@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/usage/ai-usage-by-user.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @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 AiUsageByUserMonth, type AiUsageKind } from '../model/ai-usage-by-user';
+import type { AiUsage } from '../providers/contract';
+/**
+ * PER-USER AI USAGE (AGL-2928): the writer and the readers.
+ *
+ * One document per person per month, under the org they spent in:
+ *
+ *   orgs/{orgId}/aiUsageByUser/{uid}/months/{YYYY-MM}
+ *     { uid, month, credits, estCostUsd, requests, refusals,
+ *       tokens: { input, cached, cacheWrite, output },
+ *       byKind: { kind: credits }, byHost: { hostId: credits },
+ *       updatedAt, expiresAt }
+ *
+ * ## Written in the org rollup's own batch
+ *
+ * `recordUserAiUsage` takes the BATCH the org rollup is being written into
+ * and adds this document to it, so the two cannot disagree: a batch commits
+ * whole or not at all, and there is no path on which the workspace's month
+ * moves and the person's does not. Both assist entrypoints hand it the batch
+ * from inside `recordAssistCost` / `recordAssistExchange`, and the job
+ * runner meters through the first of those, so a generation step lands here
+ * with the job's kind and creator.
+ *
+ * ## No prose, no PII past the uid
+ *
+ * The exchange's verbatim half already expires at 180 days for the reason
+ * `assist-usage.ts` gives; this rollup is integers keyed by an id, and it
+ * is kept longer (`AI_USAGE_BY_USER_RETENTION_MONTHS`) because a workspace
+ * admin's question is month-over-month. It is still a document ABOUT a
+ * person, so it is readable only by the person and by members holding
+ * `billing.view` or `org.auditLog` (the rules, and every route that serves
+ * it), and an account erasure sweeps it (`eraseUserAiUsage`).
+ */
+/** What one metered request attributes to a person. */
+export interface RecordUserAiUsageInput {
+    /** The person who asked. No uid, no attribution — the write is skipped. */
+    uid: string | null | undefined;
+    /** The billing month the org rollup is being written into. */
+    month: string;
+    /** The request's measured provider spend, as the org rollup counts it. */
+    estCostUsd: number;
+    hostId: string | null | undefined;
+    kind: AiUsageKind;
+    /** The request's four token counts (AGL-2937), added to the month's `tokens`. */
+    usage?: AiUsage;
+}
+/**
+ * A request's four token counts as increments, under the names every rollup
+ * keeps them by (`model/ai-tokens.ts`).
+ */
+export declare function aiTokenIncrements(usage: AiUsage): Record<string, FirebaseFirestore.FieldValue>;
+export declare function userAiUsageMonthRef(orgRef: FirebaseFirestore.DocumentReference, uid: string, month: string): FirebaseFirestore.DocumentReference;
+/**
+ * Fold one request into a person's month, on the caller's batch.
+ *
+ * Returns whether anything was queued: a request with no uid (a meter that
+ * could not say who asked) attributes to nobody rather than to a placeholder
+ * id that would rank on every table. `set(…, { merge: true })`, never
+ * `update()`: the document does not exist before a person's first request
+ * of the month, and a merge into a map field adds the key rather than
+ * replacing the map.
+ */
+export declare function recordUserAiUsage(batch: FirebaseFirestore.WriteBatch, orgRef: FirebaseFirestore.DocumentReference, input: RecordUserAiUsageInput): boolean;
+/**
+ * The slice of a reservation a refusal is counted from: whether the gate
+ * admitted the request, and the billing month it decided in. Structural, so
+ * every door can hand over the reservation it already holds.
+ */
+export interface UserAiRefusalSource {
+    allowed: boolean;
+    monthKey: string;
+}
+/**
+ * Count a refused reservation against the person who asked — the per-person
+ * twin of `recordAssistRefusal`, and shaped the same way: fire-and-forget,
+ * off the refusal's await path, swallowing every error, because a refusal
+ * is the gate's cheap exit and a counter must not make it dearer than the
+ * thing it counts.
+ *
+ * Takes the whole reservation rather than a month so every door calls it
+ * the same way, once, right after reserving: an admitted reservation records
+ * nothing, so the call needs no branch of its own and cannot drift from the
+ * door's refusal branch. The month is the reservation's, not the clock's,
+ * because that is the month the org's own refusal was counted in.
+ */
+export declare function recordUserAiRefusal(firestore: FirebaseFirestore.Firestore, orgId: string, uid: string | null | undefined, reservation: UserAiRefusalSource): void;
+/** One roster row's month, with the person the roster names. */
+export interface OrgAiUsageByUserRow extends AiUsageByUserMonth {
+    /** The display name, else the email, else the uid — never blank. */
+    name: string;
+    email: string | null;
+    role: string | null;
+    /** This person's share of the org's measured spend, in `[0, 1]`. */
+    share: number;
+}
+export interface OrgAiUsageByUserMonth {
+    month: string;
+    /** The org rollup's spend for the month — the denominator of every share. */
+    orgEstCostUsd: number;
+    orgCredits: number;
+    /** Every current member with a document for the month, dearest first. */
+    rows: OrgAiUsageByUserRow[];
+}
+/**
+ * The month for every current member of the org, dearest first.
+ *
+ * Reads the ROSTER and then each member's month document by path, rather
+ * than a collection-group query over `months`: the roster is the join the
+ * table needs anyway (a uid is not a name), it is bounded by the seats the
+ * plan sells, and a path read rides no index that has to be deployed before
+ * a workspace can open its Usage page. A person who has left the org is not
+ * listed — the roster is the set of people the reader may see — and their
+ * documents expire on the retention window.
+ */
+export declare function readOrgAiUsageByUser(firestore: FirebaseFirestore.Firestore, orgId: string, month: string): Promise<OrgAiUsageByUserMonth>;
+/**
+ * One person's months in one org, newest first — the member card and the
+ * staff page. Ordered on the document id, which IS the month key and so
+ * needs no field every writer must remember.
+ */
+export declare function readUserAiUsageMonths(firestore: FirebaseFirestore.Firestore, orgId: string, uid: string, limit?: number): Promise<AiUsageByUserMonth[]>;
+export interface EraseUserAiUsageResult {
+    /** Orgs whose `aiUsageByUser/{uid}` subtree was deleted by path. */
+    orgs: number;
+    /**
+     * Month documents found by the collection-group sweep and deleted — the
+     * ones in orgs the person had already left. `null` when the sweep could
+     * not run (its index is not deployed), which is not zero.
+     */
+    sweptMonths: number | null;
+}
+/**
+ * Remove a person's usage documents on account erasure.
+ *
+ * Two passes, because the documents live under the ORG and are keyed by the
+ * uid: `recursiveDelete(users/{uid})` cannot see them, and neither can a
+ * walk of current memberships find the months left behind in an org the
+ * person was removed from. So every org the erasure knows of is deleted by
+ * path first — no index, cannot fail for want of one — and then a
+ * collection-group query on `uid` catches the rest. The second pass is
+ * reported as `null` rather than thrown when it cannot run: the erasure has
+ * a legal clock, and the by-path pass has already removed everything a
+ * current membership could reach.
+ */
+export declare function eraseUserAiUsage(firestore: FirebaseFirestore.Firestore, uid: string, orgIds: readonly string[]): Promise<EraseUserAiUsageResult>;

package/src/lib/usage/ai-usage-by-user.js

