@aglyn/plugins-ai 1.0.0-beta.143

package/src/lib/declarations.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type PluginEntitlementRegistration } from '@aglyn/aglyn/plugin-manager/plugin-entitlements';
+/**
+ * The plugin's DECLARATIONS (AGL-2939): what core must know about this
+ * plugin before any of its surfaces load — its billing and access keys,
+ * the AI permission keys it adds to the org catalog (AGL-2984), its
+ * activity codes, its settings schema. Loaded eagerly by both apps
+ * through the generated declarations manifest, at boot on the server and
+ * with the plugin loader on the client, so a core billing route folds the
+ * add-on and the staff lockdown page lists the levers whether or not a
+ * request has touched the plugin yet. Light by construction: nothing here
+ * reaches a provider, Firestore or React.
+ *
+ * The plan tables keep the per-plan defaults for `aiGenerative` and
+ * `aiAssist`, and `PLAN_PRICING` keeps the add-on's price, so this names
+ * keys and bands and restates no price.
+ *
+ * `ai-assist` and `ai-generate` are separate levers because the two doors
+ * spend at different rates and an incident on one need not stop the other
+ * (AGL-2903). Both grant the staff bypass: a provider incident is verified
+ * recovered by staff making one real call, not by lifting the lock and
+ * watching customers find out.
+ */
+export declare const AI_PLUGIN_ENTITLEMENTS: PluginEntitlementRegistration;
+/**
+ * Registers everything above, and the activity codes. Idempotent: the
+ * declarations manifest runs it once per process, and a surface's register
+ * fn may call it again. The codes are a call rather than an import made
+ * for what the module does as it loads, because the browser's manifest
+ * reaches that module through nothing else, and a bundler honoring this
+ * package's `sideEffects` deletes such an import (AGL-3025).
+ */
+export declare function registerAiDeclarations(): void;

