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

package/src/lib/server/crm-records.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AglynOrgBilling } from '@aglyn/aglyn/foundation';
+import { type CrmActivityLink, type CrmEmailQuotaResult, type CrmRecordsQuotaResult } from '@aglyn/aglyn/server';
+import { type EmailRampVerdict } from '@aglyn/shared-util-email';
+/**
+ * The CRM RECORDS band's measurement (AGL-2611): the three collections it
+ * counts, and their sum.
+ *
+ * One shape for every server that asks, because the band is enforced at six
+ * doors — contact capture, the console's company and deal drawers (through
+ * the client twin of this read), the CSV import, the lead conversion and the
+ * two REST creates — and the monthly rollup bills from the same three
+ * aggregates. A door that counted contacts alone would admit a company on a
+ * band the rollup had already found full.
+ */
+export interface CrmRecordsCount {
+    contactsCount: number;
+    companiesCount: number;
+    dealsCount: number;
+    /** The band's own figure: the three above, summed. */
+    crmRecordsCount: number;
+}
+/**
+ * Count the records band for one org: three `count()` aggregates, in
+ * parallel, no document reads.
+ *
+ * `contacts` may be handed in by a caller that already holds the collection
+ * reference — `upsertHostContact` resolves it through `orgDataCollection`
+ * before it decides anything — so the read is the same one whichever door
+ * it came through, and the org reference is needed only for the two
+ * collections the hub added.
+ */
+export declare function countCrmRecords(orgRef: FirebaseFirestore.DocumentReference, contacts?: FirebaseFirestore.CollectionReference): Promise<CrmRecordsCount>;
+/**
+ * The band's verdict for one org, measured now — the read every create
+ * door takes before it writes, so the six doors cannot disagree about
+ * whether there is room. `checkCrmRecordsQuota` answers from the org doc
+ * alone; this pairs it with the measurement.
+ */
+export declare function crmRecordsQuotaForOrg(org: Partial<AglynOrgBilling> | null | undefined, orgRef: FirebaseFirestore.DocumentReference, contacts?: FirebaseFirestore.CollectionReference): Promise<CrmRecordsQuotaResult & CrmRecordsCount>;
+/**
+ * How many activities one record already carries — one aggregate on a
+ * single-field equality, which Firestore indexes on its own, so this needs
+ * no composite index and cannot go FAILED_PRECONDITION in production.
+ */
+export declare function countCrmActivitiesForRecord(orgRef: FirebaseFirestore.DocumentReference, link: CrmActivityLink): Promise<number>;
+/** Today's counter document — {@link crmEmailUsageRefForDay} keyed by `now`. */
+export declare function crmEmailUsageRef(firestore: FirebaseFirestore.Firestore, orgId: string, now?: Date): FirebaseFirestore.DocumentReference;
+/**
+ * How many one-to-one emails the org has sent today, for a meter — never
+ * for the cap, which {@link reserveCrmEmailSend} judges inside the
+ * transaction that also takes the slot.
+ */
+export declare function crmEmailsSentToday(firestore: FirebaseFirestore.Firestore, orgId: string, now?: Date): Promise<number>;
+/** One slot on one day's counter, held from the reservation to the send. */
+export interface CrmEmailSendReservation {
+    orgId: string;
+    /**
+     * The UTC day the slot was taken on, so a release after midnight gives
+     * the slot back to the day that lent it rather than to the new day.
+     */
+    day: string;
+}
+export type ReserveCrmEmailSendResult = {
+    ok: true;
+    reservation: CrmEmailSendReservation;
+    quota: CrmEmailQuotaResult;
+} | {
+    ok: false;
+    quota: CrmEmailQuotaResult;
+};
+/**
+ * Claims ONE one-to-one send against today's cap, ATOMICALLY (AGL-2645).
+ *
+ * The counter used to be read before the send and incremented after
+ * delivery, so two reps sending in the same window both passed the same
+ * reading and both sent — `CRM_EMAIL_SENDS_PER_MINUTE` past the cap per
+ * sender, in exactly the conditions the cap exists for. **A read-then-write
+ * cap is not a cap**, the lesson `reserveCampaignEmailSends` learned for
+ * campaigns; this is the same shape on the day counter.
+ *
+ * The transaction reads the counter, judges it with `checkCrmEmailQuota` —
+ * the real plan table, `UNLIMITED` on Enterprise, zero on a tier with no
+ * suite — 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. A taken one is the count the cap
+ * enforces and the billing page shows, from the moment it is taken: a send
+ * the provider then refuses hands the slot back through
+ * {@link releaseCrmEmailSend}, and a process that dies between the two
+ * leaves the org one send short for the rest of the UTC day — conservative
+ * in the direction a cap cares about, and healed at midnight, because each
+ * day is its own document.
+ *
+ * ## The new-sender ramp rides the same read
+ *
+ * `ramp` narrows the plan's day to the share of it a young workspace has
+ * earned, INSIDE the transaction and before the counter is judged — see
+ * {@link rampedCrmEmailQuota}. Applying it here rather than in the caller is
+ * the whole of what makes it safe: the ceiling and the count it is compared
+ * against come out of one read, so the retry Firestore forces on a losing
+ * transaction re-derives both. A ramp checked outside would be a second
+ * ceiling, decided from a snapshot the write never proves it still held —
+ * the defect this reservation was built to remove, one field over.
+ *
+ * The ramp is optional and an absent one is not a throttle: a caller that
+ * did not resolve one gets the plan's day, which is what every surface but
+ * the send path wants.
+ */
+export declare function reserveCrmEmailSend(firestore: FirebaseFirestore.Firestore, orgId: string, org: Partial<AglynOrgBilling> | null | undefined, now?: Date, ramp?: EmailRampVerdict | null): Promise<ReserveCrmEmailSendResult>;
+/**
+ * Gives back a slot the provider did not use.
+ *
+ * Also a transaction, and also an absolute write from its own read: a
+ * decrement computed from a stale figure would undo a slot another rep took
+ * in the meantime, which is the same defect one direction over. Never
+ * drives the counter below zero.
+ *
+ * **Never throws.** This runs on the failure path of a send that was
+ * already refused, and the answer the rep gets is the provider's refusal; a
+ * bookkeeping failure on top of it is logged, and its cost is one slot the
+ * org does not get back until midnight — the safe direction.
+ */
+export declare function releaseCrmEmailSend(firestore: FirebaseFirestore.Firestore, reservation: CrmEmailSendReservation | null | undefined): Promise<void>;