@@ -0,0 +1,211 @@
+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.
+ */ // Straight from the SDK, not the admin lib, for the reason `assist-usage.ts`
+// gives at its head: the statics need no app, and the admin lib would drag the
+// default-app initialization into every unit test that touches a counter.
+import { FieldPath, FieldValue } from "firebase-admin/firestore";
+import { AI_USAGE_BY_USER_COLLECTION, AI_USAGE_BY_USER_MONTHS_COLLECTION, AI_USAGE_BY_USER_RETENTION_MONTHS, aiUsageByUserExpiry, aiUsageByUserMonthFrom, aiUsageShare } from "../model/ai-usage-by-user.js";
+import { AI_USAGE_TOKENS_FIELD } from "../model/ai-tokens.js";
+import { assistCreditsFromUsd } from "@aglyn/aglyn/app-utils/assist-credits";
+/**
+ * A request's four token counts as increments, under the names every rollup
+ * keeps them by (`model/ai-tokens.ts`).
+ */ export function aiTokenIncrements(usage) {
+    const increment = FieldValue.increment;
+    return {
+        input: increment(usage.inputTokens),
+        cached: increment(usage.cacheReadTokens),
+        cacheWrite: increment(usage.cacheWriteTokens),
+        output: increment(usage.outputTokens)
+    };
+}
+export function userAiUsageMonthRef(orgRef, uid, month) {
+    return orgRef.collection(AI_USAGE_BY_USER_COLLECTION).doc(uid).collection(AI_USAGE_BY_USER_MONTHS_COLLECTION).doc(month);
+}
+/**
+ * Fold one request into a person's month, on the caller's batch.
+ *
+ * Returns whether anything was queued: a request with no uid (a meter that
+ * could not say who asked) attributes to nobody rather than to a placeholder
+ * id that would rank on every table. `set(…, { merge: true })`, never
+ * `update()`: the document does not exist before a person's first request
+ * of the month, and a merge into a map field adds the key rather than
+ * replacing the map.
+ */ export function recordUserAiUsage(batch, orgRef, input) {
+    var _input_uid, _input_hostId;
+    const uid = String((_input_uid = input.uid) != null ? _input_uid : '').trim();
+    if (!uid) return false;
+    const estCostUsd = Number.isFinite(input.estCostUsd) && input.estCostUsd > 0 ? input.estCostUsd : 0;
+    const credits = assistCreditsFromUsd(estCostUsd);
+    const increment = FieldValue.increment;
+    const hostId = String((_input_hostId = input.hostId) != null ? _input_hostId : '').trim();
+    batch.set(userAiUsageMonthRef(orgRef, uid, input.month), _extends({
+        uid,
+        month: input.month,
+        credits: increment(credits),
+        estCostUsd: increment(estCostUsd),
+        requests: increment(1)
+    }, input.usage ? {
+        [AI_USAGE_TOKENS_FIELD]: aiTokenIncrements(input.usage)
+    } : {}, {
+        byKind: {
+            [input.kind]: increment(credits)
+        }
+    }, hostId ? {
+        byHost: {
+            [hostId]: increment(credits)
+        }
+    } : {}, {
+        updatedAt: FieldValue.serverTimestamp(),
+        // The retention window, as a Timestamp the TTL policy can act on.
+        expiresAt: aiUsageByUserExpiry(input.month)
+    }), {
+        merge: true
+    });
+    return true;
+}
+/**
+ * Count a refused reservation against the person who asked — the per-person
+ * twin of `recordAssistRefusal`, and shaped the same way: fire-and-forget,
+ * off the refusal's await path, swallowing every error, because a refusal
+ * is the gate's cheap exit and a counter must not make it dearer than the
+ * thing it counts.
+ *
+ * Takes the whole reservation rather than a month so every door calls it
+ * the same way, once, right after reserving: an admitted reservation records
+ * nothing, so the call needs no branch of its own and cannot drift from the
+ * door's refusal branch. The month is the reservation's, not the clock's,
+ * because that is the month the org's own refusal was counted in.
+ */ export function recordUserAiRefusal(firestore, orgId, uid, reservation) {
+    if (reservation.allowed) return;
+    const subject = String(uid != null ? uid : '').trim();
+    if (!subject) return;
+    try {
+        const ref = userAiUsageMonthRef(firestore.collection('orgs').doc(orgId), subject, reservation.monthKey);
+        void Promise.resolve(ref.set({
+            uid: subject,
+            month: reservation.monthKey,
+            refusals: FieldValue.increment(1),
+            updatedAt: FieldValue.serverTimestamp(),
+            expiresAt: aiUsageByUserExpiry(reservation.monthKey)
+        }, {
+            merge: true
+        })).catch(()=>undefined);
+    } catch (unused) {
+    // A double without `set`, a ref that could not be built — the refusal
+    // has already been decided and this must not change that.
+    }
+}
+/** How many references one `getAll` carries. */ const GET_ALL_CHUNK = 100;
+/**
+ * The month for every current member of the org, dearest first.
+ *
+ * Reads the ROSTER and then each member's month document by path, rather
+ * than a collection-group query over `months`: the roster is the join the
+ * table needs anyway (a uid is not a name), it is bounded by the seats the
+ * plan sells, and a path read rides no index that has to be deployed before
+ * a workspace can open its Usage page. A person who has left the org is not
+ * listed — the roster is the set of people the reader may see — and their
+ * documents expire on the retention window.
+ */ export async function readOrgAiUsageByUser(firestore, orgId, month) {
+    var _rollup_get;
+    const orgRef = firestore.collection('orgs').doc(orgId);
+    const [roster, rollup] = await Promise.all([
+        orgRef.collection('members').get(),
+        orgRef.collection('assistUsage').doc(month).get()
+    ]);
+    const orgEstCostUsd = Number((_rollup_get = rollup.get('estCostUsd')) != null ? _rollup_get : 0);
+    const denominator = Number.isFinite(orgEstCostUsd) && orgEstCostUsd > 0 ? orgEstCostUsd : 0;
+    const members = roster.docs.map((doc)=>({
+            uid: doc.id,
+            email: typeof doc.get('email') === 'string' ? String(doc.get('email')) : null,
+            displayName: typeof doc.get('displayName') === 'string' && String(doc.get('displayName')).trim() ? String(doc.get('displayName')).trim() : null,
+            role: typeof doc.get('role') === 'string' ? String(doc.get('role')) : null
+        }));
+    const rows = [];
+    for(let start = 0; start < members.length; start += GET_ALL_CHUNK){
+        const chunk = members.slice(start, start + GET_ALL_CHUNK);
+        const snapshots = await firestore.getAll(...chunk.map((member)=>userAiUsageMonthRef(orgRef, member.uid, month)));
+        snapshots.forEach((snapshot, index)=>{
+            var _ref, _member_displayName;
+            if (!snapshot.exists) return;
+            const member = chunk[index];
+            const usage = aiUsageByUserMonthFrom(snapshot.data(), member.uid, month);
+            rows.push(_extends({}, usage, {
+                name: (_ref = (_member_displayName = member.displayName) != null ? _member_displayName : member.email) != null ? _ref : member.uid,
+                email: member.email,
+                role: member.role,
+                share: aiUsageShare(usage.estCostUsd, denominator)
+            }));
+        });
+    }
+    rows.sort((a, b)=>b.credits - a.credits || b.requests - a.requests || a.name.localeCompare(b.name));
+    return {
+        month,
+        orgEstCostUsd: denominator,
+        orgCredits: assistCreditsFromUsd(denominator),
+        rows
+    };
+}
+/**
+ * One person's months in one org, newest first — the member card and the
+ * staff page. Ordered on the document id, which IS the month key and so
+ * needs no field every writer must remember.
+ */ export async function readUserAiUsageMonths(firestore, orgId, uid, limit = AI_USAGE_BY_USER_RETENTION_MONTHS) {
+    const snapshot = await firestore.collection('orgs').doc(orgId).collection(AI_USAGE_BY_USER_COLLECTION).doc(uid).collection(AI_USAGE_BY_USER_MONTHS_COLLECTION).orderBy(FieldPath.documentId(), 'desc').limit(limit).get();
+    return snapshot.docs.map((doc)=>aiUsageByUserMonthFrom(doc.data(), uid, doc.id));
+}
+/**
+ * Remove a person's usage documents on account erasure.
+ *
+ * Two passes, because the documents live under the ORG and are keyed by the
+ * uid: `recursiveDelete(users/{uid})` cannot see them, and neither can a
+ * walk of current memberships find the months left behind in an org the
+ * person was removed from. So every org the erasure knows of is deleted by
+ * path first — no index, cannot fail for want of one — and then a
+ * collection-group query on `uid` catches the rest. The second pass is
+ * reported as `null` rather than thrown when it cannot run: the erasure has
+ * a legal clock, and the by-path pass has already removed everything a
+ * current membership could reach.
+ */ export async function eraseUserAiUsage(firestore, uid, orgIds) {
+    let orgs = 0;
+    for (const orgId of orgIds){
+        await firestore.recursiveDelete(firestore.collection('orgs').doc(orgId).collection(AI_USAGE_BY_USER_COLLECTION).doc(uid));
+        orgs += 1;
+    }
+    let sweptMonths = null;
+    try {
+        const stray = await firestore.collectionGroup(AI_USAGE_BY_USER_MONTHS_COLLECTION).where('uid', '==', uid).get();
+        sweptMonths = 0;
+        for(let start = 0; start < stray.docs.length; start += GET_ALL_CHUNK){
+            const batch = firestore.batch();
+            for (const doc of stray.docs.slice(start, start + GET_ALL_CHUNK)){
+                batch.delete(doc.ref);
+                sweptMonths += 1;
+            }
+            await batch.commit();
+        }
+    } catch (error) {
+        console.error(`eraseUserAiUsage: collection-group sweep failed for ${uid}`, error);
+    }
+    return {
+        orgs,
+        sweptMonths
+    };
+}
+
+//# sourceMappingURL=ai-usage-by-user.js.map

