@iann29/rastro 0.9.0 → 0.10.1

package/src/component/meta.ts

@@ -0,0 +1,1525 @@
+import { v, type Infer } from "convex/values";
+import { internal } from "./_generated/api.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
+import {
+  action,
+  env,
+  internalMutation,
+  internalQuery,
+  mutation,
+  query,
+  type ActionCtx,
+  type MutationCtx,
+  type QueryCtx,
+} from "./_generated/server.js";
+import {
+  MAX_LEAD_LIST,
+  MAX_REPORT_SITES,
+  MAX_SITE_AD_ACCOUNTS,
+} from "./constants.js";
+import { fail } from "./errors.js";
+import { conversionCounts, listConversions } from "./metaCapi.js";
+import {
+  metaGraph,
+  MetaGraphError,
+  type GraphAdAccount,
+  type MetaApp,
+  type MetaGraph,
+} from "./metaGraph.js";
+import {
+  backfillProgress,
+  kickSyncLoop,
+  MAX_LINKS_PER_CONNECTION,
+  PAUSED_AT,
+} from "./metaSync.js";
+import { sanitizeOpaqueId } from "./sanitize.js";
+import { decryptSecret, encryptSecret, hasSecretsKey } from "./secrets.js";
+import {
+  metaAdAccountValidator,
+  metaAuthorizerValidator,
+  metaConnectionValidator,
+  metaConnectResultValidator,
+  metaConversionValidator,
+  metaPixelSourceValidator,
+  metaPixelValidator,
+  metaStatusValidator,
+  metaUnlinkPreviewValidator,
+} from "./validators.js";
+
+/**
+ * Meta for a site: the connection (a host owner's token and its ad accounts),
+ * which of those accounts feed the site's spend, the site's pixel, and the
+ * read side (`status`, `conversions`). The contract is in `docs/meta-ads.md`;
+ * the sync itself is in metaSync.ts. Tokens are sealed with
+ * RASTRO_SECRETS_KEY before any write and only actions open them; no query
+ * returns one.
+ */
+
+type MetaAdAccount = Infer<typeof metaAdAccountValidator>;
+type MetaPixel = Infer<typeof metaPixelValidator>;
+type MetaAuthorizer = Infer<typeof metaAuthorizerValidator>;
+
+const MAX_TOKEN = 1_024;
+const MIN_TOKEN = 20;
+const MAX_TEST_EVENT_CODE = 64;
+const PIXEL_ID = /^\d{5,20}$/;
+const AD_ACCOUNT_ID = /^act_\d{1,24}$/;
+const UNLINK_BATCH = 50;
+const MAX_CODE = 1_024;
+const MAX_REDIRECT_URI = 512;
+// Pixels are listed per ad account, a call each: past this many accounts the
+// listing stops (an agency picks a pixel among its clients', not thousands).
+const MAX_PIXEL_ACCOUNTS = 100;
+const PIXEL_CONCURRENCY = 5;
+const MAX_PIXELS = 500;
+const MAX_PREVIEW_DAYS = 1_000;
+const MAX_PREVIEW_CATALOG = 4_000;
+const TOKEN_EXCHANGE_FAILED =
+  "TOKEN_EXCHANGE_FAILED: Meta did not trade the short-lived token for a long-lived one; connect again before it expires";
+/** How long before a token dies the screens ask for a new login. */
+const EXPIRY_WARNING_MS = 7 * 86_400_000;
+
+/** An owner key as stored: the host's opaque id, checked. */
+export function ownerKeyOf(value: string): string {
+  try {
+    return sanitizeOpaqueId(value, "ownerKey");
+  } catch (error) {
+    fail(
+      "INVALID_ARGUMENT",
+      error instanceof Error ? error.message : "ownerKey is invalid",
+    );
+  }
+}
+
+function tokenOf(value: string): string {
+  const token = value.trim();
+  if (
+    token.length < MIN_TOKEN ||
+    token.length > MAX_TOKEN ||
+    /\s/.test(token)
+  ) {
+    fail("INVALID_ARGUMENT", "accessToken is not a Meta access token");
+  }
+  return token;
+}
+
+function adAccountIdOf(value: string): string {
+  const trimmed = value.trim();
+  const id = /^\d+$/.test(trimmed) ? `act_${trimmed}` : trimmed;
+  if (!AD_ACCOUNT_ID.test(id)) {
+    fail("INVALID_ARGUMENT", "adAccountId must look like act_1234567890");
+  }
+  return id;
+}
+
+function requireKey() {
+  if (!hasSecretsKey(env.RASTRO_SECRETS_KEY)) {
+    fail(
+      "SECRETS_KEY_MISSING",
+      "set RASTRO_SECRETS_KEY (32 random bytes, base64) and pass it to the component",
+    );
+  }
+}
+
+const graph = () => metaGraph({ fake: env.RASTRO_META_FAKE === "true" });
+
+/**
+ * The Meta app Facebook Login for Business runs on. The fake needs none: any
+ * code logs in there, so a demo works without a real app.
+ */
+function loginApp(): MetaApp {
+  const appId = env.RASTRO_META_APP_ID?.trim() ?? "";
+  const appSecret = env.RASTRO_META_APP_SECRET?.trim() ?? "";
+  if (env.RASTRO_META_FAKE === "true") return { appId, appSecret };
+  if (!/^\d{5,20}$/.test(appId) || !appSecret) {
+    fail(
+      "META_LOGIN_UNAVAILABLE",
+      "set RASTRO_META_APP_ID and RASTRO_META_APP_SECRET and pass them to the component; a pasted token still connects",
+    );
+  }
+  return { appId, appSecret };
+}
+
+function codeOf(value: string): string {
+  const code = value.trim();
+  if (code.length < 1 || code.length > MAX_CODE || /\s/.test(code)) {
+    fail("INVALID_ARGUMENT", "code is not a Meta authorization code");
+  }
+  return code;
+}
+
+/** The redirect the code was issued for: https, or http on this machine. */
+function redirectUriOf(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value.trim());
+  } catch {
+    fail("INVALID_ARGUMENT", "redirectUri must be an absolute URL");
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (
+    value.length > MAX_REDIRECT_URI ||
+    url.username ||
+    url.password ||
+    url.hash ||
+    !(url.protocol === "https:" || (url.protocol === "http:" && local))
+  ) {
+    fail(
+      "INVALID_ARGUMENT",
+      "redirectUri must be the https page Meta sent the code to",
+    );
+  }
+  return url.toString();
+}
+
+/**
+ * The pixels the token's accounts own, deduplicated. An account the token
+ * cannot read pixels for is skipped (a token with only `ads_read` sees none);
+ * a refused token fails the whole listing. `complete` is false when Meta
+ * throttled or failed on an account: the caller then keeps the pixels it had.
+ */
+async function listPixels(
+  client: MetaGraph,
+  token: string,
+  adAccounts: MetaAdAccount[],
+): Promise<{ pixels: MetaPixel[]; complete: boolean }> {
+  const accounts = adAccounts.slice(0, MAX_PIXEL_ACCOUNTS);
+  const pixels = new Map<string, MetaPixel>();
+  let complete = true;
+  for (let start = 0; start < accounts.length; start += PIXEL_CONCURRENCY) {
+    const batch = accounts.slice(start, start + PIXEL_CONCURRENCY);
+    const results = await Promise.all(
+      batch.map(async (account) => {
+        try {
+          return await client.adPixels(token, account.adAccountId);
+        } catch (error) {
+          if (error instanceof MetaGraphError && error.kind === "token") {
+            throw error;
+          }
+          if (
+            !(error instanceof MetaGraphError) ||
+            error.kind !== "permission"
+          ) {
+            complete = false;
+          }
+          return [];
+        }
+      }),
+    );
+    for (const pixel of results.flat()) {
+      if (!PIXEL_ID.test(pixel.pixelId) || pixels.has(pixel.pixelId)) continue;
+      pixels.set(pixel.pixelId, {
+        pixelId: pixel.pixelId,
+        name: pixel.name.slice(0, 200),
+      });
+    }
+  }
+  return { pixels: [...pixels.values()].slice(0, MAX_PIXELS), complete };
+}
+
+/** Meta's failure as the component's own error code. */
+function metaFailure(error: unknown): never {
+  if (error instanceof MetaGraphError) {
+    if (error.kind === "token") {
+      fail("META_TOKEN_INVALID", `Meta refused the token: ${error.message}`);
+    }
+    if (error.kind === "app") {
+      fail(
+        "META_LOGIN_UNAVAILABLE",
+        "Meta refused RASTRO_META_APP_ID / RASTRO_META_APP_SECRET; check the host's env",
+      );
+    }
+    fail("META_UNAVAILABLE", `Meta answered: ${error.message}`, {
+      kind: error.kind,
+    });
+  }
+  throw error;
+}
+
+const toAccount = (account: GraphAdAccount): MetaAdAccount => ({
+  adAccountId: account.adAccountId,
+  name: account.name.slice(0, 200),
+  currency: account.currency.slice(0, 8),
+  timezone: account.timezone.slice(0, 64),
+});
+
+// ---------------------------------------------------------------------------
+// Connection.
+
+export const saveConnection = internalMutation({
+  args: {
+    ownerKey: v.string(),
+    tokenCipher: v.string(),
+    tokenIv: v.string(),
+    businessName: v.union(v.string(), v.null()),
+    adAccounts: v.array(metaAdAccountValidator),
+    pixels: v.array(metaPixelValidator),
+    /** False when Meta failed part of the pixel listing: keep the old ones. */
+    pixelsComplete: v.boolean(),
+    /** Facebook Login only; a pasted token clears it. */
+    authorizedBy: v.union(metaAuthorizerValidator, v.null()),
+    /** When Meta said the token expires; null for never, or not known. */
+    tokenExpiresAt: v.union(v.number(), v.null()),
+    /** A problem that did not stop the connection, such as a failed trade. */
+    lastError: v.union(v.string(), v.null()),
+  },
+  returns: v.id("metaConnections"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const warnAt =
+      args.tokenExpiresAt === null
+        ? null
+        : args.tokenExpiresAt - EXPIRY_WARNING_MS;
+    const existing = await ctx.db
+      .query("metaConnections")
+      .withIndex("by_ownerKey", (range) => range.eq("ownerKey", args.ownerKey))
+      .unique();
+    const pixels = args.pixelsComplete
+      ? args.pixels
+      : mergePixels(args.pixels, existing?.pixels ?? []);
+    const fields = {
+      tokenExpiresAt: args.tokenExpiresAt ?? undefined,
+      expiringSoon: warnAt !== null && warnAt <= now ? true : undefined,
+      tokenCipher: args.tokenCipher,
+      tokenIv: args.tokenIv,
+      businessName: args.businessName ?? undefined,
+      status: "active" as const,
+      adAccounts: args.adAccounts,
+      pixels,
+      authorizedBy: args.authorizedBy ?? undefined,
+      authorizedAt: args.authorizedBy ? now : undefined,
+      invalidSince: undefined,
+      lastCheckedAt: now,
+      lastError: args.lastError ?? undefined,
+      updatedAt: now,
+    };
+    const connectionId =
+      existing?._id ??
+      (await ctx.db.insert("metaConnections", {
+        ownerKey: args.ownerKey,
+        ...fields,
+        createdAt: now,
+      }));
+    // A query cannot read the clock, so the warning is a flag a scheduled
+    // run sets 7 days before the token dies (that token only: a newer one
+    // has another IV and ignores it).
+    if (warnAt !== null && warnAt > now) {
+      await ctx.scheduler.runAt(warnAt, internal.meta.markExpiringSoon, {
+        connectionId,
+        tokenIv: args.tokenIv,
+      });
+    }
+    if (!existing) return connectionId;
+    await ctx.db.patch("metaConnections", existing._id, fields);
+    // A new token resumes the accounts a dead one had stopped, but only
+    // those it lists: another business's token sees other accounts.
+    await reconcileGrants(ctx, existing._id, args.adAccounts, pixels, true);
+    return existing._id;
+  },
+});
+
+const ACCOUNT_NOT_GRANTED =
+  "AD_ACCOUNT_NOT_GRANTED: this connection's token does not list the ad account; grant it in Meta and connect again";
+const PIXEL_NOT_GRANTED =
+  "PIXEL_NOT_GRANTED: this connection's token does not list the pixel; grant it in Meta and connect again";
+
+const mergePixels = (fresh: MetaPixel[], kept: MetaPixel[]) => {
+  const byId = new Map(kept.map((pixel) => [pixel.pixelId, pixel]));
+  for (const pixel of fresh) byId.set(pixel.pixelId, pixel);
+  return [...byId.values()].slice(0, MAX_PIXELS);
+};
+
+/**
+ * Lines the connection's links and pixels up with what its token lists. A
+ * link to an account the token no longer lists stops, saying why; one it
+ * lists again (or, with a new token, one a dead token had stopped) resumes.
+ * A pixel the token no longer lists says why too (`loadPixelToken` already
+ * refuses it).
+ */
+async function reconcileGrants(
+  ctx: MutationCtx,
+  connectionId: Id<"metaConnections">,
+  adAccounts: MetaAdAccount[],
+  pixels: MetaPixel[],
+  newToken: boolean,
+) {
+  const now = Date.now();
+  const listed = new Set(adAccounts.map((account) => account.adAccountId));
+  const links = await ctx.db
+    .query("siteAdAccounts")
+    .withIndex("by_connectionId", (range) =>
+      range.eq("connectionId", connectionId),
+    )
+    .take(MAX_LINKS_PER_CONNECTION);
+  let resumed = false;
+  for (const link of links) {
+    if (!listed.has(link.adAccountId)) {
+      if (link.lastError === ACCOUNT_NOT_GRANTED) continue;
+      await ctx.db.patch("siteAdAccounts", link._id, {
+        syncState: "error",
+        runId: undefined,
+        syncRequested: undefined,
+        lastError: ACCOUNT_NOT_GRANTED,
+        nextSyncAt: PAUSED_AT,
+      });
+      continue;
+    }
+    if (
+      link.nextSyncAt !== PAUSED_AT ||
+      !(newToken || link.lastError === ACCOUNT_NOT_GRANTED)
+    ) {
+      continue;
+    }
+    await ctx.db.patch("siteAdAccounts", link._id, {
+      syncState: link.lastSyncAt === undefined ? "backfill" : "live",
+      lastError: undefined,
+      nextSyncAt: now,
+    });
+    resumed = true;
+  }
+  if (resumed) await kickSyncLoop(ctx, now);
+  const pixelIds = new Set(pixels.map((pixel) => pixel.pixelId));
+  const sitePixels = await ctx.db
+    .query("sitePixels")
+    .withIndex("by_connectionId", (range) =>
+      range.eq("connectionId", connectionId),
+    )
+    .take(MAX_LINKS_PER_CONNECTION);
+  for (const pixel of sitePixels) {
+    const granted = pixelIds.has(pixel.pixelId);
+    if (!granted && pixel.lastError !== PIXEL_NOT_GRANTED) {
+      await ctx.db.patch("sitePixels", pixel._id, {
+        lastError: PIXEL_NOT_GRANTED,
+      });
+    } else if (granted && pixel.lastError === PIXEL_NOT_GRANTED) {
+      await ctx.db.patch("sitePixels", pixel._id, { lastError: undefined });
+    }
+  }
+}
+
+export const markExpiringSoon = internalMutation({
+  args: { connectionId: v.id("metaConnections"), tokenIv: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const connection = await ctx.db.get("metaConnections", args.connectionId);
+    if (connection?.tokenIv !== args.tokenIv) return null;
+    await ctx.db.patch("metaConnections", args.connectionId, {
+      expiringSoon: true,
+    });
+    return null;
+  },
+});
+
+export const updateConnectionAccounts = internalMutation({
+  args: {
+    connectionId: v.id("metaConnections"),
+    /** The token the listing came from: a newer one's listing wins. */
+    tokenIv: v.string(),
+    adAccounts: v.array(metaAdAccountValidator),
+    pixels: v.array(metaPixelValidator),
+    pixelsComplete: v.boolean(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const connection = await ctx.db.get("metaConnections", args.connectionId);
+    // Removed, or reconnected, while Meta answered: not this token's to say.
+    if (connection?.tokenIv !== args.tokenIv) return null;
+    const pixels = args.pixelsComplete
+      ? args.pixels
+      : mergePixels(args.pixels, connection.pixels ?? []);
+    await ctx.db.patch("metaConnections", args.connectionId, {
+      adAccounts: args.adAccounts,
+      pixels,
+      lastCheckedAt: now,
+      updatedAt: now,
+    });
+    await reconcileGrants(
+      ctx,
+      args.connectionId,
+      args.adAccounts,
+      pixels,
+      false,
+    );
+    return null;
+  },
+});
+
+/**
+ * Meta refused the token sealed with `tokenIv`. A call that started with an
+ * older token and ends after a reconnect changes nothing: the new token is
+ * not the one that failed.
+ */
+export const markConnectionInvalid = internalMutation({
+  args: {
+    connectionId: v.id("metaConnections"),
+    tokenIv: v.string(),
+    message: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const connection = await ctx.db.get("metaConnections", args.connectionId);
+    if (connection?.tokenIv !== args.tokenIv) return null;
+    await ctx.db.patch("metaConnections", args.connectionId, {
+      status: "invalid",
+      invalidSince: connection.invalidSince ?? now,
+      lastError: args.message.slice(0, 300),
+      lastCheckedAt: now,
+      updatedAt: now,
+    });
+    return null;
+  },
+});
+
+export const loadConnection = internalQuery({
+  args: { ownerKey: v.string() },
+  returns: v.union(
+    v.null(),
+    v.object({
+      connectionId: v.id("metaConnections"),
+      tokenCipher: v.string(),
+      tokenIv: v.string(),
+      status: v.union(v.literal("active"), v.literal("invalid")),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const connection = await ctx.db
+      .query("metaConnections")
+      .withIndex("by_ownerKey", (range) => range.eq("ownerKey", args.ownerKey))
+      .unique();
+    return connection
+      ? {
+          connectionId: connection._id,
+          tokenCipher: connection.tokenCipher,
+          tokenIv: connection.tokenIv,
+          status: connection.status,
+        }
+      : null;
+  },
+});
+
+/**
+ * The path every token takes in: who it is (`/me`), its ad accounts and their
+ * pixels, then sealed and saved for the owner.
+ */
+async function connectToken(
+  ctx: ActionCtx,
+  ownerKey: string,
+  token: string,
+  client: MetaGraph,
+  /**
+   * Facebook Login: when the token expires (null for never), and what went
+   * wrong on the way that did not stop it (no sensitive data).
+   */
+  login: { expiresAt: number | null; lastError: string | null } | null,
+) {
+  let businessName: string | null;
+  let authorizedBy: MetaAuthorizer | null = null;
+  let adAccounts: MetaAdAccount[];
+  let pixels: MetaPixel[];
+  let pixelsComplete: boolean;
+  try {
+    const me = await client.me(token);
+    businessName = me.name?.slice(0, 200) ?? null;
+    if (login) {
+      authorizedBy = { id: me.id.slice(0, 64), name: businessName };
+    }
+    adAccounts = (await client.adAccounts(token)).map(toAccount);
+    ({ pixels, complete: pixelsComplete } = await listPixels(
+      client,
+      token,
+      adAccounts,
+    ));
+  } catch (error) {
+    metaFailure(error);
+  }
+  const sealed = await encryptSecret(env.RASTRO_SECRETS_KEY, token);
+  const connectionId: Id<"metaConnections"> = await ctx.runMutation(
+    internal.meta.saveConnection,
+    {
+      ownerKey,
+      tokenCipher: sealed.cipher,
+      tokenIv: sealed.iv,
+      businessName,
+      adAccounts,
+      pixels,
+      pixelsComplete,
+      authorizedBy,
+      tokenExpiresAt: login?.expiresAt ?? null,
+      lastError: login?.lastError ?? null,
+    },
+  );
+  return { connectionId, businessName, adAccounts, pixels };
+}
+
+/**
+ * Validates a Meta token (a system user token with `ads_read`), lists its ad
+ * accounts and their pixels and stores it sealed for `ownerKey`. Pasting a new
+ * token for the same owner replaces the old one and resumes any account it
+ * had stopped.
+ */
+export const connect = action({
+  args: { ownerKey: v.string(), accessToken: v.string() },
+  returns: metaConnectResultValidator,
+  handler: async (ctx, args) => {
+    const ownerKey = ownerKeyOf(args.ownerKey);
+    const token = tokenOf(args.accessToken);
+    requireKey();
+    return await connectToken(ctx, ownerKey, token, graph(), null);
+  },
+});
+
+/**
+ * Facebook Login for Business: trades the authorization code Meta sent to
+ * `redirectUri` for a token (with RASTRO_META_APP_ID/SECRET, server to
+ * server), then connects it like a pasted one and records who authorized it.
+ * Without the app env it fails with `META_LOGIN_UNAVAILABLE`; a code Meta
+ * refuses fails with `META_TOKEN_INVALID`.
+ */
+export const connectWithCode = action({
+  args: { ownerKey: v.string(), code: v.string(), redirectUri: v.string() },
+  returns: metaConnectResultValidator,
+  handler: async (ctx, args) => {
+    const ownerKey = ownerKeyOf(args.ownerKey);
+    const code = codeOf(args.code);
+    const redirectUri = redirectUriOf(args.redirectUri);
+    const app = loginApp();
+    requireKey();
+    const client = graph();
+    let token: string;
+    let expiresAt: number | null;
+    try {
+      const exchanged = await client.exchangeCode(app, code, redirectUri);
+      token = exchanged.accessToken;
+      // Meta says how long a token lives in the exchange itself. Only when
+      // it does not is the token inspected (`debug_token`). A system user
+      // token (Login for Business with a system user configuration) never
+      // expires and is kept as it is.
+      expiresAt =
+        exchanged.expiresInMs !== null
+          ? Date.now() + exchanged.expiresInMs
+          : (await client.debugToken(app, token)).expiresAt;
+    } catch (error) {
+      metaFailure(error);
+    }
+    // A token with under 7 days left (a user token from a login without a
+    // system user configuration lives for hours) is traded for a long-lived
+    // one, about 60 days. A failed trade never fails the login: the token
+    // that came is kept with its expiry, so the warning is up at once and
+    // the screen asks for a new login in time.
+    let exchangeError: string | null = null;
+    if (expiresAt !== null && expiresAt - Date.now() < EXPIRY_WARNING_MS) {
+      try {
+        const long = await client.exchangeLongLived(app, token);
+        const longExpiresAt =
+          long.expiresInMs !== null
+            ? Date.now() + long.expiresInMs
+            : (await client.debugToken(app, long.accessToken)).expiresAt;
+        token = long.accessToken;
+        expiresAt = longExpiresAt;
+      } catch {
+        exchangeError = TOKEN_EXCHANGE_FAILED;
+      }
+    }
+    return await connectToken(ctx, ownerKey, tokenOf(token), client, {
+      expiresAt,
+      lastError: exchangeError,
+    });
+  },
+});
+
+/**
+ * The owner's ad accounts, read again from Meta with their pixels (and cached
+ * for linking and picking a pixel).
+ */
+export const listAdAccounts = action({
+  args: { ownerKey: v.string() },
+  returns: v.array(metaAdAccountValidator),
+  handler: async (ctx, args) => {
+    const ownerKey = ownerKeyOf(args.ownerKey);
+    const connection = await ctx.runQuery(internal.meta.loadConnection, {
+      ownerKey,
+    });
+    if (!connection) fail("NOT_FOUND", "no Meta connection for this owner");
+    const token = await decryptSecret(env.RASTRO_SECRETS_KEY, {
+      cipher: connection.tokenCipher,
+      iv: connection.tokenIv,
+    });
+    let adAccounts: MetaAdAccount[];
+    let pixels: MetaPixel[];
+    let pixelsComplete: boolean;
+    try {
+      const client = graph();
+      adAccounts = (await client.adAccounts(token)).map(toAccount);
+      ({ pixels, complete: pixelsComplete } = await listPixels(
+        client,
+        token,
+        adAccounts,
+      ));
+    } catch (error) {
+      if (error instanceof MetaGraphError && error.kind === "token") {
+        await ctx.runMutation(internal.meta.markConnectionInvalid, {
+          connectionId: connection.connectionId,
+          tokenIv: connection.tokenIv,
+          message: error.message,
+        });
+      }
+      metaFailure(error);
+    }
+    await ctx.runMutation(internal.meta.updateConnectionAccounts, {
+      connectionId: connection.connectionId,
+      tokenIv: connection.tokenIv,
+      adAccounts,
+      pixels,
+      pixelsComplete,
+    });
+    return adAccounts;
+  },
+});
+
+async function connectionOf(ctx: QueryCtx, ownerKey: string) {
+  const key = ownerKeyOf(ownerKey);
+  return await ctx.db
+    .query("metaConnections")
+    .withIndex("by_ownerKey", (range) => range.eq("ownerKey", key))
+    .unique();
+}
+
+async function unlinkRow(
+  ctx: MutationCtx,
+  link: { _id: Id<"siteAdAccounts">; siteId: Id<"sites">; adAccountId: string },
+) {
+  await ctx.db.delete("siteAdAccounts", link._id);
+  // The account's spend stops counting for the site; its history goes too.
+  await ctx.scheduler.runAfter(0, internal.metaSync.purgeSpend, {
+    siteId: link.siteId,
+    adAccountId: link.adAccountId,
+    cursor: null,
+  });
+}
+
+/**
+ * Forgets the owner: its token, every account it fed, and every pixel it set,
+ * the ones with their own token (plan B) included. The token goes at once (no
+ * run can load it after this), its links and pixels in scheduled batches. An
+ * owner with plan B pixels and no connection still loses those pixels.
+ */
+export const removeConnection = mutation({
+  args: { ownerKey: v.string() },
+  returns: v.object({ removed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const ownerKey = ownerKeyOf(args.ownerKey);
+    const connection = await ctx.db
+      .query("metaConnections")
+      .withIndex("by_ownerKey", (range) => range.eq("ownerKey", ownerKey))
+      .unique();
+    if (connection) await ctx.db.delete("metaConnections", connection._id);
+    const removedPixels = await removeOwnerBatch(ctx, {
+      connectionId: connection?._id,
+      ownerKey,
+      before: Date.now(),
+    });
+    return { removed: connection !== null || removedPixels > 0 };
+  },
+});
+
+/**
+ * One batch of a removed owner: its connection's links and pixels, and the
+ * pixels it set (`setBy`) last changed by `before`, so a pixel the same owner
+ * sets again after the removal stays. The owner's pixels are walked in
+ * creation order from `after`, so every batch moves on even past the ones it
+ * keeps. Schedules the next batch while any is left and answers how many
+ * pixels this one removed.
+ */
+async function removeOwnerBatch(
+  ctx: MutationCtx,
+  owner: {
+    connectionId?: Id<"metaConnections"> | undefined;
+    ownerKey?: string | undefined;
+    before?: number | undefined;
+    after?: number | undefined;
+  },
+) {
+  const { connectionId, ownerKey, before, after } = owner;
+  const links = connectionId
+    ? await ctx.db
+        .query("siteAdAccounts")
+        .withIndex("by_connectionId", (range) =>
+          range.eq("connectionId", connectionId),
+        )
+        .take(UNLINK_BATCH)
+    : [];
+  for (const link of links) await unlinkRow(ctx, link);
+  // A pixel picked through the connection sent with its token: it goes too.
+  const connectionPixels = connectionId
+    ? await ctx.db
+        .query("sitePixels")
+        .withIndex("by_connectionId", (range) =>
+          range.eq("connectionId", connectionId),
+        )
+        .take(UNLINK_BATCH)
+    : [];
+  for (const pixel of connectionPixels) {
+    await ctx.db.delete("sitePixels", pixel._id);
+  }
+  // So does every pixel the owner set with its own token (plan B), unless it
+  // was set again after the removal (`updatedAt` past `before`).
+  const ownerPixels =
+    ownerKey === undefined || before === undefined
+      ? []
+      : await ctx.db
+          .query("sitePixels")
+          .withIndex("by_setBy", (range) =>
+            after === undefined
+              ? range.eq("setBy", ownerKey)
+              : range.eq("setBy", ownerKey).gt("_creationTime", after),
+          )
+          .take(UNLINK_BATCH);
+  // `<=`: a pixel set in the removal's own millisecond, before it, must go;
+  // one set again in that same millisecond after it goes too (the rarer case).
+  const stale = ownerPixels.filter((pixel) => pixel.updatedAt <= before!);
+  for (const pixel of stale) await ctx.db.delete("sitePixels", pixel._id);
+  const cursor = ownerPixels.at(-1)?._creationTime;
+  if (
+    links.length === UNLINK_BATCH ||
+    connectionPixels.length === UNLINK_BATCH ||
+    ownerPixels.length === UNLINK_BATCH
+  ) {
+    await ctx.scheduler.runAfter(0, internal.meta.unlinkConnection, {
+      ...(connectionId ? { connectionId } : {}),
+      ...(ownerKey === undefined || before === undefined
+        ? {}
+        : { ownerKey, before }),
+      // A full owner batch goes on from its last row; otherwise from where
+      // this one started.
+      ...(ownerPixels.length === UNLINK_BATCH && cursor !== undefined
+        ? { after: cursor }
+        : after === undefined
+          ? {}
+          : { after }),
+    });
+  }
+  return connectionPixels.length + stale.length;
+}
+
+/** The next batch of a removed owner's links and pixels. */
+export const unlinkConnection = internalMutation({
+  args: {
+    connectionId: v.optional(v.id("metaConnections")),
+    ownerKey: v.optional(v.string()),
+    /** The removal's time: the owner's pixels as they were then. */
+    before: v.optional(v.number()),
+    /** The `_creationTime` of the last owner pixel already walked. */
+    after: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await removeOwnerBatch(ctx, args);
+    return null;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Site ↔ ad account.
+
+/**
+ * Makes one of the owner's ad accounts a spend source for the site: a 90-day
+ * backfill with the catalog, then the live sync. The account must be in the
+ * connection's last listing. Linking an account another owner linked to the
+ * site moves the link to this owner, unless `onlyOwn` (the federated path,
+ * which never takes what another owner made: `CONFLICT`).
+ */
+export const linkAdAccount = mutation({
+  args: {
+    siteId: v.id("sites"),
+    ownerKey: v.string(),
+    adAccountId: v.string(),
+    onlyOwn: v.optional(v.boolean()),
+  },
+  returns: v.object({ linked: v.boolean() }),
+  handler: async (ctx, args) => {
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+    const adAccountId = adAccountIdOf(args.adAccountId);
+    const connection = await ctx.db
+      .query("metaConnections")
+      .withIndex("by_ownerKey", (range) =>
+        range.eq("ownerKey", ownerKeyOf(args.ownerKey)),
+      )
+      .unique();
+    if (!connection) fail("NOT_FOUND", "no Meta connection for this owner");
+    if (connection.status !== "active") {
+      fail(
+        "META_TOKEN_INVALID",
+        "the owner's Meta token is invalid; connect again",
+      );
+    }
+    const account = connection.adAccounts.find(
+      (row) => row.adAccountId === adAccountId,
+    );
+    if (!account) {
+      fail("NOT_FOUND", "the owner's Meta token does not list this ad account");
+    }
+    const now = Date.now();
+    // An ad account feeds one site: its spend is that client's.
+    const owners = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_adAccountId", (range) =>
+        range.eq("adAccountId", adAccountId),
+      )
+      .take(2);
+    if (owners.some((link) => link.siteId !== args.siteId)) {
+      fail("CONFLICT", "this ad account is already linked to another site");
+    }
+    const existing = owners.find((link) => link.siteId === args.siteId);
+    if (existing) {
+      if (existing.connectionId !== connection._id) {
+        if (args.onlyOwn)
+          fail(
+            "CONFLICT",
+            "this ad account is linked to the site by another owner on this host; unlink it there",
+          );
+        await ctx.db.patch("siteAdAccounts", existing._id, {
+          connectionId: connection._id,
+          ...account,
+          lastError: undefined,
+          nextSyncAt: now,
+        });
+        await kickSyncLoop(ctx, now);
+      }
+      return { linked: true };
+    }
+    const links = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .take(MAX_SITE_AD_ACCOUNTS);
+    if (links.length >= MAX_SITE_AD_ACCOUNTS) {
+      fail(
+        "LIMIT_EXCEEDED",
+        `a site links at most ${MAX_SITE_AD_ACCOUNTS} ad accounts`,
+      );
+    }
+    const siblings = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_connectionId", (range) =>
+        range.eq("connectionId", connection._id),
+      )
+      .take(MAX_LINKS_PER_CONNECTION);
+    if (siblings.length >= MAX_LINKS_PER_CONNECTION) {
+      fail(
+        "LIMIT_EXCEEDED",
+        `a Meta connection feeds at most ${MAX_LINKS_PER_CONNECTION} links`,
+      );
+    }
+    await ctx.db.insert("siteAdAccounts", {
+      siteId: args.siteId,
+      connectionId: connection._id,
+      ...account,
+      syncState: "backfill",
+      nextSyncAt: now,
+      createdAt: now,
+    });
+    await kickSyncLoop(ctx, now);
+    return { linked: true };
+  },
+});
+
+/** Stops an ad account feeding the site; its spend leaves the reports. */
+export const unlinkAdAccount = mutation({
+  args: {
+    siteId: v.id("sites"),
+    adAccountId: v.string(),
+    /** Only this owner's link: another owner's is a `CONFLICT`. */
+    ownerKey: v.optional(v.string()),
+  },
+  returns: v.object({ unlinked: v.boolean() }),
+  handler: async (ctx, args) => {
+    const link = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_siteId_and_adAccountId", (range) =>
+        range
+          .eq("siteId", args.siteId)
+          .eq("adAccountId", adAccountIdOf(args.adAccountId)),
+      )
+      .unique();
+    if (!link) return { unlinked: false };
+    if (args.ownerKey !== undefined) {
+      const owner = await connectionOf(ctx, args.ownerKey);
+      if (owner?._id !== link.connectionId) {
+        fail(
+          "CONFLICT",
+          "this ad account is linked to the site by another owner on this host; unlink it there",
+        );
+      }
+    }
+    await unlinkRow(ctx, link);
+    return { unlinked: true };
+  },
+});
+
+/**
+ * Asks the chain to sync every account of the site now. An account a run
+ * holds is marked, and runs again as soon as that run ends.
+ */
+export const syncNow = mutation({
+  args: { siteId: v.id("sites") },
+  returns: v.object({ scheduled: v.boolean() }),
+  handler: async (ctx, args) => {
+    const links = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .take(MAX_SITE_AD_ACCOUNTS);
+    const now = Date.now();
+    let scheduled = false;
+    for (const link of links) {
+      // A dead token needs a new one, not a retry.
+      if (link.nextSyncAt === PAUSED_AT) continue;
+      scheduled = true;
+      if (link.runId !== undefined) {
+        await ctx.db.patch("siteAdAccounts", link._id, { syncRequested: true });
+        continue;
+      }
+      await ctx.db.patch("siteAdAccounts", link._id, { nextSyncAt: now });
+    }
+    if (scheduled) await kickSyncLoop(ctx, now);
+    return { scheduled };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Pixel.
+
+export const savePixel = internalMutation({
+  args: {
+    siteId: v.id("sites"),
+    pixelId: v.string(),
+    sealed: v.union(
+      v.object({ tokenCipher: v.string(), tokenIv: v.string() }),
+      v.object({ ownerKey: v.string() }),
+    ),
+    enabled: v.boolean(),
+    testEventCode: v.union(v.string(), v.null()),
+    sendLeadEvent: v.union(v.boolean(), v.null()),
+    /** The owner setting the pixel, if the host named one. */
+    setBy: v.union(v.string(), v.null()),
+    /** Refuse to replace a pixel another owner (or the host) set. */
+    onlyOwn: v.boolean(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    let source: Doc<"sitePixels">["source"] = "token";
+    let fromConnection: Partial<Doc<"sitePixels">> = {};
+    if ("ownerKey" in args.sealed) {
+      // Checked again here: the connection may have changed since the
+      // action read it.
+      const ownerKey = args.sealed.ownerKey;
+      const connection = await ctx.db
+        .query("metaConnections")
+        .withIndex("by_ownerKey", (range) => range.eq("ownerKey", ownerKey))
+        .unique();
+      const pixel = connection?.pixels?.find(
+        (row) => row.pixelId === args.pixelId,
+      );
+      if (!connection) fail("NOT_FOUND", "no Meta connection for this owner");
+      if (connection.status !== "active") {
+        fail(
+          "META_TOKEN_INVALID",
+          "the owner's Meta token is invalid; connect again",
+        );
+      }
+      if (!pixel) {
+        fail(
+          "NOT_FOUND",
+          "the owner's Meta connection does not list this pixel",
+        );
+      }
+      source = "connection";
+      fromConnection = { connectionId: connection._id, name: pixel.name };
+    }
+    const existing = await ctx.db
+      .query("sitePixels")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .unique();
+    if (
+      args.onlyOwn &&
+      existing &&
+      existing.setBy !== (args.setBy ?? undefined)
+    ) {
+      fail(
+        "CONFLICT",
+        "the site's pixel was set by another owner on this host; change it there",
+      );
+    }
+    const pipeline = await ctx.db
+      .query("sitePipelines")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .unique();
+    const fields = {
+      siteId: args.siteId,
+      pixelId: args.pixelId,
+      source,
+      ...fromConnection,
+      ...(args.setBy ? { setBy: args.setBy } : {}),
+      ...("tokenCipher" in args.sealed
+        ? { tokenCipher: args.sealed.tokenCipher, tokenIv: args.sealed.tokenIv }
+        : {}),
+      enabled: args.enabled,
+      ...(args.testEventCode ? { testEventCode: args.testEventCode } : {}),
+      // Unsaid, `Lead` keeps what the site had (the event map's choice).
+      sendLeadEvent:
+        args.sendLeadEvent ??
+        pipeline?.sendLeadEvent ??
+        existing?.sendLeadEvent ??
+        false,
+      updatedAt: Date.now(),
+    };
+    if (existing) await ctx.db.replace("sitePixels", existing._id, fields);
+    else await ctx.db.insert("sitePixels", fields);
+    if (pipeline && pipeline.sendLeadEvent !== fields.sendLeadEvent) {
+      await ctx.db.patch("sitePipelines", pipeline._id, {
+        sendLeadEvent: fields.sendLeadEvent,
+      });
+    }
+    return null;
+  },
+});
+
+export const siteExists = internalQuery({
+  args: { siteId: v.id("sites") },
+  returns: v.boolean(),
+  handler: async (ctx, args) =>
+    (await ctx.db.get("sites", args.siteId)) !== null,
+});
+
+/**
+ * Sets the site's Meta pixel (dataset) one of two ways:
+ * - `{ ownerKey }`: a pixel from that owner's connection listing, sending with
+ *   the connection's token (a new token for the connection carries over);
+ * - `{ accessToken }`: a Conversions API token from Events Manager (plan B),
+ *   checked against the pixel and sealed like a connection's.
+ * `Lead` for a new lead is off unless `sendLeadEvent` (or the event map) says
+ * so.
+ */
+export const setPixel = action({
+  args: {
+    siteId: v.id("sites"),
+    pixelId: v.string(),
+    accessToken: v.optional(v.string()),
+    ownerKey: v.optional(v.string()),
+    enabled: v.boolean(),
+    testEventCode: v.optional(v.string()),
+    sendLeadEvent: v.optional(v.boolean()),
+    /**
+     * The owner setting a token-sourced pixel (a connection-sourced one is
+     * its `ownerKey`'s). With `onlyOwn`, a pixel another owner set is a
+     * `CONFLICT` instead of being replaced.
+     */
+    setBy: v.optional(v.string()),
+    onlyOwn: v.optional(v.boolean()),
+  },
+  returns: v.object({ ok: v.literal(true) }),
+  handler: async (ctx, args) => {
+    const pixelId = args.pixelId.trim();
+    if (!PIXEL_ID.test(pixelId)) {
+      fail("INVALID_ARGUMENT", "pixelId must be the dataset's numeric id");
+    }
+    if ((args.accessToken === undefined) === (args.ownerKey === undefined)) {
+      fail("INVALID_ARGUMENT", "pass either accessToken or ownerKey");
+    }
+    const testEventCode = args.testEventCode?.trim() || null;
+    if (
+      testEventCode !== null &&
+      (testEventCode.length > MAX_TEST_EVENT_CODE ||
+        !/^[A-Za-z0-9_-]+$/.test(testEventCode))
+    ) {
+      fail("INVALID_ARGUMENT", "testEventCode is invalid");
+    }
+    const save = {
+      siteId: args.siteId,
+      pixelId,
+      enabled: args.enabled,
+      testEventCode,
+      sendLeadEvent: args.sendLeadEvent ?? null,
+      setBy:
+        args.ownerKey !== undefined
+          ? ownerKeyOf(args.ownerKey)
+          : args.setBy !== undefined
+            ? ownerKeyOf(args.setBy)
+            : null,
+      onlyOwn: args.onlyOwn ?? false,
+    };
+    if (args.ownerKey !== undefined) {
+      const ownerKey = ownerKeyOf(args.ownerKey);
+      if (
+        !(await ctx.runQuery(internal.meta.siteExists, { siteId: args.siteId }))
+      ) {
+        fail("NOT_FOUND", "site not found");
+      }
+      const connection = await ctx.runQuery(internal.meta.loadConnection, {
+        ownerKey,
+      });
+      if (!connection) fail("NOT_FOUND", "no Meta connection for this owner");
+      if (connection.status !== "active") {
+        fail(
+          "META_TOKEN_INVALID",
+          "the owner's Meta token is invalid; connect again",
+        );
+      }
+      await ctx.runMutation(internal.meta.savePixel, {
+        ...save,
+        sealed: { ownerKey },
+      });
+      return { ok: true as const };
+    }
+    const token = tokenOf(args.accessToken ?? "");
+    requireKey();
+    if (
+      !(await ctx.runQuery(internal.meta.siteExists, { siteId: args.siteId }))
+    ) {
+      fail("NOT_FOUND", "site not found");
+    }
+    try {
+      await graph().pixel(token, pixelId);
+    } catch (error) {
+      metaFailure(error);
+    }
+    const sealed = await encryptSecret(env.RASTRO_SECRETS_KEY, token);
+    await ctx.runMutation(internal.meta.savePixel, {
+      ...save,
+      sealed: { tokenCipher: sealed.cipher, tokenIv: sealed.iv },
+    });
+    return { ok: true as const };
+  },
+});
+
+/**
+ * The sealed token a site's pixel sends with, for the Conversions API sender:
+ * its own (`token`), or its connection's while that connection is active
+ * (`connection`). Null when there is none to send with: no pixel, a disabled
+ * one, a token Meta refused, or a connection Meta refused or that was
+ * removed. When Meta refuses a `connection` token, mark it with
+ * `internal.meta.markConnectionInvalid({ connectionId, message })`.
+ */
+export const loadPixelToken = internalQuery({
+  args: { siteId: v.id("sites") },
+  returns: v.union(
+    v.null(),
+    v.object({
+      pixelId: v.string(),
+      tokenCipher: v.string(),
+      tokenIv: v.string(),
+      source: metaPixelSourceValidator,
+      /** For `connection`: the one to mark invalid when Meta refuses it. */
+      connectionId: v.optional(v.id("metaConnections")),
+    }),
+  ),
+  handler: async (ctx, args) => {
+    const pixel = await ctx.db
+      .query("sitePixels")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .unique();
+    if (!pixel?.enabled) return null;
+    if (pixel.source === "connection") {
+      const connection = pixel.connectionId
+        ? await ctx.db.get("metaConnections", pixel.connectionId)
+        : null;
+      if (connection?.status !== "active") return null;
+      // The token no longer lists the pixel (another business reconnected).
+      if (!connection.pixels?.some((row) => row.pixelId === pixel.pixelId)) {
+        return null;
+      }
+      return {
+        pixelId: pixel.pixelId,
+        tokenCipher: connection.tokenCipher,
+        tokenIv: connection.tokenIv,
+        source: "connection" as const,
+        connectionId: connection._id,
+      };
+    }
+    // A pixel whose own token Meta refused waits for a new one.
+    if (pixel.invalidSince !== undefined) return null;
+    if (!pixel.tokenCipher || !pixel.tokenIv) return null;
+    return {
+      pixelId: pixel.pixelId,
+      tokenCipher: pixel.tokenCipher,
+      tokenIv: pixel.tokenIv,
+      source: "token" as const,
+    };
+  },
+});
+
+export const removePixel = mutation({
+  args: {
+    siteId: v.id("sites"),
+    /** Only this owner's pixel: another owner's is a `CONFLICT`. */
+    ownerKey: v.optional(v.string()),
+  },
+  returns: v.object({ removed: v.boolean() }),
+  handler: async (ctx, args) => {
+    const pixel = await ctx.db
+      .query("sitePixels")
+      .withIndex("by_siteId", (range) => range.eq("siteId", args.siteId))
+      .unique();
+    if (!pixel) return { removed: false };
+    if (
+      args.ownerKey !== undefined &&
+      pixel.setBy !== ownerKeyOf(args.ownerKey)
+    ) {
+      fail(
+        "CONFLICT",
+        "the site's pixel was set by another owner on this host; remove it there",
+      );
+    }
+    await ctx.db.delete("sitePixels", pixel._id);
+    return { removed: true };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Reads.
+
+/**
+ * Where each site stands with Meta. A site with nothing linked says so. With
+ * `ownerKey`, each link and the pixel say whether that owner made them
+ * (`own`), so a screen can lock what another owner made.
+ */
+export const status = query({
+  args: {
+    siteIds: v.array(v.id("sites")),
+    ownerKey: v.optional(v.string()),
+    /** The reader's clock, for the sent counts of the last 30 days. */
+    now: v.optional(v.number()),
+  },
+  returns: metaStatusValidator,
+  handler: async (ctx, args) => {
+    const owner =
+      args.ownerKey === undefined
+        ? undefined
+        : ((await connectionOf(ctx, args.ownerKey)) ?? null);
+    const ownerKey =
+      args.ownerKey === undefined ? undefined : ownerKeyOf(args.ownerKey);
+    const siteIds = [...new Set(args.siteIds)];
+    if (
+      siteIds.length < 1 ||
+      siteIds.length > MAX_REPORT_SITES ||
+      siteIds.length !== args.siteIds.length
+    ) {
+      fail(
+        "INVALID_ARGUMENT",
+        `siteIds must contain 1-${MAX_REPORT_SITES} unique IDs`,
+      );
+    }
+    const rows = [];
+    for (const siteId of siteIds) {
+      const site = await ctx.db.get("sites", siteId);
+      if (!site) fail("NOT_FOUND", "site not found");
+      const links = await ctx.db
+        .query("siteAdAccounts")
+        .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+        .take(MAX_SITE_AD_ACCOUNTS);
+      const pixel = await ctx.db
+        .query("sitePixels")
+        .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
+        .unique();
+      rows.push({
+        siteId,
+        linked: links.length > 0,
+        adAccounts: links.map((link) => ({
+          adAccountId: link.adAccountId,
+          name: link.name,
+          currency: link.currency,
+          timezone: link.timezone,
+          syncState: link.syncState,
+          lastSyncAt: link.lastSyncAt ?? null,
+          lastError: link.lastError ?? null,
+          backfill: backfillProgress(link),
+          ...(owner === undefined
+            ? {}
+            : { own: owner?._id === link.connectionId }),
+        })),
+        pixel: {
+          enabled: pixel?.enabled ?? false,
+          pixelId: pixel?.pixelId ?? null,
+          source: pixel ? (pixel.source ?? "token") : null,
+          name: pixel?.name ?? null,
+          lastError: pixel?.lastError ?? null,
+          ...(ownerKey === undefined || !pixel
+            ? {}
+            : { own: pixel.setBy === ownerKey }),
+          testMode: pixel?.testEventCode !== undefined,
+        },
+        conversions: await conversionCounts(ctx, siteId, args.now),
+      });
+    }
+    return rows;
+  },
+});
+
+/** The site's latest conversions for its Meta pixel, newest first. */
+export const conversions = query({
+  args: {
+    siteId: v.id("sites"),
+    limit: v.optional(v.number()),
+    before: v.optional(v.number()),
+    /** The last row's `eventId`, with its `createdAt` as `before`. */
+    beforeEventId: v.optional(v.string()),
+  },
+  returns: v.array(metaConversionValidator),
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? MAX_LEAD_LIST;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_LEAD_LIST) {
+      fail(
+        "INVALID_ARGUMENT",
+        `limit must be an integer between 1 and ${MAX_LEAD_LIST}`,
+      );
+    }
+    const site = await ctx.db.get("sites", args.siteId);
+    if (!site) fail("NOT_FOUND", "site not found");
+    return await listConversions(ctx, {
+      siteId: args.siteId,
+      limit,
+      ...(args.before !== undefined ? { before: args.before } : {}),
+      ...(args.beforeEventId !== undefined
+        ? { beforeEventId: args.beforeEventId }
+        : {}),
+    });
+  },
+});
+
+/**
+ * The owner's connection as a screen shows it: status, who authorized it, the
+ * listed ad accounts (each with the site it already feeds, whoever linked it,
+ * since an account feeds one site) and the listed pixels. Never a token.
+ */
+export const connection = query({
+  args: { ownerKey: v.string() },
+  returns: metaConnectionValidator,
+  handler: async (ctx, args) => {
+    const connection = await ctx.db
+      .query("metaConnections")
+      .withIndex("by_ownerKey", (range) =>
+        range.eq("ownerKey", ownerKeyOf(args.ownerKey)),
+      )
+      .unique();
+    if (!connection) return null;
+    const adAccounts = [];
+    // One index read per listed account (the listing is capped by Meta's).
+    for (const account of connection.adAccounts) {
+      const link = await ctx.db
+        .query("siteAdAccounts")
+        .withIndex("by_adAccountId", (range) =>
+          range.eq("adAccountId", account.adAccountId),
+        )
+        .first();
+      adAccounts.push({ ...account, linkedSiteId: link?.siteId ?? null });
+    }
+    return {
+      status: connection.status,
+      businessName: connection.businessName ?? null,
+      authorizedBy: connection.authorizedBy
+        ? { name: connection.authorizedBy.name }
+        : null,
+      authorizedAt: connection.authorizedAt ?? null,
+      invalidSince:
+        connection.status === "invalid"
+          ? (connection.invalidSince ?? connection.lastCheckedAt)
+          : null,
+      lastError: connection.lastError ?? null,
+      expiresAt: connection.tokenExpiresAt ?? null,
+      expiringSoon: connection.expiringSoon === true,
+      adAccounts,
+      pixels: connection.pixels ?? [],
+    };
+  },
+});
+
+/**
+ * What unlinking the account takes out of the site's reports: its spend, over
+ * how many days, across how many campaigns (the unlink dialog's figures).
+ */
+export const unlinkPreview = query({
+  args: { siteId: v.id("sites"), adAccountId: v.string() },
+  returns: metaUnlinkPreviewValidator,
+  handler: async (ctx, args) => {
+    const adAccountId = adAccountIdOf(args.adAccountId);
+    const link = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_siteId_and_adAccountId", (range) =>
+        range.eq("siteId", args.siteId).eq("adAccountId", adAccountId),
+      )
+      .unique();
+    if (!link) fail("NOT_FOUND", "this ad account is not linked to the site");
+    // One row per account-local day: a few hundred at most.
+    const days = await ctx.db
+      .query("siteSpendDaily")
+      .withIndex("by_siteId_and_adAccountId_and_dayStart", (range) =>
+        range.eq("siteId", args.siteId).eq("adAccountId", adAccountId),
+      )
+      .take(MAX_PREVIEW_DAYS);
+    let spendCents = 0;
+    let first: number | null = null;
+    let last: number | null = null;
+    for (const day of days) {
+      if (day.spendCents <= 0) continue;
+      spendCents += day.spendCents;
+      first = first === null ? day.dayStart : Math.min(first, day.dayStart);
+      last = last === null ? day.dayStart : Math.max(last, day.dayStart);
+    }
+    const catalog = await ctx.db
+      .query("adCatalog")
+      .withIndex("by_siteId_and_adId", (range) =>
+        range.eq("siteId", args.siteId),
+      )
+      .take(MAX_PREVIEW_CATALOG);
+    const campaigns = new Set(
+      catalog
+        .filter((ad) => ad.adAccountId === adAccountId && ad.campaignId)
+        .map((ad) => ad.campaignId),
+    );
+    return {
+      spendCents,
+      currency: link.currency,
+      days:
+        first === null || last === null
+          ? 0
+          : Math.round((last - first) / 86_400_000) + 1,
+      campaigns: campaigns.size,
+      // A read cap was hit: the figures are a lower bound.
+      partial:
+        days.length === MAX_PREVIEW_DAYS ||
+        catalog.length === MAX_PREVIEW_CATALOG,
+    };
+  },
+});
+
+/**
+ * The sites an owner's connection reaches: those its links feed and those
+ * whose pixel it set. The federated whole-owner writes refuse while any of
+ * them is outside the caller's grant.
+ */
+export const connectionSites = query({
+  args: { ownerKey: v.string() },
+  returns: v.array(v.string()),
+  handler: async (ctx, args) => {
+    const connection = await connectionOf(ctx, args.ownerKey);
+    if (!connection) return [];
+    const ownerKey = connection.ownerKey;
+    const links = await ctx.db
+      .query("siteAdAccounts")
+      .withIndex("by_connectionId", (range) =>
+        range.eq("connectionId", connection._id),
+      )
+      .take(MAX_LINKS_PER_CONNECTION);
+    const pixels = await ctx.db
+      .query("sitePixels")
+      .withIndex("by_setBy", (range) => range.eq("setBy", ownerKey))
+      .take(MAX_LINKS_PER_CONNECTION);
+    return [
+      ...new Set([
+        ...links.map((link) => link.siteId),
+        ...pixels.map((pixel) => pixel.siteId),
+      ]),
+    ];
+  },
+});