@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/billing/ai-overage-gate.js

@@ -0,0 +1,177 @@
+/**
+ * @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 OVERAGE GUARDS AT THE GATE (AGL-3011).
+ *
+ * Four reasons a workspace past its included band is refused, decided from
+ * the month's own figures and the workspace's standing, and nothing else.
+ * Pure: the reservation transaction calls this with what it has already
+ * read, so the guard costs one document read and no round trip.
+ *
+ * ## The one that matters
+ *
+ * `settling` is why the bound is a bound. The other three describe a
+ * workspace whose payment standing is known to be bad; `settling` describes
+ * one whose charges simply have not landed — because a background task was
+ * killed, because Stripe was down, because the charge path has a bug, or
+ * because it was never switched on. In every one of those cases accrued
+ * overage stops at the unpaid limit, having charged nothing. **The bound
+ * holds even if a charge never runs**, and that is the whole design.
+ *
+ * ## Every refusal is `refusedBy: 'cap'`
+ *
+ * These join the workspace's own overage ceiling (AGL-2898) rather than
+ * inventing a sixth refusal class, because they are the same kind of fact: a
+ * dollar limit on credits sold past the band. `capReason` says whose limit
+ * and which one, which is what decides the status and the sentence. Like
+ * every other refusal, they move no counter.
+ */ import { AI_OVERAGE_THRESHOLD_USD, AI_OVERAGE_UNPAID_LIMIT_USD, aiOverageCardOnFile, aiOverageStandingCeilingUsd } from "./ai-overage-standing.js";
+function money(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? number : 0;
+}
+/**
+ * Which guard, if any, refuses this request.
+ *
+ * Order is deliberate and is the order a person can act on: a missing card
+ * is one action, a failed charge is another, and both of those are things
+ * the workspace can fix right now. A ceiling reached and a balance settling
+ * are waits, so they come last. Two guards holding at once is ordinary — a
+ * paused workspace is usually also at its unpaid limit — and naming the
+ * actionable one is worth more than naming the first one numerically true.
+ *
+ * `>=` throughout, matching `assistOverageCapReached`: a limit is met when
+ * it is met, not once it is passed.
+ *
+ * The card guard ABSTAINS when nobody has observed the workspace's payment
+ * method (see `AiOverageStanding.paymentMethodType`). That is a deliberate
+ * hole in the card rule and not in the bound: `settling` below does not read
+ * the card at all, so an unobserved workspace is still stopped at the unpaid
+ * limit. Closing the hole is a backfill, not a code change.
+ */ export function aiOverageRefusal(input) {
+    const overageUsd = money(input.overageUsd);
+    const paidUsd = money(input.paidUsd);
+    const unpaidUsd = Math.max(0, overageUsd - paidUsd);
+    const ceilingUsd = aiOverageStandingCeilingUsd(input.standing, input.now);
+    if (aiOverageCardOnFile(input.standing) === false) {
+        return {
+            capReason: 'no-card',
+            limitUsd: ceilingUsd,
+            unpaidUsd
+        };
+    }
+    if (input.standing.pause) {
+        return {
+            capReason: 'paused',
+            limitUsd: ceilingUsd,
+            unpaidUsd
+        };
+    }
+    if (overageUsd >= ceilingUsd) {
+        return {
+            capReason: 'limit',
+            limitUsd: ceilingUsd,
+            unpaidUsd
+        };
+    }
+    if (unpaidUsd >= AI_OVERAGE_UNPAID_LIMIT_USD) {
+        return {
+            capReason: 'settling',
+            limitUsd: AI_OVERAGE_UNPAID_LIMIT_USD,
+            unpaidUsd
+        };
+    }
+    return null;
+}
+/** `$25.00`, the one place a dollar figure in these sentences is formatted. */ function usd(value) {
+    return `$${value.toFixed(2)}`;
+}
+/**
+ * The sentence a workspace is told, by reason.
+ *
+ * In the plugin, beside the guard that produced it, so the figure quoted is
+ * the figure that refused. Every one of them says that INCLUDED CREDITS KEEP
+ * WORKING, because that is the fact a customer most needs and least expects:
+ * these guards stop what is sold past the band, never the band itself.
+ *
+ * `customer` is not answered here — the workspace's own ceiling keeps the
+ * sentence `assistOverageCapRefusalText` already gives it, which names the
+ * control by the label the console shows.
+ */ export function aiOverageRefusalText(refusal) {
+    switch(refusal.capReason){
+        case 'no-card':
+            return 'AI past your included credits needs a card on file. Add one under ' + 'Billing to keep going — your included credits still work.';
+        case 'paused':
+            return 'AI past your included credits is paused while a payment is ' + 'outstanding. Pay the open invoice or update your card under ' + 'Billing — your included credits still work.';
+        case 'limit':
+            return `This workspace reached this month's AI overage limit of ` + `${usd(refusal.limitUsd)}. The limit rises after each month an ` + 'invoice is paid; contact support to raise it sooner — your ' + 'included credits still work.';
+        case 'settling':
+            return `AI past your included credits is waiting on ` + `${usd(refusal.unpaidUsd)} of charges to settle. It resumes as soon ` + 'as they do — your included credits still work.';
+        default:
+            return null;
+    }
+}
+/**
+ * The HTTP status each reason answers with.
+ *
+ * 402 where the workspace can settle it — a card to add, an invoice to pay.
+ * 429 where it can only wait, which is the status the message cap and the
+ * spend ceiling already use for exactly that meaning. The two must not be
+ * swapped: a client retrying a 429 is right to, and retrying a 402 is not.
+ */ export function aiOverageRefusalStatus(capReason) {
+    return capReason === 'no-card' || capReason === 'paused' || capReason === 'customer' ? 402 : 429;
+}
+/**
+ * What the customer's overage card says about when the next charge lands.
+ *
+ * Here rather than in the component because it is the same arithmetic the
+ * charge trigger makes, and a card that named a different figure from the
+ * one that actually charges would be worse than a card that named none.
+ */ export function aiOverageNextChargeUsd(overageUsd, invoicedUsd) {
+    const remaining = money(overageUsd) - money(invoicedUsd);
+    return Math.max(0, AI_OVERAGE_THRESHOLD_USD - remaining);
+}
+/**
+ * The sentence and status for a reservation that AGLYN'S guards refused, or
+ * `null` when they did not.
+ *
+ * ONE function for all four doors — the chat door, the besigner copy
+ * assistant, the shared gate ladder and the generation jobs — because a
+ * refusal whose words differ by door is a refusal a customer cannot search
+ * for, and because the status and the sentence must agree about whether the
+ * workspace can do anything about it.
+ *
+ * `null` for the workspace's OWN ceiling and for every other refusal, so a
+ * door falls through to `assistOwnControlRefusalText` and the sentences it
+ * has always given.
+ */ export function aiOverageReservationRefusal(reservation) {
+    var _reservation_capReason;
+    if (reservation.refusedBy !== 'cap') return null;
+    const capReason = (_reservation_capReason = reservation.capReason) != null ? _reservation_capReason : null;
+    if (!capReason || capReason === 'customer') return null;
+    const text = aiOverageRefusalText({
+        capReason,
+        limitUsd: money(reservation.overageLimitUsd),
+        unpaidUsd: money(reservation.overageUnpaidUsd)
+    });
+    if (!text) return null;
+    return {
+        text,
+        status: aiOverageRefusalStatus(capReason)
+    };
+}
+
+//# sourceMappingURL=ai-overage-gate.js.map