package/src/lib/usage/ai-usage-by-user.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/ai-usage-by-user.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// Straight from the SDK, not the admin lib, for the reason `assist-usage.ts`\n// gives at its head: the statics need no app, and the admin lib would drag the\n// default-app initialization into every unit test that touches a counter.\nimport { FieldPath, FieldValue } from 'firebase-admin/firestore'\nimport {\n  AI_USAGE_BY_USER_COLLECTION,\n  AI_USAGE_BY_USER_MONTHS_COLLECTION,\n  AI_USAGE_BY_USER_RETENTION_MONTHS,\n  aiUsageByUserExpiry,\n  aiUsageByUserMonthFrom,\n  aiUsageShare,\n  type AiUsageByUserMonth,\n  type AiUsageKind,\n} from '../model/ai-usage-by-user'\nimport { AI_USAGE_TOKENS_FIELD } from '../model/ai-tokens'\nimport type { AiUsage } from '../providers/contract'\nimport { assistCreditsFromUsd } from '@aglyn/aglyn/app-utils/assist-credits'\n\n/**\n * PER-USER AI USAGE (AGL-2928): the writer and the readers.\n *\n * One document per person per month, under the org they spent in:\n *\n *   orgs/{orgId}/aiUsageByUser/{uid}/months/{YYYY-MM}\n *     { uid, month, credits, estCostUsd, requests, refusals,\n *       tokens: { input, cached, cacheWrite, output },\n *       byKind: { kind: credits }, byHost: { hostId: credits },\n *       updatedAt, expiresAt }\n *\n * ## Written in the org rollup's own batch\n *\n * `recordUserAiUsage` takes the BATCH the org rollup is being written into\n * and adds this document to it, so the two cannot disagree: a batch commits\n * whole or not at all, and there is no path on which the workspace's month\n * moves and the person's does not. Both assist entrypoints hand it the batch\n * from inside `recordAssistCost` / `recordAssistExchange`, and the job\n * runner meters through the first of those, so a generation step lands here\n * with the job's kind and creator.\n *\n * ## No prose, no PII past the uid\n *\n * The exchange's verbatim half already expires at 180 days for the reason\n * `assist-usage.ts` gives; this rollup is integers keyed by an id, and it\n * is kept longer (`AI_USAGE_BY_USER_RETENTION_MONTHS`) because a workspace\n * admin's question is month-over-month. It is still a document ABOUT a\n * person, so it is readable only by the person and by members holding\n * `billing.view` or `org.auditLog` (the rules, and every route that serves\n * it), and an account erasure sweeps it (`eraseUserAiUsage`).\n */\n\n/** What one metered request attributes to a person. */\nexport interface RecordUserAiUsageInput {\n  /** The person who asked. No uid, no attribution — the write is skipped. */\n  uid: string | null | undefined\n  /** The billing month the org rollup is being written into. */\n  month: string\n  /** The request's measured provider spend, as the org rollup counts it. */\n  estCostUsd: number\n  hostId: string | null | undefined\n  kind: AiUsageKind\n  /** The request's four token counts (AGL-2937), added to the month's `tokens`. */\n  usage?: AiUsage\n}\n\n/**\n * A request's four token counts as increments, under the names every rollup\n * keeps them by (`model/ai-tokens.ts`).\n */\nexport function aiTokenIncrements(usage: AiUsage): Record<string, FirebaseFirestore.FieldValue> {\n  const increment = FieldValue.increment\n  return {\n    input: increment(usage.inputTokens),\n    cached: increment(usage.cacheReadTokens),\n    cacheWrite: increment(usage.cacheWriteTokens),\n    output: increment(usage.outputTokens),\n  }\n}\n\nexport function userAiUsageMonthRef(\n  orgRef: FirebaseFirestore.DocumentReference,\n  uid: string,\n  month: string,\n): FirebaseFirestore.DocumentReference {\n  return orgRef\n    .collection(AI_USAGE_BY_USER_COLLECTION)\n    .doc(uid)\n    .collection(AI_USAGE_BY_USER_MONTHS_COLLECTION)\n    .doc(month)\n}\n\n/**\n * Fold one request into a person's month, on the caller's batch.\n *\n * Returns whether anything was queued: a request with no uid (a meter that\n * could not say who asked) attributes to nobody rather than to a placeholder\n * id that would rank on every table. `set(…, { merge: true })`, never\n * `update()`: the document does not exist before a person's first request\n * of the month, and a merge into a map field adds the key rather than\n * replacing the map.\n */\nexport function recordUserAiUsage(\n  batch: FirebaseFirestore.WriteBatch,\n  orgRef: FirebaseFirestore.DocumentReference,\n  input: RecordUserAiUsageInput,\n): boolean {\n  const uid = String(input.uid ?? '').trim()\n  if (!uid) return false\n  const estCostUsd =\n    Number.isFinite(input.estCostUsd) && input.estCostUsd > 0\n      ? input.estCostUsd\n      : 0\n  const credits = assistCreditsFromUsd(estCostUsd)\n  const increment = FieldValue.increment\n  const hostId = String(input.hostId ?? '').trim()\n  batch.set(\n    userAiUsageMonthRef(orgRef, uid, input.month),\n    {\n      uid,\n      month: input.month,\n      credits: increment(credits),\n      estCostUsd: increment(estCostUsd),\n      requests: increment(1),\n      ...(input.usage ? { [AI_USAGE_TOKENS_FIELD]: aiTokenIncrements(input.usage) } : {}),\n      byKind: { [input.kind]: increment(credits) },\n      ...(hostId ? { byHost: { [hostId]: increment(credits) } } : {}),\n      updatedAt: FieldValue.serverTimestamp(),\n      // The retention window, as a Timestamp the TTL policy can act on.\n      expiresAt: aiUsageByUserExpiry(input.month),\n    },\n    { merge: true },\n  )\n  return true\n}\n\n/**\n * The slice of a reservation a refusal is counted from: whether the gate\n * admitted the request, and the billing month it decided in. Structural, so\n * every door can hand over the reservation it already holds.\n */\nexport interface UserAiRefusalSource {\n  allowed: boolean\n  monthKey: string\n}\n\n/**\n * Count a refused reservation against the person who asked — the per-person\n * twin of `recordAssistRefusal`, and shaped the same way: fire-and-forget,\n * off the refusal's await path, swallowing every error, because a refusal\n * is the gate's cheap exit and a counter must not make it dearer than the\n * thing it counts.\n *\n * Takes the whole reservation rather than a month so every door calls it\n * the same way, once, right after reserving: an admitted reservation records\n * nothing, so the call needs no branch of its own and cannot drift from the\n * door's refusal branch. The month is the reservation's, not the clock's,\n * because that is the month the org's own refusal was counted in.\n */\nexport function recordUserAiRefusal(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  uid: string | null | undefined,\n  reservation: UserAiRefusalSource,\n): void {\n  if (reservation.allowed) return\n  const subject = String(uid ?? '').trim()\n  if (!subject) return\n  try {\n    const ref = userAiUsageMonthRef(\n      firestore.collection('orgs').doc(orgId),\n      subject,\n      reservation.monthKey,\n    )\n    void Promise.resolve(\n      ref.set(\n        {\n          uid: subject,\n          month: reservation.monthKey,\n          refusals: FieldValue.increment(1),\n          updatedAt: FieldValue.serverTimestamp(),\n          expiresAt: aiUsageByUserExpiry(reservation.monthKey),\n        },\n        { merge: true },\n      ),\n    ).catch(() => undefined)\n  } catch {\n    // A double without `set`, a ref that could not be built — the refusal\n    // has already been decided and this must not change that.\n  }\n}\n\n/** One roster row's month, with the person the roster names. */\nexport interface OrgAiUsageByUserRow extends AiUsageByUserMonth {\n  /** The display name, else the email, else the uid — never blank. */\n  name: string\n  email: string | null\n  role: string | null\n  /** This person's share of the org's measured spend, in `[0, 1]`. */\n  share: number\n}\n\nexport interface OrgAiUsageByUserMonth {\n  month: string\n  /** The org rollup's spend for the month — the denominator of every share. */\n  orgEstCostUsd: number\n  orgCredits: number\n  /** Every current member with a document for the month, dearest first. */\n  rows: OrgAiUsageByUserRow[]\n}\n\n/** How many references one `getAll` carries. */\nconst GET_ALL_CHUNK = 100\n\n/**\n * The month for every current member of the org, dearest first.\n *\n * Reads the ROSTER and then each member's month document by path, rather\n * than a collection-group query over `months`: the roster is the join the\n * table needs anyway (a uid is not a name), it is bounded by the seats the\n * plan sells, and a path read rides no index that has to be deployed before\n * a workspace can open its Usage page. A person who has left the org is not\n * listed — the roster is the set of people the reader may see — and their\n * documents expire on the retention window.\n */\nexport async function readOrgAiUsageByUser(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  month: string,\n): Promise<OrgAiUsageByUserMonth> {\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const [roster, rollup] = await Promise.all([\n    orgRef.collection('members').get(),\n    orgRef.collection('assistUsage').doc(month).get(),\n  ])\n  const orgEstCostUsd = Number(rollup.get('estCostUsd') ?? 0)\n  const denominator =\n    Number.isFinite(orgEstCostUsd) && orgEstCostUsd > 0 ? orgEstCostUsd : 0\n\n  const members = roster.docs.map((doc) => ({\n    uid: doc.id,\n    email: typeof doc.get('email') === 'string' ? String(doc.get('email')) : null,\n    displayName:\n      typeof doc.get('displayName') === 'string' && String(doc.get('displayName')).trim()\n        ? String(doc.get('displayName')).trim()\n        : null,\n    role: typeof doc.get('role') === 'string' ? String(doc.get('role')) : null,\n  }))\n\n  const rows: OrgAiUsageByUserRow[] = []\n  for (let start = 0; start < members.length; start += GET_ALL_CHUNK) {\n    const chunk = members.slice(start, start + GET_ALL_CHUNK)\n    const snapshots = await firestore.getAll(\n      ...chunk.map((member) => userAiUsageMonthRef(orgRef, member.uid, month)),\n    )\n    snapshots.forEach((snapshot, index) => {\n      if (!snapshot.exists) return\n      const member = chunk[index]\n      const usage = aiUsageByUserMonthFrom(snapshot.data(), member.uid, month)\n      rows.push({\n        ...usage,\n        name: member.displayName ?? member.email ?? member.uid,\n        email: member.email,\n        role: member.role,\n        share: aiUsageShare(usage.estCostUsd, denominator),\n      })\n    })\n  }\n  rows.sort(\n    (a, b) =>\n      b.credits - a.credits ||\n      b.requests - a.requests ||\n      a.name.localeCompare(b.name),\n  )\n  return {\n    month,\n    orgEstCostUsd: denominator,\n    orgCredits: assistCreditsFromUsd(denominator),\n    rows,\n  }\n}\n\n/**\n * One person's months in one org, newest first — the member card and the\n * staff page. Ordered on the document id, which IS the month key and so\n * needs no field every writer must remember.\n */\nexport async function readUserAiUsageMonths(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  uid: string,\n  limit: number = AI_USAGE_BY_USER_RETENTION_MONTHS,\n): Promise<AiUsageByUserMonth[]> {\n  const snapshot = await firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(AI_USAGE_BY_USER_COLLECTION)\n    .doc(uid)\n    .collection(AI_USAGE_BY_USER_MONTHS_COLLECTION)\n    .orderBy(FieldPath.documentId(), 'desc')\n    .limit(limit)\n    .get()\n  return snapshot.docs.map((doc) => aiUsageByUserMonthFrom(doc.data(), uid, doc.id))\n}\n\nexport interface EraseUserAiUsageResult {\n  /** Orgs whose `aiUsageByUser/{uid}` subtree was deleted by path. */\n  orgs: number\n  /**\n   * Month documents found by the collection-group sweep and deleted — the\n   * ones in orgs the person had already left. `null` when the sweep could\n   * not run (its index is not deployed), which is not zero.\n   */\n  sweptMonths: number | null\n}\n\n/**\n * Remove a person's usage documents on account erasure.\n *\n * Two passes, because the documents live under the ORG and are keyed by the\n * uid: `recursiveDelete(users/{uid})` cannot see them, and neither can a\n * walk of current memberships find the months left behind in an org the\n * person was removed from. So every org the erasure knows of is deleted by\n * path first — no index, cannot fail for want of one — and then a\n * collection-group query on `uid` catches the rest. The second pass is\n * reported as `null` rather than thrown when it cannot run: the erasure has\n * a legal clock, and the by-path pass has already removed everything a\n * current membership could reach.\n */\nexport async function eraseUserAiUsage(\n  firestore: FirebaseFirestore.Firestore,\n  uid: string,\n  orgIds: readonly string[],\n): Promise<EraseUserAiUsageResult> {\n  let orgs = 0\n  for (const orgId of orgIds) {\n    await firestore.recursiveDelete(\n      firestore\n        .collection('orgs')\n        .doc(orgId)\n        .collection(AI_USAGE_BY_USER_COLLECTION)\n        .doc(uid),\n    )\n    orgs += 1\n  }\n  let sweptMonths: number | null = null\n  try {\n    const stray = await firestore\n      .collectionGroup(AI_USAGE_BY_USER_MONTHS_COLLECTION)\n      .where('uid', '==', uid)\n      .get()\n    sweptMonths = 0\n    for (let start = 0; start < stray.docs.length; start += GET_ALL_CHUNK) {\n      const batch = firestore.batch()\n      for (const doc of stray.docs.slice(start, start + GET_ALL_CHUNK)) {\n        batch.delete(doc.ref)\n        sweptMonths += 1\n      }\n      await batch.commit()\n    }\n  } catch (error) {\n    console.error(`eraseUserAiUsage: collection-group sweep failed for ${uid}`, error)\n  }\n  return { orgs, sweptMonths }\n}\n"],"names":["FieldPath","FieldValue","AI_USAGE_BY_USER_COLLECTION","AI_USAGE_BY_USER_MONTHS_COLLECTION","AI_USAGE_BY_USER_RETENTION_MONTHS","aiUsageByUserExpiry","aiUsageByUserMonthFrom","aiUsageShare","AI_USAGE_TOKENS_FIELD","assistCreditsFromUsd","aiTokenIncrements","usage","increment","input","inputTokens","cached","cacheReadTokens","cacheWrite","cacheWriteTokens","output","outputTokens","userAiUsageMonthRef","orgRef","uid","month","collection","doc","recordUserAiUsage","batch","String","trim","estCostUsd","Number","isFinite","credits","hostId","set","requests","byKind","kind","byHost","updatedAt","serverTimestamp","expiresAt","merge","recordUserAiRefusal","firestore","orgId","reservation","allowed","subject","ref","monthKey","Promise","resolve","refusals","catch","undefined","GET_ALL_CHUNK","readOrgAiUsageByUser","rollup","roster","all","get","orgEstCostUsd","denominator","members","docs","map","id","email","displayName","role","rows","start","length","chunk","slice","snapshots","getAll","member","forEach","snapshot","index","exists","data","push","name","share","sort","a","b","localeCompare","orgCredits","readUserAiUsageMonths","limit","orderBy","documentId","eraseUserAiUsage","orgIds","orgs","recursiveDelete","sweptMonths","stray","collectionGroup","where","delete","commit","error","console"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,6EAA6E;AAC7E,+EAA+E;AAC/E,0EAA0E;AAC1E,SAASA,SAAS,EAAEC,UAAU,QAAQ,2BAA0B;AAChE,SACEC,2BAA2B,EAC3BC,kCAAkC,EAClCC,iCAAiC,EACjCC,mBAAmB,EACnBC,sBAAsB,EACtBC,YAAY,QAGP,+BAA2B;AAClC,SAASC,qBAAqB,QAAQ,wBAAoB;AAE1D,SAASC,oBAAoB,QAAQ,wCAAuC;AAgD5E;;;CAGC,GACD,OAAO,SAASC,kBAAkBC,KAAc;IAC9C,MAAMC,YAAYX,WAAWW,SAAS;IACtC,OAAO;QACLC,OAAOD,UAAUD,MAAMG,WAAW;QAClCC,QAAQH,UAAUD,MAAMK,eAAe;QACvCC,YAAYL,UAAUD,MAAMO,gBAAgB;QAC5CC,QAAQP,UAAUD,MAAMS,YAAY;IACtC;AACF;AAEA,OAAO,SAASC,oBACdC,MAA2C,EAC3CC,GAAW,EACXC,KAAa;IAEb,OAAOF,OACJG,UAAU,CAACvB,6BACXwB,GAAG,CAACH,KACJE,UAAU,CAACtB,oCACXuB,GAAG,CAACF;AACT;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASG,kBACdC,KAAmC,EACnCN,MAA2C,EAC3CT,KAA6B;QAEVA,YAQGA;IARtB,MAAMU,MAAMM,QAAOhB,aAAAA,MAAMU,GAAG,YAATV,aAAa,IAAIiB,IAAI;IACxC,IAAI,CAACP,KAAK,OAAO;IACjB,MAAMQ,aACJC,OAAOC,QAAQ,CAACpB,MAAMkB,UAAU,KAAKlB,MAAMkB,UAAU,GAAG,IACpDlB,MAAMkB,UAAU,GAChB;IACN,MAAMG,UAAUzB,qBAAqBsB;IACrC,MAAMnB,YAAYX,WAAWW,SAAS;IACtC,MAAMuB,SAASN,QAAOhB,gBAAAA,MAAMsB,MAAM,YAAZtB,gBAAgB,IAAIiB,IAAI;IAC9CF,MAAMQ,GAAG,CACPf,oBAAoBC,QAAQC,KAAKV,MAAMW,KAAK,GAC5C;QACED;QACAC,OAAOX,MAAMW,KAAK;QAClBU,SAAStB,UAAUsB;QACnBH,YAAYnB,UAAUmB;QACtBM,UAAUzB,UAAU;OAChBC,MAAMF,KAAK,GAAG;QAAE,CAACH,sBAAsB,EAAEE,kBAAkBG,MAAMF,KAAK;IAAE,IAAI,CAAC;QACjF2B,QAAQ;YAAE,CAACzB,MAAM0B,IAAI,CAAC,EAAE3B,UAAUsB;QAAS;OACvCC,SAAS;QAAEK,QAAQ;YAAE,CAACL,OAAO,EAAEvB,UAAUsB;QAAS;IAAE,IAAI,CAAC;QAC7DO,WAAWxC,WAAWyC,eAAe;QACrC,kEAAkE;QAClEC,WAAWtC,oBAAoBQ,MAAMW,KAAK;QAE5C;QAAEoB,OAAO;IAAK;IAEhB,OAAO;AACT;AAYA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,oBACdC,SAAsC,EACtCC,KAAa,EACbxB,GAA8B,EAC9ByB,WAAgC;IAEhC,IAAIA,YAAYC,OAAO,EAAE;IACzB,MAAMC,UAAUrB,OAAON,cAAAA,MAAO,IAAIO,IAAI;IACtC,IAAI,CAACoB,SAAS;IACd,IAAI;QACF,MAAMC,MAAM9B,oBACVyB,UAAUrB,UAAU,CAAC,QAAQC,GAAG,CAACqB,QACjCG,SACAF,YAAYI,QAAQ;QAEtB,KAAKC,QAAQC,OAAO,CAClBH,IAAIf,GAAG,CACL;YACEb,KAAK2B;YACL1B,OAAOwB,YAAYI,QAAQ;YAC3BG,UAAUtD,WAAWW,SAAS,CAAC;YAC/B6B,WAAWxC,WAAWyC,eAAe;YACrCC,WAAWtC,oBAAoB2C,YAAYI,QAAQ;QACrD,GACA;YAAER,OAAO;QAAK,IAEhBY,KAAK,CAAC,IAAMC;IAChB,EAAE,eAAM;IACN,sEAAsE;IACtE,0DAA0D;IAC5D;AACF;AAqBA,8CAA8C,GAC9C,MAAMC,gBAAgB;AAEtB;;;;;;;;;;CAUC,GACD,OAAO,eAAeC,qBACpBb,SAAsC,EACtCC,KAAa,EACbvB,KAAa;QAOgBoC;IAL7B,MAAMtC,SAASwB,UAAUrB,UAAU,CAAC,QAAQC,GAAG,CAACqB;IAChD,MAAM,CAACc,QAAQD,OAAO,GAAG,MAAMP,QAAQS,GAAG,CAAC;QACzCxC,OAAOG,UAAU,CAAC,WAAWsC,GAAG;QAChCzC,OAAOG,UAAU,CAAC,eAAeC,GAAG,CAACF,OAAOuC,GAAG;KAChD;IACD,MAAMC,gBAAgBhC,QAAO4B,cAAAA,OAAOG,GAAG,CAAC,yBAAXH,cAA4B;IACzD,MAAMK,cACJjC,OAAOC,QAAQ,CAAC+B,kBAAkBA,gBAAgB,IAAIA,gBAAgB;IAExE,MAAME,UAAUL,OAAOM,IAAI,CAACC,GAAG,CAAC,CAAC1C,MAAS,CAAA;YACxCH,KAAKG,IAAI2C,EAAE;YACXC,OAAO,OAAO5C,IAAIqC,GAAG,CAAC,aAAa,WAAWlC,OAAOH,IAAIqC,GAAG,CAAC,YAAY;YACzEQ,aACE,OAAO7C,IAAIqC,GAAG,CAAC,mBAAmB,YAAYlC,OAAOH,IAAIqC,GAAG,CAAC,gBAAgBjC,IAAI,KAC7ED,OAAOH,IAAIqC,GAAG,CAAC,gBAAgBjC,IAAI,KACnC;YACN0C,MAAM,OAAO9C,IAAIqC,GAAG,CAAC,YAAY,WAAWlC,OAAOH,IAAIqC,GAAG,CAAC,WAAW;QACxE,CAAA;IAEA,MAAMU,OAA8B,EAAE;IACtC,IAAK,IAAIC,QAAQ,GAAGA,QAAQR,QAAQS,MAAM,EAAED,SAAShB,cAAe;QAClE,MAAMkB,QAAQV,QAAQW,KAAK,CAACH,OAAOA,QAAQhB;QAC3C,MAAMoB,YAAY,MAAMhC,UAAUiC,MAAM,IACnCH,MAAMR,GAAG,CAAC,CAACY,SAAW3D,oBAAoBC,QAAQ0D,OAAOzD,GAAG,EAAEC;QAEnEsD,UAAUG,OAAO,CAAC,CAACC,UAAUC;gBAMnBH,MAAAA;YALR,IAAI,CAACE,SAASE,MAAM,EAAE;YACtB,MAAMJ,SAASJ,KAAK,CAACO,MAAM;YAC3B,MAAMxE,QAAQL,uBAAuB4E,SAASG,IAAI,IAAIL,OAAOzD,GAAG,EAAEC;YAClEiD,KAAKa,IAAI,CAAC,aACL3E;gBACH4E,IAAI,GAAEP,QAAAA,sBAAAA,OAAOT,WAAW,YAAlBS,sBAAsBA,OAAOV,KAAK,YAAlCU,OAAsCA,OAAOzD,GAAG;gBACtD+C,OAAOU,OAAOV,KAAK;gBACnBE,MAAMQ,OAAOR,IAAI;gBACjBgB,OAAOjF,aAAaI,MAAMoB,UAAU,EAAEkC;;QAE1C;IACF;IACAQ,KAAKgB,IAAI,CACP,CAACC,GAAGC,IACFA,EAAEzD,OAAO,GAAGwD,EAAExD,OAAO,IACrByD,EAAEtD,QAAQ,GAAGqD,EAAErD,QAAQ,IACvBqD,EAAEH,IAAI,CAACK,aAAa,CAACD,EAAEJ,IAAI;IAE/B,OAAO;QACL/D;QACAwC,eAAeC;QACf4B,YAAYpF,qBAAqBwD;QACjCQ;IACF;AACF;AAEA;;;;CAIC,GACD,OAAO,eAAeqB,sBACpBhD,SAAsC,EACtCC,KAAa,EACbxB,GAAW,EACXwE,QAAgB3F,iCAAiC;IAEjD,MAAM8E,WAAW,MAAMpC,UACpBrB,UAAU,CAAC,QACXC,GAAG,CAACqB,OACJtB,UAAU,CAACvB,6BACXwB,GAAG,CAACH,KACJE,UAAU,CAACtB,oCACX6F,OAAO,CAAChG,UAAUiG,UAAU,IAAI,QAChCF,KAAK,CAACA,OACNhC,GAAG;IACN,OAAOmB,SAASf,IAAI,CAACC,GAAG,CAAC,CAAC1C,MAAQpB,uBAAuBoB,IAAI2D,IAAI,IAAI9D,KAAKG,IAAI2C,EAAE;AAClF;AAaA;;;;;;;;;;;;CAYC,GACD,OAAO,eAAe6B,iBACpBpD,SAAsC,EACtCvB,GAAW,EACX4E,MAAyB;IAEzB,IAAIC,OAAO;IACX,KAAK,MAAMrD,SAASoD,OAAQ;QAC1B,MAAMrD,UAAUuD,eAAe,CAC7BvD,UACGrB,UAAU,CAAC,QACXC,GAAG,CAACqB,OACJtB,UAAU,CAACvB,6BACXwB,GAAG,CAACH;QAET6E,QAAQ;IACV;IACA,IAAIE,cAA6B;IACjC,IAAI;QACF,MAAMC,QAAQ,MAAMzD,UACjB0D,eAAe,CAACrG,oCAChBsG,KAAK,CAAC,OAAO,MAAMlF,KACnBwC,GAAG;QACNuC,cAAc;QACd,IAAK,IAAI5B,QAAQ,GAAGA,QAAQ6B,MAAMpC,IAAI,CAACQ,MAAM,EAAED,SAAShB,cAAe;YACrE,MAAM9B,QAAQkB,UAAUlB,KAAK;YAC7B,KAAK,MAAMF,OAAO6E,MAAMpC,IAAI,CAACU,KAAK,CAACH,OAAOA,QAAQhB,eAAgB;gBAChE9B,MAAM8E,MAAM,CAAChF,IAAIyB,GAAG;gBACpBmD,eAAe;YACjB;YACA,MAAM1E,MAAM+E,MAAM;QACpB;IACF,EAAE,OAAOC,OAAO;QACdC,QAAQD,KAAK,CAAC,CAAC,oDAAoD,EAAErF,KAAK,EAAEqF;IAC9E;IACA,OAAO;QAAER;QAAME;IAAY;AAC7B"}

