@aglyn/aglyn 1.0.0-beta.143

package/src/lib/plugin-manager/plugin-entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-entitlements.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/**\n * Plugin-declared billing and access keys (AGL-2940).\n *\n * A plugin that sells something, gates something, or can be switched off in\n * an incident declares the KEYS here — a seat add-on, a feature flag, a\n * lockdown lever, a permission — and the core catalogs that used to be\n * edited for each one read the declarations instead:\n *\n * - `plan-entitlements` folds every registered seat add-on into\n *   `resolveOrgEntitlements` (a quota raised per unit, features switched on)\n *   and answers a registered feature's plan defaults;\n * - `lockdown` lists a registered lever on the staff page, carries its label,\n *   its staff-bypass rule and its visitor notice, and maps the API paths it\n *   names onto it for the plugin dispatcher;\n * - `plugin-permissions` receives the permissions with the owner filled in;\n * - `org-permissions` folds every declared catalog key into the org\n *   permission catalog — the role editor, custom roles, per-member overrides\n *   and the rules stamp — and `host-permissions` decides the keys that\n *   declare host-role defaults for a site collaborator, per site.\n *\n * The NUMBERS stay where they are checked. A seat add-on's price is a row in\n * `PLAN_PRICING`, read by the Stripe wiring and reconciled by\n * `check-pricing-drift`; a declaration names the quota it widens and by how\n * much per plan, and nothing here restates a price.\n *\n * Registration order is deterministic: the catalog order of\n * `FIRST_PARTY_PLUGINS`, then any other id alphabetically. Plugin modules\n * load in parallel, so the order they REGISTER in is whatever the network\n * gave, and a list that followed it would put the staff lockdown checklist\n * in a different order per session.\n */\n\nimport type { HostAccessRole, OrgPlan, OrgRole } from '../foundation'\nimport { FIRST_PARTY_PLUGINS } from './enabled-plugins'\nimport {\n  registerPluginPermissions,\n  type PluginPermission,\n} from './plugin-permissions'\n\nexport interface PluginSeatAddonDeclaration {\n  /** The `org.seatAddons` key the purchase is stored under (`aiAddon`). */\n  key: string\n  label: string\n  /**\n   * How many purchased units count. `1` for an org-wide add-on that is\n   * bought once, where a doubled webhook item or a hand edit above one is\n   * still one purchase; absent to count the stored quantity.\n   */\n  maxUnits?: number\n  /**\n   * The quota each unit widens, per plan: the resolved entitlement named by\n   * `key` gains `perUnitByPlan[plan] × units`. A plan the add-on is not sold\n   * on declares 0.\n   */\n  quota?: {\n    key: string\n    perUnitByPlan: Readonly<Record<OrgPlan, number>>\n  }\n  /** Feature flags a purchased unit switches on. */\n  features?: readonly string[]\n}\n\nexport interface PluginFeatureDeclaration {\n  /** The `OrgFeatureFlags` key. */\n  key: string\n  label: string\n  /**\n   * The plan defaults, when the key is not one the plan tables already\n   * carry. Absent means the plan tables decide, which is the case for every\n   * key that predates this registry.\n   */\n  defaultByPlan?: Readonly<Partial<Record<OrgPlan, boolean>>>\n}\n\nexport interface PluginLockdownFeatureDeclaration {\n  /** The lever's wire identity (`ai-generate`). */\n  key: string\n  /** The staff checklist's label. */\n  label: string\n  /**\n   * Whether a verified staff claim passes the lock. Granted where a staff\n   * action aids incident response — one real call proves a provider is back\n   * — and withheld where the staff action would BE the incident.\n   */\n  staffBypass: boolean\n  /**\n   * What a visitor reads while the lever is pulled: what is paused AND what\n   * still works. The expected-back window is appended by the notice builder.\n   */\n  notice: { title: string; body: string }\n  /**\n   * Plugin API paths the lever gates at the dispatcher: exact paths, and\n   * prefixes matched on a segment boundary (`ai/generate` also gates\n   * `ai/generate/section`, never `ai/generated-report`).\n   */\n  apiPaths?: { exact?: readonly string[]; prefixes?: readonly string[] }\n}\n\n/**\n * A key a plugin adds to the org permission CATALOG (AGL-2984): the granular\n * map custom roles and per-member overrides are stored in, that\n * `resolveOrgPermissions` layers and the rules stamp carries, and that the\n * role editor lists. A declared key is stored, layered and resolved exactly\n * like a core key; the declaration supplies what a core key's catalog entry\n * and role table supply.\n */\nexport interface PluginOrgPermissionDeclaration {\n  /** The dotted key a custom role and a per-member override store (`reviews.reply`). */\n  key: string\n  /** The role editor's line for the key, and the word a refusal names. */\n  label: string\n  /** What the key opens, under the label in the role editor. */\n  description: string\n  /** Each org role's verdict when no custom role or per-member override sets the key. */\n  roleDefaults: Readonly<Record<OrgRole, boolean>>\n  /**\n   * Each HOST role's verdict, for a key a site collaborator holds per site.\n   *\n   * A collaborator's membership carries no org standing to refine — it\n   * exists only to carry access to named sites — so a key with this field is\n   * decided for them on the site a request names: the host role they hold\n   * there, refined by the per-site toggle on their member document. A key\n   * without it is never held by a collaborator.\n   */\n  hostRoleDefaults?: Readonly<Record<HostAccessRole, boolean>>\n}\n\nexport interface PluginEntitlementRegistration {\n  pluginId: string\n  seatAddons?: readonly PluginSeatAddonDeclaration[]\n  features?: readonly PluginFeatureDeclaration[]\n  lockdownFeatures?: readonly PluginLockdownFeatureDeclaration[]\n  /** Per-tier keys a plugin's own pages read (`registerPluginPermissions`). */\n  permissions?: readonly Omit<PluginPermission, 'pluginId'>[]\n  /** Keys added to the org permission catalog — see {@link PluginOrgPermissionDeclaration}. */\n  orgPermissions?: readonly PluginOrgPermissionDeclaration[]\n}\n\nconst registrations = new Map<string, PluginEntitlementRegistration>()\n\n/**\n * Readers of the registrations that keep a derived view in step with them —\n * the org permission catalog rebuilds itself on every registration and\n * reset, because a plugin's declarations can register after a module that\n * imported the catalog was evaluated.\n */\nconst listeners = new Set<() => void>()\n\n/** Calls `listener` after every registration and reset; answers the unsubscribe. */\nexport function subscribePluginEntitlements(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\nfunction notifyListeners(): void {\n  for (const listener of [...listeners]) listener()\n}\n\nconst CATALOG_ORDER = new Map(\n  FIRST_PARTY_PLUGINS.map((plugin, index) => [plugin.id, index]),\n)\n\nfunction catalogRank(pluginId: string): number {\n  return CATALOG_ORDER.get(pluginId) ?? Number.MAX_SAFE_INTEGER\n}\n\nfunction orderedRegistrations(): PluginEntitlementRegistration[] {\n  return [...registrations.values()].sort(\n    (a, b) =>\n      catalogRank(a.pluginId) - catalogRank(b.pluginId) ||\n      a.pluginId.localeCompare(b.pluginId),\n  )\n}\n\nfunction refuseStolenKeys(\n  pluginId: string,\n  kind: 'seat add-on' | 'lockdown feature' | 'org permission',\n  keys: readonly string[],\n  ownerOf: (key: string) => string | undefined,\n): void {\n  for (const key of keys) {\n    const owner = ownerOf(key)\n    if (owner && owner !== pluginId) {\n      throw new Error(\n        `${kind} \"${key}\" is already declared by \"${owner}\"; refused \"${pluginId}\"`,\n      )\n    }\n  }\n}\n\n/**\n * Idempotent per plugin — re-registration replaces that plugin's\n * declarations. A seat add-on, lockdown or catalog permission key another\n * plugin already owns refuses the whole registration: one key, one owner,\n * or the two declarations disagree about what the key means.\n */\nexport function registerPluginEntitlements(\n  registration: PluginEntitlementRegistration,\n): void {\n  const pluginId = registration.pluginId.trim()\n  if (!pluginId) throw new Error('plugin entitlements need a pluginId')\n  refuseStolenKeys(\n    pluginId,\n    'seat add-on',\n    (registration.seatAddons ?? []).map((entry) => entry.key),\n    (key) => pluginSeatAddonOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'lockdown feature',\n    (registration.lockdownFeatures ?? []).map((entry) => entry.key),\n    (key) => pluginLockdownFeatureOwner(key),\n  )\n  refuseStolenKeys(\n    pluginId,\n    'org permission',\n    (registration.orgPermissions ?? []).map((entry) => entry.key),\n    (key) => pluginOrgPermissionOwner(key),\n  )\n  registrations.set(pluginId, { ...registration, pluginId })\n  if (registration.permissions?.length) {\n    registerPluginPermissions(\n      registration.permissions.map((permission) => ({ ...permission, pluginId })),\n    )\n  }\n  notifyListeners()\n}\n\nfunction pluginSeatAddonOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.seatAddons?.some((addon) => addon.key === key)) return entry.pluginId\n  }\n  return undefined\n}\n\nfunction pluginLockdownFeatureOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.lockdownFeatures?.some((feature) => feature.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\nfunction pluginOrgPermissionOwner(key: string): string | undefined {\n  for (const entry of registrations.values()) {\n    if (entry.orgPermissions?.some((permission) => permission.key === key)) {\n      return entry.pluginId\n    }\n  }\n  return undefined\n}\n\n/** Every declared catalog permission, in catalog order, with the plugin that declared it. */\nexport function listPluginOrgPermissions(): Array<\n  PluginOrgPermissionDeclaration & { pluginId: string }\n> {\n  return orderedRegistrations().flatMap((entry) =>\n    (entry.orgPermissions ?? []).map((permission) => ({\n      ...permission,\n      pluginId: entry.pluginId,\n    })),\n  )\n}\n\n/** Every declared seat add-on, in catalog order. */\nexport function listPluginSeatAddons(): PluginSeatAddonDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.seatAddons ?? [])])\n}\n\n/** One declared seat add-on by its `seatAddons` key. */\nexport function pluginSeatAddon(key: string): PluginSeatAddonDeclaration | undefined {\n  return listPluginSeatAddons().find((entry) => entry.key === key)\n}\n\n/** Every declared feature, in catalog order. */\nexport function listPluginFeatures(): PluginFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [...(entry.features ?? [])])\n}\n\n/** Every declared lockdown lever, in catalog order. */\nexport function listPluginLockdownFeatures(): PluginLockdownFeatureDeclaration[] {\n  return orderedRegistrations().flatMap((entry) => [\n    ...(entry.lockdownFeatures ?? []),\n  ])\n}\n\n/** One declared lockdown lever by key. */\nexport function pluginLockdownFeature(\n  key: string,\n): PluginLockdownFeatureDeclaration | undefined {\n  return listPluginLockdownFeatures().find((entry) => entry.key === key)\n}\n\n/** The plugin that declared a lockdown lever, for attribution. */\nexport function pluginIdForLockdownFeature(key: string): string | undefined {\n  return pluginLockdownFeatureOwner(key)\n}\n\n/** Every registration, in catalog order. */\nexport function listPluginEntitlementRegistrations(): PluginEntitlementRegistration[] {\n  return orderedRegistrations()\n}\n\n/**\n * Test seam: forget every registration. The per-tier permissions stay\n * registered; the catalog permissions go with their registrations.\n */\nexport function resetPluginEntitlementsForTests(): void {\n  registrations.clear()\n  notifyListeners()\n}\n"],"names":["FIRST_PARTY_PLUGINS","registerPluginPermissions","registrations","Map","listeners","Set","subscribePluginEntitlements","listener","add","delete","notifyListeners","CATALOG_ORDER","map","plugin","index","id","catalogRank","pluginId","get","Number","MAX_SAFE_INTEGER","orderedRegistrations","values","sort","a","b","localeCompare","refuseStolenKeys","kind","keys","ownerOf","key","owner","Error","registerPluginEntitlements","registration","trim","seatAddons","entry","pluginSeatAddonOwner","lockdownFeatures","pluginLockdownFeatureOwner","orgPermissions","pluginOrgPermissionOwner","set","permissions","length","permission","some","addon","undefined","feature","listPluginOrgPermissions","flatMap","listPluginSeatAddons","pluginSeatAddon","find","listPluginFeatures","features","listPluginLockdownFeatures","pluginLockdownFeature","pluginIdForLockdownFeature","listPluginEntitlementRegistrations","resetPluginEntitlementsForTests","clear"],"mappings":"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"}

