@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/server/ai-admin-overage.js

@@ -0,0 +1,246 @@
+/**
+ * @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 { pluginRequestFromWeb } from "@aglyn/aglyn/server";
+import { emailUnverifiedResponse, firebaseAdmin, isImpersonationSession } from "@aglyn/tenant-data-admin";
+import { recordAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit";
+import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { assistUsageMonth } from "../usage/assist-usage.js";
+import { AI_BILLING_STANDING_DOC, AI_BILLING_SUBCOLLECTION, AI_OVERAGE_CHARGES_SUBCOLLECTION, readAiOverageMonthLedger } from "../billing/ai-overage-ledger.js";
+import { AI_OVERAGE_CEILING_LADDER_USD, AI_OVERAGE_STAFF_CEILING_MAX_USD, AI_OVERAGE_STAFF_CEILING_MIN_USD, AI_OVERAGE_THRESHOLD_USD, AI_OVERAGE_UNPAID_LIMIT_USD, aiOverageCardOnFile, aiOverageEffectiveCeilingUsd, aiOverageStandingCeilingUsd, aiOverageStep, readAiOverageStanding } from "../billing/ai-overage-standing.js";
+import { resetAiOverageStep, resumeAiOverage, setAiOverageStaffOverride } from "../billing/ai-overage-standing-writes.js";
+import { aiOverageBillsByInvoice } from "../billing/ai-overage-cutover.js";
+/**
+ * STAFF'S CONTROLS OVER ONE WORKSPACE'S OVERAGE STANDING (AGL-3011).
+ *
+ * The ladder rises on payment history and a dispute takes it back to the
+ * bottom. Both are rules, and a rule that nobody can override is a rule that
+ * strands the customer it gets wrong: an enterprise-shaped workspace on its
+ * first month, a dispute that turns out to be fraud on the cardholder rather
+ * than by them, a failed charge whose cause was ours.
+ *
+ * So four acts, staff-only, every one of them audited:
+ *
+ *   `get`           the standing in full, with the month's charges
+ *   `setCeiling`    a ceiling that outranks the ladder, with a reason and an
+ *                   optional expiry
+ *   `liftPause`     resume accrual, with a reason — the ONLY way a dispute
+ *                   pause comes off
+ *   `resetStep`     put the workspace back at the bottom of the ladder
+ *
+ * A reason is required on every act that changes something, because the
+ * question a month later is never "what was the ceiling" — the document says
+ * that — but "why did someone raise it".
+ *
+ * The emergency stop is not here and does not change: Lockdown, scoped to
+ * the organization, which stops AI along with everything else.
+ */ /** How many of the month's charge rows the card lists. */ const CHARGES_LISTED = 20;
+/** The longest a staff reason may be, so a paste cannot fill the document. */ const REASON_MAX = 500;
+function badRequest(error, code) {
+    return Response.json({
+        error,
+        code
+    }, {
+        status: 400
+    });
+}
+async function handler(request) {
+    var _headers_authorization, _ref, _ref1;
+    const { method, body, headers: rawHeaders } = await pluginRequestFromWeb(request);
+    const headers = rawHeaders;
+    if (method !== 'POST') {
+        return Response.json({
+            error: 'Method not allowed'
+        }, {
+            status: 405
+        });
+    }
+    const authorization = (_headers_authorization = headers.authorization) != null ? _headers_authorization : '';
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return Response.json({
+        error: 'Unauthenticated'
+    }, {
+        status: 401
+    });
+    const orgId = String((_ref = body == null ? void 0 : body.orgId) != null ? _ref : '');
+    const action = String((_ref1 = body == null ? void 0 : body.action) != null ? _ref1 : '');
+    const actions = [
+        'get',
+        'setCeiling',
+        'liftPause',
+        'resetStep'
+    ];
+    if (!orgId || !actions.includes(action)) {
+        return Response.json({
+            error: 'Bad request'
+        }, {
+            status: 400
+        });
+    }
+    try {
+        var _orgSnapshot_data, _ref2, _standingSnapshot_data, _usageSnapshot_data, _standing_paymentMethodType, _aiOverageCardOnFile;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        if (!decoded.email_verified && !isImpersonationSession(decoded)) {
+            return emailUnverifiedResponse();
+        }
+        // The staff claim, the same test `ai/admin/org` makes. Not a permission
+        // on the workspace: these controls are Aglyn's side of the relationship,
+        // and a workspace admin raising their own ceiling is the thing the
+        // ladder exists to prevent.
+        if (!decoded['staff']) {
+            return Response.json({
+                error: 'Staff only'
+            }, {
+                status: 403
+            });
+        }
+        const now = new Date();
+        const month = assistUsageMonth(now);
+        const db = firebaseAdmin.app().firestore();
+        const orgRef = db.collection('orgs').doc(orgId);
+        const orgSnapshot = await orgRef.get();
+        if (!orgSnapshot.exists) {
+            return Response.json({
+                error: 'No such organization'
+            }, {
+                status: 404
+            });
+        }
+        const org = (_orgSnapshot_data = orgSnapshot.data()) != null ? _orgSnapshot_data : {};
+        const reason = String((_ref2 = body == null ? void 0 : body.reason) != null ? _ref2 : '').trim().slice(0, REASON_MAX);
+        if (action === 'setCeiling') {
+            const clearing = (body == null ? void 0 : body.ceilingUsd) === null;
+            const ceilingUsd = Number(body == null ? void 0 : body.ceilingUsd);
+            if (!reason) {
+                return badRequest('Say why the ceiling is being changed', 'reason_required');
+            }
+            if (!clearing && (!Number.isFinite(ceilingUsd) || ceilingUsd < AI_OVERAGE_STAFF_CEILING_MIN_USD || ceilingUsd > AI_OVERAGE_STAFF_CEILING_MAX_USD)) {
+                return badRequest(`Set a ceiling between $${AI_OVERAGE_STAFF_CEILING_MIN_USD} and ` + `$${AI_OVERAGE_STAFF_CEILING_MAX_USD.toLocaleString('en-US')}, or clear it.`, 'invalid_ceiling');
+            }
+            // An expiry that does not parse is refused rather than dropped: a
+            // ceiling meant to last a week and stored with no end is the failure
+            // this field exists to avoid.
+            const rawExpiry = body == null ? void 0 : body.expiresAt;
+            const expiresAt = rawExpiry === null || rawExpiry === undefined ? null : String(rawExpiry);
+            if (expiresAt !== null && !Number.isFinite(Date.parse(expiresAt))) {
+                return badRequest('The expiry is not a date', 'invalid_expiry');
+            }
+            await setAiOverageStaffOverride(db, orgId, clearing ? null : {
+                ceilingUsd,
+                reason,
+                setBy: decoded.uid,
+                expiresAt
+            }, now);
+            await recordAdminAudit({
+                actorUid: decoded.uid,
+                action: clearing ? 'ai.overage.clearCeiling' : 'ai.overage.setCeiling',
+                target: `orgs/${orgId}/${AI_BILLING_SUBCOLLECTION}/${AI_BILLING_STANDING_DOC}`,
+                note: clearing ? reason : `${reason} — ceiling $${ceilingUsd}${expiresAt ? `, until ${expiresAt}` : ''}`
+            });
+        }
+        if (action === 'liftPause') {
+            if (!reason) {
+                return badRequest('Say why the pause is being lifted', 'reason_required');
+            }
+            // `force`, because staff lifting a pause is the one path a DISPUTE
+            // pause has out. Every other pause lifts on its own when the payment
+            // that set it succeeds.
+            await resumeAiOverage(db, orgId, {
+                force: true
+            });
+            await recordAdminAudit({
+                actorUid: decoded.uid,
+                action: 'ai.overage.liftPause',
+                target: `orgs/${orgId}/${AI_BILLING_SUBCOLLECTION}/${AI_BILLING_STANDING_DOC}`,
+                note: reason
+            });
+        }
+        if (action === 'resetStep') {
+            if (!reason) {
+                return badRequest('Say why the step is being reset', 'reason_required');
+            }
+            await resetAiOverageStep(db, orgId);
+            await recordAdminAudit({
+                actorUid: decoded.uid,
+                action: 'ai.overage.resetStep',
+                target: `orgs/${orgId}/${AI_BILLING_SUBCOLLECTION}/${AI_BILLING_STANDING_DOC}`,
+                note: reason
+            });
+        }
+        // Read AFTER any write, so the answer is the state the act produced
+        // rather than the state it found — a staff card that showed the old
+        // ceiling after raising it would be read as the raise having failed.
+        const [standingSnapshot, usageSnapshot, chargesSnapshot] = await Promise.all([
+            orgRef.collection(AI_BILLING_SUBCOLLECTION).doc(AI_BILLING_STANDING_DOC).get(),
+            orgRef.collection('assistUsage').doc(month).get(),
+            orgRef.collection(AI_OVERAGE_CHARGES_SUBCOLLECTION).where('month', '==', month).limit(CHARGES_LISTED).get()
+        ]);
+        const standing = readAiOverageStanding(standingSnapshot.exists ? (_standingSnapshot_data = standingSnapshot.data()) != null ? _standingSnapshot_data : null : null);
+        const ledger = readAiOverageMonthLedger(usageSnapshot.exists ? (_usageSnapshot_data = usageSnapshot.data()) != null ? _usageSnapshot_data : null : null);
+        return Response.json({
+            month,
+            // Whether any of this is live yet. Staff looking at a standing that
+            // nothing consults should be told so rather than left to infer it
+            // from a ceiling that never refuses.
+            billsByInvoice: aiOverageBillsByInvoice(month),
+            standing: {
+                paymentMethodType: (_standing_paymentMethodType = standing.paymentMethodType) != null ? _standing_paymentMethodType : null,
+                cardOnFile: (_aiOverageCardOnFile = aiOverageCardOnFile(standing)) != null ? _aiOverageCardOnFile : null,
+                firstPaidMonth: standing.firstPaidMonth,
+                qualifyingMonths: standing.qualifyingMonths,
+                step: aiOverageStep(standing),
+                staffOverride: standing.staffOverride,
+                pause: standing.pause,
+                lastDisputeAt: standing.lastDisputeAt
+            },
+            ceiling: {
+                ladderUsd: [
+                    ...AI_OVERAGE_CEILING_LADDER_USD
+                ],
+                standingUsd: aiOverageStandingCeilingUsd(standing, now),
+                effectiveUsd: aiOverageEffectiveCeilingUsd(org, standing, now),
+                thresholdUsd: AI_OVERAGE_THRESHOLD_USD,
+                unpaidLimitUsd: AI_OVERAGE_UNPAID_LIMIT_USD
+            },
+            ledger,
+            charges: chargesSnapshot.docs.map((doc)=>{
+                var _doc_get, _doc_get1, _doc_get2, _doc_get3, _doc_get4;
+                return {
+                    chargeId: doc.id,
+                    kind: (_doc_get = doc.get('kind')) != null ? _doc_get : null,
+                    amountUsd: Number((_doc_get1 = doc.get('amountUsd')) != null ? _doc_get1 : 0),
+                    credits: Number((_doc_get2 = doc.get('credits')) != null ? _doc_get2 : 0),
+                    invoiceId: (_doc_get3 = doc.get('invoiceId')) != null ? _doc_get3 : null,
+                    status: (_doc_get4 = doc.get('status')) != null ? _doc_get4 : null
+                };
+            })
+        }, {
+            status: 200
+        });
+    } catch (error) {
+        const unauthenticated = invalidIdTokenResponse(error);
+        if (unauthenticated) return unauthenticated;
+        console.error(error);
+        return Response.json({
+            error: 'AI overage standing failed'
+        }, {
+            status: 500
+        });
+    }
+}
+export const dynamic = 'force-dynamic';
+export { handler as POST };
+
+//# sourceMappingURL=ai-admin-overage.js.map