package/src/lib/usage/ai-usage-eraser.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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 { PluginUserErasureReport, PluginUserErasureRequest } from '@aglyn/aglyn/plugin-manager/plugin-user-erasure';
+/**
+ * The AI plugin's share of an account erasure (AGL-2939): the person's
+ * monthly usage documents, deleted from every org they belonged to and
+ * swept from the ones they had left, and the AI allotments set on them
+ * (AGL-2942) in the orgs the erasure names. The report is the meter's own —
+ * orgs deleted by path, months found by the cross-org sweep (`null` when
+ * that sweep could not run), and allotments removed.
+ *
+ * Its own module, imported by the server declarations when an erasure
+ * runs, so the boot registers the eraser without loading the meter.
+ */
+export declare function eraseAiUsageForUser({ uid, orgIds, }: PluginUserErasureRequest): Promise<PluginUserErasureReport>;

package/src/lib/usage/ai-usage-eraser.js

@@ -0,0 +1,40 @@
+/**
+ * @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 { eraseAiAllotmentsForUser } from "./ai-allotments.js";
+import { eraseUserAiUsage } from "./ai-usage-by-user.js";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin/server/firebase-admin";
+/**
+ * The AI plugin's share of an account erasure (AGL-2939): the person's
+ * monthly usage documents, deleted from every org they belonged to and
+ * swept from the ones they had left, and the AI allotments set on them
+ * (AGL-2942) in the orgs the erasure names. The report is the meter's own —
+ * orgs deleted by path, months found by the cross-org sweep (`null` when
+ * that sweep could not run), and allotments removed.
+ *
+ * Its own module, imported by the server declarations when an erasure
+ * runs, so the boot registers the eraser without loading the meter.
+ */ export async function eraseAiUsageForUser({ uid, orgIds }) {
+    const firestore = firebaseAdmin.app().firestore();
+    const { orgs, sweptMonths } = await eraseUserAiUsage(firestore, uid, orgIds);
+    const allotments = await eraseAiAllotmentsForUser(firestore, uid, orgIds);
+    return {
+        orgs,
+        sweptMonths,
+        allotments
+    };
+}
+
+//# sourceMappingURL=ai-usage-eraser.js.map

