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

package/src/lib/server/email-suppression.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/email-suppression.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 * The PLATFORM-WIDE email suppression list, `emailSuppressions/{emailKey}`\n * (AGL-2407).\n *\n * ## What was missing\n *\n * AGL-1918 (`7a8f3cd68`) made `email.bounced` (permanent) and\n * `email.complained` write a suppression — into `hosts/{hostId}/suppressions`,\n * found from a Resend tag that only `campaign-send.ts` stamped. That closed\n * the campaign half and could close no other, because there was nowhere to\n * file the rest:\n *\n * Every other sender in the product goes through the shared `sendEmail` —\n * invites,\n * password resets, verification, receipts, booking confirmations, the monthly\n * usage summary, the usage-alert fan-out, restock and abandoned-cart mail, the\n * merchant-authored workflow `sendEmail` step. A bounce on any of those\n * arrived at the webhook with no site to place it against and was answered\n * `200 {ignored:true}`. A dead address was re-mailed on every subsequent send,\n * forever, and a spam complaint had no effect on anything.\n *\n * That matters most exactly when it is hardest to fix: on Sept 1 the signup\n * door opens, and verification and invite mail — addressed by strangers typing\n * addresses — is the highest-bounce-rate mail we send, on the same Resend key\n * and the same From address as everything else.\n *\n * ## Why a sibling of `contactSuppressions` and not a channel on it\n *\n * `contact-suppression.ts` is the same idea for phones and every argument it\n * makes holds here: keyed on the identifier because that is what the sender\n * holds at send time; one `get()` by document id, no query and no composite\n * index that could go missing and fail the lookup open; a revocation is a\n * FIELD and not a delete, because the record is the evidence that the\n * suppression was honoured while it was in force.\n *\n * It is a separate collection for one concrete reason: the document id. That\n * list's key is the E.164 digits, and its docblock argues at length that a\n * phone number must NOT be hashed (NANP is ~10^10 values, so a hash buys the\n * appearance of de-identification and none of the substance). An email address\n * is not enumerable, `hosts/{hostId}/suppressions` already keys on\n * `sha256(email)`, and one collection holding two incompatible key spaces is\n * how a lookup comes to be performed against the wrong derivation. The\n * address is stored in the document in the clear regardless, exactly as the\n * per-host list stores it, so a staff reader still shows a human something\n * they can act on.\n *\n * ## Who reads it, and who deliberately does NOT\n *\n * AGL-1438's rule is that a QUOTA may only ever refuse a campaign, because\n * refusing a receipt or a password reset converts a billing event into an\n * outage on a customer's business. A suppression is not a quota, but the same\n * proportionality applies and lands in the same place:\n *\n *  - **Bulk mail consults this list.** The monthly usage summary, the\n *    usage-alert fan-out and the marketplace review fan-out to a publisher's\n *    owners and admins go to a LIST of people who did not ask for that\n *    particular message, on a schedule or on every submission, forever. They\n *    are the sends that re-hit a dead mailbox every month and teach a mailbox\n *    provider that `aglyn.com` does not listen.\n *  - **Transactional mail does NOT.** A password reset, a verification, an\n *    invite, a receipt or a booking confirmation answers something the human\n *    just did. Refusing one because an address bounced or because somebody\n *    once pressed \"report spam\" on an unrelated message would lock a real\n *    customer out of their own account. The shared sender is therefore left\n *    unconditional on purpose, and this is the note that says so.\n *\n * (Written throughout without a literal call expression, on purpose:\n * `email-send-metering-coverage.spec.ts` enumerates senders by grepping the\n * tree for one, and a prose mention here would enrol a module that sends\n * nothing into the AGL-1438 cost-meter sweep.)\n */\n\nimport { FieldValue, Timestamp } from 'firebase-admin/firestore'\n// The leaf entry, not the `@aglyn/aglyn` barrel, for the reason\n// `document-id.ts` gives at length: a barrel import resolves to whatever a\n// spec's `jest.mock` happens to contain, and this module's neighbours are\n// mocked in nearly every spec that touches them.\nimport {\n  readTopicSubscriptionState,\n  TOPIC_OPT_OUTS_SUBCOLLECTION,\n} from '@aglyn/aglyn/app-utils/email-topics'\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport firebaseAdmin from './firebase-admin'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\nexport const EMAIL_SUPPRESSIONS_COLLECTION = 'emailSuppressions'\n\n/**\n * The PER-SITE list, `hosts/{hostId}/suppressions/{emailKey}` — unsubscribes\n * from one site's campaigns, plus the bounces and complaints that arrived\n * carrying that site's tag.\n *\n * Named here rather than at each call site because the two lists are read\n * together by {@link filterSendableForHost}, and a sender that knows one path\n * as a string literal and the other through this module is one rename away\n * from consulting a collection that does not exist and finding nobody\n * suppressed.\n */\nexport const HOST_SUPPRESSIONS_SUBCOLLECTION = 'suppressions'\n\n/**\n * Why an address is suppressed.\n *\n * `bounce` means PERMANENT only. Resend reports `data.bounce.type` as\n * `Permanent` or `Transient`, and a transient bounce is a full mailbox or a\n * greylisting server — recording one here would suppress a real recipient over\n * a temporary condition at their provider. The webhook makes that distinction;\n * this type only names the outcome.\n */\nexport type EmailSuppressionReason =\n  /** Permanent bounce — the mailbox does not exist. */\n  | 'bounce'\n  /** The recipient pressed \"report spam\". */\n  | 'complaint'\n  /** Recorded by staff (a written request, a court order, a correction). */\n  | 'staff'\n\n/**\n * The reasons that may be filed PLATFORM-WIDE, as a runtime set.\n *\n * ## The split this constant enforces\n *\n * A bounce and a complaint are facts about a MAILBOX and about the sending\n * domain every tenant's mail leaves by: the address does not exist for\n * anybody, and somebody who pressed \"report spam\" on `noreply@aglyn.com` has\n * told every sender behind that domain at once. Those belong everywhere,\n * immediately.\n *\n * An UNSUBSCRIBE is not that. It is a preference a person expressed to ONE\n * brand — the sender line they read, the newsletter they joined — and an\n * agency running twelve unrelated clients out of one account would, on a\n * platform-wide entry, stop mailing that person on behalf of eleven brands\n * they never heard from. So an unsubscribe lives only in\n * `hosts/{hostId}/suppressions`, and {@link suppressEmail} refuses it.\n *\n * ## Why a runtime refusal and not just the type\n *\n * {@link EmailSuppressionReason} already excludes it, and a type is not a\n * guard: every caller here builds its reason from a webhook payload or a\n * ternary, `as` casts exist, and the plugin API surface is untyped at the\n * boundary. The cost of the type being wrong once is an opt-out from one\n * brand silently applied to every brand in the account, which is invisible\n * from the console — the mail simply never arrives, and the merchant's own\n * suppression list does not mention it.\n */\nexport const PLATFORM_SUPPRESSION_REASONS: readonly EmailSuppressionReason[] = [\n  'bounce',\n  'complaint',\n  'staff',\n]\n\n/**\n * The reason a self-service opt-out is filed under, on the PER-SITE list.\n *\n * Named because three call sites compare against it — the unsubscribe writes\n * it, the resubscribe link refuses to reverse anything else, and the\n * preference page reads it to decide whether an address may opt back in. A\n * literal in three places is a literal that can be changed in two.\n */\nexport const UNSUBSCRIBE_SUPPRESSION_REASON = 'unsubscribe'\n\nexport interface EmailSuppressionRecord {\n  /** The address, in the clear, lowercased. The id is its hash. */\n  email: string\n  reason: EmailSuppressionReason\n  /**\n   * The `context` tag the send carried (`'invite'`, `'usage-summary'`,\n   * `'campaign'`, …), so a human reading the list can tell which of our\n   * senders produced the address that died. Null when the send carried none.\n   */\n  context: string | null\n  /** The site the failure was attributed to, when the send named one. */\n  hostId: string | null\n  /** Non-null once released. A released record does not suppress. */\n  releasedAt: unknown | null\n  /** What lifted it. Absent on records written before releases were typed. */\n  releasedVia?: EmailReleaseChannel\n  /** The site whose confirmed double opt-in lifted it, when one did. */\n  releasedHostId?: string | null\n  /** The stream that was confirmed, likewise. */\n  releasedTopicId?: string | null\n}\n\n/**\n * Document id for an address: `sha256` of the lowercased, trimmed form.\n *\n * The SAME derivation `campaign-send.ts` uses for `hosts/{hostId}/suppressions`\n * — deliberately, so the two lists can never disagree about which document\n * describes which person.\n *\n * @returns the id, or `null` for anything that is not an address. Never a\n *          best-guess id: suppressing the wrong person and believing you\n *          suppressed the right one is worse than refusing.\n */\nexport function emailSuppressionKey(\n  email: string | null | undefined,\n): string | null {\n  /*\n   * Delegated, not reimplemented. A second hash of the same address is how\n   * this area got two derivations that agreed only by accident; `personKey`\n   * is the one that normalizes and the one the unsubscribe route already\n   * hashes through, so a suppression filed by either is found by both.\n   */\n  return personKey(email)\n}\n\nexport interface SuppressEmailInput {\n  email: string\n  reason: EmailSuppressionReason\n  /** The `context` tag the failed send carried, when it carried one. */\n  context?: string | null\n  /** The site the failed send was attributed to, when it named one. */\n  hostId?: string | null\n  /** Injectable for tests; defaults to the admin app's Firestore. */\n  firestore?: any\n}\n\n/**\n * Record a platform-wide suppression. Idempotent by document id.\n *\n * `createdAt` is stamped only when the document is new, matching the per-host\n * list: a second bounce must not overwrite the moment the address first went\n * bad, because that is the date a human is told when they ask. `suppressedAt`\n * moves every time, so \"when did we last see this fail\" stays answerable.\n *\n * A previously released record is un-released — a fresh failure is a fresh\n * failure.\n *\n * @returns `created: false` when the address was already on the list.\n */\nexport async function suppressEmail(input: SuppressEmailInput): Promise<{\n  key: string\n  created: boolean\n}> {\n  const key = emailSuppressionKey(input.email)\n  if (!key) {\n    throw new Error('[email-suppression] cannot key a suppression for that value')\n  }\n  if (!PLATFORM_SUPPRESSION_REASONS.includes(input.reason)) {\n    throw new Error(\n      `[email-suppression] ${input.reason} is a per-site preference and ` +\n        'cannot be filed platform-wide',\n    )\n  }\n  const db = input.firestore ?? defaultFirestore()\n  const ref = db.collection(EMAIL_SUPPRESSIONS_COLLECTION).doc(key)\n  const snapshot = await ref.get()\n  await ref.set(\n    {\n      email: String(input.email).trim().toLowerCase(),\n      reason: input.reason,\n      context: input.context ?? null,\n      hostId: input.hostId ?? null,\n      releasedAt: null,\n      suppressedAt: FieldValue.serverTimestamp(),\n      ...(snapshot.exists ? {} : { createdAt: FieldValue.serverTimestamp() }),\n    },\n    { merge: true },\n  )\n  return { key, created: !snapshot.exists }\n}\n\n/**\n * What lifted a suppression, recorded on the record it lifted.\n *\n * Written explicitly by both paths rather than left to \"absent means staff\".\n * The two are held to different rules — a staff release may lift any reason,\n * a confirmed opt-in may lift exactly one — so the audit answer to \"how did\n * this address get back on the domain\" has to be a stored fact and not an\n * inference from which field happens to be missing.\n */\nexport type EmailReleaseChannel =\n  /** A staff correction through the admin suppressions surface. */\n  | 'staff'\n  /** A recipient completed a double opt-in from this address. */\n  | 'double-opt-in'\n\n/**\n * Put an address back in circulation (a staff correction, or the person asking\n * to be re-added). The record is kept and marked released, never deleted —\n * same reasoning as `releasePhoneContact`: a deleted record cannot show that\n * the suppression was honored while it stood.\n *\n * Unconditional on the reason, and that is what separates it from\n * {@link releaseEmailForConfirmedOptIn}: a human with the staff role has read\n * the record and is accountable for the row, so they may lift a complaint —\n * a report filed against the wrong message, an address entered by mistake.\n * Nothing automatic gets that latitude.\n *\n * @returns false when there was no live record to release.\n */\nexport async function releaseEmail(input: {\n  email: string\n  releasedByUid?: string | null\n  note?: string | null\n  firestore?: any\n}): Promise<boolean> {\n  const key = emailSuppressionKey(input.email)\n  if (!key) return false\n  const db = input.firestore ?? defaultFirestore()\n  const ref = db.collection(EMAIL_SUPPRESSIONS_COLLECTION).doc(key)\n  const snapshot = await ref.get()\n  if (!snapshot.exists || snapshot.get('releasedAt')) return false\n  await ref.set(\n    {\n      releasedAt: FieldValue.serverTimestamp(),\n      releasedByUid: input.releasedByUid ?? null,\n      releasedNote: input.note ?? null,\n      releasedVia: 'staff' satisfies EmailReleaseChannel,\n    },\n    { merge: true },\n  )\n  return true\n}\n\n/**\n * The ONLY reason a completed round trip may lift, as a runtime set.\n *\n * ## Why a bounce is releasable\n *\n * A `bounce` record is a claim about a MAILBOX at a moment: mail addressed\n * here was permanently refused. Somebody clicking a confirmation link that\n * was delivered to that mailbox has refuted the claim with the only evidence\n * that could refute it — the message arrived, a human read it, and the round\n * trip closed. Leaving the record standing after that makes one transient\n * failure recorded as permanent — a mailbox that was full, a receiving server\n * that answered 550 while it was misconfigured — a life sentence no route can\n * undo.\n *\n * ## Why a complaint is NOT, and never will be\n *\n * `complaint` is not a deliverability fact. It is a person stating they do not\n * want this mail, and a round trip proves nothing about that statement — it\n * proves the mailbox works, which nobody doubted. Releasing one here would\n * make a public signup form into a laundry for spam complaints: submit the\n * complainant's address, they receive a confirmation (the shared sender is\n * transactional and consults no list), and one click anywhere in the chain\n * puts them back on the sending domain that the complaint was filed against.\n * The same reasoning refuses `staff`, which is a written request, a\n * correction, or a legal instruction, and is nobody's to reverse from a link.\n *\n * A runtime set and not just the type, for the reason\n * {@link PLATFORM_SUPPRESSION_REASONS} gives: reasons arrive from webhook\n * payloads through an untyped boundary, and the cost of the type being wrong\n * once here is a complaint silently laundered.\n */\nexport const OPT_IN_RELEASABLE_REASONS: readonly EmailSuppressionReason[] = [\n  'bounce',\n]\n\n/** What a completed double opt-in did to a platform suppression. */\nexport type ConfirmedOptInRelease =\n  /** A live `bounce` record was lifted. The address is mailable again. */\n  | 'released'\n  /** Nothing was suppressed, or it was already released. */\n  | 'nothing-to-release'\n  /** A record stands that a round trip may not lift — see the constant. */\n  | 'refused'\n  /** The read or the write failed. The record, whatever it is, still stands. */\n  | 'failed'\n\n/**\n * Lift a platform suppression that a completed double opt-in has disproved.\n *\n * THE ONE PLACE THE AUTOMATIC RULE IS STATED, mirroring\n * `releaseSiteSuppression` for the per-site list: every path that puts an\n * address back in circulation without a human deciding goes through here, so\n * there is one line to read and one line to change.\n *\n * ## Platform-wide, from one site's round trip\n *\n * The record being lifted asserts something host-independent — this mailbox\n * does not exist, learned anywhere in the product, including on transactional\n * mail that carried no site tag. A confirmation delivered to that mailbox\n * disproves it just as host-independently, so scoping the release to the\n * confirming site would leave a record standing that says the mailbox is dead\n * while we hold proof that it is not. The site and the topic are written onto\n * the record instead, which is what makes the release reviewable: an operator\n * reading the row sees which site's round trip lifted it and when.\n *\n * ## The per-site list is NOT touched\n *\n * `hosts/{hostId}/suppressions` mixes a deliverability fact with a stated\n * preference — an unsubscribe from that one site lives there too — and the\n * email plugin's `releaseSiteSuppression` is the single guarded path that\n * lifts one. Reaching around it from here would put a second, differently\n * reasoned releaser on a list whose whole protection is that there is one.\n *\n * Never throws: it runs inside a recipient's confirmation click, and a\n * Firestore failure must degrade to a suppression that stays in force, not to\n * a person told their confirmation failed.\n */\nexport async function releaseEmailForConfirmedOptIn(input: {\n  email: string\n  /** The site whose confirmation link was clicked, for the audit trail. */\n  hostId: string\n  /** The stream that was confirmed, likewise. */\n  topicId: string\n  firestore?: any\n}): Promise<ConfirmedOptInRelease> {\n  const key = emailSuppressionKey(input.email)\n  if (!key) return 'nothing-to-release'\n  try {\n    const db = input.firestore ?? defaultFirestore()\n    const ref = db.collection(EMAIL_SUPPRESSIONS_COLLECTION).doc(key)\n    const snapshot = await ref.get()\n    if (!snapshot.exists || snapshot.get('releasedAt')) {\n      return 'nothing-to-release'\n    }\n    if (!OPT_IN_RELEASABLE_REASONS.includes(snapshot.get('reason'))) {\n      return 'refused'\n    }\n    await ref.set(\n      {\n        releasedAt: FieldValue.serverTimestamp(),\n        // No human released this, so the field says so rather than naming\n        // whoever last touched the record.\n        releasedByUid: null,\n        releasedVia: 'double-opt-in' satisfies EmailReleaseChannel,\n        releasedHostId: input.hostId || null,\n        releasedTopicId: input.topicId || null,\n      },\n      { merge: true },\n    )\n    return 'released'\n  } catch (error) {\n    console.error(\n      '[email-suppression] opt-in release failed; suppression stands',\n      error,\n    )\n    return 'failed'\n  }\n}\n\n/**\n * The BULK-SEND gate. See the module note for which senders must call this and\n * which must not.\n *\n * FAILS CLOSED, like `isPhoneContactSuppressed`: a read that throws answers\n * `true`, meaning \"treat as suppressed\". The cost of failing closed here is\n * one delayed informational email — every caller is a cron that runs again —\n * and it is nearly free besides, because every one of them is already deep\n * inside a Firestore-backed sweep that a Firestore outage has stopped anyway.\n * The cost of failing open is another delivery attempt at a mailbox that has\n * already told us permanently that it does not exist, which is precisely the\n * behaviour a provider scores a sending domain on. Never \"fix\" a flaky read\n * here by returning false.\n */\nexport async function isEmailSuppressed(\n  email: string | null | undefined,\n  injectedFirestore?: any,\n): Promise<boolean> {\n  const key = emailSuppressionKey(email)\n  // An unusable value is one we cannot check against the list, so it is one we\n  // must not send to. Same fail-closed rule.\n  if (!key) return true\n  try {\n    const db = injectedFirestore ?? defaultFirestore()\n    const snapshot = await db\n      .collection(EMAIL_SUPPRESSIONS_COLLECTION)\n      .doc(key)\n      .get()\n    if (!snapshot.exists) return false\n    return !snapshot.get('releasedAt')\n  } catch (error) {\n    console.error('[email-suppression] lookup failed; failing closed', error)\n    return true\n  }\n}\n\n/**\n * The sendable subset of a recipient list, for the bulk senders.\n *\n * One `get()` per DISTINCT address rather than a query, so the check needs no\n * index and cannot fail open on a missing one. The list is deduplicated first\n * because the callers build it by fanning out over an org's owners and admins,\n * which routinely names the same person twice.\n */\nexport async function filterSuppressedEmails(\n  emails: readonly string[],\n  injectedFirestore?: any,\n): Promise<string[]> {\n  const seen = new Set<string>()\n  const candidates: string[] = []\n  for (const email of emails) {\n    const normalized = String(email ?? '')\n      .trim()\n      .toLowerCase()\n    if (!normalized || seen.has(normalized)) continue\n    seen.add(normalized)\n    candidates.push(normalized)\n  }\n  const verdicts = await Promise.all(\n    candidates.map((email) => isEmailSuppressed(email, injectedFirestore)),\n  )\n  return candidates.filter((_email, index) => !verdicts[index])\n}\n\n/**\n * The sendable subset for a send made in ONE SITE's name — BOTH lists.\n *\n * A per-site suppression says \"not from this site\". A platform suppression\n * says the address hard-bounced or somebody pressed \"report spam\", learned\n * anywhere in the product — including on transactional mail that carried no\n * site tag at all and could therefore never have reached the per-site list.\n * Consulting only the site's own list mails a known-dead or complaining\n * address from the one shared sending domain every tenant's mail leaves by,\n * which makes it every tenant's deliverability problem rather than one\n * merchant's.\n *\n * Composed from {@link filterSuppressedEmails} rather than reimplementing the\n * platform half: normalization, de-duplication and the fail-closed posture\n * live there, and a second copy of them is a second set of rules for two\n * senders to disagree about.\n *\n * ## Both halves fail CLOSED\n *\n * A read that throws answers \"suppressed\". The platform half already does; the\n * per-site half matches it, because a list we could not read is not a list\n * that said this address is safe to mail. The cost of the other choice is a\n * message delivered to somebody who asked us to stop.\n *\n * ## One `getAll`, keyed, rather than a scan of the collection\n *\n * The per-site half looks up exactly the addresses being mailed, by document\n * id, in one round trip. Reading the whole collection instead — which is what\n * the campaign sender did — is bounded by however large the collection has\n * grown, so a site with more suppressions than the read window fails OPEN on\n * the remainder: the people most certain not to want the mail are the ones a\n * truncated read drops.\n */\nexport async function filterSendableForHost(\n  hostId: string,\n  emails: readonly string[],\n  injectedFirestore?: any,\n): Promise<string[]> {\n  const platformSendable = await filterSuppressedEmails(\n    emails,\n    injectedFirestore,\n  )\n  // `getAll` rejects an empty reference list, and there is nothing to ask.\n  if (!platformSendable.length) return []\n  const db = injectedFirestore ?? defaultFirestore()\n  const hostList = db\n    .collection('hosts')\n    .doc(hostId)\n    .collection(HOST_SUPPRESSIONS_SUBCOLLECTION)\n  // Every survivor of the platform half is keyable — `isEmailSuppressed`\n  // answers `true` for an address it cannot key — so this narrows the type\n  // rather than dropping anybody.\n  const keyed: Array<{ email: string; key: string }> = []\n  for (const email of platformSendable) {\n    const key = emailSuppressionKey(email)\n    if (key) keyed.push({ email, key })\n  }\n  if (!keyed.length) return []\n  try {\n    const snapshots = await db.getAll(\n      ...keyed.map((entry) => hostList.doc(entry.key)),\n    )\n    return keyed\n      .filter((_entry, index) => !snapshots[index]?.exists)\n      .map((entry) => entry.email)\n  } catch (error) {\n    console.error(\n      '[email-suppression] per-site lookup failed; failing closed',\n      error,\n    )\n    return []\n  }\n}\n\n/**\n * The subset of `emails` that may be mailed about `topicId` on this site.\n *\n * The third filter a campaign passes, after the platform list and the site's\n * own: the two suppression lists answer \"may we mail this person at all\", and\n * this answers \"may we mail them about THIS\". A recipient who unticked\n * \"Promotions and offers\" on the preference page is not suppressed — they\n * still get the newsletter — so the fact cannot live on either suppression\n * list without meaning something it does not mean.\n *\n * ## Two ways to be excluded, and both are held here\n *\n * Somebody who LEFT the stream, and somebody who has been asked to confirm\n * joining it and has not. The second is what makes a double opt-in worth\n * recording: an unconfirmed subscriber has to be a real quarantine, not a\n * field the send path never looks at. Both come back from\n * `readTopicSubscriptionState`, which is the only place the three states are\n * decided.\n *\n * Keyed by {@link emailSuppressionKey} and read with one `getAll`, which is\n * both halves of the point: the same derivation as the two lists it runs\n * beside, so one person is one document id everywhere; and one round trip\n * bounded by the size of the send, so adding topics does not make a campaign\n * cost more to resolve.\n *\n * ## This one fails OPEN, and that is the opposite of its neighbors\n *\n * Every other filter in this module answers \"suppressed\" when a read throws,\n * because the cost of guessing wrong is mailing somebody who told us to stop.\n * Here the cost of guessing wrong in that direction is refusing to send a\n * newsletter somebody asked for, on a read that failed for an unrelated\n * reason — and the campaign has already passed both suppression lists, so\n * nobody who asked us to stop entirely can reach this line. A topic\n * preference is a narrower fact than a suppression and it gets the treatment\n * that matches. A caller that wants the strict posture already has it one\n * layer up.\n *\n * An empty `topicId` is a campaign from before topics existed, or one whose\n * topic was never resolved. It filters nobody: there is no stream to have\n * left.\n */\nexport async function filterTopicSendable(\n  hostId: string,\n  topicId: string | null | undefined,\n  emails: readonly string[],\n  injectedFirestore?: any,\n): Promise<string[]> {\n  const topic = String(topicId ?? '').trim()\n  if (!topic || !emails.length) return [...emails]\n  // An unkeyable address cannot carry an opt-out record, so it cannot have\n  // left this topic. It is dropped from the LOOKUP and kept in the answer —\n  // the suppression filters above have already refused it on their own\n  // stricter rule, so this one has no business refusing it a second time.\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 = injectedFirestore ?? defaultFirestore()\n    const optOuts = db\n      .collection('hosts')\n      .doc(hostId)\n      .collection(TOPIC_OPT_OUTS_SUBCOLLECTION)\n    const snapshots = await db.getAll(\n      ...lookups.map((entry) => optOuts.doc(entry.key)),\n    )\n    const gone = new Set<string>()\n    lookups.forEach((entry, index) => {\n      const snapshot = snapshots[index]\n      if (!snapshot?.exists) return\n      /*\n       * The shared state reader, never a field test written out here.\n       *\n       * An entry means one of three things and only that function knows all\n       * three. The shorthand this replaced — \"an entry with no\n       * `resubscribedAt` is a live opt-out\" — reads a CONFIRMED double\n       * opt-in, which carries `pendingAt` and `confirmedAt` and no\n       * `resubscribedAt`, as somebody who left.\n       */\n      const record = (snapshot.get('topics') ?? {})[topic]\n      if (readTopicSubscriptionState(record) !== 'subscribed') {\n        gone.add(entry.email)\n      }\n    })\n    return emails.filter((email) => !gone.has(email))\n  } catch (error) {\n    console.error(\n      '[email-suppression] topic opt-out lookup failed; failing open',\n      error,\n    )\n    return [...emails]\n  }\n}\n\n/*\n * THE FOURTH FILTER IS NOT IN THIS FILE, and where it is is forced.\n *\n * `filterCadenceSendable` — the subset that has not asked this site for mail\n * less often than right now — lives in `email-marketing-gate.ts`, because it\n * reads the per-recipient counter document that module owns and names. That\n * module already imports this one for the two suppression lists, so putting\n * the cadence filter here would close a cycle. A campaign's subtraction chain\n * therefore reads: this file's two lists, this file's topic opt-outs, then\n * that file's cadence.\n */\n\n/**\n * The staff queue, newest first, ordered by `suppressedAt` so a re-recorded or\n * released entry surfaces again — the operator's question is \"what changed\",\n * not \"what was first written\". Mirrors `listContactSuppressions`.\n */\nexport async function listEmailSuppressions(options?: {\n  limit?: number\n  /**\n   * Where the NEXT page starts: the `suppressedAt` of the last row already\n   * shown, as `seconds.nanoseconds`.\n   *\n   * The full timestamp rather than milliseconds, because `startAfter` skips\n   * exactly the value it is given: a millisecond-truncated cursor sits BEFORE\n   * the record it names, so that record would arrive again at the top of the\n   * following page. Repeating a row is a smaller fault than skipping one and\n   * neither is necessary.\n   */\n  startAfter?: string | null\n  firestore?: any\n}): Promise<Array<EmailSuppressionRecord & { $id: string }>> {\n  const db = options?.firestore ?? defaultFirestore()\n  let query = db\n    .collection(EMAIL_SUPPRESSIONS_COLLECTION)\n    .orderBy('suppressedAt', 'desc')\n  const cursor = suppressionCursorTimestamp(options?.startAfter)\n  if (cursor) query = query.startAfter(cursor)\n  const snapshot = await query\n    .limit(Math.min(Math.max(options?.limit ?? 100, 1), 500))\n    .get()\n  return snapshot.docs.map((doc: any) => ({\n    $id: doc.id,\n    ...(doc.data() as EmailSuppressionRecord),\n  }))\n}\n\n/**\n * The cursor a page hands back, from the last row on it.\n *\n * Null when the row carries no `suppressedAt` — every entry written since\n * AGL-1918 does, and `orderBy` has already excluded any that does not, so\n * this is the type narrowing rather than a case that occurs.\n */\nexport function suppressionCursorFrom(\n  record: Record<string, any> | null | undefined,\n): string | null {\n  const at = record?.['suppressedAt'] as\n    | { seconds?: number; _seconds?: number; nanoseconds?: number; _nanoseconds?: number }\n    | undefined\n  const seconds = at?.seconds ?? at?._seconds\n  if (typeof seconds !== 'number') return null\n  const nanoseconds = at?.nanoseconds ?? at?._nanoseconds ?? 0\n  return `${seconds}.${nanoseconds}`\n}\n\n/** The inverse, for the query. Invalid input yields no cursor, never a guess. */\nexport function suppressionCursorTimestamp(\n  cursor: string | null | undefined,\n): Timestamp | null {\n  const [rawSeconds, rawNanos] = String(cursor ?? '').split('.')\n  const seconds = Number(rawSeconds)\n  const nanoseconds = Number(rawNanos ?? 0)\n  if (!Number.isFinite(seconds) || !seconds) return null\n  return new Timestamp(seconds, Number.isFinite(nanoseconds) ? nanoseconds : 0)\n}\n\n/*==========================================\n * THE ERASURE ROW ON THE PER-SITE LIST (AGL-2623).\n *\n * A person erased from a workspace must not be quietly rebuilt by the next\n * form they fill in or the next order they place, and must not be mailed by\n * a campaign either. Both gates already read `hosts/{hostId}/suppressions`\n * — every campaign filter refuses an address with a row there — so the\n * erasure writes one row per site of the workspace rather than inventing a\n * third list, and the capture door reads the same row.\n *\n * The row carries NO address. Every other writer of this list stores the\n * email in the clear beside the hash, because a hub admin releasing an\n * unsubscribe needs to see who it was; an erasure row is the one whose\n * whole purpose is that the address is no longer held, so the id — the\n * hash — is the entire record, and a row that already held the address in\n * the clear has it removed. The hub's list renders such a row as an entry\n * with no address, which it already knows how to do.\n *\n * Per SITE, not platform-wide, on purpose: the erasure was asked of one\n * workspace, and a second workspace that knows the same person has a\n * relationship this request has no claim on. The platform list is for\n * bounces and complaints, which are facts about the address everywhere.\n *=========================================*/\n\n/** The `reason` an erasure row carries. Read by the capture door, below. */\nexport const HOST_ERASURE_SUPPRESSION_REASON = 'erasure'\n\n/**\n * Suppress an address on one site because the person was erased. Idempotent:\n * a second erasure of the same person merges onto the same row.\n */\nexport async function suppressEmailForHostErasure(input: {\n  hostId: string\n  email: string\n  firestore?: any\n}): Promise<{ key: string; created: boolean } | null> {\n  const key = emailSuppressionKey(input.email)\n  if (!key) return null\n  const db = input.firestore ?? defaultFirestore()\n  const ref = db\n    .collection('hosts')\n    .doc(input.hostId)\n    .collection(HOST_SUPPRESSIONS_SUBCOLLECTION)\n    .doc(key)\n  const snapshot = await ref.get()\n  await ref.set(\n    {\n      email: null,\n      reason: HOST_ERASURE_SUPPRESSION_REASON,\n      suppressedAt: FieldValue.serverTimestamp(),\n      ...(snapshot.exists ? {} : { createdAt: FieldValue.serverTimestamp() }),\n    },\n    { merge: true },\n  )\n  return { key, created: !snapshot.exists }\n}\n\n/**\n * Whether a site has erased this address, so a capture must not create a\n * contact for it. Only an ERASURE row refuses: an ordinary unsubscribe is a\n * mailing preference, and a person who unsubscribed and then bought\n * something is still a customer whose order the CRM should know about.\n *\n * Fails OPEN. A read that throws answers `false` and logs: the alternative\n * refuses every capture on the site for as long as the list is unreadable,\n * which turns a transient read failure into a silent drop of the site's\n * leads and orders. The window this leaves — a recreate during an outage\n * of the suppression read — is logged, and the next erasure run finds the\n * recreated record by the same address.\n */\nexport async function hostRefusesCaptureForErasure(\n  hostId: string,\n  email: string | null | undefined,\n  injectedFirestore?: any,\n): Promise<boolean> {\n  const key = emailSuppressionKey(email)\n  if (!key) return false\n  try {\n    const db = injectedFirestore ?? defaultFirestore()\n    const snapshot = await db\n      .collection('hosts')\n      .doc(hostId)\n      .collection(HOST_SUPPRESSIONS_SUBCOLLECTION)\n      .doc(key)\n      .get()\n    return (\n      Boolean(snapshot?.exists) &&\n      snapshot.get('reason') === HOST_ERASURE_SUPPRESSION_REASON\n    )\n  } catch (error) {\n    console.error(\n      '[email-suppression] erasure lookup failed; the capture proceeds',\n      error,\n    )\n    return false\n  }\n}\n"],"names":["FieldValue","Timestamp","readTopicSubscriptionState","TOPIC_OPT_OUTS_SUBCOLLECTION","personKey","firebaseAdmin","defaultFirestore","app","firestore","EMAIL_SUPPRESSIONS_COLLECTION","HOST_SUPPRESSIONS_SUBCOLLECTION","PLATFORM_SUPPRESSION_REASONS","UNSUBSCRIBE_SUPPRESSION_REASON","emailSuppressionKey","email","suppressEmail","input","key","Error","includes","reason","db","ref","collection","doc","snapshot","get","set","String","trim","toLowerCase","context","hostId","releasedAt","suppressedAt","serverTimestamp","exists","createdAt","merge","created","releaseEmail","releasedByUid","releasedNote","note","releasedVia","OPT_IN_RELEASABLE_REASONS","releaseEmailForConfirmedOptIn","releasedHostId","releasedTopicId","topicId","error","console","isEmailSuppressed","injectedFirestore","filterSuppressedEmails","emails","seen","Set","candidates","normalized","has","add","push","verdicts","Promise","all","map","filter","_email","index","filterSendableForHost","platformSendable","length","hostList","keyed","snapshots","getAll","entry","_entry","filterTopicSendable","topic","lookups","optOuts","gone","forEach","record","listEmailSuppressions","options","query","orderBy","cursor","suppressionCursorTimestamp","startAfter","limit","Math","min","max","docs","$id","id","data","suppressionCursorFrom","at","seconds","_seconds","nanoseconds","_nanoseconds","rawSeconds","rawNanos","split","Number","isFinite","HOST_ERASURE_SUPPRESSION_REASON","suppressEmailForHostErasure","hostRefusesCaptureForErasure","Boolean"],"mappings":"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"}

