@aglyn/plugins-marketing 1.0.0-beta.143

package/src/lib/server/email-campaign-reach.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @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.
+ */
+/**
+ * Where the record lives: beside the link rollup, under the send it belongs
+ * to.
+ *
+ * A subcollection document rather than a field on the send, for the reason
+ * the link rollup is one — the send document is read by the emails list, the
+ * glance widget and the send path, and a set that grows with the audience on
+ * it would make every one of those reads larger.
+ */
+export declare const CAMPAIGN_REACH_DOC = "reached";
+/** The subcollection the link rollup already uses. */
+export declare const CAMPAIGN_REACH_SUBCOLLECTION = "reports";
+/**
+ * The most people one email may reach across all of its sends.
+ *
+ * The sender's audience read budget, taken from the one place it is stated
+ * rather than restated here. See the header for why the two are necessarily
+ * the same number: an email cannot reach more people than one resolution of
+ * its audience can hold.
+ */
+export declare const CAMPAIGN_REACH_CEILING = 5000;
+/** The stored document. */
+export interface CampaignReachRecord {
+    /** `sha256` of each normalized address this email has reached. */
+    keys: string[];
+    /** `keys.length`, so a reader can size the record without loading it. */
+    count: number;
+    /**
+     * `sha256` of each address a send CONSIDERED and did not mail — suppressed,
+     * or gone from the topic the email opens on.
+     *
+     * See {@link readCampaignSettled} for why a batched send needs this and a
+     * merchant's follow-up must not read it.
+     */
+    skipped?: string[];
+    /** `skipped.length`, alongside `count` for the same reason. */
+    skippedCount?: number;
+}
+/**
+ * Everything one send of this email has DECIDED about, either way.
+ *
+ * `reached` is who got it. `skipped` is who was addressed by a batch, refused
+ * by a suppression list or a topic opt-out, and must not consume a slot in
+ * every later batch of the same email.
+ */
+export interface CampaignSettledRecord {
+    reached: Set<string>;
+    skipped: Set<string>;
+}
+/**
+ * The keys of everyone this email has reached.
+ *
+ * FAILS CLOSED — it throws rather than answering "nobody". The asymmetry with
+ * {@link readMarketingFrequency}, which fails open, is the same one
+ * `filterSendableForHost` draws: a frequency window that cannot be read
+ * refuses a message nobody objected to, where a reach record that cannot be
+ * read would mail somebody a second copy of a message they already have. A
+ * follow-up is a discretionary act a merchant can repeat in a minute; a
+ * duplicate in a stranger's inbox is not retractable.
+ *
+ * @throws when the record cannot be read.
+ */
+export declare function readCampaignReach(hostId: string, sendId: string, firestore?: any): Promise<Set<string>>;
+/**
+ * Everything one email has decided about, in ONE read.
+ *
+ * ## Why a batch subtracts more than a follow-up does
+ *
+ * A merchant's follow-up subtracts {@link readCampaignReach} alone, and that
+ * is right: somebody who was suppressed when the email first went out, and
+ * has since been released, has never had it and should get it.
+ *
+ * A BATCH of the same email cannot use that rule, and the reason is the same
+ * one that puts the reach subtraction above the per-send cap rather than
+ * below it. The cap takes the first N of a stable order. An address the last
+ * batch addressed and could not mail is still at the head of that order, so
+ * it is selected again, and again, and it consumes a slot every time. A
+ * hundred suppressed addresses at the head of a list cost a hundred of every
+ * batch's five hundred; five hundred of them stop the campaign dead, having
+ * addressed nobody, forever.
+ *
+ * So a batch subtracts everything the email has SETTLED — mailed or refused —
+ * and the frontier advances by the whole cap every time. The distinction is
+ * kept in two fields rather than one because the two questions are different
+ * and only one of them is "who has this email".
+ *
+ * FAILS CLOSED, exactly as {@link readCampaignReach} does and for the same
+ * reason: a batch that cannot say who it has already mailed must not run.
+ *
+ * @throws when the record cannot be read.
+ */
+export declare function readCampaignSettled(hostId: string, sendId: string, firestore?: any): Promise<CampaignSettledRecord>;
+/**
+ * How many addresses this email's record accounts for, either way.
+ *
+ * The figure {@link CAMPAIGN_REACH_CEILING} bounds. Both halves count,
+ * because both halves are stored on the one document Firestore's size limit
+ * applies to.
+ */
+export declare function campaignSettledSize(settled: CampaignSettledRecord): number;
+/**
+ * Splits an audience into the people this email has not reached and the count
+ * of those it has.
+ *
+ * An address this cannot key counts as ALREADY REACHED and is dropped. The
+ * same posture the read takes: an address whose identity we cannot establish
+ * is one we cannot prove we have not already mailed, and both suppression
+ * lists refuse it for the same reason.
+ */
+export declare function partitionByCampaignReach(emails: readonly string[], reached: ReadonlySet<string>): {
+    unreached: string[];
+    alreadyReached: number;
+};
+/**
+ * Adds the addresses a send delivered to, to the email's reach record.
+ *
+ * `arrayUnion` rather than a read-modify-write: it is atomic, it is
+ * idempotent, and two sends of the same email contending would otherwise lose
+ * one of their sets — which is a set of people a later follow-up would then
+ * mail twice.
+ *
+ * Returns how many keys were offered, NOT how many were new; the union
+ * decides that and does not report it. The caller records the count so a
+ * follow-up can check the record covers the send.
+ *
+ * @throws nothing on a Firestore failure — a send that has already delivered
+ * must not be turned into an error by its own bookkeeping. The COVERAGE check
+ * in {@link campaignReachCovers} is what catches a lost write, by refusing
+ * the follow-up rather than by pretending the record is whole.
+ */
+export declare function recordCampaignReach(hostId: string, sendId: string, emails: readonly string[], firestore?: any): Promise<number>;
+/**
+ * Adds the addresses a send CONSIDERED and did not mail.
+ *
+ * The same document, the same `arrayUnion` and the same never-throws posture
+ * as {@link recordCampaignReach}, under a field of its own so that a
+ * merchant's follow-up and an automatic batch can read different questions
+ * off one record. A failed write costs a later batch a repeated suppression
+ * lookup and nothing else — nobody is mailed twice by it, because the
+ * addresses in here are the ones nothing may mail at all.
+ */
+export declare function recordCampaignSkipped(hostId: string, sendId: string, emails: readonly string[], firestore?: any): Promise<number>;
+/**
+ * Whether the reach record accounts for every message this email has sent.
+ *
+ * The one guard standing between a lost bookkeeping write and a duplicate in
+ * somebody's inbox. `sent` is the send document's own delivered total, and
+ * the reach record holds one key per delivered message — a recipient cannot
+ * be addressed twice by one send, because the audience is deduplicated, and
+ * cannot be addressed twice ACROSS sends, because that is the property this
+ * record exists to hold. So the two numbers agree exactly, and a record that
+ * is short is a record that is missing somebody.
+ *
+ * It also answers correctly for every email sent before this record existed:
+ * no document, `0` keys, a non-zero `sent`, and the follow-up is refused —
+ * which is right, because nobody can say who that send reached.
+ */
+export declare function campaignReachCovers(reached: ReadonlySet<string>, sent: number): boolean;

