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

package/src/lib/server/email-metering.js

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

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

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

package/src/lib/server/email-revenue-attribution.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @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 { EMAIL_ATTRIBUTION_WINDOW_MS } from '@aglyn/shared-util-email';
+/**
+ * THE COMMERCE↔EMAIL JOIN — an order, credited to the campaign that led to it.
+ *
+ * ## Why this is a join
+ *
+ * Every compared ESP attributes revenue through an integration into a store
+ * it does not own: a catalog sync, an on-site tracking snippet, an identity
+ * graph, and a window wide enough to absorb what the reconciliation misses.
+ * Commerce here is first-party and runs on the merchant's own Stripe Connect
+ * account, so the click and the order are two rows in one database keyed the
+ * same way. The window is not a fudge factor here — it is the model, and
+ * nothing else about the number is estimated.
+ *
+ * ## Three writes, and what each one is for
+ *
+ *  - **The touch**, `emailDeliveries/{personKey}.campaignTouches[hostId]`,
+ *    written by the delivery webhook on a click. Owned by
+ *    `email-delivery-log.ts`, because it lives on the person's document and
+ *    the erasure path has to be able to remove it.
+ *  - **The attribution record**, `hosts/{hostId}/emailAttributions/{orderId}`,
+ *    written here when an order is credited. It is the audit trail — which
+ *    campaign, which click, which model, which window — and it is what the
+ *    refund path reads to find out which campaign to take the money back off.
+ *  - **The rollup**, `campaigns/{campaignId}/reports/revenue`, incremented
+ *    here. One document per campaign, so the report reads it whole.
+ *
+ * ## Why the record is a document and not a field on the order
+ *
+ * Three reasons, and the first is decisive. `create()` fails when the
+ * document already exists, which is exact idempotency for free: webhook
+ * delivery is at-least-once, and a redelivered purchase must not be able to
+ * credit a campaign twice. Second, not every purchase door writes an order —
+ * a booking is a sale with no order document — and a field would have had to
+ * either skip those or conjure the document, and conjuring is the
+ * phantom-document shape this codebase spent a sweep removing. Third, the
+ * order document is read by the console list, the fulfilment path, the
+ * supplier outbox and the CSV export, and none of them wants a field about
+ * email.
+ *
+ * ## Never throws
+ *
+ * Same contract as `upsertHostContact`, which calls it, and for the same
+ * reason: the money has already moved and the order already records it, so
+ * nothing here may fail a sale. A lost attribution understates a campaign; a
+ * thrown one loses a checkout.
+ */
+/** The per-host collection of attribution records. */
+export declare const EMAIL_ATTRIBUTIONS_COLLECTION = "emailAttributions";
+/** The single rollup document under a campaign. */
+export declare const CAMPAIGN_REVENUE_REPORT_DOC = "revenue";
+/**
+ * The currency an amount is recorded under when the caller does not say.
+ *
+ * Every checkout door in this repo — cart, buy-now, POS, draft orders,
+ * reservations, subscriptions — writes `currency: 'usd'` onto the Stripe line
+ * items, and no order document carries a currency field to read back. So this
+ * is a statement about what the code charges rather than a guess about the
+ * money. The parameter exists so a door that ever charges in something else
+ * says so and lands in its own bucket, because the one thing the report may
+ * never do is add two currencies together.
+ */
+export declare const DEFAULT_ATTRIBUTION_CURRENCY = "usd";
+/** What one attribution record holds. */
+export interface EmailAttributionRecord {
+    campaignId: string;
+    /** When the credited click happened. */
+    clickedAtMs: number;
+    /** When the order was placed. */
+    orderedAtMs: number;
+    /** Minor units credited, gross — the amount the buyer was charged. */
+    amountCents: number;
+    /** Lowercase currency code the amount is in. */
+    currency: string;
+    /** The model this credit was decided under. */
+    model: string;
+    /** The window, in days, it was decided inside. */
+    windowDays: number;
+}
+/**
+ * Credits one order to the campaign whose link the buyer last clicked.
+ *
+ * ## What happens when there is nobody to credit
+ *
+ * Each case answers `null` and writes NOTHING, which is the whole design:
+ *
+ *  - **No email on the order.** A guest checkout that never identified its
+ *    buyer cannot be joined to anybody's clicks. There is no fallback and
+ *    there deliberately is not one — the alternatives are an IP or a device
+ *    guess, which is the probabilistic attribution owning the checkout exists
+ *    to avoid.
+ *  - **A guest with an email but no contact record.** This is ATTRIBUTED
+ *    normally. The join keys on the address hash, exactly as the touch and
+ *    the suppression list do, so it never asks whether a contact document
+ *    exists — which matters, because contact creation is audience-band gated
+ *    and a Free org's dropped contact would otherwise silently drop the
+ *    revenue with it.
+ *  - **No touch, or a touch on another site.** Nobody clicked, so nobody is
+ *    credited. The touch map is keyed by host and the send path refuses
+ *    cross-site reach; the revenue join agrees with it.
+ *  - **A touch outside the window**, in either direction. See
+ *    {@link emailTouchIsInWindow} — a click AFTER the order is the receipt,
+ *    not the cause.
+ *
+ * None of these is counted anywhere. A miss costs no write, which is what
+ * keeps the ordinary order — placed by somebody who is not on the mailing
+ * list at all — at exactly one document read. What it means for the report is
+ * stated on the report: the figure counts orders it could join, and is a
+ * floor.
+ *
+ * @returns the record written, or `null` when nothing was credited.
+ */
+export declare function attributeOrderToEmail(options: {
+    hostId: string;
+    /** The order, booking or invoice the money came in on. */
+    orderId: string;
+    /** The buyer as the sale recorded them, raw — normalized downstream. */
+    email: unknown;
+    /** Gross minor units the buyer was charged. */
+    amountCents: number;
+    /** Lowercase currency code, when the door knows one. */
+    currency?: string;
+    /** When the order was placed. Defaults to now. */
+    orderedAtMs?: number;
+}, firestore?: any): Promise<EmailAttributionRecord | null>;
+/**
+ * Takes back revenue a campaign was credited with, when it is refunded.
+ *
+ * ## Recorded beside the gross, never subtracted from it
+ *
+ * `grossCents` is left exactly as it is and the reversal lands in
+ * `refundedCents` next to it. This is the shape `contact-refund.ts` chose for
+ * `ltvCents`/`refundedCents` and the orders CSV chose for
+ * `amountUsd`/`refundedUsd`, and it is chosen a third time here so all three
+ * answer "what did this earn, net" identically. Decrementing would make a
+ * stored number mean one thing for rollups written before a refund and
+ * another after, with nothing on the document to tell them apart — and would
+ * put the question "can it go negative" onto storage, where the answer cannot
+ * be clamped without destroying evidence. Both stored figures are monotonic
+ * counters of money that really moved in one direction; the derived net is
+ * clamped at the point of display and nowhere else.
+ *
+ * ## The currency comes from the RECORD, not from the caller
+ *
+ * A refund reverses a specific sale, and the bucket it comes out of has to be
+ * the bucket it went into. Reading the currency back off the attribution
+ * record is what guarantees that, and it is the second thing the record is
+ * for.
+ *
+ * ## Chargebacks come through here too
+ *
+ * Money reversed is money reversed, whichever door it left by, so a lost
+ * dispute reverses the credit the same way a refund does. `kind` exists for
+ * the caller's clarity and changes nothing about the arithmetic — the same
+ * choice `recordContactRefund` made one field along.
+ *
+ * @returns whether a reversal was recorded.
+ */
+export declare function reverseEmailAttributedRevenue(options: {
+    hostId: string;
+    orderId: string;
+    /** Minor units reversed by THIS attempt, never the order total. */
+    amountCents: number;
+    /** True only for the write that moved the order into `refunded`. */
+    closedTheOrder: boolean;
+    kind?: 'refund' | 'chargeback';
+}, firestore?: any): Promise<boolean>;
+/** The window, re-exported so a caller needs one import for the whole join. */
+export { EMAIL_ATTRIBUTION_WINDOW_MS };