package/src/lib/plugin-manager/plugin-events.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @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.
+ */
+/**
+ * Platform events a plugin listens to (AGL-2939, AGL-2940).
+ *
+ * Core raises a small number of facts about the workspace that a plugin
+ * may care about — a seat add-on was bought or dropped, a permission key
+ * moved on a member, a role or a site — and a plugin subscribes from its
+ * declarations rather than core calling the plugin's own writer. The
+ * billing-webhook hooks are the precedent for one vendor's events; this is
+ * the same shape for the platform's own.
+ *
+ * Handlers run sequentially and are ISOLATED: a plugin that throws is
+ * logged and the next one runs, because these are consequences of a write
+ * that has already happened — an activity row, a notification — and a
+ * failure in one must not undo or hide the write for the customer.
+ */
+import type { OrgSeatAddons } from '../foundation';
+/** Who did it, as the activity logs record an actor. */
+export interface PluginEventActor {
+    uid: string | null;
+    email: string | null;
+}
+/** The payload each platform event carries. */
+export interface PluginEventPayloads {
+    /** An org's purchased seat add-ons were written (a purchase, a removal, a webhook mirror). */
+    'org.seatAddons.changed': {
+        orgId: string;
+        actor: PluginEventActor;
+        before: OrgSeatAddons | null | undefined;
+        after: OrgSeatAddons | null | undefined;
+    };
+    /**
+     * The workspace's Stripe invoice was paid, in full, by a real charge.
+     *
+     * Raised from the platform billing webhook once the invoice has resolved
+     * to a workspace, so a plugin that bills its own usage learns the outcome
+     * of the invoice it asked for without subscribing to Stripe itself. The
+     * invoice's own `metadata` travels with it, unread by core: a plugin that
+     * stamped `pluginId` on the invoice it created recognizes its own by it,
+     * and every other handler ignores the event.
+     *
+     * `paidOutOfBand` is Stripe's own flag for an invoice marked paid without
+     * a charge. A plugin counting payment history must not count one: it is a
+     * staff action, not evidence that money moved.
+     */
+    'billing.invoice.paid': {
+        orgId: string;
+        invoiceId: string;
+        amountPaidCents: number;
+        currency: string;
+        paidOutOfBand: boolean;
+        metadata: Readonly<Record<string, string>>;
+    };
+    /** A charge attempt on the workspace's invoice failed or needs action. */
+    'billing.invoice.failed': {
+        orgId: string;
+        invoiceId: string;
+        amountDueCents: number;
+        metadata: Readonly<Record<string, string>>;
+    };
+    /**
+     * An invoice was closed without being paid — voided, or written off as
+     * uncollectible.
+     *
+     * ONE event for both Stripe events because they are one fact to a plugin:
+     * this invoice will never be paid and nothing more is owed on it. A
+     * handler that must tell them apart reads `reason`; one that only needs
+     * to stop waiting does not.
+     */
+    'billing.invoice.closed': {
+        orgId: string;
+        invoiceId: string;
+        reason: 'voided' | 'uncollectible';
+        metadata: Readonly<Record<string, string>>;
+    };
+    /** A cardholder disputed a charge of the workspace's. */
+    'billing.dispute.opened': {
+        orgId: string;
+        chargeId: string;
+        invoiceId: string | null;
+        amountCents: number;
+    };
+    /**
+     * The workspace's default payment method changed, or its type did.
+     *
+     * `defaultType` is Stripe's own type string (`card`, `us_bank_account`,
+     * `link`, …), or `null` when the customer has no default. Core states the
+     * fact and takes no view: which types a plugin will extend credit against
+     * is the plugin's decision, not the platform's.
+     */
+    'billing.paymentMethod.changed': {
+        orgId: string;
+        defaultType: string | null;
+    };
+    /** One permission key moved on a subject of the org. */
+    'org.permissions.changed': {
+        orgId: string;
+        actor: PluginEventActor;
+        subject: {
+            type: 'org' | 'role' | 'member' | 'host';
+            id?: string | null;
+            name?: string | null;
+        };
+        permission: string;
+        granted: boolean;
+    };
+}
+export type PluginEventName = keyof PluginEventPayloads;
+export type PluginEventHandler<E extends PluginEventName> = (payload: PluginEventPayloads[E]) => void | Promise<void>;
+/**
+ * Subscribes to an event. Owner = the loader's marker inside a register fn,
+ * else `options.pluginId`; a subscription with neither throws. A plugin
+ * re-subscribing replaces its earlier handler for that event, so a module
+ * evaluated twice does not write two rows.
+ */
+export declare function registerPluginEventHandler<E extends PluginEventName>(event: E, handler: PluginEventHandler<E>, options?: {
+    pluginId?: string;
+}): void;
+/**
+ * Raises an event. Every handler runs, in subscription order; a throw is
+ * logged with the plugin's id and does not stop the others.
+ */
+export declare function runPluginEventHandlers<E extends PluginEventName>(event: E, payload: PluginEventPayloads[E]): Promise<{
+    handled: number;
+    failed: string[];
+}>;
+/** The plugins subscribed to an event, for diagnostics. */
+export declare function listPluginEventHandlers(event: PluginEventName): string[];
+/** Test seam: forget every subscription. */
+export declare function resetPluginEventHandlersForTests(): void;