package/src/lib/server/email-topic-confirmation.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @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.
+ */
+/** What asking for a confirmation did. */
+export type PendingConfirmationResult = 
+/** Recorded. The address is not mailable about this topic until confirmed. */
+'pending'
+/** Already confirmed, or never needed confirming. Nothing was written. */
+ | 'already-subscribed'
+/**
+ * They left this stream. Nothing was written and nothing may be sent.
+ *
+ * A signup form cannot re-arm mail to somebody who unsubscribed by asking
+ * them again: the confirmation request is itself a message, and sending it
+ * would be mailing somebody who told this site to stop.
+ */
+ | 'opted-out'
+/** Not an address, or not a topic id. */
+ | 'unusable';
+/**
+ * Puts an address in the quarantine for one topic and returns the moment it
+ * entered, which is what the confirmation link is signed and dated from.
+ *
+ * ## Re-asking does not restamp
+ *
+ * A second signup from the same address inside the window keeps the original
+ * `pendingAt`, so the 72-hour expiry measures from when we first asked. The
+ * alternative lets somebody — or a script — hold an address in a permanently
+ * fresh pending state by resubmitting a form, which is a way to keep a
+ * confirmation link alive indefinitely.
+ */
+export declare function recordPendingTopicConfirmation(hostId: string, email: string, topicId: string, options?: {
+    nowMs?: number;
+    firestore?: any;
+}): Promise<{
+    result: PendingConfirmationResult;
+    pendingAtMs: number | null;
+}>;
+/** What a click on a confirmation link did. */
+export type ConfirmTopicResult = 
+/** They are now a subscriber to this topic. */
+'confirmed'
+/** They already were, and a second click changes nothing. */
+ | 'already-confirmed'
+/** The request is older than the window, so the link no longer acts. */
+ | 'expired'
+/** They left this stream. A confirmation link may not undo that. */
+ | 'opted-out'
+/** Nothing was pending for this address and topic. */
+ | 'not-pending'
+/** Not an address, or not a topic id. */
+ | 'unusable';
+/**
+ * Honors a confirmation click.
+ *
+ * ## An expired link does not admit anybody, and does not clear anything
+ *
+ * `expired` leaves the record exactly as it was: still pending, still
+ * unmailable. Expiry is a property of the LINK, and a lapse that quietly
+ * admitted the address, or quietly cleared the request, would make the window
+ * a delay somebody could wait out rather than a gate.
+ *
+ * ## A confirmation cannot reverse an unsubscribe
+ *
+ * Same rule as `releaseSiteSuppression`: the recipient's later, more explicit
+ * act stands, and a link minted before it must not undo it.
+ *
+ * ## A confirmation DOES reverse a hard bounce
+ *
+ * The one thing a completed round trip is evidence of. A `bounce` entry on
+ * the platform list claims mail addressed here is permanently refused, and a
+ * click on a link that was delivered to that mailbox is the only evidence
+ * that could refute it. Without this, an address recorded as permanently
+ * bounced — often a full mailbox or a misconfigured receiving server that a
+ * provider reported as permanent — can never re-subscribe by any route, and
+ * the double opt-in it just completed would enrol somebody the send path then
+ * silently drops.
+ *
+ * The refusal above and the release here are the same rule seen from two
+ * sides: a stated intention stands and a measurement does not. Which reasons
+ * qualify is decided by `OPT_IN_RELEASABLE_REASONS`, not here — an unsubscribe
+ * or a spam complaint is never among them, or this function would be a way to
+ * launder a complaint through a signup form.
+ *
+ * The release is best-effort and deliberately after the transaction: the
+ * confirmation is what the person is waiting for, and a suppression list that
+ * could not be written must not cost them the subscription they just made.
+ */
+export declare function confirmTopicSubscription(hostId: string, email: string, topicId: string, options?: {
+    nowMs?: number;
+    firestore?: any;
+}): Promise<ConfirmTopicResult>;
+/**
+ * Whether this site confirms new subscriptions by default.
+ *
+ * One host-document field, read at the moment somebody signs up and nowhere
+ * else — the send path never asks, because by then the answer is already on
+ * the person's own record as a pending mark or its absence. A read on every
+ * send would be a read per recipient to re-derive a decision that was made
+ * once.
+ *
+ * Fails to `false`, which is off. A default that a failed read could switch
+ * ON would quarantine every new signup on a site whose owner never asked for
+ * confirmations, and they would have no way to tell why their list stopped
+ * growing.
+ */
+export declare function siteRequiresDoubleOptIn(hostId: string, firestore?: any): Promise<boolean>;
+/** What asking to leave one topic did. */
+export type TopicOptOutResult = 
+/** Recorded now. The address is not mailable about this topic. */
+'opted-out'
+/** They had already left it; the moment they left is kept. */
+ | 'already-opted-out'
+/** Not an address, or not a topic id. Nothing was written. */
+ | 'unusable';
+/**
+ * Takes one address off one topic on one site (AGL-2981) — the opt-out a
+ * sender that is not the preference page records: a sales email's
+ * unsubscribe link, a reply that asks to be left alone.
+ *
+ * The same record the preference page writes (`writeTopicOptOuts` in the
+ * email plugin) and the send path reads, on the same rules:
+ *
+ *  - an address that already left keeps the moment it left — a second
+ *    request is not a later one;
+ *  - the entry is carried forward rather than replaced, so a confirmation
+ *    the person once gave stays on the record beside the opt-out;
+ *  - a rejoin stamped earlier is cleared, because leaving is now the more
+ *    recent act.
+ *
+ * A transaction, and its verdict comes out of it rather than through a
+ * variable beside it: a retried attempt must not describe itself as the one
+ * that committed.
+ */
+export declare function recordTopicOptOut(hostId: string, email: string, topicId: string, options?: {
+    firestore?: any;
+}): Promise<TopicOptOutResult>;

