Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

10.8 KB
Raw Blame
// `bun run send` — send real requests to a worktree's API with the seeded clients:
// one event, an identify, or a whole generated journey replayed through `/track`
// (ingest → Kafka → worker → ClickHouse), unlike `bun run seed`, which inserts
// directly. For testing ingest, live views and anything that reacts to new events.
//
//   bun run send track <event> [--project acme-shop] [--path /pricing] [--profile usr_x] [--prop k=v]... [--revenue 99]
//   bun run send identify <profileId> [--project] [--email] [--first-name] [--last-name] [--prop k=v]...
//   bun run send journey [--project acme-shop] [--sessions 1] [--realtime] [--seed 7]
//   options: --url <api> (default $API_URL), --client <id> --secret <secret> (default: the project's seeded client)

import { existsSync, readFileSync } from 'node:fs';
import { resolve } from 'node:path';
import { setTimeout as sleep } from 'node:timers/promises';
import { parseArgs } from 'node:util';
import { ARCHETYPES, archetypeById } from './archetypes';
import {
  type Archetype,
  Journey,
  type JourneyEvent,
} from './archetypes/archetype';
import { CAMPAIGNS } from './data/referrers';
import { projectIdFor } from './ids';
import type { Person, Visitor } from './model';
import { Rng } from './rng';
import { MANIFEST_FILE } from './seed.constants';
import { World } from './world';

const USAGE = `Usage: bun run send <track|identify|journey> [options]

  track <event>          send one event    --path /x  --profile usr_x  --prop k=v  --revenue 99
  identify <profileId>   send an identify  --email a@b  --first-name A  --last-name B  --prop k=v
  journey                generate a session with the project's archetype and replay it live
                         --sessions N (default 1)  --realtime (real dwell times; default caps gaps at 1s)  --seed N

  --project <id>         which seeded project (default: acme-web)
  --url <api>            default $API_URL
  --client <id> --secret <secret>   override the project's seeded write client
`;

/** Gaps between replayed events are capped so a journey takes seconds, not minutes. */
const MAX_GAP_MS = 1000;
const MANIFEST_PATH = resolve(import.meta.dir, '..', '..', '..', MANIFEST_FILE);
const DEFAULT_PROJECT = 'acme-web';

interface Manifest {
  projects: {
    id: string;
    archetype: string;
    clientId: string;
    clientSecret: string;
  }[];
}

interface Target {
  url: string;
  clientId: string;
  clientSecret: string;
  projectId: string;
  archetype: Archetype;
}

function readManifest(): Manifest | null {
  if (!existsSync(MANIFEST_PATH)) {
    return null;
  }
  return JSON.parse(readFileSync(MANIFEST_PATH, 'utf8')) as Manifest;
}

function parseProps(values: string[] | undefined): Record<string, unknown> {
  const properties: Record<string, unknown> = {};
  for (const entry of values ?? []) {
    const index = entry.indexOf('=');
    if (index <= 0) {
      throw new Error(`--prop expects key=value, got "${entry}"`);
    }
    const raw = entry.slice(index + 1);
    const asNumber = Number(raw);
    properties[entry.slice(0, index)] =
      raw === 'true'
        ? true
        : raw === 'false'
          ? false
          : raw !== '' && !Number.isNaN(asNumber)
            ? asNumber
            : raw;
  }
  return properties;
}

function resolveTarget(values: {
  url?: string;
  project?: string;
  client?: string;
  secret?: string;
}): Target {
  const url = (values.url ?? process.env.API_URL ?? '').replace(/\/$/, '');
  if (!url) {
    throw new Error('No API: pass --url or set API_URL.');
  }
  const projectId = values.project ?? DEFAULT_PROJECT;
  const archetype =
    ARCHETYPES.find((candidate) => projectIdFor(candidate) === projectId) ??
    archetypeById(projectId);
  const manifest = readManifest();
  const seeded = manifest?.projects.find((project) => project.id === projectId);
  const clientId = values.client ?? seeded?.clientId;
  const clientSecret = values.secret ?? seeded?.clientSecret;
  if (!(clientId && clientSecret)) {
    throw new Error(
      `No client for ${projectId}: run \`bun run seed\` first or pass --client and --secret.`
    );
  }
  return { url, clientId, clientSecret, projectId, archetype };
}

interface Sender {
  userAgent: string;
  ip: string;
}

async function post(
  target: Target,
  sender: Sender,
  body: unknown
): Promise<string> {
  const response = await fetch(`${target.url}/track`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'openpanel-client-id': target.clientId,
      'openpanel-client-secret': target.clientSecret,
      'openpanel-sdk-name': target.archetype.sdk.name,
      'openpanel-sdk-version': target.archetype.sdk.version,
      'user-agent': sender.userAgent,
      'x-client-ip': sender.ip,
    },
    body: JSON.stringify(body),
  });
  const text = await response.text();
  return `${response.status} ${text}`;
}

function trackBody(
  name: string,
  properties: Record<string, unknown>,
  profileId?: string
) {
  return {
    type: 'track',
    payload: { name, properties, ...(profileId ? { profileId } : {}) },
  };
}

function identifyBody(person: Person) {
  // Empty strings fail validation (`avatar` must be a URL); send only what is set.
  const optional = Object.fromEntries(
    Object.entries({
      firstName: person.firstName,
      lastName: person.lastName,
      email: person.email,
      avatar: person.avatar,
    }).filter(([, value]) => value !== '')
  );
  return {
    type: 'identify',
    payload: {
      profileId: person.id,
      ...optional,
      properties: person.properties,
    },
  };
}