package/src/lib/plugin-manager/plugin-events.js

@@ -0,0 +1,79 @@
+/**
+ * @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.
+ */ /**
+ * Platform events a plugin listens to (AGL-2939, AGL-2940).
+ *
+ * Core raises a small number of facts about the workspace that a plugin
+ * may care about — a seat add-on was bought or dropped, a permission key
+ * moved on a member, a role or a site — and a plugin subscribes from its
+ * declarations rather than core calling the plugin's own writer. The
+ * billing-webhook hooks are the precedent for one vendor's events; this is
+ * the same shape for the platform's own.
+ *
+ * Handlers run sequentially and are ISOLATED: a plugin that throws is
+ * logged and the next one runs, because these are consequences of a write
+ * that has already happened — an activity row, a notification — and a
+ * failure in one must not undo or hide the write for the customer.
+ */ import { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+const handlers = new Map();
+/**
+ * Subscribes to an event. Owner = the loader's marker inside a register fn,
+ * else `options.pluginId`; a subscription with neither throws. A plugin
+ * re-subscribing replaces its earlier handler for that event, so a module
+ * evaluated twice does not write two rows.
+ */ export function registerPluginEventHandler(event, handler, options) {
+    var _ref, _getRegisteringPluginId, _handlers_get;
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`plugin event "${event}" subscribed with no owner: pass { pluginId } ` + 'when subscribing outside a plugin register fn');
+    }
+    const list = ((_handlers_get = handlers.get(event)) != null ? _handlers_get : []).filter((entry)=>entry.pluginId !== pluginId);
+    list.push({
+        pluginId,
+        handler: handler
+    });
+    handlers.set(event, list);
+}
+/**
+ * Raises an event. Every handler runs, in subscription order; a throw is
+ * logged with the plugin's id and does not stop the others.
+ */ export async function runPluginEventHandlers(event, payload) {
+    var _handlers_get;
+    let handled = 0;
+    const failed = [];
+    for (const { pluginId, handler } of (_handlers_get = handlers.get(event)) != null ? _handlers_get : []){
+        try {
+            await handler(payload);
+            handled += 1;
+        } catch (error) {
+            failed.push(pluginId);
+            console.error(`[plugins] ${pluginId} failed on event ${event}`, error);
+        }
+    }
+    return {
+        handled,
+        failed
+    };
+}
+/** The plugins subscribed to an event, for diagnostics. */ export function listPluginEventHandlers(event) {
+    var _handlers_get;
+    return ((_handlers_get = handlers.get(event)) != null ? _handlers_get : []).map((entry)=>entry.pluginId);
+}
+/** Test seam: forget every subscription. */ export function resetPluginEventHandlersForTests() {
+    handlers.clear();
+}
+
+//# sourceMappingURL=plugin-events.js.map

