@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,114 @@
+/**
+ * @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 CUTOVER (AGL-3011): one switch, and everything hangs off it.
+ *
+ * `AI_OVERAGE_INVOICED_FROM` names the first month (`YYYY-MM`) in which AI
+ * overage is billed by invoice as it accrues. Unset — which is how it ships
+ * — every workspace behaves exactly as it does today: overage accrues, the
+ * monthly sweep prices it into the meter event, and the renewal invoice
+ * bills it. Nothing charges mid-period and nothing new refuses.
+ *
+ * ## Why the GUARDS are behind the same switch as the charging
+ *
+ * The unpaid bound refuses a workspace whose accrued overage has not been
+ * paid for. Before cutover nothing charges, so nothing is ever paid for, so
+ * every workspace past $50 of overage would be refused with no invoice to
+ * pay and no way to clear it. A bound with no way to settle is not a bound,
+ * it is a wall — and a wall nobody agreed to.
+ *
+ * So the guards read this same switch. Turning it on turns on the charging
+ * and the guards together, which is the only combination in which each one
+ * makes sense.
+ *
+ * ## Why it is a month and not a boolean
+ *
+ * The meter and the invoice must never both bill one month's overage. A
+ * month is the unit the meter reports in, so a month is the unit the handover
+ * has to be expressed in: everything before the named month bills through the
+ * meter exactly as it always did, and everything from it bills by invoice.
+ * A boolean flipped mid-month would split one month's overage across both
+ * channels and bill part of it twice.
+ */ import { registerPluginMeteredLine } from "@aglyn/aglyn/plugin-manager/plugin-metered-lines";
+import { AI_PLUGIN_ID } from "../constants.js";
+/**
+ * Core's own name for the AI overage line in the monthly usage sweep. The
+ * sweep asks the registry by this id; the plugin answers.
+ */ export const AI_OVERAGE_METER_LINE_ID = 'assist-overage';
+/** The environment variable that starts mid-period charging. */ export const AI_OVERAGE_INVOICED_FROM_ENV = 'AI_OVERAGE_INVOICED_FROM';
+const MONTH = /^\d{4}-\d{2}$/;
+/**
+ * The configured cutover month, or `null` when there is none.
+ *
+ * Read on every call rather than cached, so setting the variable takes
+ * effect without a restart and a process that started before it was set is
+ * not stuck a month behind.
+ *
+ * An unparseable value is `null`, not an error: a typo must leave the
+ * platform billing through the channel that works, not stop billing.
+ */ export function aiOverageInvoicedFrom() {
+    var _process_env_AI_OVERAGE_INVOICED_FROM_ENV;
+    const raw = String((_process_env_AI_OVERAGE_INVOICED_FROM_ENV = process.env[AI_OVERAGE_INVOICED_FROM_ENV]) != null ? _process_env_AI_OVERAGE_INVOICED_FROM_ENV : '').trim();
+    return MONTH.test(raw) ? raw : null;
+}
+/**
+ * Is AI overage billed by invoice — rather than through the monthly meter —
+ * for this month?
+ *
+ * `YYYY-MM` is zero-padded and fixed width, so it orders identically as a
+ * string and as a date; the format checks are what make that true rather
+ * than lucky.
+ */ export function aiOverageBillsByInvoice(month) {
+    const from = aiOverageInvoicedFrom();
+    if (!from) return false;
+    if (!MONTH.test(month)) return false;
+    return month >= from;
+}
+/**
+ * Are the overage guards live for this month?
+ *
+ * The same answer as `aiOverageBillsByInvoice`, given its own name because
+ * it is asked for a different reason and a reader of the gate should not
+ * have to work out why the gate consults a billing question. If the two ever
+ * need to differ, this is where that would be said — and it would need a
+ * paragraph explaining how a workspace refused for unpaid overage is
+ * supposed to pay it.
+ */ export function aiOverageGuardsApply(month) {
+    return aiOverageBillsByInvoice(month);
+}
+/**
+ * Claims the meter line, so the monthly sweep leaves AI overage out of the
+ * figure it meters from the cutover month on.
+ *
+ * Registered from the plugin's server declarations, at boot, because the
+ * sweep is a core cron that never loads an AI door. Idempotent by the
+ * registry's own rule: the same plugin re-claiming replaces its claim.
+ */ export function registerAiOverageMeteredLine() {
+    registerPluginMeteredLine({
+        lineId: AI_OVERAGE_METER_LINE_ID,
+        pluginId: AI_PLUGIN_ID,
+        billsFrom: aiOverageInvoicedFrom,
+        // Loaded on the first closed month rather than at boot, so the console's
+        // every process does not carry the Stripe path for a sweep that runs
+        // once a day in one of them.
+        closeMonth: async (context)=>{
+            const { closeAiOverageMonth } = await import("./ai-overage-close.js");
+            await closeAiOverageMonth(context);
+        }
+    });
+}
+
+//# sourceMappingURL=ai-overage-cutover.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-cutover.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 CUTOVER (AGL-3011): one switch, and everything hangs off it.\n *\n * `AI_OVERAGE_INVOICED_FROM` names the first month (`YYYY-MM`) in which AI\n * overage is billed by invoice as it accrues. Unset — which is how it ships\n * — every workspace behaves exactly as it does today: overage accrues, the\n * monthly sweep prices it into the meter event, and the renewal invoice\n * bills it. Nothing charges mid-period and nothing new refuses.\n *\n * ## Why the GUARDS are behind the same switch as the charging\n *\n * The unpaid bound refuses a workspace whose accrued overage has not been\n * paid for. Before cutover nothing charges, so nothing is ever paid for, so\n * every workspace past $50 of overage would be refused with no invoice to\n * pay and no way to clear it. A bound with no way to settle is not a bound,\n * it is a wall — and a wall nobody agreed to.\n *\n * So the guards read this same switch. Turning it on turns on the charging\n * and the guards together, which is the only combination in which each one\n * makes sense.\n *\n * ## Why it is a month and not a boolean\n *\n * The meter and the invoice must never both bill one month's overage. A\n * month is the unit the meter reports in, so a month is the unit the handover\n * has to be expressed in: everything before the named month bills through the\n * meter exactly as it always did, and everything from it bills by invoice.\n * A boolean flipped mid-month would split one month's overage across both\n * channels and bill part of it twice.\n */\n\nimport { registerPluginMeteredLine } from '@aglyn/aglyn/plugin-manager/plugin-metered-lines'\nimport { AI_PLUGIN_ID } from '../constants'\n\n/**\n * Core's own name for the AI overage line in the monthly usage sweep. The\n * sweep asks the registry by this id; the plugin answers.\n */\nexport const AI_OVERAGE_METER_LINE_ID = 'assist-overage'\n\n/** The environment variable that starts mid-period charging. */\nexport const AI_OVERAGE_INVOICED_FROM_ENV = 'AI_OVERAGE_INVOICED_FROM'\n\nconst MONTH = /^\\d{4}-\\d{2}$/\n\n/**\n * The configured cutover month, or `null` when there is none.\n *\n * Read on every call rather than cached, so setting the variable takes\n * effect without a restart and a process that started before it was set is\n * not stuck a month behind.\n *\n * An unparseable value is `null`, not an error: a typo must leave the\n * platform billing through the channel that works, not stop billing.\n */\nexport function aiOverageInvoicedFrom(): string | null {\n  const raw = String(process.env[AI_OVERAGE_INVOICED_FROM_ENV] ?? '').trim()\n  return MONTH.test(raw) ? raw : null\n}\n\n/**\n * Is AI overage billed by invoice — rather than through the monthly meter —\n * for this month?\n *\n * `YYYY-MM` is zero-padded and fixed width, so it orders identically as a\n * string and as a date; the format checks are what make that true rather\n * than lucky.\n */\nexport function aiOverageBillsByInvoice(month: string): boolean {\n  const from = aiOverageInvoicedFrom()\n  if (!from) return false\n  if (!MONTH.test(month)) return false\n  return month >= from\n}\n\n/**\n * Are the overage guards live for this month?\n *\n * The same answer as `aiOverageBillsByInvoice`, given its own name because\n * it is asked for a different reason and a reader of the gate should not\n * have to work out why the gate consults a billing question. If the two ever\n * need to differ, this is where that would be said — and it would need a\n * paragraph explaining how a workspace refused for unpaid overage is\n * supposed to pay it.\n */\nexport function aiOverageGuardsApply(month: string): boolean {\n  return aiOverageBillsByInvoice(month)\n}\n\n/**\n * Claims the meter line, so the monthly sweep leaves AI overage out of the\n * figure it meters from the cutover month on.\n *\n * Registered from the plugin's server declarations, at boot, because the\n * sweep is a core cron that never loads an AI door. Idempotent by the\n * registry's own rule: the same plugin re-claiming replaces its claim.\n */\nexport function registerAiOverageMeteredLine(): void {\n  registerPluginMeteredLine({\n    lineId: AI_OVERAGE_METER_LINE_ID,\n    pluginId: AI_PLUGIN_ID,\n    billsFrom: aiOverageInvoicedFrom,\n    // Loaded on the first closed month rather than at boot, so the console's\n    // every process does not carry the Stripe path for a sweep that runs\n    // once a day in one of them.\n    closeMonth: async (context) => {\n      const { closeAiOverageMonth } = await import('./ai-overage-close')\n      await closeAiOverageMonth(context)\n    },\n  })\n}\n"],"names":["registerPluginMeteredLine","AI_PLUGIN_ID","AI_OVERAGE_METER_LINE_ID","AI_OVERAGE_INVOICED_FROM_ENV","MONTH","aiOverageInvoicedFrom","process","raw","String","env","trim","test","aiOverageBillsByInvoice","month","from","aiOverageGuardsApply","registerAiOverageMeteredLine","lineId","pluginId","billsFrom","closeMonth","context","closeAiOverageMonth"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GAED,SAASA,yBAAyB,QAAQ,mDAAkD;AAC5F,SAASC,YAAY,QAAQ,kBAAc;AAE3C;;;CAGC,GACD,OAAO,MAAMC,2BAA2B,iBAAgB;AAExD,8DAA8D,GAC9D,OAAO,MAAMC,+BAA+B,2BAA0B;AAEtE,MAAMC,QAAQ;AAEd;;;;;;;;;CASC,GACD,OAAO,SAASC;QACKC;IAAnB,MAAMC,MAAMC,QAAOF,4CAAAA,QAAQG,GAAG,CAACN,6BAA6B,YAAzCG,4CAA6C,IAAII,IAAI;IACxE,OAAON,MAAMO,IAAI,CAACJ,OAAOA,MAAM;AACjC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASK,wBAAwBC,KAAa;IACnD,MAAMC,OAAOT;IACb,IAAI,CAACS,MAAM,OAAO;IAClB,IAAI,CAACV,MAAMO,IAAI,CAACE,QAAQ,OAAO;IAC/B,OAAOA,SAASC;AAClB;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASC,qBAAqBF,KAAa;IAChD,OAAOD,wBAAwBC;AACjC;AAEA;;;;;;;CAOC,GACD,OAAO,SAASG;IACdhB,0BAA0B;QACxBiB,QAAQf;QACRgB,UAAUjB;QACVkB,WAAWd;QACX,yEAAyE;QACzE,qEAAqE;QACrE,6BAA6B;QAC7Be,YAAY,OAAOC;YACjB,MAAM,EAAEC,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC;YAC7C,MAAMA,oBAAoBD;QAC5B;IACF;AACF"}

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