package/src/lib/declarations.js

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ // Named modules rather than the `@aglyn/aglyn` barrel: both apps load this
+// on the server at boot, and the full barrel carries client-only contexts
+// (AGL-405).
+import { AI_ADDON_CREDITS_PER_MONTH } from "@aglyn/aglyn/app-utils/plan-entitlements";
+import { registerPluginConfigSchema } from "@aglyn/aglyn/plugin-manager/plugin-config";
+import { registerPluginEntitlements } from "@aglyn/aglyn/plugin-manager/plugin-entitlements";
+import { AI_PLUGIN_ID } from "./constants.js";
+import { AI_ORG_PERMISSIONS } from "./model/ai-permissions.js";
+import { AI_CONFIG_SCHEMA } from "./plugin-config.js";
+import { registerAiActivityActions } from "./activity/ai-activity-actions.js";
+/**
+ * The plugin's DECLARATIONS (AGL-2939): what core must know about this
+ * plugin before any of its surfaces load — its billing and access keys,
+ * the AI permission keys it adds to the org catalog (AGL-2984), its
+ * activity codes, its settings schema. Loaded eagerly by both apps
+ * through the generated declarations manifest, at boot on the server and
+ * with the plugin loader on the client, so a core billing route folds the
+ * add-on and the staff lockdown page lists the levers whether or not a
+ * request has touched the plugin yet. Light by construction: nothing here
+ * reaches a provider, Firestore or React.
+ *
+ * The plan tables keep the per-plan defaults for `aiGenerative` and
+ * `aiAssist`, and `PLAN_PRICING` keeps the add-on's price, so this names
+ * keys and bands and restates no price.
+ *
+ * `ai-assist` and `ai-generate` are separate levers because the two doors
+ * spend at different rates and an incident on one need not stop the other
+ * (AGL-2903). Both grant the staff bypass: a provider incident is verified
+ * recovered by staff making one real call, not by lifting the lock and
+ * watching customers find out.
+ */ export const AI_PLUGIN_ENTITLEMENTS = {
+    pluginId: AI_PLUGIN_ID,
+    seatAddons: [
+        {
+            key: 'aiAddon',
+            label: 'AI add-on',
+            maxUnits: 1,
+            quota: {
+                key: 'assistCreditsPerMonth',
+                perUnitByPlan: AI_ADDON_CREDITS_PER_MONTH
+            },
+            features: [
+                'aiGenerative',
+                'aiAssist'
+            ]
+        }
+    ],
+    features: [
+        {
+            key: 'aiAssist',
+            label: 'AI assist'
+        },
+        {
+            key: 'aiGenerative',
+            label: 'AI generation'
+        }
+    ],
+    lockdownFeatures: [
+        {
+            key: 'ai-assist',
+            label: 'AI assist',
+            staffBypass: true,
+            notice: {
+                title: 'AI assist is temporarily unavailable',
+                body: 'AI assist is temporarily unavailable. Your content is unaffected — please try again shortly.'
+            },
+            // Gated even while the route 501s without a provider key — the switch
+            // predates the key on purpose.
+            apiPaths: {
+                exact: [
+                    'ai/assist',
+                    'assist/chat'
+                ]
+            }
+        },
+        {
+            key: 'ai-generate',
+            label: 'AI generation',
+            staffBypass: true,
+            notice: {
+                title: 'AI generation is temporarily unavailable',
+                body: 'Generating sections, pages and automations with AI is temporarily unavailable. Everything already built is unaffected — please try again shortly.'
+            },
+            // `ai/seo` (AGL-2910) applies a finished audit's drafts; it spends
+            // nothing, and it is still a generative door the switch stops.
+            apiPaths: {
+                prefixes: [
+                    'ai/generate',
+                    'ai/jobs',
+                    'ai/seo'
+                ]
+            }
+        }
+    ],
+    orgPermissions: AI_ORG_PERMISSIONS
+};
+let declared = false;
+/**
+ * Registers everything above, and the activity codes. Idempotent: the
+ * declarations manifest runs it once per process, and a surface's register
+ * fn may call it again. The codes are a call rather than an import made
+ * for what the module does as it loads, because the browser's manifest
+ * reaches that module through nothing else, and a bundler honoring this
+ * package's `sideEffects` deletes such an import (AGL-3025).
+ */ export function registerAiDeclarations() {
+    if (declared) return;
+    declared = true;
+    registerPluginEntitlements(AI_PLUGIN_ENTITLEMENTS);
+    registerPluginConfigSchema(AI_CONFIG_SCHEMA);
+    registerAiActivityActions();
+}
+registerAiDeclarations();
+
+//# sourceMappingURL=declarations.js.map