package/src/lib/usage/ai-usage-eraser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/ai-usage-eraser.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  PluginUserErasureReport,\n  PluginUserErasureRequest,\n} from '@aglyn/aglyn/plugin-manager/plugin-user-erasure'\nimport { eraseAiAllotmentsForUser } from './ai-allotments'\nimport { eraseUserAiUsage } from './ai-usage-by-user'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\n\n/**\n * The AI plugin's share of an account erasure (AGL-2939): the person's\n * monthly usage documents, deleted from every org they belonged to and\n * swept from the ones they had left, and the AI allotments set on them\n * (AGL-2942) in the orgs the erasure names. The report is the meter's own —\n * orgs deleted by path, months found by the cross-org sweep (`null` when\n * that sweep could not run), and allotments removed.\n *\n * Its own module, imported by the server declarations when an erasure\n * runs, so the boot registers the eraser without loading the meter.\n */\nexport async function eraseAiUsageForUser({\n  uid,\n  orgIds,\n}: PluginUserErasureRequest): Promise<PluginUserErasureReport> {\n  const firestore = firebaseAdmin.app().firestore()\n  const { orgs, sweptMonths } = await eraseUserAiUsage(firestore, uid, orgIds)\n  const allotments = await eraseAiAllotmentsForUser(firestore, uid, orgIds)\n  return { orgs, sweptMonths, allotments }\n}\n"],"names":["eraseAiAllotmentsForUser","eraseUserAiUsage","firebaseAdmin","eraseAiUsageForUser","uid","orgIds","firestore","app","orgs","sweptMonths","allotments"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAMD,SAASA,wBAAwB,QAAQ,qBAAiB;AAC1D,SAASC,gBAAgB,QAAQ,wBAAoB;AACrD,SAASC,aAAa,QAAQ,iDAAgD;AAE9E;;;;;;;;;;CAUC,GACD,OAAO,eAAeC,oBAAoB,EACxCC,GAAG,EACHC,MAAM,EACmB;IACzB,MAAMC,YAAYJ,cAAcK,GAAG,GAAGD,SAAS;IAC/C,MAAM,EAAEE,IAAI,EAAEC,WAAW,EAAE,GAAG,MAAMR,iBAAiBK,WAAWF,KAAKC;IACrE,MAAMK,aAAa,MAAMV,yBAAyBM,WAAWF,KAAKC;IAClE,OAAO;QAAEG;QAAMC;QAAaC;IAAW;AACzC"}

