@iann29/rastro 0.9.0 → 0.10.1

package/src/component/leads.ts

@@ -9,14 +9,29 @@ import {
 import {
   DAY_MS,
   MAX_AD_CATALOG_BATCH,
+  MAX_LEAD_DAILY_DAYS,
   MAX_LEAD_EVENTS_PER_LEAD,
   MAX_LEAD_LIST,
   MAX_LEAD_REPORT_ADS,
   MAX_LEAD_REPORT_ROWS,
   MAX_REPORT_RANGE_DAYS,
   MAX_REPORT_SITES,
+  MAX_SITE_AD_ACCOUNTS,
+  MAX_AD_SPEND_ROWS,
+  MAX_SPEND_SUM_ROWS,
 } from "./constants.js";
 import { fail } from "./errors.js";
+import {
+  enterColumn,
+  forgetLeadColumns,
+  recordColumnMove,
+} from "./pipeline.js";
+import {
+  enqueueNewLead,
+  enqueuePurchase,
+  parseMetaUserData,
+  removeLeadConversions,
+} from "./metaCapi.js";
 import { cleanString, isValidMoney, sanitizeOpaqueId } from "./sanitize.js";
 import {
   leadAdRowValidator,
@@ -25,6 +40,7 @@ import {
   leadCampaignRowValidator,
   leadChannelValidator,
   leadJourneyValidator,
+  leadsDailyValidator,
   leadsReportValidator,
   leadStageChangeValidator,
   leadSummaryValidator,
@@ -208,7 +224,16 @@ export const record = mutation({
     ad: v.optional(leadAdValidator),
     label: v.optional(v.string()),
     visitorId: v.optional(v.string()),
+    /** The host's board column the lead is in (see `setPipeline`). */
+    column: v.optional(v.string()),
     occurredAt: v.number(),
+    /**
+     * The contact's hashes, for the site's Meta pixel: `{ ph, externalId? }`
+     * (see metaCapi.ts). Any shape is accepted here and checked by
+     * `parseMetaUserData`, so a bad value never fails the call nor shows up
+     * in an error.
+     */
+    meta: v.optional(v.any()),
   },
   returns: v.object({ leadId: v.id("leads"), created: v.boolean() }),
   handler: async (ctx, args) => {
@@ -216,6 +241,7 @@ export const record = mutation({
     if (!site) fail("NOT_FOUND", "site not found");
     const now = Date.now();
     const leadKey = opaque(args.leadKey, "leadKey");
+    const meta = parseMetaUserData(args.meta) ?? undefined;
     const label = optionalText(args.label, MAX_LABEL);
     const visitorId =
       args.visitorId === undefined
@@ -223,10 +249,18 @@ export const record = mutation({
         : opaque(args.visitorId, "visitorId");
     const existing = await findLead(ctx, args.siteId, leadKey);
     if (existing) {
-      const patch: { label?: string; visitorId?: string; updatedAt?: number } =
-        {};
+      const patch: Partial<Doc<"leads">> = {};
       if (label && label !== existing.label) patch.label = label;
       if (visitorId && !existing.visitorId) patch.visitorId = visitorId;
+      // The column is where the lead is now, so a later call may move it.
+      const moved = await enterColumn(
+        ctx,
+        existing,
+        args.column,
+        eventTime(args.occurredAt, now),
+        meta,
+      );
+      if (moved) Object.assign(patch, moved);
       if (Object.keys(patch).length > 0) {
         await ctx.db.patch("leads", existing._id, { ...patch, updatedAt: now });
       }
@@ -252,6 +286,14 @@ export const record = mutation({
       updatedAt: now,
     };
     const leadId = await ctx.db.insert("leads", lead);
+    const placed = await enterColumn(
+      ctx,
+      { _id: leadId, siteId: args.siteId, column: undefined },
+      args.column,
+      firstAt,
+      meta,
+    );
+    if (placed) await ctx.db.patch("leads", leadId, placed);
     await ctx.db.insert("leadEvents", {
       siteId: args.siteId,
       leadId,
@@ -265,6 +307,12 @@ export const record = mutation({
       won: 0,
       revenueCents: 0,
     });
+    await enqueueNewLead(ctx, {
+      siteId: args.siteId,
+      leadId,
+      eventTime: firstAt,
+      meta,
+    });
     return { leadId, created: true };
   },
 });
@@ -272,23 +320,35 @@ export const record = mutation({
 /**
  * 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`.
+ * invented here: the call returns `applied: false`. `column` is the host's
+ * board column the lead is now in; a call may carry the column alone, when the
+ * lead moves on the board without changing stage.
  */
 export const setStage = mutation({
   args: {
     siteId: v.id("sites"),
     leadKey: v.string(),
-    stage: leadStageChangeValidator,
+    stage: v.optional(leadStageChangeValidator),
+    /** The host's board column the lead is now in (see `setPipeline`). */
+    column: v.optional(v.string()),
     /** The sale value, in the site's currency, for `won`. */
     revenueCents: v.optional(v.number()),
     eventId: v.string(),
     occurredAt: v.number(),
+    /**
+     * The contact's hashes, for the site's Meta pixel: `{ ph, externalId? }`
+     * (see metaCapi.ts). Any shape is accepted here and checked by
+     * `parseMetaUserData`, so a bad value never fails the call nor shows up
+     * in an error.
+     */
+    meta: v.optional(v.any()),
   },
   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 meta = parseMetaUserData(args.meta) ?? undefined;
     const at = eventTime(args.occurredAt, now);
     const revenueCents = args.revenueCents ?? 0;
     if (!isValidMoney(revenueCents)) {
@@ -300,6 +360,9 @@ export const setStage = mutation({
     if (args.stage !== "won" && args.revenueCents !== undefined) {
       fail("INVALID_ARGUMENT", "revenueCents is only accepted with won");
     }
+    if (args.stage === undefined && args.column === undefined) {
+      fail("INVALID_ARGUMENT", "pass a stage, a column, or both");
+    }
     const lead = await findLead(ctx, args.siteId, leadKey);
     if (!lead) return { applied: false };
     const seen = await ctx.db
@@ -309,6 +372,25 @@ export const setStage = mutation({
       )
       .unique();
     if (seen) return { applied: seen.leadId === lead._id };
+    if (args.stage === undefined) {
+      // A board move alone, idempotent by its own eventId. A move older than
+      // the lead's last one is recorded (so a retry stays a no-op) but never
+      // moves the lead back.
+      const column = args.column ?? "";
+      const move = await recordColumnMove(ctx, {
+        siteId: args.siteId,
+        leadId: lead._id,
+        eventId,
+        column,
+        at,
+      });
+      if (!move.fresh) return { applied: move.leadId === lead._id };
+      const moved = await enterColumn(ctx, lead, column, at, meta);
+      if (moved) {
+        await ctx.db.patch("leads", lead._id, { ...moved, updatedAt: now });
+      }
+      return { applied: true };
+    }
 
     const delta: Counters = { leads: 0, qualified: 0, won: 0, revenueCents: 0 };
     const patch: Partial<Doc<"leads">> = { stageAt: at, updatedAt: now };
@@ -352,7 +434,8 @@ export const setStage = mutation({
         patch.stage = lead.qualifiedAt !== undefined ? "qualified" : "lead";
         break;
     }
-    await ctx.db.patch("leads", lead._id, patch);
+    const moved = await enterColumn(ctx, lead, args.column, at, meta);
+    await ctx.db.patch("leads", lead._id, { ...patch, ...moved });
     await ctx.db.insert("leadEvents", {
       siteId: args.siteId,
       leadId: lead._id,
@@ -362,6 +445,18 @@ export const setStage = mutation({
       ...(args.stage === "won" ? { revenueCents } : {}),
     });
     await bumpLead(ctx, lead, delta);
+    // Purchase only ever comes from a recorded sale, never from a column.
+    if (args.stage === "won" && meta) {
+      const site = await ctx.db.get("sites", args.siteId);
+      await enqueuePurchase(ctx, {
+        siteId: args.siteId,
+        leadId: lead._id,
+        eventTime: at,
+        valueCents: revenueCents,
+        currency: site?.currency ?? "USD",
+        meta,
+      });
+    }
     return { applied: true };
   },
 });
@@ -385,12 +480,14 @@ export const remove = mutation({
       .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 removeLeadConversions(ctx, lead);
     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 forgetLeadColumns(ctx, lead);
     await ctx.db.delete("leads", lead._id);
     return { removed: true };
   },
@@ -498,6 +595,128 @@ function cohortDays(from: number, to: number) {
   return { first: Math.floor(from / DAY_MS) * DAY_MS, last: to };
 }
 
+type Spend = { spendCents: number; impressions: number; clicks: number };
+type NullableSpend = { [K in keyof Spend]: number | null };
+// Unknown spend (no synced ad account covers the row), never zero.
+const NO_SPEND: NullableSpend = {
+  spendCents: null,
+  impressions: null,
+  clicks: null,
+};
+const zeroSpend = (): Spend => ({ spendCents: 0, impressions: 0, clicks: 0 });
+/** Only the three spend figures of a row, whatever else it carries. */
+const spendOf = (row: Spend): Spend => ({
+  spendCents: row.spendCents,
+  impressions: row.impressions,
+  clicks: row.clicks,
+});
+const addSpend = (into: Spend, row: Spend) => {
+  into.spendCents += row.spendCents;
+  into.impressions += row.impressions;
+  into.clicks += row.clicks;
+};
+/** Sums two nullable spends: unknown only when both are. */
+function plusSpend(left: NullableSpend, right: NullableSpend): NullableSpend {
+  if (left.spendCents === null) return { ...NO_SPEND, ...pickSpend(right) };
+  if (right.spendCents === null) return pickSpend(left);
+  return {
+    spendCents: left.spendCents + right.spendCents,
+    impressions: (left.impressions ?? 0) + (right.impressions ?? 0),
+    clicks: (left.clicks ?? 0) + (right.clicks ?? 0),
+  };
+}
+const pickSpend = (row: NullableSpend): NullableSpend => ({
+  spendCents: row.spendCents,
+  impressions: row.impressions,
+  clicks: row.clicks,
+});
+
+/**
+ * What a site's Meta spend can be read from: its linked ad accounts that have
+ * finished a sync. An account still backfilling reports nothing yet, so its
+ * spend reads as unknown ("syncing"), never as zero.
+ */
+async function spendSources(ctx: QueryCtx, siteId: Id<"sites">) {
+  const links = await ctx.db
+    .query("siteAdAccounts")
+    .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+    .take(MAX_SITE_AD_ACCOUNTS);
+  const synced = links.filter((link) => link.lastSyncAt !== undefined);
+  return {
+    accounts: new Set(synced.map((link) => link.adAccountId)),
+    currencies: new Set(synced.map((link) => link.currency)),
+  };
+}
+
+/**
+ * A site's spend per account and day in the range, from the site-day sums.
+ * Its budget is its own, so Meta rows never cost the lead report its leads;
+ * past it the answer is `null` (the caller reports spend as incomplete).
+ */
+async function readSiteSpend(
+  ctx: QueryCtx,
+  budget: { rows: number },
+  siteId: Id<"sites">,
+  first: number,
+  lastDay: number,
+) {
+  const rows = await ctx.db
+    .query("siteSpendDaily")
+    .withIndex("by_siteId_and_dayStart", (range) =>
+      range
+        .eq("siteId", siteId)
+        .gte("dayStart", first)
+        .lte("dayStart", lastDay),
+    )
+    .take(budget.rows + 1);
+  if (rows.length > budget.rows) {
+    budget.rows = 0;
+    return null;
+  }
+  budget.rows -= rows.length;
+  return rows;
+}
+
+/**
+ * A site's spend per ad and day in the range (or one ad's), for the campaign
+ * tree. A budget of its own: past it the answer is `null` and the tree's
+ * spend is unknown, while the leads and the site totals stay exact.
+ */
+async function readAdSpend(
+  ctx: QueryCtx,
+  budget: { rows: number },
+  siteId: Id<"sites">,
+  first: number,
+  lastDay: number,
+  adId?: string,
+) {
+  const query = adId
+    ? ctx.db
+        .query("adSpendDaily")
+        .withIndex("by_siteId_and_adId_and_dayStart", (range) =>
+          range
+            .eq("siteId", siteId)
+            .eq("adId", adId)
+            .gte("dayStart", first)
+            .lte("dayStart", lastDay),
+        )
+    : ctx.db
+        .query("adSpendDaily")
+        .withIndex("by_siteId_and_dayStart", (range) =>
+          range
+            .eq("siteId", siteId)
+            .gte("dayStart", first)
+            .lte("dayStart", lastDay),
+        );
+  const rows = await query.take(budget.rows + 1);
+  if (rows.length > budget.rows) {
+    budget.rows = 0;
+    return null;
+  }
+  budget.rows -= rows.length;
+  return rows;
+}
+
 const zero = (): Counters => ({
   leads: 0,
   qualified: 0,
@@ -560,15 +779,52 @@ export const report = query({
   handler: async (ctx, args) => {
     const siteIds = validateSites(args.siteIds);
     const { first, last } = cohortDays(args.from, args.to);
+    const lastDay = Math.floor(last / DAY_MS) * DAY_MS;
     const currencies = new Set<string>();
     const totals = zero();
     const origins = new Map<string, Counters>();
-    const ads = new Map<string, { siteId: Id<"sites">; counters: Counters }>();
+    type AdEntry = {
+      siteId: Id<"sites">;
+      counters: Counters;
+      spend: Spend | null;
+      accounts: Set<string>;
+    };
+    const ads = new Map<string, AdEntry>();
+    type SiteEntry = {
+      siteId: Id<"sites">;
+      counters: Counters;
+      paid: Counters;
+      spend: NullableSpend;
+      spendCurrency: string | null;
+      currencyMismatch: boolean;
+    };
+    const bySite: SiteEntry[] = [];
     const budget = { rows: MAX_LEAD_REPORT_ROWS };
+    const sumBudget = { rows: MAX_SPEND_SUM_ROWS };
+    const adBudget = { rows: MAX_AD_SPEND_ROWS };
+    // Every currency the synced accounts of the requested sites bill in.
+    const spendCurrencies = new Set<string>();
+    let spendIncomplete = false;
+    let treeSpendKnown = true;
+    const adEntry = (
+      adId: string,
+      siteId: Id<"sites">,
+      accounts: Set<string>,
+    ): AdEntry => {
+      let entry = ads.get(adId);
+      if (!entry) {
+        entry = { siteId, counters: zero(), spend: null, accounts };
+        ads.set(adId, entry);
+      }
+      return entry;
+    };
     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");
+      const siteCurrency = site.currency ?? "USD";
+      currencies.add(siteCurrency);
+      const siteCounters = zero();
+      const paidCounters = zero();
       for (const row of await readRollups(
         ctx,
         budget,
@@ -578,10 +834,13 @@ export const report = query({
         last,
       )) {
         add(totals, row);
+        add(siteCounters, row);
+        if (row.key === AD_ORIGIN) add(paidCounters, row);
         const counters = origins.get(row.key) ?? zero();
         add(counters, row);
         origins.set(row.key, counters);
       }
+      const sources = await spendSources(ctx, siteId);
       for (const row of await readRollups(
         ctx,
         budget,
@@ -590,11 +849,67 @@ export const report = query({
         first,
         last,
       )) {
-        const entry = ads.get(row.key) ?? { siteId, counters: zero() };
-        add(entry.counters, row);
-        ads.set(row.key, entry);
+        add(adEntry(row.key, siteId, sources.accounts).counters, row);
+      }
+      for (const currency of sources.currencies) spendCurrencies.add(currency);
+
+      // The site's spend, from the site-day sums of its synced accounts.
+      let spend: NullableSpend = NO_SPEND;
+      if (sources.accounts.size > 0) {
+        const sums = await readSiteSpend(
+          ctx,
+          sumBudget,
+          siteId,
+          first,
+          lastDay,
+        );
+        if (sums === null) {
+          spendIncomplete = true;
+        } else {
+          const total = zeroSpend();
+          for (const row of sums) {
+            if (sources.accounts.has(row.adAccountId)) addSpend(total, row);
+          }
+          spend = total;
+        }
+      }
+      const mixed = sources.currencies.size > 1;
+      const spendCurrency =
+        sources.currencies.size === 1 ? [...sources.currencies][0]! : null;
+      bySite.push({
+        siteId,
+        counters: siteCounters,
+        paid: paidCounters,
+        // Two currencies cannot be summed: the site's spend is unknown.
+        spend: mixed ? NO_SPEND : spend,
+        spendCurrency,
+        currencyMismatch:
+          mixed || (spendCurrency !== null && spendCurrency !== siteCurrency),
+      });
+
+      // The campaign tree's spend, per ad, on a budget of its own.
+      if (sources.accounts.size > 0 && treeSpendKnown) {
+        const rows = await readAdSpend(ctx, adBudget, siteId, first, lastDay);
+        if (rows === null) {
+          spendIncomplete = true;
+          treeSpendKnown = false;
+        } else {
+          for (const row of rows) {
+            if (!sources.accounts.has(row.adAccountId)) continue;
+            const entry = adEntry(row.adId, siteId, sources.accounts);
+            entry.spend ??= zeroSpend();
+            addSpend(entry.spend, spendOf(row));
+          }
+        }
       }
     }
+    // Spend adds up only in one currency.
+    const oneCurrency = spendCurrencies.size <= 1;
+    if (!oneCurrency) treeSpendKnown = false;
+    let totalSpend: NullableSpend = NO_SPEND;
+    if (oneCurrency) {
+      for (const site of bySite) totalSpend = plusSpend(totalSpend, site.spend);
+    }
     if (ads.size > MAX_LEAD_REPORT_ADS) {
       fail(
         "REPORT_INCOMPLETE",
@@ -609,10 +924,28 @@ export const report = query({
     type AdsetRow = Infer<typeof leadAdsetRowValidator>;
     type CampaignRow = Infer<typeof leadCampaignRowValidator>;
     const campaigns = new Map<string, CampaignRow>();
-    for (const [adId, { siteId, counters }] of ads) {
+    const sum = (
+      row: { [K in keyof Spend]?: number | null },
+      spend: NullableSpend,
+    ) => {
+      const next = plusSpend(
+        {
+          spendCents: row.spendCents ?? null,
+          impressions: row.impressions ?? null,
+          clicks: row.clicks ?? null,
+        },
+        spend,
+      );
+      row.spendCents = next.spendCents;
+      row.impressions = next.impressions;
+      row.clicks = next.clicks;
+    };
+    for (const [adId, entry] of ads) {
+      const { siteId, counters } = entry;
       // 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;
+      // nothing left there (removed leads leave zeroed rows behind), unless
+      // the ad spent: an ad burning budget without leads is the point.
+      if (counters.leads === 0 && entry.spend === null) continue;
       const catalog = await ctx.db
         .query("adCatalog")
         .withIndex("by_siteId_and_adId", (range) =>
@@ -628,23 +961,41 @@ export const report = query({
         )
         .order("desc")
         .first();
+      // An ad of a synced account that spent nothing in the range spent 0;
+      // one no synced account covers has unknown spend.
+      const spend: NullableSpend = !treeSpendKnown
+        ? NO_SPEND
+        : entry.spend
+          ? spendOf(entry.spend)
+          : catalog?.adAccountId && entry.accounts.has(catalog.adAccountId)
+            ? zeroSpend()
+            : NO_SPEND;
+      const thumbnailUrl = catalog?.thumbnailStorageId
+        ? await ctx.storage.getUrl(catalog.thumbnailStorageId)
+        : null;
       const ad: AdRow = {
         adId,
+        siteId,
         adName: catalog?.adName ?? null,
         sourceApp: latest?.ad?.sourceApp ?? null,
         sourceUrl: latest?.ad?.sourceUrl ?? null,
         title: latest?.ad?.title ?? null,
-        thumbnailUrl: catalog?.thumbnailUrl ?? null,
+        thumbnailUrl: thumbnailUrl ?? catalog?.thumbnailUrl ?? null,
+        creativeType: catalog?.creativeType ?? null,
+        adStatus: catalog?.adStatus ?? null,
         ...counters,
+        ...spend,
       };
       const campaignKey = catalog?.campaignId ?? "";
       const campaign = campaigns.get(campaignKey) ?? {
         campaignId: catalog?.campaignId ?? null,
         campaignName: catalog?.campaignName ?? null,
         ...zero(),
+        ...NO_SPEND,
         adsets: [],
       };
       add(campaign, counters);
+      sum(campaign, spend);
       const adsetId = catalog?.adsetId ?? null;
       let adset: AdsetRow | undefined = campaign.adsets.find(
         (row) => row.adsetId === adsetId,
@@ -654,11 +1005,13 @@ export const report = query({
           adsetId,
           adsetName: catalog?.adsetName ?? null,
           ...zero(),
+          ...NO_SPEND,
           ads: [],
         };
         campaign.adsets.push(adset);
       }
       add(adset, counters);
+      sum(adset, spend);
       adset.ads.push(ad);
       campaigns.set(campaignKey, campaign);
     }
@@ -684,20 +1037,167 @@ export const report = query({
                 right,
               ),
       );
+    // Spend buys the ad origin only; the organic ones stay unknown.
+    if (!origins.has(AD_ORIGIN) && (totalSpend.spendCents ?? 0) > 0) {
+      origins.set(AD_ORIGIN, zero());
+    }
     return {
       from: args.from,
       to: args.to,
       currency: currencies.size === 1 ? [...currencies][0] : null,
-      totals,
+      totals: { ...totals, ...totalSpend },
       origins: [...origins]
-        .map(([key, counters]) => ({ key, ...counters }))
-        .filter((row) => row.leads > 0)
+        .map(([key, counters]) => ({
+          key,
+          ...counters,
+          ...(key === AD_ORIGIN ? totalSpend : NO_SPEND),
+        }))
+        .filter(
+          (row) =>
+            row.leads > 0 || (row.spendCents !== null && row.spendCents > 0),
+        )
         .sort(byLeadsThenKey((row) => row.key)),
       campaigns: campaignRows,
+      bySite: bySite.map((site) => ({
+        siteId: site.siteId,
+        ...site.counters,
+        paid: site.paid,
+        spendCents: site.spend.spendCents,
+        spendCurrency: site.spendCurrency,
+        currencyMismatch: site.currencyMismatch,
+      })),
+      spendCurrency:
+        oneCurrency && totalSpend.spendCents !== null
+          ? ([...spendCurrencies][0] ?? null)
+          : null,
+      currencyMismatch:
+        !oneCurrency || bySite.some((site) => site.currencyMismatch),
+      spendIncomplete,
     };
   },
 });
 
+/**
+ * The lead funnel per cohort day, for sparklines and the sales × spend chart:
+ * every UTC day in the range, empty days included. With `adId`, only that
+ * ad's leads; with `origin`, only that origin's (`ctwa_ad` for the leads the
+ * ads bought). Spend is the day's Meta spend for the same scope, null where
+ * no synced ad account covers it, for an organic origin, or when the sites'
+ * accounts bill in more than one currency.
+ */
+export const daily = query({
+  args: {
+    siteIds: v.array(v.id("sites")),
+    from: v.number(),
+    to: v.number(),
+    adId: v.optional(v.string()),
+    origin: v.optional(v.string()),
+  },
+  returns: leadsDailyValidator,
+  handler: async (ctx, args) => {
+    const siteIds = validateSites(args.siteIds);
+    const { first, last } = cohortDays(args.from, args.to);
+    const lastDay = Math.floor(last / DAY_MS) * DAY_MS;
+    if ((lastDay - first) / DAY_MS + 1 > MAX_LEAD_DAILY_DAYS) {
+      fail(
+        "INVALID_ARGUMENT",
+        `a daily series spans at most ${MAX_LEAD_DAILY_DAYS} UTC days`,
+      );
+    }
+    if (args.adId !== undefined && args.origin !== undefined) {
+      fail("INVALID_ARGUMENT", "pass adId or origin, not both");
+    }
+    if (args.origin !== undefined && !ENTRY_POINT.test(args.origin)) {
+      invalid("origin");
+    }
+    const adId =
+      args.adId === undefined ? undefined : opaque(args.adId, "adId");
+    const key = adId ?? args.origin;
+    const days = new Map<number, Counters>();
+    for (let day = first; day <= lastDay; day += DAY_MS) days.set(day, zero());
+    const budget = { rows: MAX_LEAD_REPORT_ROWS };
+    const spendBudget = { rows: MAX_SPEND_SUM_ROWS };
+    const spend = new Map<number, number>();
+    const spendCurrencies = new Set<string>();
+    let spendKnown = false;
+    let spendBroken = false;
+    for (const siteId of siteIds) {
+      const site = await ctx.db.get("sites", siteId);
+      if (!site) fail("NOT_FOUND", "site not found");
+      for (const row of await readRollups(
+        ctx,
+        budget,
+        siteId,
+        adId === undefined ? "origin" : "ad",
+        first,
+        last,
+      )) {
+        if (key !== undefined && row.key !== key) continue;
+        const counters = days.get(row.dayStart);
+        if (counters) add(counters, row);
+      }
+      // Spend buys the ad leads: an organic origin has none to show.
+      if (args.origin !== undefined && args.origin !== AD_ORIGIN) continue;
+      const sources = await spendSources(ctx, siteId);
+      if (sources.accounts.size === 0) continue;
+      let rows: Array<{
+        dayStart: number;
+        spendCents: number;
+        adAccountId: string;
+      }> | null;
+      if (adId === undefined) {
+        rows = await readSiteSpend(ctx, spendBudget, siteId, first, lastDay);
+      } else {
+        rows = await readAdSpend(
+          ctx,
+          spendBudget,
+          siteId,
+          first,
+          lastDay,
+          adId,
+        );
+        const own = rows?.some((row) => sources.accounts.has(row.adAccountId));
+        if (!own) {
+          // One ad: its spend is known only if a synced account of this
+          // site runs it.
+          const catalog = await ctx.db
+            .query("adCatalog")
+            .withIndex("by_siteId_and_adId", (range) =>
+              range.eq("siteId", siteId).eq("adId", adId),
+            )
+            .unique();
+          if (
+            !catalog?.adAccountId ||
+            !sources.accounts.has(catalog.adAccountId)
+          ) {
+            continue;
+          }
+        }
+      }
+      if (rows === null) {
+        spendBroken = true;
+        continue;
+      }
+      spendKnown = true;
+      for (const currency of sources.currencies) spendCurrencies.add(currency);
+      for (const row of rows) {
+        if (!sources.accounts.has(row.adAccountId)) continue;
+        spend.set(
+          row.dayStart,
+          (spend.get(row.dayStart) ?? 0) + row.spendCents,
+        );
+      }
+    }
+    // Two currencies do not add up; a series past its budget is not whole.
+    const showSpend = spendKnown && !spendBroken && spendCurrencies.size <= 1;
+    return [...days].map(([dayStart, counters]) => ({
+      dayStart,
+      ...counters,
+      spendCents: showSpend ? (spend.get(dayStart) ?? 0) : null,
+    }));
+  },
+});
+
 // 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> {