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

package/src/lib/server/email-marketing-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/email-marketing-gate.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\n/**\n * MARKETING MAIL — the durable half.\n *\n * `marketing-send.ts` in `@aglyn/shared-util-email` states the policy and\n * holds the injection seam; this answers the question, because answering it\n * needs Firestore and that library may not hold the Admin SDK.\n *\n * Five things, in the order they cost:\n *\n *  1. **Both suppression lists**, through the one shared helper. A person who\n *     unsubscribed from this site, hard-bounced anywhere in the product, or\n *     pressed \"report spam\" is not mailed. Asked first because it is the only\n *     one whose answer is permanent.\n *  2. **The pace the RECIPIENT asked for** on the preference page, if they\n *     asked for one.\n *  3. **An engagement sunset**, when an operator has configured a window —\n *     off by default, and it costs a read only when it is on.\n *  4. **A frequency ceiling**, per recipient per site, over a rolling day.\n *  5. **The signed unsubscribe URL**, so the message carries a way out.\n *\n * ## The order of the three pace refusals, and who each one is for\n *\n * Suppression is first and needs no argument: its answer is permanent, and\n * the frequency record must not count a message that was never going to\n * leave. The other three are all refusals about PACE, and they are ordered by\n * whose refusal it is, then by what asking costs.\n *\n * **The recipient's own cadence is second — above both platform controls.**\n * It is the only one of the three a PERSON asked for; the sunset is an\n * inference this platform drew about them and the ceiling is a guard against\n * the merchant. When more than one applies, the honest answer to \"why did\n * this not send\" is the fact somebody stated, not the guess we made. It is\n * also the cheapest to ask: it is already on the counter document the ceiling\n * reads, so a recipient who asked for monthly mail never pays for the\n * sunset's engagement read. And it is the only one that binds a campaign, so\n * putting it first makes the campaign path and the automated paths evaluate\n * the same refusals in the same order rather than interleaving one control a\n * campaign skips with one it does not.\n *\n * **The sunset is third, above the ceiling.** Its refusal is TERMINAL and the\n * ceiling's is not: a sweep defers a `frequency-capped` message and retries\n * it, so reporting the retryable refusal for a person the sunset would refuse\n * anyway means the same doomed row comes back on every beat. That argument\n * does not reach past the cadence, because a cadence gap is a day, a week or\n * a month — a sweep retries such a row once per interval, not once per beat.\n *\n * ## Which refusals bind a campaign\n *\n * `MarketingSendContext.capped` is `false` for a campaign, and it governs\n * exactly two of the four:\n *\n * | Refusal            | A campaign is |\n * | ------------------ | ------------- |\n * | `suppressed`       | **bound** |\n * | `cadence-limited`  | **bound** |\n * | `unengaged`        | exempt (`capped`) |\n * | `frequency-capped` | exempt (`capped`) |\n *\n * The two exemptions share one reason: a campaign is a merchant's reviewed,\n * one-shot act with a recipient count on screen before they press Send, and a\n * platform control that silently removed people from that number would make\n * it a lie. That reason is about a control the merchant did not ask for and\n * cannot see. It does not reach a request the RECIPIENT made — a campaign\n * that overrode the preference page would make it a form recording a choice\n * nothing honors, which is ignoring an unsubscribe one notch quieter.\n *\n * A campaign COUNTS toward the ceiling either way; it is exempt from the\n * refusal, never from the counting.\n *\n * ## The counter is a WINDOW, not a total\n *\n * `hosts/{hostId}/emailFrequency/{sha256(address)}` holds the instants of the\n * marketing messages this site sent this person, trimmed to the window on\n * every touch. A rolling window needs the instants; a running total would\n * need a reset nobody triggers, and a per-day bucket would let a merchant\n * send the whole ceiling at 23:55 and the whole ceiling again at 00:05.\n *\n * The record is bounded by the cap — a handful of numbers — because\n * `marketingFrequencyVerdict` returns the trimmed window and this writes back\n * only that. It is server-owned: the address is hashed exactly as the two\n * suppression lists hash it, and no client writes or reads it.\n *\n * ## The check and the write are not one transaction, on purpose\n *\n * Two concurrent marketing sends to the same person can both read a window\n * with room and both append, so the cap can be exceeded by the number of\n * messages genuinely in flight at that instant. That is accepted rather than\n * papered over: a transaction per recipient would double the round trips on a\n * path that is already one awaited HTTP POST per person, and being off by one\n * on a runaway guard costs a recipient one extra message. Being slow costs\n * every recipient.\n *\n * ## Never a reduction of the person or their data\n *\n * A cap here refuses a SEND. It never removes a contact, never unsubscribes\n * anybody, never trims an audience and never deletes a counter row belonging\n * to somebody. `over-limit.ts` states the rule for capacity limits and this is\n * the same instrument pointed at time: the message does not go, the person\n * stays exactly where they were, and the next window mails them again. The\n * recipient's own cadence is the same shape — a person who asked for monthly\n * mail stays on every audience they were on and is mailed again next month.\n */\n\nimport {\n  getMarketingSendGate,\n  marketingCadenceVerdict,\n  marketingFrequencyVerdict,\n  marketingSunsetDays,\n  marketingSunsetVerdict,\n  normalizeMarketingCadence,\n  setMarketingSendGate,\n  type MarketingCadence,\n  type MarketingSendGateRequest,\n  type MarketingSendGateVerdict,\n} from '@aglyn/shared-util-email'\nimport firebaseAdmin from './firebase-admin'\nimport { readPersonEngagement } from './email-delivery-log'\nimport {\n  emailSuppressionKey,\n  filterSendableForHost,\n  filterTopicSendable,\n} from './email-suppression'\nimport { buildUnsubscribeUrl } from './email-unsubscribe-link'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/**\n * Where the per-recipient window lives.\n *\n * Under the host rather than the org: the ceiling is \"how much mail this SITE\n * sends one person\", which is the unit a recipient experiences and the unit\n * the unsubscribe link is scoped to. An org-wide counter would let one site's\n * newsletter suppress a sibling site's order-related marketing, and the two\n * sites may be unrelated brands.\n */\nexport const EMAIL_FREQUENCY_SUBCOLLECTION = 'emailFrequency'\n\n/** How each cadence reads inside a refusal sentence. */\nconst CADENCE_PHRASES: Record<MarketingCadence, string> = {\n  all: 'at this pace',\n  daily: 'a day',\n  weekly: 'a week',\n  monthly: 'a month',\n}\n\n/** The stored window. */\nexport interface EmailFrequencyRecord {\n  /** The address, in the clear, lowercased. The id is its hash. */\n  email: string\n  /** Marketing send instants, trimmed to the window on every touch. */\n  sentAtMs: number[]\n  /**\n   * When this site FIRST sent this person marketing mail.\n   *\n   * Written once and never again, and it rides here rather than in a store of\n   * its own because this document is already written on every marketing send:\n   * carrying the field costs nothing, and a second per-recipient document\n   * would be a write per send per person for one number.\n   *\n   * The sunset is what reads it — see `marketingSunsetVerdict`. A person we\n   * have not been mailing for longer than the sunset window cannot have been\n   * quiet for longer than the sunset window, so this is the field that keeps\n   * a new subscriber from being refused for having nothing on record yet.\n   *\n   * Null for every row written before this field existed, which reads as \"no\n   * record\" and therefore refuses nobody. That is the conservative direction\n   * for a field introduced after the data, and it self-heals: the row gains\n   * the stamp on this site's next marketing send to that person, and the\n   * clock starts from then rather than from a past nobody recorded.\n   */\n  firstSentAtMs?: number\n  /**\n   * The most recent marketing send, NEVER trimmed.\n   *\n   * `sentAtMs` is a rolling day, so after a quiet day it is empty and cannot\n   * answer \"when did this site last mail this person\" — which is the only\n   * question a weekly or monthly cadence asks. One number rather than a\n   * window kept for a month.\n   *\n   * The bookends of the same relationship: `firstSentAtMs` never moves and\n   * this one moves on every send, so between them they answer both \"how long\n   * have we been mailing this person\" and \"how long since we last did\".\n   */\n  lastSentAtMs?: number\n  /**\n   * How often the RECIPIENT asked to hear from this site.\n   *\n   * Stored on the counter document rather than beside the topic opt-outs, and\n   * that is the whole reason it costs nothing: the gate already reads this\n   * document on every marketing message, so honoring the preference adds no\n   * round trip to any send. It also puts the preference in the one document\n   * that is already about how much mail this site sends this person.\n   *\n   * Absent on every record written before it existed, which reads as no\n   * expressed preference — see `normalizeMarketingCadence`.\n   */\n  cadence?: MarketingCadence\n  /** When the recipient chose it, for the record that the request was made. */\n  cadenceSetAtMs?: number\n}\n\n/**\n * What one recipient's counter document says, with its defaults applied.\n *\n * Everything the gate asks of Firestore about this person on this site, in\n * one shape, because it is fetched in one round trip — see\n * {@link readMarketingFrequencyState}.\n */\nexport interface MarketingFrequencyState {\n  /** Send instants inside the rolling window. */\n  window: number[]\n  /** When this site first mailed them, or `null` for no record. */\n  firstSentAtMs: number | null\n  /** The most recent send, or `null` for somebody never mailed. */\n  lastSentAtMs: number | null\n  /** The recipient's chosen pace. */\n  cadence: MarketingCadence\n}\n\n/** What an unreadable, absent or unkeyable counter reads as. */\nconst NO_RECORD: MarketingFrequencyState = {\n  window: [],\n  firstSentAtMs: null,\n  lastSentAtMs: null,\n  cadence: 'all',\n}\n\n/**\n * One counter snapshot, decoded.\n *\n * Shared by {@link readMarketingFrequencyState} and\n * {@link filterCadenceSendable} so the two cannot come to different\n * conclusions about the same document — in particular about the\n * `lastSentAtMs` fallback, where a per-message answer and a per-campaign\n * answer that disagreed would refuse a recipient on one path and mail them on\n * the other.\n */\nfunction stateFromSnapshot(snapshot: any): MarketingFrequencyState {\n  const stored = snapshot.get('sentAtMs')\n  const window = Array.isArray(stored)\n    ? stored.map((at: unknown) => Number(at))\n    : []\n  const first = Number(snapshot.get('firstSentAtMs'))\n  const last = Number(snapshot.get('lastSentAtMs'))\n  return {\n    window,\n    firstSentAtMs: Number.isFinite(first) && first > 0 ? first : null,\n    /*\n     * The stored instant, or the newest entry still inside the window.\n     *\n     * The fallback is what makes this work on every record written before\n     * `lastSentAtMs` existed: those carry a window and nothing else, and\n     * reading `null` for them would let a monthly cadence pass on the first\n     * message after this ships for anybody mailed in the last day.\n     *\n     * `firstSentAtMs` deliberately has NO such fallback. The window would be\n     * the wrong answer for it in exactly the direction that matters: a\n     * relationship dated from a send inside the last day is younger than any\n     * sunset window, so the sunset could never fire — and a relationship\n     * dated from the oldest entry in a rolling DAY is not the first send\n     * either. Absent means \"no record\", and no record refuses nobody.\n     */\n    lastSentAtMs: Number.isFinite(last)\n      ? last\n      : window.length\n        ? Math.max(...window)\n        : null,\n    cadence: normalizeMarketingCadence(snapshot.get('cadence')),\n  }\n}\n\nfunction frequencyDoc(\n  hostId: string,\n  emailKey: string,\n  firestore?: any,\n): FirebaseFirestore.DocumentReference {\n  return (firestore ?? defaultFirestore())\n    .collection('hosts')\n    .doc(hostId)\n    .collection(EMAIL_FREQUENCY_SUBCOLLECTION)\n    .doc(emailKey)\n}\n\n/**\n * The instants inside the window for one recipient of one site's mail.\n *\n * FAILS OPEN — an empty window, meaning \"nothing recorded, so there is room\".\n * The opposite of {@link filterSendableForHost}, and the difference is what\n * each answer costs when it is wrong. A suppression read that fails open\n * mails somebody who told us to stop; a frequency read that fails closed\n * refuses a message nobody objected to, over a counter that is a runaway\n * guard rather than a consent record.\n */\nexport async function readMarketingFrequency(\n  hostId: string,\n  email: string,\n  firestore?: any,\n): Promise<number[]> {\n  return (await readMarketingFrequencyState(hostId, email, firestore)).window\n}\n\n/**\n * The whole counter document — the window, the first send, the last send and\n * the recipient's chosen pace — in ONE round trip.\n *\n * **One read, four facts, and that is a requirement rather than a tidiness.**\n * Three separate refusals in {@link marketingSendVerdict} read this document,\n * and a `get` per refusal would be three awaited round trips on a path that\n * is already one awaited HTTP POST per recipient. Which is also why the\n * recipient's cadence is stored HERE rather than beside the topic opt-outs:\n * honoring a preference this gate has to consult on every marketing message\n * has to cost nothing, and riding on a document already being read is the\n * only shape that does. See {@link EmailFrequencyRecord.cadence}.\n *\n * FAILS OPEN on every field, and in the same direction each time: an empty\n * window means \"there is room\", a null `firstSentAtMs` means \"no record\", a\n * null `lastSentAtMs` means \"never mailed\", and an unreadable cadence reads\n * as no preference expressed. An unreadable counter is not evidence that\n * somebody asked for less, and it is not evidence that they have gone cold —\n * the opposite of {@link filterSendableForHost}, for the reason\n * {@link readMarketingFrequency} states.\n */\nexport async function readMarketingFrequencyState(\n  hostId: string,\n  email: string,\n  firestore?: any,\n): Promise<MarketingFrequencyState> {\n  const key = emailSuppressionKey(email)\n  if (!key) return { ...NO_RECORD }\n  try {\n    const snapshot = await frequencyDoc(hostId, key, firestore).get()\n    if (!snapshot.exists) return { ...NO_RECORD }\n    return stateFromSnapshot(snapshot)\n  } catch (error) {\n    console.error('[email-marketing] frequency read failed; allowing', error)\n    return { ...NO_RECORD }\n  }\n}\n\n/**\n * Records the pace a recipient asked for.\n *\n * Written from the preference page, which is unauthenticated and reached by a\n * signed link — so the CALLER has already proved the request is this\n * address's. A merge, because the document is the send counter and this must\n * not disturb the window it shares with.\n *\n * Never throws: a preference that failed to store is a page that should say\n * so, not a 500 on a screen a recipient reached in order to leave.\n *\n * @returns whether it was stored.\n */\nexport async function setMarketingCadence(\n  hostId: string,\n  email: string,\n  cadence: MarketingCadence,\n  options?: { nowMs?: number; firestore?: any },\n): Promise<boolean> {\n  const key = emailSuppressionKey(email)\n  if (!key || !hostId) return false\n  try {\n    await frequencyDoc(hostId, key, options?.firestore).set(\n      {\n        email: String(email).trim().toLowerCase(),\n        cadence: normalizeMarketingCadence(cadence),\n        cadenceSetAtMs: options?.nowMs ?? Date.now(),\n      },\n      { merge: true },\n    )\n    return true\n  } catch (error) {\n    console.error('[email-marketing] cadence write failed', error)\n    return false\n  }\n}\n\n/**\n * Records marketing messages against the recipients' windows.\n *\n * Takes a LIST because the campaign sender records a whole batch at once: it\n * is exempt from the refusal (a reviewed, one-shot act whose recipient count\n * is on screen before it goes) but not from the counting, since a campaign is\n * most of the mail a person receives from a site. Doing that per recipient\n * inside the send loop would add a round trip to each of up to 500 sequential\n * sends; doing it here adds one batch after them.\n *\n * Never throws. A lost counter increment means one recipient's ceiling is\n * measured a message low, which is not worth failing a delivered send over.\n */\nexport async function recordMarketingSends(\n  hostId: string,\n  emails: readonly string[],\n  options?: { nowMs?: number; firestore?: any },\n): Promise<number> {\n  const nowMs = options?.nowMs ?? Date.now()\n  const keyed = new Map<string, string>()\n  for (const email of emails) {\n    const key = emailSuppressionKey(email)\n    if (key) keyed.set(key, String(email).trim().toLowerCase())\n  }\n  if (!keyed.size || !hostId) return 0\n  let recorded = 0\n  try {\n    const db = options?.firestore ?? defaultFirestore()\n    for (const [key, email] of keyed) {\n      const ref = frequencyDoc(hostId, key, db)\n      const existing: MarketingFrequencyState = await ref\n        .get()\n        .then((snapshot: any) =>\n          snapshot.exists ? stateFromSnapshot(snapshot) : { ...NO_RECORD },\n        )\n        .catch(() => ({ ...NO_RECORD }))\n      const window = marketingFrequencyVerdict(\n        [...existing.window, nowMs],\n        nowMs,\n      )\n      await ref.set(\n        {\n          email,\n          sentAtMs: window.inWindow,\n          lastSentAtMs: nowMs,\n          // Write-once, unlike `lastSentAtMs` beside it. Overwriting it would\n          // restart the sunset clock on every send, which would make the\n          // sunset unreachable — a person whose relationship is always \"as\n          // old as the last message\" is never older than the window.\n          ...(existing.firstSentAtMs ? {} : { firstSentAtMs: nowMs }),\n        },\n        { merge: true },\n      )\n      recorded += 1\n    }\n  } catch (error) {\n    console.error('[email-marketing] frequency record failed', error)\n  }\n  return recorded\n}\n\n/**\n * The subset of `emails` that has NOT asked this site for mail less often\n * than right now.\n *\n * The fourth filter a campaign passes, after the platform suppression list,\n * the site's own and the topic opt-outs — and the only one that is not in\n * `email-suppression.ts` beside those three, because it reads the counter\n * document this module owns and that module is this module's dependency.\n *\n * {@link marketingSendVerdict} enforces the same rule per message, for the\n * senders that reach the gate. THIS is the campaign path's copy, and it is\n * the enforcement there rather than only a count: a campaign carries no\n * `marketing` context — it mints its own unsubscribe URL upstream — so the\n * gate is not on its path at all, and a rule asked only there would not be\n * asked of the sender that produces most of a person's mail.\n *\n * Answering it as a FILTER rather than per message is also the only placement\n * that keeps the composer honest. The argument for exempting a campaign from\n * the platform ceiling is that a control which silently removed people from a\n * reviewed one-shot send would make the number on screen a lie; subtracting\n * a request the recipient actually made, where every other refusal is already\n * subtracted, is what keeps this one from having that problem.\n *\n * Keyed and read with one `getAll`, matching its three neighbors: one round\n * trip bounded by the size of the send, and no composite index to go missing.\n *\n * ## Fails OPEN, like the topic filter beside it\n *\n * A cadence is a PACE, not a stop. Guessing wrong on an unreadable counter\n * costs one recipient one message sooner than they asked for; guessing wrong\n * the other way withholds a whole campaign on a transient read failure. The\n * two suppression lists have already refused everybody who asked us to stop\n * entirely, so nobody who said \"no\" reaches this line.\n */\nexport async function filterCadenceSendable(\n  hostId: string,\n  emails: readonly string[],\n  options?: { nowMs?: number; firestore?: any },\n): Promise<string[]> {\n  if (!emails.length || !hostId) return [...emails]\n  const nowMs = options?.nowMs ?? Date.now()\n  // An unkeyable address carries no counter, so it has expressed no pace. It\n  // is dropped from the LOOKUP and kept in the answer, exactly as the topic\n  // filter keeps one: the stricter filters above have already had their say.\n  const lookups: Array<{ email: string; key: string }> = []\n  for (const email of emails) {\n    const key = emailSuppressionKey(email)\n    if (key) lookups.push({ email, key })\n  }\n  if (!lookups.length) return [...emails]\n  try {\n    const db = options?.firestore ?? defaultFirestore()\n    const counters = db\n      .collection('hosts')\n      .doc(hostId)\n      .collection(EMAIL_FREQUENCY_SUBCOLLECTION)\n    const snapshots = await db.getAll(\n      ...lookups.map((entry) => counters.doc(entry.key)),\n    )\n    const holding = new Set<string>()\n    lookups.forEach((entry, index) => {\n      const snapshot = snapshots[index]\n      if (!snapshot?.exists) return\n      // The same decoder the per-message path uses, so the two cannot\n      // disagree about one document. The sunset's `firstSentAtMs` comes back\n      // with it and is deliberately unused: a campaign is exempt from that\n      // refusal, so subtracting on it here would remove people from a count\n      // the gate is going to mail anyway.\n      const state = stateFromSnapshot(snapshot)\n      const verdict = marketingCadenceVerdict(\n        state.cadence,\n        state.lastSentAtMs,\n        nowMs,\n      )\n      if (!verdict.allowed) holding.add(entry.email)\n    })\n    return emails.filter((email) => !holding.has(email))\n  } catch (error) {\n    console.error(\n      '[email-marketing] cadence lookup failed; failing open',\n      error,\n    )\n    return [...emails]\n  }\n}\n\n/**\n * The gate itself, exported so it can be exercised without installing it.\n *\n * ORDER MATTERS. The suppression check is first because its answer is\n * permanent and the frequency record must not count a message that was never\n * going to leave — a suppressed address whose window kept growing would stay\n * capped for a day after being released.\n */\nexport async function marketingSendVerdict(\n  request: MarketingSendGateRequest,\n  options?: { nowMs?: number; firestore?: any },\n): Promise<MarketingSendGateVerdict> {\n  const nowMs = options?.nowMs ?? Date.now()\n  const email = String(request.email ?? '')\n    .trim()\n    .toLowerCase()\n  const sendable = await filterSendableForHost(\n    request.hostId,\n    [email],\n    options?.firestore,\n  )\n  if (!sendable.length) {\n    return {\n      allowed: false,\n      refusal: 'suppressed',\n      detail:\n        'This address has unsubscribed, bounced permanently, or reported a ' +\n        'message as spam.',\n    }\n  }\n\n  // Normalized once, and read by both the links below and the topic check\n  // further down: two spellings of \"which stream is this\" is how a link comes\n  // to carry a topic the gate did not check.\n  const topicId = String(request.topicId ?? '').trim()\n\n  /*\n   * TWO URLS OVER ONE SIGNATURE, the same split `campaign-send.ts` makes and\n   * for the same reason (RFC 8058).\n   *\n   * `oneClickUrl` is what `List-Unsubscribe` names: a mailbox provider POSTs\n   * it with nobody present and expects the act to have happened when it reads\n   * the 200, so it points at the route whose POST writes immediately.\n   *\n   * `unsubscribeUrl` is the link a PERSON clicks in the footer, and it points\n   * at the preference page. Every caller on this path — the abandoned-cart\n   * sweep, the restock notice, the newsletter welcome, the automation step —\n   * names a topic, and a footer pointing at the one-click route gives the\n   * recipient of one of those exactly one choice: stop hearing from this site\n   * entirely. The page offers leaving that one stream instead, with\n   * \"Unsubscribe from everything\" still on it.\n   *\n   * The topic rides both links, so the page opens on the stream the message\n   * belonged to rather than on a list the recipient has to search.\n   */\n  const link = {\n    siteBase: request.siteBase,\n    hostId: request.hostId,\n    email,\n    ...(topicId ? { topicId } : {}),\n  }\n  const unsubscribeUrl = buildUnsubscribeUrl({\n    ...link,\n    surface: 'preferences',\n  })\n  const oneClickUrl = buildUnsubscribeUrl({ ...link, surface: 'one-click' })\n\n  /*\n   * THE STREAM THIS MESSAGE BELONGS TO — the third list, and the narrowest.\n   *\n   * ONLY when the caller named one. An absent topic is not \"the default\n   * topic\": it is a message that belongs to no stream, and there is nothing\n   * for a person to have left. That is what keeps this check off the mail it\n   * must never touch — a receipt, a password reset, a booking confirmation,\n   * none of which declare a `marketing` context at all and none of which name\n   * a stream if they somehow did.\n   *\n   * After the suppression lists and before the counter read below, matching\n   * the order `campaign-send.ts` filters in, for two reasons that agree. It\n   * is the weaker fact, and the weaker fact should never be the one that\n   * decides — a person who unticked \"Promotions and offers\" is still a\n   * subscriber, where a person on either suppression list is not. And it is a\n   * TERMINAL refusal, so answering it before the counter read means a\n   * recipient this message was never going to reach costs one lookup rather\n   * than three.\n   *\n   * Fails OPEN, because `filterTopicSendable` does: a topic preference is a\n   * narrower fact than a suppression, and a read that failed for an unrelated\n   * reason is no reason to withhold a message from somebody the two lists\n   * above already cleared.\n   */\n  if (topicId) {\n    const onTopic = await filterTopicSendable(\n      request.hostId,\n      topicId,\n      [email],\n      options?.firestore,\n    )\n    if (!onTopic.length) {\n      /*\n       * ⛔ A REFUSAL AND NOTHING ELSE, as with the pace refusals below.\n       *\n       * No suppression is written, no membership changes, and the frequency\n       * window is not appended to — a message that never left must not count\n       * against what this person has received. They stay on every other\n       * stream they subscribe to, and the next message on one of those goes.\n       */\n      return {\n        allowed: false,\n        refusal: 'topic-unsubscribed',\n        detail:\n          'This address has left the email topic this message belongs to. ' +\n          'They still receive the other streams from this site.',\n        unsubscribeUrl,\n        oneClickUrl,\n      }\n    }\n  }\n\n  // ONE read, and every refusal below is answered from it — except the\n  // sunset's engagement half, which is a different document and is fetched\n  // only when a window is configured and nothing above has already refused.\n  const state = await readMarketingFrequencyState(\n    request.hostId,\n    email,\n    options?.firestore,\n  )\n\n  /*\n   * THE RECIPIENT'S OWN REQUEST, first among the three pace refusals and the\n   * only one not subject to `capped`.\n   *\n   * `capped: false` exempts a campaign from the platform CEILING and from the\n   * SUNSET, because a control the merchant did not ask for and cannot see,\n   * silently removing people from a reviewed one-shot send, would make the\n   * recipient count on screen a lie. That argument does not reach this one: a\n   * person used the preference page to ask this site for less mail, and a\n   * campaign that overrode them would make that page a form that records a\n   * request nobody honors — the same failure as ignoring an unsubscribe, one\n   * notch quieter.\n   *\n   * Above the sunset for three reasons. It is the only one of the three a\n   * PERSON asked for, and when both apply the honest answer to \"why did this\n   * not send\" is the fact somebody stated rather than the inference we drew.\n   * It is answered entirely from the counter document already in hand, so a\n   * recipient who asked for monthly mail never pays for the sunset's second\n   * read. And it is the one refusal a campaign is bound by, so asking it\n   * first gives the campaign path and the automated paths the same order.\n   *\n   * The sunset's terminality argument does not out-rank any of that: a sweep\n   * that defers this row retries it once per cadence interval — a day, a week\n   * or a month — not once per beat, which is what that argument is about.\n   *\n   * A campaign is bound by the rule but not by THIS enforcement of it: it\n   * carries no `marketing` context, so nothing on its path reaches this\n   * function. {@link filterCadenceSendable} is where it is asked there, and\n   * asked as a filter so the recipient count reflects it before Send.\n   */\n  const cadence = marketingCadenceVerdict(\n    state.cadence,\n    state.lastSentAtMs,\n    nowMs,\n  )\n  if (!cadence.allowed) {\n    /*\n     * ⛔ A REFUSAL AND NOTHING ELSE, exactly as below.\n     *\n     * Nobody is unsubscribed, no membership changes, no contact is touched,\n     * and the frequency window is not appended to — a message that never left\n     * must not count against what this person has received. Somebody who\n     * asked for monthly mail stays on every audience they were on and is\n     * mailed again next month.\n     */\n    return {\n      allowed: false,\n      refusal: 'cadence-limited',\n      detail:\n        `This address asked this site for no more than one marketing ` +\n        `message ${CADENCE_PHRASES[state.cadence]}. The next one may go on ` +\n        `${new Date(cadence.nextAllowedAtMs).toISOString()}.`,\n      unsubscribeUrl,\n      oneClickUrl,\n    }\n  }\n\n  /*\n   * THE SUNSET, ahead of the frequency ceiling.\n   *\n   * Ordered above the ceiling because its refusal is TERMINAL and the\n   * ceiling's is not: a sweep defers a `frequency-capped` message and retries\n   * it, so reporting the retryable refusal for a person the sunset would\n   * refuse anyway means the same doomed row comes back on every beat.\n   *\n   * `request.capped` governs it, the same flag the ceiling reads, so a\n   * campaign — a reviewed act with its recipient count on screen — is exempt\n   * for the reason recorded on `MarketingSendContext.capped`. That leaves the\n   * sunset governing the automated paths, which fire with no human present.\n   *\n   * The engagement read is the ONLY second round trip on this path, and it is\n   * spent only when a window is configured, the caller is capped, and the\n   * cadence above has already allowed. Off is the default, and off costs\n   * nothing.\n   */\n  const sunsetDays = marketingSunsetDays()\n  if (request.capped && sunsetDays > 0) {\n    const engagement = await readPersonEngagement(email, options?.firestore)\n    const sunset = marketingSunsetVerdict(\n      {\n        firstSentAtMs: state.firstSentAtMs,\n        lastEngagedAtMs: engagement.lastEngagedAtMs,\n      },\n      nowMs,\n      sunsetDays,\n    )\n    if (!sunset.allowed) {\n      /*\n       * ⛔ A REFUSAL AND NOTHING ELSE.\n       *\n       * No suppression is written, no membership is touched, no contact is\n       * changed, and the frequency window below is not appended to — a\n       * message that never left must not count against what this person has\n       * received. The person is exactly where they were, and the next send\n       * after they open anything goes.\n       */\n      return {\n        allowed: false,\n        refusal: 'unengaged',\n        detail:\n          `This address has not opened or clicked anything for ` +\n          `${sunset.quietForDays} days, and this site has been mailing it ` +\n          `for longer than the ${sunset.days}-day engagement window. It ` +\n          `becomes mailable again as soon as they engage.`,\n        unsubscribeUrl,\n        oneClickUrl,\n      }\n    }\n  }\n\n  const verdict = marketingFrequencyVerdict(state.window, nowMs)\n  if (request.capped && !verdict.allowed) {\n    return {\n      allowed: false,\n      refusal: 'frequency-capped',\n      detail:\n        `This address has already received ${verdict.used} marketing ` +\n        `messages from this site today (the ceiling is ${verdict.cap}).`,\n      unsubscribeUrl,\n      oneClickUrl,\n    }\n  }\n\n  /*\n   * The send is granted, so it is counted — including for a campaign, which\n   * is exempt from the refusal above and not from this. `sentAtMs` therefore\n   * measures what the recipient actually receives rather than only the part\n   * of it a cap may stop, which is the difference between a ceiling and a\n   * number that describes nothing.\n   */\n  const appended = marketingFrequencyVerdict(\n    [...verdict.inWindow, nowMs],\n    nowMs,\n  )\n  const key = emailSuppressionKey(email)\n  if (key) {\n    await frequencyDoc(request.hostId, key, options?.firestore)\n      .set(\n        {\n          email,\n          sentAtMs: appended.inWindow,\n          lastSentAtMs: nowMs,\n          // Write-once — see EmailFrequencyRecord.firstSentAtMs. Re-stamping\n          // it on every send would keep the relationship permanently younger\n          // than any sunset window, so the sunset could never fire.\n          ...(state.firstSentAtMs ? {} : { firstSentAtMs: nowMs }),\n        },\n        { merge: true },\n      )\n      // Never blocks the send. A counter write that failed is a ceiling\n      // measured one message low, and refusing delivery over it would let a\n      // Firestore hiccup become an outage on a merchant's mail.\n      .catch((error: unknown) => {\n        console.error('[email-marketing] frequency write failed', error)\n      })\n  }\n\n  return { allowed: true, unsubscribeUrl, oneClickUrl }\n}\n\n/**\n * Puts the gate on `sendEmail`'s path.\n *\n * **Called at module load**, from the bottom of this file, so that importing\n * `@aglyn/tenant-data-admin` anywhere is enough — every server surface in the\n * product already imports that barrel, and `export *` forces this module to\n * evaluate. The alternative, a call at each server entrypoint, is the\n * many-places-to-remember shape this codebase has rejected twice already.\n *\n * Idempotent: installing twice replaces the same closure with an equivalent\n * one, and the closure holds no state — the state is the Firestore document.\n */\nexport function installMarketingSendGate(): void {\n  setMarketingSendGate((request) => marketingSendVerdict(request))\n}\n\n/** Whether a gate is installed. Reads the shared seam, not a local flag. */\nexport function isMarketingSendGateInstalled(): boolean {\n  return getMarketingSendGate() !== null\n}\n\ninstallMarketingSendGate()\n"],"names":["getMarketingSendGate","marketingCadenceVerdict","marketingFrequencyVerdict","marketingSunsetDays","marketingSunsetVerdict","normalizeMarketingCadence","setMarketingSendGate","firebaseAdmin","readPersonEngagement","emailSuppressionKey","filterSendableForHost","filterTopicSendable","buildUnsubscribeUrl","defaultFirestore","app","firestore","EMAIL_FREQUENCY_SUBCOLLECTION","CADENCE_PHRASES","all","daily","weekly","monthly","NO_RECORD","window","firstSentAtMs","lastSentAtMs","cadence","stateFromSnapshot","snapshot","stored","get","Array","isArray","map","at","Number","first","last","isFinite","length","Math","max","frequencyDoc","hostId","emailKey","collection","doc","readMarketingFrequency","email","readMarketingFrequencyState","key","exists","error","console","setMarketingCadence","options","set","String","trim","toLowerCase","cadenceSetAtMs","nowMs","Date","now","merge","recordMarketingSends","emails","keyed","Map","size","recorded","db","ref","existing","then","catch","sentAtMs","inWindow","filterCadenceSendable","lookups","push","counters","snapshots","getAll","entry","holding","Set","forEach","index","state","verdict","allowed","add","filter","has","marketingSendVerdict","request","sendable","refusal","detail","topicId","link","siteBase","unsubscribeUrl","surface","oneClickUrl","onTopic","nextAllowedAtMs","toISOString","sunsetDays","capped","engagement","sunset","lastEngagedAtMs","quietForDays","days","used","cap","appended","installMarketingSendGate","isMarketingSendGateInstalled"],"mappings":"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"}

package/src/lib/server/email-metering.d.ts

@@ -0,0 +1,293 @@
+/**
+ * @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.
+ */
+/**
+ * The email meters (AGL-1438). **Two of them, deliberately.**
+ *
+ * Before this, `hosts/{hostId}/counters/emailSends` was written by exactly one
+ * caller — the marketing campaign sender. Workflows, commerce, bookings and
+ * invites all called `sendEmail` and counted nothing, so the counter that named
+ * itself "email sends" held campaign sends alone. Two things followed from
+ * that: `emailSendsPerMonth` under-enforced, and the COGS figure AGL-1134
+ * started recording off this counter under-reported real email cost by however
+ * much non-campaign volume an org sent.
+ *
+ * UNITS: plain COUNTS — one per recipient address handed to the sender —
+ * for the calendar month named by the `YYYY-MM` FIELD on the counter document.
+ * Not bytes, not currency, not a running total: each month's field is
+ * independent, so summing months is a legitimate year-to-date and reading one
+ * is that month alone. Same unit as `workflowRuns`/`actionRuns` beside it, and
+ * the same unit `orgCounterTotals` sums, so a campaign of 300 and 300 workflow
+ * notifications are the same 300 on the meter.
+ *
+ * ### `emailSends` — the COST meter. Counts everything. Gates nothing.
+ *
+ * Every `sendEmail` call site increments this, whatever sent it. It is what the
+ * monthly rollup carries for COGS, and it is RECORDED, NOT PRICED — there is
+ * still no per-email rate anywhere, so it enters neither `billedCents` nor
+ * `costUsd` nor `ORG_COGS_UNIT_RATES_USD`. Pricing it is a decision with an
+ * invoice month behind it.
+ *
+ * ### `campaignEmailSends` — the ENFORCEABLE meter. Counts campaigns only.
+ *
+ * `emailSendsPerMonth` is checked against this and nothing else. A campaign is
+ * discretionary: refusing one at the cap is the outcome the plan sells, the
+ * customer sees a clear message, and they upgrade or wait.
+ *
+ * **Transactional mail is never blocked by a quota, at any tier.** Password
+ * resets, invites, order confirmations, booking reminders and workflow
+ * notifications send regardless of counter state; they count toward cost and
+ * cannot be refused. The failure modes are not symmetric — a blocked password
+ * reset locks somebody out of their own account, and the message explaining
+ * why is itself an email that will not send; a dropped order confirmation
+ * reads to the buyer as a failed order. That converts a billing event into an
+ * outage on somebody else's business, where the overage it saved was bounded
+ * and billable. It is the same fail-open posture the rest of this codebase
+ * takes: rate limiting fails soft, robots/sitemap fail open so a transient
+ * error cannot de-index a customer's site.
+ *
+ * ### Not double-counted
+ *
+ * One call site, one call to this function, and a campaign send increments BOTH
+ * counters from that single call rather than incrementing `emailSends` here and
+ * again somewhere else. The counter is keyed by month ON THE DOCUMENT, so
+ * nothing accumulates across a re-read, and the rollup re-derives rather than
+ * adds. A meter that double-counts is worse than no meter, because it looks
+ * authoritative (AGL-1402).
+ *
+ * ### Transition note
+ *
+ * `campaignEmailSends` starts empty. For the month this ships, campaign volume
+ * already sent is recorded only under the old `emailSends`, so the campaign cap
+ * effectively restarts once. That loosens for at most one month, which is the
+ * correct direction to be wrong in — the alternative, seeding the enforceable
+ * meter from a counter that now also holds transactional mail, would refuse
+ * campaigns because of order confirmations.
+ */
+/** Every send, whatever produced it. The cost meter. */
+export declare const EMAIL_SENDS_COUNTER = "emailSends";
+/** Campaign sends alone. The only meter `emailSendsPerMonth` may refuse. */
+export declare const CAMPAIGN_EMAIL_SENDS_COUNTER = "campaignEmailSends";
+/** Top-level home for platform-scoped meters: `meters/platform/counters/*`. */
+export declare const PLATFORM_METER_COLLECTION = "meters";
+export declare const PLATFORM_METER_DOC = "platform";
+/**
+ * Who the send is attributed to.
+ *
+ * - `host` — a site sent it: campaigns, receipts, booking mail, workflow
+ *   notifications, member mail. Rolls up to the owning org.
+ * - `org` — the org sent it with no site involved: invites, member-added,
+ *   the welcome mail, usage summaries, erasure notices.
+ * - `platform` — Aglyn's own account and staff mail: password resets and
+ *   verification (which happen before any org is known), new-device and
+ *   passkey alerts, staff alerts, the system-email test send. Real cost, but
+ *   not any one customer's, so it is counted apart from every org rollup and
+ *   never reaches a COGS figure or an invoice.
+ */
+export type EmailMeterScope = {
+    kind: 'host';
+    hostId: string;
+} | {
+    kind: 'org';
+    orgId: string;
+} | {
+    kind: 'platform';
+};
+/**
+ * Whether a quota may refuse this send.
+ *
+ * `campaign` is the ONLY discretionary class. Everything else is
+ * `transactional`, which means: count it, never gate on it.
+ */
+export type EmailSendClass = 'campaign' | 'transactional';
+export interface RecordEmailSendsOptions {
+    scope: EmailMeterScope;
+    /** Emails actually handed to the sender. Zero and negatives are no-ops. */
+    count: number;
+    sendClass: EmailSendClass;
+    /** `YYYY-MM`; defaults to the current UTC month. */
+    month?: string;
+    /** Injectable for tests; defaults to the Admin SDK's Firestore. */
+    firestore?: any;
+}
+/** The counters document for a scope, e.g. `hosts/{id}/counters/emailSends`. */
+export declare function emailMeterRef(firestore: any, scope: EmailMeterScope, counter: string): any;
+/** Current calendar month as `YYYY-MM`, matching every other counter here. */
+export declare function currentMeterMonth(now?: Date): string;
+/**
+ * Records `count` emails against the cost meter, and against the campaign
+ * meter too when the send was a campaign.
+ *
+ * **Never throws.** Metering is bookkeeping that runs after mail has already
+ * gone out — a counter write that fails must not turn a delivered receipt into
+ * a 500 for the buyer, and must certainly not be able to stop the next send.
+ * Failures are logged and swallowed, the same posture `sendEmail` itself takes.
+ */
+export declare function recordEmailSends(options: RecordEmailSendsOptions): Promise<void>;
+/**
+ * One transactional (or, with `sendClass`, campaign) send attributed to a site.
+ *
+ * The overwhelmingly common call — `await meterHostEmail(hostId)` right after
+ * a `sendEmail` — so it reads as one line at every call site and there is one
+ * place to change if the counter ever moves.
+ */
+export declare function meterHostEmail(hostId: string, count?: number, sendClass?: EmailSendClass): Promise<void>;
+/** Org-scoped transactional mail: invites, welcome, usage summaries. */
+export declare function meterOrgEmail(orgId: string, count?: number): Promise<void>;
+/**
+ * Account and staff mail that belongs to no org at send time — a password
+ * reset knows only an address, and a staff alert has no customer at all.
+ */
+export declare function meterPlatformEmail(count?: number): Promise<void>;
+/**
+ * The enforceable figure for a site this month: campaign sends alone.
+ *
+ * Reads the campaign meter and NOT `emailSends`, which now also holds every
+ * receipt and password reset the site sent. Enforcing the plan's cap against
+ * that total is exactly the behaviour this issue exists to prevent.
+ */
+export declare function campaignEmailSendsForMonth(hostRef: any, month: string): Promise<number>;
+/**
+ * The org-level campaign meter, and the ONLY figure `emailSendsPerMonth` is
+ * enforced against since AGL-2267.
+ *
+ * ## Why a second counter and not the per-host one
+ *
+ * `hosts/{hostId}/counters/campaignEmailSends` is per SITE. `emailSendsPerMonth`
+ * is an ORG entitlement. An org with N sites therefore received N × the cap it
+ * bought — invisible on Free and Starter (`hostLimit: 1`) and growing with the
+ * plan, so the customers who paid most got the most cap they had not paid for.
+ *
+ * The per-host counter is UNCHANGED and still written, by `meterHostEmail`, on
+ * the delivered count. It is per-site history and it feeds the cost meter;
+ * nothing about it was wrong except being asked a question about an org.
+ *
+ * ## Why folding the existing per-site counters in was rejected
+ *
+ * Summing N site counters into one org total retroactively puts multi-site
+ * paying customers over a limit they have been under all along — a limit that
+ * then refuses a campaign they had every reason to expect to send, days after
+ * they bought the plan. This counter therefore STARTS EMPTY, and the campaign
+ * cap effectively restarts once for the month this ships.
+ *
+ * That is the same transition `campaignEmailSends` itself was given, and the
+ * same reasoning: it loosens for at most one month, which is the correct
+ * direction to be wrong in, and it needs no production measurement of who is
+ * currently over — a measurement that could only be taken against live
+ * customer data and would have blocked the fix indefinitely.
+ */
+export declare const ORG_CAMPAIGN_EMAIL_SENDS_COUNTER = "campaignEmailSends";
+/** A granted claim on the org's monthly campaign allowance. */
+export interface CampaignSendReservation {
+    orgId: string;
+    month: string;
+    /** Messages claimed up front. */
+    reserved: number;
+}
+export type ReserveCampaignSendsResult = {
+    ok: true;
+    reservation: CampaignSendReservation;
+    used: number;
+    limit: number;
+} | {
+    ok: false;
+    used: number;
+    limit: number;
+};
+/**
+ * The enforceable figure for an ORG this month: campaign sends alone.
+ *
+ * Read-only. Used by the campaign composer's recipient preview, which must
+ * not reserve anything (AGL-2178 — "nothing has been written above this
+ * line"), and by anything that reports headroom.
+ */
+export declare function orgCampaignEmailSendsForMonth(orgId: string, month: string, firestore?: any): Promise<number>;
+/**
+ * Claims `count` campaign sends against the org's monthly allowance, ATOMICALLY.
+ *
+ * ## Why a reservation and not a check
+ *
+ * The cap used to be read before the send and incremented after delivery, so
+ * two concurrent campaigns both passed the same reading and both sent — the
+ * cap was advisory in exactly the conditions it existed for. **A read-then-write
+ * cap is not a cap.**
+ *
+ * The transaction reads the counter and writes an ABSOLUTE value derived from
+ * that read, deliberately not `FieldValue.increment`. Firestore aborts and
+ * re-runs the callback when a document the transaction read has moved, so a
+ * second sender that starts inside the first one's window re-reads the raised
+ * figure and is refused. An increment would be atomic on the number and
+ * useless for the decision, because the decision is made from a value the
+ * write never proves it still held.
+ *
+ * A refused reservation writes NOTHING.
+ *
+ * ## Why reserve-then-reconcile rather than reserve-and-keep
+ *
+ * A campaign reserves against a PARTIAL delivery: `sendEmail` reports per
+ * message, and only some of a 500-address batch may go out. Keeping the whole
+ * reservation would charge a customer's allowance for mail that never left.
+ * So the claim is taken in full up front — that is what makes it a cap — and
+ * {@link reconcileCampaignSendReservation} gives back the difference once the
+ * delivered count is known.
+ *
+ * **The failure mode is stated rather than hidden**: if the process dies
+ * between reserving and reconciling, the org is charged for the undelivered
+ * remainder for the rest of that calendar month. That is conservative in the
+ * direction this issue cares about — it can only ever refuse more mail, never
+ * let more out — and it self-heals at the month boundary, because each month
+ * is an independent field on the document.
+ *
+ * `limit` may be `Infinity` (`UNLIMITED`), which admits everything.
+ */
+export declare function reserveCampaignEmailSends(options: {
+    orgId: string;
+    month: string;
+    count: number;
+    limit: number;
+    firestore?: any;
+}): Promise<ReserveCampaignSendsResult>;
+/**
+ * Returns the undelivered part of a reservation.
+ *
+ * Also a transaction, and also an absolute write from its own read: a refund
+ * computed from a stale figure would undo a reservation another campaign took
+ * in the meantime, which is the same defect one direction over.
+ *
+ * **Never throws** and never drives the counter below zero. This runs after
+ * mail has already gone out; a bookkeeping failure must not turn a delivered
+ * campaign into a 500, exactly like `recordEmailSends` above. The cost of
+ * swallowing it is that the org keeps a claim it did not use for the rest of
+ * the month, which is the safe direction.
+ */
+export declare function reconcileCampaignSendReservation(reservation: CampaignSendReservation | null | undefined, delivered: number, firestore?: any): Promise<void>;
+/**
+ * Volume above the plan's included band, in emails — RE-EXPORTED, not defined
+ * here, the same move AGL-2155 made for the bandwidth helpers.
+ *
+ * The definition moved down to `@aglyn/aglyn/app-utils/plan-entitlements`
+ * because the billing page has to render the overage BEFORE it is charged,
+ * and that page is a client component which cannot import this module: the
+ * Admin SDK comes with it. A second copy of the subtraction on the client is
+ * the shape where the readout and the invoice quietly stop agreeing.
+ *
+ * Re-exported so every server caller keeps importing it from the module it
+ * always did — one definition, no drift, no import churn.
+ *
+ * @see priceEmailSendOverage — what the excess costs, at the plan's rate.
+ */
+export { emailSendsOverage } from '@aglyn/aglyn/app-utils/plan-entitlements';
+export default recordEmailSends;