@aglyn/plugins-ai 1.0.0-beta.225 → 1.0.0-beta.227

package/src/lib/runtime/site-inventory.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type AiInventoryTheme, type AiSiteInventory } from '../model/ai-site-inventory';
+import { type AiInventoryScreen, type AiInventoryTheme, type AiSiteInventory } from '../model/ai-site-inventory';
 /**
  * The reader behind the site inventory (AGL-2935): one site's components,
  * layouts, templates, forms, datasets, content collections, screens and
@@ -46,6 +46,21 @@ export interface ReadSiteInventoryOptions {
 }
 /** The theme a site renders with, reduced to what a plan and an email can act on. */
 export declare function aiInventoryTheme(host: Data | null): AiInventoryTheme | null;
+/**
+ * The screen a site's starter home may be (AGL-3594, AGL-3408): the one
+ * `host.defaultHomeScreenId` names, while it still answers `/` in the routing
+ * map and is listed as a page. `null` on every site whose owner published a
+ * home page of their own, which clears the marker (AGL-3478), and on every
+ * site created before the marker existed, whose home page is the owner's.
+ */
+export declare function aiStarterHomeCandidate(host: Readonly<Record<string, unknown>> | null, screens: ReadonlyArray<Pick<AiInventoryScreen, 'id' | 'template'>>): string | null;
+/**
+ * Whether the starter home is as the platform wrote it: its one version is
+ * the one it was provisioned and published with. A version saved in the
+ * editor is an edit, published or not, and an edited starter is the owner's
+ * page — a plan keeps it.
+ */
+export declare function aiStarterHomeUntouched(publishedVersionId: string, versionIds: readonly string[]): boolean;
 /**
  * Read one site's inventory for a generation.
  *

package/src/lib/runtime/site-inventory.js

@@ -18,7 +18,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { isFormArchived } from "@aglyn/aglyn/app-utils/forms";
 import { describeTheme, resolveSiteTheme } from "@aglyn/aglyn/app-utils/site-theme";
 import { REUSABLE_COMPONENT_KIND_EMAIL, reusableComponentKindOf } from "@aglyn/aglyn/app-utils/reusable-component-kind";
-import { SCREEN_KIND_TEMPLATE } from "@aglyn/aglyn/app-utils/screen-route";
+import { SCREEN_KIND_TEMPLATE, SCREEN_ROOT_PATH } from "@aglyn/aglyn/app-utils/screen-route";
 import { pluginRecordIndex } from "@aglyn/aglyn/plugin-manager/plugin-record-index";
 import { firebaseAdmin } from "@aglyn/tenant-data-admin/server/firebase-admin";
 import { resolveOrgIdForHost } from "@aglyn/tenant-data-admin/server/organizations";
@@ -79,6 +79,28 @@ async function readWindow(query, fields, cap, map) {
         truncated: snapshot.docs.length > cap
     };
 }
+/**
+ * The screen a site's starter home may be (AGL-3594, AGL-3408): the one
+ * `host.defaultHomeScreenId` names, while it still answers `/` in the routing
+ * map and is listed as a page. `null` on every site whose owner published a
+ * home page of their own, which clears the marker (AGL-3478), and on every
+ * site created before the marker existed, whose home page is the owner's.
+ */ export function aiStarterHomeCandidate(host, screens) {
+    const id = text(host == null ? void 0 : host['defaultHomeScreenId']);
+    if (!id) return null;
+    const routing = host == null ? void 0 : host['screens'];
+    const path = routing && typeof routing === 'object' ? routing[id] : undefined;
+    if (path !== SCREEN_ROOT_PATH) return null;
+    return screens.some((screen)=>screen.id === id && !screen.template) ? id : null;
+}
+/**
+ * Whether the starter home is as the platform wrote it: its one version is
+ * the one it was provisioned and published with. A version saved in the
+ * editor is an edit, published or not, and an edited starter is the owner's
+ * page — a plan keeps it.
+ */ export function aiStarterHomeUntouched(publishedVersionId, versionIds) {
+    return Boolean(publishedVersionId) && versionIds.length === 1 && versionIds[0] === publishedVersionId;
+}
 /**
  * The org's datasets shared with the site, through the `dataset` index the
  * data plugin publishes (AGL-3080) rather than its collection: their names
@@ -130,6 +152,9 @@ async function readWindow(query, fields, cap, map) {
     const firestore = (_options_firestore = options.firestore) != null ? _options_firestore : firebaseAdmin.app().firestore();
     const cap = Math.min(AI_SITE_INVENTORY_MAX_PER_KIND, Math.max(1, Math.floor((_options_maxPerKind = options.maxPerKind) != null ? _options_maxPerKind : AI_SITE_INVENTORY_MAX_PER_KIND)));
     const host = firestore.collection('hosts').doc(hostId);
+    // Each listed screen's published version, read in the same window, for the
+    // starter home's untouched test below.
+    const screenVersions = new Map();
     const [components, layouts, templates, forms, datasets, collections, screens, hostDoc] = await Promise.all([
         readWindow(host.collection('components'), [
             'displayName',
@@ -208,11 +233,13 @@ async function readWindow(query, fields, cap, map) {
             'slug',
             'layoutId',
             'kind',
-            'deletedAt'
+            'deletedAt',
+            'versionId'
         ], cap, (id, data)=>{
             const kind = text(data['kind']);
             // An email design and an error body are not pages a plan links or duplicates.
             if (data['deletedAt'] || kind && kind !== SCREEN_KIND_TEMPLATE) return null;
+            screenVersions.set(id, text(data['versionId']));
             return {
                 id,
                 name: nameOf(data, id, 'displayName', 'slug'),
@@ -223,6 +250,19 @@ async function readWindow(query, fields, cap, map) {
         }),
         host.get()
     ]);
+    const hostData = hostDoc.exists ? (_hostDoc_data = hostDoc.data()) != null ? _hostDoc_data : {} : null;
+    const starter = aiStarterHomeCandidate(hostData, screens.rows);
+    if (starter) {
+        var _screenVersions_get;
+        // One more read, and only on a site that still carries the marker: the
+        // starter's versions, of which an untouched one has exactly the one it
+        // was provisioned with.
+        const versions = await host.collection('screens').doc(starter).collection('versions').select().limit(2).get();
+        if (aiStarterHomeUntouched((_screenVersions_get = screenVersions.get(starter)) != null ? _screenVersions_get : '', versions.docs.map((doc)=>doc.id))) {
+            const row = screens.rows.find((screen)=>screen.id === starter);
+            if (row) row.replaceable = true;
+        }
+    }
     const windows = {
         components,
         layouts,
@@ -241,7 +281,7 @@ async function readWindow(query, fields, cap, map) {
         datasets: datasets.rows,
         collections: collections.rows,
         screens: screens.rows,
-        theme: aiInventoryTheme(hostDoc.exists ? (_hostDoc_data = hostDoc.data()) != null ? _hostDoc_data : {} : null),
+        theme: aiInventoryTheme(hostData),
         truncated: AI_INVENTORY_KINDS.filter((kind)=>windows[kind].truncated)
     };
 }

package/src/lib/runtime/site-inventory.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/site-inventory.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 { hostCollectionKind } from '@aglyn/aglyn/app-utils/collection-kind'\nimport { isFormArchived } from '@aglyn/aglyn/app-utils/forms'\nimport {\n  describeTheme,\n  resolveSiteTheme,\n  type ThemeHostDocument,\n} from '@aglyn/aglyn/app-utils/site-theme'\nimport {\n  REUSABLE_COMPONENT_KIND_EMAIL,\n  reusableComponentKindOf,\n} from '@aglyn/aglyn/app-utils/reusable-component-kind'\nimport { SCREEN_KIND_TEMPLATE } from '@aglyn/aglyn/app-utils/screen-route'\nimport { pluginRecordIndex } from '@aglyn/aglyn/plugin-manager/plugin-record-index'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations'\nimport {\n  AI_INVENTORY_KINDS,\n  AI_SITE_INVENTORY_MAX_PER_KIND,\n  AiInventoryScopeError,\n  type AiComponentPropTypes,\n  type AiInventoryCollection,\n  type AiInventoryComponent,\n  type AiInventoryDataset,\n  type AiInventoryForm,\n  type AiInventoryKind,\n  type AiInventoryLayout,\n  type AiInventoryScreen,\n  type AiInventoryTemplate,\n  type AiInventoryTheme,\n  type AiSiteInventory,\n} from '../model/ai-site-inventory'\nimport { aiBracketedFacts } from './ai-doctrine-validators'\n\n/**\n * The reader behind the site inventory (AGL-2935): one site's components,\n * layouts, templates, forms, datasets, content collections, screens and\n * theme, read as projections through the Admin SDK and reduced to the\n * compact shape `model/ai-site-inventory.ts` describes.\n *\n * Every kind is a projection (`select`) of the fields the inventory names —\n * never a node map, never a record's content — read one row past the cap so\n * a full page is told apart from a cut one. Retired rows (soft-deleted,\n * archived, a component never published) are filtered after the read, so a\n * site with many retired rows can list fewer than the cap; the kind is still\n * marked truncated when the read was cut, which is the honest answer.\n *\n * The window is WIDER than the prompt lists (AGL-2937). The prompt block\n * lists `AI_SITE_INVENTORY_LISTED_PER_KIND` records of a kind because every\n * character of it is billed on every attempt; the rest of the window is what\n * the lookup tool searches, and a record never read cannot be found. The\n * difference is paid in document reads rather than tokens — a projection of\n * a few fields, once per job step — which is the cheaper of the two by some\n * orders of magnitude.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\ntype Data = Record<string, unknown>\n\nexport interface ReadSiteInventoryOptions {\n  /** The Admin SDK handle; the platform's default app when absent. */\n  firestore?: Firestore\n  /** Rows read per kind; `AI_SITE_INVENTORY_MAX_PER_KIND` when absent, and never above it. */\n  maxPerKind?: number\n}\n\nfunction text(value: unknown): string {\n  return typeof value === 'string' ? value.trim() : ''\n}\n\n/** A record's name, or its id when it was saved without one. */\nfunction nameOf(data: Data, id: string, ...fields: string[]): string {\n  for (const field of fields) {\n    const value = text(data[field])\n    if (value) return value\n  }\n  return id\n}\n\n/** The flat `path → color` leaves of one scheme, e.g. `primary.main`. */\nfunction schemeColors(scheme: unknown): Record<string, string> {\n  const colors: Record<string, string> = {}\n  const visit = (value: unknown, path: string) => {\n    if (typeof value === 'string') {\n      if (path) colors[path] = value\n      return\n    }\n    if (!value || typeof value !== 'object' || Array.isArray(value)) return\n    for (const [key, inner] of Object.entries(value as Data)) {\n      visit(inner, path ? `${path}.${key}` : key)\n    }\n  }\n  visit(scheme, '')\n  return colors\n}\n\n/** The theme a site renders with, reduced to what a plan and an email can act on. */\nexport function aiInventoryTheme(host: Data | null): AiInventoryTheme | null {\n  const theme = resolveSiteTheme(host as ThemeHostDocument | null)\n  if (!theme) return null\n  const fonts = new Set<string>()\n  for (const font of theme.fonts ?? []) {\n    if (text(font?.family)) fonts.add(text(font.family))\n  }\n  return {\n    summary: describeTheme(theme),\n    colors: schemeColors(theme.colorSchemes?.light),\n    fonts: [...fonts],\n  }\n}\n\ninterface Window<T> {\n  rows: T[]\n  truncated: boolean\n}\n\nasync function readWindow<T>(\n  query: FirebaseFirestore.Query,\n  fields: string[],\n  cap: number,\n  map: (id: string, data: Data) => T | null,\n): Promise<Window<T>> {\n  const snapshot = await query\n    .select(...fields)\n    .limit(cap + 1)\n    .get()\n  const rows: T[] = []\n  for (const doc of snapshot.docs.slice(0, cap)) {\n    const row = map(doc.id, (doc.data() ?? {}) as Data)\n    if (row) rows.push(row)\n  }\n  return { rows, truncated: snapshot.docs.length > cap }\n}\n\n/**\n * The org's datasets shared with the site, through the `dataset` index the\n * data plugin publishes (AGL-3080) rather than its collection: their names\n * and their fields' names, in the dataset page's order. None where no plugin\n * keeps datasets here.\n */\nasync function readIndexedDatasets(\n  orgId: string,\n  hostId: string,\n  cap: number,\n): Promise<Window<AiInventoryDataset>> {\n  const datasets = pluginRecordIndex('dataset')\n  if (!datasets) return { rows: [], truncated: false }\n  const { records, truncated } = await datasets.index.list({ orgId, hostId, limit: cap })\n  return {\n    rows: records.map((record) => {\n      const fields = (Array.isArray(record.facts['fields']) ? (record.facts['fields'] as Data[]) : [])\n        .map((field) => ({ id: text(field?.['id']), name: text(field?.['name']) || text(field?.['id']) }))\n        .filter((field) => field.name)\n      return {\n        id: record.id,\n        name: record.name,\n        fields: fields.map((field) => field.name),\n        fieldIds: fields.map((field) => field.id || field.name),\n      }\n    }),\n    truncated,\n  }\n}\n\n/**\n * Read one site's inventory for a generation.\n *\n * SCOPED before anything is read. The job names a site and an org, and\n * nothing the reader is handed proves the site belongs to the org, so it asks\n * the host index first and refuses a pairing it does not record: another\n * workspace's component names are not this workspace's prompt. Datasets are\n * org-owned and narrowed to what this site may see.\n *\n * Throws `AiInventoryScopeError` for a site outside the org, and lets a\n * Firestore failure propagate: a planner handed an empty inventory by\n * mistake would create everything the site already has.\n */\nexport async function readSiteInventory(\n  orgId: string,\n  hostId: string,\n  options: ReadSiteInventoryOptions = {},\n): Promise<AiSiteInventory> {\n  const owner = await resolveOrgIdForHost(hostId)\n  if (!owner || owner !== orgId) throw new AiInventoryScopeError(hostId)\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  const cap = Math.min(\n    AI_SITE_INVENTORY_MAX_PER_KIND,\n    Math.max(1, Math.floor(options.maxPerKind ?? AI_SITE_INVENTORY_MAX_PER_KIND)),\n  )\n  const host = firestore.collection('hosts').doc(hostId)\n\n  const [components, layouts, templates, forms, datasets, collections, screens, hostDoc] =\n    await Promise.all([\n      readWindow<AiInventoryComponent>(\n        host.collection('components'),\n        ['displayName', 'props', 'rootId', 'versionId', 'deletedAt', 'kind'],\n        cap,\n        (id, data) => {\n          // Soft-deleted, or never published: an instance of either renders nothing.\n          if (data['deletedAt'] || !(data['rootId'] || data['versionId'])) return null\n          // An email block (AGL-3287) is built from email elements and placed\n          // in emails alone: no page, layout or component a job builds can\n          // render one, and the email a job builds places no instances.\n          if (reusableComponentKindOf(data) === REUSABLE_COMPONENT_KIND_EMAIL) return null\n          const props: AiComponentPropTypes = {}\n          const bracketedDefaults: Record<string, string[]> = {}\n          for (const prop of Array.isArray(data['props']) ? (data['props'] as Data[]) : []) {\n            const name = text(prop?.['name'])\n            if (!name) continue\n            props[name] = text(prop['type']) || 'text'\n            const facts = aiBracketedFacts([text(prop['defaultValue'])])\n            if (facts.length) bracketedDefaults[name] = facts\n          }\n          return {\n            id,\n            name: nameOf(data, id, 'displayName'),\n            props,\n            ...(Object.keys(bracketedDefaults).length ? { bracketedDefaults } : {}),\n          }\n        },\n      ),\n      readWindow<AiInventoryLayout>(\n        host.collection('layouts'),\n        ['displayName', 'layoutId', 'deletedAt'],\n        cap,\n        (id, data) =>\n          data['deletedAt']\n            ? null\n            : {\n                id,\n                name: nameOf(data, id, 'displayName'),\n                parentId: text(data['layoutId']) || null,\n              },\n      ),\n      readWindow<AiInventoryTemplate>(\n        host.collection('templates'),\n        ['displayName', 'kind', 'deletedAt'],\n        cap,\n        (id, data) =>\n          data['deletedAt']\n            ? null\n            : { id, name: nameOf(data, id, 'displayName'), kind: text(data['kind']) || 'page' },\n      ),\n      readWindow<AiInventoryForm>(\n        host.collection('forms'),\n        ['displayName', 'slug', 'fields', 'archivedAt'],\n        cap,\n        (id, data) =>\n          isFormArchived(data as { archivedAt?: unknown })\n            ? null\n            : {\n                id,\n                name: nameOf(data, id, 'displayName', 'slug'),\n                fields: (Array.isArray(data['fields']) ? (data['fields'] as Data[]) : [])\n                  .map((field) => text(field?.['fieldName']))\n                  .filter(Boolean),\n              },\n      ),\n      readIndexedDatasets(orgId, hostId, cap),\n      readWindow<AiInventoryCollection>(\n        host.collection('collections'),\n        ['displayName', 'name', 'slug', 'kind'],\n        cap,\n        (id, data) =>\n          hostCollectionKind(data) !== 'content'\n            ? null\n            : {\n                id,\n                name: nameOf(data, id, 'displayName', 'name', 'slug'),\n                slug: text(data['slug']),\n              },\n      ),\n      readWindow<AiInventoryScreen>(\n        host.collection('screens'),\n        ['displayName', 'slug', 'layoutId', 'kind', 'deletedAt'],\n        cap,\n        (id, data) => {\n          const kind = text(data['kind'])\n          // An email design and an error body are not pages a plan links or duplicates.\n          if (data['deletedAt'] || (kind && kind !== SCREEN_KIND_TEMPLATE)) return null\n          return {\n            id,\n            name: nameOf(data, id, 'displayName', 'slug'),\n            slug: text(data['slug']),\n            layoutId: text(data['layoutId']) || null,\n            template: kind === SCREEN_KIND_TEMPLATE,\n          }\n        },\n      ),\n      host.get(),\n    ])\n\n  const windows: Record<AiInventoryKind, Window<unknown>> = {\n    components,\n    layouts,\n    templates,\n    forms,\n    datasets,\n    collections,\n    screens,\n  }\n  return {\n    hostId,\n    components: components.rows,\n    layouts: layouts.rows,\n    templates: templates.rows,\n    forms: forms.rows,\n    datasets: datasets.rows,\n    collections: collections.rows,\n    screens: screens.rows,\n    theme: aiInventoryTheme(hostDoc.exists ? ((hostDoc.data() ?? {}) as Data) : null),\n    truncated: AI_INVENTORY_KINDS.filter((kind) => windows[kind].truncated),\n  }\n}\n"],"names":["hostCollectionKind","isFormArchived","describeTheme","resolveSiteTheme","REUSABLE_COMPONENT_KIND_EMAIL","reusableComponentKindOf","SCREEN_KIND_TEMPLATE","pluginRecordIndex","firebaseAdmin","resolveOrgIdForHost","AI_INVENTORY_KINDS","AI_SITE_INVENTORY_MAX_PER_KIND","AiInventoryScopeError","aiBracketedFacts","text","value","trim","nameOf","data","id","fields","field","schemeColors","scheme","colors","visit","path","Array","isArray","key","inner","Object","entries","aiInventoryTheme","host","theme","fonts","Set","font","family","add","summary","colorSchemes","light","readWindow","query","cap","map","snapshot","select","limit","get","rows","doc","docs","slice","row","push","truncated","length","readIndexedDatasets","orgId","hostId","datasets","records","index","list","record","facts","name","filter","fieldIds","readSiteInventory","options","hostDoc","owner","firestore","app","Math","min","max","floor","maxPerKind","collection","components","layouts","templates","forms","collections","screens","Promise","all","props","bracketedDefaults","prop","keys","parentId","kind","Boolean","slug","layoutId","template","windows","exists"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/runtime/site-inventory.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 { hostCollectionKind } from '@aglyn/aglyn/app-utils/collection-kind'\nimport { isFormArchived } from '@aglyn/aglyn/app-utils/forms'\nimport {\n  describeTheme,\n  resolveSiteTheme,\n  type ThemeHostDocument,\n} from '@aglyn/aglyn/app-utils/site-theme'\nimport {\n  REUSABLE_COMPONENT_KIND_EMAIL,\n  reusableComponentKindOf,\n} from '@aglyn/aglyn/app-utils/reusable-component-kind'\nimport { SCREEN_KIND_TEMPLATE, SCREEN_ROOT_PATH } from '@aglyn/aglyn/app-utils/screen-route'\nimport { pluginRecordIndex } from '@aglyn/aglyn/plugin-manager/plugin-record-index'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { resolveOrgIdForHost } from '@aglyn/tenant-data-admin/server/organizations'\nimport {\n  AI_INVENTORY_KINDS,\n  AI_SITE_INVENTORY_MAX_PER_KIND,\n  AiInventoryScopeError,\n  type AiComponentPropTypes,\n  type AiInventoryCollection,\n  type AiInventoryComponent,\n  type AiInventoryDataset,\n  type AiInventoryForm,\n  type AiInventoryKind,\n  type AiInventoryLayout,\n  type AiInventoryScreen,\n  type AiInventoryTemplate,\n  type AiInventoryTheme,\n  type AiSiteInventory,\n} from '../model/ai-site-inventory'\nimport { aiBracketedFacts } from './ai-doctrine-validators'\n\n/**\n * The reader behind the site inventory (AGL-2935): one site's components,\n * layouts, templates, forms, datasets, content collections, screens and\n * theme, read as projections through the Admin SDK and reduced to the\n * compact shape `model/ai-site-inventory.ts` describes.\n *\n * Every kind is a projection (`select`) of the fields the inventory names —\n * never a node map, never a record's content — read one row past the cap so\n * a full page is told apart from a cut one. Retired rows (soft-deleted,\n * archived, a component never published) are filtered after the read, so a\n * site with many retired rows can list fewer than the cap; the kind is still\n * marked truncated when the read was cut, which is the honest answer.\n *\n * The window is WIDER than the prompt lists (AGL-2937). The prompt block\n * lists `AI_SITE_INVENTORY_LISTED_PER_KIND` records of a kind because every\n * character of it is billed on every attempt; the rest of the window is what\n * the lookup tool searches, and a record never read cannot be found. The\n * difference is paid in document reads rather than tokens — a projection of\n * a few fields, once per job step — which is the cheaper of the two by some\n * orders of magnitude.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\ntype Data = Record<string, unknown>\n\nexport interface ReadSiteInventoryOptions {\n  /** The Admin SDK handle; the platform's default app when absent. */\n  firestore?: Firestore\n  /** Rows read per kind; `AI_SITE_INVENTORY_MAX_PER_KIND` when absent, and never above it. */\n  maxPerKind?: number\n}\n\nfunction text(value: unknown): string {\n  return typeof value === 'string' ? value.trim() : ''\n}\n\n/** A record's name, or its id when it was saved without one. */\nfunction nameOf(data: Data, id: string, ...fields: string[]): string {\n  for (const field of fields) {\n    const value = text(data[field])\n    if (value) return value\n  }\n  return id\n}\n\n/** The flat `path → color` leaves of one scheme, e.g. `primary.main`. */\nfunction schemeColors(scheme: unknown): Record<string, string> {\n  const colors: Record<string, string> = {}\n  const visit = (value: unknown, path: string) => {\n    if (typeof value === 'string') {\n      if (path) colors[path] = value\n      return\n    }\n    if (!value || typeof value !== 'object' || Array.isArray(value)) return\n    for (const [key, inner] of Object.entries(value as Data)) {\n      visit(inner, path ? `${path}.${key}` : key)\n    }\n  }\n  visit(scheme, '')\n  return colors\n}\n\n/** The theme a site renders with, reduced to what a plan and an email can act on. */\nexport function aiInventoryTheme(host: Data | null): AiInventoryTheme | null {\n  const theme = resolveSiteTheme(host as ThemeHostDocument | null)\n  if (!theme) return null\n  const fonts = new Set<string>()\n  for (const font of theme.fonts ?? []) {\n    if (text(font?.family)) fonts.add(text(font.family))\n  }\n  return {\n    summary: describeTheme(theme),\n    colors: schemeColors(theme.colorSchemes?.light),\n    fonts: [...fonts],\n  }\n}\n\ninterface Window<T> {\n  rows: T[]\n  truncated: boolean\n}\n\nasync function readWindow<T>(\n  query: FirebaseFirestore.Query,\n  fields: string[],\n  cap: number,\n  map: (id: string, data: Data) => T | null,\n): Promise<Window<T>> {\n  const snapshot = await query\n    .select(...fields)\n    .limit(cap + 1)\n    .get()\n  const rows: T[] = []\n  for (const doc of snapshot.docs.slice(0, cap)) {\n    const row = map(doc.id, (doc.data() ?? {}) as Data)\n    if (row) rows.push(row)\n  }\n  return { rows, truncated: snapshot.docs.length > cap }\n}\n\n/**\n * The screen a site's starter home may be (AGL-3594, AGL-3408): the one\n * `host.defaultHomeScreenId` names, while it still answers `/` in the routing\n * map and is listed as a page. `null` on every site whose owner published a\n * home page of their own, which clears the marker (AGL-3478), and on every\n * site created before the marker existed, whose home page is the owner's.\n */\nexport function aiStarterHomeCandidate(\n  host: Readonly<Record<string, unknown>> | null,\n  screens: ReadonlyArray<Pick<AiInventoryScreen, 'id' | 'template'>>,\n): string | null {\n  const id = text(host?.['defaultHomeScreenId'])\n  if (!id) return null\n  const routing = host?.['screens']\n  const path =\n    routing && typeof routing === 'object' ? (routing as Record<string, unknown>)[id] : undefined\n  if (path !== SCREEN_ROOT_PATH) return null\n  return screens.some((screen) => screen.id === id && !screen.template) ? id : null\n}\n\n/**\n * Whether the starter home is as the platform wrote it: its one version is\n * the one it was provisioned and published with. A version saved in the\n * editor is an edit, published or not, and an edited starter is the owner's\n * page — a plan keeps it.\n */\nexport function aiStarterHomeUntouched(\n  publishedVersionId: string,\n  versionIds: readonly string[],\n): boolean {\n  return Boolean(publishedVersionId) && versionIds.length === 1 && versionIds[0] === publishedVersionId\n}\n\n/**\n * The org's datasets shared with the site, through the `dataset` index the\n * data plugin publishes (AGL-3080) rather than its collection: their names\n * and their fields' names, in the dataset page's order. None where no plugin\n * keeps datasets here.\n */\nasync function readIndexedDatasets(\n  orgId: string,\n  hostId: string,\n  cap: number,\n): Promise<Window<AiInventoryDataset>> {\n  const datasets = pluginRecordIndex('dataset')\n  if (!datasets) return { rows: [], truncated: false }\n  const { records, truncated } = await datasets.index.list({ orgId, hostId, limit: cap })\n  return {\n    rows: records.map((record) => {\n      const fields = (Array.isArray(record.facts['fields']) ? (record.facts['fields'] as Data[]) : [])\n        .map((field) => ({ id: text(field?.['id']), name: text(field?.['name']) || text(field?.['id']) }))\n        .filter((field) => field.name)\n      return {\n        id: record.id,\n        name: record.name,\n        fields: fields.map((field) => field.name),\n        fieldIds: fields.map((field) => field.id || field.name),\n      }\n    }),\n    truncated,\n  }\n}\n\n/**\n * Read one site's inventory for a generation.\n *\n * SCOPED before anything is read. The job names a site and an org, and\n * nothing the reader is handed proves the site belongs to the org, so it asks\n * the host index first and refuses a pairing it does not record: another\n * workspace's component names are not this workspace's prompt. Datasets are\n * org-owned and narrowed to what this site may see.\n *\n * Throws `AiInventoryScopeError` for a site outside the org, and lets a\n * Firestore failure propagate: a planner handed an empty inventory by\n * mistake would create everything the site already has.\n */\nexport async function readSiteInventory(\n  orgId: string,\n  hostId: string,\n  options: ReadSiteInventoryOptions = {},\n): Promise<AiSiteInventory> {\n  const owner = await resolveOrgIdForHost(hostId)\n  if (!owner || owner !== orgId) throw new AiInventoryScopeError(hostId)\n  const firestore = options.firestore ?? firebaseAdmin.app().firestore()\n  const cap = Math.min(\n    AI_SITE_INVENTORY_MAX_PER_KIND,\n    Math.max(1, Math.floor(options.maxPerKind ?? AI_SITE_INVENTORY_MAX_PER_KIND)),\n  )\n  const host = firestore.collection('hosts').doc(hostId)\n  // Each listed screen's published version, read in the same window, for the\n  // starter home's untouched test below.\n  const screenVersions = new Map<string, string>()\n\n  const [components, layouts, templates, forms, datasets, collections, screens, hostDoc] =\n    await Promise.all([\n      readWindow<AiInventoryComponent>(\n        host.collection('components'),\n        ['displayName', 'props', 'rootId', 'versionId', 'deletedAt', 'kind'],\n        cap,\n        (id, data) => {\n          // Soft-deleted, or never published: an instance of either renders nothing.\n          if (data['deletedAt'] || !(data['rootId'] || data['versionId'])) return null\n          // An email block (AGL-3287) is built from email elements and placed\n          // in emails alone: no page, layout or component a job builds can\n          // render one, and the email a job builds places no instances.\n          if (reusableComponentKindOf(data) === REUSABLE_COMPONENT_KIND_EMAIL) return null\n          const props: AiComponentPropTypes = {}\n          const bracketedDefaults: Record<string, string[]> = {}\n          for (const prop of Array.isArray(data['props']) ? (data['props'] as Data[]) : []) {\n            const name = text(prop?.['name'])\n            if (!name) continue\n            props[name] = text(prop['type']) || 'text'\n            const facts = aiBracketedFacts([text(prop['defaultValue'])])\n            if (facts.length) bracketedDefaults[name] = facts\n          }\n          return {\n            id,\n            name: nameOf(data, id, 'displayName'),\n            props,\n            ...(Object.keys(bracketedDefaults).length ? { bracketedDefaults } : {}),\n          }\n        },\n      ),\n      readWindow<AiInventoryLayout>(\n        host.collection('layouts'),\n        ['displayName', 'layoutId', 'deletedAt'],\n        cap,\n        (id, data) =>\n          data['deletedAt']\n            ? null\n            : {\n                id,\n                name: nameOf(data, id, 'displayName'),\n                parentId: text(data['layoutId']) || null,\n              },\n      ),\n      readWindow<AiInventoryTemplate>(\n        host.collection('templates'),\n        ['displayName', 'kind', 'deletedAt'],\n        cap,\n        (id, data) =>\n          data['deletedAt']\n            ? null\n            : { id, name: nameOf(data, id, 'displayName'), kind: text(data['kind']) || 'page' },\n      ),\n      readWindow<AiInventoryForm>(\n        host.collection('forms'),\n        ['displayName', 'slug', 'fields', 'archivedAt'],\n        cap,\n        (id, data) =>\n          isFormArchived(data as { archivedAt?: unknown })\n            ? null\n            : {\n                id,\n                name: nameOf(data, id, 'displayName', 'slug'),\n                fields: (Array.isArray(data['fields']) ? (data['fields'] as Data[]) : [])\n                  .map((field) => text(field?.['fieldName']))\n                  .filter(Boolean),\n              },\n      ),\n      readIndexedDatasets(orgId, hostId, cap),\n      readWindow<AiInventoryCollection>(\n        host.collection('collections'),\n        ['displayName', 'name', 'slug', 'kind'],\n        cap,\n        (id, data) =>\n          hostCollectionKind(data) !== 'content'\n            ? null\n            : {\n                id,\n                name: nameOf(data, id, 'displayName', 'name', 'slug'),\n                slug: text(data['slug']),\n              },\n      ),\n      readWindow<AiInventoryScreen>(\n        host.collection('screens'),\n        ['displayName', 'slug', 'layoutId', 'kind', 'deletedAt', 'versionId'],\n        cap,\n        (id, data) => {\n          const kind = text(data['kind'])\n          // An email design and an error body are not pages a plan links or duplicates.\n          if (data['deletedAt'] || (kind && kind !== SCREEN_KIND_TEMPLATE)) return null\n          screenVersions.set(id, text(data['versionId']))\n          return {\n            id,\n            name: nameOf(data, id, 'displayName', 'slug'),\n            slug: text(data['slug']),\n            layoutId: text(data['layoutId']) || null,\n            template: kind === SCREEN_KIND_TEMPLATE,\n          }\n        },\n      ),\n      host.get(),\n    ])\n\n  const hostData = hostDoc.exists ? ((hostDoc.data() ?? {}) as Data) : null\n  const starter = aiStarterHomeCandidate(hostData, screens.rows)\n  if (starter) {\n    // One more read, and only on a site that still carries the marker: the\n    // starter's versions, of which an untouched one has exactly the one it\n    // was provisioned with.\n    const versions = await host\n      .collection('screens')\n      .doc(starter)\n      .collection('versions')\n      .select()\n      .limit(2)\n      .get()\n    if (aiStarterHomeUntouched(screenVersions.get(starter) ?? '', versions.docs.map((doc) => doc.id))) {\n      const row = screens.rows.find((screen) => screen.id === starter)\n      if (row) row.replaceable = true\n    }\n  }\n\n  const windows: Record<AiInventoryKind, Window<unknown>> = {\n    components,\n    layouts,\n    templates,\n    forms,\n    datasets,\n    collections,\n    screens,\n  }\n  return {\n    hostId,\n    components: components.rows,\n    layouts: layouts.rows,\n    templates: templates.rows,\n    forms: forms.rows,\n    datasets: datasets.rows,\n    collections: collections.rows,\n    screens: screens.rows,\n    theme: aiInventoryTheme(hostData),\n    truncated: AI_INVENTORY_KINDS.filter((kind) => windows[kind].truncated),\n  }\n}\n"],"names":["hostCollectionKind","isFormArchived","describeTheme","resolveSiteTheme","REUSABLE_COMPONENT_KIND_EMAIL","reusableComponentKindOf","SCREEN_KIND_TEMPLATE","SCREEN_ROOT_PATH","pluginRecordIndex","firebaseAdmin","resolveOrgIdForHost","AI_INVENTORY_KINDS","AI_SITE_INVENTORY_MAX_PER_KIND","AiInventoryScopeError","aiBracketedFacts","text","value","trim","nameOf","data","id","fields","field","schemeColors","scheme","colors","visit","path","Array","isArray","key","inner","Object","entries","aiInventoryTheme","host","theme","fonts","Set","font","family","add","summary","colorSchemes","light","readWindow","query","cap","map","snapshot","select","limit","get","rows","doc","docs","slice","row","push","truncated","length","aiStarterHomeCandidate","screens","routing","undefined","some","screen","template","aiStarterHomeUntouched","publishedVersionId","versionIds","Boolean","readIndexedDatasets","orgId","hostId","datasets","records","index","list","record","facts","name","filter","fieldIds","readSiteInventory","options","hostDoc","owner","firestore","app","Math","min","max","floor","maxPerKind","collection","screenVersions","Map","components","layouts","templates","forms","collections","Promise","all","props","bracketedDefaults","prop","keys","parentId","kind","slug","set","layoutId","hostData","exists","starter","versions","find","replaceable","windows"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,kBAAkB,QAAQ,yCAAwC;AAC3E,SAASC,cAAc,QAAQ,+BAA8B;AAC7D,SACEC,aAAa,EACbC,gBAAgB,QAEX,oCAAmC;AAC1C,SACEC,6BAA6B,EAC7BC,uBAAuB,QAClB,iDAAgD;AACvD,SAASC,oBAAoB,EAAEC,gBAAgB,QAAQ,sCAAqC;AAC5F,SAASC,iBAAiB,QAAQ,kDAAiD;AACnF,SAASC,aAAa,QAAQ,iDAAgD;AAC9E,SAASC,mBAAmB,QAAQ,gDAA+C;AACnF,SACEC,kBAAkB,EAClBC,8BAA8B,EAC9BC,qBAAqB,QAYhB,gCAA4B;AACnC,SAASC,gBAAgB,QAAQ,8BAA0B;AAkC3D,SAASC,KAAKC,KAAc;IAC1B,OAAO,OAAOA,UAAU,WAAWA,MAAMC,IAAI,KAAK;AACpD;AAEA,8DAA8D,GAC9D,SAASC,OAAOC,IAAU,EAAEC,EAAU,EAAE,GAAGC,MAAgB;IACzD,KAAK,MAAMC,SAASD,OAAQ;QAC1B,MAAML,QAAQD,KAAKI,IAAI,CAACG,MAAM;QAC9B,IAAIN,OAAO,OAAOA;IACpB;IACA,OAAOI;AACT;AAEA,uEAAuE,GACvE,SAASG,aAAaC,MAAe;IACnC,MAAMC,SAAiC,CAAC;IACxC,MAAMC,QAAQ,CAACV,OAAgBW;QAC7B,IAAI,OAAOX,UAAU,UAAU;YAC7B,IAAIW,MAAMF,MAAM,CAACE,KAAK,GAAGX;YACzB;QACF;QACA,IAAI,CAACA,SAAS,OAAOA,UAAU,YAAYY,MAAMC,OAAO,CAACb,QAAQ;QACjE,KAAK,MAAM,CAACc,KAAKC,MAAM,IAAIC,OAAOC,OAAO,CAACjB,OAAgB;YACxDU,MAAMK,OAAOJ,OAAO,GAAGA,KAAK,CAAC,EAAEG,KAAK,GAAGA;QACzC;IACF;IACAJ,MAAMF,QAAQ;IACd,OAAOC;AACT;AAEA,mFAAmF,GACnF,OAAO,SAASS,iBAAiBC,IAAiB;QAI7BC;QAKIA;IARvB,MAAMA,QAAQjC,iBAAiBgC;IAC/B,IAAI,CAACC,OAAO,OAAO;IACnB,MAAMC,QAAQ,IAAIC;IAClB,KAAK,MAAMC,SAAQH,eAAAA,MAAMC,KAAK,YAAXD,eAAe,EAAE,CAAE;QACpC,IAAIrB,KAAKwB,wBAAAA,KAAMC,MAAM,GAAGH,MAAMI,GAAG,CAAC1B,KAAKwB,KAAKC,MAAM;IACpD;IACA,OAAO;QACLE,SAASxC,cAAckC;QACvBX,QAAQF,cAAaa,sBAAAA,MAAMO,YAAY,qBAAlBP,oBAAoBQ,KAAK;QAC9CP,OAAO;eAAIA;SAAM;IACnB;AACF;AAOA,eAAeQ,WACbC,KAA8B,EAC9BzB,MAAgB,EAChB0B,GAAW,EACXC,GAAyC;IAEzC,MAAMC,WAAW,MAAMH,MACpBI,MAAM,IAAI7B,QACV8B,KAAK,CAACJ,MAAM,GACZK,GAAG;IACN,MAAMC,OAAY,EAAE;IACpB,KAAK,MAAMC,OAAOL,SAASM,IAAI,CAACC,KAAK,CAAC,GAAGT,KAAM;YACpBO;QAAzB,MAAMG,MAAMT,IAAIM,IAAIlC,EAAE,GAAGkC,YAAAA,IAAInC,IAAI,cAARmC,YAAc,CAAC;QACxC,IAAIG,KAAKJ,KAAKK,IAAI,CAACD;IACrB;IACA,OAAO;QAAEJ;QAAMM,WAAWV,SAASM,IAAI,CAACK,MAAM,GAAGb;IAAI;AACvD;AAEA;;;;;;CAMC,GACD,OAAO,SAASc,uBACd1B,IAA8C,EAC9C2B,OAAkE;IAElE,MAAM1C,KAAKL,KAAKoB,wBAAAA,IAAM,CAAC,sBAAsB;IAC7C,IAAI,CAACf,IAAI,OAAO;IAChB,MAAM2C,UAAU5B,wBAAAA,IAAM,CAAC,UAAU;IACjC,MAAMR,OACJoC,WAAW,OAAOA,YAAY,WAAW,AAACA,OAAmC,CAAC3C,GAAG,GAAG4C;IACtF,IAAIrC,SAASpB,kBAAkB,OAAO;IACtC,OAAOuD,QAAQG,IAAI,CAAC,CAACC,SAAWA,OAAO9C,EAAE,KAAKA,MAAM,CAAC8C,OAAOC,QAAQ,IAAI/C,KAAK;AAC/E;AAEA;;;;;CAKC,GACD,OAAO,SAASgD,uBACdC,kBAA0B,EAC1BC,UAA6B;IAE7B,OAAOC,QAAQF,uBAAuBC,WAAWV,MAAM,KAAK,KAAKU,UAAU,CAAC,EAAE,KAAKD;AACrF;AAEA;;;;;CAKC,GACD,eAAeG,oBACbC,KAAa,EACbC,MAAc,EACd3B,GAAW;IAEX,MAAM4B,WAAWnE,kBAAkB;IACnC,IAAI,CAACmE,UAAU,OAAO;QAAEtB,MAAM,EAAE;QAAEM,WAAW;IAAM;IACnD,MAAM,EAAEiB,OAAO,EAAEjB,SAAS,EAAE,GAAG,MAAMgB,SAASE,KAAK,CAACC,IAAI,CAAC;QAAEL;QAAOC;QAAQvB,OAAOJ;IAAI;IACrF,OAAO;QACLM,MAAMuB,QAAQ5B,GAAG,CAAC,CAAC+B;YACjB,MAAM1D,SAAS,AAACO,CAAAA,MAAMC,OAAO,CAACkD,OAAOC,KAAK,CAAC,SAAS,IAAKD,OAAOC,KAAK,CAAC,SAAS,GAAc,EAAE,AAAD,EAC3FhC,GAAG,CAAC,CAAC1B,QAAW,CAAA;oBAAEF,IAAIL,KAAKO,yBAAAA,KAAO,CAAC,KAAK;oBAAG2D,MAAMlE,KAAKO,yBAAAA,KAAO,CAAC,OAAO,KAAKP,KAAKO,yBAAAA,KAAO,CAAC,KAAK;gBAAE,CAAA,GAC9F4D,MAAM,CAAC,CAAC5D,QAAUA,MAAM2D,IAAI;YAC/B,OAAO;gBACL7D,IAAI2D,OAAO3D,EAAE;gBACb6D,MAAMF,OAAOE,IAAI;gBACjB5D,QAAQA,OAAO2B,GAAG,CAAC,CAAC1B,QAAUA,MAAM2D,IAAI;gBACxCE,UAAU9D,OAAO2B,GAAG,CAAC,CAAC1B,QAAUA,MAAMF,EAAE,IAAIE,MAAM2D,IAAI;YACxD;QACF;QACAtB;IACF;AACF;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,eAAeyB,kBACpBX,KAAa,EACbC,MAAc,EACdW,UAAoC,CAAC,CAAC;QAIpBA,oBAGOA,qBA6GWC;IAlHpC,MAAMC,QAAQ,MAAM7E,oBAAoBgE;IACxC,IAAI,CAACa,SAASA,UAAUd,OAAO,MAAM,IAAI5D,sBAAsB6D;IAC/D,MAAMc,aAAYH,qBAAAA,QAAQG,SAAS,YAAjBH,qBAAqB5E,cAAcgF,GAAG,GAAGD,SAAS;IACpE,MAAMzC,MAAM2C,KAAKC,GAAG,CAClB/E,gCACA8E,KAAKE,GAAG,CAAC,GAAGF,KAAKG,KAAK,EAACR,sBAAAA,QAAQS,UAAU,YAAlBT,sBAAsBzE;IAE/C,MAAMuB,OAAOqD,UAAUO,UAAU,CAAC,SAASzC,GAAG,CAACoB;IAC/C,2EAA2E;IAC3E,uCAAuC;IACvC,MAAMsB,iBAAiB,IAAIC;IAE3B,MAAM,CAACC,YAAYC,SAASC,WAAWC,OAAO1B,UAAU2B,aAAaxC,SAASwB,QAAQ,GACpF,MAAMiB,QAAQC,GAAG,CAAC;QAChB3D,WACEV,KAAK4D,UAAU,CAAC,eAChB;YAAC;YAAe;YAAS;YAAU;YAAa;YAAa;SAAO,EACpEhD,KACA,CAAC3B,IAAID;YACH,2EAA2E;YAC3E,IAAIA,IAAI,CAAC,YAAY,IAAI,CAAEA,CAAAA,IAAI,CAAC,SAAS,IAAIA,IAAI,CAAC,YAAY,AAAD,GAAI,OAAO;YACxE,oEAAoE;YACpE,iEAAiE;YACjE,8DAA8D;YAC9D,IAAId,wBAAwBc,UAAUf,+BAA+B,OAAO;YAC5E,MAAMqG,QAA8B,CAAC;YACrC,MAAMC,oBAA8C,CAAC;YACrD,KAAK,MAAMC,QAAQ/E,MAAMC,OAAO,CAACV,IAAI,CAAC,QAAQ,IAAKA,IAAI,CAAC,QAAQ,GAAc,EAAE,CAAE;gBAChF,MAAM8D,OAAOlE,KAAK4F,wBAAAA,IAAM,CAAC,OAAO;gBAChC,IAAI,CAAC1B,MAAM;gBACXwB,KAAK,CAACxB,KAAK,GAAGlE,KAAK4F,IAAI,CAAC,OAAO,KAAK;gBACpC,MAAM3B,QAAQlE,iBAAiB;oBAACC,KAAK4F,IAAI,CAAC,eAAe;iBAAE;gBAC3D,IAAI3B,MAAMpB,MAAM,EAAE8C,iBAAiB,CAACzB,KAAK,GAAGD;YAC9C;YACA,OAAO;gBACL5D;gBACA6D,MAAM/D,OAAOC,MAAMC,IAAI;gBACvBqF;eACIzE,OAAO4E,IAAI,CAACF,mBAAmB9C,MAAM,GAAG;gBAAE8C;YAAkB,IAAI,CAAC;QAEzE;QAEF7D,WACEV,KAAK4D,UAAU,CAAC,YAChB;YAAC;YAAe;YAAY;SAAY,EACxChD,KACA,CAAC3B,IAAID,OACHA,IAAI,CAAC,YAAY,GACb,OACA;gBACEC;gBACA6D,MAAM/D,OAAOC,MAAMC,IAAI;gBACvByF,UAAU9F,KAAKI,IAAI,CAAC,WAAW,KAAK;YACtC;QAER0B,WACEV,KAAK4D,UAAU,CAAC,cAChB;YAAC;YAAe;YAAQ;SAAY,EACpChD,KACA,CAAC3B,IAAID,OACHA,IAAI,CAAC,YAAY,GACb,OACA;gBAAEC;gBAAI6D,MAAM/D,OAAOC,MAAMC,IAAI;gBAAgB0F,MAAM/F,KAAKI,IAAI,CAAC,OAAO,KAAK;YAAO;QAExF0B,WACEV,KAAK4D,UAAU,CAAC,UAChB;YAAC;YAAe;YAAQ;YAAU;SAAa,EAC/ChD,KACA,CAAC3B,IAAID,OACHlB,eAAekB,QACX,OACA;gBACEC;gBACA6D,MAAM/D,OAAOC,MAAMC,IAAI,eAAe;gBACtCC,QAAQ,AAACO,CAAAA,MAAMC,OAAO,CAACV,IAAI,CAAC,SAAS,IAAKA,IAAI,CAAC,SAAS,GAAc,EAAE,AAAD,EACpE6B,GAAG,CAAC,CAAC1B,QAAUP,KAAKO,yBAAAA,KAAO,CAAC,YAAY,GACxC4D,MAAM,CAACX;YACZ;QAERC,oBAAoBC,OAAOC,QAAQ3B;QACnCF,WACEV,KAAK4D,UAAU,CAAC,gBAChB;YAAC;YAAe;YAAQ;YAAQ;SAAO,EACvChD,KACA,CAAC3B,IAAID,OACHnB,mBAAmBmB,UAAU,YACzB,OACA;gBACEC;gBACA6D,MAAM/D,OAAOC,MAAMC,IAAI,eAAe,QAAQ;gBAC9C2F,MAAMhG,KAAKI,IAAI,CAAC,OAAO;YACzB;QAER0B,WACEV,KAAK4D,UAAU,CAAC,YAChB;YAAC;YAAe;YAAQ;YAAY;YAAQ;YAAa;SAAY,EACrEhD,KACA,CAAC3B,IAAID;YACH,MAAM2F,OAAO/F,KAAKI,IAAI,CAAC,OAAO;YAC9B,8EAA8E;YAC9E,IAAIA,IAAI,CAAC,YAAY,IAAK2F,QAAQA,SAASxG,sBAAuB,OAAO;YACzE0F,eAAegB,GAAG,CAAC5F,IAAIL,KAAKI,IAAI,CAAC,YAAY;YAC7C,OAAO;gBACLC;gBACA6D,MAAM/D,OAAOC,MAAMC,IAAI,eAAe;gBACtC2F,MAAMhG,KAAKI,IAAI,CAAC,OAAO;gBACvB8F,UAAUlG,KAAKI,IAAI,CAAC,WAAW,KAAK;gBACpCgD,UAAU2C,SAASxG;YACrB;QACF;QAEF6B,KAAKiB,GAAG;KACT;IAEH,MAAM8D,WAAW5B,QAAQ6B,MAAM,IAAK7B,gBAAAA,QAAQnE,IAAI,cAAZmE,gBAAkB,CAAC,IAAc;IACrE,MAAM8B,UAAUvD,uBAAuBqD,UAAUpD,QAAQT,IAAI;IAC7D,IAAI+D,SAAS;YAWgBpB;QAV3B,uEAAuE;QACvE,uEAAuE;QACvE,wBAAwB;QACxB,MAAMqB,WAAW,MAAMlF,KACpB4D,UAAU,CAAC,WACXzC,GAAG,CAAC8D,SACJrB,UAAU,CAAC,YACX7C,MAAM,GACNC,KAAK,CAAC,GACNC,GAAG;QACN,IAAIgB,wBAAuB4B,sBAAAA,eAAe5C,GAAG,CAACgE,oBAAnBpB,sBAA+B,IAAIqB,SAAS9D,IAAI,CAACP,GAAG,CAAC,CAACM,MAAQA,IAAIlC,EAAE,IAAI;YACjG,MAAMqC,MAAMK,QAAQT,IAAI,CAACiE,IAAI,CAAC,CAACpD,SAAWA,OAAO9C,EAAE,KAAKgG;YACxD,IAAI3D,KAAKA,IAAI8D,WAAW,GAAG;QAC7B;IACF;IAEA,MAAMC,UAAoD;QACxDtB;QACAC;QACAC;QACAC;QACA1B;QACA2B;QACAxC;IACF;IACA,OAAO;QACLY;QACAwB,YAAYA,WAAW7C,IAAI;QAC3B8C,SAASA,QAAQ9C,IAAI;QACrB+C,WAAWA,UAAU/C,IAAI;QACzBgD,OAAOA,MAAMhD,IAAI;QACjBsB,UAAUA,SAAStB,IAAI;QACvBiD,aAAaA,YAAYjD,IAAI;QAC7BS,SAASA,QAAQT,IAAI;QACrBjB,OAAOF,iBAAiBgF;QACxBvD,WAAWhD,mBAAmBuE,MAAM,CAAC,CAAC4B,OAASU,OAAO,CAACV,KAAK,CAACnD,SAAS;IACxE;AACF"}

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

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** The staff roles that may give credits back. */
+export declare const AI_CREDIT_RETURN_ROLES: readonly ["super", "billing"];
+declare function handler(request: Request): Promise<Response>;
+export declare const dynamic = "force-dynamic";
+export { handler as POST };

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

@@ -0,0 +1,213 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { ORG_BILLING_DOC_ID, ORG_BILLING_SUBCOLLECTION, pluginRequestFromWeb } from "@aglyn/aglyn/server";
+import { emailUnverifiedResponse, firebaseAdmin, isImpersonationSession } from "@aglyn/tenant-data-admin";
+import { setAdminAudit } from "@aglyn/tenant-data-admin/server/admin-audit-write";
+import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token-refusal";
+import { FieldValue } from "firebase-admin/firestore";
+import { freeAssistAccount } from "../usage/assist-free-taste.js";
+import { assistUsageMonth } from "../usage/assist-usage.js";
+import { accountCreditMeter, isAssistCreditReturnKey, returnAssistCredits, workspaceCreditMeter } from "../usage/assist-credit-returns-write.js";
+/**
+ * STAFF GIVE AI CREDITS BACK (AGL-3595) — compensation for a fault of ours.
+ *
+ * A planner bug refused a Free workspace's plan after it had spent 227 of
+ * its 300 monthly credits, and the person could not try again until the
+ * month rolled. This is the control that undoes that: staff return credits
+ * to the meter they were drawn from, with a reason, and the person's next
+ * request is admitted against the reduced figure.
+ *
+ * POST `{ orgId | uid, action, meter, credits?, reason, jobId?, idempotencyKey }`
+ *
+ *   action  `give`   return `credits` to each named meter
+ *           `reset`  return everything each meter used this month
+ *   meter   `workspace`  the workspace's band          (needs `orgId`)
+ *           `account`    a Free owner's allowance      (`orgId` of a Free
+ *                        workspace, or the account's `uid`)
+ *           `both`       the two together, for a Free workspace
+ *
+ * ## The gate
+ *
+ * The staff claim, and then the `super` or `billing` staff role — the bar
+ * `/api/admin/org-override` holds for a quota write, because a give-back is
+ * one: it hands out credits that are worth money. A missing role is
+ * `support`, and refused (AGL-495).
+ *
+ * ## What it writes
+ *
+ * An adjustment, never an edit: `returnAssistCredits` adds to the month's
+ * `returnedUsd` and keeps the act under `creditReturns.{key}`, and one
+ * `adminAudit` row commits in the same transaction. A repeated key writes
+ * nothing and answers `duplicate`, so a double-click returns once.
+ */ /** The longest a staff reason may be, so a paste cannot fill the document. */ const REASON_MAX = 500;
+/** The staff roles that may give credits back. */ export const AI_CREDIT_RETURN_ROLES = [
+    'super',
+    'billing'
+];
+const refuse = (error, status, code, extra = {})=>Response.json(_extends({
+        error
+    }, code ? {
+        code
+    } : {}, extra), {
+        status
+    });
+async function handler(request) {
+    var _headers_authorization;
+    const { method, body, headers: rawHeaders } = await pluginRequestFromWeb(request);
+    const headers = rawHeaders;
+    if (method !== 'POST') return refuse('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 refuse('Unauthenticated', 401);
+    try {
+        var _decoded_staffRole, _ref, _ref1, _ref2, _ref3, _ref4, _ref5;
+        const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
+        if (!decoded.email_verified && !isImpersonationSession(decoded)) {
+            return emailUnverifiedResponse();
+        }
+        if (!decoded['staff']) return refuse('Staff only', 403);
+        const role = String((_decoded_staffRole = decoded['staffRole']) != null ? _decoded_staffRole : 'support');
+        if (!AI_CREDIT_RETURN_ROLES.includes(role)) {
+            return refuse('Requires the billing or super staff role', 403, 'role');
+        }
+        const orgId = String((_ref = body == null ? void 0 : body.orgId) != null ? _ref : '').trim();
+        const uid = String((_ref1 = body == null ? void 0 : body.uid) != null ? _ref1 : '').trim();
+        const action = String((_ref2 = body == null ? void 0 : body.action) != null ? _ref2 : '');
+        const meter = String((_ref3 = body == null ? void 0 : body.meter) != null ? _ref3 : '');
+        if (!orgId && !uid) return refuse('Name an organization or an account', 400);
+        if (action !== 'give' && action !== 'reset') return refuse('Bad action', 400);
+        if (![
+            'workspace',
+            'account',
+            'both'
+        ].includes(meter)) {
+            return refuse('Bad meter', 400);
+        }
+        // Refused before anything is read: the reason is the audit row's whole
+        // value, and a row written without one cannot be corrected later.
+        const reason = String((_ref4 = body == null ? void 0 : body.reason) != null ? _ref4 : '').trim().slice(0, REASON_MAX);
+        if (!reason) {
+            return refuse('Say why the credits are being given back', 400, 'reason_required');
+        }
+        const key = body == null ? void 0 : body.idempotencyKey;
+        if (!isAssistCreditReturnKey(key)) {
+            return refuse('Missing idempotency key', 400, 'idempotency_key');
+        }
+        const credits = Number(body == null ? void 0 : body.credits);
+        if (action === 'give' && !(Number.isInteger(credits) && credits > 0)) {
+            return refuse('Give back a positive whole number of credits', 400, 'invalid_credits');
+        }
+        const jobId = String((_ref5 = body == null ? void 0 : body.jobId) != null ? _ref5 : '').trim().slice(0, 200) || null;
+        const firestore = firebaseAdmin.app().firestore();
+        const month = assistUsageMonth(new Date());
+        const targets = [];
+        let accountUid = null;
+        if (orgId) {
+            var _orgSnap_data;
+            const orgRef = firestore.collection('orgs').doc(orgId);
+            const [orgSnap, billingSnap] = await Promise.all([
+                orgRef.get(),
+                orgRef.collection(ORG_BILLING_SUBCOLLECTION).doc(ORG_BILLING_DOC_ID).get()
+            ]);
+            if (!orgSnap.exists) return refuse('No such organization', 404);
+            // Org doc first, billing mirror over it — the merge the staff card
+            // reads, so a workspace whose subscription died resolves as Free here
+            // exactly as it does at the gate.
+            const org = _extends({}, (_orgSnap_data = orgSnap.data()) != null ? _orgSnap_data : {}, billingSnap.exists ? billingSnap.data() : {});
+            if (meter !== 'account') targets.push(workspaceCreditMeter(firestore, orgId, month));
+            if (meter !== 'workspace') {
+                var _ref6;
+                var _freeAssistAccount;
+                accountUid = (_ref6 = (_freeAssistAccount = freeAssistAccount(org)) == null ? void 0 : _freeAssistAccount.accountUid) != null ? _ref6 : null;
+                if (!accountUid) {
+                    return refuse('Only a Free workspace with an owner draws on an account allowance', 409, 'no_account_allowance');
+                }
+                targets.push(accountCreditMeter(firestore, accountUid, month));
+            }
+        } else {
+            // From the staff user page: the account's own allowance, nothing else.
+            if (meter !== 'account') {
+                return refuse('An account has only its allowance to give back to', 400);
+            }
+            accountUid = uid;
+            targets.push(accountCreditMeter(firestore, uid, month));
+        }
+        const outcome = await returnAssistCredits(firestore, {
+            month,
+            meters: targets,
+            credits: action === 'reset' ? 'all' : credits,
+            key,
+            reason,
+            actorUid: decoded.uid,
+            source: 'staff',
+            jobId
+        }, (tx, lines)=>{
+            var _ref;
+            var _returned_;
+            const returned = lines.filter((line)=>line.credits > 0);
+            setAdminAudit(tx, firestore, _extends({
+                actorUid: decoded.uid,
+                action: action === 'reset' ? 'ai.credits.reset' : 'ai.credits.giveBack',
+                target: (_ref = (_returned_ = returned[0]) == null ? void 0 : _returned_.path) != null ? _ref : targets[0].ref.path
+            }, accountUid ? {
+                subjectUid: accountUid
+            } : {}, {
+                note: `${reason} — ` + returned.map((line)=>`${line.credits} credits to the ${line.meter}`).join(', ') + (jobId ? ` (job ${jobId})` : ''),
+                after: {
+                    orgId: orgId || null,
+                    accountUid,
+                    month,
+                    jobId,
+                    idempotencyKey: key,
+                    meters: returned.map((line)=>({
+                            meter: line.meter,
+                            path: line.path,
+                            credits: line.credits,
+                            usedBefore: line.usedBefore
+                        }))
+                },
+                at: FieldValue.serverTimestamp()
+            }));
+        });
+        if (outcome.status === 'over') {
+            return refuse('That is more than this month used: ' + outcome.lines.map((line)=>`${line.usedBefore} on the ${line.meter}`).join(', '), 409, 'over_return', {
+                lines: outcome.lines
+            });
+        }
+        if (outcome.status === 'nothing') {
+            return refuse('Nothing used this month to give back', 409, 'nothing_used', {
+                lines: outcome.lines
+            });
+        }
+        return Response.json({
+            month,
+            duplicate: outcome.status === 'duplicate',
+            lines: outcome.lines
+        }, {
+            status: 200
+        });
+    } catch (error) {
+        const unauthenticated = invalidIdTokenResponse(error);
+        if (unauthenticated) return unauthenticated;
+        console.error('[ai/admin/credits]', error);
+        return refuse('Giving credits back failed', 500);
+    }
+}
+export const dynamic = 'force-dynamic';
+export { handler as POST };
+
+//# sourceMappingURL=ai-admin-credits.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/ai/src/lib/server/ai-admin-credits.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 {\n  ORG_BILLING_DOC_ID,\n  ORG_BILLING_SUBCOLLECTION,\n  pluginRequestFromWeb,\n} from '@aglyn/aglyn/server'\nimport {\n  emailUnverifiedResponse,\n  firebaseAdmin,\n  isImpersonationSession,\n} from '@aglyn/tenant-data-admin'\nimport { setAdminAudit } from '@aglyn/tenant-data-admin/server/admin-audit-write'\nimport { invalidIdTokenResponse } from '@aglyn/tenant-data-admin/server/id-token-refusal'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { freeAssistAccount } from '../usage/assist-free-taste'\nimport { assistUsageMonth } from '../usage/assist-usage'\nimport {\n  accountCreditMeter,\n  isAssistCreditReturnKey,\n  returnAssistCredits,\n  workspaceCreditMeter,\n  type AssistCreditMeterTarget,\n} from '../usage/assist-credit-returns-write'\n\n/**\n * STAFF GIVE AI CREDITS BACK (AGL-3595) — compensation for a fault of ours.\n *\n * A planner bug refused a Free workspace's plan after it had spent 227 of\n * its 300 monthly credits, and the person could not try again until the\n * month rolled. This is the control that undoes that: staff return credits\n * to the meter they were drawn from, with a reason, and the person's next\n * request is admitted against the reduced figure.\n *\n * POST `{ orgId | uid, action, meter, credits?, reason, jobId?, idempotencyKey }`\n *\n *   action  `give`   return `credits` to each named meter\n *           `reset`  return everything each meter used this month\n *   meter   `workspace`  the workspace's band          (needs `orgId`)\n *           `account`    a Free owner's allowance      (`orgId` of a Free\n *                        workspace, or the account's `uid`)\n *           `both`       the two together, for a Free workspace\n *\n * ## The gate\n *\n * The staff claim, and then the `super` or `billing` staff role — the bar\n * `/api/admin/org-override` holds for a quota write, because a give-back is\n * one: it hands out credits that are worth money. A missing role is\n * `support`, and refused (AGL-495).\n *\n * ## What it writes\n *\n * An adjustment, never an edit: `returnAssistCredits` adds to the month's\n * `returnedUsd` and keeps the act under `creditReturns.{key}`, and one\n * `adminAudit` row commits in the same transaction. A repeated key writes\n * nothing and answers `duplicate`, so a double-click returns once.\n */\n\n/** The longest a staff reason may be, so a paste cannot fill the document. */\nconst REASON_MAX = 500\n\n/** The staff roles that may give credits back. */\nexport const AI_CREDIT_RETURN_ROLES = ['super', 'billing'] as const\n\ntype Meter = 'workspace' | 'account' | 'both'\n\nconst refuse = (error: string, status: number, code?: string, extra = {}) =>\n  Response.json({ error, ...(code ? { code } : {}), ...extra }, { status })\n\nasync function handler(request: Request): Promise<Response> {\n  const { method, body, headers: rawHeaders } = await pluginRequestFromWeb(request)\n  const headers = rawHeaders as Partial<Record<string, string>>\n  if (method !== 'POST') return refuse('Method not allowed', 405)\n  const authorization = headers.authorization ?? ''\n  const idToken = authorization.startsWith('Bearer ')\n    ? authorization.slice('Bearer '.length)\n    : undefined\n  if (!idToken) return refuse('Unauthenticated', 401)\n\n  try {\n    const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken)\n    if (!decoded.email_verified && !isImpersonationSession(decoded)) {\n      return emailUnverifiedResponse()\n    }\n    if (!decoded['staff']) return refuse('Staff only', 403)\n    const role = String(decoded['staffRole'] ?? 'support')\n    if (!(AI_CREDIT_RETURN_ROLES as readonly string[]).includes(role)) {\n      return refuse('Requires the billing or super staff role', 403, 'role')\n    }\n\n    const orgId = String(body?.orgId ?? '').trim()\n    const uid = String(body?.uid ?? '').trim()\n    const action = String(body?.action ?? '')\n    const meter = String(body?.meter ?? '') as Meter\n    if (!orgId && !uid) return refuse('Name an organization or an account', 400)\n    if (action !== 'give' && action !== 'reset') return refuse('Bad action', 400)\n    if (!['workspace', 'account', 'both'].includes(meter)) {\n      return refuse('Bad meter', 400)\n    }\n    // Refused before anything is read: the reason is the audit row's whole\n    // value, and a row written without one cannot be corrected later.\n    const reason = String(body?.reason ?? '').trim().slice(0, REASON_MAX)\n    if (!reason) {\n      return refuse('Say why the credits are being given back', 400, 'reason_required')\n    }\n    const key = body?.idempotencyKey\n    if (!isAssistCreditReturnKey(key)) {\n      return refuse('Missing idempotency key', 400, 'idempotency_key')\n    }\n    const credits = Number(body?.credits)\n    if (action === 'give' && !(Number.isInteger(credits) && credits > 0)) {\n      return refuse('Give back a positive whole number of credits', 400, 'invalid_credits')\n    }\n    const jobId = String(body?.jobId ?? '').trim().slice(0, 200) || null\n\n    const firestore = firebaseAdmin.app().firestore()\n    const month = assistUsageMonth(new Date())\n    const targets: AssistCreditMeterTarget[] = []\n    let accountUid: string | null = null\n\n    if (orgId) {\n      const orgRef = firestore.collection('orgs').doc(orgId)\n      const [orgSnap, billingSnap] = await Promise.all([\n        orgRef.get(),\n        orgRef.collection(ORG_BILLING_SUBCOLLECTION).doc(ORG_BILLING_DOC_ID).get(),\n      ])\n      if (!orgSnap.exists) return refuse('No such organization', 404)\n      // Org doc first, billing mirror over it — the merge the staff card\n      // reads, so a workspace whose subscription died resolves as Free here\n      // exactly as it does at the gate.\n      const org = {\n        ...(orgSnap.data() ?? {}),\n        ...(billingSnap.exists ? billingSnap.data() : {}),\n      }\n      if (meter !== 'account') targets.push(workspaceCreditMeter(firestore, orgId, month))\n      if (meter !== 'workspace') {\n        accountUid = freeAssistAccount(org as never)?.accountUid ?? null\n        if (!accountUid) {\n          return refuse(\n            'Only a Free workspace with an owner draws on an account allowance',\n            409,\n            'no_account_allowance',\n          )\n        }\n        targets.push(accountCreditMeter(firestore, accountUid, month))\n      }\n    } else {\n      // From the staff user page: the account's own allowance, nothing else.\n      if (meter !== 'account') {\n        return refuse('An account has only its allowance to give back to', 400)\n      }\n      accountUid = uid\n      targets.push(accountCreditMeter(firestore, uid, month))\n    }\n\n    const outcome = await returnAssistCredits(\n      firestore,\n      {\n        month,\n        meters: targets,\n        credits: action === 'reset' ? 'all' : credits,\n        key,\n        reason,\n        actorUid: decoded.uid,\n        source: 'staff',\n        jobId,\n      },\n      (tx, lines) => {\n        const returned = lines.filter((line) => line.credits > 0)\n        setAdminAudit(tx, firestore, {\n          actorUid: decoded.uid,\n          action: action === 'reset' ? 'ai.credits.reset' : 'ai.credits.giveBack',\n          target: returned[0]?.path ?? targets[0]!.ref.path,\n          ...(accountUid ? { subjectUid: accountUid } : {}),\n          note:\n            `${reason} — ` +\n            returned.map((line) => `${line.credits} credits to the ${line.meter}`).join(', ') +\n            (jobId ? ` (job ${jobId})` : ''),\n          after: {\n            orgId: orgId || null,\n            accountUid,\n            month,\n            jobId,\n            idempotencyKey: key,\n            meters: returned.map((line) => ({\n              meter: line.meter,\n              path: line.path,\n              credits: line.credits,\n              usedBefore: line.usedBefore,\n            })),\n          },\n          at: FieldValue.serverTimestamp(),\n        })\n      },\n    )\n\n    if (outcome.status === 'over') {\n      return refuse(\n        'That is more than this month used: ' +\n          outcome.lines.map((line) => `${line.usedBefore} on the ${line.meter}`).join(', '),\n        409,\n        'over_return',\n        { lines: outcome.lines },\n      )\n    }\n    if (outcome.status === 'nothing') {\n      return refuse('Nothing used this month to give back', 409, 'nothing_used', {\n        lines: outcome.lines,\n      })\n    }\n    return Response.json(\n      { month, duplicate: outcome.status === 'duplicate', lines: outcome.lines },\n      { status: 200 },\n    )\n  } catch (error) {\n    const unauthenticated = invalidIdTokenResponse(error)\n    if (unauthenticated) return unauthenticated\n    console.error('[ai/admin/credits]', error)\n    return refuse('Giving credits back failed', 500)\n  }\n}\n\nexport const dynamic = 'force-dynamic'\nexport { handler as POST }\n"],"names":["ORG_BILLING_DOC_ID","ORG_BILLING_SUBCOLLECTION","pluginRequestFromWeb","emailUnverifiedResponse","firebaseAdmin","isImpersonationSession","setAdminAudit","invalidIdTokenResponse","FieldValue","freeAssistAccount","assistUsageMonth","accountCreditMeter","isAssistCreditReturnKey","returnAssistCredits","workspaceCreditMeter","REASON_MAX","AI_CREDIT_RETURN_ROLES","refuse","error","status","code","extra","Response","json","handler","request","headers","method","body","rawHeaders","authorization","idToken","startsWith","slice","length","undefined","decoded","app","auth","verifyIdToken","email_verified","role","String","includes","orgId","trim","uid","action","meter","reason","key","idempotencyKey","credits","Number","isInteger","jobId","firestore","month","Date","targets","accountUid","orgSnap","orgRef","collection","doc","billingSnap","Promise","all","get","exists","org","data","push","outcome","meters","actorUid","source","tx","lines","returned","filter","line","target","path","ref","subjectUid","note","map","join","after","usedBefore","at","serverTimestamp","duplicate","unauthenticated","console","dynamic","POST"],"mappings":"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"}

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

@@ -23,7 +23,8 @@ import { invalidIdTokenResponse } from "@aglyn/tenant-data-admin/server/id-token
 import { addonKindFromPriceId } from "@aglyn/tenant-data-admin/server/billing-addons";
 import { orgMarginRow } from "@aglyn/aglyn/app-utils/margin-utilization";
 import { assistCogsAlertThresholdUsd, assistMarginMultiple } from "../usage/assist-spend-guards.js";
-import { composeStaffOrgAiAddon, composeStaffOrgAiMargin, composeStaffOrgAiOverage, composeStaffOrgAiPool, composeStaffOrgAiTokens, emptyJobCounts, STAFF_ORG_AI_JOB_STATUSES } from "../usage/staff-org-ai.js";
+import { freeAccountUsageRef, freeAssistAccount } from "../usage/assist-free-taste.js";
+import { composeStaffAiAccountAllowance, composeStaffOrgAiAddon, composeStaffOrgAiMargin, composeStaffOrgAiOverage, composeStaffOrgAiPool, composeStaffOrgAiTokens, emptyJobCounts, STAFF_ORG_AI_JOB_STATUSES } from "../usage/staff-org-ai.js";
 /**
  * THE STAFF AI CARD'S BACKING READ (AGL-2930).
  *
@@ -254,7 +255,7 @@ async function handler(request) {
         status: 400
     });
     try {
-        var _orgSnap_data, _monthSnap_data, _org_name, _rollupDoc_get, _ref, _ref1, _ref2;
+        var _orgSnap_data, _monthSnap_data, _org_name, _rollupDoc_get, _ref, _ref1, _ref2, _accountSnap_data;
         const decoded = await firebaseAdmin.app().auth().verifyIdToken(idToken);
         if (!decoded.email_verified && !isImpersonationSession(decoded)) {
             return emailUnverifiedResponse();
@@ -287,10 +288,15 @@ async function handler(request) {
         // mirror — the same merge the margin route and the org detail read make.
         const org = _extends({}, (_orgSnap_data = orgSnap.data()) != null ? _orgSnap_data : {}, billingSnap.exists ? billingSnap.data() : {});
         const monthDoc = monthSnap.exists ? (_monthSnap_data = monthSnap.data()) != null ? _monthSnap_data : {} : null;
-        const [jobs, users, since] = await Promise.all([
+        // A Free workspace also draws on its OWNER's account allowance
+        // (AGL-2925), which is what staff give credits back to beside the band
+        // (AGL-3595). One more document, read only for a Free workspace.
+        const free = freeAssistAccount(org);
+        const [jobs, users, since, accountSnap] = await Promise.all([
             readOrgAiJobsSummary(db, orgId, month),
             readOrgAiTopUsers(db, orgId, month),
-            addonSinceFor(orgId)
+            addonSinceFor(orgId),
+            (free == null ? void 0 : free.accountUid) ? freeAccountUsageRef(db, free.accountUid, month).get() : Promise.resolve(null)
         ]);
         const pool = composeStaffOrgAiPool(org, monthDoc, now);
         // The overage line is an invoice, so it is priced off what the month
@@ -337,7 +343,8 @@ async function handler(request) {
             jobs,
             users,
             margin,
-            tokens: composeStaffOrgAiTokens(monthDoc)
+            tokens: composeStaffOrgAiTokens(monthDoc),
+            account: (free == null ? void 0 : free.accountUid) && accountSnap ? composeStaffAiAccountAllowance(free.accountUid, month, accountSnap.exists ? (_accountSnap_data = accountSnap.data()) != null ? _accountSnap_data : null : null) : null
         };
         return Response.json(body, {
             status: 200