@iann29/rastro 0.10.8 → 0.11.0

package/src/component/leadAdsValidators.ts

@@ -0,0 +1,365 @@
+import { v, type Infer } from "convex/values";
+
+/*
+ * Lead Ads: Pages, instant forms, their rules and the leads they bring
+ * (metaLeads.ts, since 0.11.0). A lead's personal data (name, phone, e-mail,
+ * any answer typed freely) never reaches a table: it goes from Meta to the
+ * host's handler in memory. Only the answers to choice questions are kept.
+ */
+
+const countersFields = {
+  leads: v.number(),
+  qualified: v.number(),
+  won: v.number(),
+  revenueCents: v.number(),
+};
+
+/** One option of a choice question, as Meta lists it. */
+export const metaFormOptionValidator = v.object({
+  key: v.string(),
+  value: v.string(),
+});
+
+/** One question of an instant form. `options` only on choice questions. */
+export const metaFormQuestionValidator = v.object({
+  key: v.string(),
+  label: v.string(),
+  /** Meta's type: `FULL_NAME`, `EMAIL`, `PHONE`, `CUSTOM`… */
+  type: v.string(),
+  options: v.optional(v.array(metaFormOptionValidator)),
+});
+
+/** Where a rule sends a lead: a board column, or the discard with a reason. */
+export const formRuleTargetValidator = v.union(
+  v.object({ column: v.string() }),
+  v.object({ discard: v.string() }),
+);
+
+/** One rule: an answer to a choice question decides where the lead goes. */
+export const formRuleValidator = v.object({
+  questionKey: v.string(),
+  /** Option keys (or values) of the question; any of them matches. */
+  answers: v.array(v.string()),
+  to: formRuleTargetValidator,
+});
+
+/** The brakes on an automatic first message (the host's own sender). */
+export const firstContactBrakesValidator = v.object({
+  waitMinutes: v.number(),
+  maxPerHour: v.number(),
+  businessHoursOnly: v.boolean(),
+});
+
+/**
+ * How the host makes the first contact. `lead_starts`: the form's end screen
+ * has the WhatsApp button and the lead writes first (recommended);
+ * `one_click`: a person sends the suggested `text`; `automatic`: a scheduled
+ * send under `brakes`, which the host keeps off unless the business accepted
+ * the risk.
+ */
+export const firstContactValidator = v.object({
+  mode: v.union(
+    v.literal("lead_starts"),
+    v.literal("one_click"),
+    v.literal("automatic"),
+  ),
+  text: v.optional(v.string()),
+  brakes: v.optional(firstContactBrakesValidator),
+});
+
+/**
+ * What the rules decided for a lead: a column (`null` is the host's own
+ * entry, when no rule matched and the form names no entry column), or the
+ * discard with its reason.
+ */
+export const formLeadDecisionValidator = v.union(
+  v.object({ column: v.union(v.string(), v.null()) }),
+  v.object({ discard: v.string() }),
+);
+
+/** A choice answer as stored: the question and the option keys picked. */
+export const formChoiceAnswerValidator = v.object({
+  questionKey: v.string(),
+  answers: v.array(v.string()),
+});
+
+/** Where a form lead came from: the Page, the form and the ad. */
+export const formLeadOriginValidator = v.object({
+  pageId: v.string(),
+  pageName: v.union(v.string(), v.null()),
+  formId: v.string(),
+  formName: v.union(v.string(), v.null()),
+  adId: v.union(v.string(), v.null()),
+  adName: v.union(v.string(), v.null()),
+  adsetId: v.union(v.string(), v.null()),
+  adsetName: v.union(v.string(), v.null()),
+  campaignId: v.union(v.string(), v.null()),
+  campaignName: v.union(v.string(), v.null()),
+  /** `fb` or `ig`, as Meta says where the form was filled. */
+  platform: v.union(v.string(), v.null()),
+  isOrganic: v.boolean(),
+});
+
+/** A choice answer with the labels the form shows. */
+export const formLabeledAnswerValidator = v.object({
+  questionKey: v.string(),
+  label: v.string(),
+  values: v.array(v.string()),
+});
+
+/**
+ * What the component hands the host's form lead handler (an internal
+ * mutation registered with `setFormLeadHandler`). `contact` and
+ * `freeAnswers` come from Meta in memory and are never stored by Rastro; the
+ * host owns the person from here. The handler must be idempotent on
+ * `leadgenId`.
+ */
+export const formLeadPayloadValidator = v.object({
+  siteId: v.string(),
+  /** Rastro's lead; `leadKey` is what `setLeadStage` takes for it. */
+  leadId: v.string(),
+  leadKey: v.string(),
+  leadgenId: v.string(),
+  /** When the lead submitted the form (Meta's `created_time`). */
+  receivedAt: v.number(),
+  contact: v.object({
+    name: v.union(v.string(), v.null()),
+    /** As the lead typed it, usually with the country code (`+55…`). */
+    phone: v.union(v.string(), v.null()),
+    email: v.union(v.string(), v.null()),
+  }),
+  /** Answers typed freely (and any personal field besides the contact). */
+  freeAnswers: v.array(
+    v.object({ questionKey: v.string(), label: v.string(), value: v.string() }),
+  ),
+  /** The choice answers, with the labels the form shows. */
+  answers: v.array(formLabeledAnswerValidator),
+  decision: formLeadDecisionValidator,
+  /** The rule indexes evaluated, in order; the last one decided if any did. */
+  rulePath: v.array(v.number()),
+  /** The rule that decided, or null when none matched. */
+  ruleIndex: v.union(v.number(), v.null()),
+  origin: formLeadOriginValidator,
+  firstContact: firstContactValidator,
+});
+
+/**
+ * What stops or slows a linked Page, as a code a screen maps to its own text
+ * (decision D6). Only `META_TOKEN_INVALID` and `META_PERMISSION_MISSING` are
+ * fixed by reconnecting Meta (the second also covers a Page the login no
+ * longer lists). `HANDLER_MISSING`, `HANDLER_FAILED` and `HANDLER_GAVE_UP`
+ * are the host's (no form lead handler; it throws and the lead is read again;
+ * it threw too often and the lead was skipped for good); `SECRETS_KEY_MISSING`
+ * is the host's env.
+ * `META_TRUNCATED`, `META_RATE_LIMITED`, `META_UNAVAILABLE` and `RUN_TIMEOUT`
+ * pass by themselves: the next run goes on.
+ */
+export const META_PAGE_ERROR_CODES = [
+  "META_TOKEN_INVALID",
+  "META_PERMISSION_MISSING",
+  "HANDLER_MISSING",
+  "HANDLER_FAILED",
+  "HANDLER_GAVE_UP",
+  "SECRETS_KEY_MISSING",
+  "META_TRUNCATED",
+  "META_RATE_LIMITED",
+  "META_UNAVAILABLE",
+  "RUN_TIMEOUT",
+] as const;
+export type MetaPageErrorCode = (typeof META_PAGE_ERROR_CODES)[number];
+
+export const metaPageErrorCodeValidator = v.union(
+  v.literal("META_TOKEN_INVALID"),
+  v.literal("META_PERMISSION_MISSING"),
+  v.literal("HANDLER_MISSING"),
+  v.literal("HANDLER_FAILED"),
+  v.literal("HANDLER_GAVE_UP"),
+  v.literal("SECRETS_KEY_MISSING"),
+  v.literal("META_TRUNCATED"),
+  v.literal("META_RATE_LIMITED"),
+  v.literal("META_UNAVAILABLE"),
+  v.literal("RUN_TIMEOUT"),
+);
+
+/** What `metaLinkedPages` answers the control plane (decision D1). */
+export const linkedPagesValidator = v.object({
+  pages: v.array(v.object({ pageId: v.string(), siteId: v.string() })),
+  /**
+   * The component has `RASTRO_FEDERATION_AUDIENCE`: its leadgen route can
+   * verify a forward. False, every forward would answer `503`.
+   */
+  leadgenReady: v.boolean(),
+  /** The issuer the leadgen route verifies forwards against. */
+  issuer: v.string(),
+  /**
+   * The audience the leadgen route expects (`RASTRO_FEDERATION_AUDIENCE`,
+   * without a trailing slash), or null when it has none.
+   */
+  audience: v.union(v.string(), v.null()),
+  /**
+   * The host registered its form lead handler (the Lead Ads opt-in). False,
+   * the component reads no Pages: the list stays empty until it does, and
+   * reconnecting Meta changes nothing.
+   */
+  handlerReady: v.boolean(),
+});
+
+/** A Page an owner's Meta connection lists, as a screen shows it. */
+export const metaPageValidator = v.object({
+  pageId: v.string(),
+  name: v.string(),
+  tasks: v.array(v.string()),
+  /** Meta granted `leads_retrieval` for the Page to this login. */
+  leadsAllowed: v.boolean(),
+  /** The site the Page feeds, whoever linked it; null when free. */
+  linkedSiteId: v.union(v.string(), v.null()),
+  /** Federated reads only: linked to a site outside the caller's grant. */
+  linkedOutsideScope: v.optional(v.boolean()),
+  /** Whether this owner linked it; null while the Page is free. */
+  own: v.union(v.boolean(), v.null()),
+  subscribedAt: v.union(v.number(), v.null()),
+  /**
+   * What stops or slows the Page, as a code (`META_PAGE_ERROR_CODES`): Meta
+   * refused its token or lead access, or, for a Page this owner linked, the
+   * host's handler or the last reconciliation. Null when nothing does.
+   */
+  lastError: v.union(metaPageErrorCodeValidator, v.null()),
+  /** Whether the host registered its form lead handler (no lead comes in without it). */
+  handlerReady: v.boolean(),
+});
+
+const formRulesSummaryValidator = v.object({
+  configured: v.boolean(),
+  count: v.number(),
+  entryColumn: v.union(v.string(), v.null()),
+  /** With an owner: whether that owner may edit them (not another's). */
+  own: v.optional(v.boolean()),
+});
+
+/** One instant form of a Page linked to the site, for the forms screen. */
+export const metaFormRowValidator = v.object({
+  formId: v.string(),
+  name: v.string(),
+  /** Meta's status: `ACTIVE`, `ARCHIVED`, `DELETED`, `DRAFT`. */
+  status: v.string(),
+  questions: v.array(metaFormQuestionValidator),
+  /** The end screen's WhatsApp button; null when Meta does not say. */
+  whatsappButton: v.union(v.boolean(), v.null()),
+  /** The host marked the button as set by hand ("Já liguei"). */
+  whatsappButtonConfirmed: v.boolean(),
+  createdTime: v.union(v.number(), v.null()),
+  syncedAt: v.number(),
+  /** Leads in the 30 UTC days up to `now`; null without `now`. */
+  leads30d: v.union(v.number(), v.null()),
+  /** Those leads per UTC day, oldest first (30 entries); null without `now`. */
+  daily: v.union(v.array(v.number()), v.null()),
+  lastLeadAt: v.union(v.number(), v.null()),
+  rules: formRulesSummaryValidator,
+});
+
+/** The Pages linked to a site, each with its forms. */
+export const metaFormsValidator = v.array(
+  v.object({
+    pageId: v.string(),
+    pageName: v.string(),
+    leadsAllowed: v.boolean(),
+    subscribedAt: v.union(v.number(), v.null()),
+    lastReconcileAt: v.union(v.number(), v.null()),
+    lastLeadAt: v.union(v.number(), v.null()),
+    /** As on `metaPages`: a code of `META_PAGE_ERROR_CODES`, or null. */
+    lastError: v.union(metaPageErrorCodeValidator, v.null()),
+    /** With an owner: whether that owner linked the Page. */
+    own: v.optional(v.boolean()),
+    /** Whether the host registered its form lead handler. */
+    handlerReady: v.boolean(),
+    forms: v.array(metaFormRowValidator),
+  }),
+);
+
+/** A form's rules as the drawer edits them, each with its monthly count. */
+export const formRulesValidator = v.object({
+  siteId: v.string(),
+  formId: v.string(),
+  configured: v.boolean(),
+  entryColumn: v.union(v.string(), v.null()),
+  rules: v.array(
+    v.object({
+      ...formRuleValidator.fields,
+      /** Leads this rule decided in the 30 days up to `now`; null without. */
+      monthCount: v.union(v.number(), v.null()),
+    }),
+  ),
+  firstContact: firstContactValidator,
+  whatsappButtonConfirmed: v.boolean(),
+  updatedAt: v.union(v.number(), v.null()),
+  /** With an owner: whether that owner may edit them (not another's). */
+  own: v.optional(v.boolean()),
+});
+
+/** The last 30 days' leads of a form under a draft of its rules. */
+export const formRulesSimulationValidator = v.object({
+  total: v.number(),
+  /**
+   * Leads no rule matched: they go to the entry. Unlike `formsReport`'s
+   * `entry`, this counts them whether or not the draft names an entry column.
+   */
+  entry: v.number(),
+  /** Per draft rule, in order: the leads it would decide. */
+  rules: v.array(v.number()),
+  /**
+   * Leads per column the draft sends them to. With an `entryColumn`, its row
+   * already holds the `entry` leads: add `entry` only when no row names it.
+   */
+  columns: v.array(v.object({ column: v.string(), leads: v.number() })),
+  discarded: v.array(v.object({ reason: v.string(), leads: v.number() })),
+  /** A read cap was hit: the figures cover the newest leads only. */
+  partial: v.boolean(),
+});
+
+/**
+ * Per form: its leads in the range and where the rules sent them. One row per
+ * (siteId, formId): a Page moved from one site to another inside the range
+ * has a row for each, so key rows by both. The range is whole UTC days:
+ * `from` floors to its day and `to` takes in the UTC day it falls on.
+ */
+export const formsReportValidator = v.object({
+  forms: v.array(
+    v.object({
+      siteId: v.string(),
+      pageId: v.string(),
+      formId: v.string(),
+      name: v.union(v.string(), v.null()),
+      ...countersFields,
+      /** Leads a rule (or the entry column) sent to each column. */
+      columns: v.array(v.object({ column: v.string(), leads: v.number() })),
+      /** Leads that went to the host's own entry (no column named). */
+      entry: v.number(),
+      discarded: v.array(v.object({ reason: v.string(), leads: v.number() })),
+      /** Discarded leads someone sent back to the funnel. */
+      returned: v.number(),
+    }),
+  ),
+  /** A read cap was hit: the decision counts are a lower bound. */
+  partial: v.boolean(),
+});
+
+/** A form lead as the journey shows it: answers, origin and the path. */
+export const formLeadDetailValidator = v.object({
+  leadgenId: v.string(),
+  receivedAt: v.number(),
+  origin: formLeadOriginValidator,
+  answers: v.array(formLabeledAnswerValidator),
+  decision: formLeadDecisionValidator,
+  rulePath: v.array(v.number()),
+  ruleIndex: v.union(v.number(), v.null()),
+  /** When a discarded lead was sent back, and the reason it had. */
+  returned: v.union(v.object({ at: v.number(), reason: v.string() }), v.null()),
+});
+
+export type FormRule = Infer<typeof formRuleValidator>;
+export type FormRuleTarget = Infer<typeof formRuleTargetValidator>;
+export type FirstContact = Infer<typeof firstContactValidator>;
+export type FormLeadDecision = Infer<typeof formLeadDecisionValidator>;
+export type FormLeadPayload = Infer<typeof formLeadPayloadValidator>;
+export type MetaFormQuestion = Infer<typeof metaFormQuestionValidator>;
+export type FormChoiceAnswer = Infer<typeof formChoiceAnswerValidator>;