@@ -0,0 +1,77 @@
+/**
+ * @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 { PluginEventPayloads } from '@aglyn/aglyn/plugin-manager/plugin-events';
+/** The metadata an invoice of ours carries. */
+export declare const AI_OVERAGE_INVOICE_KIND = "ai-overage";
+interface OverageInvoice {
+    chargeId: string;
+    month: string;
+}
+/**
+ * Is this invoice one of ours, and which charge does it settle?
+ *
+ * Both halves are required. `pluginId` alone would claim an invoice another
+ * AI feature might one day raise, and a `chargeId` alone would claim any
+ * invoice that happened to carry the key.
+ */
+export declare function aiOverageInvoiceFromMetadata(metadata: Readonly<Record<string, string>>): OverageInvoice | null;
+/**
+ * An invoice was paid.
+ *
+ * Three consequences, and they are independent of each other:
+ *
+ * 1. The workspace's payment history moves, which is what raises the ceiling
+ *    over time. Every real payment counts, ours or a renewal.
+ * 2. If it was OUR invoice, the charge is settled — and settling is what
+ *    lowers the unpaid balance the gate refuses on, so paying is what lets a
+ *    workspace keep going.
+ * 3. A pause this invoice caused is lifted. A paid renewal also lifts a
+ *    `past_due` pause, because past due is exactly what it stopped being.
+ */
+export declare function onAiBillingInvoicePaid(payload: PluginEventPayloads['billing.invoice.paid'], now?: Date): Promise<void>;
+/**
+ * A charge attempt failed.
+ *
+ * Ours pauses on `charge_failed` and names the invoice, so the sentence the
+ * customer reads points at something they can pay. Anything else is the
+ * workspace's own subscription falling past due, which pauses for a
+ * different reason and names no invoice of ours.
+ *
+ * Either way the workspace keeps its INCLUDED credits. Pausing overage is
+ * about credit we extend between invoices; the band was paid for in advance.
+ */
+export declare function onAiBillingInvoiceFailed(payload: PluginEventPayloads['billing.invoice.failed'], now?: Date): Promise<void>;
+/**
+ * An invoice was voided or written off.
+ *
+ * Only ours matters here: the charge is closed as `void`, and the pause it
+ * set is lifted. Nothing is re-billed — voiding an invoice is a decision
+ * that these dollars are not owed, and the ledger keeps the row so the
+ * decision is visible rather than looking like a gap in the sequence.
+ */
+export declare function onAiBillingInvoiceClosed(payload: PluginEventPayloads['billing.invoice.closed']): Promise<void>;
+/** A dispute resets the ladder and pauses until staff review it. */
+export declare function onAiBillingDisputeOpened(payload: PluginEventPayloads['billing.dispute.opened'], now?: Date): Promise<void>;
+/**
+ * The default payment method changed.
+ *
+ * Mirrored rather than looked up at the gate: the reservation runs on every
+ * metered request and a Stripe round trip there would put a vendor's
+ * latency on the critical path of every AI turn.
+ */
+export declare function onAiBillingPaymentMethodChanged(payload: PluginEventPayloads['billing.paymentMethod.changed']): Promise<void>;
+export {};

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

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WHAT THE PLATFORM'S BILLING EVENTS MEAN TO AI OVERAGE (AGL-3011).
+ *
+ * Five facts reach the plugin from the platform's Stripe webhook, and this
+ * module is where each one becomes a change to a workspace's standing. The
+ * plugin subscribes no Stripe endpoint of its own: core raises the fact, the
+ * plugin decides what it means.
+ *
+ * ## Whose invoice is it
+ *
+ * Every invoice this plugin creates is stamped `pluginId: 'ai'` and
+ * `kind: 'ai-overage'`. An invoice carrying those is OURS — its outcome
+ * settles a charge in the ledger. An invoice without them is the workspace's
+ * subscription, and it still matters: a failed renewal is a past-due
+ * workspace, and extending it credit between invoices is precisely what must
+ * not happen while it owes us money.
+ *
+ * ## Resuming needs no cron
+ *
+ * The gate reads the standing document on every request past the band, so
+ * clearing a pause here is the whole of "overage resumes". There is nothing
+ * to schedule and no cache to expire: the next request sees it.
+ */ import { firebaseAdmin } from "@aglyn/tenant-data-admin";
+import { assistUsageMonth } from "../usage/assist-usage.js";
+import { AI_PLUGIN_ID } from "../constants.js";
+import { settleAiOverageCharge } from "./ai-overage-ledger.js";
+import { pauseAiOverage, recordAiOveragePaidInvoice, recordAiOveragePaymentMethod, recordAiOverageDispute, resumeAiOverage } from "./ai-overage-standing-writes.js";
+/** The metadata an invoice of ours carries. */ export const AI_OVERAGE_INVOICE_KIND = 'ai-overage';
+/**
+ * Is this invoice one of ours, and which charge does it settle?
+ *
+ * Both halves are required. `pluginId` alone would claim an invoice another
+ * AI feature might one day raise, and a `chargeId` alone would claim any
+ * invoice that happened to carry the key.
+ */ export function aiOverageInvoiceFromMetadata(metadata) {
+    var _metadata_chargeId, _metadata_month;
+    if (metadata['pluginId'] !== AI_PLUGIN_ID) return null;
+    if (metadata['kind'] !== AI_OVERAGE_INVOICE_KIND) return null;
+    const chargeId = String((_metadata_chargeId = metadata['chargeId']) != null ? _metadata_chargeId : '').trim();
+    const month = String((_metadata_month = metadata['month']) != null ? _metadata_month : '').trim();
+    if (!chargeId || !/^\d{4}-\d{2}$/.test(month)) return null;
+    return {
+        chargeId,
+        month
+    };
+}
+function firestore() {
+    return firebaseAdmin.app().firestore();
+}
+/**
+ * An invoice was paid.
+ *
+ * Three consequences, and they are independent of each other:
+ *
+ * 1. The workspace's payment history moves, which is what raises the ceiling
+ *    over time. Every real payment counts, ours or a renewal.
+ * 2. If it was OUR invoice, the charge is settled — and settling is what
+ *    lowers the unpaid balance the gate refuses on, so paying is what lets a
+ *    workspace keep going.
+ * 3. A pause this invoice caused is lifted. A paid renewal also lifts a
+ *    `past_due` pause, because past due is exactly what it stopped being.
+ */ export async function onAiBillingInvoicePaid(payload, now = new Date()) {
+    const db = firestore();
+    await recordAiOveragePaidInvoice(db, payload.orgId, {
+        month: assistUsageMonth(now),
+        amountPaidCents: payload.amountPaidCents,
+        paidOutOfBand: payload.paidOutOfBand
+    });
+    const ours = aiOverageInvoiceFromMetadata(payload.metadata);
+    if (ours) {
+        await settleAiOverageCharge(db, payload.orgId, {
+            chargeId: ours.chargeId,
+            month: ours.month,
+            invoiceId: payload.invoiceId,
+            status: 'paid',
+            // The event's own figure (AGL-3023): what Stripe collected, which is
+            // the only thing that may clear what the gate refuses on.
+            paidUsd: payload.amountPaidCents / 100
+        });
+        await resumeAiOverage(db, payload.orgId, {
+            invoiceId: payload.invoiceId
+        });
+        return;
+    }
+    // A renewal paid. It clears the `past_due` pause its own failure set, and
+    // NOTHING else: an AI charge that failed is still an open invoice, and
+    // resuming accrual against it would let the unpaid balance grow.
+    await resumeAiOverage(db, payload.orgId, {
+        reason: 'past_due'
+    });
+}
+/**
+ * A charge attempt failed.
+ *
+ * Ours pauses on `charge_failed` and names the invoice, so the sentence the
+ * customer reads points at something they can pay. Anything else is the
+ * workspace's own subscription falling past due, which pauses for a
+ * different reason and names no invoice of ours.
+ *
+ * Either way the workspace keeps its INCLUDED credits. Pausing overage is
+ * about credit we extend between invoices; the band was paid for in advance.
+ */ export async function onAiBillingInvoiceFailed(payload, now = new Date()) {
+    const db = firestore();
+    const ours = aiOverageInvoiceFromMetadata(payload.metadata);
+    if (ours) {
+        await settleAiOverageCharge(db, payload.orgId, {
+            chargeId: ours.chargeId,
+            month: ours.month,
+            invoiceId: payload.invoiceId,
+            status: 'failed'
+        });
+        await pauseAiOverage(db, payload.orgId, {
+            reason: 'charge_failed',
+            invoiceId: payload.invoiceId,
+            now
+        });
+        return;
+    }
+    await pauseAiOverage(db, payload.orgId, {
+        reason: 'past_due',
+        invoiceId: null,
+        now
+    });
+}
+/**
+ * An invoice was voided or written off.
+ *
+ * Only ours matters here: the charge is closed as `void`, and the pause it
+ * set is lifted. Nothing is re-billed — voiding an invoice is a decision
+ * that these dollars are not owed, and the ledger keeps the row so the
+ * decision is visible rather than looking like a gap in the sequence.
+ */ export async function onAiBillingInvoiceClosed(payload) {
+    const ours = aiOverageInvoiceFromMetadata(payload.metadata);
+    if (!ours) return;
+    const db = firestore();
+    await settleAiOverageCharge(db, payload.orgId, {
+        chargeId: ours.chargeId,
+        month: ours.month,
+        invoiceId: payload.invoiceId,
+        status: 'void'
+    });
+    await resumeAiOverage(db, payload.orgId, {
+        invoiceId: payload.invoiceId
+    });
+}
+/** A dispute resets the ladder and pauses until staff review it. */ export async function onAiBillingDisputeOpened(payload, now = new Date()) {
+    await recordAiOverageDispute(firestore(), payload.orgId, now);
+}
+/**
+ * The default payment method changed.
+ *
+ * Mirrored rather than looked up at the gate: the reservation runs on every
+ * metered request and a Stripe round trip there would put a vendor's
+ * latency on the critical path of every AI turn.
+ */ export async function onAiBillingPaymentMethodChanged(payload) {
+    await recordAiOveragePaymentMethod(firestore(), payload.orgId, payload.defaultType);
+}
+
+//# sourceMappingURL=ai-overage-events.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-events.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 * WHAT THE PLATFORM'S BILLING EVENTS MEAN TO AI OVERAGE (AGL-3011).\n *\n * Five facts reach the plugin from the platform's Stripe webhook, and this\n * module is where each one becomes a change to a workspace's standing. The\n * plugin subscribes no Stripe endpoint of its own: core raises the fact, the\n * plugin decides what it means.\n *\n * ## Whose invoice is it\n *\n * Every invoice this plugin creates is stamped `pluginId: 'ai'` and\n * `kind: 'ai-overage'`. An invoice carrying those is OURS — its outcome\n * settles a charge in the ledger. An invoice without them is the workspace's\n * subscription, and it still matters: a failed renewal is a past-due\n * workspace, and extending it credit between invoices is precisely what must\n * not happen while it owes us money.\n *\n * ## Resuming needs no cron\n *\n * The gate reads the standing document on every request past the band, so\n * clearing a pause here is the whole of \"overage resumes\". There is nothing\n * to schedule and no cache to expire: the next request sees it.\n */\n\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport type { PluginEventPayloads } from '@aglyn/aglyn/plugin-manager/plugin-events'\nimport { assistUsageMonth } from '../usage/assist-usage'\nimport { AI_PLUGIN_ID } from '../constants'\nimport { settleAiOverageCharge } from './ai-overage-ledger'\nimport {\n  pauseAiOverage,\n  recordAiOveragePaidInvoice,\n  recordAiOveragePaymentMethod,\n  recordAiOverageDispute,\n  resumeAiOverage,\n} from './ai-overage-standing-writes'\n\n/** The metadata an invoice of ours carries. */\nexport const AI_OVERAGE_INVOICE_KIND = 'ai-overage'\n\ninterface OverageInvoice {\n  chargeId: string\n  month: string\n}\n\n/**\n * Is this invoice one of ours, and which charge does it settle?\n *\n * Both halves are required. `pluginId` alone would claim an invoice another\n * AI feature might one day raise, and a `chargeId` alone would claim any\n * invoice that happened to carry the key.\n */\nexport function aiOverageInvoiceFromMetadata(\n  metadata: Readonly<Record<string, string>>,\n): OverageInvoice | null {\n  if (metadata['pluginId'] !== AI_PLUGIN_ID) return null\n  if (metadata['kind'] !== AI_OVERAGE_INVOICE_KIND) return null\n  const chargeId = String(metadata['chargeId'] ?? '').trim()\n  const month = String(metadata['month'] ?? '').trim()\n  if (!chargeId || !/^\\d{4}-\\d{2}$/.test(month)) return null\n  return { chargeId, month }\n}\n\nfunction firestore(): FirebaseFirestore.Firestore {\n  return firebaseAdmin.app().firestore()\n}\n\n/**\n * An invoice was paid.\n *\n * Three consequences, and they are independent of each other:\n *\n * 1. The workspace's payment history moves, which is what raises the ceiling\n *    over time. Every real payment counts, ours or a renewal.\n * 2. If it was OUR invoice, the charge is settled — and settling is what\n *    lowers the unpaid balance the gate refuses on, so paying is what lets a\n *    workspace keep going.\n * 3. A pause this invoice caused is lifted. A paid renewal also lifts a\n *    `past_due` pause, because past due is exactly what it stopped being.\n */\nexport async function onAiBillingInvoicePaid(\n  payload: PluginEventPayloads['billing.invoice.paid'],\n  now = new Date(),\n): Promise<void> {\n  const db = firestore()\n  await recordAiOveragePaidInvoice(db, payload.orgId, {\n    month: assistUsageMonth(now),\n    amountPaidCents: payload.amountPaidCents,\n    paidOutOfBand: payload.paidOutOfBand,\n  })\n  const ours = aiOverageInvoiceFromMetadata(payload.metadata)\n  if (ours) {\n    await settleAiOverageCharge(db, payload.orgId, {\n      chargeId: ours.chargeId,\n      month: ours.month,\n      invoiceId: payload.invoiceId,\n      status: 'paid',\n      // The event's own figure (AGL-3023): what Stripe collected, which is\n      // the only thing that may clear what the gate refuses on.\n      paidUsd: payload.amountPaidCents / 100,\n    })\n    await resumeAiOverage(db, payload.orgId, { invoiceId: payload.invoiceId })\n    return\n  }\n  // A renewal paid. It clears the `past_due` pause its own failure set, and\n  // NOTHING else: an AI charge that failed is still an open invoice, and\n  // resuming accrual against it would let the unpaid balance grow.\n  await resumeAiOverage(db, payload.orgId, { reason: 'past_due' })\n}\n\n/**\n * A charge attempt failed.\n *\n * Ours pauses on `charge_failed` and names the invoice, so the sentence the\n * customer reads points at something they can pay. Anything else is the\n * workspace's own subscription falling past due, which pauses for a\n * different reason and names no invoice of ours.\n *\n * Either way the workspace keeps its INCLUDED credits. Pausing overage is\n * about credit we extend between invoices; the band was paid for in advance.\n */\nexport async function onAiBillingInvoiceFailed(\n  payload: PluginEventPayloads['billing.invoice.failed'],\n  now = new Date(),\n): Promise<void> {\n  const db = firestore()\n  const ours = aiOverageInvoiceFromMetadata(payload.metadata)\n  if (ours) {\n    await settleAiOverageCharge(db, payload.orgId, {\n      chargeId: ours.chargeId,\n      month: ours.month,\n      invoiceId: payload.invoiceId,\n      status: 'failed',\n    })\n    await pauseAiOverage(db, payload.orgId, {\n      reason: 'charge_failed',\n      invoiceId: payload.invoiceId,\n      now,\n    })\n    return\n  }\n  await pauseAiOverage(db, payload.orgId, { reason: 'past_due', invoiceId: null, now })\n}\n\n/**\n * An invoice was voided or written off.\n *\n * Only ours matters here: the charge is closed as `void`, and the pause it\n * set is lifted. Nothing is re-billed — voiding an invoice is a decision\n * that these dollars are not owed, and the ledger keeps the row so the\n * decision is visible rather than looking like a gap in the sequence.\n */\nexport async function onAiBillingInvoiceClosed(\n  payload: PluginEventPayloads['billing.invoice.closed'],\n): Promise<void> {\n  const ours = aiOverageInvoiceFromMetadata(payload.metadata)\n  if (!ours) return\n  const db = firestore()\n  await settleAiOverageCharge(db, payload.orgId, {\n    chargeId: ours.chargeId,\n    month: ours.month,\n    invoiceId: payload.invoiceId,\n    status: 'void',\n  })\n  await resumeAiOverage(db, payload.orgId, { invoiceId: payload.invoiceId })\n}\n\n/** A dispute resets the ladder and pauses until staff review it. */\nexport async function onAiBillingDisputeOpened(\n  payload: PluginEventPayloads['billing.dispute.opened'],\n  now = new Date(),\n): Promise<void> {\n  await recordAiOverageDispute(firestore(), payload.orgId, now)\n}\n\n/**\n * The default payment method changed.\n *\n * Mirrored rather than looked up at the gate: the reservation runs on every\n * metered request and a Stripe round trip there would put a vendor's\n * latency on the critical path of every AI turn.\n */\nexport async function onAiBillingPaymentMethodChanged(\n  payload: PluginEventPayloads['billing.paymentMethod.changed'],\n): Promise<void> {\n  await recordAiOveragePaymentMethod(firestore(), payload.orgId, payload.defaultType)\n}\n"],"names":["firebaseAdmin","assistUsageMonth","AI_PLUGIN_ID","settleAiOverageCharge","pauseAiOverage","recordAiOveragePaidInvoice","recordAiOveragePaymentMethod","recordAiOverageDispute","resumeAiOverage","AI_OVERAGE_INVOICE_KIND","aiOverageInvoiceFromMetadata","metadata","chargeId","String","trim","month","test","firestore","app","onAiBillingInvoicePaid","payload","now","Date","db","orgId","amountPaidCents","paidOutOfBand","ours","invoiceId","status","paidUsd","reason","onAiBillingInvoiceFailed","onAiBillingInvoiceClosed","onAiBillingDisputeOpened","onAiBillingPaymentMethodChanged","defaultType"],"mappings":"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"}

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