package/src/lib/billing/ai-overage-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-gate.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * THE OVERAGE GUARDS AT THE GATE (AGL-3011).\n *\n * Four reasons a workspace past its included band is refused, decided from\n * the month's own figures and the workspace's standing, and nothing else.\n * Pure: the reservation transaction calls this with what it has already\n * read, so the guard costs one document read and no round trip.\n *\n * ## The one that matters\n *\n * `settling` is why the bound is a bound. The other three describe a\n * workspace whose payment standing is known to be bad; `settling` describes\n * one whose charges simply have not landed — because a background task was\n * killed, because Stripe was down, because the charge path has a bug, or\n * because it was never switched on. In every one of those cases accrued\n * overage stops at the unpaid limit, having charged nothing. **The bound\n * holds even if a charge never runs**, and that is the whole design.\n *\n * ## Every refusal is `refusedBy: 'cap'`\n *\n * These join the workspace's own overage ceiling (AGL-2898) rather than\n * inventing a sixth refusal class, because they are the same kind of fact: a\n * dollar limit on credits sold past the band. `capReason` says whose limit\n * and which one, which is what decides the status and the sentence. Like\n * every other refusal, they move no counter.\n */\n\nimport {\n  AI_OVERAGE_THRESHOLD_USD,\n  AI_OVERAGE_UNPAID_LIMIT_USD,\n  aiOverageCardOnFile,\n  aiOverageStandingCeilingUsd,\n  type AiOverageStanding,\n} from './ai-overage-standing'\n\n/**\n * Which limit refused.\n *\n * - `no-card`    the workspace has no card as its default payment method.\n * - `paused`     accrual is stopped — a failed charge, a past-due invoice,\n *                a dispute, or staff.\n * - `limit`      this month's overage reached Aglyn's ceiling.\n * - `settling`   accrued-but-unpaid overage reached the unpaid limit.\n * - `customer`   the workspace's own ceiling (AGL-2898), which refuses\n *                before any of the above and keeps its existing sentence.\n */\nexport type AiOverageCapReason =\n  | 'no-card'\n  | 'paused'\n  | 'limit'\n  | 'settling'\n  | 'customer'\n\n/** What the gate hands the guards. All figures are retail dollars. */\nexport interface AiOverageGateInput {\n  /** This month's overage, priced as the invoice prices it. */\n  overageUsd: number\n  /** What of it has been paid — `overagePaidUsd` on the month's rollup. */\n  paidUsd: number\n  standing: AiOverageStanding\n  now: Date\n}\n\n/** The refusal, with the figure its sentence must quote. */\nexport interface AiOverageRefusal {\n  capReason: AiOverageCapReason\n  /** The ceiling in force, for `limit`; the unpaid limit for `settling`. */\n  limitUsd: number\n  /** What is accrued and unpaid, for the pause and settling sentences. */\n  unpaidUsd: number\n}\n\nfunction money(value: unknown): number {\n  const number = Number(value)\n  return Number.isFinite(number) && number > 0 ? number : 0\n}\n\n/**\n * Which guard, if any, refuses this request.\n *\n * Order is deliberate and is the order a person can act on: a missing card\n * is one action, a failed charge is another, and both of those are things\n * the workspace can fix right now. A ceiling reached and a balance settling\n * are waits, so they come last. Two guards holding at once is ordinary — a\n * paused workspace is usually also at its unpaid limit — and naming the\n * actionable one is worth more than naming the first one numerically true.\n *\n * `>=` throughout, matching `assistOverageCapReached`: a limit is met when\n * it is met, not once it is passed.\n *\n * The card guard ABSTAINS when nobody has observed the workspace's payment\n * method (see `AiOverageStanding.paymentMethodType`). That is a deliberate\n * hole in the card rule and not in the bound: `settling` below does not read\n * the card at all, so an unobserved workspace is still stopped at the unpaid\n * limit. Closing the hole is a backfill, not a code change.\n */\nexport function aiOverageRefusal(\n  input: AiOverageGateInput,\n): AiOverageRefusal | null {\n  const overageUsd = money(input.overageUsd)\n  const paidUsd = money(input.paidUsd)\n  const unpaidUsd = Math.max(0, overageUsd - paidUsd)\n  const ceilingUsd = aiOverageStandingCeilingUsd(input.standing, input.now)\n\n  if (aiOverageCardOnFile(input.standing) === false) {\n    return { capReason: 'no-card', limitUsd: ceilingUsd, unpaidUsd }\n  }\n  if (input.standing.pause) {\n    return { capReason: 'paused', limitUsd: ceilingUsd, unpaidUsd }\n  }\n  if (overageUsd >= ceilingUsd) {\n    return { capReason: 'limit', limitUsd: ceilingUsd, unpaidUsd }\n  }\n  if (unpaidUsd >= AI_OVERAGE_UNPAID_LIMIT_USD) {\n    return {\n      capReason: 'settling',\n      limitUsd: AI_OVERAGE_UNPAID_LIMIT_USD,\n      unpaidUsd,\n    }\n  }\n  return null\n}\n\n/** `$25.00`, the one place a dollar figure in these sentences is formatted. */\nfunction usd(value: number): string {\n  return `$${value.toFixed(2)}`\n}\n\n/**\n * The sentence a workspace is told, by reason.\n *\n * In the plugin, beside the guard that produced it, so the figure quoted is\n * the figure that refused. Every one of them says that INCLUDED CREDITS KEEP\n * WORKING, because that is the fact a customer most needs and least expects:\n * these guards stop what is sold past the band, never the band itself.\n *\n * `customer` is not answered here — the workspace's own ceiling keeps the\n * sentence `assistOverageCapRefusalText` already gives it, which names the\n * control by the label the console shows.\n */\nexport function aiOverageRefusalText(refusal: AiOverageRefusal): string | null {\n  switch (refusal.capReason) {\n    case 'no-card':\n      return (\n        'AI past your included credits needs a card on file. Add one under ' +\n        'Billing to keep going — your included credits still work.'\n      )\n    case 'paused':\n      return (\n        'AI past your included credits is paused while a payment is ' +\n        'outstanding. Pay the open invoice or update your card under ' +\n        'Billing — your included credits still work.'\n      )\n    case 'limit':\n      return (\n        `This workspace reached this month's AI overage limit of ` +\n        `${usd(refusal.limitUsd)}. The limit rises after each month an ` +\n        'invoice is paid; contact support to raise it sooner — your ' +\n        'included credits still work.'\n      )\n    case 'settling':\n      return (\n        `AI past your included credits is waiting on ` +\n        `${usd(refusal.unpaidUsd)} of charges to settle. It resumes as soon ` +\n        'as they do — your included credits still work.'\n      )\n    default:\n      return null\n  }\n}\n\n/**\n * The HTTP status each reason answers with.\n *\n * 402 where the workspace can settle it — a card to add, an invoice to pay.\n * 429 where it can only wait, which is the status the message cap and the\n * spend ceiling already use for exactly that meaning. The two must not be\n * swapped: a client retrying a 429 is right to, and retrying a 402 is not.\n */\nexport function aiOverageRefusalStatus(capReason: AiOverageCapReason): 402 | 429 {\n  return capReason === 'no-card' || capReason === 'paused' || capReason === 'customer'\n    ? 402\n    : 429\n}\n\n/**\n * What the customer's overage card says about when the next charge lands.\n *\n * Here rather than in the component because it is the same arithmetic the\n * charge trigger makes, and a card that named a different figure from the\n * one that actually charges would be worse than a card that named none.\n */\nexport function aiOverageNextChargeUsd(\n  overageUsd: number,\n  invoicedUsd: number,\n): number {\n  const remaining = money(overageUsd) - money(invoicedUsd)\n  return Math.max(0, AI_OVERAGE_THRESHOLD_USD - remaining)\n}\n\n/** The refusal fields a reservation carries, without importing its type. */\nexport interface AiOverageRefusedReservation {\n  refusedBy: string | null\n  capReason?: AiOverageCapReason | null\n  overageLimitUsd?: number | null\n  overageUnpaidUsd?: number | null\n}\n\n/**\n * The sentence and status for a reservation that AGLYN'S guards refused, or\n * `null` when they did not.\n *\n * ONE function for all four doors — the chat door, the besigner copy\n * assistant, the shared gate ladder and the generation jobs — because a\n * refusal whose words differ by door is a refusal a customer cannot search\n * for, and because the status and the sentence must agree about whether the\n * workspace can do anything about it.\n *\n * `null` for the workspace's OWN ceiling and for every other refusal, so a\n * door falls through to `assistOwnControlRefusalText` and the sentences it\n * has always given.\n */\nexport function aiOverageReservationRefusal(\n  reservation: AiOverageRefusedReservation,\n): { text: string; status: 402 | 429 } | null {\n  if (reservation.refusedBy !== 'cap') return null\n  const capReason = reservation.capReason ?? null\n  if (!capReason || capReason === 'customer') return null\n  const text = aiOverageRefusalText({\n    capReason,\n    limitUsd: money(reservation.overageLimitUsd),\n    unpaidUsd: money(reservation.overageUnpaidUsd),\n  })\n  if (!text) return null\n  return { text, status: aiOverageRefusalStatus(capReason) }\n}\n"],"names":["AI_OVERAGE_THRESHOLD_USD","AI_OVERAGE_UNPAID_LIMIT_USD","aiOverageCardOnFile","aiOverageStandingCeilingUsd","money","value","number","Number","isFinite","aiOverageRefusal","input","overageUsd","paidUsd","unpaidUsd","Math","max","ceilingUsd","standing","now","capReason","limitUsd","pause","usd","toFixed","aiOverageRefusalText","refusal","aiOverageRefusalStatus","aiOverageNextChargeUsd","invoicedUsd","remaining","aiOverageReservationRefusal","reservation","refusedBy","text","overageLimitUsd","overageUnpaidUsd","status"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GAED,SACEA,wBAAwB,EACxBC,2BAA2B,EAC3BC,mBAAmB,EACnBC,2BAA2B,QAEtB,2BAAuB;AAuC9B,SAASC,MAAMC,KAAc;IAC3B,MAAMC,SAASC,OAAOF;IACtB,OAAOE,OAAOC,QAAQ,CAACF,WAAWA,SAAS,IAAIA,SAAS;AAC1D;AAEA;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,SAASG,iBACdC,KAAyB;IAEzB,MAAMC,aAAaP,MAAMM,MAAMC,UAAU;IACzC,MAAMC,UAAUR,MAAMM,MAAME,OAAO;IACnC,MAAMC,YAAYC,KAAKC,GAAG,CAAC,GAAGJ,aAAaC;IAC3C,MAAMI,aAAab,4BAA4BO,MAAMO,QAAQ,EAAEP,MAAMQ,GAAG;IAExE,IAAIhB,oBAAoBQ,MAAMO,QAAQ,MAAM,OAAO;QACjD,OAAO;YAAEE,WAAW;YAAWC,UAAUJ;YAAYH;QAAU;IACjE;IACA,IAAIH,MAAMO,QAAQ,CAACI,KAAK,EAAE;QACxB,OAAO;YAAEF,WAAW;YAAUC,UAAUJ;YAAYH;QAAU;IAChE;IACA,IAAIF,cAAcK,YAAY;QAC5B,OAAO;YAAEG,WAAW;YAASC,UAAUJ;YAAYH;QAAU;IAC/D;IACA,IAAIA,aAAaZ,6BAA6B;QAC5C,OAAO;YACLkB,WAAW;YACXC,UAAUnB;YACVY;QACF;IACF;IACA,OAAO;AACT;AAEA,6EAA6E,GAC7E,SAASS,IAAIjB,KAAa;IACxB,OAAO,CAAC,CAAC,EAAEA,MAAMkB,OAAO,CAAC,IAAI;AAC/B;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,qBAAqBC,OAAyB;IAC5D,OAAQA,QAAQN,SAAS;QACvB,KAAK;YACH,OACE,uEACA;QAEJ,KAAK;YACH,OACE,gEACA,iEACA;QAEJ,KAAK;YACH,OACE,CAAC,wDAAwD,CAAC,GAC1D,GAAGG,IAAIG,QAAQL,QAAQ,EAAE,sCAAsC,CAAC,GAChE,gEACA;QAEJ,KAAK;YACH,OACE,CAAC,4CAA4C,CAAC,GAC9C,GAAGE,IAAIG,QAAQZ,SAAS,EAAE,0CAA0C,CAAC,GACrE;QAEJ;YACE,OAAO;IACX;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASa,uBAAuBP,SAA6B;IAClE,OAAOA,cAAc,aAAaA,cAAc,YAAYA,cAAc,aACtE,MACA;AACN;AAEA;;;;;;CAMC,GACD,OAAO,SAASQ,uBACdhB,UAAkB,EAClBiB,WAAmB;IAEnB,MAAMC,YAAYzB,MAAMO,cAAcP,MAAMwB;IAC5C,OAAOd,KAAKC,GAAG,CAAC,GAAGf,2BAA2B6B;AAChD;AAUA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,4BACdC,WAAwC;QAGtBA;IADlB,IAAIA,YAAYC,SAAS,KAAK,OAAO,OAAO;IAC5C,MAAMb,aAAYY,yBAAAA,YAAYZ,SAAS,YAArBY,yBAAyB;IAC3C,IAAI,CAACZ,aAAaA,cAAc,YAAY,OAAO;IACnD,MAAMc,OAAOT,qBAAqB;QAChCL;QACAC,UAAUhB,MAAM2B,YAAYG,eAAe;QAC3CrB,WAAWT,MAAM2B,YAAYI,gBAAgB;IAC/C;IACA,IAAI,CAACF,MAAM,OAAO;IAClB,OAAO;QAAEA;QAAMG,QAAQV,uBAAuBP;IAAW;AAC3D"}