package/src/lib/server/email-topic-confirmation.js

@@ -0,0 +1,272 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ /**
+ * DOUBLE OPT-IN — the durable half.
+ *
+ * `email-topics.ts` in the framework states the policy and owns the three
+ * states an entry can be in; this writes them, because writing them needs
+ * Firestore.
+ *
+ * ## The record it writes is the one the send path already reads
+ *
+ * `hosts/{hostId}/topicOptOuts/{emailKey}` holds a map keyed by topic, and
+ * `filterTopicSendable` reads it on every topic-filtered send. A pending
+ * confirmation is therefore a THIRD state of a fact the send path already
+ * consults rather than a new document nobody has a reason to look at — which
+ * is the difference between ActiveCampaign's quarantine, where an unconfirmed
+ * subscriber genuinely cannot be mailed, and Customer.io's recipe, whose own
+ * documentation warns that it "doesn't automatically check this attribute
+ * before sending messages".
+ *
+ * ## Nothing here is a deletion
+ *
+ * A confirmation stamps `confirmedAt` beside the `pendingAt` it answers,
+ * rather than clearing the pending mark. The pair IS the evidence — when we
+ * asked and when they answered — and it is the evidence a consent question
+ * needs, which is the same argument `writeTopicOptOuts` makes for keeping an
+ * opt-out entry after somebody rejoins.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { doubleOptInExpired, readTopicSubscriptionState, TOPIC_OPT_OUTS_SUBCOLLECTION } from "@aglyn/aglyn/app-utils/email-topics";
+import { isEmailTopicId } from "@aglyn/aglyn/app-utils/email-topics";
+import firebaseAdmin from "./firebase-admin.js";
+import { emailSuppressionKey, releaseEmailForConfirmedOptIn } from "./email-suppression.js";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+function optOutDoc(hostId, key, firestore) {
+    return (firestore != null ? firestore : defaultFirestore()).collection('hosts').doc(hostId).collection(TOPIC_OPT_OUTS_SUBCOLLECTION).doc(key);
+}
+/**
+ * Puts an address in the quarantine for one topic and returns the moment it
+ * entered, which is what the confirmation link is signed and dated from.
+ *
+ * ## Re-asking does not restamp
+ *
+ * A second signup from the same address inside the window keeps the original
+ * `pendingAt`, so the 72-hour expiry measures from when we first asked. The
+ * alternative lets somebody — or a script — hold an address in a permanently
+ * fresh pending state by resubmitting a form, which is a way to keep a
+ * confirmation link alive indefinitely.
+ */ export async function recordPendingTopicConfirmation(hostId, email, topicId, options) {
+    var _ref, _ref1;
+    const key = emailSuppressionKey(email);
+    if (!key || !hostId || !isEmailTopicId(topicId)) {
+        return {
+            result: 'unusable',
+            pendingAtMs: null
+        };
+    }
+    const nowMs = (_ref = options == null ? void 0 : options.nowMs) != null ? _ref : Date.now();
+    const ref = optOutDoc(hostId, key, options == null ? void 0 : options.firestore);
+    const address = String(email).trim().toLowerCase();
+    let result = 'pending';
+    let pendingAtMs = nowMs;
+    await ((_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : defaultFirestore()).runTransaction(async (transaction)=>{
+        var _ref;
+        const snapshot = await transaction.get(ref);
+        const stored = (_ref = snapshot.exists ? snapshot.get('topics') : null) != null ? _ref : {};
+        const existing = stored[topicId];
+        const state = readTopicSubscriptionState(existing);
+        if (state === 'opted-out') {
+            result = 'opted-out';
+            pendingAtMs = null;
+            return;
+        }
+        if (state === 'pending') {
+            // Already in the quarantine. Keep the original moment — see above.
+            result = 'pending';
+            pendingAtMs = Number(existing == null ? void 0 : existing.pendingAt) || nowMs;
+            return;
+        }
+        if (existing == null ? void 0 : existing.confirmedAt) {
+            result = 'already-subscribed';
+            pendingAtMs = null;
+            return;
+        }
+        transaction.set(ref, _extends({
+            email: address,
+            topics: _extends({}, stored, {
+                [topicId]: _extends({}, existing != null ? existing : {}, {
+                    pendingAt: nowMs,
+                    confirmedAt: null
+                })
+            }),
+            updatedAt: FieldValue.serverTimestamp()
+        }, snapshot.exists ? {} : {
+            createdAt: FieldValue.serverTimestamp()
+        }), {
+            merge: true
+        });
+    });
+    return {
+        result,
+        pendingAtMs
+    };
+}
+/**
+ * Honors a confirmation click.
+ *
+ * ## An expired link does not admit anybody, and does not clear anything
+ *
+ * `expired` leaves the record exactly as it was: still pending, still
+ * unmailable. Expiry is a property of the LINK, and a lapse that quietly
+ * admitted the address, or quietly cleared the request, would make the window
+ * a delay somebody could wait out rather than a gate.
+ *
+ * ## A confirmation cannot reverse an unsubscribe
+ *
+ * Same rule as `releaseSiteSuppression`: the recipient's later, more explicit
+ * act stands, and a link minted before it must not undo it.
+ *
+ * ## A confirmation DOES reverse a hard bounce
+ *
+ * The one thing a completed round trip is evidence of. A `bounce` entry on
+ * the platform list claims mail addressed here is permanently refused, and a
+ * click on a link that was delivered to that mailbox is the only evidence
+ * that could refute it. Without this, an address recorded as permanently
+ * bounced — often a full mailbox or a misconfigured receiving server that a
+ * provider reported as permanent — can never re-subscribe by any route, and
+ * the double opt-in it just completed would enrol somebody the send path then
+ * silently drops.
+ *
+ * The refusal above and the release here are the same rule seen from two
+ * sides: a stated intention stands and a measurement does not. Which reasons
+ * qualify is decided by `OPT_IN_RELEASABLE_REASONS`, not here — an unsubscribe
+ * or a spam complaint is never among them, or this function would be a way to
+ * launder a complaint through a signup form.
+ *
+ * The release is best-effort and deliberately after the transaction: the
+ * confirmation is what the person is waiting for, and a suppression list that
+ * could not be written must not cost them the subscription they just made.
+ */ export async function confirmTopicSubscription(hostId, email, topicId, options) {
+    var _ref, _ref1;
+    const key = emailSuppressionKey(email);
+    if (!key || !hostId || !isEmailTopicId(topicId)) return 'unusable';
+    const nowMs = (_ref = options == null ? void 0 : options.nowMs) != null ? _ref : Date.now();
+    const ref = optOutDoc(hostId, key, options == null ? void 0 : options.firestore);
+    /*
+   * The verdict comes OUT of the transaction rather than through a closure
+   * variable beside it. A transaction body can be retried, so a variable the
+   * caller reads afterwards describes whichever attempt ran last rather than
+   * the one that committed.
+   */ const result = await ((_ref1 = options == null ? void 0 : options.firestore) != null ? _ref1 : defaultFirestore()).runTransaction(async (transaction)=>{
+        var _ref;
+        const snapshot = await transaction.get(ref);
+        const stored = (_ref = snapshot.exists ? snapshot.get('topics') : null) != null ? _ref : {};
+        const existing = stored[topicId];
+        const state = readTopicSubscriptionState(existing);
+        if (state === 'opted-out') return 'opted-out';
+        if (state === 'subscribed') {
+            return (existing == null ? void 0 : existing.confirmedAt) ? 'already-confirmed' : 'not-pending';
+        }
+        if (doubleOptInExpired(Number(existing == null ? void 0 : existing.pendingAt), nowMs)) {
+            return 'expired';
+        }
+        transaction.set(ref, {
+            email: String(email).trim().toLowerCase(),
+            topics: _extends({}, stored, {
+                [topicId]: _extends({}, existing != null ? existing : {}, {
+                    confirmedAt: nowMs
+                })
+            }),
+            updatedAt: FieldValue.serverTimestamp()
+        }, {
+            merge: true
+        });
+        return 'confirmed';
+    });
+    if (result === 'confirmed') {
+        await releaseEmailForConfirmedOptIn(_extends({
+            email,
+            hostId,
+            topicId
+        }, (options == null ? void 0 : options.firestore) ? {
+            firestore: options.firestore
+        } : {}));
+    }
+    return result;
+}
+/**
+ * Whether this site confirms new subscriptions by default.
+ *
+ * One host-document field, read at the moment somebody signs up and nowhere
+ * else — the send path never asks, because by then the answer is already on
+ * the person's own record as a pending mark or its absence. A read on every
+ * send would be a read per recipient to re-derive a decision that was made
+ * once.
+ *
+ * Fails to `false`, which is off. A default that a failed read could switch
+ * ON would quarantine every new signup on a site whose owner never asked for
+ * confirmations, and they would have no way to tell why their list stopped
+ * growing.
+ */ export async function siteRequiresDoubleOptIn(hostId, firestore) {
+    if (!hostId) return false;
+    try {
+        const snapshot = await (firestore != null ? firestore : defaultFirestore()).collection('hosts').doc(hostId).get();
+        return snapshot.exists && snapshot.get('emailDoubleOptIn') === true;
+    } catch (error) {
+        console.error('[email-topics] double opt-in setting read failed', error);
+        return false;
+    }
+}
+/**
+ * Takes one address off one topic on one site (AGL-2981) — the opt-out a
+ * sender that is not the preference page records: a sales email's
+ * unsubscribe link, a reply that asks to be left alone.
+ *
+ * The same record the preference page writes (`writeTopicOptOuts` in the
+ * email plugin) and the send path reads, on the same rules:
+ *
+ *  - an address that already left keeps the moment it left — a second
+ *    request is not a later one;
+ *  - the entry is carried forward rather than replaced, so a confirmation
+ *    the person once gave stays on the record beside the opt-out;
+ *  - a rejoin stamped earlier is cleared, because leaving is now the more
+ *    recent act.
+ *
+ * A transaction, and its verdict comes out of it rather than through a
+ * variable beside it: a retried attempt must not describe itself as the one
+ * that committed.
+ */ export async function recordTopicOptOut(hostId, email, topicId, options) {
+    var _ref;
+    const key = emailSuppressionKey(email);
+    if (!key || !hostId || !isEmailTopicId(topicId)) return 'unusable';
+    const db = (_ref = options == null ? void 0 : options.firestore) != null ? _ref : defaultFirestore();
+    const ref = optOutDoc(hostId, key, db);
+    return db.runTransaction(async (transaction)=>{
+        var _ref;
+        const snapshot = await transaction.get(ref);
+        const stored = (_ref = snapshot.exists ? snapshot.get('topics') : null) != null ? _ref : {};
+        const previous = stored[topicId];
+        if (readTopicSubscriptionState(previous) === 'opted-out') return 'already-opted-out';
+        transaction.set(ref, _extends({
+            email: String(email).trim().toLowerCase(),
+            topics: _extends({}, stored, {
+                [topicId]: _extends({}, previous != null ? previous : {}, {
+                    optedOutAt: FieldValue.serverTimestamp(),
+                    resubscribedAt: null
+                })
+            }),
+            updatedAt: FieldValue.serverTimestamp()
+        }, snapshot.exists ? {} : {
+            createdAt: FieldValue.serverTimestamp()
+        }), {
+            merge: true
+        });
+        return 'opted-out';
+    });
+}
+
+//# sourceMappingURL=email-topic-confirmation.js.map

package/src/lib/server/email-topic-confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/email-topic-confirmation.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 * DOUBLE OPT-IN — the durable half.\n *\n * `email-topics.ts` in the framework states the policy and owns the three\n * states an entry can be in; this writes them, because writing them needs\n * Firestore.\n *\n * ## The record it writes is the one the send path already reads\n *\n * `hosts/{hostId}/topicOptOuts/{emailKey}` holds a map keyed by topic, and\n * `filterTopicSendable` reads it on every topic-filtered send. A pending\n * confirmation is therefore a THIRD state of a fact the send path already\n * consults rather than a new document nobody has a reason to look at — which\n * is the difference between ActiveCampaign's quarantine, where an unconfirmed\n * subscriber genuinely cannot be mailed, and Customer.io's recipe, whose own\n * documentation warns that it \"doesn't automatically check this attribute\n * before sending messages\".\n *\n * ## Nothing here is a deletion\n *\n * A confirmation stamps `confirmedAt` beside the `pendingAt` it answers,\n * rather than clearing the pending mark. The pair IS the evidence — when we\n * asked and when they answered — and it is the evidence a consent question\n * needs, which is the same argument `writeTopicOptOuts` makes for keeping an\n * opt-out entry after somebody rejoins.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  doubleOptInExpired,\n  readTopicSubscriptionState,\n  TOPIC_OPT_OUTS_SUBCOLLECTION,\n  type TopicSubscriptionEntry,\n} from '@aglyn/aglyn/app-utils/email-topics'\nimport { isEmailTopicId } from '@aglyn/aglyn/app-utils/email-topics'\nimport firebaseAdmin from './firebase-admin'\nimport {\n  emailSuppressionKey,\n  releaseEmailForConfirmedOptIn,\n} from './email-suppression'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\nfunction optOutDoc(hostId: string, key: string, firestore?: any) {\n  return (firestore ?? defaultFirestore())\n    .collection('hosts')\n    .doc(hostId)\n    .collection(TOPIC_OPT_OUTS_SUBCOLLECTION)\n    .doc(key)\n}\n\n/** What asking for a confirmation did. */\nexport type PendingConfirmationResult =\n  /** Recorded. The address is not mailable about this topic until confirmed. */\n  | 'pending'\n  /** Already confirmed, or never needed confirming. Nothing was written. */\n  | 'already-subscribed'\n  /**\n   * They left this stream. Nothing was written and nothing may be sent.\n   *\n   * A signup form cannot re-arm mail to somebody who unsubscribed by asking\n   * them again: the confirmation request is itself a message, and sending it\n   * would be mailing somebody who told this site to stop.\n   */\n  | 'opted-out'\n  /** Not an address, or not a topic id. */\n  | 'unusable'\n\n/**\n * Puts an address in the quarantine for one topic and returns the moment it\n * entered, which is what the confirmation link is signed and dated from.\n *\n * ## Re-asking does not restamp\n *\n * A second signup from the same address inside the window keeps the original\n * `pendingAt`, so the 72-hour expiry measures from when we first asked. The\n * alternative lets somebody — or a script — hold an address in a permanently\n * fresh pending state by resubmitting a form, which is a way to keep a\n * confirmation link alive indefinitely.\n */\nexport async function recordPendingTopicConfirmation(\n  hostId: string,\n  email: string,\n  topicId: string,\n  options?: { nowMs?: number; firestore?: any },\n): Promise<{ result: PendingConfirmationResult; pendingAtMs: number | null }> {\n  const key = emailSuppressionKey(email)\n  if (!key || !hostId || !isEmailTopicId(topicId)) {\n    return { result: 'unusable', pendingAtMs: null }\n  }\n  const nowMs = options?.nowMs ?? Date.now()\n  const ref = optOutDoc(hostId, key, options?.firestore)\n  const address = String(email).trim().toLowerCase()\n  let result: PendingConfirmationResult = 'pending'\n  let pendingAtMs: number | null = nowMs\n  await (options?.firestore ?? defaultFirestore()).runTransaction(\n    async (transaction: any) => {\n      const snapshot = await transaction.get(ref)\n      const stored = ((snapshot.exists ? snapshot.get('topics') : null) ??\n        {}) as Record<string, TopicSubscriptionEntry>\n      const existing = stored[topicId]\n      const state = readTopicSubscriptionState(existing)\n      if (state === 'opted-out') {\n        result = 'opted-out'\n        pendingAtMs = null\n        return\n      }\n      if (state === 'pending') {\n        // Already in the quarantine. Keep the original moment — see above.\n        result = 'pending'\n        pendingAtMs = Number(existing?.pendingAt) || nowMs\n        return\n      }\n      if (existing?.confirmedAt) {\n        result = 'already-subscribed'\n        pendingAtMs = null\n        return\n      }\n      transaction.set(\n        ref,\n        {\n          email: address,\n          topics: {\n            ...stored,\n            [topicId]: {\n              ...(existing ?? {}),\n              pendingAt: nowMs,\n              confirmedAt: null,\n            },\n          },\n          updatedAt: FieldValue.serverTimestamp(),\n          ...(snapshot.exists\n            ? {}\n            : { createdAt: FieldValue.serverTimestamp() }),\n        },\n        { merge: true },\n      )\n    },\n  )\n  return { result, pendingAtMs }\n}\n\n/** What a click on a confirmation link did. */\nexport type ConfirmTopicResult =\n  /** They are now a subscriber to this topic. */\n  | 'confirmed'\n  /** They already were, and a second click changes nothing. */\n  | 'already-confirmed'\n  /** The request is older than the window, so the link no longer acts. */\n  | 'expired'\n  /** They left this stream. A confirmation link may not undo that. */\n  | 'opted-out'\n  /** Nothing was pending for this address and topic. */\n  | 'not-pending'\n  /** Not an address, or not a topic id. */\n  | 'unusable'\n\n/**\n * Honors a confirmation click.\n *\n * ## An expired link does not admit anybody, and does not clear anything\n *\n * `expired` leaves the record exactly as it was: still pending, still\n * unmailable. Expiry is a property of the LINK, and a lapse that quietly\n * admitted the address, or quietly cleared the request, would make the window\n * a delay somebody could wait out rather than a gate.\n *\n * ## A confirmation cannot reverse an unsubscribe\n *\n * Same rule as `releaseSiteSuppression`: the recipient's later, more explicit\n * act stands, and a link minted before it must not undo it.\n *\n * ## A confirmation DOES reverse a hard bounce\n *\n * The one thing a completed round trip is evidence of. A `bounce` entry on\n * the platform list claims mail addressed here is permanently refused, and a\n * click on a link that was delivered to that mailbox is the only evidence\n * that could refute it. Without this, an address recorded as permanently\n * bounced — often a full mailbox or a misconfigured receiving server that a\n * provider reported as permanent — can never re-subscribe by any route, and\n * the double opt-in it just completed would enrol somebody the send path then\n * silently drops.\n *\n * The refusal above and the release here are the same rule seen from two\n * sides: a stated intention stands and a measurement does not. Which reasons\n * qualify is decided by `OPT_IN_RELEASABLE_REASONS`, not here — an unsubscribe\n * or a spam complaint is never among them, or this function would be a way to\n * launder a complaint through a signup form.\n *\n * The release is best-effort and deliberately after the transaction: the\n * confirmation is what the person is waiting for, and a suppression list that\n * could not be written must not cost them the subscription they just made.\n */\nexport async function confirmTopicSubscription(\n  hostId: string,\n  email: string,\n  topicId: string,\n  options?: { nowMs?: number; firestore?: any },\n): Promise<ConfirmTopicResult> {\n  const key = emailSuppressionKey(email)\n  if (!key || !hostId || !isEmailTopicId(topicId)) return 'unusable'\n  const nowMs = options?.nowMs ?? Date.now()\n  const ref = optOutDoc(hostId, key, options?.firestore)\n  /*\n   * The verdict comes OUT of the transaction rather than through a closure\n   * variable beside it. A transaction body can be retried, so a variable the\n   * caller reads afterwards describes whichever attempt ran last rather than\n   * the one that committed.\n   */\n  const result: ConfirmTopicResult = await (\n    options?.firestore ?? defaultFirestore()\n  ).runTransaction(async (transaction: any): Promise<ConfirmTopicResult> => {\n    const snapshot = await transaction.get(ref)\n    const stored = ((snapshot.exists ? snapshot.get('topics') : null) ??\n      {}) as Record<string, TopicSubscriptionEntry>\n    const existing = stored[topicId]\n    const state = readTopicSubscriptionState(existing)\n    if (state === 'opted-out') return 'opted-out'\n    if (state === 'subscribed') {\n      return existing?.confirmedAt ? 'already-confirmed' : 'not-pending'\n    }\n    if (doubleOptInExpired(Number(existing?.pendingAt), nowMs)) {\n      return 'expired'\n    }\n    transaction.set(\n      ref,\n      {\n        email: String(email).trim().toLowerCase(),\n        topics: {\n          ...stored,\n          [topicId]: { ...(existing ?? {}), confirmedAt: nowMs },\n        },\n        updatedAt: FieldValue.serverTimestamp(),\n      },\n      { merge: true },\n    )\n    return 'confirmed'\n  })\n  if (result === 'confirmed') {\n    await releaseEmailForConfirmedOptIn({\n      email,\n      hostId,\n      topicId,\n      ...(options?.firestore ? { firestore: options.firestore } : {}),\n    })\n  }\n  return result\n}\n\n/**\n * Whether this site confirms new subscriptions by default.\n *\n * One host-document field, read at the moment somebody signs up and nowhere\n * else — the send path never asks, because by then the answer is already on\n * the person's own record as a pending mark or its absence. A read on every\n * send would be a read per recipient to re-derive a decision that was made\n * once.\n *\n * Fails to `false`, which is off. A default that a failed read could switch\n * ON would quarantine every new signup on a site whose owner never asked for\n * confirmations, and they would have no way to tell why their list stopped\n * growing.\n */\nexport async function siteRequiresDoubleOptIn(\n  hostId: string,\n  firestore?: any,\n): Promise<boolean> {\n  if (!hostId) return false\n  try {\n    const snapshot = await (firestore ?? defaultFirestore())\n      .collection('hosts')\n      .doc(hostId)\n      .get()\n    return snapshot.exists && snapshot.get('emailDoubleOptIn') === true\n  } catch (error) {\n    console.error('[email-topics] double opt-in setting read failed', error)\n    return false\n  }\n}\n\n/** What asking to leave one topic did. */\nexport type TopicOptOutResult =\n  /** Recorded now. The address is not mailable about this topic. */\n  | 'opted-out'\n  /** They had already left it; the moment they left is kept. */\n  | 'already-opted-out'\n  /** Not an address, or not a topic id. Nothing was written. */\n  | 'unusable'\n\n/**\n * Takes one address off one topic on one site (AGL-2981) — the opt-out a\n * sender that is not the preference page records: a sales email's\n * unsubscribe link, a reply that asks to be left alone.\n *\n * The same record the preference page writes (`writeTopicOptOuts` in the\n * email plugin) and the send path reads, on the same rules:\n *\n *  - an address that already left keeps the moment it left — a second\n *    request is not a later one;\n *  - the entry is carried forward rather than replaced, so a confirmation\n *    the person once gave stays on the record beside the opt-out;\n *  - a rejoin stamped earlier is cleared, because leaving is now the more\n *    recent act.\n *\n * A transaction, and its verdict comes out of it rather than through a\n * variable beside it: a retried attempt must not describe itself as the one\n * that committed.\n */\nexport async function recordTopicOptOut(\n  hostId: string,\n  email: string,\n  topicId: string,\n  options?: { firestore?: any },\n): Promise<TopicOptOutResult> {\n  const key = emailSuppressionKey(email)\n  if (!key || !hostId || !isEmailTopicId(topicId)) return 'unusable'\n  const db = options?.firestore ?? defaultFirestore()\n  const ref = optOutDoc(hostId, key, db)\n  return db.runTransaction(async (transaction: any): Promise<TopicOptOutResult> => {\n    const snapshot = await transaction.get(ref)\n    const stored = ((snapshot.exists ? snapshot.get('topics') : null) ??\n      {}) as Record<string, TopicSubscriptionEntry>\n    const previous = stored[topicId]\n    if (readTopicSubscriptionState(previous) === 'opted-out') return 'already-opted-out'\n    transaction.set(\n      ref,\n      {\n        email: String(email).trim().toLowerCase(),\n        topics: {\n          ...stored,\n          [topicId]: {\n            ...(previous ?? {}),\n            optedOutAt: FieldValue.serverTimestamp(),\n            resubscribedAt: null,\n          },\n        },\n        updatedAt: FieldValue.serverTimestamp(),\n        ...(snapshot.exists ? {} : { createdAt: FieldValue.serverTimestamp() }),\n      },\n      { merge: true },\n    )\n    return 'opted-out'\n  })\n}\n"],"names":["FieldValue","doubleOptInExpired","readTopicSubscriptionState","TOPIC_OPT_OUTS_SUBCOLLECTION","isEmailTopicId","firebaseAdmin","emailSuppressionKey","releaseEmailForConfirmedOptIn","defaultFirestore","app","firestore","optOutDoc","hostId","key","collection","doc","recordPendingTopicConfirmation","email","topicId","options","result","pendingAtMs","nowMs","Date","now","ref","address","String","trim","toLowerCase","runTransaction","transaction","snapshot","get","stored","exists","existing","state","Number","pendingAt","confirmedAt","set","topics","updatedAt","serverTimestamp","createdAt","merge","confirmTopicSubscription","siteRequiresDoubleOptIn","error","console","recordTopicOptOut","db","previous","optedOutAt","resubscribedAt"],"mappings":"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"}