@@ -0,0 +1,147 @@
+/**
+ * @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 { type AiOverageStanding } from './ai-overage-standing';
+/**
+ * Which limit refused.
+ *
+ * - `no-card`    the workspace has no card as its default payment method.
+ * - `paused`     accrual is stopped — a failed charge, a past-due invoice,
+ *                a dispute, or staff.
+ * - `limit`      this month's overage reached Aglyn's ceiling.
+ * - `settling`   accrued-but-unpaid overage reached the unpaid limit.
+ * - `customer`   the workspace's own ceiling (AGL-2898), which refuses
+ *                before any of the above and keeps its existing sentence.
+ */
+export type AiOverageCapReason = 'no-card' | 'paused' | 'limit' | 'settling' | 'customer';
+/** What the gate hands the guards. All figures are retail dollars. */
+export interface AiOverageGateInput {
+    /** This month's overage, priced as the invoice prices it. */
+    overageUsd: number;
+    /** What of it has been paid — `overagePaidUsd` on the month's rollup. */
+    paidUsd: number;
+    standing: AiOverageStanding;
+    now: Date;
+}
+/** The refusal, with the figure its sentence must quote. */
+export interface AiOverageRefusal {
+    capReason: AiOverageCapReason;
+    /** The ceiling in force, for `limit`; the unpaid limit for `settling`. */
+    limitUsd: number;
+    /** What is accrued and unpaid, for the pause and settling sentences. */
+    unpaidUsd: number;
+}
+/**
+ * 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 declare function aiOverageRefusal(input: AiOverageGateInput): AiOverageRefusal | null;
+/**
+ * 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 declare function aiOverageRefusalText(refusal: AiOverageRefusal): string | 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 declare function aiOverageRefusalStatus(capReason: AiOverageCapReason): 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 declare function aiOverageNextChargeUsd(overageUsd: number, invoicedUsd: number): number;
+/** The refusal fields a reservation carries, without importing its type. */
+export interface AiOverageRefusedReservation {
+    refusedBy: string | null;
+    capReason?: AiOverageCapReason | null;
+    overageLimitUsd?: number | null;
+    overageUnpaidUsd?: number | null;
+}
+/**
+ * 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 declare function aiOverageReservationRefusal(reservation: AiOverageRefusedReservation): {
+    text: string;
+    status: 402 | 429;
+} | null;