@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/edit-hint-token.js

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createHmac, timingSafeEqual } from "crypto";
+import { tokenSigningSecret } from "./media-signing.js";
+/**
+ * Editor-presence HINT tokens for the tenant admin bar on `*.aglyn.app`
+ * (AGL-1842, the cross-site half AGL-1829 could not reach).
+ *
+ * The console session lives on `app.aglyn.com`; `*.aglyn.app` is a different
+ * registrable domain, so neither the AGL-1829 hint cookie nor the silent
+ * iframe probe can cross over — storage partitioning keeps the two worlds
+ * apart, correctly. What CAN cross is a top-level navigation: at console
+ * sign-in the browser is bounced once through
+ * `https://console.aglyn.app/api/edit-hint/set?sig=<bounce token>` and back,
+ * and in that first-party moment the tenant app plants a signed hint cookie
+ * on `Domain=.aglyn.app` that every tenant subdomain can present to its own
+ * server afterwards.
+ *
+ * Two kinds, deliberately non-interchangeable:
+ *
+ * - `bounce` — rides the redirect URL once. URLs are logged and shareable,
+ *   so its TTL is seconds ({@link EDIT_HINT_BOUNCE_TTL_MS}).
+ * - `cookie` — the planted `aglyn_edit_hint` value, HttpOnly, living the
+ *   {@link EDIT_HINT_COOKIE_TTL_MS} window between console visits.
+ *
+ * The kind is INSIDE the signed context string, so a leaked 60-second bounce
+ * URL can never be replayed as a week-long cookie, and a stolen cookie value
+ * can never be planted elsewhere through the bounce endpoint. The `edit-hint:`
+ * prefix domain-separates both from the `edit-bar:`/`media:`/commerce
+ * signatures sharing `TOKEN_SIGNING_SECRET`.
+ *
+ * A hint is NOT edit access: it names a uid and nothing else. Everything
+ * real happens server-side at the tenant's `/api/edit-access/exchange`,
+ * which re-authorizes that uid against the specific host being viewed with
+ * the same membership gate the console's token mint applies. A forged,
+ * expired, or stale hint costs one refused POST.
+ */ /** Seconds, not minutes: the bounce URL is single-use inside one redirect. */ export const EDIT_HINT_BOUNCE_TTL_MS = 60 * 1000;
+/** 7 days — matches the AGL-1829 marker cookie's refresh cadence. */ export const EDIT_HINT_COOKIE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * The HttpOnly signed hint cookie on `Domain=.aglyn.app`. Sibling of the
+ * JS-visible `aglyn_editor=1` marker (`EDITOR_HINT_COOKIE`), which the
+ * admin-bar stub reads to arm; this one only ever travels back to the
+ * tenant's own exchange route, where it is verified server-side.
+ */ export const EDIT_HINT_COOKIE = 'aglyn_edit_hint';
+/** Version tag, mirroring the edit-access token's debuggability rationale. */ const TOKEN_PREFIX = 'aglyn-edit-hint-v1';
+function signPayload(kind, payloadB64) {
+    return createHmac('sha256', tokenSigningSecret()).update(`edit-hint:${kind}:${payloadB64}`).digest('base64url');
+}
+/**
+ * Mints a hint of the given kind for a uid the caller has ALREADY verified
+ * (the console route verifies a Firebase ID token; the bounce endpoint
+ * verifies a `bounce` hint). The mint itself checks nothing.
+ */ export function mintEditHintToken(kind, uid, nowMs = Date.now()) {
+    if (!uid) throw new Error('uid is required');
+    const exp = nowMs + (kind === 'bounce' ? EDIT_HINT_BOUNCE_TTL_MS : EDIT_HINT_COOKIE_TTL_MS);
+    const claims = {
+        uid,
+        exp
+    };
+    const payload = Buffer.from(JSON.stringify(claims), 'utf8').toString('base64url');
+    return {
+        token: `${TOKEN_PREFIX}.${payload}.${signPayload(kind, payload)}`,
+        expiresAtMs: exp
+    };
+}
+/**
+ * Verifies a presented hint AS the stated kind and returns its claims, or
+ * `null` for anything else — expired, tampered, malformed, wrong version,
+ * wrong KIND (the replay wall), or a deploy with no signing secret (fail
+ * closed, like every signature in this family).
+ */ export function verifyEditHintToken(kind, token, nowMs = Date.now()) {
+    if (typeof token !== 'string' || token.length === 0 || token.length > 4096) {
+        return null;
+    }
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX) return null;
+    const [, payload, sig] = parts;
+    let expected;
+    try {
+        expected = signPayload(kind, payload);
+    } catch (unused) {
+        // Secret missing — refuse rather than trusting anything.
+        return null;
+    }
+    // Length-checked before timingSafeEqual, which THROWS on attacker-length
+    // input — a 500 where a refusal belongs (same note as edit-access-token).
+    if (sig.length !== expected.length) return null;
+    if (!timingSafeEqual(new Uint8Array(Buffer.from(sig)), new Uint8Array(Buffer.from(expected)))) {
+        return null;
+    }
+    let claims;
+    try {
+        claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    } catch (unused) {
+        return null;
+    }
+    const exp = Number(claims == null ? void 0 : claims.exp);
+    if (!Number.isFinite(exp) || exp <= nowMs) return null;
+    if (typeof claims.uid !== 'string' || !claims.uid) return null;
+    return {
+        uid: claims.uid,
+        exp
+    };
+}
+
+//# sourceMappingURL=edit-hint-token.js.map