package/src/component/leadFormRules.ts

@@ -0,0 +1,202 @@
+import type {
+  FormChoiceAnswer,
+  FormLeadDecision,
+  FormRule,
+  MetaFormQuestion,
+} from "./leadAdsValidators.js";
+
+/*
+ * The pure half of Lead Ads: how a Meta lead's `field_data` splits into the
+ * contact (kept in memory only), free answers (in memory only) and choice
+ * answers (the only answers Rastro stores), and how a form's rules decide
+ * where the lead goes. No database, no clock: the ingestion, the drawer's
+ * simulation and the tests share it.
+ */
+
+/** One `field_data` entry as Meta returns it: the question key, the values. */
+export interface LeadField {
+  name: string;
+  values: string[];
+}
+
+export interface SplitLead {
+  contact: { name: string | null; phone: string | null; email: string | null };
+  freeAnswers: Array<{ questionKey: string; label: string; value: string }>;
+  choices: FormChoiceAnswer[];
+}
+
+const MAX_VALUE = 500;
+const NAME_FIELDS = new Set(["full_name"]);
+const FIRST_NAME_FIELDS = new Set(["first_name"]);
+const LAST_NAME_FIELDS = new Set(["last_name"]);
+const PHONE_FIELDS = new Set(["phone_number", "phone"]);
+const EMAIL_FIELDS = new Set(["email"]);
+
+const normalize = (value: string) =>
+  value.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ");
+
+const clip = (value: string) => value.trim().slice(0, MAX_VALUE);
+
+/** The question's options, when it is a choice question. */
+export function choiceOptions(
+  question: MetaFormQuestion | undefined,
+): Array<{ key: string; value: string }> | null {
+  return question?.options && question.options.length > 0
+    ? question.options
+    : null;
+}
+
+/**
+ * The option an answer names, by its key or its shown value (Meta returns
+ * either, depending on the form), or null when it names none.
+ */
+export function optionKeyOf(
+  question: MetaFormQuestion | undefined,
+  answer: string,
+): string | null {
+  const options = choiceOptions(question);
+  if (!options) return null;
+  const wanted = normalize(answer);
+  const found =
+    options.find((option) => normalize(option.key) === wanted) ??
+    options.find((option) => normalize(option.value) === wanted);
+  return found?.key ?? null;
+}
+
+/**
+ * Splits a lead's answers. The identity fields become `contact`; an answer
+ * to a choice question that names its options becomes a choice; anything
+ * else, including any field the form does not describe, is a free answer.
+ * Only `choices` may ever be stored.
+ */
+export function splitLeadFields(
+  questions: readonly MetaFormQuestion[],
+  fields: readonly LeadField[],
+): SplitLead {
+  const byKey = new Map(questions.map((question) => [question.key, question]));
+  let fullName: string | null = null;
+  let firstName: string | null = null;
+  let lastName: string | null = null;
+  let phone: string | null = null;
+  let email: string | null = null;
+  const freeAnswers: SplitLead["freeAnswers"] = [];
+  const choices: FormChoiceAnswer[] = [];
+  for (const field of fields) {
+    const values = field.values.map(clip).filter(Boolean);
+    if (values.length === 0) continue;
+    const key = field.name;
+    const question = byKey.get(key);
+    const type = question?.type.toUpperCase() ?? "";
+    if (NAME_FIELDS.has(key) || type === "FULL_NAME") {
+      fullName ??= values.join(" ");
+      continue;
+    }
+    if (FIRST_NAME_FIELDS.has(key) || type === "FIRST_NAME") {
+      firstName ??= values.join(" ");
+      continue;
+    }
+    if (LAST_NAME_FIELDS.has(key) || type === "LAST_NAME") {
+      lastName ??= values.join(" ");
+      continue;
+    }
+    if (PHONE_FIELDS.has(key) || type === "PHONE") {
+      phone ??= values[0]!;
+      continue;
+    }
+    if (EMAIL_FIELDS.has(key) || type === "EMAIL") {
+      email ??= values[0]!;
+      continue;
+    }
+    if (choiceOptions(question)) {
+      const keys = values.map((value) => optionKeyOf(question, value));
+      // Every value must name an option: a stray value may be something
+      // the lead typed, so the whole answer stays in memory.
+      if (keys.every((option): option is string => option !== null)) {
+        choices.push({ questionKey: key, answers: [...new Set(keys)] });
+        continue;
+      }
+    }
+    freeAnswers.push({
+      questionKey: key,
+      label: question?.label ?? key,
+      value: values.join(", "),
+    });
+  }
+  const name =
+    fullName ?? ([firstName, lastName].filter(Boolean).join(" ") || null);
+  return { contact: { name, phone, email }, freeAnswers, choices };
+}
+
+export interface RuleOutcome {
+  decision: FormLeadDecision;
+  rulePath: number[];
+  ruleIndex: number | null;
+}
+
+/**
+ * The first rule whose question the lead answered with one of its answers
+ * decides; with none, the lead goes to `entryColumn` (null: the host's own
+ * entry). `rulePath` lists every rule looked at, in order.
+ */
+export function evaluateRules(
+  rules: readonly FormRule[],
+  entryColumn: string | null,
+  choices: readonly FormChoiceAnswer[],
+): RuleOutcome {
+  const answered = new Map(
+    choices.map((choice) => [choice.questionKey, new Set(choice.answers)]),
+  );
+  const rulePath: number[] = [];
+  for (const [index, rule] of rules.entries()) {
+    rulePath.push(index);
+    const picked = answered.get(rule.questionKey);
+    if (!picked || !rule.answers.some((answer) => picked.has(answer))) {
+      continue;
+    }
+    return {
+      decision:
+        "column" in rule.to
+          ? { column: rule.to.column }
+          : { discard: rule.to.discard },
+      rulePath,
+      ruleIndex: index,
+    };
+  }
+  return { decision: { column: entryColumn }, rulePath, ruleIndex: null };
+}
+
+/**
+ * A rule's identity for its monthly count: the question, the answers and the
+ * target. Reordering keeps a rule's count; changing it starts a new one, as
+ * an edited rule only decides the leads after it.
+ */
+export function ruleSignature(rule: FormRule): string {
+  const target =
+    "column" in rule.to
+      ? `column:${rule.to.column}`
+      : `discard:${rule.to.discard}`;
+  return JSON.stringify([
+    rule.questionKey,
+    [...new Set(rule.answers)].sort(),
+    target,
+  ]);
+}
+
+/** The choice answers with the labels the form shows, for the host. */
+export function labelChoices(
+  questions: readonly MetaFormQuestion[],
+  choices: readonly FormChoiceAnswer[],
+): Array<{ questionKey: string; label: string; values: string[] }> {
+  const byKey = new Map(questions.map((question) => [question.key, question]));
+  return choices.map((choice) => {
+    const question = byKey.get(choice.questionKey);
+    const options = choiceOptions(question) ?? [];
+    return {
+      questionKey: choice.questionKey,
+      label: question?.label ?? choice.questionKey,
+      values: choice.answers.map(
+        (key) => options.find((option) => option.key === key)?.value ?? key,
+      ),
+    };
+  });
+}