package/src/lib/usage/ai-usage-meter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 AssistReservation } from './assist-usage';
+import { type AiUsageMeterWire } from './ai-usage-wire';
+/**
+ * The usage strip's envelope from what a door already holds (AGL-2942): the
+ * reservation it took and, once the provider answered, what the exchange
+ * cost. No read — the reservation measured the pool and the caller's month
+ * inside the transaction it already runs.
+ *
+ * Every figure is credits. The pool comes through `publicAssistQuota`, the
+ * one projection allowed to turn our provider bill into a customer figure;
+ * the caller's month comes off the allotment gate, which the meter wrote in
+ * credits in the first place.
+ *
+ * `last` is added to both months, because the reservation measured them
+ * BEFORE this exchange and the strip is read after it.
+ */
+export declare function aiUsageMeter(reservation: Pick<AssistReservation, 'monthKey' | 'allowed'> & Partial<AssistReservation>, extra?: {
+    lastCredits?: number | null;
+    model?: {
+        id: string;
+        auto: boolean;
+    } | null;
+}): AiUsageMeterWire;

package/src/lib/usage/ai-usage-meter.js

@@ -0,0 +1,85 @@
+/**
+ * @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 { aiCatalogEntry } from "../providers/catalog.js";
+import { publicAssistQuota } from "./assist-usage.js";
+import { aiUsageMeterState } from "./ai-usage-wire.js";
+/**
+ * The usage strip's envelope from what a door already holds (AGL-2942): the
+ * reservation it took and, once the provider answered, what the exchange
+ * cost. No read — the reservation measured the pool and the caller's month
+ * inside the transaction it already runs.
+ *
+ * Every figure is credits. The pool comes through `publicAssistQuota`, the
+ * one projection allowed to turn our provider bill into a customer figure;
+ * the caller's month comes off the allotment gate, which the meter wrote in
+ * credits in the first place.
+ *
+ * `last` is added to both months, because the reservation measured them
+ * BEFORE this exchange and the strip is read after it.
+ */ export function aiUsageMeter(reservation, extra = {}) {
+    var _reservation_allotment, _ref, _ref1;
+    const last = typeof extra.lastCredits === 'number' && Number.isFinite(extra.lastCredits) ? Math.max(0, Math.ceil(extra.lastCredits)) : null;
+    const spent = last != null ? last : 0;
+    let pool = {
+        used: spent,
+        limit: null
+    };
+    try {
+        var _publicAssistQuota;
+        const credits = (_publicAssistQuota = publicAssistQuota(reservation)) == null ? void 0 : _publicAssistQuota.credits;
+        if (credits) pool = {
+            used: credits.used + spent,
+            limit: credits.limit
+        };
+    } catch (unused) {
+    // A reservation without its dollar figures (a double, a refusal taken
+    // before the month was read) reports the exchange alone.
+    }
+    const gate = (_reservation_allotment = reservation.allotment) != null ? _reservation_allotment : null;
+    const binding = (_ref = gate == null ? void 0 : gate.binding) != null ? _ref : null;
+    const mine = binding ? {
+        used: binding.used + spent,
+        limit: binding.credits,
+        mode: binding.mode,
+        scope: binding.scope
+    } : {
+        used: ((_ref1 = gate == null ? void 0 : gate.personalCredits) != null ? _ref1 : 0) + spent,
+        limit: null,
+        mode: null,
+        scope: null
+    };
+    const refused = !reservation.allowed;
+    const entry = extra.model ? aiCatalogEntry(extra.model.id) : undefined;
+    return {
+        month: reservation.monthKey,
+        pool,
+        mine,
+        last,
+        refused,
+        state: aiUsageMeterState({
+            pool,
+            mine,
+            refused
+        }),
+        model: extra.model && entry ? {
+            id: entry.id,
+            label: entry.label,
+            auto: extra.model.auto
+        } : null
+    };
+}
+
+//# sourceMappingURL=ai-usage-meter.js.map

