@iann29/rastro 0.7.0 → 0.8.0

package/dist/component/leads.js

@@ -0,0 +1,689 @@
+import { v } from "convex/values";
+import { mutation, query, } 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";
+function invalid(field, error) {
+    fail("INVALID_ARGUMENT", error instanceof Error ? error.message : `${field} is invalid`);
+}
+function opaque(value, field) {
+    try {
+        return sanitizeOpaqueId(value, field);
+    }
+    catch (error) {
+        invalid(field, error);
+    }
+}
+function eventTime(value, now) {
+    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, max) {
+    if (value === undefined)
+        return undefined;
+    return cleanString(value, max) || undefined;
+}
+function httpUrl(value) {
+    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) {
+    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 = {
+        ...(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) {
+    if (value === undefined)
+        return undefined;
+    const entryPoint = value.trim().toLowerCase();
+    if (!ENTRY_POINT.test(entryPoint))
+        invalid("entryPoint");
+    return entryPoint;
+}
+function originKeyFor(entryPoint, ad) {
+    if (ad || entryPoint === AD_ORIGIN)
+        return AD_ORIGIN;
+    return entryPoint ?? NO_ORIGIN;
+}
+async function bumpRollup(ctx, lead, dimension, key, delta) {
+    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, lead, delta) {
+    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, siteId, leadKey) {
+    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 = {};
+            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",
+            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 = { leads: 0, qualified: 0, won: 0, revenueCents: 0 };
+        const patch = { 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, field) => {
+            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(siteIds) {
+    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, to) {
+    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 = () => ({
+    leads: 0,
+    qualified: 0,
+    won: 0,
+    revenueCents: 0,
+});
+const add = (into, row) => {
+    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, budget, siteId, dimension, first, last) {
+    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 = (key) => (left, right) => 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();
+        const totals = zero();
+        const origins = new Map();
+        const ads = new Map();
+        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,
+            });
+        }
+        const campaigns = new Map();
+        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 = {
+                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 = 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((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) {
+    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,
+            })),
+        };
+    },
+});
+//# sourceMappingURL=leads.js.map