package/src/component/leadFormStore.ts

@@ -0,0 +1,129 @@
+import type { Infer } from "convex/values";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import type { MutationCtx, QueryCtx } from "./_generated/server.js";
+import type {
+  formLeadDetailValidator,
+  formLeadOriginValidator,
+} from "./leadAdsValidators.js";
+import { labelChoices } from "./leadFormRules.js";
+
+/*
+ * Reads and clean-up of a form lead's record (`formLeads`), shared by the
+ * lead journey (leads.ts) and the Lead Ads module (metaLeads.ts).
+ */
+
+/** Where a form lead came from, with the names Rastro knows. */
+export async function formLeadOrigin(
+  ctx: QueryCtx,
+  row: Pick<
+    Doc<"formLeads">,
+    | "siteId"
+    | "pageId"
+    | "formId"
+    | "adId"
+    | "adsetId"
+    | "campaignId"
+    | "platform"
+    | "isOrganic"
+  >,
+): Promise<Infer<typeof formLeadOriginValidator>> {
+  const link = await ctx.db
+    .query("sitePages")
+    .withIndex("by_pageId", (range) => range.eq("pageId", row.pageId))
+    .first();
+  const page =
+    link ??
+    (await ctx.db
+      .query("metaPages")
+      .withIndex("by_pageId", (range) => range.eq("pageId", row.pageId))
+      .first());
+  const form = await ctx.db
+    .query("metaForms")
+    .withIndex("by_formId", (range) => range.eq("formId", row.formId))
+    .first();
+  const catalog = row.adId
+    ? await ctx.db
+        .query("adCatalog")
+        .withIndex("by_siteId_and_adId", (range) =>
+          range.eq("siteId", row.siteId).eq("adId", row.adId!),
+        )
+        .unique()
+    : null;
+  return {
+    pageId: row.pageId,
+    pageName: page?.name ?? null,
+    formId: row.formId,
+    formName: form?.name ?? null,
+    adId: row.adId ?? null,
+    adName: catalog?.adName ?? null,
+    adsetId: row.adsetId ?? catalog?.adsetId ?? null,
+    adsetName: catalog?.adsetName ?? null,
+    campaignId: row.campaignId ?? catalog?.campaignId ?? null,
+    campaignName: catalog?.campaignName ?? null,
+    platform: row.platform ?? null,
+    isOrganic: row.isOrganic,
+  };
+}
+
+/** A form lead's answers, origin and path, for the lead journey. */
+export async function formLeadDetail(
+  ctx: QueryCtx,
+  lead: Pick<Doc<"leads">, "_id">,
+): Promise<Infer<typeof formLeadDetailValidator> | null> {
+  const row = await ctx.db
+    .query("formLeads")
+    .withIndex("by_leadId", (range) => range.eq("leadId", lead._id))
+    .first();
+  if (!row) return null;
+  const form = await ctx.db
+    .query("metaForms")
+    .withIndex("by_formId", (range) => range.eq("formId", row.formId))
+    .first();
+  return {
+    leadgenId: row.leadgenId,
+    receivedAt: row.receivedAt,
+    origin: await formLeadOrigin(ctx, row),
+    answers: labelChoices(form?.questions ?? [], row.answers),
+    decision: row.decision,
+    rulePath: row.rulePath,
+    ruleIndex: row.ruleIndex ?? null,
+    returned: row.returned ?? null,
+  };
+}
+
+/**
+ * Deletes a removed lead's ingestion record and leaves its leadgen id behind
+ * (nothing else), so the same Meta lead is never ingested again.
+ */
+export async function forgetFormLead(
+  ctx: MutationCtx,
+  leadId: Id<"leads">,
+): Promise<void> {
+  const rows = await ctx.db
+    .query("formLeads")
+    .withIndex("by_leadId", (range) => range.eq("leadId", leadId))
+    .take(10);
+  const now = Date.now();
+  for (const row of rows) {
+    await ctx.db.delete("formLeads", row._id);
+    if (!(await isForgottenFormLead(ctx, row.leadgenId))) {
+      await ctx.db.insert("formLeadTombstones", {
+        leadgenId: row.leadgenId,
+        removedAt: now,
+      });
+    }
+  }
+}
+
+/** Whether the host removed the lead Meta knows by this leadgen id. */
+export async function isForgottenFormLead(
+  ctx: QueryCtx,
+  leadgenId: string,
+): Promise<boolean> {
+  return (
+    (await ctx.db
+      .query("formLeadTombstones")
+      .withIndex("by_leadgenId", (range) => range.eq("leadgenId", leadgenId))
+      .first()) !== null
+  );
+}