package/src/lib/usage/ai-usage-meter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/usage/ai-usage-meter.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 { aiCatalogEntry } from '../providers/catalog'\nimport { publicAssistQuota, type AssistReservation } from './assist-usage'\nimport { aiUsageMeterState, type AiUsageMeterWire } from './ai-usage-wire'\n\n/**\n * The usage strip's envelope from what a door already holds (AGL-2942): the\n * reservation it took and, once the provider answered, what the exchange\n * cost. No read — the reservation measured the pool and the caller's month\n * inside the transaction it already runs.\n *\n * Every figure is credits. The pool comes through `publicAssistQuota`, the\n * one projection allowed to turn our provider bill into a customer figure;\n * the caller's month comes off the allotment gate, which the meter wrote in\n * credits in the first place.\n *\n * `last` is added to both months, because the reservation measured them\n * BEFORE this exchange and the strip is read after it.\n */\nexport function aiUsageMeter(\n  reservation: Pick<AssistReservation, 'monthKey' | 'allowed'> &\n    Partial<AssistReservation>,\n  extra: {\n    lastCredits?: number | null\n    model?: { id: string; auto: boolean } | null\n  } = {},\n): AiUsageMeterWire {\n  const last =\n    typeof extra.lastCredits === 'number' && Number.isFinite(extra.lastCredits)\n      ? Math.max(0, Math.ceil(extra.lastCredits))\n      : null\n  const spent = last ?? 0\n  let pool: AiUsageMeterWire['pool'] = { used: spent, limit: null }\n  try {\n    const credits = publicAssistQuota(reservation as AssistReservation)?.credits\n    if (credits) pool = { used: credits.used + spent, limit: credits.limit }\n  } catch {\n    // A reservation without its dollar figures (a double, a refusal taken\n    // before the month was read) reports the exchange alone.\n  }\n  const gate = reservation.allotment ?? null\n  const binding = gate?.binding ?? null\n  const mine: AiUsageMeterWire['mine'] = binding\n    ? {\n        used: binding.used + spent,\n        limit: binding.credits,\n        mode: binding.mode,\n        scope: binding.scope,\n      }\n    : {\n        used: (gate?.personalCredits ?? 0) + spent,\n        limit: null,\n        mode: null,\n        scope: null,\n      }\n  const refused = !reservation.allowed\n  const entry = extra.model ? aiCatalogEntry(extra.model.id) : undefined\n  return {\n    month: reservation.monthKey,\n    pool,\n    mine,\n    last,\n    refused,\n    state: aiUsageMeterState({ pool, mine, refused }),\n    model:\n      extra.model && entry\n        ? { id: entry.id, label: entry.label, auto: extra.model.auto }\n        : null,\n  }\n}\n"],"names":["aiCatalogEntry","publicAssistQuota","aiUsageMeterState","aiUsageMeter","reservation","extra","last","lastCredits","Number","isFinite","Math","max","ceil","spent","pool","used","limit","credits","gate","allotment","binding","mine","mode","scope","personalCredits","refused","allowed","entry","model","id","undefined","month","monthKey","state","label","auto"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,cAAc,QAAQ,0BAAsB;AACrD,SAASC,iBAAiB,QAAgC,oBAAgB;AAC1E,SAASC,iBAAiB,QAA+B,qBAAiB;AAE1E;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,aACdC,WAC4B,EAC5BC,QAGI,CAAC,CAAC;QAeOD;IAbb,MAAME,OACJ,OAAOD,MAAME,WAAW,KAAK,YAAYC,OAAOC,QAAQ,CAACJ,MAAME,WAAW,IACtEG,KAAKC,GAAG,CAAC,GAAGD,KAAKE,IAAI,CAACP,MAAME,WAAW,KACvC;IACN,MAAMM,QAAQP,eAAAA,OAAQ;IACtB,IAAIQ,OAAiC;QAAEC,MAAMF;QAAOG,OAAO;IAAK;IAChE,IAAI;YACcf;QAAhB,MAAMgB,WAAUhB,qBAAAA,kBAAkBG,iCAAlBH,mBAAqDgB,OAAO;QAC5E,IAAIA,SAASH,OAAO;YAAEC,MAAME,QAAQF,IAAI,GAAGF;YAAOG,OAAOC,QAAQD,KAAK;QAAC;IACzE,EAAE,eAAM;IACN,sEAAsE;IACtE,yDAAyD;IAC3D;IACA,MAAME,QAAOd,yBAAAA,YAAYe,SAAS,YAArBf,yBAAyB;IACtC,MAAMgB,kBAAUF,wBAAAA,KAAME,OAAO,mBAAI;IACjC,MAAMC,OAAiCD,UACnC;QACEL,MAAMK,QAAQL,IAAI,GAAGF;QACrBG,OAAOI,QAAQH,OAAO;QACtBK,MAAMF,QAAQE,IAAI;QAClBC,OAAOH,QAAQG,KAAK;IACtB,IACA;QACER,MAAM,UAACG,wBAAAA,KAAMM,eAAe,oBAAI,KAAKX;QACrCG,OAAO;QACPM,MAAM;QACNC,OAAO;IACT;IACJ,MAAME,UAAU,CAACrB,YAAYsB,OAAO;IACpC,MAAMC,QAAQtB,MAAMuB,KAAK,GAAG5B,eAAeK,MAAMuB,KAAK,CAACC,EAAE,IAAIC;IAC7D,OAAO;QACLC,OAAO3B,YAAY4B,QAAQ;QAC3BlB;QACAO;QACAf;QACAmB;QACAQ,OAAO/B,kBAAkB;YAAEY;YAAMO;YAAMI;QAAQ;QAC/CG,OACEvB,MAAMuB,KAAK,IAAID,QACX;YAAEE,IAAIF,MAAME,EAAE;YAAEK,OAAOP,MAAMO,KAAK;YAAEC,MAAM9B,MAAMuB,KAAK,CAACO,IAAI;QAAC,IAC3D;IACR;AACF"}