package/src/lib/plugin-manager/plugin-events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-events.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/**\n * Platform events a plugin listens to (AGL-2939, AGL-2940).\n *\n * Core raises a small number of facts about the workspace that a plugin\n * may care about — a seat add-on was bought or dropped, a permission key\n * moved on a member, a role or a site — and a plugin subscribes from its\n * declarations rather than core calling the plugin's own writer. The\n * billing-webhook hooks are the precedent for one vendor's events; this is\n * the same shape for the platform's own.\n *\n * Handlers run sequentially and are ISOLATED: a plugin that throws is\n * logged and the next one runs, because these are consequences of a write\n * that has already happened — an activity row, a notification — and a\n * failure in one must not undo or hide the write for the customer.\n */\n\nimport type { OrgSeatAddons } from '../foundation'\nimport { getRegisteringPluginId } from '../app-utils/registering-plugin'\n\n/** Who did it, as the activity logs record an actor. */\nexport interface PluginEventActor {\n  uid: string | null\n  email: string | null\n}\n\n/** The payload each platform event carries. */\nexport interface PluginEventPayloads {\n  /** An org's purchased seat add-ons were written (a purchase, a removal, a webhook mirror). */\n  'org.seatAddons.changed': {\n    orgId: string\n    actor: PluginEventActor\n    before: OrgSeatAddons | null | undefined\n    after: OrgSeatAddons | null | undefined\n  }\n  /**\n   * The workspace's Stripe invoice was paid, in full, by a real charge.\n   *\n   * Raised from the platform billing webhook once the invoice has resolved\n   * to a workspace, so a plugin that bills its own usage learns the outcome\n   * of the invoice it asked for without subscribing to Stripe itself. The\n   * invoice's own `metadata` travels with it, unread by core: a plugin that\n   * stamped `pluginId` on the invoice it created recognizes its own by it,\n   * and every other handler ignores the event.\n   *\n   * `paidOutOfBand` is Stripe's own flag for an invoice marked paid without\n   * a charge. A plugin counting payment history must not count one: it is a\n   * staff action, not evidence that money moved.\n   */\n  'billing.invoice.paid': {\n    orgId: string\n    invoiceId: string\n    amountPaidCents: number\n    currency: string\n    paidOutOfBand: boolean\n    metadata: Readonly<Record<string, string>>\n  }\n  /** A charge attempt on the workspace's invoice failed or needs action. */\n  'billing.invoice.failed': {\n    orgId: string\n    invoiceId: string\n    amountDueCents: number\n    metadata: Readonly<Record<string, string>>\n  }\n  /**\n   * An invoice was closed without being paid — voided, or written off as\n   * uncollectible.\n   *\n   * ONE event for both Stripe events because they are one fact to a plugin:\n   * this invoice will never be paid and nothing more is owed on it. A\n   * handler that must tell them apart reads `reason`; one that only needs\n   * to stop waiting does not.\n   */\n  'billing.invoice.closed': {\n    orgId: string\n    invoiceId: string\n    reason: 'voided' | 'uncollectible'\n    metadata: Readonly<Record<string, string>>\n  }\n  /** A cardholder disputed a charge of the workspace's. */\n  'billing.dispute.opened': {\n    orgId: string\n    chargeId: string\n    invoiceId: string | null\n    amountCents: number\n  }\n  /**\n   * The workspace's default payment method changed, or its type did.\n   *\n   * `defaultType` is Stripe's own type string (`card`, `us_bank_account`,\n   * `link`, …), or `null` when the customer has no default. Core states the\n   * fact and takes no view: which types a plugin will extend credit against\n   * is the plugin's decision, not the platform's.\n   */\n  'billing.paymentMethod.changed': {\n    orgId: string\n    defaultType: string | null\n  }\n  /** One permission key moved on a subject of the org. */\n  'org.permissions.changed': {\n    orgId: string\n    actor: PluginEventActor\n    subject: {\n      type: 'org' | 'role' | 'member' | 'host'\n      id?: string | null\n      name?: string | null\n    }\n    permission: string\n    granted: boolean\n  }\n}\n\nexport type PluginEventName = keyof PluginEventPayloads\n\nexport type PluginEventHandler<E extends PluginEventName> = (\n  payload: PluginEventPayloads[E],\n) => void | Promise<void>\n\ninterface Registration {\n  pluginId: string\n  handler: PluginEventHandler<PluginEventName>\n}\n\nconst handlers = new Map<PluginEventName, Registration[]>()\n\n/**\n * Subscribes to an event. Owner = the loader's marker inside a register fn,\n * else `options.pluginId`; a subscription with neither throws. A plugin\n * re-subscribing replaces its earlier handler for that event, so a module\n * evaluated twice does not write two rows.\n */\nexport function registerPluginEventHandler<E extends PluginEventName>(\n  event: E,\n  handler: PluginEventHandler<E>,\n  options?: { pluginId?: string },\n): void {\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(\n      `plugin event \"${event}\" subscribed with no owner: pass { pluginId } ` +\n        'when subscribing outside a plugin register fn',\n    )\n  }\n  const list = (handlers.get(event) ?? []).filter((entry) => entry.pluginId !== pluginId)\n  list.push({ pluginId, handler: handler as PluginEventHandler<PluginEventName> })\n  handlers.set(event, list)\n}\n\n/**\n * Raises an event. Every handler runs, in subscription order; a throw is\n * logged with the plugin's id and does not stop the others.\n */\nexport async function runPluginEventHandlers<E extends PluginEventName>(\n  event: E,\n  payload: PluginEventPayloads[E],\n): Promise<{ handled: number; failed: string[] }> {\n  let handled = 0\n  const failed: string[] = []\n  for (const { pluginId, handler } of handlers.get(event) ?? []) {\n    try {\n      await handler(payload)\n      handled += 1\n    } catch (error) {\n      failed.push(pluginId)\n      console.error(`[plugins] ${pluginId} failed on event ${event}`, error)\n    }\n  }\n  return { handled, failed }\n}\n\n/** The plugins subscribed to an event, for diagnostics. */\nexport function listPluginEventHandlers(event: PluginEventName): string[] {\n  return (handlers.get(event) ?? []).map((entry) => entry.pluginId)\n}\n\n/** Test seam: forget every subscription. */\nexport function resetPluginEventHandlersForTests(): void {\n  handlers.clear()\n}\n"],"names":["getRegisteringPluginId","handlers","Map","registerPluginEventHandler","event","handler","options","pluginId","trim","Error","list","get","filter","entry","push","set","runPluginEventHandlers","payload","handled","failed","error","console","listPluginEventHandlers","map","resetPluginEventHandlersForTests","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;CAcC,GAGD,SAASA,sBAAsB,QAAQ,qCAAiC;AAyGxE,MAAMC,WAAW,IAAIC;AAErB;;;;;CAKC,GACD,OAAO,SAASC,2BACdC,KAAQ,EACRC,OAA8B,EAC9BC,OAA+B;QAEbN,MAAAA,yBAOJC;IAPd,MAAMM,WAAW,EAACP,QAAAA,0BAAAA,oCAAAA,0BAA4BM,2BAAAA,QAASC,QAAQ,YAA7CP,OAAiD,IAAIQ,IAAI;IAC3E,IAAI,CAACD,UAAU;QACb,MAAM,IAAIE,MACR,CAAC,cAAc,EAAEL,MAAM,8CAA8C,CAAC,GACpE;IAEN;IACA,MAAMM,OAAO,EAACT,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,EAAEW,MAAM,CAAC,CAACC,QAAUA,MAAMN,QAAQ,KAAKA;IAC9EG,KAAKI,IAAI,CAAC;QAAEP;QAAUF,SAASA;IAA+C;IAC9EJ,SAASc,GAAG,CAACX,OAAOM;AACtB;AAEA;;;CAGC,GACD,OAAO,eAAeM,uBACpBZ,KAAQ,EACRa,OAA+B;QAIKhB;IAFpC,IAAIiB,UAAU;IACd,MAAMC,SAAmB,EAAE;IAC3B,KAAK,MAAM,EAAEZ,QAAQ,EAAEF,OAAO,EAAE,KAAIJ,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,CAAE;QAC7D,IAAI;YACF,MAAMI,QAAQY;YACdC,WAAW;QACb,EAAE,OAAOE,OAAO;YACdD,OAAOL,IAAI,CAACP;YACZc,QAAQD,KAAK,CAAC,CAAC,UAAU,EAAEb,SAAS,iBAAiB,EAAEH,OAAO,EAAEgB;QAClE;IACF;IACA,OAAO;QAAEF;QAASC;IAAO;AAC3B;AAEA,yDAAyD,GACzD,OAAO,SAASG,wBAAwBlB,KAAsB;QACpDH;IAAR,OAAO,EAACA,gBAAAA,SAASU,GAAG,CAACP,kBAAbH,gBAAuB,EAAE,EAAEsB,GAAG,CAAC,CAACV,QAAUA,MAAMN,QAAQ;AAClE;AAEA,0CAA0C,GAC1C,OAAO,SAASiB;IACdvB,SAASwB,KAAK;AAChB"}