package/src/lib/server/ai-admin-overage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-admin-overage.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { pluginRequestFromWeb } from '@aglyn/aglyn/server'\nimport {\n  emailUnverifiedResponse,\n  firebaseAdmin,\n  isImpersonationSession,\n} from '@aglyn/tenant-data-admin'\nimport { recordAdminAudit } from '@aglyn/tenant-data-admin/server/admin-audit'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport { assistUsageMonth } from '../usage/assist-usage'\nimport {\n  AI_BILLING_STANDING_DOC,\n  AI_BILLING_SUBCOLLECTION,\n  AI_OVERAGE_CHARGES_SUBCOLLECTION,\n  readAiOverageMonthLedger,\n} from '../billing/ai-overage-ledger'\nimport {\n  AI_OVERAGE_CEILING_LADDER_USD,\n  AI_OVERAGE_STAFF_CEILING_MAX_USD,\n  AI_OVERAGE_STAFF_CEILING_MIN_USD,\n  AI_OVERAGE_THRESHOLD_USD,\n  AI_OVERAGE_UNPAID_LIMIT_USD,\n  aiOverageCardOnFile,\n  aiOverageEffectiveCeilingUsd,\n  aiOverageStandingCeilingUsd,\n  aiOverageStep,\n  readAiOverageStanding,\n} from '../billing/ai-overage-standing'\nimport {\n  resetAiOverageStep,\n  resumeAiOverage,\n  setAiOverageStaffOverride,\n} from '../billing/ai-overage-standing-writes'\nimport { aiOverageBillsByInvoice } from '../billing/ai-overage-cutover'\n\n/**\n * STAFF'S CONTROLS OVER ONE WORKSPACE'S OVERAGE STANDING (AGL-3011).\n *\n * The ladder rises on payment history and a dispute takes it back to the\n * bottom. Both are rules, and a rule that nobody can override is a rule that\n * strands the customer it gets wrong: an enterprise-shaped workspace on its\n * first month, a dispute that turns out to be fraud on the cardholder rather\n * than by them, a failed charge whose cause was ours.\n *\n * So four acts, staff-only, every one of them audited:\n *\n *   `get`           the standing in full, with the month's charges\n *   `setCeiling`    a ceiling that outranks the ladder, with a reason and an\n *                   optional expiry\n *   `liftPause`     resume accrual, with a reason — the ONLY way a dispute\n *                   pause comes off\n *   `resetStep`     put the workspace back at the bottom of the ladder\n *\n * A reason is required on every act that changes something, because the\n * question a month later is never \"what was the ceiling\" — the document says\n * that — but \"why did someone raise it\".\n *\n * The emergency stop is not here and does not change: Lockdown, scoped to\n * the organization, which stops AI along with everything else.\n */\n\n/** How many of the month's charge rows the card lists. */\nconst CHARGES_LISTED = 20\n\n/** The longest a staff reason may be, so a paste cannot fill the document. */\nconst REASON_MAX = 500\n\nfunction badRequest(error: string, code: string): Response {\n  return Response.json({ error, code }, { status: 400 })\n}\n\nasync function handler(request: Request): Promise<Response> {\n  const { method, body, headers: rawHeaders } = await pluginRequestFromWeb(request)\n  const headers = rawHeaders as Partial<Record<string, string>>\n  if (method !== 'POST') {\n    return Response.json({ error: 'Method not allowed' }, { status: 405 })\n  }\n  const authorization = headers.authorization ?? ''\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return Response.json({ error: 'Unauthenticated' }, { status: 401 })\n  const orgId = String(body?.orgId ?? '')\n  const action = String(body?.action ?? '')\n  const actions = ['get', 'setCeiling', 'liftPause', 'resetStep']\n  if (!orgId || !actions.includes(action)) {\n    return Response.json({ error: 'Bad request' }, { status: 400 })\n  }\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    if (!decoded.email_verified && !isImpersonationSession(decoded)) {\n      return emailUnverifiedResponse()\n    }\n    // The staff claim, the same test `ai/admin/org` makes. Not a permission\n    // on the workspace: these controls are Aglyn's side of the relationship,\n    // and a workspace admin raising their own ceiling is the thing the\n    // ladder exists to prevent.\n    if (!decoded['staff']) {\n      return Response.json({ error: 'Staff only' }, { status: 403 })\n    }\n\n    const now = new Date()\n    const month = assistUsageMonth(now)\n    const db = firebaseAdmin.app().firestore()\n    const orgRef = db.collection('orgs').doc(orgId)\n    const orgSnapshot = await orgRef.get()\n    if (!orgSnapshot.exists) {\n      return Response.json({ error: 'No such organization' }, { status: 404 })\n    }\n    const org = (orgSnapshot.data() ?? {}) as Record<string, unknown>\n    const reason = String(body?.reason ?? '').trim().slice(0, REASON_MAX)\n\n    if (action === 'setCeiling') {\n      const clearing = body?.ceilingUsd === null\n      const ceilingUsd = Number(body?.ceilingUsd)\n      if (!reason) {\n        return badRequest('Say why the ceiling is being changed', 'reason_required')\n      }\n      if (\n        !clearing &&\n        (!Number.isFinite(ceilingUsd) ||\n          ceilingUsd < AI_OVERAGE_STAFF_CEILING_MIN_USD ||\n          ceilingUsd > AI_OVERAGE_STAFF_CEILING_MAX_USD)\n      ) {\n        return badRequest(\n          `Set a ceiling between $${AI_OVERAGE_STAFF_CEILING_MIN_USD} and ` +\n            `$${AI_OVERAGE_STAFF_CEILING_MAX_USD.toLocaleString('en-US')}, or clear it.`,\n          'invalid_ceiling',\n        )\n      }\n      // An expiry that does not parse is refused rather than dropped: a\n      // ceiling meant to last a week and stored with no end is the failure\n      // this field exists to avoid.\n      const rawExpiry = body?.expiresAt\n      const expiresAt =\n        rawExpiry === null || rawExpiry === undefined ? null : String(rawExpiry)\n      if (expiresAt !== null && !Number.isFinite(Date.parse(expiresAt))) {\n        return badRequest('The expiry is not a date', 'invalid_expiry')\n      }\n      await setAiOverageStaffOverride(\n        db,\n        orgId,\n        clearing\n          ? null\n          : { ceilingUsd, reason, setBy: decoded.uid, expiresAt },\n        now,\n      )\n      await recordAdminAudit({\n        actorUid: decoded.uid,\n        action: clearing\n          ? 'ai.overage.clearCeiling'\n          : 'ai.overage.setCeiling',\n        target: `orgs/${orgId}/${AI_BILLING_SUBCOLLECTION}/${AI_BILLING_STANDING_DOC}`,\n        note: clearing\n          ? reason\n          : `${reason} — ceiling $${ceilingUsd}${expiresAt ? `, until ${expiresAt}` : ''}`,\n      })\n    }\n\n    if (action === 'liftPause') {\n      if (!reason) {\n        return badRequest('Say why the pause is being lifted', 'reason_required')\n      }\n      // `force`, because staff lifting a pause is the one path a DISPUTE\n      // pause has out. Every other pause lifts on its own when the payment\n      // that set it succeeds.\n      await resumeAiOverage(db, orgId, { force: true })\n      await recordAdminAudit({\n        actorUid: decoded.uid,\n        action: 'ai.overage.liftPause',\n        target: `orgs/${orgId}/${AI_BILLING_SUBCOLLECTION}/${AI_BILLING_STANDING_DOC}`,\n        note: reason,\n      })\n    }\n\n    if (action === 'resetStep') {\n      if (!reason) {\n        return badRequest('Say why the step is being reset', 'reason_required')\n      }\n      await resetAiOverageStep(db, orgId)\n      await recordAdminAudit({\n        actorUid: decoded.uid,\n        action: 'ai.overage.resetStep',\n        target: `orgs/${orgId}/${AI_BILLING_SUBCOLLECTION}/${AI_BILLING_STANDING_DOC}`,\n        note: reason,\n      })\n    }\n\n    // Read AFTER any write, so the answer is the state the act produced\n    // rather than the state it found — a staff card that showed the old\n    // ceiling after raising it would be read as the raise having failed.\n    const [standingSnapshot, usageSnapshot, chargesSnapshot] = await Promise.all([\n      orgRef.collection(AI_BILLING_SUBCOLLECTION).doc(AI_BILLING_STANDING_DOC).get(),\n      orgRef.collection('assistUsage').doc(month).get(),\n      orgRef\n        .collection(AI_OVERAGE_CHARGES_SUBCOLLECTION)\n        .where('month', '==', month)\n        .limit(CHARGES_LISTED)\n        .get(),\n    ])\n    const standing = readAiOverageStanding(\n      standingSnapshot.exists ? (standingSnapshot.data() ?? null) : null,\n    )\n    const ledger = readAiOverageMonthLedger(\n      usageSnapshot.exists ? (usageSnapshot.data() ?? null) : null,\n    )\n    return Response.json(\n      {\n        month,\n        // Whether any of this is live yet. Staff looking at a standing that\n        // nothing consults should be told so rather than left to infer it\n        // from a ceiling that never refuses.\n        billsByInvoice: aiOverageBillsByInvoice(month),\n        standing: {\n          paymentMethodType: standing.paymentMethodType ?? null,\n          cardOnFile: aiOverageCardOnFile(standing) ?? null,\n          firstPaidMonth: standing.firstPaidMonth,\n          qualifyingMonths: standing.qualifyingMonths,\n          step: aiOverageStep(standing),\n          staffOverride: standing.staffOverride,\n          pause: standing.pause,\n          lastDisputeAt: standing.lastDisputeAt,\n        },\n        ceiling: {\n          ladderUsd: [...AI_OVERAGE_CEILING_LADDER_USD],\n          standingUsd: aiOverageStandingCeilingUsd(standing, now),\n          effectiveUsd: aiOverageEffectiveCeilingUsd(org as never, standing, now),\n          thresholdUsd: AI_OVERAGE_THRESHOLD_USD,\n          unpaidLimitUsd: AI_OVERAGE_UNPAID_LIMIT_USD,\n        },\n        ledger,\n        charges: chargesSnapshot.docs.map((doc) => ({\n          chargeId: doc.id,\n          kind: doc.get('kind') ?? null,\n          amountUsd: Number(doc.get('amountUsd') ?? 0),\n          credits: Number(doc.get('credits') ?? 0),\n          invoiceId: doc.get('invoiceId') ?? null,\n          status: doc.get('status') ?? null,\n        })),\n      },\n      { status: 200 },\n    )\n  } catch (error) {\n    const unauthenticated = invalidIdTokenResponse(error)\n    if (unauthenticated) return unauthenticated\n    console.error(error)\n    return Response.json({ error: 'AI overage standing failed' }, { status: 500 })\n  }\n}\n\nexport const dynamic = 'force-dynamic'\nexport { handler as POST }\n"],"names":["pluginRequestFromWeb","emailUnverifiedResponse","firebaseAdmin","isImpersonationSession","recordAdminAudit","invalidIdTokenResponse","assistUsageMonth","AI_BILLING_STANDING_DOC","AI_BILLING_SUBCOLLECTION","AI_OVERAGE_CHARGES_SUBCOLLECTION","readAiOverageMonthLedger","AI_OVERAGE_CEILING_LADDER_USD","AI_OVERAGE_STAFF_CEILING_MAX_USD","AI_OVERAGE_STAFF_CEILING_MIN_USD","AI_OVERAGE_THRESHOLD_USD","AI_OVERAGE_UNPAID_LIMIT_USD","aiOverageCardOnFile","aiOverageEffectiveCeilingUsd","aiOverageStandingCeilingUsd","aiOverageStep","readAiOverageStanding","resetAiOverageStep","resumeAiOverage","setAiOverageStaffOverride","aiOverageBillsByInvoice","CHARGES_LISTED","REASON_MAX","badRequest","error","code","Response","json","status","handler","request","headers","method","body","rawHeaders","authorization","idToken","startsWith","slice","length","undefined","orgId","String","action","actions","includes","orgSnapshot","standingSnapshot","usageSnapshot","standing","decoded","app","auth","verifyIdToken","email_verified","now","Date","month","db","firestore","orgRef","collection","doc","get","exists","org","data","reason","trim","clearing","ceilingUsd","Number","isFinite","toLocaleString","rawExpiry","expiresAt","parse","setBy","uid","actorUid","target","note","force","chargesSnapshot","Promise","all","where","limit","ledger","billsByInvoice","paymentMethodType","cardOnFile","firstPaidMonth","qualifyingMonths","step","staffOverride","pause","lastDisputeAt","ceiling","ladderUsd","standingUsd","effectiveUsd","thresholdUsd","unpaidLimitUsd","charges","docs","map","chargeId","id","kind","amountUsd","credits","invoiceId","unauthenticated","console","dynamic","POST"],"mappings":"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"}

package/src/lib/server/ai-admin-signals.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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 AssistSpendRow } from '../usage/assist-signal-mining';
+export interface AssistSpendLeaderboard {
+    month: string;
+    rows: AssistSpendRow[];
+    /** How many workspaces had a document for the month — the ranked count. */
+    ranked: number;
+    /** True when the scan hit its ceiling, so the ranking is over a sample. */
+    truncated: boolean;
+    /**
+     * True when the month documents could not be read at all. Reported rather
+     * than rendered as an empty table: "no workspace spent anything" and "the
+     * read failed" are opposite findings, and the rest of the board — read
+     * from a different collection — is still good.
+     */
+    failed: boolean;
+}
+declare function handler(request: Request): Promise<Response>;
+export { handler as GET };

