@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/server/ai-seo-apply.js

@@ -0,0 +1,294 @@
+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.
+ */ // lockdown-423: via libs/plugins/ai/src/lib/server/ai-jobs-gate.ts
+// The gate carries the org verdict; the handler adds the site's own below,
+// with the host document in hand.
+import { checkEntitlement, createResourceUid, encodeStoredNodes, hostRoleCanWrite } from "@aglyn/aglyn/server";
+import { pageContentRootId } from "@aglyn/aglyn/app-utils/page-markdown";
+import { decodeStoredNodes } from "@aglyn/aglyn/app-utils/stored-nodes";
+import { lockdownRefusal } from "@aglyn/tenant-data-admin/server/lockdown";
+import { logAiSeoApplied } from "../activity/ai-activity.js";
+import { aiJobSummary, getAiJob, recordAiJobApplied, writeAiJobAudit } from "../jobs/ai-jobs.js";
+import { aiSeoAuditView, aiSeoJobTarget } from "../model/ai-seo.js";
+import { applyAiSeoContentFixes } from "../runtime/seo-content-fixes.js";
+import { aiJobsGate } from "./ai-jobs-gate.js";
+/**
+ * Apply a site audit (AGL-2910): `POST /api/ai/seo/apply { orgId, hostId, jobId }`.
+ *
+ * "Apply all" does two things and neither changes what the published site
+ * serves.
+ *
+ * - **Content fixes open a NEW version per page.** The page's published
+ *   version is copied, the fixes are applied to the copy — an image
+ *   description, the page's one main heading — and the copy is stored as a
+ *   new unpublished version. The published version and the screen's
+ *   `versionId` are never touched: a person opens the draft, looks, and
+ *   publishes it through the door that already exists.
+ * - **Listing values are STAGED, not written.** A page's search title and
+ *   description are served straight from the screen document, so writing
+ *   them would publish them. The apply records which pages have values
+ *   waiting; the page's SEO card offers them, and its Save SEO is the write.
+ *
+ * The site-wide proposals — structured data and the agent guidance — are the
+ * site SEO form's to save, and the card puts them there as unsaved edits; this
+ * door never writes the host document.
+ *
+ * Idempotent per job: a page this job already opened a version for keeps
+ * that version, so a second press opens nothing new.
+ *
+ * ## The rungs
+ *
+ * The jobs read gate (membership, the release flag, `aiGenerative`, the org
+ * lockdown), then the site: it must be the job's and the org's, the caller
+ * must hold a role that writes the site's content — the role creating a
+ * version asks for — and the site's own lockdown verdict must admit a write.
+ * Nothing here spends a token, so there is no reservation.
+ */ const ID_CHARS = /^[A-Za-z0-9_-]{1,100}$/;
+/** The version history sentence the versions route gives, for a plan without it. */ export const AI_SEO_APPLY_VERSIONING_COPY = 'Version history requires a Pro plan — see Billing to upgrade';
+const str = (value)=>typeof value === 'string' ? value.trim() : '';
+/**
+ * Open the versions and record the apply. Exported for the spec, which drives
+ * it against a Firestore double and proves what it leaves alone.
+ */ export async function applyAiSeoAudit(firestore, input) {
+    var _input_now, _ref, _ref1;
+    var _input_job_applied, _input_job_applied1;
+    const now = (_input_now = input.now) != null ? _input_now : new Date();
+    const hostRef = firestore.collection('hosts').doc(input.hostId);
+    const opened = _extends({}, (_ref = (_input_job_applied = input.job.applied) == null ? void 0 : _input_job_applied.versions) != null ? _ref : {});
+    const staged = new Set((_ref1 = (_input_job_applied1 = input.job.applied) == null ? void 0 : _input_job_applied1.staged) != null ? _ref1 : []);
+    const names = new Map(input.view.report.pages.map((page)=>[
+            page.screenId,
+            page.name
+        ]));
+    const versions = [];
+    const skipped = [];
+    for (const fix of Object.values(input.view.fixes)){
+        var _names_get;
+        const screenId = fix.screenId;
+        const name = (_names_get = names.get(screenId)) != null ? _names_get : screenId;
+        if (Object.keys(fix.values).length) staged.add(screenId);
+        if (!fix.content.length) continue;
+        const screenRef = hostRef.collection('screens').doc(screenId);
+        const earlier = opened[screenId];
+        if (earlier && (await screenRef.collection('versions').doc(earlier).get()).exists) {
+            versions.push({
+                screenId,
+                versionId: earlier,
+                name,
+                fixes: 0
+            });
+            continue;
+        }
+        if (!input.versioning) {
+            skipped.push({
+                screenId,
+                reason: AI_SEO_APPLY_VERSIONING_COPY
+            });
+            continue;
+        }
+        const screenSnapshot = await screenRef.get();
+        if (!screenSnapshot.exists || screenSnapshot.get('deletedAt')) {
+            skipped.push({
+                screenId,
+                reason: 'The page no longer exists.'
+            });
+            continue;
+        }
+        const publishedId = str(screenSnapshot.get('versionId'));
+        const source = publishedId ? await screenRef.collection('versions').doc(publishedId).get() : null;
+        const sourceData = (source == null ? void 0 : source.exists) ? source.data() : null;
+        const nodes = sourceData ? decodeStoredNodes(sourceData['nodes']) : null;
+        if (!sourceData || !nodes) {
+            skipped.push({
+                screenId,
+                reason: 'The page has no published version to start from.'
+            });
+            continue;
+        }
+        const rootId = typeof sourceData['rootId'] === 'string' ? sourceData['rootId'] : undefined;
+        const result = applyAiSeoContentFixes(nodes, fix.content, pageContentRootId(nodes, rootId));
+        if (!result.applied.length) {
+            var _ref2;
+            var _result_skipped_;
+            skipped.push({
+                screenId,
+                reason: (_ref2 = (_result_skipped_ = result.skipped[0]) == null ? void 0 : _result_skipped_.reason) != null ? _ref2 : 'Nothing on the page needed changing.'
+            });
+            continue;
+        }
+        const versionId = createResourceUid();
+        // Compressed at rest, as every write of a version's nodes is.
+        const packed = encodeStoredNodes(result.nodes);
+        await screenRef.collection('versions').doc(versionId).create(_extends({}, sourceData, {
+            nodes: packed ? Buffer.from(packed) : result.nodes,
+            displayName: 'SEO fixes',
+            createdAt: now,
+            updatedAt: now,
+            createdBy: input.uid
+        }));
+        opened[screenId] = versionId;
+        versions.push({
+            screenId,
+            versionId,
+            name,
+            fixes: result.applied.length
+        });
+    }
+    const applied = {
+        // The Admin SDK stores a `Date` as the timestamp the type describes.
+        at: now,
+        by: input.uid,
+        versions: opened,
+        staged: [
+            ...staged
+        ]
+    };
+    const job = await recordAiJobApplied(firestore, input.orgId, input.job.$id, applied, now);
+    return {
+        job,
+        versions,
+        staged: [
+            ...staged
+        ],
+        skipped
+    };
+}
+export async function POST(request) {
+    var _body_orgId, _host_memberRoles, _job_outputs, _decoded_email;
+    let body;
+    try {
+        var _ref;
+        body = (_ref = await request.json()) != null ? _ref : {};
+    } catch (unused) {
+        body = {};
+    }
+    const gate = await aiJobsGate(request, String((_body_orgId = body['orgId']) != null ? _body_orgId : ''));
+    if (gate instanceof Response) return gate;
+    const hostId = str(body['hostId']);
+    const jobId = str(body['jobId']);
+    if (!ID_CHARS.test(hostId) || !ID_CHARS.test(jobId)) {
+        return Response.json({
+            error: 'Name the site and the audit to apply'
+        }, {
+            status: 400
+        });
+    }
+    const { firestore, orgId, uid, staff, org, decoded } = gate;
+    const hostSnapshot = await firestore.collection('hosts').doc(hostId).get();
+    const host = hostSnapshot.exists ? hostSnapshot.data() : null;
+    if (!host || host['orgId'] !== orgId) {
+        return Response.json({
+            error: 'Unknown site'
+        }, {
+            status: 404
+        });
+    }
+    const role = ((_host_memberRoles = host['memberRoles']) != null ? _host_memberRoles : {})[uid];
+    if (!staff && !hostRoleCanWrite(role)) {
+        return Response.json({
+            error: 'Editing requires the editor role'
+        }, {
+            status: 403
+        });
+    }
+    const locked = await lockdownRefusal({
+        request,
+        staff,
+        uid,
+        org: org,
+        host: host
+    });
+    if (locked) return locked;
+    const job = await getAiJob(firestore, orgId, jobId);
+    if (!job || job.kind !== 'seo' || job.hostId !== hostId || aiSeoJobTarget(job.inputs) !== 'site') {
+        return Response.json({
+            error: 'Unknown audit'
+        }, {
+            status: 404
+        });
+    }
+    if (job.status !== 'done') {
+        return Response.json({
+            error: 'The audit is still running — apply it once it has finished'
+        }, {
+            status: 409
+        });
+    }
+    const view = aiSeoAuditView((_job_outputs = job.outputs) != null ? _job_outputs : []);
+    if (!view) {
+        return Response.json({
+            error: 'This audit has nothing to apply'
+        }, {
+            status: 409
+        });
+    }
+    const result = await applyAiSeoAudit(firestore, {
+        orgId,
+        hostId,
+        job,
+        view,
+        uid,
+        versioning: checkEntitlement(org, 'versioning')
+    });
+    const opened = result.versions.filter((entry)=>entry.fixes > 0);
+    await writeAiJobAudit(firestore, {
+        action: 'ai.job.apply',
+        actorUid: uid,
+        actorEmail: (_decoded_email = decoded.email) != null ? _decoded_email : null,
+        orgId,
+        jobId,
+        after: {
+            hostId,
+            versions: Object.fromEntries(opened.map((entry)=>[
+                    entry.screenId,
+                    entry.versionId
+                ])),
+            staged: result.staged
+        }
+    });
+    if (opened.length || result.staged.length) {
+        var _decoded_email1;
+        await logAiSeoApplied(orgId, {
+            uid,
+            email: (_decoded_email1 = decoded.email) != null ? _decoded_email1 : null
+        }, {
+            jobId,
+            hostId,
+            hostName: str(host['displayName']) || null,
+            versions: opened.length,
+            staged: result.staged.length
+        }).catch((error)=>console.error('ai seo apply activity failed', {
+                orgId,
+                jobId,
+                error
+            }));
+    }
+    return Response.json({
+        job: aiJobSummary(result.job),
+        versions: result.versions,
+        staged: result.staged,
+        skipped: result.skipped
+    }, {
+        status: 200,
+        headers: {
+            'Cache-Control': 'no-store'
+        }
+    });
+}
+export const dynamic = 'force-dynamic';
+
+//# sourceMappingURL=ai-seo-apply.js.map

