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

package/src/lib/server/email-revenue-attribution.js

@@ -0,0 +1,300 @@
+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.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { EMAIL_ATTRIBUTION_MODEL, EMAIL_ATTRIBUTION_WINDOW_DAYS, EMAIL_ATTRIBUTION_WINDOW_MS, emailTouchIsInWindow } from "@aglyn/shared-util-email";
+import { readEmailCampaignTouch } from "./email-delivery-log.js";
+import { isDocumentId } from "./document-id.js";
+import firebaseAdmin from "./firebase-admin.js";
+const defaultFirestore = ()=>firebaseAdmin.app().firestore();
+/**
+ * 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 const EMAIL_ATTRIBUTIONS_COLLECTION = 'emailAttributions';
+/** The single rollup document under a campaign. */ export 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 const DEFAULT_ATTRIBUTION_CURRENCY = 'usd';
+/** Normalizes a currency code to the key its bucket is stored under. */ function currencyKey(raw) {
+    const code = String(raw != null ? raw : '').trim().toLowerCase();
+    // Letters only: the code becomes a MAP KEY, and a key carrying a dot would
+    // be unreachable by any dotted field path a later reader wants to use.
+    return /^[a-z]{3}$/.test(code) ? code : DEFAULT_ATTRIBUTION_CURRENCY;
+}
+/** A positive integer number of minor units, or 0. */ function minorUnits(raw) {
+    const value = Math.round(Number(raw));
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * 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 async function attributeOrderToEmail(options, firestore) {
+    try {
+        var _options_hostId, _options_orderId, _options_orderedAtMs, _options_email;
+        const hostId = String((_options_hostId = options.hostId) != null ? _options_hostId : '');
+        const orderId = String((_options_orderId = options.orderId) != null ? _options_orderId : '');
+        const amountCents = minorUnits(options.amountCents);
+        if (!isDocumentId(hostId) || !isDocumentId(orderId)) return null;
+        if (!amountCents) return null;
+        const orderedAtMs = Number((_options_orderedAtMs = options.orderedAtMs) != null ? _options_orderedAtMs : Date.now());
+        const db = firestore != null ? firestore : defaultFirestore();
+        /*
+     * `String()` on an `unknown`, then let `emailSuppressionKey` decide.
+     *
+     * The buyer's address arrives as the ORDER recorded it, which is not
+     * consistently a string — the same rawness `recordContactRefund` takes
+     * `email: unknown` for. The key derivation is the one place that knows
+     * how an address becomes a document id, so nothing here tries to
+     * pre-clean it; a value that is not an address answers `null` there and
+     * the order is credited to nobody.
+     */ const rawEmail = typeof options.email === 'string' ? options.email : String((_options_email = options.email) != null ? _options_email : '');
+        const touch = await readEmailCampaignTouch(rawEmail, hostId, db);
+        if (!touch) return null;
+        if (!isDocumentId(touch.campaignId)) return null;
+        if (!emailTouchIsInWindow(touch.clickedAtMs, orderedAtMs)) return null;
+        const record = {
+            campaignId: touch.campaignId,
+            clickedAtMs: touch.clickedAtMs,
+            orderedAtMs,
+            amountCents,
+            currency: currencyKey(options.currency),
+            model: EMAIL_ATTRIBUTION_MODEL,
+            windowDays: EMAIL_ATTRIBUTION_WINDOW_DAYS
+        };
+        const hostRef = db.collection('hosts').doc(hostId);
+        /*
+     * `create()`, never `set()`. It fails with ALREADY_EXISTS when this order
+     * has been credited before, and that failure is the idempotency: a
+     * webhook redelivery, a retried checkout completion and a replayed event
+     * all land here a second time, and all three must leave the rollup where
+     * they found it. The increment below is reached only when the create
+     * succeeded, so the two can never disagree about whether this order was
+     * counted.
+     */ try {
+            await hostRef.collection(EMAIL_ATTRIBUTIONS_COLLECTION).doc(orderId).create(_extends({}, record, {
+                createdAt: FieldValue.serverTimestamp()
+            }));
+        } catch (unused) {
+            return null;
+        }
+        /*
+     * A merge-set that CREATES, unlike the campaign counters the delivery
+     * webhook writes through `updateExisting`.
+     *
+     * The distinction is which document is being conjured. Those counters
+     * refuse to create because a merge-set against a DELETED CAMPAIGN
+     * resurrects the campaign itself, as a husk holding a stats map and no
+     * subject. This writes a subcollection document UNDER a campaign, so a
+     * campaign that no longer exists gains an orphaned report rather than
+     * coming back to life in the merchant's history — and the campaign was
+     * proven to exist a moment ago, when its click wrote the touch.
+     *
+     * Every amount is an increment, so two orders settling at once both land.
+     */ const currency = record.currency;
+        await hostRef.collection('campaigns').doc(touch.campaignId).collection('reports').doc(CAMPAIGN_REVENUE_REPORT_DOC).set({
+            model: EMAIL_ATTRIBUTION_MODEL,
+            windowDays: EMAIL_ATTRIBUTION_WINDOW_DAYS,
+            byCurrency: {
+                [currency]: {
+                    grossCents: FieldValue.increment(amountCents),
+                    orders: FieldValue.increment(1)
+                }
+            },
+            updatedAt: FieldValue.serverTimestamp()
+        }, {
+            merge: true
+        });
+        return record;
+    } catch (error) {
+        console.error('attributeOrderToEmail failed', error);
+        return 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 async function reverseEmailAttributedRevenue(options, firestore) {
+    try {
+        var _options_hostId, _options_orderId, _snapshot_data, _record_campaignId;
+        const hostId = String((_options_hostId = options.hostId) != null ? _options_hostId : '');
+        const orderId = String((_options_orderId = options.orderId) != null ? _options_orderId : '');
+        const amountCents = minorUnits(options.amountCents);
+        if (!isDocumentId(hostId) || !isDocumentId(orderId)) return false;
+        if (!amountCents) return false;
+        const db = firestore != null ? firestore : defaultFirestore();
+        const hostRef = db.collection('hosts').doc(hostId);
+        const snapshot = await hostRef.collection(EMAIL_ATTRIBUTIONS_COLLECTION).doc(orderId).get();
+        // The ordinary case, and not an error: most orders were never credited to
+        // a campaign, so most refunds have nothing to reverse.
+        if (!snapshot.exists) return false;
+        const record = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+        const campaignId = String((_record_campaignId = record.campaignId) != null ? _record_campaignId : '');
+        if (!isDocumentId(campaignId)) return false;
+        const currency = currencyKey(record.currency);
+        /*
+     * NOT capped against what was credited, and that is deliberate. The
+     * caller already caps each attempt against what is left on the ORDER, so
+     * several partials sum to at most the order total; capping again here
+     * against the attributed amount would silently discard the reversal of an
+     * order refunded for more than the amount the campaign was credited with
+     * — which happens when the credit was the charge and the refund includes
+     * something the credit did not. The stored pair keeps both true figures
+     * and the reader clamps the net it prints.
+     */ await hostRef.collection('campaigns').doc(campaignId).collection('reports').doc(CAMPAIGN_REVENUE_REPORT_DOC).set({
+            byCurrency: {
+                [currency]: _extends({
+                    refundedCents: FieldValue.increment(amountCents)
+                }, options.closedTheOrder ? {
+                    refundedOrders: FieldValue.increment(1)
+                } : {})
+            },
+            updatedAt: FieldValue.serverTimestamp()
+        }, {
+            merge: true
+        });
+        /*
+     * Stamped on the record as well as counted in the rollup. The rollup is a
+     * sum and cannot say WHICH orders came back; this is the per-order half
+     * of the same fact, and it is what a merchant asking "why did this
+     * campaign's revenue drop" is eventually going to need. Increments, so
+     * two partials on one order both land.
+     */ await snapshot.ref.set(_extends({
+            refundedCents: FieldValue.increment(amountCents),
+            lastRefundAtMs: Date.now()
+        }, options.kind === 'chargeback' ? {
+            chargedBack: true
+        } : {}, options.closedTheOrder ? {
+            fullyRefunded: true
+        } : {}), {
+            merge: true
+        }).catch(()=>undefined);
+        return true;
+    } catch (error) {
+        console.error('reverseEmailAttributedRevenue failed', error);
+        return false;
+    }
+}
+/** The window, re-exported so a caller needs one import for the whole join. */ export { EMAIL_ATTRIBUTION_WINDOW_MS };
+
+//# sourceMappingURL=email-revenue-attribution.js.map

package/src/lib/server/email-revenue-attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/email-revenue-attribution.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 { FieldValue } from 'firebase-admin/firestore'\nimport {\n  EMAIL_ATTRIBUTION_MODEL,\n  EMAIL_ATTRIBUTION_WINDOW_DAYS,\n  EMAIL_ATTRIBUTION_WINDOW_MS,\n  emailTouchIsInWindow,\n} from '@aglyn/shared-util-email'\nimport { readEmailCampaignTouch } from './email-delivery-log'\nimport { isDocumentId } from './document-id'\nimport firebaseAdmin from './firebase-admin'\n\nconst defaultFirestore = () => firebaseAdmin.app().firestore()\n\n/**\n * THE COMMERCE↔EMAIL JOIN — an order, credited to the campaign that led to it.\n *\n * ## Why this is a join\n *\n * Every compared ESP attributes revenue through an integration into a store\n * it does not own: a catalog sync, an on-site tracking snippet, an identity\n * graph, and a window wide enough to absorb what the reconciliation misses.\n * Commerce here is first-party and runs on the merchant's own Stripe Connect\n * account, so the click and the order are two rows in one database keyed the\n * same way. The window is not a fudge factor here — it is the model, and\n * nothing else about the number is estimated.\n *\n * ## Three writes, and what each one is for\n *\n *  - **The touch**, `emailDeliveries/{personKey}.campaignTouches[hostId]`,\n *    written by the delivery webhook on a click. Owned by\n *    `email-delivery-log.ts`, because it lives on the person's document and\n *    the erasure path has to be able to remove it.\n *  - **The attribution record**, `hosts/{hostId}/emailAttributions/{orderId}`,\n *    written here when an order is credited. It is the audit trail — which\n *    campaign, which click, which model, which window — and it is what the\n *    refund path reads to find out which campaign to take the money back off.\n *  - **The rollup**, `campaigns/{campaignId}/reports/revenue`, incremented\n *    here. One document per campaign, so the report reads it whole.\n *\n * ## Why the record is a document and not a field on the order\n *\n * Three reasons, and the first is decisive. `create()` fails when the\n * document already exists, which is exact idempotency for free: webhook\n * delivery is at-least-once, and a redelivered purchase must not be able to\n * credit a campaign twice. Second, not every purchase door writes an order —\n * a booking is a sale with no order document — and a field would have had to\n * either skip those or conjure the document, and conjuring is the\n * phantom-document shape this codebase spent a sweep removing. Third, the\n * order document is read by the console list, the fulfilment path, the\n * supplier outbox and the CSV export, and none of them wants a field about\n * email.\n *\n * ## Never throws\n *\n * Same contract as `upsertHostContact`, which calls it, and for the same\n * reason: the money has already moved and the order already records it, so\n * nothing here may fail a sale. A lost attribution understates a campaign; a\n * thrown one loses a checkout.\n */\n\n/** The per-host collection of attribution records. */\nexport const EMAIL_ATTRIBUTIONS_COLLECTION = 'emailAttributions'\n\n/** The single rollup document under a campaign. */\nexport const CAMPAIGN_REVENUE_REPORT_DOC = 'revenue'\n\n/**\n * The currency an amount is recorded under when the caller does not say.\n *\n * Every checkout door in this repo — cart, buy-now, POS, draft orders,\n * reservations, subscriptions — writes `currency: 'usd'` onto the Stripe line\n * items, and no order document carries a currency field to read back. So this\n * is a statement about what the code charges rather than a guess about the\n * money. The parameter exists so a door that ever charges in something else\n * says so and lands in its own bucket, because the one thing the report may\n * never do is add two currencies together.\n */\nexport const DEFAULT_ATTRIBUTION_CURRENCY = 'usd'\n\n/** What one attribution record holds. */\nexport interface EmailAttributionRecord {\n  campaignId: string\n  /** When the credited click happened. */\n  clickedAtMs: number\n  /** When the order was placed. */\n  orderedAtMs: number\n  /** Minor units credited, gross — the amount the buyer was charged. */\n  amountCents: number\n  /** Lowercase currency code the amount is in. */\n  currency: string\n  /** The model this credit was decided under. */\n  model: string\n  /** The window, in days, it was decided inside. */\n  windowDays: number\n}\n\n/** Normalizes a currency code to the key its bucket is stored under. */\nfunction currencyKey(raw: unknown): string {\n  const code = String(raw ?? '')\n    .trim()\n    .toLowerCase()\n  // Letters only: the code becomes a MAP KEY, and a key carrying a dot would\n  // be unreachable by any dotted field path a later reader wants to use.\n  return /^[a-z]{3}$/.test(code) ? code : DEFAULT_ATTRIBUTION_CURRENCY\n}\n\n/** A positive integer number of minor units, or 0. */\nfunction minorUnits(raw: unknown): number {\n  const value = Math.round(Number(raw))\n  return Number.isFinite(value) && value > 0 ? value : 0\n}\n\n/**\n * Credits one order to the campaign whose link the buyer last clicked.\n *\n * ## What happens when there is nobody to credit\n *\n * Each case answers `null` and writes NOTHING, which is the whole design:\n *\n *  - **No email on the order.** A guest checkout that never identified its\n *    buyer cannot be joined to anybody's clicks. There is no fallback and\n *    there deliberately is not one — the alternatives are an IP or a device\n *    guess, which is the probabilistic attribution owning the checkout exists\n *    to avoid.\n *  - **A guest with an email but no contact record.** This is ATTRIBUTED\n *    normally. The join keys on the address hash, exactly as the touch and\n *    the suppression list do, so it never asks whether a contact document\n *    exists — which matters, because contact creation is audience-band gated\n *    and a Free org's dropped contact would otherwise silently drop the\n *    revenue with it.\n *  - **No touch, or a touch on another site.** Nobody clicked, so nobody is\n *    credited. The touch map is keyed by host and the send path refuses\n *    cross-site reach; the revenue join agrees with it.\n *  - **A touch outside the window**, in either direction. See\n *    {@link emailTouchIsInWindow} — a click AFTER the order is the receipt,\n *    not the cause.\n *\n * None of these is counted anywhere. A miss costs no write, which is what\n * keeps the ordinary order — placed by somebody who is not on the mailing\n * list at all — at exactly one document read. What it means for the report is\n * stated on the report: the figure counts orders it could join, and is a\n * floor.\n *\n * @returns the record written, or `null` when nothing was credited.\n */\nexport async function attributeOrderToEmail(\n  options: {\n    hostId: string\n    /** The order, booking or invoice the money came in on. */\n    orderId: string\n    /** The buyer as the sale recorded them, raw — normalized downstream. */\n    email: unknown\n    /** Gross minor units the buyer was charged. */\n    amountCents: number\n    /** Lowercase currency code, when the door knows one. */\n    currency?: string\n    /** When the order was placed. Defaults to now. */\n    orderedAtMs?: number\n  },\n  firestore?: any,\n): Promise<EmailAttributionRecord | null> {\n  try {\n    const hostId = String(options.hostId ?? '')\n    const orderId = String(options.orderId ?? '')\n    const amountCents = minorUnits(options.amountCents)\n    if (!isDocumentId(hostId) || !isDocumentId(orderId)) return null\n    if (!amountCents) return null\n\n    const orderedAtMs = Number(options.orderedAtMs ?? Date.now())\n    const db = firestore ?? defaultFirestore()\n\n    /*\n     * `String()` on an `unknown`, then let `emailSuppressionKey` decide.\n     *\n     * The buyer's address arrives as the ORDER recorded it, which is not\n     * consistently a string — the same rawness `recordContactRefund` takes\n     * `email: unknown` for. The key derivation is the one place that knows\n     * how an address becomes a document id, so nothing here tries to\n     * pre-clean it; a value that is not an address answers `null` there and\n     * the order is credited to nobody.\n     */\n    const rawEmail =\n      typeof options.email === 'string' ? options.email : String(options.email ?? '')\n    const touch = await readEmailCampaignTouch(rawEmail, hostId, db)\n    if (!touch) return null\n    if (!isDocumentId(touch.campaignId)) return null\n    if (!emailTouchIsInWindow(touch.clickedAtMs, orderedAtMs)) return null\n\n    const record: EmailAttributionRecord = {\n      campaignId: touch.campaignId,\n      clickedAtMs: touch.clickedAtMs,\n      orderedAtMs,\n      amountCents,\n      currency: currencyKey(options.currency),\n      model: EMAIL_ATTRIBUTION_MODEL,\n      windowDays: EMAIL_ATTRIBUTION_WINDOW_DAYS,\n    }\n\n    const hostRef = db.collection('hosts').doc(hostId)\n    /*\n     * `create()`, never `set()`. It fails with ALREADY_EXISTS when this order\n     * has been credited before, and that failure is the idempotency: a\n     * webhook redelivery, a retried checkout completion and a replayed event\n     * all land here a second time, and all three must leave the rollup where\n     * they found it. The increment below is reached only when the create\n     * succeeded, so the two can never disagree about whether this order was\n     * counted.\n     */\n    try {\n      await hostRef\n        .collection(EMAIL_ATTRIBUTIONS_COLLECTION)\n        .doc(orderId)\n        .create({ ...record, createdAt: FieldValue.serverTimestamp() })\n    } catch {\n      return null\n    }\n\n    /*\n     * A merge-set that CREATES, unlike the campaign counters the delivery\n     * webhook writes through `updateExisting`.\n     *\n     * The distinction is which document is being conjured. Those counters\n     * refuse to create because a merge-set against a DELETED CAMPAIGN\n     * resurrects the campaign itself, as a husk holding a stats map and no\n     * subject. This writes a subcollection document UNDER a campaign, so a\n     * campaign that no longer exists gains an orphaned report rather than\n     * coming back to life in the merchant's history — and the campaign was\n     * proven to exist a moment ago, when its click wrote the touch.\n     *\n     * Every amount is an increment, so two orders settling at once both land.\n     */\n    const currency = record.currency\n    await hostRef\n      .collection('campaigns')\n      .doc(touch.campaignId)\n      .collection('reports')\n      .doc(CAMPAIGN_REVENUE_REPORT_DOC)\n      .set(\n        {\n          model: EMAIL_ATTRIBUTION_MODEL,\n          windowDays: EMAIL_ATTRIBUTION_WINDOW_DAYS,\n          byCurrency: {\n            [currency]: {\n              grossCents: FieldValue.increment(amountCents),\n              orders: FieldValue.increment(1),\n            },\n          },\n          updatedAt: FieldValue.serverTimestamp(),\n        },\n        { merge: true },\n      )\n\n    return record\n  } catch (error) {\n    console.error('attributeOrderToEmail failed', error)\n    return null\n  }\n}\n\n/**\n * Takes back revenue a campaign was credited with, when it is refunded.\n *\n * ## Recorded beside the gross, never subtracted from it\n *\n * `grossCents` is left exactly as it is and the reversal lands in\n * `refundedCents` next to it. This is the shape `contact-refund.ts` chose for\n * `ltvCents`/`refundedCents` and the orders CSV chose for\n * `amountUsd`/`refundedUsd`, and it is chosen a third time here so all three\n * answer \"what did this earn, net\" identically. Decrementing would make a\n * stored number mean one thing for rollups written before a refund and\n * another after, with nothing on the document to tell them apart — and would\n * put the question \"can it go negative\" onto storage, where the answer cannot\n * be clamped without destroying evidence. Both stored figures are monotonic\n * counters of money that really moved in one direction; the derived net is\n * clamped at the point of display and nowhere else.\n *\n * ## The currency comes from the RECORD, not from the caller\n *\n * A refund reverses a specific sale, and the bucket it comes out of has to be\n * the bucket it went into. Reading the currency back off the attribution\n * record is what guarantees that, and it is the second thing the record is\n * for.\n *\n * ## Chargebacks come through here too\n *\n * Money reversed is money reversed, whichever door it left by, so a lost\n * dispute reverses the credit the same way a refund does. `kind` exists for\n * the caller's clarity and changes nothing about the arithmetic — the same\n * choice `recordContactRefund` made one field along.\n *\n * @returns whether a reversal was recorded.\n */\nexport async function reverseEmailAttributedRevenue(\n  options: {\n    hostId: string\n    orderId: string\n    /** Minor units reversed by THIS attempt, never the order total. */\n    amountCents: number\n    /** True only for the write that moved the order into `refunded`. */\n    closedTheOrder: boolean\n    kind?: 'refund' | 'chargeback'\n  },\n  firestore?: any,\n): Promise<boolean> {\n  try {\n    const hostId = String(options.hostId ?? '')\n    const orderId = String(options.orderId ?? '')\n    const amountCents = minorUnits(options.amountCents)\n    if (!isDocumentId(hostId) || !isDocumentId(orderId)) return false\n    if (!amountCents) return false\n\n    const db = firestore ?? defaultFirestore()\n    const hostRef = db.collection('hosts').doc(hostId)\n    const snapshot = await hostRef\n      .collection(EMAIL_ATTRIBUTIONS_COLLECTION)\n      .doc(orderId)\n      .get()\n    // The ordinary case, and not an error: most orders were never credited to\n    // a campaign, so most refunds have nothing to reverse.\n    if (!snapshot.exists) return false\n\n    const record = snapshot.data() ?? {}\n    const campaignId = String(record.campaignId ?? '')\n    if (!isDocumentId(campaignId)) return false\n    const currency = currencyKey(record.currency)\n\n    /*\n     * NOT capped against what was credited, and that is deliberate. The\n     * caller already caps each attempt against what is left on the ORDER, so\n     * several partials sum to at most the order total; capping again here\n     * against the attributed amount would silently discard the reversal of an\n     * order refunded for more than the amount the campaign was credited with\n     * — which happens when the credit was the charge and the refund includes\n     * something the credit did not. The stored pair keeps both true figures\n     * and the reader clamps the net it prints.\n     */\n    await hostRef\n      .collection('campaigns')\n      .doc(campaignId)\n      .collection('reports')\n      .doc(CAMPAIGN_REVENUE_REPORT_DOC)\n      .set(\n        {\n          byCurrency: {\n            [currency]: {\n              refundedCents: FieldValue.increment(amountCents),\n              ...(options.closedTheOrder\n                ? { refundedOrders: FieldValue.increment(1) }\n                : {}),\n            },\n          },\n          updatedAt: FieldValue.serverTimestamp(),\n        },\n        { merge: true },\n      )\n\n    /*\n     * Stamped on the record as well as counted in the rollup. The rollup is a\n     * sum and cannot say WHICH orders came back; this is the per-order half\n     * of the same fact, and it is what a merchant asking \"why did this\n     * campaign's revenue drop\" is eventually going to need. Increments, so\n     * two partials on one order both land.\n     */\n    await snapshot.ref\n      .set(\n        {\n          refundedCents: FieldValue.increment(amountCents),\n          lastRefundAtMs: Date.now(),\n          ...(options.kind === 'chargeback' ? { chargedBack: true } : {}),\n          ...(options.closedTheOrder ? { fullyRefunded: true } : {}),\n        },\n        { merge: true },\n      )\n      .catch(() => undefined)\n\n    return true\n  } catch (error) {\n    console.error('reverseEmailAttributedRevenue failed', error)\n    return false\n  }\n}\n\n/** The window, re-exported so a caller needs one import for the whole join. */\nexport { EMAIL_ATTRIBUTION_WINDOW_MS }\n"],"names":["FieldValue","EMAIL_ATTRIBUTION_MODEL","EMAIL_ATTRIBUTION_WINDOW_DAYS","EMAIL_ATTRIBUTION_WINDOW_MS","emailTouchIsInWindow","readEmailCampaignTouch","isDocumentId","firebaseAdmin","defaultFirestore","app","firestore","EMAIL_ATTRIBUTIONS_COLLECTION","CAMPAIGN_REVENUE_REPORT_DOC","DEFAULT_ATTRIBUTION_CURRENCY","currencyKey","raw","code","String","trim","toLowerCase","test","minorUnits","value","Math","round","Number","isFinite","attributeOrderToEmail","options","hostId","orderId","amountCents","orderedAtMs","Date","now","db","rawEmail","email","touch","campaignId","clickedAtMs","record","currency","model","windowDays","hostRef","collection","doc","create","createdAt","serverTimestamp","set","byCurrency","grossCents","increment","orders","updatedAt","merge","error","console","reverseEmailAttributedRevenue","snapshot","get","exists","data","refundedCents","closedTheOrder","refundedOrders","ref","lastRefundAtMs","kind","chargedBack","fullyRefunded","catch","undefined"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,QAAQ,2BAA0B;AACrD,SACEC,uBAAuB,EACvBC,6BAA6B,EAC7BC,2BAA2B,EAC3BC,oBAAoB,QACf,2BAA0B;AACjC,SAASC,sBAAsB,QAAQ,0BAAsB;AAC7D,SAASC,YAAY,QAAQ,mBAAe;AAC5C,OAAOC,mBAAmB,sBAAkB;AAE5C,MAAMC,mBAAmB,IAAMD,cAAcE,GAAG,GAAGC,SAAS;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CC,GAED,oDAAoD,GACpD,OAAO,MAAMC,gCAAgC,oBAAmB;AAEhE,iDAAiD,GACjD,OAAO,MAAMC,8BAA8B,UAAS;AAEpD;;;;;;;;;;CAUC,GACD,OAAO,MAAMC,+BAA+B,MAAK;AAmBjD,sEAAsE,GACtE,SAASC,YAAYC,GAAY;IAC/B,MAAMC,OAAOC,OAAOF,cAAAA,MAAO,IACxBG,IAAI,GACJC,WAAW;IACd,2EAA2E;IAC3E,uEAAuE;IACvE,OAAO,aAAaC,IAAI,CAACJ,QAAQA,OAAOH;AAC1C;AAEA,oDAAoD,GACpD,SAASQ,WAAWN,GAAY;IAC9B,MAAMO,QAAQC,KAAKC,KAAK,CAACC,OAAOV;IAChC,OAAOU,OAAOC,QAAQ,CAACJ,UAAUA,QAAQ,IAAIA,QAAQ;AACvD;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,OAAO,eAAeK,sBACpBC,OAYC,EACDlB,SAAe;IAEf,IAAI;YACoBkB,iBACCA,kBAKIA,sBAckCA;QApB7D,MAAMC,SAASZ,QAAOW,kBAAAA,QAAQC,MAAM,YAAdD,kBAAkB;QACxC,MAAME,UAAUb,QAAOW,mBAAAA,QAAQE,OAAO,YAAfF,mBAAmB;QAC1C,MAAMG,cAAcV,WAAWO,QAAQG,WAAW;QAClD,IAAI,CAACzB,aAAauB,WAAW,CAACvB,aAAawB,UAAU,OAAO;QAC5D,IAAI,CAACC,aAAa,OAAO;QAEzB,MAAMC,cAAcP,QAAOG,uBAAAA,QAAQI,WAAW,YAAnBJ,uBAAuBK,KAAKC,GAAG;QAC1D,MAAMC,KAAKzB,oBAAAA,YAAaF;QAExB;;;;;;;;;KASC,GACD,MAAM4B,WACJ,OAAOR,QAAQS,KAAK,KAAK,WAAWT,QAAQS,KAAK,GAAGpB,QAAOW,iBAAAA,QAAQS,KAAK,YAAbT,iBAAiB;QAC9E,MAAMU,QAAQ,MAAMjC,uBAAuB+B,UAAUP,QAAQM;QAC7D,IAAI,CAACG,OAAO,OAAO;QACnB,IAAI,CAAChC,aAAagC,MAAMC,UAAU,GAAG,OAAO;QAC5C,IAAI,CAACnC,qBAAqBkC,MAAME,WAAW,EAAER,cAAc,OAAO;QAElE,MAAMS,SAAiC;YACrCF,YAAYD,MAAMC,UAAU;YAC5BC,aAAaF,MAAME,WAAW;YAC9BR;YACAD;YACAW,UAAU5B,YAAYc,QAAQc,QAAQ;YACtCC,OAAO1C;YACP2C,YAAY1C;QACd;QAEA,MAAM2C,UAAUV,GAAGW,UAAU,CAAC,SAASC,GAAG,CAAClB;QAC3C;;;;;;;;KAQC,GACD,IAAI;YACF,MAAMgB,QACHC,UAAU,CAACnC,+BACXoC,GAAG,CAACjB,SACJkB,MAAM,CAAC,aAAKP;gBAAQQ,WAAWjD,WAAWkD,eAAe;;QAC9D,EAAE,eAAM;YACN,OAAO;QACT;QAEA;;;;;;;;;;;;;KAaC,GACD,MAAMR,WAAWD,OAAOC,QAAQ;QAChC,MAAMG,QACHC,UAAU,CAAC,aACXC,GAAG,CAACT,MAAMC,UAAU,EACpBO,UAAU,CAAC,WACXC,GAAG,CAACnC,6BACJuC,GAAG,CACF;YACER,OAAO1C;YACP2C,YAAY1C;YACZkD,YAAY;gBACV,CAACV,SAAS,EAAE;oBACVW,YAAYrD,WAAWsD,SAAS,CAACvB;oBACjCwB,QAAQvD,WAAWsD,SAAS,CAAC;gBAC/B;YACF;YACAE,WAAWxD,WAAWkD,eAAe;QACvC,GACA;YAAEO,OAAO;QAAK;QAGlB,OAAOhB;IACT,EAAE,OAAOiB,OAAO;QACdC,QAAQD,KAAK,CAAC,gCAAgCA;QAC9C,OAAO;IACT;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,OAAO,eAAeE,8BACpBhC,OAQC,EACDlB,SAAe;IAEf,IAAI;YACoBkB,iBACCA,kBAeRiC,gBACWpB;QAjB1B,MAAMZ,SAASZ,QAAOW,kBAAAA,QAAQC,MAAM,YAAdD,kBAAkB;QACxC,MAAME,UAAUb,QAAOW,mBAAAA,QAAQE,OAAO,YAAfF,mBAAmB;QAC1C,MAAMG,cAAcV,WAAWO,QAAQG,WAAW;QAClD,IAAI,CAACzB,aAAauB,WAAW,CAACvB,aAAawB,UAAU,OAAO;QAC5D,IAAI,CAACC,aAAa,OAAO;QAEzB,MAAMI,KAAKzB,oBAAAA,YAAaF;QACxB,MAAMqC,UAAUV,GAAGW,UAAU,CAAC,SAASC,GAAG,CAAClB;QAC3C,MAAMgC,WAAW,MAAMhB,QACpBC,UAAU,CAACnC,+BACXoC,GAAG,CAACjB,SACJgC,GAAG;QACN,0EAA0E;QAC1E,uDAAuD;QACvD,IAAI,CAACD,SAASE,MAAM,EAAE,OAAO;QAE7B,MAAMtB,UAASoB,iBAAAA,SAASG,IAAI,cAAbH,iBAAmB,CAAC;QACnC,MAAMtB,aAAatB,QAAOwB,qBAAAA,OAAOF,UAAU,YAAjBE,qBAAqB;QAC/C,IAAI,CAACnC,aAAaiC,aAAa,OAAO;QACtC,MAAMG,WAAW5B,YAAY2B,OAAOC,QAAQ;QAE5C;;;;;;;;;KASC,GACD,MAAMG,QACHC,UAAU,CAAC,aACXC,GAAG,CAACR,YACJO,UAAU,CAAC,WACXC,GAAG,CAACnC,6BACJuC,GAAG,CACF;YACEC,YAAY;gBACV,CAACV,SAAS,EAAE;oBACVuB,eAAejE,WAAWsD,SAAS,CAACvB;mBAChCH,QAAQsC,cAAc,GACtB;oBAAEC,gBAAgBnE,WAAWsD,SAAS,CAAC;gBAAG,IAC1C,CAAC;YAET;YACAE,WAAWxD,WAAWkD,eAAe;QACvC,GACA;YAAEO,OAAO;QAAK;QAGlB;;;;;;KAMC,GACD,MAAMI,SAASO,GAAG,CACfjB,GAAG,CACF;YACEc,eAAejE,WAAWsD,SAAS,CAACvB;YACpCsC,gBAAgBpC,KAAKC,GAAG;WACpBN,QAAQ0C,IAAI,KAAK,eAAe;YAAEC,aAAa;QAAK,IAAI,CAAC,GACzD3C,QAAQsC,cAAc,GAAG;YAAEM,eAAe;QAAK,IAAI,CAAC,IAE1D;YAAEf,OAAO;QAAK,GAEfgB,KAAK,CAAC,IAAMC;QAEf,OAAO;IACT,EAAE,OAAOhB,OAAO;QACdC,QAAQD,KAAK,CAAC,wCAAwCA;QACtD,OAAO;IACT;AACF;AAEA,6EAA6E,GAC7E,SAASvD,2BAA2B,GAAE"}

package/src/lib/server/email-send-rate.d.ts

@@ -0,0 +1,232 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * THE PLATFORM SEND-RATE GOVERNOR — durable half (AGL-2409).
+ *
+ * The policy is pure and lives in `@aglyn/shared-util-email`
+ * (`send-rate.ts`); this adds the Firestore counter that makes the ceiling
+ * global rather than per-instance, the configuration read that makes a ramp a
+ * value change instead of a deploy, and the installation that puts the whole
+ * thing on `sendEmail`'s path.
+ *
+ * ## Storage: the `rateLimits` collection, on purpose
+ *
+ * Both documents live in `rateLimits`, the same collection AGL-794's counters,
+ * AGL-1679's degradation markers and AGL-1907's signup-refusal markers already
+ * use, for the reason those two state: it inherits the deny-all security rule
+ * and the `expiresAt` TTL policy that already exist rather than needing a new
+ * collection, a rules deploy and a second TTL policy.
+ *
+ *  - `rateLimits/sendRate_{windowStartMs}` — one document per hour, holding
+ *    the count. Carries `expiresAt`, so the TTL policy sweeps it.
+ *  - `rateLimits/sendRateConfig` — the ceiling. **Carries NO `expiresAt`, and
+ *    must never be given one**, or the TTL policy that serves the counters
+ *    would quietly delete the configuration and the platform would silently
+ *    revert to the compiled-in default. `emailSendRateConfigWrite` is the one
+ *    writer and `email-send-rate.spec.ts` asserts the field is absent.
+ *
+ * The window document does NOT carry `lastAtMs`. AGL-1693's rate-limiter
+ * health probe queries this collection with `where('lastAtMs', '>=', cutoff)`;
+ * a per-hour document in that range would compete with the degradation
+ * markers the probe exists to find. It uses `sentAtMs`, which keeps the two
+ * queries disjoint at the index level — the same reasoning, and the same
+ * mistake avoided, as `refusedAtMs` on the signup markers.
+ *
+ * ## Failure posture: OPEN
+ *
+ * If the counter or the config cannot be read, every send is granted. That is
+ * the opposite of `consumeRateLimit`'s fail-closed-on-contention rule, and the
+ * difference is what the two controls protect. A brute-force limiter that
+ * fails open lets an attacker in; this one failing open lets a campaign out.
+ * The cost of failing CLOSED here is refusing a paying customer's campaign
+ * because of an unrelated Firestore blip — and, worse, refusing a bulk sweep
+ * that a customer's month depends on. Neither is worth the hour of ramp it
+ * would buy back, and the operator can see it: a degraded grant is reported
+ * and surfaced on /admin/emails.
+ */
+import { type EmailSendPriority, type EmailSendRateConfig, type EmailSendRateVerdict } from '@aglyn/shared-util-email';
+/** Document id of the live ceiling. NEVER written with `expiresAt`. */
+export declare const EMAIL_SEND_RATE_CONFIG_DOC = "sendRateConfig";
+/** Id prefix for the per-hour counters. */
+export declare const EMAIL_SEND_RATE_WINDOW_PREFIX = "sendRate_";
+/** The counter document id for a window. */
+export declare function emailSendRateWindowDocId(windowStartMs: number): string;
+/** Drop the in-process config cache — called by the console after a write. */
+export declare function invalidateEmailSendRateConfigCache(): void;
+/**
+ * The live ceiling. Falls back to the compiled-in default on any read error,
+ * which is the fail-open posture stated above: an unreachable config must not
+ * be read as a ceiling of zero.
+ */
+export declare function readEmailSendRateConfig(options?: {
+    firestore?: any;
+    now?: number;
+}): Promise<EmailSendRateConfig>;
+export interface ConsumeEmailSendBudgetOptions {
+    priority: EmailSendPriority;
+    /** Messages this send would add. */
+    count: number;
+    now?: number;
+    firestore?: any;
+    /** Injectable for tests; otherwise read (and cached) from Firestore. */
+    config?: EmailSendRateConfig;
+}
+export interface ConsumeEmailSendBudgetResult extends EmailSendRateVerdict {
+    windowStartMs: number;
+    /** True when the counter was unreachable and this failed open. */
+    degraded: boolean;
+}
+/**
+ * Counts `count` messages against the current hour, globally, and answers
+ * whether they may go.
+ *
+ * The transaction reads the counter and writes an ABSOLUTE value derived from
+ * that read — not `FieldValue.increment` — because the read is the authority
+ * for the decision. Firestore aborts and re-runs the callback when a
+ * document it read has moved, so two concurrent sweeps cannot both see the
+ * same headroom and both take it. An increment would be atomic on the number
+ * and useless for the decision, which is exactly the read-then-write shape
+ * AGL-2267 is about one surface over.
+ *
+ * A refused send writes NOTHING. A caller that will retry next hour must not
+ * have spent budget on being told no.
+ */
+export declare function consumeEmailSendBudget(options: ConsumeEmailSendBudgetOptions): Promise<ConsumeEmailSendBudgetResult>;
+/**
+ * What the current hour looks like. Read-only, for the staff console.
+ *
+ * Returns `used: 0` rather than throwing when the window document does not
+ * exist, which is the ordinary state of a quiet hour.
+ */
+export declare function readEmailSendRateWindow(options?: {
+    firestore?: any;
+    now?: number;
+}): Promise<{
+    windowStartMs: number;
+    resetMs: number;
+    used: number;
+}>;
+/** Id prefix for the per-org, per-hour campaign counters. */
+export declare const EMAIL_ORG_SEND_RATE_WINDOW_PREFIX = "sendRateOrg_";
+/**
+ * The per-org counter document id for a window.
+ *
+ * A separate document per org rather than a map field on the platform window,
+ * so two orgs sending in the same hour contend on their own documents instead
+ * of serialising on one. The platform window is already a single hot document
+ * and adding N org fields to it would make every campaign in the hour a write
+ * conflict with every other.
+ */
+export declare function emailOrgSendRateWindowDocId(windowStartMs: number, orgId: string): string;
+/** The current hour for one org. Read-only, for a usage surface. */
+export declare function readOrgEmailSendWindow(options: {
+    orgId: string;
+    firestore?: any;
+    now?: number;
+}): Promise<{
+    windowStartMs: number;
+    resetMs: number;
+    used: number;
+}>;
+/** The answer to a per-org hourly claim. Every field is a stated number. */
+export interface OrgEmailSendClaimResult {
+    allowed: boolean;
+    /** Count in this org's window BEFORE this send. */
+    used: number;
+    /** What this org may send in an hour. */
+    ceiling: number;
+    /** Headroom after this send, floored at 0. */
+    remaining: number;
+    /** When the window rolls and a deferred campaign may go. */
+    retryAtMs: number;
+    /** True when the counter was unreachable and this failed open. */
+    degraded: boolean;
+}
+/**
+ * THE PER-ORG SHARE OF THE PLATFORM HOUR.
+ *
+ * The platform governor bounds total volume; it does not bound how much of
+ * that total ONE tenant may take. Without this, a single org with a large
+ * audience occupies the whole hour and every other customer's campaigns are
+ * refused by a ceiling they did nothing to reach — one tenant denying service
+ * to the rest, on a limit they cannot see.
+ *
+ * The ceiling is derived, not configured: `orgHourlyCampaignCeiling` is a
+ * share of whatever the live platform ceiling currently is, so a staff ramp
+ * moves both together and the two can never drift into contradiction. See
+ * `send-ceilings.ts` for the arithmetic and the relations it maintains.
+ *
+ * **Campaigns only.** This function is not on `sendEmail`'s path and is called
+ * from the campaign sender alone. A transactional message can never reach it,
+ * which is the same boundary `emailSendRateVerdict` enforces one layer down
+ * and for the same reason: a password reset refused by a throttle converts a
+ * reputation risk into an outage on somebody else's business.
+ *
+ * ## Fails OPEN
+ *
+ * An unreachable counter grants the send, matching `consumeEmailSendBudget`.
+ * A refusal produced by a Firestore blip is a refused campaign for a paying
+ * customer, and the hour of pacing it buys back is not worth it.
+ *
+ * ## Claimed, not reconciled
+ *
+ * The claim is taken for the whole batch and never refunded, unlike the
+ * monthly reservation. The window is one hour and TTL-swept, so an
+ * undelivered remainder costs the org the rest of that hour and nothing
+ * after it — where an unreconciled MONTHLY claim would cost the rest of the
+ * month, which is why that one is reconciled and this one is not. The error
+ * is in the direction that can only ever pace mail more, never let more out.
+ */
+export declare function claimOrgEmailSendBudget(options: {
+    orgId: string;
+    /** Messages this campaign would send. */
+    count: number;
+    /** The live platform ceiling; the org share is derived from it. */
+    platformPerHour: number;
+    /** False parks the control, exactly as the platform governor's flag does. */
+    enabled?: boolean;
+    now?: number;
+    firestore?: any;
+}): Promise<OrgEmailSendClaimResult>;
+/**
+ * The document the console writes when staff move the ramp.
+ *
+ * Returned rather than written so the route owns the write (and the audit row
+ * beside it), and so a spec can assert the SHAPE without a Firestore. The one
+ * thing it must never contain is `expiresAt`.
+ */
+export declare function emailSendRateConfigWrite(input: {
+    perHour: number;
+    enabled: boolean;
+    actorEmail?: string | null;
+    note?: string;
+    now?: number;
+}): Partial<EmailSendRateConfig>;
+/**
+ * Puts the durable governor on `sendEmail`'s path.
+ *
+ * **Called at module load**, from the bottom of this file, so that importing
+ * `@aglyn/tenant-data-admin` anywhere is enough — every server surface in the
+ * product already imports that barrel, and `export *` forces this module to
+ * evaluate. The alternative, an `installEmailSendGovernor()` call at each
+ * server entrypoint, is the 37-places-to-remember shape this codebase already
+ * rejected once for the `context` tag.
+ *
+ * Idempotent: installing twice replaces the same closure with an equivalent
+ * one, and the closure holds no state — the state is the Firestore document.
+ */
+export declare function installEmailSendGovernor(): void;