@aglyn/plugins-ai 1.0.0-beta.143

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

@@ -0,0 +1,258 @@
+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.
+ */ /**
+ * CHARGING AI OVERAGE AS IT ACCRUES (AGL-3011).
+ *
+ * Three entry points, all of them the same three steps — claim, charge,
+ * settle — differing only in what makes them run:
+ *
+ * - `maybeChargeAiOverage` runs after a metered turn's batch commits, and
+ *   charges when unbilled overage has reached the threshold.
+ * - `closeOutAiOverage` runs after a month ends, and bills the remainder.
+ * - `reconcileAiOverageCharge` runs over a claim that never reported an
+ *   outcome, and asks Stripe what actually happened.
+ *
+ * ## Nothing here runs before the cutover
+ *
+ * Every entry point asks `aiOverageBillsByInvoice` first. With
+ * `AI_OVERAGE_INVOICED_FROM` unset — how it ships — each one returns without
+ * reading a document, and AI overage keeps billing through the monthly meter
+ * exactly as it does today. There is no other switch and no partial state.
+ *
+ * ## A failed charge fails only its own invoice
+ *
+ * The invoice this creates is a one-off, not a subscription invoice. A
+ * declined card fails it and leaves the plan untouched; the subscription
+ * dunning that ends by CANCELING a subscription is not reachable from here.
+ * What the failure does do is pause accrual, which stops the balance growing
+ * while it is unpaid — and leaves the workspace's included credits working.
+ */ import { chargeOrgUsageInvoice, findOrgUsageInvoice } from "@aglyn/tenant-data-admin/server/usage-invoice";
+import { AI_PLUGIN_ID } from "../constants.js";
+import { aiOverageBillsByInvoice } from "./ai-overage-cutover.js";
+import { AI_OVERAGE_CHARGES_SUBCOLLECTION, claimAiOverageCharge, settleAiOverageCharge } from "./ai-overage-ledger.js";
+import { pauseAiOverage } from "./ai-overage-standing-writes.js";
+/**
+ * The Stripe product the overage line is billed against.
+ *
+ * A product rather than a bare amount because the PRODUCT carries the tax
+ * code the account's automatic tax computes from. Created in test mode
+ * first and in live mode only with the owner's yes; until the variable is
+ * set, no charge is attempted and the reason says so rather than failing
+ * against Stripe.
+ */ export const AI_OVERAGE_PRODUCT_ENV = 'STRIPE_PRODUCT_AI_OVERAGE';
+/** The metadata key the reconcile search matches a claim on. */ export const AI_OVERAGE_CHARGE_METADATA_KEY = 'chargeId';
+const NOTHING = {
+    charged: false,
+    chargeId: null,
+    invoiceId: null,
+    skipped: null,
+    error: null
+};
+/**
+ * The line as the customer reads it on the invoice.
+ *
+ * Credits and retail dollars only. Provider cost never reaches a customer
+ * surface, and an invoice is the most customer-facing surface there is.
+ */ export function aiOverageInvoiceDescription(claim) {
+    const credits = claim.credits.toLocaleString('en-US');
+    const month = claim.month;
+    return claim.kind === 'closeout' ? `AI credits past your included band — ${month} close-out (${credits} credits)` : `AI credits past your included band — ${month} (${credits} credits)`;
+}
+async function chargeClaim(firestore, request, claim) {
+    var _process_env_AI_OVERAGE_PRODUCT_ENV;
+    const productId = String((_process_env_AI_OVERAGE_PRODUCT_ENV = process.env[AI_OVERAGE_PRODUCT_ENV]) != null ? _process_env_AI_OVERAGE_PRODUCT_ENV : '').trim();
+    if (!productId) {
+        // The claim is released rather than left open: with no product there is
+        // nothing to bill against, and an open claim would block every later
+        // charge behind a state that only configuration can change.
+        await settleAiOverageCharge(firestore, request.orgId, {
+            chargeId: claim.chargeId,
+            month: claim.month,
+            invoiceId: null,
+            status: 'failed'
+        });
+        return _extends({}, NOTHING, {
+            chargeId: claim.chargeId,
+            skipped: 'no-product'
+        });
+    }
+    const result = await chargeOrgUsageInvoice({
+        orgId: request.orgId,
+        stripeCustomerId: request.stripeCustomerId,
+        productId,
+        amountCents: Math.round(claim.amountUsd * 100),
+        currency: 'usd',
+        description: aiOverageInvoiceDescription(claim),
+        metadata: {
+            orgId: request.orgId,
+            pluginId: AI_PLUGIN_ID,
+            kind: 'ai-overage',
+            [AI_OVERAGE_CHARGE_METADATA_KEY]: claim.chargeId,
+            month: claim.month
+        },
+        // One key per attempt, derived from the claim — which is unique per
+        // workspace-month-sequence — so a retry of this attempt re-reads the
+        // objects the first one made instead of creating a second invoice.
+        idempotencyKey: `aiov-${request.orgId}-${claim.chargeId}`
+    });
+    // `failed` covers both shapes of a failure, and the difference between
+    // them is carried by `invoiceId`: an invoice that exists keeps its claim on
+    // the month's unbilled total, and one that never existed releases it. The
+    // ledger reads that distinction rather than a second status for it.
+    await settleAiOverageCharge(firestore, request.orgId, {
+        chargeId: claim.chargeId,
+        month: claim.month,
+        invoiceId: result.invoiceId,
+        status: result.ok ? 'paid' : 'failed',
+        // What Stripe took, not what we claimed (AGL-3023). The two agree on
+        // every ordinary charge; where they do not, crediting the claim would
+        // clear a balance nobody paid.
+        paidUsd: result.amountPaidCents / 100
+    });
+    if (!result.ok) {
+        var _request_now;
+        // `requires_action` reads like "not yet" and is in fact "no": nobody is
+        // at the keyboard for an off-session charge, so a 3-D Secure challenge
+        // is a charge that will not complete. It pauses accrual like a decline.
+        await pauseAiOverage(firestore, request.orgId, {
+            reason: 'charge_failed',
+            invoiceId: result.invoiceId,
+            now: (_request_now = request.now) != null ? _request_now : new Date()
+        });
+    }
+    return {
+        charged: result.ok,
+        chargeId: claim.chargeId,
+        invoiceId: result.invoiceId,
+        skipped: null,
+        error: result.error
+    };
+}
+async function runCharge(firestore, request, kind) {
+    if (!aiOverageBillsByInvoice(request.month)) {
+        return _extends({}, NOTHING, {
+            skipped: 'before-cutover'
+        });
+    }
+    if (!request.stripeCustomerId) {
+        return _extends({}, NOTHING, {
+            skipped: 'no-stripe-customer'
+        });
+    }
+    const claim = await claimAiOverageCharge(firestore, {
+        orgId: request.orgId,
+        org: request.org,
+        month: request.month,
+        kind,
+        now: request.now
+    });
+    if (!claim.claimed) return _extends({}, NOTHING, {
+        skipped: claim.refused
+    });
+    return chargeClaim(firestore, _extends({}, request, {
+        stripeCustomerId: request.stripeCustomerId
+    }), claim.claimed);
+}
+/**
+ * Charges the workspace when its unbilled overage has reached the threshold.
+ *
+ * Called from `after()` once a metered turn's batch has committed, never on
+ * the request's await path: the tokens are already spent, and making a
+ * customer wait on a Stripe round trip to be handed an answer they have
+ * already paid for is the wrong trade. A charge that does not happen because
+ * the process ended is picked up by the reconcile sweep or by the next turn.
+ */ export function maybeChargeAiOverage(firestore, request) {
+    return runCharge(firestore, request, 'threshold');
+}
+/**
+ * Bills the remainder of a month that has ended.
+ *
+ * The month's last charge, and the only one that bills below the threshold —
+ * there is nothing more to accrue, so anything Stripe will accept is worth
+ * settling. A remainder under Stripe's minimum is left unbilled rather than
+ * sent as an invoice that can never be paid.
+ */ export function closeOutAiOverage(firestore, request) {
+    return runCharge(firestore, request, 'closeout');
+}
+/**
+ * Asks Stripe what became of a claim that never reported an outcome.
+ *
+ * The case is a process that died between claiming and charging, or between
+ * charging and recording. The claim id is on the invoice's metadata, so the
+ * question "did this claim ever become an invoice" has an answer even though
+ * this process never saw one.
+ *
+ * Stripe's search index is eventually consistent, so "not found" means NOT
+ * FOUND YET. A claim is only released after a grace period long enough for
+ * the index to have caught up; releasing early would create a second invoice
+ * for dollars that are already billed.
+ */ export async function reconcileAiOverageCharge(firestore, request, options = {}) {
+    var _options_graceMs;
+    const graceMs = (_options_graceMs = options.graceMs) != null ? _options_graceMs : 15 * 60 * 1000;
+    const found = await findOrgUsageInvoice({
+        metadataKey: AI_OVERAGE_CHARGE_METADATA_KEY,
+        metadataValue: request.chargeId
+    });
+    if (found.invoiceId) {
+        await settleAiOverageCharge(firestore, request.orgId, {
+            chargeId: request.chargeId,
+            month: request.month,
+            invoiceId: found.invoiceId,
+            status: found.status === 'paid' ? 'paid' : found.status === 'void' ? 'void' : found.status === 'uncollectible' ? 'void' : 'open',
+            // The found invoice's own collected figure (AGL-3023), never the
+            // claim: a reconcile that credited what we meant to charge would clear
+            // a balance on the strength of an invoice it had just looked up.
+            paidUsd: found.amountPaidCents / 100
+        });
+        return {
+            resolved: true,
+            invoiceId: found.invoiceId,
+            released: false
+        };
+    }
+    if (found.error) return {
+        resolved: false,
+        invoiceId: null,
+        released: false
+    };
+    if (request.claimedAgeMs < graceMs) {
+        return {
+            resolved: false,
+            invoiceId: null,
+            released: false
+        };
+    }
+    // Old enough that the index would have it. No invoice was ever created, so
+    // the dollars the claim reserved go back to unbilled and a later charge
+    // bills them.
+    await settleAiOverageCharge(firestore, request.orgId, {
+        chargeId: request.chargeId,
+        month: request.month,
+        invoiceId: null,
+        status: 'failed'
+    });
+    return {
+        resolved: true,
+        invoiceId: null,
+        released: true
+    };
+}
+/** The path a claimed charge's audit row lives at, for the sweep's query. */ export function aiOverageChargesPath(orgId) {
+    return `orgs/${orgId}/${AI_OVERAGE_CHARGES_SUBCOLLECTION}`;
+}
+
+//# sourceMappingURL=ai-overage-charge.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-charge.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 * CHARGING AI OVERAGE AS IT ACCRUES (AGL-3011).\n *\n * Three entry points, all of them the same three steps — claim, charge,\n * settle — differing only in what makes them run:\n *\n * - `maybeChargeAiOverage` runs after a metered turn's batch commits, and\n *   charges when unbilled overage has reached the threshold.\n * - `closeOutAiOverage` runs after a month ends, and bills the remainder.\n * - `reconcileAiOverageCharge` runs over a claim that never reported an\n *   outcome, and asks Stripe what actually happened.\n *\n * ## Nothing here runs before the cutover\n *\n * Every entry point asks `aiOverageBillsByInvoice` first. With\n * `AI_OVERAGE_INVOICED_FROM` unset — how it ships — each one returns without\n * reading a document, and AI overage keeps billing through the monthly meter\n * exactly as it does today. There is no other switch and no partial state.\n *\n * ## A failed charge fails only its own invoice\n *\n * The invoice this creates is a one-off, not a subscription invoice. A\n * declined card fails it and leaves the plan untouched; the subscription\n * dunning that ends by CANCELING a subscription is not reachable from here.\n * What the failure does do is pause accrual, which stops the balance growing\n * while it is unpaid — and leaves the workspace's included credits working.\n */\n\nimport {\n  chargeOrgUsageInvoice,\n  findOrgUsageInvoice,\n} from '@aglyn/tenant-data-admin/server/usage-invoice'\nimport { AI_PLUGIN_ID } from '../constants'\nimport { aiOverageBillsByInvoice } from './ai-overage-cutover'\nimport {\n  AI_OVERAGE_CHARGES_SUBCOLLECTION,\n  claimAiOverageCharge,\n  settleAiOverageCharge,\n  type AiOverageChargeKind,\n  type AiOverageClaim,\n  type AiOverageClaimRefusal,\n} from './ai-overage-ledger'\nimport { pauseAiOverage } from './ai-overage-standing-writes'\nimport type { AiOverageOrg } from './ai-overage-standing'\n\n/**\n * The Stripe product the overage line is billed against.\n *\n * A product rather than a bare amount because the PRODUCT carries the tax\n * code the account's automatic tax computes from. Created in test mode\n * first and in live mode only with the owner's yes; until the variable is\n * set, no charge is attempted and the reason says so rather than failing\n * against Stripe.\n */\nexport const AI_OVERAGE_PRODUCT_ENV = 'STRIPE_PRODUCT_AI_OVERAGE'\n\n/** The metadata key the reconcile search matches a claim on. */\nexport const AI_OVERAGE_CHARGE_METADATA_KEY = 'chargeId'\n\n/** What one attempt did, for logs, the sweep's report and specs. */\nexport interface AiOverageChargeOutcome {\n  charged: boolean\n  chargeId: string | null\n  invoiceId: string | null\n  /** Why nothing was charged, when nothing was. */\n  skipped:\n    | AiOverageClaimRefusal\n    | 'before-cutover'\n    | 'no-stripe-customer'\n    | 'no-product'\n    | null\n  /** Stripe's message when a charge was attempted and failed. */\n  error: string | null\n}\n\nconst NOTHING: AiOverageChargeOutcome = {\n  charged: false,\n  chargeId: null,\n  invoiceId: null,\n  skipped: null,\n  error: null,\n}\n\n/** What the caller must hand over; nothing here reads the org document. */\nexport interface AiOverageChargeRequest {\n  orgId: string\n  org: AiOverageOrg\n  month: string\n  /** The workspace's Stripe customer, resolved by the caller from billing. */\n  stripeCustomerId: string | null\n  now?: Date\n}\n\n/**\n * The line as the customer reads it on the invoice.\n *\n * Credits and retail dollars only. Provider cost never reaches a customer\n * surface, and an invoice is the most customer-facing surface there is.\n */\nexport function aiOverageInvoiceDescription(claim: AiOverageClaim): string {\n  const credits = claim.credits.toLocaleString('en-US')\n  const month = claim.month\n  return claim.kind === 'closeout'\n    ? `AI credits past your included band — ${month} close-out (${credits} credits)`\n    : `AI credits past your included band — ${month} (${credits} credits)`\n}\n\nasync function chargeClaim(\n  firestore: FirebaseFirestore.Firestore,\n  request: AiOverageChargeRequest & { stripeCustomerId: string },\n  claim: AiOverageClaim,\n): Promise<AiOverageChargeOutcome> {\n  const productId = String(process.env[AI_OVERAGE_PRODUCT_ENV] ?? '').trim()\n  if (!productId) {\n    // The claim is released rather than left open: with no product there is\n    // nothing to bill against, and an open claim would block every later\n    // charge behind a state that only configuration can change.\n    await settleAiOverageCharge(firestore, request.orgId, {\n      chargeId: claim.chargeId,\n      month: claim.month,\n      invoiceId: null,\n      status: 'failed',\n    })\n    return { ...NOTHING, chargeId: claim.chargeId, skipped: 'no-product' }\n  }\n  const result = await chargeOrgUsageInvoice({\n    orgId: request.orgId,\n    stripeCustomerId: request.stripeCustomerId,\n    productId,\n    amountCents: Math.round(claim.amountUsd * 100),\n    currency: 'usd',\n    description: aiOverageInvoiceDescription(claim),\n    metadata: {\n      orgId: request.orgId,\n      pluginId: AI_PLUGIN_ID,\n      kind: 'ai-overage',\n      [AI_OVERAGE_CHARGE_METADATA_KEY]: claim.chargeId,\n      month: claim.month,\n    },\n    // One key per attempt, derived from the claim — which is unique per\n    // workspace-month-sequence — so a retry of this attempt re-reads the\n    // objects the first one made instead of creating a second invoice.\n    idempotencyKey: `aiov-${request.orgId}-${claim.chargeId}`,\n  })\n  // `failed` covers both shapes of a failure, and the difference between\n  // them is carried by `invoiceId`: an invoice that exists keeps its claim on\n  // the month's unbilled total, and one that never existed releases it. The\n  // ledger reads that distinction rather than a second status for it.\n  await settleAiOverageCharge(firestore, request.orgId, {\n    chargeId: claim.chargeId,\n    month: claim.month,\n    invoiceId: result.invoiceId,\n    status: result.ok ? 'paid' : 'failed',\n    // What Stripe took, not what we claimed (AGL-3023). The two agree on\n    // every ordinary charge; where they do not, crediting the claim would\n    // clear a balance nobody paid.\n    paidUsd: result.amountPaidCents / 100,\n  })\n  if (!result.ok) {\n    // `requires_action` reads like \"not yet\" and is in fact \"no\": nobody is\n    // at the keyboard for an off-session charge, so a 3-D Secure challenge\n    // is a charge that will not complete. It pauses accrual like a decline.\n    await pauseAiOverage(firestore, request.orgId, {\n      reason: 'charge_failed',\n      invoiceId: result.invoiceId,\n      now: request.now ?? new Date(),\n    })\n  }\n  return {\n    charged: result.ok,\n    chargeId: claim.chargeId,\n    invoiceId: result.invoiceId,\n    skipped: null,\n    error: result.error,\n  }\n}\n\nasync function runCharge(\n  firestore: FirebaseFirestore.Firestore,\n  request: AiOverageChargeRequest,\n  kind: AiOverageChargeKind,\n): Promise<AiOverageChargeOutcome> {\n  if (!aiOverageBillsByInvoice(request.month)) {\n    return { ...NOTHING, skipped: 'before-cutover' }\n  }\n  if (!request.stripeCustomerId) {\n    return { ...NOTHING, skipped: 'no-stripe-customer' }\n  }\n  const claim = await claimAiOverageCharge(firestore, {\n    orgId: request.orgId,\n    org: request.org,\n    month: request.month,\n    kind,\n    now: request.now,\n  })\n  if (!claim.claimed) return { ...NOTHING, skipped: claim.refused }\n  return chargeClaim(\n    firestore,\n    { ...request, stripeCustomerId: request.stripeCustomerId },\n    claim.claimed,\n  )\n}\n\n/**\n * Charges the workspace when its unbilled overage has reached the threshold.\n *\n * Called from `after()` once a metered turn's batch has committed, never on\n * the request's await path: the tokens are already spent, and making a\n * customer wait on a Stripe round trip to be handed an answer they have\n * already paid for is the wrong trade. A charge that does not happen because\n * the process ended is picked up by the reconcile sweep or by the next turn.\n */\nexport function maybeChargeAiOverage(\n  firestore: FirebaseFirestore.Firestore,\n  request: AiOverageChargeRequest,\n): Promise<AiOverageChargeOutcome> {\n  return runCharge(firestore, request, 'threshold')\n}\n\n/**\n * Bills the remainder of a month that has ended.\n *\n * The month's last charge, and the only one that bills below the threshold —\n * there is nothing more to accrue, so anything Stripe will accept is worth\n * settling. A remainder under Stripe's minimum is left unbilled rather than\n * sent as an invoice that can never be paid.\n */\nexport function closeOutAiOverage(\n  firestore: FirebaseFirestore.Firestore,\n  request: AiOverageChargeRequest,\n): Promise<AiOverageChargeOutcome> {\n  return runCharge(firestore, request, 'closeout')\n}\n\n/**\n * Asks Stripe what became of a claim that never reported an outcome.\n *\n * The case is a process that died between claiming and charging, or between\n * charging and recording. The claim id is on the invoice's metadata, so the\n * question \"did this claim ever become an invoice\" has an answer even though\n * this process never saw one.\n *\n * Stripe's search index is eventually consistent, so \"not found\" means NOT\n * FOUND YET. A claim is only released after a grace period long enough for\n * the index to have caught up; releasing early would create a second invoice\n * for dollars that are already billed.\n */\nexport async function reconcileAiOverageCharge(\n  firestore: FirebaseFirestore.Firestore,\n  request: { orgId: string; month: string; chargeId: string; claimedAgeMs: number },\n  options: { graceMs?: number } = {},\n): Promise<{ resolved: boolean; invoiceId: string | null; released: boolean }> {\n  const graceMs = options.graceMs ?? 15 * 60 * 1000\n  const found = await findOrgUsageInvoice({\n    metadataKey: AI_OVERAGE_CHARGE_METADATA_KEY,\n    metadataValue: request.chargeId,\n  })\n  if (found.invoiceId) {\n    await settleAiOverageCharge(firestore, request.orgId, {\n      chargeId: request.chargeId,\n      month: request.month,\n      invoiceId: found.invoiceId,\n      status:\n        found.status === 'paid'\n          ? 'paid'\n          : found.status === 'void'\n            ? 'void'\n            : found.status === 'uncollectible'\n              ? 'void'\n              : 'open',\n      // The found invoice's own collected figure (AGL-3023), never the\n      // claim: a reconcile that credited what we meant to charge would clear\n      // a balance on the strength of an invoice it had just looked up.\n      paidUsd: found.amountPaidCents / 100,\n    })\n    return { resolved: true, invoiceId: found.invoiceId, released: false }\n  }\n  if (found.error) return { resolved: false, invoiceId: null, released: false }\n  if (request.claimedAgeMs < graceMs) {\n    return { resolved: false, invoiceId: null, released: false }\n  }\n  // Old enough that the index would have it. No invoice was ever created, so\n  // the dollars the claim reserved go back to unbilled and a later charge\n  // bills them.\n  await settleAiOverageCharge(firestore, request.orgId, {\n    chargeId: request.chargeId,\n    month: request.month,\n    invoiceId: null,\n    status: 'failed',\n  })\n  return { resolved: true, invoiceId: null, released: true }\n}\n\n/** The path a claimed charge's audit row lives at, for the sweep's query. */\nexport function aiOverageChargesPath(orgId: string): string {\n  return `orgs/${orgId}/${AI_OVERAGE_CHARGES_SUBCOLLECTION}`\n}\n"],"names":["chargeOrgUsageInvoice","findOrgUsageInvoice","AI_PLUGIN_ID","aiOverageBillsByInvoice","AI_OVERAGE_CHARGES_SUBCOLLECTION","claimAiOverageCharge","settleAiOverageCharge","pauseAiOverage","AI_OVERAGE_PRODUCT_ENV","AI_OVERAGE_CHARGE_METADATA_KEY","NOTHING","charged","chargeId","invoiceId","skipped","error","aiOverageInvoiceDescription","claim","credits","toLocaleString","month","kind","chargeClaim","firestore","request","process","productId","String","env","trim","orgId","status","result","stripeCustomerId","amountCents","Math","round","amountUsd","currency","description","metadata","pluginId","idempotencyKey","ok","paidUsd","amountPaidCents","reason","now","Date","runCharge","org","claimed","refused","maybeChargeAiOverage","closeOutAiOverage","reconcileAiOverageCharge","options","graceMs","found","metadataKey","metadataValue","resolved","released","claimedAgeMs","aiOverageChargesPath"],"mappings":"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"}