package/src/lib/server/ai-admin-signals.js

@@ -0,0 +1,330 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { ORG_BILLING_DOC_ID, ORG_BILLING_SUBCOLLECTION, pluginRequestFromWeb } from "@aglyn/aglyn/server";
+import { emailUnverifiedResponse, firebaseAdmin, isImpersonationSession } from "@aglyn/tenant-data-admin";
+import { ASSIST_PROVIDER_COST_FIELD, assistCreditsFromUsd, assistProviderCostUsd } from "@aglyn/aglyn/app-utils/assist-credits";
+import { hasAiAddon, resolveEffectivePlan } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { readPlatformFreeSpend } from "../usage/assist-free-taste.js";
+import { assistRefusalCounts } from "../usage/assist-refusals.js";
+import { assistUsageDay, assistUsageMonth } from "../usage/assist-usage.js";
+import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { assistSignalRow, mineAssistSignals, rankAssistSpend } from "../usage/assist-signal-mining.js";
+/**
+ * The Assist docs-gap and cost mining view (AGL-1860, AGL-2252), served at
+ * `/api/ai/admin/signals` for the plugin's Assist signal staff page.
+ * Staff-gated, read-only, and the only reader `assistSignals` has.
+ *
+ * ## Why a route and not a client query
+ *
+ * `assistSignals` is absent from `firebase-firestore.rules` deliberately: the
+ * org block matches its subcollections BY NAME and carries no wildcard, so an
+ * unlisted name is default-deny for every client. That is the property that
+ * lets the collection hold cross-tenant analytics at all. Reading it therefore
+ * goes through the Admin SDK behind the staff claim, exactly as every staff
+ * route does.
+ *
+ * ## The collection group, and the index it does not need
+ *
+ * One `collectionGroup('assistSignals')` read gathers every org's signals in a
+ * single query; the owning org is `ref.parent.parent.id`, since the document
+ * carries no `orgId` field (it carries no identifiers at all — see AGL-1972).
+ * The query has no `where` and no `orderBy`, so it needs no composite index,
+ * and adding one later would mean declaring a `COLLECTION_GROUP`-scoped
+ * override and deploying it by hand. `/api/admin/overview` reads org billing
+ * the same way and for the same reason.
+ *
+ * ## Truncation is reported, never hidden
+ *
+ * The read is bounded — an unbounded fleet-wide get is how a staff page
+ * becomes an outage — but a ranking cut short looks exactly like a complete
+ * one, so the ceiling is fetched PLUS ONE and the extra row sets `truncated`.
+ * AGL-2220 is the standing example of the alternative: a sweep that stopped at
+ * 500 orgs and reported nothing about the rest, for as long as nobody counted.
+ */ /**
+ * Rows read in one pass. Each signal is a handful of scalars, so this is a
+ * few megabytes at the ceiling — large enough to be worth ranking, small
+ * enough that the honest answer to "is it all of them" is usually yes.
+ */ const SCAN_CEILING = 20000;
+/**
+ * How much of an answer the prose panel shows.
+ *
+ * Enough to judge whether the answer was wrong, short enough that twenty-five
+ * of them are still a page somebody reads.
+ */ const ANSWER_PREVIEW_CHARS = 600;
+/**
+ * Month documents read in one pass for the spend leaderboard (AGL-2930).
+ *
+ * `assistUsage` holds one document per org per month, so this is orgs times
+ * months — a fraction of the signal count, and the same PLUS-ONE truncation
+ * probe the signals read uses. Read as a collection group with NO `where`
+ * and NO `orderBy`, for the reason the module note gives: a filter on
+ * `month` would need a COLLECTION_GROUP-scoped index deployed by hand, and
+ * filtering the month in memory costs nothing at this size.
+ */ const SPEND_SCAN_CEILING = 20000;
+/**
+ * The month's per-org spend, refusals and plan, dearest first.
+ *
+ * Plan and add-on come from the org and billing documents of the ranked
+ * rows only — bounded by `limit`, never by the fleet — merged org-doc-first
+ * exactly as every other staff reader merges them.
+ */ async function readAssistSpendLeaderboard(firestore, limit, month) {
+    try {
+        return await rankAssistSpendForMonth(firestore, limit, month);
+    } catch (error) {
+        console.error('[ai/admin/signals] spend leaderboard read failed', error);
+        return {
+            month,
+            rows: [],
+            ranked: 0,
+            truncated: false,
+            failed: true
+        };
+    }
+}
+async function rankAssistSpendForMonth(firestore, limit, month) {
+    const snapshot = await firestore.collectionGroup('assistUsage').limit(SPEND_SCAN_CEILING + 1).get();
+    const truncated = snapshot.size > SPEND_SCAN_CEILING;
+    const docs = truncated ? snapshot.docs.slice(0, SPEND_SCAN_CEILING) : snapshot.docs;
+    const unranked = [];
+    for (const doc of docs){
+        var _doc_get;
+        var _doc_ref_parent_parent;
+        // The id IS the month; the field is the same value and is what an
+        // older document may lack.
+        if (doc.id !== month && doc.get('month') !== month) continue;
+        const orgId = (_doc_ref_parent_parent = doc.ref.parent.parent) == null ? void 0 : _doc_ref_parent_parent.id;
+        if (!orgId) continue;
+        // Two figures off one document (AGL-3015): the credits a workspace drew
+        // come from what it was BILLED, and the dollars staff rank workspaces by
+        // come from what it COST US. Ranking on the billed figure would sort the
+        // fleet by our own markup wherever workspaces differ in model mix.
+        const billed = Number((_doc_get = doc.get('estCostUsd')) != null ? _doc_get : 0);
+        const billedUsd = Number.isFinite(billed) && billed > 0 ? billed : 0;
+        unranked.push({
+            orgId,
+            plan: 'free',
+            aiAddon: false,
+            credits: assistCreditsFromUsd(billedUsd),
+            providerCostUsd: assistProviderCostUsd(billedUsd, doc.get(ASSIST_PROVIDER_COST_FIELD)),
+            refusals: assistRefusalCounts(doc.get('refusals'))
+        });
+    }
+    const { rows, ranked } = rankAssistSpend(unranked, limit);
+    if (rows.length) {
+        const orgRefs = rows.map((row)=>firestore.collection('orgs').doc(row.orgId));
+        const [orgSnaps, billingSnaps] = await Promise.all([
+            firestore.getAll(...orgRefs),
+            firestore.getAll(...orgRefs.map((ref)=>ref.collection(ORG_BILLING_SUBCOLLECTION).doc(ORG_BILLING_DOC_ID)))
+        ]);
+        rows.forEach((row, index)=>{
+            var _orgSnaps_index_data, _ref, _orgData_name;
+            var _orgSnaps_index, _billingSnaps_index;
+            const orgData = ((_orgSnaps_index = orgSnaps[index]) == null ? void 0 : _orgSnaps_index.exists) ? (_orgSnaps_index_data = orgSnaps[index].data()) != null ? _orgSnaps_index_data : {} : {};
+            const org = _extends({}, orgData, ((_billingSnaps_index = billingSnaps[index]) == null ? void 0 : _billingSnaps_index.exists) ? billingSnaps[index].data() : {});
+            row.plan = resolveEffectivePlan(org);
+            row.aiAddon = hasAiAddon(org);
+            const label = (_ref = (_orgData_name = orgData['name']) != null ? _orgData_name : orgData['slug']) != null ? _ref : '';
+            row.orgLabel = label || null;
+        });
+    }
+    return {
+        month,
+        rows,
+        ranked,
+        truncated,
+        failed: false
+    };
+}
+async function handler(request) {
+    var _headers_authorization;
+    const { method, query, headers: rawHeaders } = await pluginRequestFromWeb(request);
+    const headers = rawHeaders;
+    if (method !== 'GET') {
+        return Response.json({
+            error: 'Method not allowed'
+        }, {
+            status: 405
+        });
+    }
+    const authorization = (_headers_authorization = headers.authorization) != null ? _headers_authorization : '';
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return Response.json({
+        error: 'Unauthenticated'
+    }, {
+        status: 401
+    });
+    try {
+        var _query_limit;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        if (!decoded.email_verified && !isImpersonationSession(decoded)) {
+            return emailUnverifiedResponse();
+        }
+        if (!decoded['staff']) {
+            return Response.json({
+                error: 'Staff only'
+            }, {
+                status: 403
+            });
+        }
+        const requested = Number((_query_limit = query.limit) != null ? _query_limit : 25);
+        const limit = Number.isFinite(requested) && requested > 0 ? Math.min(Math.floor(requested), 100) : 25;
+        const snapshot = await firebaseAdmin.app().firestore().collectionGroup('assistSignals')// Ceiling PLUS ONE: the extra document is what makes truncation
+        // detectable rather than assumed.
+        .limit(SCAN_CEILING + 1).get();
+        const truncated = snapshot.size > SCAN_CEILING;
+        const docs = truncated ? snapshot.docs.slice(0, SCAN_CEILING) : snapshot.docs;
+        const rows = docs.map((doc)=>{
+            var _ref;
+            var _doc_ref_parent_parent;
+            return assistSignalRow((_ref = (_doc_ref_parent_parent = doc.ref.parent.parent) == null ? void 0 : _doc_ref_parent_parent.id) != null ? _ref : '(unknown)', // The signal id IS the exchange id (AGL-2314) — one id, two halves,
+            // minted together by `recordAssistExchange` precisely so the join is
+            // possible. Until now nothing carried it this far.
+            doc.id, doc.data());
+        });
+        const report = mineAssistSignals(rows, {
+            truncated,
+            limit
+        });
+        // This month's spend, per workspace (AGL-2930) — the board's only
+        // month-scoped panel, read off the month documents rather than mined
+        // from the all-time signals above.
+        const spend = await readAssistSpendLeaderboard(firebaseAdmin.app().firestore(), limit, assistUsageMonth());
+        /*==========================================
+     * THE VERBATIM HALF (AGL-2314).
+     *
+     * `assistExchanges` stores the question a customer typed and the answer
+     * we gave, for 180 days, and `assist-usage.ts` calls it "the data loop's
+     * corpus". NOTHING read it — one write, no reader, no collection group.
+     * So we retained customers' words, and committed publicly in the privacy
+     * policy to retaining them, for zero product value.
+     *
+     * Read here rather than in the miner because the miner is pure: it does
+     * the arithmetic, the route does the reading.
+     *
+     * ## Only the turns that FAILED
+     *
+     * The shortlist is thumbs-down and ungrounded turns only, capped by the
+     * same `limit` as every other panel. That is a privacy decision as much
+     * as a cost one: the counts already answer "how often", and the words are
+     * fetched only where the counts CANNOT say what went wrong. Pulling every
+     * exchange would be surveillance with a dashboard on it.
+     *
+     * `uid` is deliberately not projected. The corpus question is what people
+     * asked, never who asked it — and the exchange is the only document that
+     * still carries an identifier at all.
+     *
+     * ## An expired exchange is an ANSWER
+     *
+     * The 180-day TTL means a signal can outlive its prose, and it is meant
+     * to. A missing document therefore reports `expired: true` rather than
+     * being dropped: a shortlist silently shorter than the failure count it
+     * came from would read as "these are all the failures", which is the
+     * AGL-2220 shape.
+     *=========================================*/ const firestore = firebaseAdmin.app().firestore();
+        const exchanges = report.proseCandidates.length ? await firestore.getAll(...report.proseCandidates.map((candidate)=>firestore.collection('orgs').doc(candidate.orgId).collection('assistExchanges').doc(candidate.exchangeId))) : [];
+        const prose = report.proseCandidates.map((candidate, index)=>{
+            var _ref;
+            const snapshot = exchanges[index];
+            const data = (_ref = (snapshot == null ? void 0 : snapshot.exists) ? snapshot.data() : null) != null ? _ref : {};
+            return _extends({}, candidate, {
+                expired: !(snapshot == null ? void 0 : snapshot.exists),
+                question: typeof data['question'] === 'string' ? data['question'] : null,
+                // Trimmed, not omitted: judging whether an answer was wrong needs to
+                // see it, and a whole answer per row would make the panel unreadable.
+                answer: typeof data['answer'] === 'string' ? data['answer'].slice(0, ANSWER_PREVIEW_CHARS) : null,
+                answerTruncated: typeof data['answer'] === 'string' && data['answer'].length > ANSWER_PREVIEW_CHARS
+            });
+        });
+        /*==========================================
+     * THE WORKSPACE, BY NAME.
+     *
+     * A staff reader recognizes a customer by name, never by document id,
+     * and the cost board's own column header says "Workspace" over a column
+     * of generated ids. `/api/admin/overview` fixed the same shape by
+     * building a label map from a snapshot it already held; there is no such
+     * snapshot here — this route reads `assistSignals` and nothing else — so
+     * the labels are fetched, with the same `name` → `slug` → id precedence
+     * so one workspace cannot appear under two different labels on two
+     * screens.
+     *
+     * Bounded by what is actually RENDERED, not by the fleet. Both lists the
+     * ids come from are already sliced to `limit` (25 by default, 100 at the
+     * ceiling), so this is one `getAll` over at most a couple of hundred
+     * documents — and it reads the orgs the reader can see rather than
+     * scanning a collection to name a handful of rows.
+     *
+     * An org that has been deleted keeps its id rather than going blank: an
+     * unfamiliar id is still a lead a staff member can paste into the org
+     * search, and an empty cell is not.
+     *=========================================*/ const orgIds = [
+            ...new Set([
+                ...report.orgs.map((row)=>row.orgId),
+                ...report.proseCandidates.map((row)=>row.orgId)
+            ].filter((orgId)=>orgId && orgId !== '(unknown)'))
+        ];
+        const orgLabelById = new Map();
+        if (orgIds.length) {
+            const orgDocs = await firestore.getAll(...orgIds.map((orgId)=>firestore.collection('orgs').doc(orgId)));
+            for (const doc of orgDocs){
+                var _doc_data, _ref, _data_name;
+                if (!doc.exists) continue;
+                const data = (_doc_data = doc.data()) != null ? _doc_data : {};
+                const label = (_ref = (_data_name = data['name']) != null ? _data_name : data['slug']) != null ? _ref : '';
+                if (label) orgLabelById.set(doc.id, label);
+            }
+        }
+        const orgLabel = (orgId)=>{
+            var _orgLabelById_get;
+            return (_orgLabelById_get = orgLabelById.get(orgId)) != null ? _orgLabelById_get : orgId;
+        };
+        // Today's free-tier spend against the platform ceiling (AGL-2925): one
+        // document read, and the only place staff can see the taste switching
+        // itself off before the email arrives. Best-effort — a readout that
+        // cannot be read must not take the rest of the board down with it.
+        const freeSpend = await readPlatformFreeSpend(firestore, assistUsageDay()).catch((error)=>{
+            console.error('[ai/admin/signals] free spend readout failed', error);
+            return undefined;
+        });
+        return Response.json(_extends({}, report, {
+            freeSpend,
+            orgs: report.orgs.map((row)=>_extends({}, row, {
+                    orgLabel: orgLabel(row.orgId)
+                })),
+            prose: prose.map((row)=>_extends({}, row, {
+                    orgLabel: orgLabel(row.orgId)
+                })),
+            spend,
+            ceiling: SCAN_CEILING
+        }), {
+            status: 200
+        });
+    } catch (error) {
+        // An unverifiable credential is a 401, not a fault of ours
+        // (AGL-1993). Null for anything else, so a real failure keeps its 500.
+        const unauthenticated = invalidIdTokenResponse(error);
+        if (unauthenticated) return unauthenticated;
+        console.error('[ai/admin/signals]', error);
+        return Response.json({
+            error: 'Assist signal lookup failed'
+        }, {
+            status: 500
+        });
+    }
+}
+export { handler as GET };
+
+//# sourceMappingURL=ai-admin-signals.js.map