package/src/lib/billing/ai-overage-ledger.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @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 AiOverageOrg } from './ai-overage-standing';
+/** The subcollection and document the standing lives at. */
+export declare const AI_BILLING_SUBCOLLECTION = "aiBilling";
+export declare const AI_BILLING_STANDING_DOC = "standing";
+/** The subcollection one row per charge lives in. */
+export declare const AI_OVERAGE_CHARGES_SUBCOLLECTION = "aiOverageCharges";
+/** Which sweep asked for the charge. */
+export type AiOverageChargeKind = 'threshold' | 'closeout';
+/** Where a charge is in its life. */
+export type AiOverageChargeStatus = 'claimed' | 'open' | 'paid' | 'failed' | 'void';
+/** A claim taken, ready to be charged. */
+export interface AiOverageClaim {
+    chargeId: string;
+    orgId: string;
+    month: string;
+    seq: number;
+    kind: AiOverageChargeKind;
+    /** Floored to the cent — Stripe bills whole cents. */
+    amountUsd: number;
+    /** The credits and rate the amount came from, for the audit row. */
+    credits: number;
+    rateUsdPer1k: number | null;
+}
+/** Why no claim was taken. Each one is a different thing to do about it. */
+export type AiOverageClaimRefusal = 'below-threshold' | 'charge-already-open' | 'no-card' | 'paused' | 'not-sold';
+export type AiOverageClaimResult = {
+    claimed: AiOverageClaim;
+    refused: null;
+} | {
+    claimed: null;
+    refused: AiOverageClaimRefusal;
+};
+/** Down to the cent. Never up: a rounded-up cent is a cent never accrued. */
+export declare function floorToCent(usd: number): number;
+/**
+ * `{month}-{seq}` — readable, sortable, and unique per workspace-month.
+ *
+ * The id is also the Stripe idempotency key's payload and the metadata the
+ * reconcile search matches on, so it must survive a URL and a Stripe search
+ * query unescaped: digits, a hyphen, nothing else.
+ */
+export declare function aiOverageChargeId(month: string, seq: number): string;
+/**
+ * Takes a claim on the workspace's unbilled overage, or explains why not.
+ *
+ * The four conditions are the design's, in one transaction with the reads
+ * they are decided from:
+ *
+ * - enough unbilled overage (the threshold, or the minimum for a close-out);
+ * - no charge already open — one at a time, so a failure has one owner;
+ * - a card on file, since the bound assumes a payment method that settles
+ *   now rather than in days;
+ * - not paused.
+ *
+ * The card condition abstains when the workspace's payment method has never
+ * been observed, for the reason `AiOverageStanding.paymentMethodType` gives.
+ * A charge attempted against a customer with no default simply fails, and
+ * the failure pauses accrual like any other — the guard is an optimization
+ * here, not the safety property.
+ */
+export declare function claimAiOverageCharge(firestore: FirebaseFirestore.Firestore, request: {
+    orgId: string;
+    org: AiOverageOrg;
+    month: string;
+    kind: AiOverageChargeKind;
+    now?: Date;
+}): Promise<AiOverageClaimResult>;
+/** What Stripe said, as the ledger records it. */
+export interface AiOverageSettlement {
+    chargeId: string;
+    month: string;
+    /** `null` only when no invoice was ever created. */
+    invoiceId: string | null;
+    status: AiOverageChargeStatus;
+    /**
+     * What Stripe actually collected, in dollars (AGL-3023).
+     *
+     * The month's paid total moves by THIS and never by the claim. The two are
+     * normally equal, and the case where they are not is the one that matters:
+     * an invoice that finalized at zero or collected less than it billed would
+     * otherwise clear a balance nobody paid, and the gate's unpaid bound would
+     * be satisfied by our own bookkeeping instead of by money.
+     *
+     * Omitted on a settlement that is not a payment, where it is not read.
+     */
+    paidUsd?: number;
+}
+/**
+ * Records what became of a claimed charge.
+ *
+ * `paid` adds the amount to the month's `overagePaidUsd`, which is what the
+ * gate's unpaid bound subtracts — so paying is what lets a workspace keep
+ * going, and nothing else does.
+ *
+ * An invoice that exists but is not paid KEEPS its claim on
+ * `overageInvoicedUsd`: it is a real bill, Stripe's retries may still settle
+ * it, and re-billing the same dollars on a second invoice would charge the
+ * customer twice for one month's usage. Only a claim that never became an
+ * invoice at all releases what it claimed, so those dollars can be charged
+ * by a later attempt.
+ *
+ * The open-charge slot is always cleared. Leaving it set on a failure would
+ * block the close-out and every later charge behind an invoice that is
+ * never going to move on its own.
+ */
+export declare function settleAiOverageCharge(firestore: FirebaseFirestore.Firestore, orgId: string, settlement: AiOverageSettlement): Promise<void>;
+/** The month's charge counters, as the customer card and staff card read them. */
+export interface AiOverageMonthLedger {
+    invoicedUsd: number;
+    paidUsd: number;
+    charges: number;
+    open: {
+        chargeId: string;
+        invoiceId: string | null;
+        amountUsd: number;
+    } | null;
+}
+/** Reads the four fields off a month's rollup, defensively. */
+export declare function readAiOverageMonthLedger(data: Record<string, unknown> | null | undefined): AiOverageMonthLedger;