package/src/lib/billing/ai-overage-close.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.
+ */
+/**
+ * CLOSING A MONTH OF AI OVERAGE (AGL-3011).
+ *
+ * Charging as usage accrues always leaves a remainder: the part of a month
+ * that never reached the threshold before the month ended. This settles it,
+ * and does the two other things a month's end is the right moment for.
+ *
+ * Run from the platform's closed-month usage sweep through the metered-line
+ * seam — the one job that already knows every workspace, its month and its
+ * Stripe customer — rather than from a cron of its own. A second schedule
+ * for the same fact is a second schedule to keep in step, and the sweep that
+ * closes the month is by definition on time for this.
+ *
+ * ## Three things, in order
+ *
+ * 1. **Reconcile.** A claim that never reported an outcome is asked about in
+ *    Stripe, and either recorded or released. It comes first because a stuck
+ *    open charge blocks the close-out behind it.
+ * 2. **Close out.** Whatever is left unbilled is invoiced, however small —
+ *    down to Stripe's minimum, below which it is carried rather than sent as
+ *    an invoice nobody can pay.
+ * 3. **Correct the ladder.** A month that ended with an AI charge unpaid is
+ *    taken back off the workspace's qualifying months. A month in which a
+ *    workspace both paid an invoice and left an AI charge unpaid is not
+ *    evidence of the thing the ladder measures.
+ *
+ * Idempotent, because the sweep calls it every day the month is closed: the
+ * reconcile is a no-op once the charge is settled, the close-out claims
+ * nothing once there is nothing unbilled, and the month is dropped from the
+ * ladder only while it is on it.
+ */
+import type { PluginMeteredLineMonthContext } from '@aglyn/aglyn/plugin-manager/plugin-metered-lines';
+/** What the close-out did, for the sweep's log and the specs. */
+export interface AiOverageCloseResult {
+    reconciled: number;
+    closedOutUsd: number;
+    droppedFromLadder: boolean;
+}
+/**
+ * Settles one workspace's closed month.
+ *
+ * Errors are the caller's to isolate — the registry logs and continues — but
+ * each step is attempted independently so one workspace's failed Stripe call
+ * does not cost it the ladder correction it also needed.
+ */
+export declare function closeAiOverageMonth(context: PluginMeteredLineMonthContext, now?: Date): Promise<AiOverageCloseResult>;

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