package/src/lib/server/edit-hint-token.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/edit-hint-token.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createHmac, timingSafeEqual } from 'crypto'\nimport { tokenSigningSecret } from './media-signing'\n\n/**\n * Editor-presence HINT tokens for the tenant admin bar on `*.aglyn.app`\n * (AGL-1842, the cross-site half AGL-1829 could not reach).\n *\n * The console session lives on `app.aglyn.com`; `*.aglyn.app` is a different\n * registrable domain, so neither the AGL-1829 hint cookie nor the silent\n * iframe probe can cross over — storage partitioning keeps the two worlds\n * apart, correctly. What CAN cross is a top-level navigation: at console\n * sign-in the browser is bounced once through\n * `https://console.aglyn.app/api/edit-hint/set?sig=<bounce token>` and back,\n * and in that first-party moment the tenant app plants a signed hint cookie\n * on `Domain=.aglyn.app` that every tenant subdomain can present to its own\n * server afterwards.\n *\n * Two kinds, deliberately non-interchangeable:\n *\n * - `bounce` — rides the redirect URL once. URLs are logged and shareable,\n *   so its TTL is seconds ({@link EDIT_HINT_BOUNCE_TTL_MS}).\n * - `cookie` — the planted `aglyn_edit_hint` value, HttpOnly, living the\n *   {@link EDIT_HINT_COOKIE_TTL_MS} window between console visits.\n *\n * The kind is INSIDE the signed context string, so a leaked 60-second bounce\n * URL can never be replayed as a week-long cookie, and a stolen cookie value\n * can never be planted elsewhere through the bounce endpoint. The `edit-hint:`\n * prefix domain-separates both from the `edit-bar:`/`media:`/commerce\n * signatures sharing `TOKEN_SIGNING_SECRET`.\n *\n * A hint is NOT edit access: it names a uid and nothing else. Everything\n * real happens server-side at the tenant's `/api/edit-access/exchange`,\n * which re-authorizes that uid against the specific host being viewed with\n * the same membership gate the console's token mint applies. A forged,\n * expired, or stale hint costs one refused POST.\n */\n\n/** Seconds, not minutes: the bounce URL is single-use inside one redirect. */\nexport const EDIT_HINT_BOUNCE_TTL_MS = 60 * 1000\n\n/** 7 days — matches the AGL-1829 marker cookie's refresh cadence. */\nexport const EDIT_HINT_COOKIE_TTL_MS = 7 * 24 * 60 * 60 * 1000\n\n/**\n * The HttpOnly signed hint cookie on `Domain=.aglyn.app`. Sibling of the\n * JS-visible `aglyn_editor=1` marker (`EDITOR_HINT_COOKIE`), which the\n * admin-bar stub reads to arm; this one only ever travels back to the\n * tenant's own exchange route, where it is verified server-side.\n */\nexport const EDIT_HINT_COOKIE = 'aglyn_edit_hint'\n\n/** Version tag, mirroring the edit-access token's debuggability rationale. */\nconst TOKEN_PREFIX = 'aglyn-edit-hint-v1'\n\nexport type EditHintKind = 'bounce' | 'cookie'\n\nexport interface EditHintClaims {\n  uid: string\n  /** Expiry, epoch ms. */\n  exp: number\n}\n\nfunction signPayload(kind: EditHintKind, payloadB64: string): string {\n  return createHmac('sha256', tokenSigningSecret())\n    .update(`edit-hint:${kind}:${payloadB64}`)\n    .digest('base64url')\n}\n\nexport interface MintedEditHintToken {\n  token: string\n  expiresAtMs: number\n}\n\n/**\n * Mints a hint of the given kind for a uid the caller has ALREADY verified\n * (the console route verifies a Firebase ID token; the bounce endpoint\n * verifies a `bounce` hint). The mint itself checks nothing.\n */\nexport function mintEditHintToken(\n  kind: EditHintKind,\n  uid: string,\n  nowMs: number = Date.now(),\n): MintedEditHintToken {\n  if (!uid) throw new Error('uid is required')\n  const exp =\n    nowMs +\n    (kind === 'bounce' ? EDIT_HINT_BOUNCE_TTL_MS : EDIT_HINT_COOKIE_TTL_MS)\n  const claims: EditHintClaims = { uid, exp }\n  const payload = Buffer.from(JSON.stringify(claims), 'utf8').toString(\n    'base64url',\n  )\n  return {\n    token: `${TOKEN_PREFIX}.${payload}.${signPayload(kind, payload)}`,\n    expiresAtMs: exp,\n  }\n}\n\n/**\n * Verifies a presented hint AS the stated kind and returns its claims, or\n * `null` for anything else — expired, tampered, malformed, wrong version,\n * wrong KIND (the replay wall), or a deploy with no signing secret (fail\n * closed, like every signature in this family).\n */\nexport function verifyEditHintToken(\n  kind: EditHintKind,\n  token: unknown,\n  nowMs: number = Date.now(),\n): EditHintClaims | null {\n  if (typeof token !== 'string' || token.length === 0 || token.length > 4096) {\n    return null\n  }\n  const parts = token.split('.')\n  if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX) return null\n  const [, payload, sig] = parts\n  let expected: string\n  try {\n    expected = signPayload(kind, payload)\n  } catch {\n    // Secret missing — refuse rather than trusting anything.\n    return null\n  }\n  // Length-checked before timingSafeEqual, which THROWS on attacker-length\n  // input — a 500 where a refusal belongs (same note as edit-access-token).\n  if (sig.length !== expected.length) return null\n  if (\n    !timingSafeEqual(\n      new Uint8Array(Buffer.from(sig)),\n      new Uint8Array(Buffer.from(expected)),\n    )\n  ) {\n    return null\n  }\n  let claims: EditHintClaims\n  try {\n    claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'))\n  } catch {\n    return null\n  }\n  const exp = Number(claims?.exp)\n  if (!Number.isFinite(exp) || exp <= nowMs) return null\n  if (typeof claims.uid !== 'string' || !claims.uid) return null\n  return { uid: claims.uid, exp }\n}\n"],"names":["createHmac","timingSafeEqual","tokenSigningSecret","EDIT_HINT_BOUNCE_TTL_MS","EDIT_HINT_COOKIE_TTL_MS","EDIT_HINT_COOKIE","TOKEN_PREFIX","signPayload","kind","payloadB64","update","digest","mintEditHintToken","uid","nowMs","Date","now","Error","exp","claims","payload","Buffer","from","JSON","stringify","toString","token","expiresAtMs","verifyEditHintToken","length","parts","split","sig","expected","Uint8Array","parse","Number","isFinite"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,EAAEC,eAAe,QAAQ,SAAQ;AACpD,SAASC,kBAAkB,QAAQ,qBAAiB;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GAED,4EAA4E,GAC5E,OAAO,MAAMC,0BAA0B,KAAK,KAAI;AAEhD,mEAAmE,GACnE,OAAO,MAAMC,0BAA0B,IAAI,KAAK,KAAK,KAAK,KAAI;AAE9D;;;;;CAKC,GACD,OAAO,MAAMC,mBAAmB,kBAAiB;AAEjD,4EAA4E,GAC5E,MAAMC,eAAe;AAUrB,SAASC,YAAYC,IAAkB,EAAEC,UAAkB;IACzD,OAAOT,WAAW,UAAUE,sBACzBQ,MAAM,CAAC,CAAC,UAAU,EAAEF,KAAK,CAAC,EAAEC,YAAY,EACxCE,MAAM,CAAC;AACZ;AAOA;;;;CAIC,GACD,OAAO,SAASC,kBACdJ,IAAkB,EAClBK,GAAW,EACXC,QAAgBC,KAAKC,GAAG,EAAE;IAE1B,IAAI,CAACH,KAAK,MAAM,IAAII,MAAM;IAC1B,MAAMC,MACJJ,QACCN,CAAAA,SAAS,WAAWL,0BAA0BC,uBAAsB;IACvE,MAAMe,SAAyB;QAAEN;QAAKK;IAAI;IAC1C,MAAME,UAAUC,OAAOC,IAAI,CAACC,KAAKC,SAAS,CAACL,SAAS,QAAQM,QAAQ,CAClE;IAEF,OAAO;QACLC,OAAO,GAAGpB,aAAa,CAAC,EAAEc,QAAQ,CAAC,EAAEb,YAAYC,MAAMY,UAAU;QACjEO,aAAaT;IACf;AACF;AAEA;;;;;CAKC,GACD,OAAO,SAASU,oBACdpB,IAAkB,EAClBkB,KAAc,EACdZ,QAAgBC,KAAKC,GAAG,EAAE;IAE1B,IAAI,OAAOU,UAAU,YAAYA,MAAMG,MAAM,KAAK,KAAKH,MAAMG,MAAM,GAAG,MAAM;QAC1E,OAAO;IACT;IACA,MAAMC,QAAQJ,MAAMK,KAAK,CAAC;IAC1B,IAAID,MAAMD,MAAM,KAAK,KAAKC,KAAK,CAAC,EAAE,KAAKxB,cAAc,OAAO;IAC5D,MAAM,GAAGc,SAASY,IAAI,GAAGF;IACzB,IAAIG;IACJ,IAAI;QACFA,WAAW1B,YAAYC,MAAMY;IAC/B,EAAE,eAAM;QACN,yDAAyD;QACzD,OAAO;IACT;IACA,yEAAyE;IACzE,0EAA0E;IAC1E,IAAIY,IAAIH,MAAM,KAAKI,SAASJ,MAAM,EAAE,OAAO;IAC3C,IACE,CAAC5B,gBACC,IAAIiC,WAAWb,OAAOC,IAAI,CAACU,OAC3B,IAAIE,WAAWb,OAAOC,IAAI,CAACW,aAE7B;QACA,OAAO;IACT;IACA,IAAId;IACJ,IAAI;QACFA,SAASI,KAAKY,KAAK,CAACd,OAAOC,IAAI,CAACF,SAAS,aAAaK,QAAQ,CAAC;IACjE,EAAE,eAAM;QACN,OAAO;IACT;IACA,MAAMP,MAAMkB,OAAOjB,0BAAAA,OAAQD,GAAG;IAC9B,IAAI,CAACkB,OAAOC,QAAQ,CAACnB,QAAQA,OAAOJ,OAAO,OAAO;IAClD,IAAI,OAAOK,OAAON,GAAG,KAAK,YAAY,CAACM,OAAON,GAAG,EAAE,OAAO;IAC1D,OAAO;QAAEA,KAAKM,OAAON,GAAG;QAAEK;IAAI;AAChC"}

package/src/lib/server/email-delivery-log.d.ts

@@ -0,0 +1,509 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type EmailDeliveryEvent, type EmailDeliveryEventType, type EmailDeliveryHistorySource, type EmailDeliverySnapshot } from '@aglyn/shared-util-email';
+export declare const EMAIL_DELIVERIES_COLLECTION = "emailDeliveries";
+export declare const EMAIL_DELIVERY_MESSAGES_COLLECTION = "messages";
+/** The most messages one staff read will return. */
+export declare const EMAIL_DELIVERY_READ_LIMIT = 50;
+/**
+ * The most distinct links one message records.
+ *
+ * A newsletter with forty links clicked by one reader must not grow the
+ * document without bound; the first few tell a staffer what they need.
+ */
+export declare const EMAIL_DELIVERY_MAX_LINKS = 10;
+/** One message as the staff view reads it. */
+export interface EmailDeliveryRecord {
+    /** The provider's message id — also the document id. */
+    messageId: string;
+    provider: string;
+    to: string;
+    subject: string | null;
+    /** The sender label, e.g. `'invite'`. Null for a send that carried none. */
+    context: string | null;
+    /** Furthest-along (worst) lifecycle state seen. */
+    status: EmailDeliveryEventType;
+    /** Epoch ms per state, absent for states that never happened. */
+    timestamps: Partial<Record<EmailDeliveryEventType, number>>;
+    /** First event we saw for this message. Always present — the sort key. */
+    firstSeenAtMs: number;
+    openCount: number;
+    clickCount: number;
+    /** Distinct destinations followed, capped. */
+    clickedLinks: string[];
+    bounceType: string | null;
+    detail: string | null;
+    hostId: string | null;
+    campaignId: string | null;
+}
+/**
+ * What one {@link recordEmailDeliveryEvent} call did.
+ *
+ * `firstOfType` exists so a CAMPAIGN counter can be incremented once per
+ * recipient without buying a read of its own. This transaction already holds
+ * the message's prior state, and "has this message ever been opened before"
+ * is the fact a distinct-openers count needs — deriving it here costs
+ * nothing, and deriving it anywhere else costs a document read per event.
+ *
+ * It is also what makes those counters idempotent, on the same reasoning the
+ * webhook's replay guard rests on: a redelivered or replayed event finds the
+ * state already recorded and reports `false`, so the counter cannot be
+ * incremented twice for one message's first open.
+ */
+export interface EmailDeliveryEventOutcome {
+    /**
+     * No event of this TYPE had been recorded against this message before.
+     *
+     * Read off `timestamps`, which is written for every event type, rather than
+     * off `openCount`/`clickCount`, which exist for two of them.
+     */
+    firstOfType: boolean;
+    /** The message this event was recorded against. */
+    providerMessageId: string;
+    /** The recipient, lowercased — the person the event is about. */
+    to: string;
+    /** Which event this was. */
+    type: EmailDeliveryEventType;
+    /** When it happened, epoch ms. */
+    at: number;
+}
+/**
+ * Records one normalized event against its message.
+ *
+ * A transaction rather than a merge-set, for one property that matters to the
+ * reader: `firstSeenAtMs` must be written exactly once and must never be
+ * absent. Events arrive out of order — an `opened` can beat its own `sent`
+ * through the queue — so "create with the first event's time, then leave it
+ * alone" needs a read in the same atomic step as the write. A document missing
+ * that field would be dropped from the `orderBy` read entirely and the message
+ * would simply not appear, which is the failure mode a delivery log can least
+ * afford.
+ *
+ * @returns the outcome, or `null` when nothing was written. `null` is the
+ *          ordinary answer for an address that is not an address; it is never
+ *          an error.
+ */
+export declare function recordEmailDeliveryEvent(event: EmailDeliveryEvent, firestore?: any): Promise<EmailDeliveryEventOutcome | null>;
+/**
+ * Records one message the PROVIDER already knows about — the history import.
+ *
+ * ## Why this is not just `recordEmailDeliveryEvent` with a made-up event
+ *
+ * A snapshot is weaker evidence than an event, in two specific ways, and
+ * writing it as an event would silently promote it:
+ *
+ *  - **It carries no counts.** A provider's list reports one `last_event` per
+ *    message and no engagement detail, so `opened` means "at least once" and
+ *    can never mean "three times". Incrementing `openCount` from a snapshot
+ *    would invent a number, and re-running the import would invent it again.
+ *  - **It can be STALER than what we already hold.** The event feed is live;
+ *    an import is a page of results fetched some time ago. So the status is
+ *    merged with {@link worstDeliveryStatus} rather than assigned, and a row
+ *    the webhook has already advanced is never walked backwards.
+ *
+ * Everything else it fills is a gap-fill only: `subject` and `sentAt` are
+ * written when absent and left alone when present. The net effect is that
+ * importing history is idempotent and can be run as often as you like, and a
+ * message the event feed has covered is untouched by it.
+ *
+ * `context` is deliberately NOT recoverable here. It comes from a send tag,
+ * and the list endpoint does not return tags — so an imported row shows the
+ * subject and the status but cannot say which of our senders produced it. The
+ * card renders that absence rather than guessing.
+ *
+ * @returns whether a row was written or updated.
+ */
+export declare function recordEmailDeliverySnapshot(snapshot: EmailDeliverySnapshot, firestore?: any): Promise<boolean>;
+/**
+ * Records a batch, independently — one bad event must not lose the others.
+ *
+ * @returns one outcome per event that was WRITTEN; events that wrote nothing
+ *          are absent, so the length is still the count the old return value
+ *          reported.
+ */
+export declare function recordEmailDeliveryEvents(events: EmailDeliveryEvent[], firestore?: any): Promise<EmailDeliveryEventOutcome[]>;
+/** What one person's mail says about whether they are still listening. */
+export interface EmailPersonEngagement {
+    /** The later of {@link lastOpenedAtMs} and {@link lastClickedAtMs}. */
+    lastEngagedAtMs: number | null;
+    lastOpenedAtMs: number | null;
+    /**
+     * Clicks are the metric to lean on. Apple's Mail Privacy Protection
+     * prefetches images, so an open is partly a statement about the recipient's
+     * mail client; a click is a statement about the recipient.
+     */
+    lastClickedAtMs: number | null;
+}
+/** The empty answer, so a caller never has to invent one. */
+export declare const NO_PERSON_ENGAGEMENT: EmailPersonEngagement;
+/**
+ * Advances the engagement stamps for the people these outcomes are about.
+ *
+ * A transaction, and it buys exactly one property: the stamps only ever move
+ * FORWARD. Provider events are not ordered, and a replay of an event whose
+ * first delivery never landed can carry an instant from months ago — a blind
+ * merge-set would let that overwrite a fresh stamp and quietly make an active
+ * subscriber look cold to a control whose whole job is refusing to mail cold
+ * people. Reading before writing is a cheaper unit than the write beside it,
+ * and it happens at most once per message per event type.
+ *
+ * Never throws, for the same reason nothing else in this file does: a rollup
+ * that failed loses a stamp, and a rollup that threw would lose the webhook's
+ * acknowledgement and teach the provider to retry the whole event.
+ *
+ * @returns how many person documents were written.
+ */
+export declare function recordPersonEngagement(outcomes: readonly EmailDeliveryEventOutcome[], firestore?: any): Promise<number>;
+/**
+ * One person's engagement, by address. Never throws.
+ *
+ * Returns {@link NO_PERSON_ENGAGEMENT} for an address we hold nothing about,
+ * AND for a read that failed. The two are deliberately the same answer here:
+ * every caller uses this to decide whether to REFUSE something, and both
+ * readings must resolve to "we have no evidence this person is cold", which
+ * is the only safe direction for a control that stops mail.
+ */
+export declare function readPersonEngagement(email: string | null | undefined, firestore?: any): Promise<EmailPersonEngagement>;
+/**
+ * Engagement for many people at once, keyed by their person key.
+ *
+ * A `getAll` rather than a query: these are keyed document reads, so this
+ * needs no index, cannot be truncated by a `limit`, and cannot drop somebody
+ * for missing a field the way an `orderBy` would. The audience materializer
+ * calls it a page at a time and counts every read against its scan budget.
+ *
+ * A key with no document is present in the result with
+ * {@link NO_PERSON_ENGAGEMENT}, so a caller never has to tell "absent" from
+ * "not read" — and a failure returns every requested key that way for the
+ * same reason {@link readPersonEngagement} does.
+ */
+export declare function readPersonEngagementByKeys(keys: readonly string[], firestore?: any): Promise<Map<string, EmailPersonEngagement>>;
+/** The field on `emailDeliveries/{key}` holding the per-host touches. */
+export declare const EMAIL_TOUCH_FIELD = "campaignTouches";
+/**
+ * How many sites' touches one person's document keeps.
+ *
+ * A cap, not a page size: the map lives in a document with a 1 MiB ceiling
+ * and nothing else bounds how many sites may mail one address.
+ */
+export declare const EMAIL_TOUCH_MAX_HOSTS = 10;
+/** The last campaign one person clicked on one site. */
+export interface EmailCampaignTouch {
+    hostId: string;
+    campaignId: string;
+    /** When the click happened, epoch ms — the provider's instant. */
+    clickedAtMs: number;
+}
+/**
+ * Records that this person clicked this campaign's mail. Never throws.
+ *
+ * Forward-only, in a transaction, for the reason {@link recordPersonEngagement}
+ * is: provider delivery is at-least-once and unordered, so a replayed click
+ * from last month must not displace this week's. That same property is what
+ * makes this idempotent — a redelivered event finds its own instant already
+ * stored and writes nothing.
+ *
+ * @returns whether the touch moved forward.
+ */
+export declare function recordEmailCampaignTouch(touch: {
+    email: string | null | undefined;
+    hostId: string;
+    campaignId: string;
+    atMs: number;
+}, firestore?: any): Promise<boolean>;
+/**
+ * The last campaign this person clicked on this site, or `null`.
+ *
+ * One keyed document read — no query, no index, and nothing that can be
+ * truncated. `null` for an address we hold no touch for AND for a read that
+ * failed, which are the same answer on purpose: both mean "we cannot say
+ * which campaign preceded this order", and the only safe thing to do with
+ * that is credit nobody.
+ */
+export declare function readEmailCampaignTouch(email: string | null | undefined, hostId: string, firestore?: any): Promise<EmailCampaignTouch | null>;
+/** What one {@link importEmailDeliveryHistory} run did. */
+export interface EmailDeliveryImportResult {
+    /** Provider messages read. */
+    scanned: number;
+    /** Per-recipient rows written or refreshed. */
+    recorded: number;
+    pages: number;
+    /** Cursor to resume from, or null when the history was exhausted. */
+    nextCursor: string | null;
+    /** True when the page budget ran out before the history did. */
+    truncated: boolean;
+}
+/** Default page budget for one import run. 100 messages per page. */
+export declare const EMAIL_DELIVERY_IMPORT_MAX_PAGES = 20;
+/**
+ * Imports already-sent mail from a provider into the log.
+ *
+ * Bounded by PAGES rather than run to completion: this is called from a
+ * request handler, and an account with a large history would otherwise hold
+ * one open until it timed out — losing every page it had already written,
+ * because a partial import that reports nothing is indistinguishable from one
+ * that did nothing. Instead it stops at the budget, returns `nextCursor`, and
+ * the caller resumes. Every page is written before the next is fetched, so an
+ * interrupted run keeps its work.
+ *
+ * Idempotent by construction — see {@link recordEmailDeliverySnapshot}: a
+ * message the event feed already covered is not walked backwards, and
+ * re-running invents no counts.
+ *
+ * The `source` is injected rather than constructed here. This module may not
+ * know which provider is in use, and a test must be able to run the whole
+ * loop — pagination, cursor handling, the stop condition — without a network.
+ */
+export declare function importEmailDeliveryHistory(options: {
+    source: EmailDeliveryHistorySource;
+    cursor?: string | null;
+    maxPages?: number;
+    firestore?: any;
+}): Promise<EmailDeliveryImportResult>;
+/**
+ * The messages sent to one address, newest first.
+ *
+ * Ordered on `firstSeenAtMs`, which the writer guarantees on creation, rather
+ * than on a per-state timestamp that only some rows carry: `orderBy` drops
+ * every document missing the field, so ordering on `timestamps.sent` would
+ * silently hide any message whose `sent` webhook never arrived — exactly the
+ * message a staffer is looking for.
+ *
+ * @returns the rows, or an empty array. The caller distinguishes "none" from
+ *          "could not read" through {@link readEmailDeliveryHistory}.
+ */
+export declare function readEmailDeliveries(email: string | null | undefined, options?: {
+    limit?: number;
+    firestore?: any;
+}): Promise<EmailDeliveryRecord[]>;
+/**
+ * {@link readEmailDeliveries} with the read failure kept separate from an
+ * empty result.
+ *
+ * The same shape `devices` uses on the staff detail route, for the same
+ * reason: "we have no record of any email to this person" and "we could not
+ * reach the log" lead a staffer to opposite next actions, and a card that
+ * renders both as an empty table sends them down the wrong one.
+ */
+export declare function readEmailDeliveryHistory(email: string | null | undefined, options?: {
+    limit?: number;
+    firestore?: any;
+}): Promise<{
+    lookupFailed: boolean;
+    rows: EmailDeliveryRecord[];
+}>;
+/** The most recipient rows one campaign-engagement read returns. */
+export declare const EMAIL_CAMPAIGN_ENGAGEMENT_PAGE_SIZE = 25;
+/**
+ * How many campaigns one engagement read can span.
+ *
+ * Firestore's `in` operator takes at most 30 values, and the query below runs
+ * as a merge of one sub-query per value — so this is a hard limit of the
+ * store rather than a number worth tuning. A design used by more campaigns
+ * than this reads its most recent 30, and the caller is told so.
+ */
+export declare const EMAIL_CAMPAIGN_ENGAGEMENT_MAX_CAMPAIGNS = 30;
+/** Which recipients a campaign-engagement read returns. */
+export type EmailEngagementFilter = 'all' | 'opened' | 'clicked';
+/** One page of recipient rows. */
+export interface EmailCampaignEngagementPage {
+    rows: EmailDeliveryRecord[];
+    /**
+     * Cursor for the next page, or null at the end.
+     *
+     * The full document PATH of the last row, which is
+     * `emailDeliveries/{sha256(address)}/messages/{messageId}`. It is re-read
+     * as a snapshot to resume the query, rather than resuming from the ordered
+     * VALUE: a value cursor positions after every document sharing it, so two
+     * messages recorded in the same millisecond would lose one of them between
+     * pages — silently, and only under load.
+     */
+    cursor: string | null;
+    /** The read failed, as distinct from finding nothing. */
+    lookupFailed: boolean;
+    /** Campaigns past {@link EMAIL_CAMPAIGN_ENGAGEMENT_MAX_CAMPAIGNS}. */
+    campaignsOmitted: number;
+}
+/**
+ * The recipients of one site's campaigns, newest message first.
+ *
+ * ## What each filter orders on, and why it is not one query with a flag
+ *
+ * `all` orders on `firstSeenAtMs`, which {@link recordEmailDeliveryEvent}
+ * guarantees on creation. `opened` and `clicked` carry an inequality —
+ * `openCount > 0` — and Firestore requires the first ordering to be on the
+ * inequality's own field, so those two order on the count and then on the
+ * time. That is not a workaround: a message never opened has no `openCount`
+ * field at all, so the inequality is also what excludes it, and the ordering
+ * puts the most engaged recipient first, which is the order a merchant reads
+ * such a table in.
+ *
+ * ## Never throws
+ *
+ * Same contract as the rest of this file: `lookupFailed` distinguishes a read
+ * that could not run — a missing index is the likely one — from a campaign
+ * nobody opened. Rendering those two the same way is how a merchant concludes
+ * their campaign reached nobody.
+ */
+export declare function readCampaignEngagement(options: {
+    /** The site whose mail this is. The caller must already have proven it. */
+    hostId: string;
+    /** Campaign ids to read, most recent first. */
+    campaignIds: readonly string[];
+    filter?: EmailEngagementFilter;
+    limit?: number;
+    /** A `cursor` from a previous page. */
+    cursor?: string | null;
+    firestore?: any;
+}): Promise<EmailCampaignEngagementPage>;
+/**
+ * A record that delivery data WAS held for an address and has been erased.
+ *
+ * Written into the parent `emailDeliveries/{emailKey}` document, which the
+ * messages subcollection otherwise leaves empty.
+ *
+ * ⚠️ It carries no address, no subject, no message id and no uid — nothing
+ * the erasure was performed to destroy. `count` is a magnitude, which is what
+ * makes the row honest without reconstituting anything: it says data existed
+ * and is gone, and nothing about what it was.
+ */
+export interface EmailDeliveryErasure {
+    /** Epoch ms. */
+    at: number;
+    /** How many messages were removed. */
+    count: number;
+}
+/** One account's mail, gathered from every address it holds. */
+export interface EmailDeliveryHistory {
+    lookupFailed: boolean;
+    rows: EmailDeliveryRecord[];
+    /**
+     * The addresses actually read, in the order they were given.
+     *
+     * The card names them. A staffer looking at mail sent to an address that is
+     * no longer this account's primary has to be able to see that that is what
+     * they are looking at.
+     */
+    addressesRead: string[];
+    /**
+     * Erasure tombstones found, keyed by address.
+     *
+     * An address whose records were erased under somebody's request reads as an
+     * empty table otherwise — which is the precise failure this card's copy
+     * warns about, recreated by the fix for it.
+     */
+    erasures: Record<string, EmailDeliveryErasure>;
+}
+/** The tombstone on one address, or null. Never throws. */
+export declare function readEmailDeliveryErasure(email: string | null | undefined, firestore?: any): Promise<EmailDeliveryErasure | null>;
+/**
+ * Every message sent to any address this account holds, newest first.
+ *
+ * Merged and re-sorted rather than concatenated: the rows are one person's
+ * mail and a staffer reads them as a timeline, so grouping them by which
+ * address happened to receive them would put the answer in two places and
+ * make "what was the last thing we sent them" a question about two tables.
+ * Each row keeps its own `to`, so the card can still say which address.
+ *
+ * `lookupFailed` is true when ANY address failed. A partial read of a
+ * delivery log is the same hazard as an empty one — it under-reports mail we
+ * sent — and reporting it as a clean result is how a staffer comes to tell a
+ * customer something untrue.
+ */
+export declare function readEmailDeliveryHistoryForAddresses(addresses: readonly string[], options?: {
+    limit?: number;
+    firestore?: any;
+}): Promise<EmailDeliveryHistory>;
+/** What one multi-address erasure did. */
+export interface EmailDeliveryErasureResult {
+    /** Messages removed, across every address that was erased. */
+    removed: number;
+    /** The addresses actually erased. Tombstoned, one document each. */
+    addresses: string[];
+    /**
+     * Addresses left INTACT because another account is also known to hold them.
+     *
+     * Never empty and ignorable: a caller erasing an account has to treat a
+     * non-empty list as an erasure it did not finish. See
+     * {@link eraseEmailDeliveriesForAddresses}.
+     */
+    contestedAddresses: string[];
+}
+/**
+ * Erase the delivery log for every address an account holds, except the ones
+ * a second account also holds.
+ *
+ * ## The shared-address decision
+ *
+ * The log describes an ADDRESS, not an account. Where one account holds an
+ * address, erasing it is simply erasing the subject's mail, and this sweeps
+ * it.
+ *
+ * Where TWO accounts hold one address, the same rows are two people's answer
+ * to "what did you send me", and the two readings are incompatible:
+ *
+ *  - **One human, two accounts** — the ordinary live shape, an account whose
+ *    federated provider address is another account's primary. Erasing is
+ *    right; the mail is the requester's.
+ *  - **A genuinely shared mailbox** — `billing@`, `support@`, a role account
+ *    two different people hold. Erasing destroys the second person's delivery
+ *    history for an address they legitimately hold, and they asked for
+ *    nothing.
+ *
+ * ⛔ **Nothing here can tell those apart.** The difference is a fact about the
+ * humans, and the data holds no fact about the humans — only that two account
+ * records name one address. So this function does not choose. It erases what
+ * it can decide about and reports the rest as CONTESTED, and `eraseUser`
+ * refuses the whole erasure rather than half-perform one: destroying the
+ * second party's mail has no remedy, and quietly leaving it while reporting
+ * the erasure complete is the gap this area exists to close. Refusing is the
+ * only outcome that is neither, and it is reversible — a human decides which
+ * reading applies, detaches the address or confirms the account, and the
+ * erasure runs.
+ *
+ * ⚠️ A contested address is not tombstoned. The tombstone means "the records
+ * here were removed under an erasure request", and writing one over rows that
+ * are still present would tell the second holder their mail is gone while it
+ * sits underneath — a worse misreading than the blank table, because it is
+ * confidently wrong rather than merely empty. Nothing was removed, so their
+ * card renders their mail exactly as before.
+ *
+ * ⚠️ `shared` is one-directional evidence. True proves a second holder; false
+ * only means none was found, because there is no lookup for an account
+ * holding an address through a federated provider (see
+ * `account-addresses.ts`). So the tombstone is still written for EVERY
+ * address that IS erased, not only ones believed unshared — it costs one
+ * small document and closes the case where a second holder exists behind the
+ * gap in the probe and would otherwise meet a blank table.
+ *
+ * ⛔ Only addresses the account HOLDS, resolved through the one resolver. An
+ * address arriving here that the account does not hold erases a stranger's
+ * mail, which no erasure request authorises.
+ */
+export declare function eraseEmailDeliveriesForAddresses(addresses: readonly {
+    address: string;
+    shared?: boolean;
+}[], firestore?: any): Promise<EmailDeliveryErasureResult>;
+/**
+ * Deletes everything recorded for one address.
+ *
+ * The log holds an address, the subjects sent to it and when they were opened
+ * — personal data by any reading — so the erasure path has to be able to reach
+ * it. Batched because a long-lived account can hold hundreds of rows and a
+ * single `delete()` per document would be one round trip each.
+ */
+export declare function eraseEmailDeliveries(email: string | null | undefined, firestore?: any): Promise<number>;