package/src/lib/server/ai-seo-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-seo-apply.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// lockdown-423: via libs/plugins/ai/src/lib/server/ai-jobs-gate.ts\n// The gate carries the org verdict; the handler adds the site's own below,\n// with the host document in hand.\n\nimport {\n  checkEntitlement,\n  createResourceUid,\n  encodeStoredNodes,\n  hostRoleCanWrite,\n} from '@aglyn/aglyn/server'\nimport { pageContentRootId } from '@aglyn/aglyn/app-utils/page-markdown'\nimport { decodeStoredNodes } from '@aglyn/aglyn/app-utils/stored-nodes'\nimport { lockdownRefusal } from '@aglyn/tenant-data-admin/server/lockdown'\nimport { logAiSeoApplied } from '../activity/ai-activity'\nimport {\n  aiJobSummary,\n  getAiJob,\n  recordAiJobApplied,\n  writeAiJobAudit,\n} from '../jobs/ai-jobs'\nimport type { AiJob, AiJobApplied } from '../model/ai-jobs.types'\nimport { aiSeoAuditView, aiSeoJobTarget, type AiSeoAuditView } from '../model/ai-seo'\nimport { applyAiSeoContentFixes } from '../runtime/seo-content-fixes'\nimport { aiJobsGate } from './ai-jobs-gate'\n\n/**\n * Apply a site audit (AGL-2910): `POST /api/ai/seo/apply { orgId, hostId, jobId }`.\n *\n * \"Apply all\" does two things and neither changes what the published site\n * serves.\n *\n * - **Content fixes open a NEW version per page.** The page's published\n *   version is copied, the fixes are applied to the copy — an image\n *   description, the page's one main heading — and the copy is stored as a\n *   new unpublished version. The published version and the screen's\n *   `versionId` are never touched: a person opens the draft, looks, and\n *   publishes it through the door that already exists.\n * - **Listing values are STAGED, not written.** A page's search title and\n *   description are served straight from the screen document, so writing\n *   them would publish them. The apply records which pages have values\n *   waiting; the page's SEO card offers them, and its Save SEO is the write.\n *\n * The site-wide proposals — structured data and the agent guidance — are the\n * site SEO form's to save, and the card puts them there as unsaved edits; this\n * door never writes the host document.\n *\n * Idempotent per job: a page this job already opened a version for keeps\n * that version, so a second press opens nothing new.\n *\n * ## The rungs\n *\n * The jobs read gate (membership, the release flag, `aiGenerative`, the org\n * lockdown), then the site: it must be the job's and the org's, the caller\n * must hold a role that writes the site's content — the role creating a\n * version asks for — and the site's own lockdown verdict must admit a write.\n * Nothing here spends a token, so there is no reservation.\n */\n\nconst ID_CHARS = /^[A-Za-z0-9_-]{1,100}$/\n\n/** The version history sentence the versions route gives, for a plan without it. */\nexport const AI_SEO_APPLY_VERSIONING_COPY =\n  'Version history requires a Pro plan — see Billing to upgrade'\n\nexport interface AiSeoApplyInput {\n  orgId: string\n  hostId: string\n  job: AiJob\n  view: AiSeoAuditView\n  uid: string\n  /** Whether the org's plan keeps more than one version of a page. */\n  versioning: boolean\n  now?: Date\n}\n\nexport interface AiSeoApplyResult {\n  job: AiJob\n  /** The version each page's content fixes went into; `fixes` is 0 for one opened by an earlier apply. */\n  versions: Array<{ screenId: string; versionId: string; name: string; fixes: number }>\n  /** Pages whose listing values wait in their SEO card. */\n  staged: string[]\n  skipped: Array<{ screenId: string; reason: string }>\n}\n\nconst str = (value: unknown): string => (typeof value === 'string' ? value.trim() : '')\n\n/**\n * Open the versions and record the apply. Exported for the spec, which drives\n * it against a Firestore double and proves what it leaves alone.\n */\nexport async function applyAiSeoAudit(\n  firestore: FirebaseFirestore.Firestore,\n  input: AiSeoApplyInput,\n): Promise<AiSeoApplyResult> {\n  const now = input.now ?? new Date()\n  const hostRef = firestore.collection('hosts').doc(input.hostId)\n  const opened = { ...(input.job.applied?.versions ?? {}) }\n  const staged = new Set(input.job.applied?.staged ?? [])\n  const names = new Map(input.view.report.pages.map((page) => [page.screenId, page.name]))\n  const versions: AiSeoApplyResult['versions'] = []\n  const skipped: AiSeoApplyResult['skipped'] = []\n\n  for (const fix of Object.values(input.view.fixes)) {\n    const screenId = fix.screenId\n    const name = names.get(screenId) ?? screenId\n    if (Object.keys(fix.values).length) staged.add(screenId)\n    if (!fix.content.length) continue\n    const screenRef = hostRef.collection('screens').doc(screenId)\n\n    const earlier = opened[screenId]\n    if (earlier && (await screenRef.collection('versions').doc(earlier).get()).exists) {\n      versions.push({ screenId, versionId: earlier, name, fixes: 0 })\n      continue\n    }\n    if (!input.versioning) {\n      skipped.push({ screenId, reason: AI_SEO_APPLY_VERSIONING_COPY })\n      continue\n    }\n    const screenSnapshot = await screenRef.get()\n    if (!screenSnapshot.exists || screenSnapshot.get('deletedAt')) {\n      skipped.push({ screenId, reason: 'The page no longer exists.' })\n      continue\n    }\n    const publishedId = str(screenSnapshot.get('versionId'))\n    const source = publishedId ? await screenRef.collection('versions').doc(publishedId).get() : null\n    const sourceData = source?.exists ? (source.data() as Record<string, unknown>) : null\n    const nodes = sourceData ? decodeStoredNodes<Record<string, unknown>>(sourceData['nodes']) : null\n    if (!sourceData || !nodes) {\n      skipped.push({ screenId, reason: 'The page has no published version to start from.' })\n      continue\n    }\n    const rootId = typeof sourceData['rootId'] === 'string' ? sourceData['rootId'] : undefined\n    const result = applyAiSeoContentFixes(\n      nodes,\n      fix.content,\n      pageContentRootId(nodes as never, rootId),\n    )\n    if (!result.applied.length) {\n      skipped.push({ screenId, reason: result.skipped[0]?.reason ?? 'Nothing on the page needed changing.' })\n      continue\n    }\n    const versionId = createResourceUid()\n    // Compressed at rest, as every write of a version's nodes is.\n    const packed = encodeStoredNodes(result.nodes)\n    await screenRef\n      .collection('versions')\n      .doc(versionId)\n      .create({\n        ...sourceData,\n        nodes: packed ? Buffer.from(packed) : result.nodes,\n        displayName: 'SEO fixes',\n        createdAt: now,\n        updatedAt: now,\n        createdBy: input.uid,\n      })\n    opened[screenId] = versionId\n    versions.push({ screenId, versionId, name, fixes: result.applied.length })\n  }\n\n  const applied: AiJobApplied = {\n    // The Admin SDK stores a `Date` as the timestamp the type describes.\n    at: now as unknown as AiJobApplied['at'],\n    by: input.uid,\n    versions: opened,\n    staged: [...staged],\n  }\n  const job = await recordAiJobApplied(firestore, input.orgId, input.job.$id, applied, now)\n  return { job, versions, staged: [...staged], skipped }\n}\n\nexport async function POST(request: Request): Promise<Response> {\n  let body: Record<string, unknown>\n  try {\n    body = ((await request.json()) ?? {}) as Record<string, unknown>\n  } catch {\n    body = {}\n  }\n  const gate = await aiJobsGate(request, String(body['orgId'] ?? ''))\n  if (gate instanceof Response) return gate\n  const hostId = str(body['hostId'])\n  const jobId = str(body['jobId'])\n  if (!ID_CHARS.test(hostId) || !ID_CHARS.test(jobId)) {\n    return Response.json({ error: 'Name the site and the audit to apply' }, { status: 400 })\n  }\n  const { firestore, orgId, uid, staff, org, decoded } = gate\n\n  const hostSnapshot = await firestore.collection('hosts').doc(hostId).get()\n  const host = hostSnapshot.exists ? (hostSnapshot.data() as Record<string, unknown>) : null\n  if (!host || host['orgId'] !== orgId) {\n    return Response.json({ error: 'Unknown site' }, { status: 404 })\n  }\n  const role = ((host['memberRoles'] ?? {}) as Record<string, unknown>)[uid]\n  if (!staff && !hostRoleCanWrite(role)) {\n    return Response.json({ error: 'Editing requires the editor role' }, { status: 403 })\n  }\n  const locked = await lockdownRefusal({\n    request,\n    staff,\n    uid,\n    org: org as Record<string, unknown>,\n    host: host as never,\n  })\n  if (locked) return locked\n\n  const job = await getAiJob(firestore, orgId, jobId)\n  if (!job || job.kind !== 'seo' || job.hostId !== hostId || aiSeoJobTarget(job.inputs) !== 'site') {\n    return Response.json({ error: 'Unknown audit' }, { status: 404 })\n  }\n  if (job.status !== 'done') {\n    return Response.json({ error: 'The audit is still running — apply it once it has finished' }, { status: 409 })\n  }\n  const view = aiSeoAuditView(job.outputs ?? [])\n  if (!view) {\n    return Response.json({ error: 'This audit has nothing to apply' }, { status: 409 })\n  }\n\n  const result = await applyAiSeoAudit(firestore, {\n    orgId,\n    hostId,\n    job,\n    view,\n    uid,\n    versioning: checkEntitlement(org, 'versioning'),\n  })\n  const opened = result.versions.filter((entry) => entry.fixes > 0)\n  await writeAiJobAudit(firestore, {\n    action: 'ai.job.apply',\n    actorUid: uid,\n    actorEmail: decoded.email ?? null,\n    orgId,\n    jobId,\n    after: {\n      hostId,\n      versions: Object.fromEntries(opened.map((entry) => [entry.screenId, entry.versionId])),\n      staged: result.staged,\n    },\n  })\n  if (opened.length || result.staged.length) {\n    await logAiSeoApplied(orgId, { uid, email: decoded.email ?? null }, {\n      jobId,\n      hostId,\n      hostName: str(host['displayName']) || null,\n      versions: opened.length,\n      staged: result.staged.length,\n    }).catch((error) => console.error('ai seo apply activity failed', { orgId, jobId, error }))\n  }\n  return Response.json(\n    {\n      job: aiJobSummary(result.job),\n      versions: result.versions,\n      staged: result.staged,\n      skipped: result.skipped,\n    },\n    { status: 200, headers: { 'Cache-Control': 'no-store' } },\n  )\n}\n\nexport const dynamic = 'force-dynamic'\n"],"names":["checkEntitlement","createResourceUid","encodeStoredNodes","hostRoleCanWrite","pageContentRootId","decodeStoredNodes","lockdownRefusal","logAiSeoApplied","aiJobSummary","getAiJob","recordAiJobApplied","writeAiJobAudit","aiSeoAuditView","aiSeoJobTarget","applyAiSeoContentFixes","aiJobsGate","ID_CHARS","AI_SEO_APPLY_VERSIONING_COPY","str","value","trim","applyAiSeoAudit","firestore","input","now","Date","hostRef","collection","doc","hostId","opened","job","applied","versions","staged","Set","names","Map","view","report","pages","map","page","screenId","name","skipped","fix","Object","values","fixes","get","keys","length","add","content","screenRef","earlier","exists","push","versionId","versioning","reason","screenSnapshot","publishedId","source","sourceData","data","nodes","rootId","undefined","result","packed","create","Buffer","from","displayName","createdAt","updatedAt","createdBy","uid","at","by","orgId","$id","POST","request","body","host","decoded","json","gate","String","Response","jobId","test","error","status","staff","org","hostSnapshot","role","locked","kind","inputs","outputs","filter","entry","action","actorUid","actorEmail","email","after","fromEntries","hostName","catch","console","headers","dynamic"],"mappings":"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"}

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