package/src/lib/server/crm-records.js

@@ -0,0 +1,218 @@
+/**
+ * @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 { _ as _extends } from "@swc/helpers/_/_extends";
+import { checkCrmEmailQuota, checkCrmRecordsQuota, CRM_COLLECTIONS, CRM_EMAIL_USAGE_COLLECTION, crmActivityCeilingLink, crmEmailUsageDayKey } from "@aglyn/aglyn/server";
+import { rampedDailyAllowance } from "@aglyn/shared-util-email";
+import { FieldValue } from "firebase-admin/firestore";
+/**
+ * Count the records band for one org: three `count()` aggregates, in
+ * parallel, no document reads.
+ *
+ * `contacts` may be handed in by a caller that already holds the collection
+ * reference — `upsertHostContact` resolves it through `orgDataCollection`
+ * before it decides anything — so the read is the same one whichever door
+ * it came through, and the org reference is needed only for the two
+ * collections the hub added.
+ */ export async function countCrmRecords(orgRef, contacts = orgRef.collection('contacts')) {
+    const [contactsSnap, companiesSnap, dealsSnap] = await Promise.all([
+        contacts.count().get(),
+        orgRef.collection(CRM_COLLECTIONS.companies).count().get(),
+        orgRef.collection(CRM_COLLECTIONS.deals).count().get()
+    ]);
+    const contactsCount = aggregateCount(contactsSnap);
+    const companiesCount = aggregateCount(companiesSnap);
+    const dealsCount = aggregateCount(dealsSnap);
+    return {
+        contactsCount,
+        companiesCount,
+        dealsCount,
+        crmRecordsCount: contactsCount + companiesCount + dealsCount
+    };
+}
+/**
+ * The band's verdict for one org, measured now — the read every create
+ * door takes before it writes, so the six doors cannot disagree about
+ * whether there is room. `checkCrmRecordsQuota` answers from the org doc
+ * alone; this pairs it with the measurement.
+ */ export async function crmRecordsQuotaForOrg(org, orgRef, contacts) {
+    const counts = await countCrmRecords(orgRef, contacts);
+    return _extends({}, checkCrmRecordsQuota(org, counts.crmRecordsCount), counts);
+}
+/** `count()` answers through `.data().count`; a missing figure is zero, never NaN. */ function aggregateCount(snapshot) {
+    var _ref;
+    var _snapshot_data;
+    const value = Number((_ref = (_snapshot_data = snapshot.data()) == null ? void 0 : _snapshot_data.count) != null ? _ref : 0);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * How many activities one record already carries — one aggregate on a
+ * single-field equality, which Firestore indexes on its own, so this needs
+ * no composite index and cannot go FAILED_PRECONDITION in production.
+ */ export async function countCrmActivitiesForRecord(orgRef, link) {
+    const lead = crmActivityCeilingLink(link);
+    if (!lead) return 0;
+    const snapshot = await orgRef.collection(CRM_COLLECTIONS.activities).where(lead.field, '==', lead.id).count().get();
+    return aggregateCount(snapshot);
+}
+/**
+ * `orgs/{orgId}/crmEmailUsage/{day}` — one UTC day's one-to-one email
+ * counter, the document `checkCrmEmailQuota` is enforced against and the
+ * billing page reads.
+ */ function crmEmailUsageRefForDay(firestore, orgId, day) {
+    return firestore.collection('orgs').doc(orgId).collection(CRM_EMAIL_USAGE_COLLECTION).doc(day);
+}
+/** Today's counter document — {@link crmEmailUsageRefForDay} keyed by `now`. */ export function crmEmailUsageRef(firestore, orgId, now = new Date()) {
+    return crmEmailUsageRefForDay(firestore, orgId, crmEmailUsageDayKey(now));
+}
+/**
+ * The counter a day-document holds, clamped.
+ *
+ * A malformed or absent counter reads as ZERO SENT, which is the permissive
+ * direction — deliberately, and the same clamp `checkApiRequestQuota`'s
+ * reader applies: a counter that cannot be read must not refuse a rep who
+ * has sent nothing, and the cap is a pace rather than a cost.
+ */ function crmEmailCount(snapshot) {
+    var _snapshot_get;
+    const value = Number((_snapshot_get = snapshot.get('count')) != null ? _snapshot_get : 0);
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+ * How many one-to-one emails the org has sent today, for a meter — never
+ * for the cap, which {@link reserveCrmEmailSend} judges inside the
+ * transaction that also takes the slot.
+ */ export async function crmEmailsSentToday(firestore, orgId, now = new Date()) {
+    return crmEmailCount(await crmEmailUsageRef(firestore, orgId, now).get());
+}
+/**
+ * The plan's day, narrowed to the share of it a young workspace has earned.
+ *
+ * The new-sender ramp reaches the one-to-one path here and only here, so the
+ * ceiling the transaction below judges against is one value with one origin.
+ * The alternative — a full-allowance reservation with a ramp consulted beside
+ * it — is two ceilings for one decision, and under two concurrent senders it
+ * admits against whichever of them was read first.
+ *
+ * `included` is the only field the ramp moves; `resetsAt` is the day's, which
+ * a share does not change, and `used` is what the transaction read.
+ */ function rampedCrmEmailQuota(plan, ramp) {
+    const included = rampedDailyAllowance(plan.included, ramp);
+    if (included >= plan.included) return plan;
+    return _extends({}, plan, {
+        included,
+        allowed: plan.used < included,
+        remaining: Math.max(0, included - plan.used)
+    });
+}
+/**
+ * Claims ONE one-to-one send against today's cap, ATOMICALLY (AGL-2645).
+ *
+ * The counter used to be read before the send and incremented after
+ * delivery, so two reps sending in the same window both passed the same
+ * reading and both sent — `CRM_EMAIL_SENDS_PER_MINUTE` past the cap per
+ * sender, in exactly the conditions the cap exists for. **A read-then-write
+ * cap is not a cap**, the lesson `reserveCampaignEmailSends` learned for
+ * campaigns; this is the same shape on the day counter.
+ *
+ * The transaction reads the counter, judges it with `checkCrmEmailQuota` —
+ * the real plan table, `UNLIMITED` on Enterprise, zero on a tier with no
+ * suite — 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. A taken one is the count the cap
+ * enforces and the billing page shows, from the moment it is taken: a send
+ * the provider then refuses hands the slot back through
+ * {@link releaseCrmEmailSend}, and a process that dies between the two
+ * leaves the org one send short for the rest of the UTC day — conservative
+ * in the direction a cap cares about, and healed at midnight, because each
+ * day is its own document.
+ *
+ * ## The new-sender ramp rides the same read
+ *
+ * `ramp` narrows the plan's day to the share of it a young workspace has
+ * earned, INSIDE the transaction and before the counter is judged — see
+ * {@link rampedCrmEmailQuota}. Applying it here rather than in the caller is
+ * the whole of what makes it safe: the ceiling and the count it is compared
+ * against come out of one read, so the retry Firestore forces on a losing
+ * transaction re-derives both. A ramp checked outside would be a second
+ * ceiling, decided from a snapshot the write never proves it still held —
+ * the defect this reservation was built to remove, one field over.
+ *
+ * The ramp is optional and an absent one is not a throttle: a caller that
+ * did not resolve one gets the plan's day, which is what every surface but
+ * the send path wants.
+ */ export async function reserveCrmEmailSend(firestore, orgId, org, now = new Date(), ramp) {
+    const day = crmEmailUsageDayKey(now);
+    const ref = crmEmailUsageRefForDay(firestore, orgId, day);
+    return firestore.runTransaction(async (tx)=>{
+        const quota = rampedCrmEmailQuota(checkCrmEmailQuota(org, crmEmailCount(await tx.get(ref)), now), ramp);
+        if (!quota.allowed) return {
+            ok: false,
+            quota
+        };
+        tx.set(ref, {
+            count: quota.used + 1,
+            day,
+            updatedAt: FieldValue.serverTimestamp()
+        }, {
+            merge: true
+        });
+        return {
+            ok: true,
+            reservation: {
+                orgId,
+                day
+            },
+            quota
+        };
+    });
+}
+/**
+ * Gives back a slot the provider did not use.
+ *
+ * Also a transaction, and also an absolute write from its own read: a
+ * decrement computed from a stale figure would undo a slot another rep took
+ * in the meantime, which is the same defect one direction over. Never
+ * drives the counter below zero.
+ *
+ * **Never throws.** This runs on the failure path of a send that was
+ * already refused, and the answer the rep gets is the provider's refusal; a
+ * bookkeeping failure on top of it is logged, and its cost is one slot the
+ * org does not get back until midnight — the safe direction.
+ */ export async function releaseCrmEmailSend(firestore, reservation) {
+    if (!(reservation == null ? void 0 : reservation.orgId) || !reservation.day) return;
+    const ref = crmEmailUsageRefForDay(firestore, reservation.orgId, reservation.day);
+    try {
+        await firestore.runTransaction(async (tx)=>{
+            const used = crmEmailCount(await tx.get(ref));
+            tx.set(ref, {
+                count: Math.max(0, used - 1),
+                day: reservation.day,
+                updatedAt: FieldValue.serverTimestamp()
+            }, {
+                merge: true
+            });
+        });
+    } catch (error) {
+        console.error('crm email reservation release failed', error);
+    }
+}
+
+//# sourceMappingURL=crm-records.js.map

package/src/lib/server/crm-records.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/crm-records.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 type { AglynOrgBilling } from '@aglyn/aglyn/foundation'\nimport {\n  checkCrmEmailQuota,\n  checkCrmRecordsQuota,\n  CRM_COLLECTIONS,\n  CRM_EMAIL_USAGE_COLLECTION,\n  type CrmActivityLink,\n  crmActivityCeilingLink,\n  type CrmEmailQuotaResult,\n  crmEmailUsageDayKey,\n  type CrmRecordsQuotaResult,\n} from '@aglyn/aglyn/server'\nimport {\n  type EmailRampVerdict,\n  rampedDailyAllowance,\n} from '@aglyn/shared-util-email'\nimport { FieldValue } from 'firebase-admin/firestore'\n\n/**\n * The CRM RECORDS band's measurement (AGL-2611): the three collections it\n * counts, and their sum.\n *\n * One shape for every server that asks, because the band is enforced at six\n * doors — contact capture, the console's company and deal drawers (through\n * the client twin of this read), the CSV import, the lead conversion and the\n * two REST creates — and the monthly rollup bills from the same three\n * aggregates. A door that counted contacts alone would admit a company on a\n * band the rollup had already found full.\n */\nexport interface CrmRecordsCount {\n  contactsCount: number\n  companiesCount: number\n  dealsCount: number\n  /** The band's own figure: the three above, summed. */\n  crmRecordsCount: number\n}\n\n/**\n * Count the records band for one org: three `count()` aggregates, in\n * parallel, no document reads.\n *\n * `contacts` may be handed in by a caller that already holds the collection\n * reference — `upsertHostContact` resolves it through `orgDataCollection`\n * before it decides anything — so the read is the same one whichever door\n * it came through, and the org reference is needed only for the two\n * collections the hub added.\n */\nexport async function countCrmRecords(\n  orgRef: FirebaseFirestore.DocumentReference,\n  contacts: FirebaseFirestore.CollectionReference = orgRef.collection('contacts'),\n): Promise<CrmRecordsCount> {\n  const [contactsSnap, companiesSnap, dealsSnap] = await Promise.all([\n    contacts.count().get(),\n    orgRef.collection(CRM_COLLECTIONS.companies).count().get(),\n    orgRef.collection(CRM_COLLECTIONS.deals).count().get(),\n  ])\n  const contactsCount = aggregateCount(contactsSnap)\n  const companiesCount = aggregateCount(companiesSnap)\n  const dealsCount = aggregateCount(dealsSnap)\n  return {\n    contactsCount,\n    companiesCount,\n    dealsCount,\n    crmRecordsCount: contactsCount + companiesCount + dealsCount,\n  }\n}\n\n/**\n * The band's verdict for one org, measured now — the read every create\n * door takes before it writes, so the six doors cannot disagree about\n * whether there is room. `checkCrmRecordsQuota` answers from the org doc\n * alone; this pairs it with the measurement.\n */\nexport async function crmRecordsQuotaForOrg(\n  org: Partial<AglynOrgBilling> | null | undefined,\n  orgRef: FirebaseFirestore.DocumentReference,\n  contacts?: FirebaseFirestore.CollectionReference,\n): Promise<CrmRecordsQuotaResult & CrmRecordsCount> {\n  const counts = await countCrmRecords(orgRef, contacts)\n  return { ...checkCrmRecordsQuota(org, counts.crmRecordsCount), ...counts }\n}\n\n/** `count()` answers through `.data().count`; a missing figure is zero, never NaN. */\nfunction aggregateCount(snapshot: { data(): { count?: unknown } }): number {\n  const value = Number(snapshot.data()?.count ?? 0)\n  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0\n}\n\n/**\n * How many activities one record already carries — one aggregate on a\n * single-field equality, which Firestore indexes on its own, so this needs\n * no composite index and cannot go FAILED_PRECONDITION in production.\n */\nexport async function countCrmActivitiesForRecord(\n  orgRef: FirebaseFirestore.DocumentReference,\n  link: CrmActivityLink,\n): Promise<number> {\n  const lead = crmActivityCeilingLink(link)\n  if (!lead) return 0\n  const snapshot = await orgRef\n    .collection(CRM_COLLECTIONS.activities)\n    .where(lead.field, '==', lead.id)\n    .count()\n    .get()\n  return aggregateCount(snapshot)\n}\n\n/**\n * `orgs/{orgId}/crmEmailUsage/{day}` — one UTC day's one-to-one email\n * counter, the document `checkCrmEmailQuota` is enforced against and the\n * billing page reads.\n */\nfunction crmEmailUsageRefForDay(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  day: string,\n): FirebaseFirestore.DocumentReference {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(CRM_EMAIL_USAGE_COLLECTION)\n    .doc(day)\n}\n\n/** Today's counter document — {@link crmEmailUsageRefForDay} keyed by `now`. */\nexport function crmEmailUsageRef(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  now: Date = new Date(),\n): FirebaseFirestore.DocumentReference {\n  return crmEmailUsageRefForDay(firestore, orgId, crmEmailUsageDayKey(now))\n}\n\n/**\n * The counter a day-document holds, clamped.\n *\n * A malformed or absent counter reads as ZERO SENT, which is the permissive\n * direction — deliberately, and the same clamp `checkApiRequestQuota`'s\n * reader applies: a counter that cannot be read must not refuse a rep who\n * has sent nothing, and the cap is a pace rather than a cost.\n */\nfunction crmEmailCount(snapshot: { get(field: string): unknown }): number {\n  const value = Number(snapshot.get('count') ?? 0)\n  return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0\n}\n\n/**\n * How many one-to-one emails the org has sent today, for a meter — never\n * for the cap, which {@link reserveCrmEmailSend} judges inside the\n * transaction that also takes the slot.\n */\nexport async function crmEmailsSentToday(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  now: Date = new Date(),\n): Promise<number> {\n  return crmEmailCount(await crmEmailUsageRef(firestore, orgId, now).get())\n}\n\n/** One slot on one day's counter, held from the reservation to the send. */\nexport interface CrmEmailSendReservation {\n  orgId: string\n  /**\n   * The UTC day the slot was taken on, so a release after midnight gives\n   * the slot back to the day that lent it rather than to the new day.\n   */\n  day: string\n}\n\nexport type ReserveCrmEmailSendResult =\n  | { ok: true; reservation: CrmEmailSendReservation; quota: CrmEmailQuotaResult }\n  | { ok: false; quota: CrmEmailQuotaResult }\n\n/**\n * The plan's day, narrowed to the share of it a young workspace has earned.\n *\n * The new-sender ramp reaches the one-to-one path here and only here, so the\n * ceiling the transaction below judges against is one value with one origin.\n * The alternative — a full-allowance reservation with a ramp consulted beside\n * it — is two ceilings for one decision, and under two concurrent senders it\n * admits against whichever of them was read first.\n *\n * `included` is the only field the ramp moves; `resetsAt` is the day's, which\n * a share does not change, and `used` is what the transaction read.\n */\nfunction rampedCrmEmailQuota(\n  plan: CrmEmailQuotaResult,\n  ramp: EmailRampVerdict | null | undefined,\n): CrmEmailQuotaResult {\n  const included = rampedDailyAllowance(plan.included, ramp)\n  if (included >= plan.included) return plan\n  return {\n    ...plan,\n    included,\n    allowed: plan.used < included,\n    remaining: Math.max(0, included - plan.used),\n  }\n}\n\n/**\n * Claims ONE one-to-one send against today's cap, ATOMICALLY (AGL-2645).\n *\n * The counter used to be read before the send and incremented after\n * delivery, so two reps sending in the same window both passed the same\n * reading and both sent — `CRM_EMAIL_SENDS_PER_MINUTE` past the cap per\n * sender, in exactly the conditions the cap exists for. **A read-then-write\n * cap is not a cap**, the lesson `reserveCampaignEmailSends` learned for\n * campaigns; this is the same shape on the day counter.\n *\n * The transaction reads the counter, judges it with `checkCrmEmailQuota` —\n * the real plan table, `UNLIMITED` on Enterprise, zero on a tier with no\n * suite — and writes an ABSOLUTE value derived from that read, deliberately\n * not `FieldValue.increment`. Firestore aborts and re-runs the callback\n * when a document the transaction read has moved, so a second sender that\n * starts inside the first one's window re-reads the raised figure and is\n * refused. An increment would be atomic on the number and useless for the\n * decision, because the decision is made from a value the write never\n * proves it still held.\n *\n * A refused reservation writes NOTHING. A taken one is the count the cap\n * enforces and the billing page shows, from the moment it is taken: a send\n * the provider then refuses hands the slot back through\n * {@link releaseCrmEmailSend}, and a process that dies between the two\n * leaves the org one send short for the rest of the UTC day — conservative\n * in the direction a cap cares about, and healed at midnight, because each\n * day is its own document.\n *\n * ## The new-sender ramp rides the same read\n *\n * `ramp` narrows the plan's day to the share of it a young workspace has\n * earned, INSIDE the transaction and before the counter is judged — see\n * {@link rampedCrmEmailQuota}. Applying it here rather than in the caller is\n * the whole of what makes it safe: the ceiling and the count it is compared\n * against come out of one read, so the retry Firestore forces on a losing\n * transaction re-derives both. A ramp checked outside would be a second\n * ceiling, decided from a snapshot the write never proves it still held —\n * the defect this reservation was built to remove, one field over.\n *\n * The ramp is optional and an absent one is not a throttle: a caller that\n * did not resolve one gets the plan's day, which is what every surface but\n * the send path wants.\n */\nexport async function reserveCrmEmailSend(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  org: Partial<AglynOrgBilling> | null | undefined,\n  now: Date = new Date(),\n  ramp?: EmailRampVerdict | null,\n): Promise<ReserveCrmEmailSendResult> {\n  const day = crmEmailUsageDayKey(now)\n  const ref = crmEmailUsageRefForDay(firestore, orgId, day)\n  return firestore.runTransaction(async (tx) => {\n    const quota = rampedCrmEmailQuota(\n      checkCrmEmailQuota(org, crmEmailCount(await tx.get(ref)), now),\n      ramp,\n    )\n    if (!quota.allowed) return { ok: false, quota }\n    tx.set(\n      ref,\n      { count: quota.used + 1, day, updatedAt: FieldValue.serverTimestamp() },\n      { merge: true },\n    )\n    return { ok: true, reservation: { orgId, day }, quota }\n  })\n}\n\n/**\n * Gives back a slot the provider did not use.\n *\n * Also a transaction, and also an absolute write from its own read: a\n * decrement computed from a stale figure would undo a slot another rep took\n * in the meantime, which is the same defect one direction over. Never\n * drives the counter below zero.\n *\n * **Never throws.** This runs on the failure path of a send that was\n * already refused, and the answer the rep gets is the provider's refusal; a\n * bookkeeping failure on top of it is logged, and its cost is one slot the\n * org does not get back until midnight — the safe direction.\n */\nexport async function releaseCrmEmailSend(\n  firestore: FirebaseFirestore.Firestore,\n  reservation: CrmEmailSendReservation | null | undefined,\n): Promise<void> {\n  if (!reservation?.orgId || !reservation.day) return\n  const ref = crmEmailUsageRefForDay(firestore, reservation.orgId, reservation.day)\n  try {\n    await firestore.runTransaction(async (tx) => {\n      const used = crmEmailCount(await tx.get(ref))\n      tx.set(\n        ref,\n        {\n          count: Math.max(0, used - 1),\n          day: reservation.day,\n          updatedAt: FieldValue.serverTimestamp(),\n        },\n        { merge: true },\n      )\n    })\n  } catch (error) {\n    console.error('crm email reservation release failed', error)\n  }\n}\n"],"names":["checkCrmEmailQuota","checkCrmRecordsQuota","CRM_COLLECTIONS","CRM_EMAIL_USAGE_COLLECTION","crmActivityCeilingLink","crmEmailUsageDayKey","rampedDailyAllowance","FieldValue","countCrmRecords","orgRef","contacts","collection","contactsSnap","companiesSnap","dealsSnap","Promise","all","count","get","companies","deals","contactsCount","aggregateCount","companiesCount","dealsCount","crmRecordsCount","crmRecordsQuotaForOrg","org","counts","snapshot","value","Number","data","isFinite","Math","floor","countCrmActivitiesForRecord","link","lead","activities","where","field","id","crmEmailUsageRefForDay","firestore","orgId","day","doc","crmEmailUsageRef","now","Date","crmEmailCount","crmEmailsSentToday","rampedCrmEmailQuota","plan","ramp","included","allowed","used","remaining","max","reserveCrmEmailSend","ref","runTransaction","tx","quota","ok","set","updatedAt","serverTimestamp","merge","reservation","releaseCrmEmailSend","error","console"],"mappings":"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"}

package/src/lib/server/csp-aggregate.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { CspViolation } from '@aglyn/aglyn/app-utils/csp-report';
+/** Top-level collection of counter documents. Server-only; no rules match. */
+export declare const CSP_AGGREGATE_COLLECTION = "cspViolationDaily";
+/**
+ * Long enough that "a week of traffic" (AGL-1702 condition 1, AGL-1726
+ * condition 3) is readable with room to be read late, short enough that the
+ * collection stays a working set rather than an archive.
+ */
+export declare const CSP_AGGREGATE_RETENTION_DAYS = 60;
+/**
+ * Distinct blocked origins that may mint documents per (day x app x
+ * directive), per instance. A legitimate policy violates against a handful of
+ * hosts; thirty is generous headroom for a real regression while keeping a
+ * flood of attacker-invented origins from minting unbounded documents.
+ */
+export declare const MAX_DISTINCT_ORIGINS_PER_DAY = 30;
+/** Test seam: module-scope state would otherwise leak across cases. */
+export declare function resetCspAggregateStateForTests(): void;
+/**
+ * `blocked-uri` reduced to the coarsest thing worth counting: the HOST for a
+ * URL, the bare keyword (`inline`, `eval`, `data`, ...) otherwise. Paths are
+ * deliberately dropped — twelve chunk URLs off one CDN are one origin-level
+ * fact (the AGL-1779 shape), and a path would both explode the key space and
+ * hand the id to whoever controls the URL.
+ */
+export declare function cspBlockedOrigin(blockedUri: string): string;
+/** UTC day bucket, `YYYY-MM-DD`. */
+export declare function cspAggregateDay(nowMs: number): string;
+export interface RecordCspViolationsOptions {
+    /** Which collector this came through — part of the counter key. */
+    app: 'console' | 'tenant';
+    /**
+     * The reporting site (tenant only), REQUEST-derived and already clamped by
+     * the caller. Stored as a sample field, never in the id: distinct sites
+     * must not multiply the key space.
+     */
+    site?: string;
+    now?: number;
+    /** Injectable for tests; defaults to the Admin SDK's Firestore. */
+    firestore?: any;
+}
+/**
+ * Compound `violations` into the daily counters. Never throws; returns how
+ * many documents were written (0 on any failure, budget exhaustion included).
+ */
+export declare function recordCspViolations(violations: readonly CspViolation[], options: RecordCspViolationsOptions): Promise<number>;