package/src/lib/server/email-campaign-reach.js

@@ -0,0 +1,254 @@
+/**
+ * @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.
+ */ /**
+ * WHO ONE EMAIL HAS ALREADY REACHED.
+ *
+ * An email may be sent more than once — a merchant adds the people who joined
+ * the list since it went out, or the ones a bounce kept it from. The single
+ * property that makes that safe is that a later send must address nobody an
+ * earlier one already reached, and nothing in the send path could answer that
+ * question: the delivered addresses were collected for the frequency window
+ * and then dropped.
+ *
+ * ## Why a record of its own, rather than the delivery log
+ *
+ * `emailDeliveries` looks like the answer and is not. It is populated by the
+ * provider WEBHOOK, so it lags the send by seconds to minutes and is missing
+ * entirely for a message the provider accepted but has not reported on. A
+ * follow-up computed against it would re-mail exactly the people whose events
+ * had not landed yet — the one outcome this whole feature must not produce.
+ *
+ * This record is written by the SENDER, from the addresses it saw
+ * `sendEmail` succeed for. It is the send's own account of itself.
+ *
+ * ## Why keys and not addresses
+ *
+ * The stored value is {@link emailSuppressionKey} — `sha256` of the
+ * normalized address, the same derivation both suppression lists and the
+ * frequency window key on. Reusing it rather than adding a second one is the
+ * point: a second hash of the same address is how this area came to have two
+ * derivations that agreed only by accident.
+ *
+ * It also means the document is a membership test and not an address list.
+ * The send's subcollection is readable by a site member, and a mailing list
+ * in the clear under a document the console lists is a thing to not create.
+ *
+ * ## Why one document, and what bounds it
+ *
+ * One `arrayUnion` read and one write per send, against a document nothing on
+ * the read path opens — as against a document per recipient, which would be
+ * 500 writes per send and up to {@link CAMPAIGN_REACH_CEILING} reads per
+ * follow-up.
+ *
+ * The ceiling is the audience scan ceiling the send path already has, and
+ * that is not a coincidence: a send cannot resolve more people than that in
+ * the first place, so an email whose reach exceeds it has been re-sent enough
+ * times to have addressed more people than any one of its audiences can hold.
+ * Refusing there keeps the document inside Firestore's 1 MB limit — 5,000
+ * 64-character keys is about 330 KB — with the refusal stated rather than a
+ * write that starts failing.
+ */ import { EMAIL_MAX_AUDIENCE_PER_SEND } from "@aglyn/shared-util-email";
+import firebaseAdmin from "@aglyn/tenant-data-admin/server/firebase-admin";
+import { emailSuppressionKey } from "@aglyn/tenant-data-admin/server/email-suppression";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+/**
+ * Where the record lives: beside the link rollup, under the send it belongs
+ * to.
+ *
+ * A subcollection document rather than a field on the send, for the reason
+ * the link rollup is one — the send document is read by the emails list, the
+ * glance widget and the send path, and a set that grows with the audience on
+ * it would make every one of those reads larger.
+ */ export const CAMPAIGN_REACH_DOC = 'reached';
+/** The subcollection the link rollup already uses. */ export const CAMPAIGN_REACH_SUBCOLLECTION = 'reports';
+/**
+ * The most people one email may reach across all of its sends.
+ *
+ * The sender's audience read budget, taken from the one place it is stated
+ * rather than restated here. See the header for why the two are necessarily
+ * the same number: an email cannot reach more people than one resolution of
+ * its audience can hold.
+ */ export const CAMPAIGN_REACH_CEILING = EMAIL_MAX_AUDIENCE_PER_SEND;
+function reachDoc(hostId, sendId, firestore) {
+    return (firestore != null ? firestore : defaultFirestore()).collection('hosts').doc(hostId).collection('campaigns').doc(sendId).collection(CAMPAIGN_REACH_SUBCOLLECTION).doc(CAMPAIGN_REACH_DOC);
+}
+/**
+ * The keys of everyone this email has reached.
+ *
+ * FAILS CLOSED — it throws rather than answering "nobody". The asymmetry with
+ * {@link readMarketingFrequency}, which fails open, is the same one
+ * `filterSendableForHost` draws: a frequency window that cannot be read
+ * refuses a message nobody objected to, where a reach record that cannot be
+ * read would mail somebody a second copy of a message they already have. A
+ * follow-up is a discretionary act a merchant can repeat in a minute; a
+ * duplicate in a stranger's inbox is not retractable.
+ *
+ * @throws when the record cannot be read.
+ */ export async function readCampaignReach(hostId, sendId, firestore) {
+    const snapshot = await reachDoc(hostId, sendId, firestore).get();
+    const stored = snapshot.exists ? snapshot.get('keys') : null;
+    if (!Array.isArray(stored)) return new Set();
+    return new Set(stored.map((key)=>String(key)));
+}
+/**
+ * Everything one email has decided about, in ONE read.
+ *
+ * ## Why a batch subtracts more than a follow-up does
+ *
+ * A merchant's follow-up subtracts {@link readCampaignReach} alone, and that
+ * is right: somebody who was suppressed when the email first went out, and
+ * has since been released, has never had it and should get it.
+ *
+ * A BATCH of the same email cannot use that rule, and the reason is the same
+ * one that puts the reach subtraction above the per-send cap rather than
+ * below it. The cap takes the first N of a stable order. An address the last
+ * batch addressed and could not mail is still at the head of that order, so
+ * it is selected again, and again, and it consumes a slot every time. A
+ * hundred suppressed addresses at the head of a list cost a hundred of every
+ * batch's five hundred; five hundred of them stop the campaign dead, having
+ * addressed nobody, forever.
+ *
+ * So a batch subtracts everything the email has SETTLED — mailed or refused —
+ * and the frontier advances by the whole cap every time. The distinction is
+ * kept in two fields rather than one because the two questions are different
+ * and only one of them is "who has this email".
+ *
+ * FAILS CLOSED, exactly as {@link readCampaignReach} does and for the same
+ * reason: a batch that cannot say who it has already mailed must not run.
+ *
+ * @throws when the record cannot be read.
+ */ export async function readCampaignSettled(hostId, sendId, firestore) {
+    const snapshot = await reachDoc(hostId, sendId, firestore).get();
+    const keys = snapshot.exists ? snapshot.get('keys') : null;
+    const skipped = snapshot.exists ? snapshot.get('skipped') : null;
+    const toSet = (stored)=>Array.isArray(stored) ? new Set(stored.map((key)=>String(key))) : new Set();
+    return {
+        reached: toSet(keys),
+        skipped: toSet(skipped)
+    };
+}
+/**
+ * How many addresses this email's record accounts for, either way.
+ *
+ * The figure {@link CAMPAIGN_REACH_CEILING} bounds. Both halves count,
+ * because both halves are stored on the one document Firestore's size limit
+ * applies to.
+ */ export function campaignSettledSize(settled) {
+    return settled.reached.size + settled.skipped.size;
+}
+/**
+ * Splits an audience into the people this email has not reached and the count
+ * of those it has.
+ *
+ * An address this cannot key counts as ALREADY REACHED and is dropped. The
+ * same posture the read takes: an address whose identity we cannot establish
+ * is one we cannot prove we have not already mailed, and both suppression
+ * lists refuse it for the same reason.
+ */ export function partitionByCampaignReach(emails, reached) {
+    const unreached = [];
+    let alreadyReached = 0;
+    for (const email of emails){
+        const key = emailSuppressionKey(email);
+        if (key && !reached.has(key)) unreached.push(email);
+        else alreadyReached += 1;
+    }
+    return {
+        unreached,
+        alreadyReached
+    };
+}
+/**
+ * Adds the addresses a send delivered to, to the email's reach record.
+ *
+ * `arrayUnion` rather than a read-modify-write: it is atomic, it is
+ * idempotent, and two sends of the same email contending would otherwise lose
+ * one of their sets — which is a set of people a later follow-up would then
+ * mail twice.
+ *
+ * Returns how many keys were offered, NOT how many were new; the union
+ * decides that and does not report it. The caller records the count so a
+ * follow-up can check the record covers the send.
+ *
+ * @throws nothing on a Firestore failure — a send that has already delivered
+ * must not be turned into an error by its own bookkeeping. The COVERAGE check
+ * in {@link campaignReachCovers} is what catches a lost write, by refusing
+ * the follow-up rather than by pretending the record is whole.
+ */ export async function recordCampaignReach(hostId, sendId, emails, firestore) {
+    const keys = [
+        ...new Set(emails.map((email)=>emailSuppressionKey(email)).filter((key)=>Boolean(key)))
+    ];
+    if (!keys.length || !hostId || !sendId) return 0;
+    try {
+        await reachDoc(hostId, sendId, firestore).set({
+            keys: firebaseAdmin.firestore.FieldValue.arrayUnion(...keys),
+            count: firebaseAdmin.firestore.FieldValue.increment(keys.length)
+        }, {
+            merge: true
+        });
+        return keys.length;
+    } catch (error) {
+        console.error('[email-campaign-reach] reach record failed', error);
+        return 0;
+    }
+}
+/**
+ * Adds the addresses a send CONSIDERED and did not mail.
+ *
+ * The same document, the same `arrayUnion` and the same never-throws posture
+ * as {@link recordCampaignReach}, under a field of its own so that a
+ * merchant's follow-up and an automatic batch can read different questions
+ * off one record. A failed write costs a later batch a repeated suppression
+ * lookup and nothing else — nobody is mailed twice by it, because the
+ * addresses in here are the ones nothing may mail at all.
+ */ export async function recordCampaignSkipped(hostId, sendId, emails, firestore) {
+    const keys = [
+        ...new Set(emails.map((email)=>emailSuppressionKey(email)).filter((key)=>Boolean(key)))
+    ];
+    if (!keys.length || !hostId || !sendId) return 0;
+    try {
+        await reachDoc(hostId, sendId, firestore).set({
+            skipped: firebaseAdmin.firestore.FieldValue.arrayUnion(...keys),
+            skippedCount: firebaseAdmin.firestore.FieldValue.increment(keys.length)
+        }, {
+            merge: true
+        });
+        return keys.length;
+    } catch (error) {
+        console.error('[email-campaign-reach] skipped record failed', error);
+        return 0;
+    }
+}
+/**
+ * Whether the reach record accounts for every message this email has sent.
+ *
+ * The one guard standing between a lost bookkeeping write and a duplicate in
+ * somebody's inbox. `sent` is the send document's own delivered total, and
+ * the reach record holds one key per delivered message — a recipient cannot
+ * be addressed twice by one send, because the audience is deduplicated, and
+ * cannot be addressed twice ACROSS sends, because that is the property this
+ * record exists to hold. So the two numbers agree exactly, and a record that
+ * is short is a record that is missing somebody.
+ *
+ * It also answers correctly for every email sent before this record existed:
+ * no document, `0` keys, a non-zero `sent`, and the follow-up is refused —
+ * which is right, because nobody can say who that send reached.
+ */ export function campaignReachCovers(reached, sent) {
+    const delivered = Number(sent);
+    if (!Number.isFinite(delivered) || delivered <= 0) return true;
+    return reached.size >= delivered;
+}
+
+//# sourceMappingURL=email-campaign-reach.js.map