@@ -0,0 +1,129 @@
+/**
+ * @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.
+ */ /**
+ * CLOSING A MONTH OF AI OVERAGE (AGL-3011).
+ *
+ * Charging as usage accrues always leaves a remainder: the part of a month
+ * that never reached the threshold before the month ended. This settles it,
+ * and does the two other things a month's end is the right moment for.
+ *
+ * Run from the platform's closed-month usage sweep through the metered-line
+ * seam — the one job that already knows every workspace, its month and its
+ * Stripe customer — rather than from a cron of its own. A second schedule
+ * for the same fact is a second schedule to keep in step, and the sweep that
+ * closes the month is by definition on time for this.
+ *
+ * ## Three things, in order
+ *
+ * 1. **Reconcile.** A claim that never reported an outcome is asked about in
+ *    Stripe, and either recorded or released. It comes first because a stuck
+ *    open charge blocks the close-out behind it.
+ * 2. **Close out.** Whatever is left unbilled is invoiced, however small —
+ *    down to Stripe's minimum, below which it is carried rather than sent as
+ *    an invoice nobody can pay.
+ * 3. **Correct the ladder.** A month that ended with an AI charge unpaid is
+ *    taken back off the workspace's qualifying months. A month in which a
+ *    workspace both paid an invoice and left an AI charge unpaid is not
+ *    evidence of the thing the ladder measures.
+ *
+ * Idempotent, because the sweep calls it every day the month is closed: the
+ * reconcile is a no-op once the charge is settled, the close-out claims
+ * nothing once there is nothing unbilled, and the month is dropped from the
+ * ladder only while it is on it.
+ */ import { closeOutAiOverage, reconcileAiOverageCharge } from "./ai-overage-charge.js";
+import { AI_OVERAGE_CHARGES_SUBCOLLECTION, readAiOverageMonthLedger } from "./ai-overage-ledger.js";
+import { dropAiOverageQualifyingMonth } from "./ai-overage-standing-writes.js";
+import { aiOverageFirestore } from "./ai-overage-trigger.js";
+/** How many of a month's charge rows the close-out will look at. */ const CHARGE_SCAN = 100;
+/**
+ * Settles one workspace's closed month.
+ *
+ * Errors are the caller's to isolate — the registry logs and continues — but
+ * each step is attempted independently so one workspace's failed Stripe call
+ * does not cost it the ladder correction it also needed.
+ */ export async function closeAiOverageMonth(context, now = new Date()) {
+    var _usageSnapshot_data;
+    const firestore = aiOverageFirestore();
+    const orgRef = firestore.collection('orgs').doc(context.orgId);
+    const usageSnapshot = await orgRef.collection('assistUsage').doc(context.month).get();
+    const ledger = readAiOverageMonthLedger(usageSnapshot.exists ? (_usageSnapshot_data = usageSnapshot.data()) != null ? _usageSnapshot_data : null : null);
+    const result = {
+        reconciled: 0,
+        closedOutUsd: 0,
+        droppedFromLadder: false
+    };
+    // A month that never sold any overage has nothing here at all, and asking
+    // Stripe about it would be a round trip per workspace per day.
+    if (!ledger.charges && !ledger.invoicedUsd && !ledger.open) {
+        return result;
+    }
+    // 1. An open claim that never reported. `since` is on the open slot, so
+    //    its age is known without a second read.
+    if (ledger.open) {
+        var _ref;
+        const open = usageSnapshot.get('overageInvoiceOpen');
+        const since = Date.parse(String((_ref = open == null ? void 0 : open.since) != null ? _ref : ''));
+        const claimedAgeMs = Number.isFinite(since) ? Math.max(0, now.getTime() - since) : Number.MAX_SAFE_INTEGER;
+        const reconciled = await reconcileAiOverageCharge(firestore, {
+            orgId: context.orgId,
+            month: context.month,
+            chargeId: ledger.open.chargeId,
+            claimedAgeMs
+        });
+        if (reconciled.resolved) result.reconciled = 1;
+    }
+    // 2. The remainder.
+    const closed = await closeOutAiOverage(firestore, {
+        orgId: context.orgId,
+        org: context.org,
+        month: context.month,
+        stripeCustomerId: context.stripeCustomerId,
+        now
+    });
+    if (closed.charged) {
+        var _after_data;
+        const after = await orgRef.collection('assistUsage').doc(context.month).get();
+        result.closedOutUsd = readAiOverageMonthLedger((_after_data = after.data()) != null ? _after_data : null).invoicedUsd - ledger.invoicedUsd;
+    }
+    // 3. The ladder. Read AFTER the two steps above, so a charge they settled
+    //    is not counted as unpaid.
+    if (await aiOverageMonthLeftUnpaid(orgRef, context.month)) {
+        await dropAiOverageQualifyingMonth(firestore, context.orgId, context.month);
+        result.droppedFromLadder = true;
+    }
+    return result;
+}
+/**
+ * Did this month end with an AI overage charge still unpaid?
+ *
+ * `failed` and `open` both count; `void` does not — an invoice written off
+ * is a decision that the money is not owed, not a debt the workspace left.
+ * A `claimed` row that survived the reconcile above counts too: something
+ * claimed the money and never billed it, which is exactly the state that
+ * should not raise a ceiling.
+ */ async function aiOverageMonthLeftUnpaid(orgRef, month) {
+    const charges = await orgRef.collection(AI_OVERAGE_CHARGES_SUBCOLLECTION).where('month', '==', month).limit(CHARGE_SCAN).get();
+    return charges.docs.some((doc)=>{
+        var _doc_get;
+        return [
+            'claimed',
+            'open',
+            'failed'
+        ].includes(String((_doc_get = doc.get('status')) != null ? _doc_get : ''));
+    });
+}
+
+//# sourceMappingURL=ai-overage-close.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/billing/ai-overage-close.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 * CLOSING A MONTH OF AI OVERAGE (AGL-3011).\n *\n * Charging as usage accrues always leaves a remainder: the part of a month\n * that never reached the threshold before the month ended. This settles it,\n * and does the two other things a month's end is the right moment for.\n *\n * Run from the platform's closed-month usage sweep through the metered-line\n * seam — the one job that already knows every workspace, its month and its\n * Stripe customer — rather than from a cron of its own. A second schedule\n * for the same fact is a second schedule to keep in step, and the sweep that\n * closes the month is by definition on time for this.\n *\n * ## Three things, in order\n *\n * 1. **Reconcile.** A claim that never reported an outcome is asked about in\n *    Stripe, and either recorded or released. It comes first because a stuck\n *    open charge blocks the close-out behind it.\n * 2. **Close out.** Whatever is left unbilled is invoiced, however small —\n *    down to Stripe's minimum, below which it is carried rather than sent as\n *    an invoice nobody can pay.\n * 3. **Correct the ladder.** A month that ended with an AI charge unpaid is\n *    taken back off the workspace's qualifying months. A month in which a\n *    workspace both paid an invoice and left an AI charge unpaid is not\n *    evidence of the thing the ladder measures.\n *\n * Idempotent, because the sweep calls it every day the month is closed: the\n * reconcile is a no-op once the charge is settled, the close-out claims\n * nothing once there is nothing unbilled, and the month is dropped from the\n * ladder only while it is on it.\n */\n\nimport type { PluginMeteredLineMonthContext } from '@aglyn/aglyn/plugin-manager/plugin-metered-lines'\nimport {\n  closeOutAiOverage,\n  reconcileAiOverageCharge,\n} from './ai-overage-charge'\nimport {\n  AI_OVERAGE_CHARGES_SUBCOLLECTION,\n  readAiOverageMonthLedger,\n} from './ai-overage-ledger'\nimport { dropAiOverageQualifyingMonth } from './ai-overage-standing-writes'\nimport { aiOverageFirestore } from './ai-overage-trigger'\n\n/** How many of a month's charge rows the close-out will look at. */\nconst CHARGE_SCAN = 100\n\n/** What the close-out did, for the sweep's log and the specs. */\nexport interface AiOverageCloseResult {\n  reconciled: number\n  closedOutUsd: number\n  droppedFromLadder: boolean\n}\n\n/**\n * Settles one workspace's closed month.\n *\n * Errors are the caller's to isolate — the registry logs and continues — but\n * each step is attempted independently so one workspace's failed Stripe call\n * does not cost it the ladder correction it also needed.\n */\nexport async function closeAiOverageMonth(\n  context: PluginMeteredLineMonthContext,\n  now = new Date(),\n): Promise<AiOverageCloseResult> {\n  const firestore = aiOverageFirestore()\n  const orgRef = firestore.collection('orgs').doc(context.orgId)\n  const usageSnapshot = await orgRef\n    .collection('assistUsage')\n    .doc(context.month)\n    .get()\n  const ledger = readAiOverageMonthLedger(\n    usageSnapshot.exists ? (usageSnapshot.data() ?? null) : null,\n  )\n  const result: AiOverageCloseResult = {\n    reconciled: 0,\n    closedOutUsd: 0,\n    droppedFromLadder: false,\n  }\n  // A month that never sold any overage has nothing here at all, and asking\n  // Stripe about it would be a round trip per workspace per day.\n  if (!ledger.charges && !ledger.invoicedUsd && !ledger.open) {\n    return result\n  }\n\n  // 1. An open claim that never reported. `since` is on the open slot, so\n  //    its age is known without a second read.\n  if (ledger.open) {\n    const open = usageSnapshot.get('overageInvoiceOpen') as\n      | { since?: unknown }\n      | null\n      | undefined\n    const since = Date.parse(String(open?.since ?? ''))\n    const claimedAgeMs = Number.isFinite(since)\n      ? Math.max(0, now.getTime() - since)\n      : Number.MAX_SAFE_INTEGER\n    const reconciled = await reconcileAiOverageCharge(firestore, {\n      orgId: context.orgId,\n      month: context.month,\n      chargeId: ledger.open.chargeId,\n      claimedAgeMs,\n    })\n    if (reconciled.resolved) result.reconciled = 1\n  }\n\n  // 2. The remainder.\n  const closed = await closeOutAiOverage(firestore, {\n    orgId: context.orgId,\n    org: context.org as never,\n    month: context.month,\n    stripeCustomerId: context.stripeCustomerId,\n    now,\n  })\n  if (closed.charged) {\n    const after = await orgRef.collection('assistUsage').doc(context.month).get()\n    result.closedOutUsd =\n      readAiOverageMonthLedger(after.data() ?? null).invoicedUsd - ledger.invoicedUsd\n  }\n\n  // 3. The ladder. Read AFTER the two steps above, so a charge they settled\n  //    is not counted as unpaid.\n  if (await aiOverageMonthLeftUnpaid(orgRef, context.month)) {\n    await dropAiOverageQualifyingMonth(firestore, context.orgId, context.month)\n    result.droppedFromLadder = true\n  }\n  return result\n}\n\n/**\n * Did this month end with an AI overage charge still unpaid?\n *\n * `failed` and `open` both count; `void` does not — an invoice written off\n * is a decision that the money is not owed, not a debt the workspace left.\n * A `claimed` row that survived the reconcile above counts too: something\n * claimed the money and never billed it, which is exactly the state that\n * should not raise a ceiling.\n */\nasync function aiOverageMonthLeftUnpaid(\n  orgRef: FirebaseFirestore.DocumentReference,\n  month: string,\n): Promise<boolean> {\n  const charges = await orgRef\n    .collection(AI_OVERAGE_CHARGES_SUBCOLLECTION)\n    .where('month', '==', month)\n    .limit(CHARGE_SCAN)\n    .get()\n  return charges.docs.some((doc) =>\n    ['claimed', 'open', 'failed'].includes(String(doc.get('status') ?? '')),\n  )\n}\n"],"names":["closeOutAiOverage","reconcileAiOverageCharge","AI_OVERAGE_CHARGES_SUBCOLLECTION","readAiOverageMonthLedger","dropAiOverageQualifyingMonth","aiOverageFirestore","CHARGE_SCAN","closeAiOverageMonth","context","now","Date","usageSnapshot","firestore","orgRef","collection","doc","orgId","month","get","ledger","exists","data","result","reconciled","closedOutUsd","droppedFromLadder","charges","invoicedUsd","open","since","parse","String","claimedAgeMs","Number","isFinite","Math","max","getTime","MAX_SAFE_INTEGER","chargeId","resolved","closed","org","stripeCustomerId","charged","after","aiOverageMonthLeftUnpaid","where","limit","docs","some","includes"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GAGD,SACEA,iBAAiB,EACjBC,wBAAwB,QACnB,yBAAqB;AAC5B,SACEC,gCAAgC,EAChCC,wBAAwB,QACnB,yBAAqB;AAC5B,SAASC,4BAA4B,QAAQ,kCAA8B;AAC3E,SAASC,kBAAkB,QAAQ,0BAAsB;AAEzD,kEAAkE,GAClE,MAAMC,cAAc;AASpB;;;;;;CAMC,GACD,OAAO,eAAeC,oBACpBC,OAAsC,EACtCC,MAAM,IAAIC,MAAM;QASUC;IAP1B,MAAMC,YAAYP;IAClB,MAAMQ,SAASD,UAAUE,UAAU,CAAC,QAAQC,GAAG,CAACP,QAAQQ,KAAK;IAC7D,MAAML,gBAAgB,MAAME,OACzBC,UAAU,CAAC,eACXC,GAAG,CAACP,QAAQS,KAAK,EACjBC,GAAG;IACN,MAAMC,SAAShB,yBACbQ,cAAcS,MAAM,IAAIT,sBAAAA,cAAcU,IAAI,cAAlBV,sBAAwB,OAAQ;IAE1D,MAAMW,SAA+B;QACnCC,YAAY;QACZC,cAAc;QACdC,mBAAmB;IACrB;IACA,0EAA0E;IAC1E,+DAA+D;IAC/D,IAAI,CAACN,OAAOO,OAAO,IAAI,CAACP,OAAOQ,WAAW,IAAI,CAACR,OAAOS,IAAI,EAAE;QAC1D,OAAON;IACT;IAEA,wEAAwE;IACxE,6CAA6C;IAC7C,IAAIH,OAAOS,IAAI,EAAE;;QACf,MAAMA,OAAOjB,cAAcO,GAAG,CAAC;QAI/B,MAAMW,QAAQnB,KAAKoB,KAAK,CAACC,eAAOH,wBAAAA,KAAMC,KAAK,mBAAI;QAC/C,MAAMG,eAAeC,OAAOC,QAAQ,CAACL,SACjCM,KAAKC,GAAG,CAAC,GAAG3B,IAAI4B,OAAO,KAAKR,SAC5BI,OAAOK,gBAAgB;QAC3B,MAAMf,aAAa,MAAMtB,yBAAyBW,WAAW;YAC3DI,OAAOR,QAAQQ,KAAK;YACpBC,OAAOT,QAAQS,KAAK;YACpBsB,UAAUpB,OAAOS,IAAI,CAACW,QAAQ;YAC9BP;QACF;QACA,IAAIT,WAAWiB,QAAQ,EAAElB,OAAOC,UAAU,GAAG;IAC/C;IAEA,oBAAoB;IACpB,MAAMkB,SAAS,MAAMzC,kBAAkBY,WAAW;QAChDI,OAAOR,QAAQQ,KAAK;QACpB0B,KAAKlC,QAAQkC,GAAG;QAChBzB,OAAOT,QAAQS,KAAK;QACpB0B,kBAAkBnC,QAAQmC,gBAAgB;QAC1ClC;IACF;IACA,IAAIgC,OAAOG,OAAO,EAAE;YAGSC;QAF3B,MAAMA,QAAQ,MAAMhC,OAAOC,UAAU,CAAC,eAAeC,GAAG,CAACP,QAAQS,KAAK,EAAEC,GAAG;QAC3EI,OAAOE,YAAY,GACjBrB,0BAAyB0C,cAAAA,MAAMxB,IAAI,cAAVwB,cAAgB,MAAMlB,WAAW,GAAGR,OAAOQ,WAAW;IACnF;IAEA,0EAA0E;IAC1E,+BAA+B;IAC/B,IAAI,MAAMmB,yBAAyBjC,QAAQL,QAAQS,KAAK,GAAG;QACzD,MAAMb,6BAA6BQ,WAAWJ,QAAQQ,KAAK,EAAER,QAAQS,KAAK;QAC1EK,OAAOG,iBAAiB,GAAG;IAC7B;IACA,OAAOH;AACT;AAEA;;;;;;;;CAQC,GACD,eAAewB,yBACbjC,MAA2C,EAC3CI,KAAa;IAEb,MAAMS,UAAU,MAAMb,OACnBC,UAAU,CAACZ,kCACX6C,KAAK,CAAC,SAAS,MAAM9B,OACrB+B,KAAK,CAAC1C,aACNY,GAAG;IACN,OAAOQ,QAAQuB,IAAI,CAACC,IAAI,CAAC,CAACnC;YACsBA;eAA9C;YAAC;YAAW;YAAQ;SAAS,CAACoC,QAAQ,CAACpB,QAAOhB,WAAAA,IAAIG,GAAG,CAAC,qBAARH,WAAqB;;AAEvE"}

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

@@ -0,0 +1,63 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare const AI_OVERAGE_METER_LINE_ID = "assist-overage";
+/** The environment variable that starts mid-period charging. */
+export declare const AI_OVERAGE_INVOICED_FROM_ENV = "AI_OVERAGE_INVOICED_FROM";
+/**
+ * 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 declare function aiOverageInvoicedFrom(): string | 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 declare function aiOverageBillsByInvoice(month: string): boolean;
+/**
+ * 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 declare function aiOverageGuardsApply(month: string): boolean;
+/**
+ * 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 declare function registerAiOverageMeteredLine(): void;