package/src/lib/billing/ai-overage-ledger.js

@@ -0,0 +1,278 @@
+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.
+ */ /**
+ * THE OVERAGE CHARGE LEDGER (AGL-3011).
+ *
+ * Every dollar of AI overage a workspace is charged mid-period passes
+ * through here twice: once as a CLAIM, taken in a transaction before any
+ * money is asked for, and once as a SETTLEMENT, recorded after Stripe
+ * answers. Nothing in this module talks to Stripe.
+ *
+ * ## Why claim first
+ *
+ * The figure that decides a charge — the month's overage — is a counter many
+ * requests move. Two requests crossing the threshold a millisecond apart
+ * both read "$25 unbilled" and would both charge for it. The claim closes
+ * that: inside one transaction it moves `overageInvoicedUsd` forward by the
+ * amount it is about to charge and records an open charge, so the second
+ * request reads an already-claimed balance and stands down. The invoice is
+ * created afterwards, outside the transaction, because a Stripe call inside
+ * a Firestore transaction would be retried by the transaction.
+ *
+ * ## What a lost process costs
+ *
+ * A claim that never became an invoice leaves `overageInvoicedUsd` ahead of
+ * what was billed, which UNDER-charges rather than over-charges, and leaves
+ * an open charge that blocks the next one. Both are repaired by the
+ * reconcile sweep, which asks Stripe whether the claim ever became an
+ * invoice and either records it or releases the claim. Under-charging while
+ * confused is the direction this must err in.
+ *
+ * ## The documents
+ *
+ * `orgs/{orgId}/assistUsage/{YYYY-MM}` — the month's rollup, which the
+ * reservation already reads, gains four fields so the gate costs no extra
+ * read: `overageInvoicedUsd`, `overagePaidUsd`, `overageCharges` and
+ * `overageInvoiceOpen`.
+ *
+ * `orgs/{orgId}/aiOverageCharges/{chargeId}` — one row per charge, the
+ * audit trail staff read and the reconcile sweep walks.
+ *
+ * Both are server-written: the rules allow the same readers as
+ * `aiAllotments` and no writer at all.
+ */ import { FieldValue } from "firebase-admin/firestore";
+import { assistMonthOverage } from "@aglyn/aglyn/app-utils/assist-credits";
+import { AI_OVERAGE_MIN_CHARGE_USD, AI_OVERAGE_THRESHOLD_USD, aiOverageCardOnFile, readAiOverageStanding } from "./ai-overage-standing.js";
+/** The subcollection and document the standing lives at. */ export const AI_BILLING_SUBCOLLECTION = 'aiBilling';
+export const AI_BILLING_STANDING_DOC = 'standing';
+/** The subcollection one row per charge lives in. */ export const AI_OVERAGE_CHARGES_SUBCOLLECTION = 'aiOverageCharges';
+function money(value) {
+    const number = Number(value);
+    return Number.isFinite(number) && number > 0 ? number : 0;
+}
+/** Down to the cent. Never up: a rounded-up cent is a cent never accrued. */ export function floorToCent(usd) {
+    return Math.floor(money(usd) * 100) / 100;
+}
+/**
+ * `{month}-{seq}` — readable, sortable, and unique per workspace-month.
+ *
+ * The id is also the Stripe idempotency key's payload and the metadata the
+ * reconcile search matches on, so it must survive a URL and a Stripe search
+ * query unescaped: digits, a hyphen, nothing else.
+ */ export function aiOverageChargeId(month, seq) {
+    return `${month}-${String(Math.max(1, Math.floor(seq))).padStart(3, '0')}`;
+}
+/**
+ * Takes a claim on the workspace's unbilled overage, or explains why not.
+ *
+ * The four conditions are the design's, in one transaction with the reads
+ * they are decided from:
+ *
+ * - enough unbilled overage (the threshold, or the minimum for a close-out);
+ * - no charge already open — one at a time, so a failure has one owner;
+ * - a card on file, since the bound assumes a payment method that settles
+ *   now rather than in days;
+ * - not paused.
+ *
+ * The card condition abstains when the workspace's payment method has never
+ * been observed, for the reason `AiOverageStanding.paymentMethodType` gives.
+ * A charge attempted against a customer with no default simply fails, and
+ * the failure pauses accrual like any other — the guard is an optimization
+ * here, not the safety property.
+ */ export async function claimAiOverageCharge(firestore, request) {
+    var _request_now;
+    const now = (_request_now = request.now) != null ? _request_now : new Date();
+    const orgRef = firestore.collection('orgs').doc(request.orgId);
+    const usageRef = orgRef.collection('assistUsage').doc(request.month);
+    const standingRef = orgRef.collection(AI_BILLING_SUBCOLLECTION).doc(AI_BILLING_STANDING_DOC);
+    // A close-out settles a month that is over: there is nothing left to
+    // accrue, so anything Stripe will accept is worth billing. A threshold
+    // charge waits for the threshold, which is what keeps the invoice count
+    // and its fees down.
+    const floorUsd = request.kind === 'closeout' ? AI_OVERAGE_MIN_CHARGE_USD : AI_OVERAGE_THRESHOLD_USD;
+    return firestore.runTransaction(async (tx)=>{
+        var _standingSnapshot_data;
+        const [usageSnapshot, standingSnapshot] = await Promise.all([
+            tx.get(usageRef),
+            tx.get(standingRef)
+        ]);
+        const standing = readAiOverageStanding(standingSnapshot.exists ? (_standingSnapshot_data = standingSnapshot.data()) != null ? _standingSnapshot_data : null : null);
+        if (aiOverageCardOnFile(standing) === false) {
+            return {
+                claimed: null,
+                refused: 'no-card'
+            };
+        }
+        if (standing.pause) return {
+            claimed: null,
+            refused: 'paused'
+        };
+        if (usageSnapshot.get('overageInvoiceOpen')) {
+            return {
+                claimed: null,
+                refused: 'charge-already-open'
+            };
+        }
+        const priced = assistMonthOverage(request.org, money(usageSnapshot.get('estCostUsd')));
+        // A plan that sells nothing past its band prices its overage to zero, so
+        // this is structural rather than a check that could be forgotten — but
+        // it is named, because "we billed nothing" and "there is nothing to
+        // bill" are different answers to a staff question.
+        if (priced.overageRateUsd === null) {
+            return {
+                claimed: null,
+                refused: 'not-sold'
+            };
+        }
+        const invoicedUsd = money(usageSnapshot.get('overageInvoicedUsd'));
+        const unbilledUsd = floorToCent(priced.overageMonthlyUsd - invoicedUsd);
+        if (!(unbilledUsd >= floorUsd)) {
+            return {
+                claimed: null,
+                refused: 'below-threshold'
+            };
+        }
+        const seq = Math.max(0, Math.floor(money(usageSnapshot.get('overageCharges')))) + 1;
+        const chargeId = aiOverageChargeId(request.month, seq);
+        const claim = {
+            chargeId,
+            orgId: request.orgId,
+            month: request.month,
+            seq,
+            kind: request.kind,
+            amountUsd: unbilledUsd,
+            credits: priced.overageCredits,
+            rateUsdPer1k: priced.overageRateUsd
+        };
+        tx.set(usageRef, {
+            month: request.month,
+            overageInvoicedUsd: FieldValue.increment(unbilledUsd),
+            overageCharges: FieldValue.increment(1),
+            overageInvoiceOpen: {
+                chargeId,
+                invoiceId: null,
+                amountUsd: unbilledUsd,
+                since: now.toISOString()
+            },
+            updatedAt: FieldValue.serverTimestamp()
+        }, {
+            merge: true
+        });
+        tx.set(orgRef.collection(AI_OVERAGE_CHARGES_SUBCOLLECTION).doc(chargeId), {
+            month: request.month,
+            seq,
+            kind: request.kind,
+            amountUsd: unbilledUsd,
+            credits: priced.overageCredits,
+            rateUsdPer1k: priced.overageRateUsd,
+            invoiceId: null,
+            status: 'claimed',
+            createdAt: FieldValue.serverTimestamp(),
+            paidAt: null,
+            failedAt: null
+        }, {
+            merge: true
+        });
+        return {
+            claimed: claim,
+            refused: null
+        };
+    });
+}
+/**
+ * Records what became of a claimed charge.
+ *
+ * `paid` adds the amount to the month's `overagePaidUsd`, which is what the
+ * gate's unpaid bound subtracts — so paying is what lets a workspace keep
+ * going, and nothing else does.
+ *
+ * An invoice that exists but is not paid KEEPS its claim on
+ * `overageInvoicedUsd`: it is a real bill, Stripe's retries may still settle
+ * it, and re-billing the same dollars on a second invoice would charge the
+ * customer twice for one month's usage. Only a claim that never became an
+ * invoice at all releases what it claimed, so those dollars can be charged
+ * by a later attempt.
+ *
+ * The open-charge slot is always cleared. Leaving it set on a failure would
+ * block the close-out and every later charge behind an invoice that is
+ * never going to move on its own.
+ */ export async function settleAiOverageCharge(firestore, orgId, settlement) {
+    const orgRef = firestore.collection('orgs').doc(orgId);
+    const usageRef = orgRef.collection('assistUsage').doc(settlement.month);
+    const chargeRef = orgRef.collection(AI_OVERAGE_CHARGES_SUBCOLLECTION).doc(settlement.chargeId);
+    await firestore.runTransaction(async (tx)=>{
+        var _ref;
+        const [usageSnapshot, chargeSnapshot] = await Promise.all([
+            tx.get(usageRef),
+            tx.get(chargeRef)
+        ]);
+        const amountUsd = money(chargeSnapshot.get('amountUsd'));
+        // What the month's paid total moves by: what Stripe took. A settlement
+        // that claims to be a payment and names no collected figure moves
+        // nothing — silence is not evidence of money (AGL-3023).
+        const paidUsd = money(settlement.paidUsd);
+        const open = usageSnapshot.get('overageInvoiceOpen');
+        const ownsTheSlot = String((_ref = open == null ? void 0 : open.chargeId) != null ? _ref : '') === settlement.chargeId;
+        // Already settled, or settled by another path (the webhook and the
+        // synchronous answer both arrive). Recording the status again is
+        // harmless; moving the money counters again is not.
+        const alreadyPaid = chargeSnapshot.get('status') === 'paid';
+        const releases = settlement.status === 'failed' && !settlement.invoiceId;
+        tx.set(chargeRef, _extends({
+            invoiceId: settlement.invoiceId,
+            status: settlement.status
+        }, settlement.status === 'paid' ? {
+            paidUsd
+        } : {}, settlement.status === 'paid' ? {
+            paidAt: FieldValue.serverTimestamp()
+        } : {}, settlement.status === 'failed' ? {
+            failedAt: FieldValue.serverTimestamp()
+        } : {}), {
+            merge: true
+        });
+        tx.set(usageRef, _extends({
+            month: settlement.month
+        }, settlement.status === 'paid' && !alreadyPaid && paidUsd > 0 ? {
+            overagePaidUsd: FieldValue.increment(paidUsd)
+        } : {}, releases ? {
+            overageInvoicedUsd: FieldValue.increment(-amountUsd),
+            overageCharges: FieldValue.increment(-1)
+        } : {}, ownsTheSlot ? {
+            overageInvoiceOpen: null
+        } : {}, {
+            updatedAt: FieldValue.serverTimestamp()
+        }), {
+            merge: true
+        });
+    });
+}
+/** Reads the four fields off a month's rollup, defensively. */ export function readAiOverageMonthLedger(data) {
+    const open = data == null ? void 0 : data['overageInvoiceOpen'];
+    const chargeId = typeof (open == null ? void 0 : open['chargeId']) === 'string' ? open['chargeId'] : '';
+    return {
+        invoicedUsd: money(data == null ? void 0 : data['overageInvoicedUsd']),
+        paidUsd: money(data == null ? void 0 : data['overagePaidUsd']),
+        charges: Math.max(0, Math.floor(money(data == null ? void 0 : data['overageCharges']))),
+        open: chargeId ? {
+            chargeId,
+            invoiceId: typeof (open == null ? void 0 : open['invoiceId']) === 'string' ? open['invoiceId'] : null,
+            amountUsd: money(open == null ? void 0 : open['amountUsd'])
+        } : null
+    };
+}
+
+//# sourceMappingURL=ai-overage-ledger.js.map