package/src/lib/server/email-campaign-reach.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/server/email-campaign-reach.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 * WHO ONE EMAIL HAS ALREADY REACHED.\n *\n * An email may be sent more than once — a merchant adds the people who joined\n * the list since it went out, or the ones a bounce kept it from. The single\n * property that makes that safe is that a later send must address nobody an\n * earlier one already reached, and nothing in the send path could answer that\n * question: the delivered addresses were collected for the frequency window\n * and then dropped.\n *\n * ## Why a record of its own, rather than the delivery log\n *\n * `emailDeliveries` looks like the answer and is not. It is populated by the\n * provider WEBHOOK, so it lags the send by seconds to minutes and is missing\n * entirely for a message the provider accepted but has not reported on. A\n * follow-up computed against it would re-mail exactly the people whose events\n * had not landed yet — the one outcome this whole feature must not produce.\n *\n * This record is written by the SENDER, from the addresses it saw\n * `sendEmail` succeed for. It is the send's own account of itself.\n *\n * ## Why keys and not addresses\n *\n * The stored value is {@link emailSuppressionKey} — `sha256` of the\n * normalized address, the same derivation both suppression lists and the\n * frequency window key on. Reusing it rather than adding a second one is the\n * point: a second hash of the same address is how this area came to have two\n * derivations that agreed only by accident.\n *\n * It also means the document is a membership test and not an address list.\n * The send's subcollection is readable by a site member, and a mailing list\n * in the clear under a document the console lists is a thing to not create.\n *\n * ## Why one document, and what bounds it\n *\n * One `arrayUnion` read and one write per send, against a document nothing on\n * the read path opens — as against a document per recipient, which would be\n * 500 writes per send and up to {@link CAMPAIGN_REACH_CEILING} reads per\n * follow-up.\n *\n * The ceiling is the audience scan ceiling the send path already has, and\n * that is not a coincidence: a send cannot resolve more people than that in\n * the first place, so an email whose reach exceeds it has been re-sent enough\n * times to have addressed more people than any one of its audiences can hold.\n * Refusing there keeps the document inside Firestore's 1 MB limit — 5,000\n * 64-character keys is about 330 KB — with the refusal stated rather than a\n * write that starts failing.\n */\n\nimport { EMAIL_MAX_AUDIENCE_PER_SEND } from '@aglyn/shared-util-email'\nimport firebaseAdmin from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { emailSuppressionKey } from '@aglyn/tenant-data-admin/server/email-suppression'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/**\n * Where the record lives: beside the link rollup, under the send it belongs\n * to.\n *\n * A subcollection document rather than a field on the send, for the reason\n * the link rollup is one — the send document is read by the emails list, the\n * glance widget and the send path, and a set that grows with the audience on\n * it would make every one of those reads larger.\n */\nexport const CAMPAIGN_REACH_DOC = 'reached'\n\n/** The subcollection the link rollup already uses. */\nexport const CAMPAIGN_REACH_SUBCOLLECTION = 'reports'\n\n/**\n * The most people one email may reach across all of its sends.\n *\n * The sender's audience read budget, taken from the one place it is stated\n * rather than restated here. See the header for why the two are necessarily\n * the same number: an email cannot reach more people than one resolution of\n * its audience can hold.\n */\nexport const CAMPAIGN_REACH_CEILING = EMAIL_MAX_AUDIENCE_PER_SEND\n\nfunction reachDoc(\n  hostId: string,\n  sendId: string,\n  firestore?: any,\n): FirebaseFirestore.DocumentReference {\n  return (firestore ?? defaultFirestore())\n    .collection('hosts')\n    .doc(hostId)\n    .collection('campaigns')\n    .doc(sendId)\n    .collection(CAMPAIGN_REACH_SUBCOLLECTION)\n    .doc(CAMPAIGN_REACH_DOC)\n}\n\n/** The stored document. */\nexport interface CampaignReachRecord {\n  /** `sha256` of each normalized address this email has reached. */\n  keys: string[]\n  /** `keys.length`, so a reader can size the record without loading it. */\n  count: number\n  /**\n   * `sha256` of each address a send CONSIDERED and did not mail — suppressed,\n   * or gone from the topic the email opens on.\n   *\n   * See {@link readCampaignSettled} for why a batched send needs this and a\n   * merchant's follow-up must not read it.\n   */\n  skipped?: string[]\n  /** `skipped.length`, alongside `count` for the same reason. */\n  skippedCount?: number\n}\n\n/**\n * Everything one send of this email has DECIDED about, either way.\n *\n * `reached` is who got it. `skipped` is who was addressed by a batch, refused\n * by a suppression list or a topic opt-out, and must not consume a slot in\n * every later batch of the same email.\n */\nexport interface CampaignSettledRecord {\n  reached: Set<string>\n  skipped: Set<string>\n}\n\n/**\n * The keys of everyone this email has reached.\n *\n * FAILS CLOSED — it throws rather than answering \"nobody\". The asymmetry with\n * {@link readMarketingFrequency}, which fails open, is the same one\n * `filterSendableForHost` draws: a frequency window that cannot be read\n * refuses a message nobody objected to, where a reach record that cannot be\n * read would mail somebody a second copy of a message they already have. A\n * follow-up is a discretionary act a merchant can repeat in a minute; a\n * duplicate in a stranger's inbox is not retractable.\n *\n * @throws when the record cannot be read.\n */\nexport async function readCampaignReach(\n  hostId: string,\n  sendId: string,\n  firestore?: any,\n): Promise<Set<string>> {\n  const snapshot = await reachDoc(hostId, sendId, firestore).get()\n  const stored = snapshot.exists ? snapshot.get('keys') : null\n  if (!Array.isArray(stored)) return new Set<string>()\n  return new Set<string>(stored.map((key: unknown) => String(key)))\n}\n\n/**\n * Everything one email has decided about, in ONE read.\n *\n * ## Why a batch subtracts more than a follow-up does\n *\n * A merchant's follow-up subtracts {@link readCampaignReach} alone, and that\n * is right: somebody who was suppressed when the email first went out, and\n * has since been released, has never had it and should get it.\n *\n * A BATCH of the same email cannot use that rule, and the reason is the same\n * one that puts the reach subtraction above the per-send cap rather than\n * below it. The cap takes the first N of a stable order. An address the last\n * batch addressed and could not mail is still at the head of that order, so\n * it is selected again, and again, and it consumes a slot every time. A\n * hundred suppressed addresses at the head of a list cost a hundred of every\n * batch's five hundred; five hundred of them stop the campaign dead, having\n * addressed nobody, forever.\n *\n * So a batch subtracts everything the email has SETTLED — mailed or refused —\n * and the frontier advances by the whole cap every time. The distinction is\n * kept in two fields rather than one because the two questions are different\n * and only one of them is \"who has this email\".\n *\n * FAILS CLOSED, exactly as {@link readCampaignReach} does and for the same\n * reason: a batch that cannot say who it has already mailed must not run.\n *\n * @throws when the record cannot be read.\n */\nexport async function readCampaignSettled(\n  hostId: string,\n  sendId: string,\n  firestore?: any,\n): Promise<CampaignSettledRecord> {\n  const snapshot = await reachDoc(hostId, sendId, firestore).get()\n  const keys = snapshot.exists ? snapshot.get('keys') : null\n  const skipped = snapshot.exists ? snapshot.get('skipped') : null\n  const toSet = (stored: unknown) =>\n    Array.isArray(stored)\n      ? new Set<string>(stored.map((key: unknown) => String(key)))\n      : new Set<string>()\n  return { reached: toSet(keys), skipped: toSet(skipped) }\n}\n\n/**\n * How many addresses this email's record accounts for, either way.\n *\n * The figure {@link CAMPAIGN_REACH_CEILING} bounds. Both halves count,\n * because both halves are stored on the one document Firestore's size limit\n * applies to.\n */\nexport function campaignSettledSize(settled: CampaignSettledRecord): number {\n  return settled.reached.size + settled.skipped.size\n}\n\n/**\n * Splits an audience into the people this email has not reached and the count\n * of those it has.\n *\n * An address this cannot key counts as ALREADY REACHED and is dropped. The\n * same posture the read takes: an address whose identity we cannot establish\n * is one we cannot prove we have not already mailed, and both suppression\n * lists refuse it for the same reason.\n */\nexport function partitionByCampaignReach(\n  emails: readonly string[],\n  reached: ReadonlySet<string>,\n): { unreached: string[]; alreadyReached: number } {\n  const unreached: string[] = []\n  let alreadyReached = 0\n  for (const email of emails) {\n    const key = emailSuppressionKey(email)\n    if (key && !reached.has(key)) unreached.push(email)\n    else alreadyReached += 1\n  }\n  return { unreached, alreadyReached }\n}\n\n/**\n * Adds the addresses a send delivered to, to the email's reach record.\n *\n * `arrayUnion` rather than a read-modify-write: it is atomic, it is\n * idempotent, and two sends of the same email contending would otherwise lose\n * one of their sets — which is a set of people a later follow-up would then\n * mail twice.\n *\n * Returns how many keys were offered, NOT how many were new; the union\n * decides that and does not report it. The caller records the count so a\n * follow-up can check the record covers the send.\n *\n * @throws nothing on a Firestore failure — a send that has already delivered\n * must not be turned into an error by its own bookkeeping. The COVERAGE check\n * in {@link campaignReachCovers} is what catches a lost write, by refusing\n * the follow-up rather than by pretending the record is whole.\n */\nexport async function recordCampaignReach(\n  hostId: string,\n  sendId: string,\n  emails: readonly string[],\n  firestore?: any,\n): Promise<number> {\n  const keys = [\n    ...new Set(\n      emails\n        .map((email) => emailSuppressionKey(email))\n        .filter((key): key is string => Boolean(key)),\n    ),\n  ]\n  if (!keys.length || !hostId || !sendId) return 0\n  try {\n    await reachDoc(hostId, sendId, firestore).set(\n      {\n        keys: firebaseAdmin.firestore.FieldValue.arrayUnion(...keys),\n        count: firebaseAdmin.firestore.FieldValue.increment(keys.length),\n      },\n      { merge: true },\n    )\n    return keys.length\n  } catch (error) {\n    console.error('[email-campaign-reach] reach record failed', error)\n    return 0\n  }\n}\n\n/**\n * Adds the addresses a send CONSIDERED and did not mail.\n *\n * The same document, the same `arrayUnion` and the same never-throws posture\n * as {@link recordCampaignReach}, under a field of its own so that a\n * merchant's follow-up and an automatic batch can read different questions\n * off one record. A failed write costs a later batch a repeated suppression\n * lookup and nothing else — nobody is mailed twice by it, because the\n * addresses in here are the ones nothing may mail at all.\n */\nexport async function recordCampaignSkipped(\n  hostId: string,\n  sendId: string,\n  emails: readonly string[],\n  firestore?: any,\n): Promise<number> {\n  const keys = [\n    ...new Set(\n      emails\n        .map((email) => emailSuppressionKey(email))\n        .filter((key): key is string => Boolean(key)),\n    ),\n  ]\n  if (!keys.length || !hostId || !sendId) return 0\n  try {\n    await reachDoc(hostId, sendId, firestore).set(\n      {\n        skipped: firebaseAdmin.firestore.FieldValue.arrayUnion(...keys),\n        skippedCount: firebaseAdmin.firestore.FieldValue.increment(keys.length),\n      },\n      { merge: true },\n    )\n    return keys.length\n  } catch (error) {\n    console.error('[email-campaign-reach] skipped record failed', error)\n    return 0\n  }\n}\n\n/**\n * Whether the reach record accounts for every message this email has sent.\n *\n * The one guard standing between a lost bookkeeping write and a duplicate in\n * somebody's inbox. `sent` is the send document's own delivered total, and\n * the reach record holds one key per delivered message — a recipient cannot\n * be addressed twice by one send, because the audience is deduplicated, and\n * cannot be addressed twice ACROSS sends, because that is the property this\n * record exists to hold. So the two numbers agree exactly, and a record that\n * is short is a record that is missing somebody.\n *\n * It also answers correctly for every email sent before this record existed:\n * no document, `0` keys, a non-zero `sent`, and the follow-up is refused —\n * which is right, because nobody can say who that send reached.\n */\nexport function campaignReachCovers(\n  reached: ReadonlySet<string>,\n  sent: number,\n): boolean {\n  const delivered = Number(sent)\n  if (!Number.isFinite(delivered) || delivered <= 0) return true\n  return reached.size >= delivered\n}\n"],"names":["EMAIL_MAX_AUDIENCE_PER_SEND","firebaseAdmin","emailSuppressionKey","defaultFirestore","app","firestore","CAMPAIGN_REACH_DOC","CAMPAIGN_REACH_SUBCOLLECTION","CAMPAIGN_REACH_CEILING","reachDoc","hostId","sendId","collection","doc","readCampaignReach","snapshot","get","stored","exists","Array","isArray","Set","map","key","String","readCampaignSettled","keys","skipped","toSet","reached","campaignSettledSize","settled","size","partitionByCampaignReach","emails","unreached","alreadyReached","email","has","push","recordCampaignReach","filter","Boolean","length","set","FieldValue","arrayUnion","count","increment","merge","error","console","recordCampaignSkipped","skippedCount","campaignReachCovers","sent","delivered","Number","isFinite"],"mappings":"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"}

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

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type PluginApiHandler } from '@aglyn/aglyn/server';
+/**
+ * Resend event ingestion (AGL-268), relocated from the console app route
+ * into its owning plugin (AGL-418) — the URL `/api/email/events` is
+ * preserved through the plugin API dispatcher. Opened/clicked events
+ * increment the tagged campaign's stats; clicks on experiment sends also
+ * count as the recipient's variant conversion — the variant re-derives
+ * deterministically from the address, so nothing per-send is stored.
+ * Svix signs the RAW body: `req.rawBody` carries the exact request text.
+ */
+export declare const emailEventsHandler: PluginApiHandler;