@@ -0,0 +1,18 @@
+/**
+ * @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.
+ */
+declare function handler(request: Request): Promise<Response>;
+export { handler as GET };

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

@@ -0,0 +1,220 @@
+/**
+ * @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 { csvCell, pluginRequestFromWeb } from "@aglyn/aglyn/server";
+import { emailUnverifiedResponse, firebaseAdmin, isImpersonationSession, memberHasOrgPermission, resolveOrgMembership } from "@aglyn/tenant-data-admin";
+import { aiUsageMonthKeys, aiUsageMonthWithinRetention, aiUsageShare } from "../model/ai-usage-by-user.js";
+import { readOrgAiUsageByUser, readUserAiUsageMonths } from "../usage/ai-usage-by-user.js";
+import { FieldValue } from "firebase-admin/firestore";
+import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { AI_USAGE_CSV_HEADER, AI_USAGE_EXPORT_ROWS_HEADER, aiUsageCsvLine, toAiUsageWireRow } from "../usage/ai-usage-wire.js";
+// lockdown-423: exempt — a READ-ONLY usage report that writes nothing to the
+// workspace, the posture of ai/billing/credits beside it: a billing-locked
+// owner working out who spent the credits needs this table more, not less.
+/**
+ * WHO IS GENERATING WHAT, PER SITE (AGL-2928) — the customer's read of the
+ * per-user AI usage rollup.
+ *
+ * ## Three questions, one route
+ *
+ * - **The month's table** (`orgId`, `month`): every current member with a
+ *   month document, dearest first, with each person's share of the
+ *   workspace's spend. Gated on `billing.view`, the Usage page's gate, and
+ *   served as JSON or — `format=csv` — as a streamed file.
+ * - **One person** (`uid`): that person's months, newest first, for the
+ *   member detail card. The subject reads their own; anyone else needs
+ *   `billing.view` or `org.auditLog`, which is the team page's gate and the
+ *   pair the security rules admit for the same documents.
+ * - **One site** (`hostId`): the table with each row's credits ON THAT SITE
+ *   beside it, for the site's collaborators card — the agency question,
+ *   "which client site's collaborators spend".
+ *
+ * ## No dollar figure crosses this boundary
+ *
+ * The month document carries `estCostUsd`, our provider bill. The rows here
+ * carry credits and a SHARE, and the share is computed on the dollars
+ * server-side (`aiUsageShare`) so it is exact — a roster's credits each round
+ * up, the org's round once — without the dollars ever being serialized.
+ *
+ * ## The month bound
+ *
+ * `month` must be inside the retention window (`aiUsageMonthKeys`): a
+ * request for an older month is refused rather than answered empty, because
+ * "nothing for that month" and "that month has been reaped" must not read
+ * the same on a report somebody exports.
+ */ /** The most months one person's card is handed. */ const MAX_USER_MONTHS = 13;
+const json = (body, status)=>Response.json(body, {
+        status
+    });
+async function handler(request) {
+    var _headers_authorization, _params_orgId, _params_month, _params_uid, _params_hostId, _params_format;
+    const { method, query, headers: rawHeaders } = await pluginRequestFromWeb(request);
+    const headers = rawHeaders;
+    if (method !== 'GET') return json({
+        error: 'Method not allowed'
+    }, 405);
+    const authorization = (_headers_authorization = headers.authorization) != null ? _headers_authorization : '';
+    const idToken = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length) : undefined;
+    if (!idToken) return json({
+        error: 'Unauthenticated'
+    }, 401);
+    const params = query != null ? query : {};
+    const orgId = String((_params_orgId = params['orgId']) != null ? _params_orgId : '').trim();
+    if (!orgId) return json({
+        error: 'Missing orgId'
+    }, 400);
+    const now = new Date();
+    const months = aiUsageMonthKeys(now);
+    const month = String((_params_month = params['month']) != null ? _params_month : months[0]).trim();
+    if (!aiUsageMonthWithinRetention(month, now)) {
+        return json({
+            error: `AI usage is kept for ${months.length} months; ` + `ask for one of ${months[months.length - 1]} through ${months[0]}.`
+        }, 400);
+    }
+    const subjectUid = String((_params_uid = params['uid']) != null ? _params_uid : '').trim();
+    const hostId = String((_params_hostId = params['hostId']) != null ? _params_hostId : '').trim();
+    const format = String((_params_format = params['format']) != null ? _params_format : 'json').trim();
+    try {
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        if (!decoded.email_verified && !isImpersonationSession(decoded)) {
+            return emailUnverifiedResponse();
+        }
+        const staff = decoded['staff'] === true;
+        const membership = await resolveOrgMembership(decoded.uid, orgId);
+        const member = membership == null ? void 0 : membership.member;
+        if (!member && !staff) return json({
+            error: 'Not found'
+        }, 404);
+        const firestore = firebaseAdmin.app().firestore();
+        if (subjectUid) {
+            var _params_limit;
+            // One person. Their own months are theirs to read; anyone else's need
+            // the Usage page's permission or the team page's.
+            const own = subjectUid === decoded.uid && Boolean(member);
+            if (!own && !staff) {
+                const allowed = await memberHasOrgPermission(orgId, member, 'billing.view') || await memberHasOrgPermission(orgId, member, 'org.auditLog');
+                if (!allowed) return json({
+                    error: 'billing.view required'
+                }, 403);
+            }
+            const limit = Math.min(MAX_USER_MONTHS, Math.max(1, Math.floor(Number((_params_limit = params['limit']) != null ? _params_limit : 2) || 2)));
+            const rows = await readUserAiUsageMonths(firestore, orgId, subjectUid, limit);
+            const orgRef = firestore.collection('orgs').doc(orgId);
+            const rollups = rows.length ? await firestore.getAll(...rows.map((row)=>orgRef.collection('assistUsage').doc(row.month))) : [];
+            const wire = {
+                uid: subjectUid,
+                months: rows.map((row, index)=>{
+                    var _ref;
+                    var _rollups_index;
+                    return {
+                        month: row.month,
+                        credits: row.credits,
+                        share: aiUsageShare(row.estCostUsd, Number((_ref = (_rollups_index = rollups[index]) == null ? void 0 : _rollups_index.get('estCostUsd')) != null ? _ref : 0)),
+                        requests: row.requests,
+                        refusals: row.refusals,
+                        byKind: row.byKind,
+                        byHost: row.byHost
+                    };
+                })
+            };
+            return json(wire, 200);
+        }
+        // The table, which is about everyone: the Usage page's permission.
+        if (!staff && !await memberHasOrgPermission(orgId, member, 'billing.view')) {
+            return json({
+                error: 'billing.view required'
+            }, 403);
+        }
+        const usage = await readOrgAiUsageByUser(firestore, orgId, month);
+        const rows = usage.rows.map((row)=>toAiUsageWireRow(row, hostId));
+        if (hostId) {
+            rows.sort((a, b)=>{
+                var _b_hostCredits, _a_hostCredits;
+                return ((_b_hostCredits = b.hostCredits) != null ? _b_hostCredits : 0) - ((_a_hostCredits = a.hostCredits) != null ? _a_hostCredits : 0) || b.credits - a.credits;
+            });
+        }
+        if (format !== 'csv') {
+            const table = {
+                month,
+                months,
+                orgCredits: usage.orgCredits,
+                rows
+            };
+            return json(table, 200);
+        }
+        /*
+     * The file, streamed: the header first, then the rows in pages, so a
+     * roster of any size arrives without being held whole. The row count
+     * travels in a header the client checks the body against — a stream
+     * that dies halfway yields a well-formed shorter file, and nothing about
+     * the bytes says it is short.
+     */ const encoder = new TextEncoder();
+        const PAGE = 200;
+        let cursor = 0;
+        let headed = false;
+        const stream = new ReadableStream({
+            pull (controller) {
+                if (!headed) {
+                    headed = true;
+                    controller.enqueue(encoder.encode(AI_USAGE_CSV_HEADER.map(csvCell).join(',')));
+                    return;
+                }
+                if (cursor < rows.length) {
+                    const page = rows.slice(cursor, cursor + PAGE);
+                    cursor += page.length;
+                    controller.enqueue(encoder.encode(`\n${page.map(aiUsageCsvLine).join('\n')}`));
+                    return;
+                }
+                controller.enqueue(encoder.encode('\n'));
+                controller.close();
+            }
+        });
+        // Ids and counts only, never content: a report about people leaving
+        // the platform is worth a row; who was in it is the workspace's own.
+        void firestore.collection('adminAudit').add({
+            actorUid: decoded.uid,
+            action: 'ai-usage.exported',
+            target: `orgs/${orgId}/aiUsageByUser`,
+            before: null,
+            after: {
+                month,
+                rows: rows.length,
+                hostId: hostId || null
+            },
+            at: FieldValue.serverTimestamp()
+        }).catch(()=>undefined);
+        return new Response(stream, {
+            status: 200,
+            headers: {
+                'Content-Type': 'text/csv; charset=utf-8',
+                'Content-Disposition': `attachment; filename="ai-usage-${month}.csv"`,
+                [AI_USAGE_EXPORT_ROWS_HEADER]: String(rows.length),
+                'Cache-Control': 'no-store, private'
+            }
+        });
+    } catch (error) {
+        // A refused credential is a 401, not a fault of ours (AGL-1993). Null
+        // for anything else, so a real failure keeps the answer below.
+        const unauthenticated = invalidIdTokenResponse(error);
+        if (unauthenticated) return unauthenticated;
+        console.error('[ai/usage] read failed', orgId, error);
+        return json({
+            error: 'AI usage unavailable'
+        }, 500);
+    }
+}
+export { handler as GET };
+
+//# sourceMappingURL=ai-usage.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-usage.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 { csvCell, pluginRequestFromWeb } from '@aglyn/aglyn/server'\nimport {\n  emailUnverifiedResponse,\n  firebaseAdmin,\n  isImpersonationSession,\n  memberHasOrgPermission,\n  resolveOrgMembership,\n} from '@aglyn/tenant-data-admin'\nimport {\n  aiUsageMonthKeys,\n  aiUsageMonthWithinRetention,\n  aiUsageShare,\n  type AiUsageByUserMonth,\n} from '../model/ai-usage-by-user'\nimport {\n  readOrgAiUsageByUser,\n  readUserAiUsageMonths,\n} from '../usage/ai-usage-by-user'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport {\n  AI_USAGE_CSV_HEADER,\n  AI_USAGE_EXPORT_ROWS_HEADER,\n  aiUsageCsvLine,\n  toAiUsageWireRow,\n  type OrgAiUsageTableWire,\n  type UserAiUsageWire,\n} from '../usage/ai-usage-wire'\n\n// lockdown-423: exempt — a READ-ONLY usage report that writes nothing to the\n// workspace, the posture of ai/billing/credits beside it: a billing-locked\n// owner working out who spent the credits needs this table more, not less.\n\n/**\n * WHO IS GENERATING WHAT, PER SITE (AGL-2928) — the customer's read of the\n * per-user AI usage rollup.\n *\n * ## Three questions, one route\n *\n * - **The month's table** (`orgId`, `month`): every current member with a\n *   month document, dearest first, with each person's share of the\n *   workspace's spend. Gated on `billing.view`, the Usage page's gate, and\n *   served as JSON or — `format=csv` — as a streamed file.\n * - **One person** (`uid`): that person's months, newest first, for the\n *   member detail card. The subject reads their own; anyone else needs\n *   `billing.view` or `org.auditLog`, which is the team page's gate and the\n *   pair the security rules admit for the same documents.\n * - **One site** (`hostId`): the table with each row's credits ON THAT SITE\n *   beside it, for the site's collaborators card — the agency question,\n *   \"which client site's collaborators spend\".\n *\n * ## No dollar figure crosses this boundary\n *\n * The month document carries `estCostUsd`, our provider bill. The rows here\n * carry credits and a SHARE, and the share is computed on the dollars\n * server-side (`aiUsageShare`) so it is exact — a roster's credits each round\n * up, the org's round once — without the dollars ever being serialized.\n *\n * ## The month bound\n *\n * `month` must be inside the retention window (`aiUsageMonthKeys`): a\n * request for an older month is refused rather than answered empty, because\n * \"nothing for that month\" and \"that month has been reaped\" must not read\n * the same on a report somebody exports.\n */\n\n/** The most months one person's card is handed. */\nconst MAX_USER_MONTHS = 13\n\nconst json = (body: unknown, status: number) => Response.json(body, { status })\n\nasync function handler(request: Request): Promise<Response> {\n  const { method, query, headers: rawHeaders } = await pluginRequestFromWeb(request)\n  const headers = rawHeaders as Partial<Record<string, string>>\n  if (method !== 'GET') return json({ error: 'Method not allowed' }, 405)\n\n  const authorization = headers.authorization ?? ''\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return json({ error: 'Unauthenticated' }, 401)\n\n  const params = (query ?? {}) as Record<string, unknown>\n  const orgId = String(params['orgId'] ?? '').trim()\n  if (!orgId) return json({ error: 'Missing orgId' }, 400)\n  const now = new Date()\n  const months = aiUsageMonthKeys(now)\n  const month = String(params['month'] ?? months[0]).trim()\n  if (!aiUsageMonthWithinRetention(month, now)) {\n    return json(\n      {\n        error:\n          `AI usage is kept for ${months.length} months; ` +\n          `ask for one of ${months[months.length - 1]} through ${months[0]}.`,\n      },\n      400,\n    )\n  }\n  const subjectUid = String(params['uid'] ?? '').trim()\n  const hostId = String(params['hostId'] ?? '').trim()\n  const format = String(params['format'] ?? 'json').trim()\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    if (!decoded.email_verified && !isImpersonationSession(decoded)) {\n      return emailUnverifiedResponse()\n    }\n    const staff = decoded['staff'] === true\n    const membership = await resolveOrgMembership(decoded.uid, orgId)\n    const member = membership?.member\n    if (!member && !staff) return json({ error: 'Not found' }, 404)\n\n    const firestore = firebaseAdmin.app().firestore()\n\n    if (subjectUid) {\n      // One person. Their own months are theirs to read; anyone else's need\n      // the Usage page's permission or the team page's.\n      const own = subjectUid === decoded.uid && Boolean(member)\n      if (!own && !staff) {\n        const allowed =\n          (await memberHasOrgPermission(orgId, member, 'billing.view')) ||\n          (await memberHasOrgPermission(orgId, member, 'org.auditLog'))\n        if (!allowed) return json({ error: 'billing.view required' }, 403)\n      }\n      const limit = Math.min(\n        MAX_USER_MONTHS,\n        Math.max(1, Math.floor(Number(params['limit'] ?? 2) || 2)),\n      )\n      const rows = await readUserAiUsageMonths(firestore, orgId, subjectUid, limit)\n      const orgRef = firestore.collection('orgs').doc(orgId)\n      const rollups = rows.length\n        ? await firestore.getAll(\n            ...rows.map((row) => orgRef.collection('assistUsage').doc(row.month)),\n          )\n        : []\n      const wire: UserAiUsageWire = {\n        uid: subjectUid,\n        months: rows.map((row: AiUsageByUserMonth, index) => ({\n          month: row.month,\n          credits: row.credits,\n          share: aiUsageShare(\n            row.estCostUsd,\n            Number(rollups[index]?.get('estCostUsd') ?? 0),\n          ),\n          requests: row.requests,\n          refusals: row.refusals,\n          byKind: row.byKind,\n          byHost: row.byHost,\n        })),\n      }\n      return json(wire, 200)\n    }\n\n    // The table, which is about everyone: the Usage page's permission.\n    if (!staff && !(await memberHasOrgPermission(orgId, member, 'billing.view'))) {\n      return json({ error: 'billing.view required' }, 403)\n    }\n    const usage = await readOrgAiUsageByUser(firestore, orgId, month)\n    const rows = usage.rows.map((row) => toAiUsageWireRow(row, hostId))\n    if (hostId) {\n      rows.sort(\n        (a, b) =>\n          (b.hostCredits ?? 0) - (a.hostCredits ?? 0) || b.credits - a.credits,\n      )\n    }\n\n    if (format !== 'csv') {\n      const table: OrgAiUsageTableWire = {\n        month,\n        months,\n        orgCredits: usage.orgCredits,\n        rows,\n      }\n      return json(table, 200)\n    }\n\n    /*\n     * The file, streamed: the header first, then the rows in pages, so a\n     * roster of any size arrives without being held whole. The row count\n     * travels in a header the client checks the body against — a stream\n     * that dies halfway yields a well-formed shorter file, and nothing about\n     * the bytes says it is short.\n     */\n    const encoder = new TextEncoder()\n    const PAGE = 200\n    let cursor = 0\n    let headed = false\n    const stream = new ReadableStream<Uint8Array>({\n      pull(controller) {\n        if (!headed) {\n          headed = true\n          controller.enqueue(encoder.encode(AI_USAGE_CSV_HEADER.map(csvCell).join(',')))\n          return\n        }\n        if (cursor < rows.length) {\n          const page = rows.slice(cursor, cursor + PAGE)\n          cursor += page.length\n          controller.enqueue(\n            encoder.encode(`\\n${page.map(aiUsageCsvLine).join('\\n')}`),\n          )\n          return\n        }\n        controller.enqueue(encoder.encode('\\n'))\n        controller.close()\n      },\n    })\n\n    // Ids and counts only, never content: a report about people leaving\n    // the platform is worth a row; who was in it is the workspace's own.\n    void firestore\n      .collection('adminAudit')\n      .add({\n        actorUid: decoded.uid,\n        action: 'ai-usage.exported',\n        target: `orgs/${orgId}/aiUsageByUser`,\n        before: null,\n        after: { month, rows: rows.length, hostId: hostId || null },\n        at: FieldValue.serverTimestamp(),\n      })\n      .catch(() => undefined)\n\n    return new Response(stream, {\n      status: 200,\n      headers: {\n        'Content-Type': 'text/csv; charset=utf-8',\n        'Content-Disposition': `attachment; filename=\"ai-usage-${month}.csv\"`,\n        [AI_USAGE_EXPORT_ROWS_HEADER]: String(rows.length),\n        'Cache-Control': 'no-store, private',\n      },\n    })\n  } catch (error) {\n    // A refused credential is a 401, not a fault of ours (AGL-1993). Null\n    // for anything else, so a real failure keeps the answer below.\n    const unauthenticated = invalidIdTokenResponse(error)\n    if (unauthenticated) return unauthenticated\n    console.error('[ai/usage] read failed', orgId, error)\n    return json({ error: 'AI usage unavailable' }, 500)\n  }\n}\n\nexport { handler as GET }\n"],"names":["csvCell","pluginRequestFromWeb","emailUnverifiedResponse","firebaseAdmin","isImpersonationSession","memberHasOrgPermission","resolveOrgMembership","aiUsageMonthKeys","aiUsageMonthWithinRetention","aiUsageShare","readOrgAiUsageByUser","readUserAiUsageMonths","FieldValue","invalidIdTokenResponse","AI_USAGE_CSV_HEADER","AI_USAGE_EXPORT_ROWS_HEADER","aiUsageCsvLine","toAiUsageWireRow","MAX_USER_MONTHS","json","body","status","Response","handler","request","headers","params","method","query","rawHeaders","error","authorization","idToken","startsWith","slice","length","undefined","orgId","String","trim","now","Date","months","month","subjectUid","hostId","format","decoded","app","auth","verifyIdToken","email_verified","staff","membership","uid","member","firestore","own","Boolean","allowed","limit","Math","min","max","floor","Number","rows","orgRef","collection","doc","rollups","getAll","map","row","wire","index","credits","share","estCostUsd","get","requests","refusals","byKind","byHost","usage","sort","a","b","hostCredits","table","orgCredits","encoder","TextEncoder","PAGE","cursor","headed","stream","ReadableStream","pull","controller","enqueue","encode","join","page","close","add","actorUid","action","target","before","after","at","serverTimestamp","catch","unauthenticated","console","GET"],"mappings":"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"}