package/src/lib/plugin-manager/plugin-figures.d.ts

@@ -0,0 +1,251 @@
+/**
+ * @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.
+ */
+/**
+ * Figures one plugin publishes for another (AGL-2915).
+ *
+ * The records behind a figure belong to the plugin that models them: orders
+ * to commerce, bookings to bookings, campaigns and experiments to marketing.
+ * The owner knows which documents count, which are test data, what a refund
+ * does to revenue and which fields could name a person. A different plugin
+ * that wants the figure — a weekly report, an export, an assistant answering
+ * a question about the numbers — must not read those documents itself,
+ * because it would restate the owner's rules and drift from them the day the
+ * owner changes one. Nor may it import the owner, which the package map
+ * forbids.
+ *
+ * So the owner registers a READER from its server surfaces, and a caller asks
+ * for one by id. A reader answers with one compact table:
+ *
+ *  - read-only: a reader writes nothing, schedules nothing and sends nothing;
+ *  - aggregate: counts, sums, rates and labels, never the records themselves;
+ *  - about nobody: no row names a person, and no cell carries a name, an email
+ *    address, a phone number or a street address — a customer is counted,
+ *    never listed;
+ *  - bounded: at most `PLUGIN_FIGURE_MAX_ROWS` rows, each labelled with where
+ *    in the console the figures come from.
+ *
+ * Built on the typed service registry (`plugin-services`): one contract, every
+ * reader registered under its id as the service's key.
+ *
+ * ## The registry carries no authorization of the CALLER
+ *
+ * Like `plugin-resource-drafts`, a reader is a pre-authorized operation: it
+ * reads the site or the workspace it is handed. A caller establishes, in its
+ * own terms and before it asks, who is asking, that the org owns the site, that
+ * the person may see that site's figures, and that the owning plugin is
+ * switched on for it.
+ *
+ * ## A table is checked on the way out as well as on the way in
+ *
+ * `normalizePluginFigureTable` holds whatever a reader returned to the shape
+ * above — row and cell bounds, column kinds, and personal details masked in
+ * every text cell — so a consumer that shows or forwards a table relies on the
+ * contract rather than on every reader having kept it.
+ */
+/** Whether a reader's figures are about one site or about the whole workspace. */
+export type PluginFigureScope = 'site' | 'org';
+/**
+ * How a column's cells read:
+ *
+ * - `text` — a label: a page path, a form's name, a region;
+ * - `count` — a whole number of things;
+ * - `number` — any other figure, such as an average per day;
+ * - `money` — an amount in major units of the column's `currency`;
+ * - `percent` — a share or a rate, from 0 to 100;
+ * - `change` — the percent change from the window before; `null` where there
+ *   is no earlier window to compare with, never 0 or 100;
+ * - `duration` — seconds;
+ * - `date` — a calendar day, `YYYY-MM-DD`.
+ */
+export type PluginFigureColumnKind = 'text' | 'count' | 'number' | 'money' | 'percent' | 'change' | 'duration' | 'date';
+export declare const PLUGIN_FIGURE_COLUMN_KINDS: readonly PluginFigureColumnKind[];
+export interface PluginFigureColumn {
+    /** The row field the column reads. */
+    key: string;
+    label: string;
+    kind: PluginFigureColumnKind;
+    /** The ISO 4217 code of a `money` column. */
+    currency?: string;
+}
+export type PluginFigureCell = string | number | null;
+export type PluginFigureRow = Record<string, PluginFigureCell>;
+export interface PluginFigureTable {
+    title: string;
+    /**
+     * Where the figures come from: the name of the console page, and its path
+     * under the site's console root for a site reader, or under the workspace's
+     * for an org reader (`commerce/orders`), so a consumer can link to it.
+     */
+    source: {
+        label: string;
+        path: string | null;
+    };
+    /** The days the figures cover, inclusive; `null` for a current count. */
+    period: {
+        from: string;
+        to: string;
+        days: number;
+    } | null;
+    columns: PluginFigureColumn[];
+    rows: PluginFigureRow[];
+    /** Rows the reader left out past its bound. */
+    omitted: number;
+    /** Short plain sentences a reader of the figures needs, such as a window with nothing earlier to compare with. */
+    notes: string[];
+}
+export interface PluginFigureRequest {
+    orgId: string;
+    /** The site a `site` reader reads; for an `org` reader, the site the figures are narrowed to, or `null`. */
+    hostId: string | null;
+    /** The window, in days, ending at `now`: one of the reader's `windows`, or 0 for a reader with none. */
+    days: number;
+    now: Date;
+    /**
+     * The member asking. A reader of records a member may see only part of —
+     * a dataset shared with some sites — reads what this member may see; with
+     * `null`, nobody asked, and it reads only what every member of the site may.
+     */
+    uid: string | null;
+    /** The reader's own parameters, by the names its `params` declare; each a string. */
+    params: Readonly<Record<string, string>>;
+}
+/** One parameter a reader takes beyond its window. */
+export interface PluginFigureParam {
+    /** The name a request carries it under: letters, digits and underscores. */
+    name: string;
+    /** What it selects, in one plain sentence. */
+    description: string;
+    required: boolean;
+}
+export type PluginFigureRead = {
+    ok: true;
+    table: PluginFigureTable;
+} | {
+    ok: false;
+    status: 400 | 403 | 404;
+    /** Customer-safe: a caller shows it as it stands. */
+    error: string;
+};
+export interface PluginFigureReader {
+    /** Stable and unique across plugins: lowercase words joined by dots (`commerce.orders`). */
+    id: string;
+    /** What a person calls the figures: "Orders". */
+    label: string;
+    /**
+     * What the reader answers, in one or two plain sentences. The same bytes for
+     * every site, so a list of readers can be shown to anyone who may use them.
+     */
+    description: string;
+    scope: PluginFigureScope;
+    /** The windows the reader covers, in days; empty for a reader of current counts. */
+    windows: readonly number[];
+    /**
+     * The plugin whose records the figures are read from, which must run on the
+     * site — or on the workspace, for an `org` reader — before anyone is offered
+     * the reader. Absent, the plugin that registered it; `null` for figures the
+     * platform itself keeps, such as page views.
+     */
+    plugin?: string | null;
+    /** The plan feature the figures are sold under; a workspace without it is not offered the reader. */
+    feature?: string;
+    /** The parameters the reader takes beyond its window; absent for none. */
+    params?: readonly PluginFigureParam[];
+    read(request: PluginFigureRequest): Promise<PluginFigureRead>;
+}
+export declare const PLUGIN_FIGURES: import("./plugin-services").PluginServiceContract<PluginFigureReader>;
+/** The most rows one table carries; the rest are counted in `omitted`. */
+export declare const PLUGIN_FIGURE_MAX_ROWS = 25;
+/** The most columns one table carries. */
+export declare const PLUGIN_FIGURE_MAX_COLUMNS = 8;
+/** The longest text cell, title or label a table carries, in characters. */
+export declare const PLUGIN_FIGURE_MAX_TEXT = 120;
+/** The most notes one table carries. */
+export declare const PLUGIN_FIGURE_MAX_NOTES = 3;
+/**
+ * Registers a reader. The owner is the loader's marker when a register fn is
+ * running, else `options.pluginId`; with neither the registration throws. A
+ * reader id another plugin already registered throws naming both, and the
+ * incumbent keeps serving; the same plugin registering again replaces its own.
+ */
+export declare function registerPluginFigureReader(reader: PluginFigureReader, options?: {
+    pluginId?: string;
+}): void;
+export interface ResolvedPluginFigureReader {
+    /** The plugin that owns the records behind the figures. */
+    pluginId: string;
+    reader: PluginFigureReader;
+}
+/** The reader registered under an id, with its owner, or `null`. */
+export declare function pluginFigureReader(id: string): ResolvedPluginFigureReader | null;
+/** Every registered reader with its owner, ordered by id so a list of them is the same bytes on every call. */
+export declare function listPluginFigureReaders(): ResolvedPluginFigureReader[];
+/** The plugin that must run for a reader to be offered: its own `plugin`, else its owner; `null` for platform figures. */
+export declare function pluginFigureReaderPlugin(resolved: ResolvedPluginFigureReader): string | null;
+/**
+ * The parameters a request carries that the reader declares, each trimmed to
+ * a short string, or the name of the first required one that is missing.
+ */
+export declare function pluginFigureParams(reader: Pick<PluginFigureReader, 'params'>, raw: Readonly<Record<string, unknown>> | null | undefined): {
+    ok: true;
+    params: Record<string, string>;
+} | {
+    ok: false;
+    missing: string;
+};
+/**
+ * The text with every email address and phone number replaced by a marker.
+ * A figure's label is never meant to carry either, so a match is masked
+ * rather than trusted: a campaign named after a person's address says
+ * nothing about the campaign that the marker does not.
+ */
+export declare function maskPersonalDetails(text: string): string;
+/** Whether a text carries an email address or a phone number. */
+export declare function hasPersonalDetails(text: string): boolean;
+/**
+ * A reader's table held to the contract: bounded, typed and masked. Columns
+ * with a key, a kind or a currency the contract does not know are dropped, and
+ * every cell is read through its column, so a cell of the wrong type is `null`
+ * rather than passed on. `null` for a value that is not a table at all.
+ */
+export declare function normalizePluginFigureTable(value: unknown): PluginFigureTable | null;
+/** A calendar day in UTC. */
+export declare function pluginFigureDay(at: Date): string;
+/**
+ * The window of `days` ending on the day of `now`, inclusive, and the window
+ * of the same length immediately before it: what every `change` column
+ * compares, so a figure from one reader compares like a figure from another.
+ */
+export declare function pluginFigureWindows(now: Date, days: number): {
+    current: {
+        from: string;
+        to: string;
+        startMs: number;
+        endMs: number;
+    };
+    previous: {
+        from: string;
+        to: string;
+        startMs: number;
+        endMs: number;
+    };
+};
+/**
+ * The percent change from `previous` to `current`, to one decimal place.
+ * `null` when there is nothing earlier to compare with, so a first window
+ * reads as no change figure at all rather than as a rise from zero.
+ */
+export declare function pluginFigureChange(current: number, previous: number | null): number | null;