package/src/lib/declarations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/ai/src/lib/declarations.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// Named modules rather than the `@aglyn/aglyn` barrel: both apps load this\n// on the server at boot, and the full barrel carries client-only contexts\n// (AGL-405).\nimport { AI_ADDON_CREDITS_PER_MONTH } from '@aglyn/aglyn/app-utils/plan-entitlements'\nimport { registerPluginConfigSchema } from '@aglyn/aglyn/plugin-manager/plugin-config'\nimport {\n  registerPluginEntitlements,\n  type PluginEntitlementRegistration,\n} from '@aglyn/aglyn/plugin-manager/plugin-entitlements'\nimport { AI_PLUGIN_ID } from './constants'\nimport { AI_ORG_PERMISSIONS } from './model/ai-permissions'\nimport { AI_CONFIG_SCHEMA } from './plugin-config'\nimport { registerAiActivityActions } from './activity/ai-activity-actions'\n\n/**\n * The plugin's DECLARATIONS (AGL-2939): what core must know about this\n * plugin before any of its surfaces load — its billing and access keys,\n * the AI permission keys it adds to the org catalog (AGL-2984), its\n * activity codes, its settings schema. Loaded eagerly by both apps\n * through the generated declarations manifest, at boot on the server and\n * with the plugin loader on the client, so a core billing route folds the\n * add-on and the staff lockdown page lists the levers whether or not a\n * request has touched the plugin yet. Light by construction: nothing here\n * reaches a provider, Firestore or React.\n *\n * The plan tables keep the per-plan defaults for `aiGenerative` and\n * `aiAssist`, and `PLAN_PRICING` keeps the add-on's price, so this names\n * keys and bands and restates no price.\n *\n * `ai-assist` and `ai-generate` are separate levers because the two doors\n * spend at different rates and an incident on one need not stop the other\n * (AGL-2903). Both grant the staff bypass: a provider incident is verified\n * recovered by staff making one real call, not by lifting the lock and\n * watching customers find out.\n */\nexport const AI_PLUGIN_ENTITLEMENTS: PluginEntitlementRegistration = {\n  pluginId: AI_PLUGIN_ID,\n  seatAddons: [\n    {\n      key: 'aiAddon',\n      label: 'AI add-on',\n      maxUnits: 1,\n      quota: {\n        key: 'assistCreditsPerMonth',\n        perUnitByPlan: AI_ADDON_CREDITS_PER_MONTH,\n      },\n      features: ['aiGenerative', 'aiAssist'],\n    },\n  ],\n  features: [\n    { key: 'aiAssist', label: 'AI assist' },\n    { key: 'aiGenerative', label: 'AI generation' },\n  ],\n  lockdownFeatures: [\n    {\n      key: 'ai-assist',\n      label: 'AI assist',\n      staffBypass: true,\n      notice: {\n        title: 'AI assist is temporarily unavailable',\n        body: 'AI assist is temporarily unavailable. Your content is unaffected — please try again shortly.',\n      },\n      // Gated even while the route 501s without a provider key — the switch\n      // predates the key on purpose.\n      apiPaths: { exact: ['ai/assist', 'assist/chat'] },\n    },\n    {\n      key: 'ai-generate',\n      label: 'AI generation',\n      staffBypass: true,\n      notice: {\n        title: 'AI generation is temporarily unavailable',\n        body: 'Generating sections, pages and automations with AI is temporarily unavailable. Everything already built is unaffected — please try again shortly.',\n      },\n      // `ai/seo` (AGL-2910) applies a finished audit's drafts; it spends\n      // nothing, and it is still a generative door the switch stops.\n      apiPaths: { prefixes: ['ai/generate', 'ai/jobs', 'ai/seo'] },\n    },\n  ],\n  orgPermissions: AI_ORG_PERMISSIONS,\n}\n\nlet declared = false\n\n/**\n * Registers everything above, and the activity codes. Idempotent: the\n * declarations manifest runs it once per process, and a surface's register\n * fn may call it again. The codes are a call rather than an import made\n * for what the module does as it loads, because the browser's manifest\n * reaches that module through nothing else, and a bundler honoring this\n * package's `sideEffects` deletes such an import (AGL-3025).\n */\nexport function registerAiDeclarations(): void {\n  if (declared) return\n  declared = true\n  registerPluginEntitlements(AI_PLUGIN_ENTITLEMENTS)\n  registerPluginConfigSchema(AI_CONFIG_SCHEMA)\n  registerAiActivityActions()\n}\n\nregisterAiDeclarations()\n"],"names":["AI_ADDON_CREDITS_PER_MONTH","registerPluginConfigSchema","registerPluginEntitlements","AI_PLUGIN_ID","AI_ORG_PERMISSIONS","AI_CONFIG_SCHEMA","registerAiActivityActions","AI_PLUGIN_ENTITLEMENTS","pluginId","seatAddons","key","label","maxUnits","quota","perUnitByPlan","features","lockdownFeatures","staffBypass","notice","title","body","apiPaths","exact","prefixes","orgPermissions","declared","registerAiDeclarations"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,2EAA2E;AAC3E,0EAA0E;AAC1E,aAAa;AACb,SAASA,0BAA0B,QAAQ,2CAA0C;AACrF,SAASC,0BAA0B,QAAQ,4CAA2C;AACtF,SACEC,0BAA0B,QAErB,kDAAiD;AACxD,SAASC,YAAY,QAAQ,iBAAa;AAC1C,SAASC,kBAAkB,QAAQ,4BAAwB;AAC3D,SAASC,gBAAgB,QAAQ,qBAAiB;AAClD,SAASC,yBAAyB,QAAQ,oCAAgC;AAE1E;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAMC,yBAAwD;IACnEC,UAAUL;IACVM,YAAY;QACV;YACEC,KAAK;YACLC,OAAO;YACPC,UAAU;YACVC,OAAO;gBACLH,KAAK;gBACLI,eAAed;YACjB;YACAe,UAAU;gBAAC;gBAAgB;aAAW;QACxC;KACD;IACDA,UAAU;QACR;YAAEL,KAAK;YAAYC,OAAO;QAAY;QACtC;YAAED,KAAK;YAAgBC,OAAO;QAAgB;KAC/C;IACDK,kBAAkB;QAChB;YACEN,KAAK;YACLC,OAAO;YACPM,aAAa;YACbC,QAAQ;gBACNC,OAAO;gBACPC,MAAM;YACR;YACA,sEAAsE;YACtE,+BAA+B;YAC/BC,UAAU;gBAAEC,OAAO;oBAAC;oBAAa;iBAAc;YAAC;QAClD;QACA;YACEZ,KAAK;YACLC,OAAO;YACPM,aAAa;YACbC,QAAQ;gBACNC,OAAO;gBACPC,MAAM;YACR;YACA,mEAAmE;YACnE,+DAA+D;YAC/DC,UAAU;gBAAEE,UAAU;oBAAC;oBAAe;oBAAW;iBAAS;YAAC;QAC7D;KACD;IACDC,gBAAgBpB;AAClB,EAAC;AAED,IAAIqB,WAAW;AAEf;;;;;;;CAOC,GACD,OAAO,SAASC;IACd,IAAID,UAAU;IACdA,WAAW;IACXvB,2BAA2BK;IAC3BN,2BAA2BI;IAC3BC;AACF;AAEAoB"}

