@iann29/rastro 0.6.0 → 0.8.0

package/src/component/leads.ts

@@ -0,0 +1,823 @@
+import { v, type Infer } from "convex/values";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import {
+  mutation,
+  query,
+  type MutationCtx,
+  type QueryCtx,
+} from "./_generated/server.js";
+import {
+  DAY_MS,
+  MAX_AD_CATALOG_BATCH,
+  MAX_LEAD_EVENTS_PER_LEAD,
+  MAX_LEAD_LIST,
+  MAX_LEAD_REPORT_ADS,
+  MAX_LEAD_REPORT_ROWS,
+  MAX_REPORT_RANGE_DAYS,
+  MAX_REPORT_SITES,
+} from "./constants.js";
+import { fail } from "./errors.js";
+import { cleanString, isValidMoney, sanitizeOpaqueId } from "./sanitize.js";
+import {
+  leadAdRowValidator,
+  leadAdValidator,
+  leadAdsetRowValidator,
+  leadCampaignRowValidator,
+  leadChannelValidator,
+  leadJourneyValidator,
+  leadsReportValidator,
+  leadStageChangeValidator,
+  leadSummaryValidator,
+} from "./validators.js";
+
+/*
+ * Leads: conversations the host's server reports, with no web session behind
+ * them. A WhatsApp lead that came from a Click-to-WhatsApp ad never touched the
+ * site, so none of the tracker's tables can hold it.
+ *
+ * Counting is by cohort: every stage a lead reaches is counted on the UTC day
+ * the lead first arrived, so a campaign's row for a period reads "of the leads
+ * it brought then, how many qualified and how many bought". `qualified` counts
+ * leads that ever qualified (a sale implies it); `won` and revenue count the
+ * leads that are sold now, so undoing a sale takes it back out.
+ */
+
+const MIN_TIME = Date.UTC(2015, 0, 1);
+const ENTRY_POINT = /^[a-z0-9_]{1,48}$/;
+const SOURCE_APP = /^[a-z0-9_]{2,24}$/;
+const AD_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const MAX_LABEL = 80;
+const MAX_TITLE = 200;
+const MAX_URL = 512;
+const MAX_CLICK_ID = 512;
+const MAX_NAME = 200;
+/** Every lead from any ad falls in this origin bucket, whatever its entry point. */
+export const AD_ORIGIN = "ctwa_ad";
+/** The bucket for a lead the channel gave no entry point for. */
+export const NO_ORIGIN = "none";
+
+type LeadAd = Infer<typeof leadAdValidator>;
+type Counters = {
+  leads: number;
+  qualified: number;
+  won: number;
+  revenueCents: number;
+};
+
+function invalid(field: string, error?: unknown): never {
+  fail(
+    "INVALID_ARGUMENT",
+    error instanceof Error ? error.message : `${field} is invalid`,
+  );
+}
+
+function opaque(value: string, field: string): string {
+  try {
+    return sanitizeOpaqueId(value, field);
+  } catch (error) {
+    invalid(field, error);
+  }
+}
+
+function eventTime(value: number, now: number): number {
+  if (!Number.isSafeInteger(value) || value < MIN_TIME) {
+    fail("INVALID_ARGUMENT", "occurredAt must be a Unix time in milliseconds");
+  }
+  // A host clock ahead of ours never files a lead in the future.
+  return Math.min(value, now);
+}
+
+function optionalText(value: string | undefined, max: number) {
+  if (value === undefined) return undefined;
+  return cleanString(value, max) || undefined;
+}
+
+function httpUrl(value: string | undefined): string | undefined {
+  const text = optionalText(value, MAX_URL);
+  if (!text) return undefined;
+  try {
+    const url = new URL(text);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return undefined;
+    if (url.username || url.password) return undefined;
+    // The path names the post; the query is tracking noise.
+    return `${url.origin}${url.pathname}`.slice(0, MAX_URL);
+  } catch {
+    return undefined;
+  }
+}
+
+function sanitizeAd(ad: LeadAd | undefined): LeadAd | undefined {
+  if (!ad) return undefined;
+  const adId = ad.adId?.trim();
+  if (adId !== undefined && !AD_ID.test(adId)) invalid("ad.adId");
+  const sourceApp = ad.sourceApp?.trim().toLowerCase();
+  const clean: LeadAd = {
+    ...(adId ? { adId } : {}),
+    ...(sourceApp && SOURCE_APP.test(sourceApp) ? { sourceApp } : {}),
+    ...(httpUrl(ad.sourceUrl) ? { sourceUrl: httpUrl(ad.sourceUrl) } : {}),
+    ...(optionalText(ad.ctwaClid, MAX_CLICK_ID)
+      ? { ctwaClid: optionalText(ad.ctwaClid, MAX_CLICK_ID) }
+      : {}),
+    ...(optionalText(ad.title, MAX_TITLE)
+      ? { title: optionalText(ad.title, MAX_TITLE) }
+      : {}),
+  };
+  return Object.keys(clean).length > 0 ? clean : undefined;
+}
+
+function sanitizeEntryPoint(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const entryPoint = value.trim().toLowerCase();
+  if (!ENTRY_POINT.test(entryPoint)) invalid("entryPoint");
+  return entryPoint;
+}
+
+function originKeyFor(entryPoint: string | undefined, ad: LeadAd | undefined) {
+  if (ad || entryPoint === AD_ORIGIN) return AD_ORIGIN;
+  return entryPoint ?? NO_ORIGIN;
+}
+
+async function bumpRollup(
+  ctx: MutationCtx,
+  lead: Pick<Doc<"leads">, "siteId" | "dayStart">,
+  dimension: "origin" | "ad",
+  key: string,
+  delta: Counters,
+) {
+  if (!delta.leads && !delta.qualified && !delta.won && !delta.revenueCents) {
+    return;
+  }
+  const row = await ctx.db
+    .query("leadDailyRollups")
+    .withIndex("by_siteId_and_dimension_and_dayStart_and_key", (range) =>
+      range
+        .eq("siteId", lead.siteId)
+        .eq("dimension", dimension)
+        .eq("dayStart", lead.dayStart)
+        .eq("key", key),
+    )
+    .unique();
+  if (row) {
+    await ctx.db.patch("leadDailyRollups", row._id, {
+      leads: row.leads + delta.leads,
+      qualified: row.qualified + delta.qualified,
+      won: row.won + delta.won,
+      revenueCents: row.revenueCents + delta.revenueCents,
+    });
+  } else {
+    await ctx.db.insert("leadDailyRollups", {
+      siteId: lead.siteId,
+      dayStart: lead.dayStart,
+      dimension,
+      key,
+      ...delta,
+    });
+  }
+}
+
+/** Applies one lead's change to every rollup row it is counted in. */
+async function bumpLead(
+  ctx: MutationCtx,
+  lead: Pick<Doc<"leads">, "siteId" | "dayStart" | "originKey" | "ad">,
+  delta: Counters,
+) {
+  await bumpRollup(ctx, lead, "origin", lead.originKey, delta);
+  if (lead.ad?.adId) await bumpRollup(ctx, lead, "ad", lead.ad.adId, delta);
+}
+
+async function findLead(ctx: QueryCtx, siteId: Id<"sites">, leadKey: string) {
+  return await ctx.db
+    .query("leads")
+    .withIndex("by_siteId_and_leadKey", (range) =>
+      range.eq("siteId", siteId).eq("leadKey", leadKey),
+    )
+    .unique();
+}
+
+/**
+ * Records a lead the first time the host sees its conversation, idempotent by
+ * `leadKey`. The first touch wins: a later call never changes where the lead
+ * came from, only fills a label or the web visitor it lacked.
+ */
+export const record = mutation({
+  args: {
+    siteId: v.id("sites"),
+    leadKey: v.string(),
+    channel: leadChannelValidator,
+    entryPoint: v.optional(v.string()),
+    ad: v.optional(leadAdValidator),
+    label: v.optional(v.string()),
+    visitorId: v.optional(v.string()),
+    occurredAt: v.number(),
+  },
+  returns: v.object({ leadId: v.id("leads"), created: v.boolean() }),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+    const now = Date.now();
+    const leadKey = opaque(args.leadKey, "leadKey");
+    const label = optionalText(args.label, MAX_LABEL);
+    const visitorId =
+      args.visitorId === undefined
+        ? undefined
+        : opaque(args.visitorId, "visitorId");
+    const existing = await findLead(ctx, args.siteId, leadKey);
+    if (existing) {
+      const patch: { label?: string; visitorId?: string; updatedAt?: number } =
+        {};
+      if (label && label !== existing.label) patch.label = label;
+      if (visitorId && !existing.visitorId) patch.visitorId = visitorId;
+      if (Object.keys(patch).length > 0) {
+        await ctx.db.patch("leads", existing._id, { ...patch, updatedAt: now });
+      }
+      return { leadId: existing._id, created: false };
+    }
+    const entryPoint = sanitizeEntryPoint(args.entryPoint);
+    const ad = sanitizeAd(args.ad);
+    const firstAt = eventTime(args.occurredAt, now);
+    const lead = {
+      siteId: args.siteId,
+      leadKey,
+      channel: args.channel,
+      ...(entryPoint ? { entryPoint } : {}),
+      originKey: originKeyFor(entryPoint, ad),
+      ...(ad ? { ad } : {}),
+      ...(label ? { label } : {}),
+      ...(visitorId ? { visitorId } : {}),
+      stage: "lead" as const,
+      revenueCents: 0,
+      firstAt,
+      dayStart: Math.floor(firstAt / DAY_MS) * DAY_MS,
+      stageAt: firstAt,
+      updatedAt: now,
+    };
+    const leadId = await ctx.db.insert("leads", lead);
+    await ctx.db.insert("leadEvents", {
+      siteId: args.siteId,
+      leadId,
+      eventId: `created:${leadKey}`,
+      type: "created",
+      at: firstAt,
+    });
+    await bumpLead(ctx, lead, {
+      leads: 1,
+      qualified: 0,
+      won: 0,
+      revenueCents: 0,
+    });
+    return { leadId, created: true };
+  },
+});
+
+/**
+ * Moves a lead through the host's pipeline, idempotent by `eventId`. A lead the
+ * host never recorded (a conversation older than the integration) is not
+ * invented here: the call returns `applied: false`.
+ */
+export const setStage = mutation({
+  args: {
+    siteId: v.id("sites"),
+    leadKey: v.string(),
+    stage: leadStageChangeValidator,
+    /** The sale value, in the site's currency, for `won`. */
+    revenueCents: v.optional(v.number()),
+    eventId: v.string(),
+    occurredAt: v.number(),
+  },
+  returns: v.object({ applied: v.boolean() }),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const leadKey = opaque(args.leadKey, "leadKey");
+    const eventId = opaque(args.eventId, "eventId");
+    const at = eventTime(args.occurredAt, now);
+    const revenueCents = args.revenueCents ?? 0;
+    if (!isValidMoney(revenueCents)) {
+      fail(
+        "INVALID_ARGUMENT",
+        "revenueCents must be an integer between 0 and 1000000000",
+      );
+    }
+    if (args.stage !== "won" && args.revenueCents !== undefined) {
+      fail("INVALID_ARGUMENT", "revenueCents is only accepted with won");
+    }
+    const lead = await findLead(ctx, args.siteId, leadKey);
+    if (!lead) return { applied: false };
+    const seen = await ctx.db
+      .query("leadEvents")
+      .withIndex("by_siteId_and_eventId", (range) =>
+        range.eq("siteId", args.siteId).eq("eventId", eventId),
+      )
+      .unique();
+    if (seen) return { applied: seen.leadId === lead._id };
+
+    const delta: Counters = { leads: 0, qualified: 0, won: 0, revenueCents: 0 };
+    const patch: Partial<Doc<"leads">> = { stageAt: at, updatedAt: now };
+    const unsell = () => {
+      if (lead.stage !== "won") return;
+      delta.won -= 1;
+      delta.revenueCents -= lead.revenueCents;
+      patch.revenueCents = 0;
+    };
+    switch (args.stage) {
+      case "qualified":
+        if (lead.qualifiedAt === undefined) {
+          delta.qualified += 1;
+          patch.qualifiedAt = at;
+        }
+        // A sold lead stays sold; qualifying again only stamps the history.
+        if (lead.stage !== "won") patch.stage = "qualified";
+        break;
+      case "won":
+        if (lead.qualifiedAt === undefined) {
+          delta.qualified += 1;
+          patch.qualifiedAt = at;
+        }
+        if (lead.stage === "won") {
+          // A corrected sale value replaces the old one.
+          delta.revenueCents += revenueCents - lead.revenueCents;
+        } else {
+          delta.won += 1;
+          delta.revenueCents += revenueCents;
+        }
+        patch.stage = "won";
+        patch.revenueCents = revenueCents;
+        patch.wonAt = at;
+        break;
+      case "lost":
+        unsell();
+        patch.stage = "lost";
+        break;
+      case "open":
+        unsell();
+        patch.stage = lead.qualifiedAt !== undefined ? "qualified" : "lead";
+        break;
+    }
+    await ctx.db.patch("leads", lead._id, patch);
+    await ctx.db.insert("leadEvents", {
+      siteId: args.siteId,
+      leadId: lead._id,
+      eventId,
+      type: args.stage,
+      at,
+      ...(args.stage === "won" ? { revenueCents } : {}),
+    });
+    await bumpLead(ctx, lead, delta);
+    return { applied: true };
+  },
+});
+
+/**
+ * Forgets a lead and its history, taking it back out of every count. For the
+ * host's own deletions (a contact removed, a tenant wiped).
+ */
+export const remove = mutation({
+  args: { siteId: v.id("sites"), leadKey: v.string() },
+  returns: v.object({ removed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const lead = await findLead(
+      ctx,
+      args.siteId,
+      opaque(args.leadKey, "leadKey"),
+    );
+    if (!lead) return { removed: false };
+    const events = await ctx.db
+      .query("leadEvents")
+      .withIndex("by_leadId_and_at", (range) => range.eq("leadId", lead._id))
+      .take(MAX_LEAD_EVENTS_PER_LEAD);
+    for (const event of events) await ctx.db.delete("leadEvents", event._id);
+    await bumpLead(ctx, lead, {
+      leads: -1,
+      qualified: lead.qualifiedAt !== undefined ? -1 : 0,
+      won: lead.stage === "won" ? -1 : 0,
+      revenueCents: lead.stage === "won" ? -lead.revenueCents : 0,
+    });
+    await ctx.db.delete("leads", lead._id);
+    return { removed: true };
+  },
+});
+
+/**
+ * Names for the ads leads came from, as the host reads them from the Meta
+ * Marketing API. Upserts by ad id; a missing field keeps its stored value.
+ */
+export const upsertAdCatalog = mutation({
+  args: {
+    siteId: v.id("sites"),
+    ads: v.array(
+      v.object({
+        adId: v.string(),
+        adName: v.optional(v.string()),
+        adsetId: v.optional(v.string()),
+        adsetName: v.optional(v.string()),
+        campaignId: v.optional(v.string()),
+        campaignName: v.optional(v.string()),
+        thumbnailUrl: v.optional(v.string()),
+      }),
+    ),
+  },
+  returns: v.object({ upserted: v.number() }),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+    if (args.ads.length > MAX_AD_CATALOG_BATCH) {
+      fail("BATCH_TOO_LARGE", `at most ${MAX_AD_CATALOG_BATCH} ads per call`);
+    }
+    const now = Date.now();
+    const id = (value: string | undefined, field: string) => {
+      if (value === undefined) return undefined;
+      const trimmed = value.trim();
+      if (!AD_ID.test(trimmed)) invalid(field);
+      return trimmed;
+    };
+    for (const ad of args.ads) {
+      const fields = {
+        adName: optionalText(ad.adName, MAX_NAME),
+        adsetId: id(ad.adsetId, "adsetId"),
+        adsetName: optionalText(ad.adsetName, MAX_NAME),
+        campaignId: id(ad.campaignId, "campaignId"),
+        campaignName: optionalText(ad.campaignName, MAX_NAME),
+        thumbnailUrl: httpUrl(ad.thumbnailUrl),
+      };
+      const defined = Object.fromEntries(
+        Object.entries(fields).filter(([, value]) => value !== undefined),
+      );
+      const adId = id(ad.adId, "adId")!;
+      const row = await ctx.db
+        .query("adCatalog")
+        .withIndex("by_siteId_and_adId", (range) =>
+          range.eq("siteId", args.siteId).eq("adId", adId),
+        )
+        .unique();
+      if (row) {
+        await ctx.db.patch("adCatalog", row._id, {
+          ...defined,
+          updatedAt: now,
+        });
+      } else {
+        await ctx.db.insert("adCatalog", {
+          siteId: args.siteId,
+          adId,
+          ...defined,
+          updatedAt: now,
+        });
+      }
+    }
+    return { upserted: args.ads.length };
+  },
+});
+
+function validateSites<T>(siteIds: T[]): T[] {
+  const unique = [...new Set(siteIds)];
+  if (
+    unique.length < 1 ||
+    unique.length > MAX_REPORT_SITES ||
+    unique.length !== siteIds.length
+  ) {
+    fail(
+      "INVALID_ARGUMENT",
+      `siteIds must contain 1-${MAX_REPORT_SITES} unique IDs`,
+    );
+  }
+  return unique;
+}
+
+/** The cohort days a report covers: every UTC day that overlaps [from, to]. */
+function cohortDays(from: number, to: number) {
+  if (
+    !Number.isSafeInteger(from) ||
+    !Number.isSafeInteger(to) ||
+    from < 0 ||
+    to < from ||
+    to - from >= MAX_REPORT_RANGE_DAYS * DAY_MS
+  ) {
+    fail(
+      "INVALID_ARGUMENT",
+      `range must use inclusive integer milliseconds and span at most ${MAX_REPORT_RANGE_DAYS} UTC days`,
+    );
+  }
+  return { first: Math.floor(from / DAY_MS) * DAY_MS, last: to };
+}
+
+const zero = (): Counters => ({
+  leads: 0,
+  qualified: 0,
+  won: 0,
+  revenueCents: 0,
+});
+const add = (into: Counters, row: Counters) => {
+  into.leads += row.leads;
+  into.qualified += row.qualified;
+  into.won += row.won;
+  into.revenueCents += row.revenueCents;
+};
+
+/**
+ * One site's rollup rows for a dimension, charged against the report's single
+ * row budget (shared by every site and both dimensions, so ten sites cannot
+ * multiply it past the documents a query may read).
+ */
+async function readRollups(
+  ctx: QueryCtx,
+  budget: { rows: number },
+  siteId: Id<"sites">,
+  dimension: "origin" | "ad",
+  first: number,
+  last: number,
+) {
+  const rows = await ctx.db
+    .query("leadDailyRollups")
+    .withIndex("by_siteId_and_dimension_and_dayStart_and_key", (range) =>
+      range
+        .eq("siteId", siteId)
+        .eq("dimension", dimension)
+        .gte("dayStart", first)
+        .lte("dayStart", last),
+    )
+    .take(budget.rows + 1);
+  if (rows.length > budget.rows) {
+    fail("REPORT_INCOMPLETE", "lead report exceeds its row budget", {
+      maximumRows: MAX_LEAD_REPORT_ROWS,
+    });
+  }
+  budget.rows -= rows.length;
+  return rows;
+}
+
+const byLeadsThenKey =
+  <T extends Counters>(key: (row: T) => string) =>
+  (left: T, right: T) =>
+    right.won - left.won ||
+    right.leads - left.leads ||
+    key(left).localeCompare(key(right));
+
+/**
+ * Leads, qualified, sales and revenue over the cohort days in the range: in
+ * total, per origin and per campaign → ad set → ad.
+ */
+export const report = query({
+  args: { siteIds: v.array(v.id("sites")), from: v.number(), to: v.number() },
+  returns: leadsReportValidator,
+  handler: async (ctx, args) => {
+    const siteIds = validateSites(args.siteIds);
+    const { first, last } = cohortDays(args.from, args.to);
+    const currencies = new Set<string>();
+    const totals = zero();
+    const origins = new Map<string, Counters>();
+    const ads = new Map<string, { siteId: Id<"sites">; counters: Counters }>();
+    const budget = { rows: MAX_LEAD_REPORT_ROWS };
+    for (const siteId of siteIds) {
+      const site = await ctx.db.get("sites", siteId);
+      if (!site) fail("NOT_FOUND", "site not found");
+      currencies.add(site.currency ?? "USD");
+      for (const row of await readRollups(
+        ctx,
+        budget,
+        siteId,
+        "origin",
+        first,
+        last,
+      )) {
+        add(totals, row);
+        const counters = origins.get(row.key) ?? zero();
+        add(counters, row);
+        origins.set(row.key, counters);
+      }
+      for (const row of await readRollups(
+        ctx,
+        budget,
+        siteId,
+        "ad",
+        first,
+        last,
+      )) {
+        const entry = ads.get(row.key) ?? { siteId, counters: zero() };
+        add(entry.counters, row);
+        ads.set(row.key, entry);
+      }
+    }
+    if (ads.size > MAX_LEAD_REPORT_ADS) {
+      fail(
+        "REPORT_INCOMPLETE",
+        "lead report names more ads than it can resolve",
+        {
+          maximumAds: MAX_LEAD_REPORT_ADS,
+        },
+      );
+    }
+
+    type AdRow = Infer<typeof leadAdRowValidator>;
+    type AdsetRow = Infer<typeof leadAdsetRowValidator>;
+    type CampaignRow = Infer<typeof leadCampaignRowValidator>;
+    const campaigns = new Map<string, CampaignRow>();
+    for (const [adId, { siteId, counters }] of ads) {
+      // Every stage counts on the lead's own cohort row, so no leads means
+      // nothing left there (removed leads leave zeroed rows behind).
+      if (counters.leads === 0) continue;
+      const catalog = await ctx.db
+        .query("adCatalog")
+        .withIndex("by_siteId_and_adId", (range) =>
+          range.eq("siteId", siteId).eq("adId", adId),
+        )
+        .unique();
+      // What the latest message from this ad carried, for ads the catalog
+      // has not named yet (and for the post link either way).
+      const latest = await ctx.db
+        .query("leads")
+        .withIndex("by_siteId_and_ad_and_firstAt", (range) =>
+          range.eq("siteId", siteId).eq("ad.adId", adId),
+        )
+        .order("desc")
+        .first();
+      const ad: AdRow = {
+        adId,
+        adName: catalog?.adName ?? null,
+        sourceApp: latest?.ad?.sourceApp ?? null,
+        sourceUrl: latest?.ad?.sourceUrl ?? null,
+        title: latest?.ad?.title ?? null,
+        thumbnailUrl: catalog?.thumbnailUrl ?? null,
+        ...counters,
+      };
+      const campaignKey = catalog?.campaignId ?? "";
+      const campaign = campaigns.get(campaignKey) ?? {
+        campaignId: catalog?.campaignId ?? null,
+        campaignName: catalog?.campaignName ?? null,
+        ...zero(),
+        adsets: [],
+      };
+      add(campaign, counters);
+      const adsetId = catalog?.adsetId ?? null;
+      let adset: AdsetRow | undefined = campaign.adsets.find(
+        (row) => row.adsetId === adsetId,
+      );
+      if (!adset) {
+        adset = {
+          adsetId,
+          adsetName: catalog?.adsetName ?? null,
+          ...zero(),
+          ads: [],
+        };
+        campaign.adsets.push(adset);
+      }
+      add(adset, counters);
+      adset.ads.push(ad);
+      campaigns.set(campaignKey, campaign);
+    }
+
+    const campaignRows = [...campaigns.values()]
+      .map((campaign) => ({
+        ...campaign,
+        adsets: campaign.adsets
+          .map((adset) => ({
+            ...adset,
+            ads: adset.ads.sort(byLeadsThenKey((row) => row.adId)),
+          }))
+          .sort(byLeadsThenKey((row) => row.adsetId ?? "")),
+      }))
+      // Uncatalogued ads go last: they are the ones waiting for a name.
+      .sort((left, right) =>
+        left.campaignId === null
+          ? 1
+          : right.campaignId === null
+            ? -1
+            : byLeadsThenKey<CampaignRow>((row) => row.campaignId ?? "")(
+                left,
+                right,
+              ),
+      );
+    return {
+      from: args.from,
+      to: args.to,
+      currency: currencies.size === 1 ? [...currencies][0] : null,
+      totals,
+      origins: [...origins]
+        .map(([key, counters]) => ({ key, ...counters }))
+        .filter((row) => row.leads > 0)
+        .sort(byLeadsThenKey((row) => row.key)),
+      campaigns: campaignRows,
+    };
+  },
+});
+
+// The click id stays in the host's deployment: it is for the Conversions API,
+// not for a dashboard.
+function summarize(lead: Doc<"leads">): Infer<typeof leadSummaryValidator> {
+  return {
+    leadId: lead._id,
+    siteId: lead.siteId,
+    label: lead.label ?? null,
+    channel: lead.channel,
+    originKey: lead.originKey,
+    entryPoint: lead.entryPoint ?? null,
+    adId: lead.ad?.adId ?? null,
+    sourceApp: lead.ad?.sourceApp ?? null,
+    stage: lead.stage,
+    revenueCents: lead.revenueCents,
+    firstAt: lead.firstAt,
+    stageAt: lead.stageAt,
+    hasVisitor: lead.visitorId !== undefined,
+  };
+}
+
+/**
+ * The newest leads that arrived in the range, optionally from one ad. Pages
+ * with `before` (the last `firstAt` returned).
+ */
+export const list = query({
+  args: {
+    siteIds: v.array(v.id("sites")),
+    from: v.number(),
+    to: v.number(),
+    adId: v.optional(v.string()),
+    before: v.optional(v.number()),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(leadSummaryValidator),
+  handler: async (ctx, args) => {
+    const siteIds = validateSites(args.siteIds);
+    cohortDays(args.from, args.to);
+    const limit = Math.min(
+      Math.max(Math.floor(args.limit ?? 25), 1),
+      MAX_LEAD_LIST,
+    );
+    const upper = Math.min(
+      args.to,
+      (args.before ?? Number.MAX_SAFE_INTEGER) - 1,
+    );
+    const adId = args.adId?.trim();
+    if (adId !== undefined && !AD_ID.test(adId)) invalid("adId");
+    const pages = await Promise.all(
+      siteIds.map((siteId) =>
+        (adId
+          ? ctx.db
+              .query("leads")
+              .withIndex("by_siteId_and_ad_and_firstAt", (range) =>
+                range
+                  .eq("siteId", siteId)
+                  .eq("ad.adId", adId)
+                  .gte("firstAt", args.from)
+                  .lte("firstAt", upper),
+              )
+          : ctx.db
+              .query("leads")
+              .withIndex("by_siteId_and_firstAt", (range) =>
+                range
+                  .eq("siteId", siteId)
+                  .gte("firstAt", args.from)
+                  .lte("firstAt", upper),
+              )
+        )
+          .order("desc")
+          .take(limit),
+      ),
+    );
+    return pages
+      .flat()
+      .sort((left, right) => right.firstAt - left.firstAt)
+      .slice(0, limit)
+      .map(summarize);
+  },
+});
+
+/** One lead with its history, oldest first. */
+export const journey = query({
+  args: { siteId: v.id("sites"), leadId: v.string() },
+  returns: leadJourneyValidator,
+  handler: async (ctx, args) => {
+    const leadId = ctx.db.normalizeId("leads", args.leadId);
+    if (!leadId) return null;
+    const lead = await ctx.db.get("leads", leadId);
+    if (!lead || lead.siteId !== args.siteId) return null;
+    const catalog = lead.ad?.adId
+      ? await ctx.db
+          .query("adCatalog")
+          .withIndex("by_siteId_and_adId", (range) =>
+            range.eq("siteId", lead.siteId).eq("adId", lead.ad!.adId!),
+          )
+          .unique()
+      : null;
+    const events = await ctx.db
+      .query("leadEvents")
+      .withIndex("by_leadId_and_at", (range) => range.eq("leadId", lead._id))
+      .take(MAX_LEAD_EVENTS_PER_LEAD);
+    return {
+      lead: summarize(lead),
+      ad: lead.ad
+        ? {
+            adId: lead.ad.adId ?? null,
+            adName: catalog?.adName ?? null,
+            adsetName: catalog?.adsetName ?? null,
+            campaignName: catalog?.campaignName ?? null,
+            sourceApp: lead.ad.sourceApp ?? null,
+            sourceUrl: lead.ad.sourceUrl ?? null,
+            title: lead.ad.title ?? null,
+          }
+        : null,
+      visitorId: lead.visitorId ?? null,
+      events: events.map((event) => ({
+        type: event.type,
+        at: event.at,
+        revenueCents: event.revenueCents ?? null,
+      })),
+    };
+  },
+});