/** The SDK's view of a journey event: `__path` as the full URL (or screen name), `__title`, custom properties. */
function sdkProperties(
  target: Target,
  event: JourneyEvent,
  landingQuery: string
): Record<string, unknown> {
  const path =
    target.archetype.deviceClass === 'native'
      ? event.path
      : `${target.archetype.origin}${event.path}${landingQuery}`;
  return {
    ...event.properties,
    __path: path,
    __title: event.title || undefined,
    ...(event.revenue !== undefined ? { __revenue: event.revenue } : {}),
  };
}

async function replay(
  target: Target,
  visitor: Visitor,
  events: readonly JourneyEvent[],
  utm: Record<string, string>,
  realtime: boolean
): Promise<void> {
  const sender = { userAgent: visitor.userAgent, ip: visitor.geo.ip };
  let identified: Person | null = visitor.identified ? visitor.person : null;
  let previous: Date | null = null;
  for (const [index, event] of events.entries()) {
    if (previous) {
      const gap = event.at.getTime() - previous.getTime();
      await sleep(realtime ? gap : Math.min(gap, MAX_GAP_MS));
    }
    previous = event.at;
    if (event.person && event.person !== identified) {
      identified = event.person;
      console.log(
        `identify ${event.person.id} → ${await post(target, sender, identifyBody(event.person))}`
      );
    }
    const landingQuery =
      index === 0 && Object.keys(utm).length
        ? `?${new URLSearchParams(utm)}`
        : '';
    const body = trackBody(
      event.name,
      sdkProperties(target, event, landingQuery),
      identified?.id
    );
    console.log(
      `${event.name.padEnd(28)} ${event.path.padEnd(28)} → ${await post(target, sender, body)}`
    );
  }
}

async function main(): Promise<void> {
  const { values, positionals } = parseArgs({
    args: process.argv.slice(2),
    allowPositionals: true,
    options: {
      project: { type: 'string' },
      url: { type: 'string' },
      client: { type: 'string' },
      secret: { type: 'string' },
      path: { type: 'string' },
      profile: { type: 'string' },
      prop: { type: 'string', multiple: true },
      revenue: { type: 'string' },
      email: { type: 'string' },
      'first-name': { type: 'string' },
      'last-name': { type: 'string' },
      sessions: { type: 'string' },
      realtime: { type: 'boolean', default: false },
      seed: { type: 'string' },
      help: { type: 'boolean', default: false },
    },
  });
  const [command, argument] = positionals;
  if (values.help || !command) {
    process.stdout.write(USAGE);
    return;
  }
  const target = resolveTarget(values);
  const rng = new Rng(`send/${values.seed ?? Date.now()}`);
  const world = new World(
    target.archetype,
    target.projectId,
    new Date(),
    () => undefined
  );
  const visitor = world.pick(rng, new Date());
  const sender = { userAgent: visitor.userAgent, ip: visitor.geo.ip };
  console.log(
    `→ ${target.url}  project ${target.projectId}  client ${target.clientId}`
  );

  if (command === 'track') {
    if (!argument) {
      throw new Error('track needs an event name');
    }
    const path = values.path ?? '/';
    const properties = {
      ...parseProps(values.prop),
      __path:
        target.archetype.deviceClass === 'native'
          ? path
          : `${target.archetype.origin}${path}`,
      ...(values.revenue ? { __revenue: Number(values.revenue) } : {}),
    };
    console.log(
      await post(
        target,
        sender,
        trackBody(argument, properties, values.profile)
      )
    );
    return;
  }
  if (command === 'identify') {
    if (!argument) {
      throw new Error('identify needs a profile id');
    }
    const person: Person = {
      id: argument,
      firstName: values['first-name'] ?? '',
      lastName: values['last-name'] ?? '',
      email: values.email ?? '',
      avatar: '',
      properties: Object.fromEntries(
        Object.entries(parseProps(values.prop)).map(([key, value]) => [
          key,
          String(value),
        ])
      ),
    };
    console.log(await post(target, sender, identifyBody(person)));
    return;
  }
  if (command === 'journey') {
    const sessions = Number(values.sessions ?? 1);
    for (let i = 0; i < sessions; i++) {
      const current = i === 0 ? visitor : world.pick(rng, new Date());
      const campaign = rng.chance(target.archetype.campaignChance)
        ? rng.pick(CAMPAIGNS)
        : null;
      const utm: Record<string, string> = campaign
        ? {
            utm_source: campaign.source,
            utm_medium: campaign.medium,
            utm_campaign: campaign.name,
          }
        : {};
      const journey = new Journey(
        rng,
        new Date(),
        target.archetype.dwellMedianSeconds,
        current.identified ? current.person : null
      );
      target.archetype.journey(rng, journey, current);
      console.log(
        `\nsession ${i + 1}: ${journey.events.length} events, ${current.person ? `person ${current.person.id}` : 'anonymous'}`
      );
      await replay(target, current, journey.events, utm, values.realtime);
      world.touch(current, new Date(), {
        identified: journey.identified !== null,
        anonymousEvents: journey.events.some((event) => event.person === null),
      });
    }
    return;
  }
  throw new Error(`Unknown command "${command}".\n${USAGE}`);
}

await main();