package/src/lib/declarations.server.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 plugin's SERVER declarations (AGL-2939): what the server must know
+ * at boot, before any door of the plugin has been called. The two platform
+ * events the plugin writes activity for — the AI add-on bought or dropped,
+ * an `ai.*` permission moved — are raised by core billing and membership
+ * routes that never load the plugin's API surface, so the subscriptions
+ * have to be in place from the first request. So does the eraser: an
+ * account erasure is a core route too, and a person's AI usage months sit
+ * under each org, keyed by the uid, where no core delete reaches them. So
+ * does the usage alert contributor (AGL-2984): the usage-alerts sweep is a
+ * core cron, and it evaluates the plugin's staff alerts on provider spend for
+ * every org it reads.
+ *
+ * Light at boot by construction: the writers behind the handlers are
+ * imported when the first event arrives, and the alert rules when the sweep
+ * first evaluates an org, not when the process starts, so the boot cost is
+ * the registration and nothing that touches Firestore.
+ */
+export declare function registerAiServerDeclarations(): void;

package/src/lib/declarations.server.js

@@ -0,0 +1,138 @@
+/**
+ * @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.
+ */ // Each registry from its own module, not the `@aglyn/aglyn/server` barrel:
+// boot needs three registries rather than the whole server surface, and a
+// suite that stubs that barrel wholesale still loads these declarations
+// against the real registries.
+import { listPluginEventHandlers, registerPluginEventHandler } from "@aglyn/aglyn/plugin-manager/plugin-events";
+import { listPluginUserErasers, registerPluginUserEraser } from "@aglyn/aglyn/plugin-manager/plugin-user-erasure";
+import { listUsageAlertContributors, registerUsageAlertContributor } from "@aglyn/aglyn/plugin-manager/usage-alert-contributors";
+import { pluginMeteredLineOwner } from "@aglyn/aglyn/plugin-manager/plugin-metered-lines";
+import { AI_PLUGIN_ID } from "./constants.js";
+import { registerAiDeclarations } from "./declarations.js";
+import { AI_OVERAGE_METER_LINE_ID, registerAiOverageMeteredLine } from "./billing/ai-overage-cutover.js";
+/** The provider-spend staff alerts' contributor id under the plugin. */ const AI_USAGE_ALERTS_ID = 'provider-spend';
+/**
+ * The plugin's SERVER declarations (AGL-2939): what the server must know
+ * at boot, before any door of the plugin has been called. The two platform
+ * events the plugin writes activity for — the AI add-on bought or dropped,
+ * an `ai.*` permission moved — are raised by core billing and membership
+ * routes that never load the plugin's API surface, so the subscriptions
+ * have to be in place from the first request. So does the eraser: an
+ * account erasure is a core route too, and a person's AI usage months sit
+ * under each org, keyed by the uid, where no core delete reaches them. So
+ * does the usage alert contributor (AGL-2984): the usage-alerts sweep is a
+ * core cron, and it evaluates the plugin's staff alerts on provider spend for
+ * every org it reads.
+ *
+ * Light at boot by construction: the writers behind the handlers are
+ * imported when the first event arrives, and the alert rules when the sweep
+ * first evaluates an org, not when the process starts, so the boot cost is
+ * the registration and nothing that touches Firestore.
+ */ export function registerAiServerDeclarations() {
+    registerAiDeclarations();
+    // Idempotent against each REGISTRY rather than a module flag, so a
+    // registry reset (a spec) or a second module instance registers again.
+    if (!listPluginEventHandlers('org.seatAddons.changed').includes(AI_PLUGIN_ID)) {
+        registerPluginEventHandler('org.seatAddons.changed', async ({ orgId, actor, before, after })=>{
+            const { logAiAddonChanged } = await import("./activity/ai-activity.js");
+            await logAiAddonChanged(orgId, actor, {
+                before,
+                after
+            });
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+        registerPluginEventHandler('org.permissions.changed', async ({ orgId, actor, subject, permission, granted })=>{
+            if (!permission.startsWith('ai.')) return;
+            const { logAiPermissionChanged } = await import("./activity/ai-activity.js");
+            await logAiPermissionChanged(orgId, actor, {
+                subject,
+                permission,
+                granted
+            });
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+    }
+    // THE PLATFORM'S BILLING EVENTS (AGL-3011). Subscribed at boot for the
+    // same reason as the two above: they are raised by the billing webhook,
+    // which never loads an AI door, and a workspace's overage standing moving
+    // late is a workspace charged or refused against a fact we already had.
+    //
+    // The handler modules are imported when the first event arrives, so a
+    // process that never receives one pays only for the registration.
+    if (!listPluginEventHandlers('billing.invoice.paid').includes(AI_PLUGIN_ID)) {
+        registerPluginEventHandler('billing.invoice.paid', async (payload)=>{
+            const { onAiBillingInvoicePaid } = await import("./billing/ai-overage-events.js");
+            await onAiBillingInvoicePaid(payload);
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+        registerPluginEventHandler('billing.invoice.failed', async (payload)=>{
+            const { onAiBillingInvoiceFailed } = await import("./billing/ai-overage-events.js");
+            await onAiBillingInvoiceFailed(payload);
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+        registerPluginEventHandler('billing.invoice.closed', async (payload)=>{
+            const { onAiBillingInvoiceClosed } = await import("./billing/ai-overage-events.js");
+            await onAiBillingInvoiceClosed(payload);
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+        registerPluginEventHandler('billing.dispute.opened', async (payload)=>{
+            const { onAiBillingDisputeOpened } = await import("./billing/ai-overage-events.js");
+            await onAiBillingDisputeOpened(payload);
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+        registerPluginEventHandler('billing.paymentMethod.changed', async (payload)=>{
+            const { onAiBillingPaymentMethodChanged } = await import("./billing/ai-overage-events.js");
+            await onAiBillingPaymentMethodChanged(payload);
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+    }
+    // The meter line the plugin bills for itself from the cutover month
+    // (AGL-3011). Registered at boot because the monthly usage sweep is a core
+    // cron; the claim reads its own cutover month on every call, so it is
+    // inert until the month is configured.
+    if (pluginMeteredLineOwner(AI_OVERAGE_METER_LINE_ID) !== AI_PLUGIN_ID) {
+        registerAiOverageMeteredLine();
+    }
+    if (!listPluginUserErasers().includes(AI_PLUGIN_ID)) {
+        registerPluginUserEraser(async (request)=>{
+            const { eraseAiUsageForUser } = await import("./usage/ai-usage-eraser.js");
+            return eraseAiUsageForUser(request);
+        }, {
+            pluginId: AI_PLUGIN_ID
+        });
+    }
+    if (!listUsageAlertContributors().some((contributor)=>contributor.pluginId === AI_PLUGIN_ID && contributor.id === AI_USAGE_ALERTS_ID)) {
+        registerUsageAlertContributor({
+            pluginId: AI_PLUGIN_ID,
+            id: AI_USAGE_ALERTS_ID,
+            evaluate: async (context)=>{
+                const { evaluateAiUsageAlerts } = await import("./usage/ai-usage-alerts.js");
+                await evaluateAiUsageAlerts(context);
+            }
+        });
+    }
+}
+registerAiServerDeclarations();
+
+//# sourceMappingURL=declarations.server.js.map

package/src/lib/declarations.server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/plugins/ai/src/lib/declarations.server.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// Each registry from its own module, not the `@aglyn/aglyn/server` barrel:\n// boot needs three registries rather than the whole server surface, and a\n// suite that stubs that barrel wholesale still loads these declarations\n// against the real registries.\nimport {\n  listPluginEventHandlers,\n  registerPluginEventHandler,\n} from '@aglyn/aglyn/plugin-manager/plugin-events'\nimport {\n  listPluginUserErasers,\n  registerPluginUserEraser,\n} from '@aglyn/aglyn/plugin-manager/plugin-user-erasure'\nimport {\n  listUsageAlertContributors,\n  registerUsageAlertContributor,\n} from '@aglyn/aglyn/plugin-manager/usage-alert-contributors'\nimport { pluginMeteredLineOwner } from '@aglyn/aglyn/plugin-manager/plugin-metered-lines'\nimport { AI_PLUGIN_ID } from './constants'\nimport { registerAiDeclarations } from './declarations'\nimport {\n  AI_OVERAGE_METER_LINE_ID,\n  registerAiOverageMeteredLine,\n} from './billing/ai-overage-cutover'\n\n/** The provider-spend staff alerts' contributor id under the plugin. */\nconst AI_USAGE_ALERTS_ID = 'provider-spend'\n\n/**\n * The plugin's SERVER declarations (AGL-2939): what the server must know\n * at boot, before any door of the plugin has been called. The two platform\n * events the plugin writes activity for — the AI add-on bought or dropped,\n * an `ai.*` permission moved — are raised by core billing and membership\n * routes that never load the plugin's API surface, so the subscriptions\n * have to be in place from the first request. So does the eraser: an\n * account erasure is a core route too, and a person's AI usage months sit\n * under each org, keyed by the uid, where no core delete reaches them. So\n * does the usage alert contributor (AGL-2984): the usage-alerts sweep is a\n * core cron, and it evaluates the plugin's staff alerts on provider spend for\n * every org it reads.\n *\n * Light at boot by construction: the writers behind the handlers are\n * imported when the first event arrives, and the alert rules when the sweep\n * first evaluates an org, not when the process starts, so the boot cost is\n * the registration and nothing that touches Firestore.\n */\nexport function registerAiServerDeclarations(): void {\n  registerAiDeclarations()\n  // Idempotent against each REGISTRY rather than a module flag, so a\n  // registry reset (a spec) or a second module instance registers again.\n  if (!listPluginEventHandlers('org.seatAddons.changed').includes(AI_PLUGIN_ID)) {\n    registerPluginEventHandler(\n      'org.seatAddons.changed',\n      async ({ orgId, actor, before, after }) => {\n        const { logAiAddonChanged } = await import('./activity/ai-activity')\n        await logAiAddonChanged(orgId, actor, { before, after })\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n    registerPluginEventHandler(\n      'org.permissions.changed',\n      async ({ orgId, actor, subject, permission, granted }) => {\n        if (!permission.startsWith('ai.')) return\n        const { logAiPermissionChanged } = await import('./activity/ai-activity')\n        await logAiPermissionChanged(orgId, actor, { subject, permission, granted })\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n  }\n  // THE PLATFORM'S BILLING EVENTS (AGL-3011). Subscribed at boot for the\n  // same reason as the two above: they are raised by the billing webhook,\n  // which never loads an AI door, and a workspace's overage standing moving\n  // late is a workspace charged or refused against a fact we already had.\n  //\n  // The handler modules are imported when the first event arrives, so a\n  // process that never receives one pays only for the registration.\n  if (!listPluginEventHandlers('billing.invoice.paid').includes(AI_PLUGIN_ID)) {\n    registerPluginEventHandler(\n      'billing.invoice.paid',\n      async (payload) => {\n        const { onAiBillingInvoicePaid } = await import('./billing/ai-overage-events')\n        await onAiBillingInvoicePaid(payload)\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n    registerPluginEventHandler(\n      'billing.invoice.failed',\n      async (payload) => {\n        const { onAiBillingInvoiceFailed } = await import('./billing/ai-overage-events')\n        await onAiBillingInvoiceFailed(payload)\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n    registerPluginEventHandler(\n      'billing.invoice.closed',\n      async (payload) => {\n        const { onAiBillingInvoiceClosed } = await import('./billing/ai-overage-events')\n        await onAiBillingInvoiceClosed(payload)\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n    registerPluginEventHandler(\n      'billing.dispute.opened',\n      async (payload) => {\n        const { onAiBillingDisputeOpened } = await import('./billing/ai-overage-events')\n        await onAiBillingDisputeOpened(payload)\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n    registerPluginEventHandler(\n      'billing.paymentMethod.changed',\n      async (payload) => {\n        const { onAiBillingPaymentMethodChanged } = await import(\n          './billing/ai-overage-events'\n        )\n        await onAiBillingPaymentMethodChanged(payload)\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n  }\n  // The meter line the plugin bills for itself from the cutover month\n  // (AGL-3011). Registered at boot because the monthly usage sweep is a core\n  // cron; the claim reads its own cutover month on every call, so it is\n  // inert until the month is configured.\n  if (pluginMeteredLineOwner(AI_OVERAGE_METER_LINE_ID) !== AI_PLUGIN_ID) {\n    registerAiOverageMeteredLine()\n  }\n  if (!listPluginUserErasers().includes(AI_PLUGIN_ID)) {\n    registerPluginUserEraser(\n      async (request) => {\n        const { eraseAiUsageForUser } = await import('./usage/ai-usage-eraser')\n        return eraseAiUsageForUser(request)\n      },\n      { pluginId: AI_PLUGIN_ID },\n    )\n  }\n  if (\n    !listUsageAlertContributors().some(\n      (contributor) =>\n        contributor.pluginId === AI_PLUGIN_ID &&\n        contributor.id === AI_USAGE_ALERTS_ID,\n    )\n  ) {\n    registerUsageAlertContributor({\n      pluginId: AI_PLUGIN_ID,\n      id: AI_USAGE_ALERTS_ID,\n      evaluate: async (context) => {\n        const { evaluateAiUsageAlerts } = await import('./usage/ai-usage-alerts')\n        await evaluateAiUsageAlerts(context)\n      },\n    })\n  }\n}\n\nregisterAiServerDeclarations()\n"],"names":["listPluginEventHandlers","registerPluginEventHandler","listPluginUserErasers","registerPluginUserEraser","listUsageAlertContributors","registerUsageAlertContributor","pluginMeteredLineOwner","AI_PLUGIN_ID","registerAiDeclarations","AI_OVERAGE_METER_LINE_ID","registerAiOverageMeteredLine","AI_USAGE_ALERTS_ID","registerAiServerDeclarations","includes","orgId","actor","before","after","logAiAddonChanged","pluginId","subject","permission","granted","startsWith","logAiPermissionChanged","payload","onAiBillingInvoicePaid","onAiBillingInvoiceFailed","onAiBillingInvoiceClosed","onAiBillingDisputeOpened","onAiBillingPaymentMethodChanged","request","eraseAiUsageForUser","some","contributor","id","evaluate","context","evaluateAiUsageAlerts"],"mappings":"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"}

package/src/lib/insights/ai-figure-readers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type PluginFigureReader, type PluginFigureRequest } from '@aglyn/aglyn/plugin-manager/plugin-figures';
+/**
+ * The figure readers this plugin registers for records the PLATFORM keeps
+ * (AGL-2915): a site's page-view counters, its forms' counters and the
+ * workspace's datasets. Every other reader an insight reads is registered by
+ * the plugin that owns its records — commerce, bookings, marketing — on the
+ * `plugin-figures` seam, and nothing here reads their documents.
+ *
+ * Each reader answers with one compact table of aggregates, read-only and
+ * about nobody: counts, sums and rates, labeled by a page path, a form's name,
+ * a referring site or a dataset's own field — never a visitor, a submission or
+ * a record. A dataset breakdown refuses a field with more than
+ * `AI_DATASET_MAX_GROUP_VALUES` different values — on a dataset of any size, a
+ * name, an address or an order number — and folds every group of fewer than
+ * `AI_DATASET_MIN_GROUP` records into one row, so each label it shows is a
+ * value at least that many records share.
+ *
+ * The readers use the arithmetic their console cards use: the Traffic card's
+ * windows and change (`pluginFigureWindows`, `pluginFigureChange`, which are
+ * that card's split and delta), and the forms plugin's month counters through
+ * `formStatsTotals`, the one function every forms surface windows by.
+ */
+type Firestore = FirebaseFirestore.Firestore;
+/** How a reader reaches Firestore: resolved when it reads, never when it registers. */
+export type AiFigureFirestore = () => Firestore;
+/** The traffic windows: the Traffic card's own ranges. */
+export declare const AI_TRAFFIC_WINDOWS: readonly number[];
+/** A day-by-day table fits a table's row bound only over a short window. */
+export declare const AI_TRAFFIC_DAILY_WINDOWS: readonly number[];
+/** Pages a pages table lists; the rest are counted in `omitted`. */
+export declare const AI_TRAFFIC_TOP_PAGES = 10;
+/** Referring sites, and campaign sources and campaigns, a sources table lists. */
+export declare const AI_TRAFFIC_TOP_REFERRERS = 8;
+export declare const AI_TRAFFIC_TOP_CAMPAIGNS = 5;
+/** Forms a forms table reads. */
+export declare const AI_FORMS_READ_LIMIT = 100;
+/** Datasets a dataset summary reads. */
+export declare const AI_DATASETS_READ_LIMIT = 50;
+/** Records a dataset breakdown or field summary reads, in document order; the rest are named in a note. */
+export declare const AI_DATASET_RECORDS_READ_LIMIT = 2000;
+/** The fewest records a breakdown shows a group of by its own label. */
+export declare const AI_DATASET_MIN_GROUP = 3;
+/**
+ * The most different values a breakdown groups by: every state and territory,
+ * a status, a category. A field with more tells records apart rather than
+ * sorting them, so it is refused.
+ */
+export declare const AI_DATASET_MAX_GROUP_VALUES = 60;
+/** The aggregates a breakdown computes. */
+export declare const AI_DATASET_OPERATIONS: readonly ["count", "sum", "average", "min", "max"];
+export type AiDatasetOperation = (typeof AI_DATASET_OPERATIONS)[number];
+export declare function trafficFigureReaders(firestore: AiFigureFirestore): PluginFigureReader[];
+export declare function formsFigureReader(firestore: AiFigureFirestore): PluginFigureReader;
+/** A dataset a question may name, with its fields, as the read prompt lists it. */
+export interface AiDatasetCatalogEntry {
+    id: string;
+    name: string;
+    fields: Array<{
+        id: string;
+        name: string;
+        type: string;
+    }>;
+}
+/** The datasets a request may read, with their fields: what the model picks a breakdown from. */
+export declare function aiDatasetCatalog(firestore: Firestore, request: Pick<PluginFigureRequest, 'orgId' | 'hostId' | 'uid'>): Promise<AiDatasetCatalogEntry[]>;
+export declare function datasetFigureReaders(firestore: AiFigureFirestore): PluginFigureReader[];
+/** Every reader this plugin registers, for the platform's own records. */
+export declare function aiFigureReaders(firestore: AiFigureFirestore): PluginFigureReader[];
+/**
+ * Registers them from the console surface, the one surface that runs insight
+ * jobs. By a call, never by an import (AGL-3025).
+ */
+export declare function registerAiFigureReaders(firestore: AiFigureFirestore): void;
+export {};