@aglyn/aglyn 1.0.0-beta.230 → 1.0.0-beta.231

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

@@ -21,7 +21,24 @@
  * `ConsolePluginPageProps.permissions` and API-side resolution carry them
  * with zero app changes. Register at module scope from both the client
  * barrel and the /server entry (the AGL-428 pattern).
- */ const pluginPermissions = new Map();
+ */ var _globalScope_REGISTRY_KEY;
+/*
+ * One registry per process, keyed on `globalThis` under `Symbol.for`, like
+ * `plugin-services.ts`. Next compiles the boot file and the route handlers
+ * apart, so each can hold its own copy of this module: with the map at module
+ * scope, a plugin's keys registered by one copy were absent from the copy
+ * `resolveOrgPermissions` read, an absent key reads as refused, and the
+ * register's `managePos` gate answered 403 to the site's own owner.
+ */ const REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-permissions');
+const globalScope = globalThis;
+const tables = (_globalScope_REGISTRY_KEY = globalScope[REGISTRY_KEY]) != null ? _globalScope_REGISTRY_KEY : globalScope[REGISTRY_KEY] = {
+    permissions: new Map(),
+    listeners: new Set(),
+    version: {
+        value: 0
+    }
+};
+const pluginPermissions = tables.permissions;
 /*
  * Whoever resolved a permission map before a plugin registered holds a map
  * without that plugin's keys, and a key that is absent reads as refused
@@ -31,8 +48,7 @@
  * they hold by default until the next full render. So registration is
  * observable, the way `subscribePluginEntitlements` makes the org catalog's
  * registrations observable, and the provider re-reads on every change.
- */ let registrationVersion = 0;
-const listeners = new Set();
+ */ const listeners = tables.listeners;
 /** Calls `listener` after every registration; answers the unsubscribe. */ export function subscribePluginPermissions(listener) {
     listeners.add(listener);
     return ()=>{
@@ -43,10 +59,10 @@ const listeners = new Set();
  * A number that changes whenever the registry does — the snapshot for a
  * `useSyncExternalStore` over `subscribePluginPermissions`.
  */ export function pluginPermissionsVersion() {
-    return registrationVersion;
+    return tables.version.value;
 }
 function notifyListeners() {
-    registrationVersion += 1;
+    tables.version.value += 1;
     for (const listener of [
         ...listeners
     ])listener();

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-permissions.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 permissions (AGL-435, Strapi RBAC-actions parity): a\n * plugin contributes NAMED permission keys with per-role-tier defaults.\n * `resolveRolePermissions` spreads them into every resolved set (custom\n * roles override key-by-key exactly like built-in keys), so\n * `ConsolePluginPageProps.permissions` and API-side resolution carry them\n * with zero app changes. Register at module scope from both the client\n * barrel and the /server entry (the AGL-428 pattern).\n */\n\nexport interface PluginPermission {\n  /** Stable key ('managePos') — persisted in custom role docs. */\n  key: string\n  pluginId: string\n  label: string\n  description?: string\n  /** Verdict per built-in role tier when a role doesn't name the key. */\n  defaults: { admin: boolean; editor: boolean; viewer: boolean }\n}\n\nconst pluginPermissions = new Map<string, PluginPermission>()\n\n/*\n * Whoever resolved a permission map before a plugin registered holds a map\n * without that plugin's keys, and a key that is absent reads as refused\n * (AGL-3228). The console's permission provider resolved its map when the\n * member document arrived; on a cold load of a plugin's deep link the\n * plugin's chunk can register AFTER that, so the owner was refused a surface\n * they hold by default until the next full render. So registration is\n * observable, the way `subscribePluginEntitlements` makes the org catalog's\n * registrations observable, and the provider re-reads on every change.\n */\nlet registrationVersion = 0\nconst listeners = new Set<() => void>()\n\n/** Calls `listener` after every registration; answers the unsubscribe. */\nexport function subscribePluginPermissions(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * A number that changes whenever the registry does — the snapshot for a\n * `useSyncExternalStore` over `subscribePluginPermissions`.\n */\nexport function pluginPermissionsVersion(): number {\n  return registrationVersion\n}\n\nfunction notifyListeners(): void {\n  registrationVersion += 1\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Idempotent per key FOR ITS OWNER — the declaring plugin may re-register\n * (hot reload, a second surface, a repeated init) and its entry is replaced.\n *\n * A key already declared by a DIFFERENT plugin is refused (AGL-2484). This\n * map keyed on `permission.key` alone, so a later registration could redeclare\n * someone else's key with its own tier defaults — and these defaults are not\n * cosmetic: `managePos` is enforced server-side in\n * `libs/plugins/commerce/src/lib/server/pos-order.ts`, so moving\n * `defaults.viewer` to `true` hands a viewer the register. Reaching this\n * needs `PLUGIN_REMOTE_SERVER=enabled` (off by default), realm trust and a\n * signature; the registry closing its own door is the cheap part of that\n * stack.\n *\n * Per KEY, not per batch: a bundle that collides on one key still gets the\n * keys that are genuinely its own.\n */\nexport function registerPluginPermissions(\n  permissions: readonly PluginPermission[],\n): void {\n  for (const permission of permissions) {\n    const incumbent = pluginPermissions.get(permission.key)\n    if (incumbent !== undefined && incumbent.pluginId !== permission.pluginId) {\n      console.error(\n        `[plugins] refused permission key \"${permission.key}\" to ` +\n          `\"${permission.pluginId}\": already declared by ` +\n          `\"${incumbent.pluginId}\"`,\n      )\n      continue\n    }\n    pluginPermissions.set(permission.key, permission)\n  }\n  notifyListeners()\n}\n\nexport function listPluginPermissions(): PluginPermission[] {\n  return [...pluginPermissions.values()]\n}\n\n/**\n * The registered keys alone (AGL-2474). `resolveRolePermissions` needs the\n * grantable key SPACE, not the tier verdicts: it used to iterate\n * `ORG_ROLE_PERMISSION_KEYS` — the legacy six — when applying overrides and\n * custom roles, so a plugin-declared key materialised into the resolved map\n * and could then only ever hold its tier default. Read live rather than\n * snapshotted: registration happens at plugin module scope, which can run\n * after any module-level constant here has already been evaluated.\n */\nexport function listPluginPermissionKeys(): string[] {\n  return [...pluginPermissions.keys()]\n}\n\n/** Tier defaults for every registered plugin permission. */\nexport function pluginPermissionDefaults(\n  tier: 'admin' | 'editor' | 'viewer',\n): Record<string, boolean> {\n  const defaults: Record<string, boolean> = {}\n  for (const permission of pluginPermissions.values()) {\n    defaults[permission.key] = permission.defaults[tier]\n  }\n  return defaults\n}\n"],"names":["pluginPermissions","Map","registrationVersion","listeners","Set","subscribePluginPermissions","listener","add","delete","pluginPermissionsVersion","notifyListeners","registerPluginPermissions","permissions","permission","incumbent","get","key","undefined","pluginId","console","error","set","listPluginPermissions","values","listPluginPermissionKeys","keys","pluginPermissionDefaults","tier","defaults"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,GAYD,MAAMA,oBAAoB,IAAIC;AAE9B;;;;;;;;;CASC,GACD,IAAIC,sBAAsB;AAC1B,MAAMC,YAAY,IAAIC;AAEtB,wEAAwE,GACxE,OAAO,SAASC,2BAA2BC,QAAoB;IAC7DH,UAAUI,GAAG,CAACD;IACd,OAAO;QACLH,UAAUK,MAAM,CAACF;IACnB;AACF;AAEA;;;CAGC,GACD,OAAO,SAASG;IACd,OAAOP;AACT;AAEA,SAASQ;IACPR,uBAAuB;IACvB,KAAK,MAAMI,YAAY;WAAIH;KAAU,CAAEG;AACzC;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASK,0BACdC,WAAwC;IAExC,KAAK,MAAMC,cAAcD,YAAa;QACpC,MAAME,YAAYd,kBAAkBe,GAAG,CAACF,WAAWG,GAAG;QACtD,IAAIF,cAAcG,aAAaH,UAAUI,QAAQ,KAAKL,WAAWK,QAAQ,EAAE;YACzEC,QAAQC,KAAK,CACX,CAAC,kCAAkC,EAAEP,WAAWG,GAAG,CAAC,KAAK,CAAC,GACxD,CAAC,CAAC,EAAEH,WAAWK,QAAQ,CAAC,uBAAuB,CAAC,GAChD,CAAC,CAAC,EAAEJ,UAAUI,QAAQ,CAAC,CAAC,CAAC;YAE7B;QACF;QACAlB,kBAAkBqB,GAAG,CAACR,WAAWG,GAAG,EAAEH;IACxC;IACAH;AACF;AAEA,OAAO,SAASY;IACd,OAAO;WAAItB,kBAAkBuB,MAAM;KAAG;AACxC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC;IACd,OAAO;WAAIxB,kBAAkByB,IAAI;KAAG;AACtC;AAEA,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,IAAmC;IAEnC,MAAMC,WAAoC,CAAC;IAC3C,KAAK,MAAMf,cAAcb,kBAAkBuB,MAAM,GAAI;QACnDK,QAAQ,CAACf,WAAWG,GAAG,CAAC,GAAGH,WAAWe,QAAQ,CAACD,KAAK;IACtD;IACA,OAAOC;AACT"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-permissions.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 permissions (AGL-435, Strapi RBAC-actions parity): a\n * plugin contributes NAMED permission keys with per-role-tier defaults.\n * `resolveRolePermissions` spreads them into every resolved set (custom\n * roles override key-by-key exactly like built-in keys), so\n * `ConsolePluginPageProps.permissions` and API-side resolution carry them\n * with zero app changes. Register at module scope from both the client\n * barrel and the /server entry (the AGL-428 pattern).\n */\n\nexport interface PluginPermission {\n  /** Stable key ('managePos') — persisted in custom role docs. */\n  key: string\n  pluginId: string\n  label: string\n  description?: string\n  /** Verdict per built-in role tier when a role doesn't name the key. */\n  defaults: { admin: boolean; editor: boolean; viewer: boolean }\n}\n\n/*\n * One registry per process, keyed on `globalThis` under `Symbol.for`, like\n * `plugin-services.ts`. Next compiles the boot file and the route handlers\n * apart, so each can hold its own copy of this module: with the map at module\n * scope, a plugin's keys registered by one copy were absent from the copy\n * `resolveOrgPermissions` read, an absent key reads as refused, and the\n * register's `managePos` gate answered 403 to the site's own owner.\n */\nconst REGISTRY_KEY = Symbol.for('@aglyn/aglyn:plugin-permissions')\n\ninterface PluginPermissionTables {\n  permissions: Map<string, PluginPermission>\n  listeners: Set<() => void>\n  version: { value: number }\n}\n\nconst globalScope = globalThis as typeof globalThis & {\n  [REGISTRY_KEY]?: PluginPermissionTables\n}\n\nconst tables: PluginPermissionTables =\n  globalScope[REGISTRY_KEY] ??\n  (globalScope[REGISTRY_KEY] = {\n    permissions: new Map(),\n    listeners: new Set(),\n    version: { value: 0 },\n  })\nconst pluginPermissions = tables.permissions\n\n/*\n * Whoever resolved a permission map before a plugin registered holds a map\n * without that plugin's keys, and a key that is absent reads as refused\n * (AGL-3228). The console's permission provider resolved its map when the\n * member document arrived; on a cold load of a plugin's deep link the\n * plugin's chunk can register AFTER that, so the owner was refused a surface\n * they hold by default until the next full render. So registration is\n * observable, the way `subscribePluginEntitlements` makes the org catalog's\n * registrations observable, and the provider re-reads on every change.\n */\nconst listeners = tables.listeners\n\n/** Calls `listener` after every registration; answers the unsubscribe. */\nexport function subscribePluginPermissions(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * A number that changes whenever the registry does — the snapshot for a\n * `useSyncExternalStore` over `subscribePluginPermissions`.\n */\nexport function pluginPermissionsVersion(): number {\n  return tables.version.value\n}\n\nfunction notifyListeners(): void {\n  tables.version.value += 1\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Idempotent per key FOR ITS OWNER — the declaring plugin may re-register\n * (hot reload, a second surface, a repeated init) and its entry is replaced.\n *\n * A key already declared by a DIFFERENT plugin is refused (AGL-2484). This\n * map keyed on `permission.key` alone, so a later registration could redeclare\n * someone else's key with its own tier defaults — and these defaults are not\n * cosmetic: `managePos` is enforced server-side in\n * `libs/plugins/commerce/src/lib/server/pos-order.ts`, so moving\n * `defaults.viewer` to `true` hands a viewer the register. Reaching this\n * needs `PLUGIN_REMOTE_SERVER=enabled` (off by default), realm trust and a\n * signature; the registry closing its own door is the cheap part of that\n * stack.\n *\n * Per KEY, not per batch: a bundle that collides on one key still gets the\n * keys that are genuinely its own.\n */\nexport function registerPluginPermissions(\n  permissions: readonly PluginPermission[],\n): void {\n  for (const permission of permissions) {\n    const incumbent = pluginPermissions.get(permission.key)\n    if (incumbent !== undefined && incumbent.pluginId !== permission.pluginId) {\n      console.error(\n        `[plugins] refused permission key \"${permission.key}\" to ` +\n          `\"${permission.pluginId}\": already declared by ` +\n          `\"${incumbent.pluginId}\"`,\n      )\n      continue\n    }\n    pluginPermissions.set(permission.key, permission)\n  }\n  notifyListeners()\n}\n\nexport function listPluginPermissions(): PluginPermission[] {\n  return [...pluginPermissions.values()]\n}\n\n/**\n * The registered keys alone (AGL-2474). `resolveRolePermissions` needs the\n * grantable key SPACE, not the tier verdicts: it used to iterate\n * `ORG_ROLE_PERMISSION_KEYS` — the legacy six — when applying overrides and\n * custom roles, so a plugin-declared key materialised into the resolved map\n * and could then only ever hold its tier default. Read live rather than\n * snapshotted: registration happens at plugin module scope, which can run\n * after any module-level constant here has already been evaluated.\n */\nexport function listPluginPermissionKeys(): string[] {\n  return [...pluginPermissions.keys()]\n}\n\n/** Tier defaults for every registered plugin permission. */\nexport function pluginPermissionDefaults(\n  tier: 'admin' | 'editor' | 'viewer',\n): Record<string, boolean> {\n  const defaults: Record<string, boolean> = {}\n  for (const permission of pluginPermissions.values()) {\n    defaults[permission.key] = permission.defaults[tier]\n  }\n  return defaults\n}\n"],"names":["globalScope","REGISTRY_KEY","Symbol","for","globalThis","tables","permissions","Map","listeners","Set","version","value","pluginPermissions","subscribePluginPermissions","listener","add","delete","pluginPermissionsVersion","notifyListeners","registerPluginPermissions","permission","incumbent","get","key","undefined","pluginId","console","error","set","listPluginPermissions","values","listPluginPermissionKeys","keys","pluginPermissionDefaults","tier","defaults"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;CAQC,OAiCCA;AArBF;;;;;;;CAOC,GACD,MAAMC,eAAeC,OAAOC,GAAG,CAAC;AAQhC,MAAMH,cAAcI;AAIpB,MAAMC,UACJL,4BAAAA,WAAW,CAACC,aAAa,YAAzBD,4BACCA,WAAW,CAACC,aAAa,GAAG;IAC3BK,aAAa,IAAIC;IACjBC,WAAW,IAAIC;IACfC,SAAS;QAAEC,OAAO;IAAE;AACtB;AACF,MAAMC,oBAAoBP,OAAOC,WAAW;AAE5C;;;;;;;;;CASC,GACD,MAAME,YAAYH,OAAOG,SAAS;AAElC,wEAAwE,GACxE,OAAO,SAASK,2BAA2BC,QAAoB;IAC7DN,UAAUO,GAAG,CAACD;IACd,OAAO;QACLN,UAAUQ,MAAM,CAACF;IACnB;AACF;AAEA;;;CAGC,GACD,OAAO,SAASG;IACd,OAAOZ,OAAOK,OAAO,CAACC,KAAK;AAC7B;AAEA,SAASO;IACPb,OAAOK,OAAO,CAACC,KAAK,IAAI;IACxB,KAAK,MAAMG,YAAY;WAAIN;KAAU,CAAEM;AACzC;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASK,0BACdb,WAAwC;IAExC,KAAK,MAAMc,cAAcd,YAAa;QACpC,MAAMe,YAAYT,kBAAkBU,GAAG,CAACF,WAAWG,GAAG;QACtD,IAAIF,cAAcG,aAAaH,UAAUI,QAAQ,KAAKL,WAAWK,QAAQ,EAAE;YACzEC,QAAQC,KAAK,CACX,CAAC,kCAAkC,EAAEP,WAAWG,GAAG,CAAC,KAAK,CAAC,GACxD,CAAC,CAAC,EAAEH,WAAWK,QAAQ,CAAC,uBAAuB,CAAC,GAChD,CAAC,CAAC,EAAEJ,UAAUI,QAAQ,CAAC,CAAC,CAAC;YAE7B;QACF;QACAb,kBAAkBgB,GAAG,CAACR,WAAWG,GAAG,EAAEH;IACxC;IACAF;AACF;AAEA,OAAO,SAASW;IACd,OAAO;WAAIjB,kBAAkBkB,MAAM;KAAG;AACxC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC;IACd,OAAO;WAAInB,kBAAkBoB,IAAI;KAAG;AACtC;AAEA,0DAA0D,GAC1D,OAAO,SAASC,yBACdC,IAAmC;IAEnC,MAAMC,WAAoC,CAAC;IAC3C,KAAK,MAAMf,cAAcR,kBAAkBkB,MAAM,GAAI;QACnDK,QAAQ,CAACf,WAAWG,GAAG,CAAC,GAAGH,WAAWe,QAAQ,CAACD,KAAK;IACtD;IACA,OAAOC;AACT"}

package/src/lib/plugin-manager/plugin-person-records.d.ts

@@ -190,11 +190,75 @@ export type PluginPersonViewPeople = {
     reason: 'not-found' | 'not-people' | 'unsupported';
     unsupported?: string[];
 };
+/**
+ * People a site may see whose name, address or phone starts with what was
+ * typed (AGL-3609) — a cashier looking a customer up at the register, a
+ * picker anywhere a person is chosen by hand. One word: the owner answers it
+ * from its own search index and never by scanning its records.
+ */
+export interface PluginPersonSearchRequest {
+    /** The site searching: only records it may see are answered. */
+    hostId: string;
+    /** The organization, when the caller knows it; the owner reads it off `hostId` otherwise. */
+    orgId?: string | null;
+    /** What was typed. Raw: the owner normalizes it, and reads a run of digits as a phone. */
+    text: string;
+    /** The most people answered. The owner may answer fewer. */
+    limit: number;
+}
 /** Records to ask about, by the refs the owner handed out. */
 export interface PluginPersonWroteInRequest {
     orgId: string;
     records: readonly PluginPersonRecordRef[];
 }
+/**
+ * The people one site holds, oldest change first, after a cursor (AGL-3639)
+ * — what a connector that mirrors a workspace's people into another system
+ * walks, once from the start as a backfill and then from where it stopped.
+ */
+export interface PluginPersonChangesRequest {
+    /** The site the people are taken for: only records it may see are answered. */
+    hostId: string;
+    orgId?: string | null;
+    /**
+     * Where the last page stopped, exactly as the owner handed it out, or
+     * `null` to start from the earliest change. Opaque: only the owner reads
+     * it, so it can hold a change time finer than a millisecond and the id
+     * that breaks a tie, and a walk neither skips a person nor repeats one.
+     */
+    after: string | null;
+    /** The most people answered; the owner may answer fewer. */
+    limit: number;
+}
+/**
+ * A person as a connector copies them out: the platform's own fields on the
+ * record (`data`, read with the platform's readers — the consent basis
+ * above all), and the owner's profile of them as this site holds it, in the
+ * platform's words rather than the owner's storage.
+ */
+export interface PluginPersonChange extends PluginPersonRecord {
+    /** When the record last changed, epoch ms. */
+    changedAtMs: number;
+    profile: {
+        name: string | null;
+        phone: string | null;
+        tags: string[];
+        /** What the person has spent at this site, integer cents, when the owner keeps it. */
+        lifetimeValueCents: number | null;
+        ordersCount: number | null;
+    };
+}
+export interface PluginPersonChangesPage {
+    people: PluginPersonChange[];
+    /**
+     * Where the next page starts — the cursor to store. It moves past every
+     * record the owner READ, including one it left out for the site, so a page
+     * can be empty and still move on. `null` when nothing changed after the
+     * cursor: the walk has reached the latest change, and the caller keeps the
+     * cursor it asked with.
+     */
+    next: string | null;
+}
 export interface PluginPersonRecords {
     /** The person an address belongs to, or `null`. A read; may throw, and the caller decides which way a failure falls. */
     find(request: PluginPersonFindRequest): Promise<PluginPersonRecord | null>;
@@ -218,6 +282,17 @@ export interface PluginPersonRecords {
      * could not answer. Optional.
      */
     wroteIn?(request: PluginPersonWroteInRequest): Promise<Array<boolean | null>>;
+    /**
+     * People a site may see that match one typed word, best first. Optional:
+     * an owner that keeps no search index answers nothing. A read; may throw.
+     */
+    search?(request: PluginPersonSearchRequest): Promise<PluginPersonRecord[]>;
+    /**
+     * The people a site holds that changed after a cursor, oldest first.
+     * Optional: an owner that cannot walk its records by change answers
+     * nothing. A failed read throws.
+     */
+    changedSince?(request: PluginPersonChangesRequest): Promise<PluginPersonChangesPage>;
 }
 export declare const PLUGIN_PERSON_RECORDS: import("./plugin-services").PluginServiceContract<PluginPersonRecords>;
 /**
@@ -273,3 +348,18 @@ export declare function pluginPeopleInView(request: PluginPersonViewRequest): Pr
  * caller reads an unknown as unknown.
  */
 export declare function pluginPeopleWroteIn(request: PluginPersonWroteInRequest): Promise<Array<boolean | null> | null>;
+/**
+ * People a site may see matching what was typed, or `null` when no plugin
+ * keeps people here or the one that does keeps no search — which is not
+ * "nobody matched". Blank text answers no one without asking. A failed read
+ * throws, and the caller decides how to say so.
+ */
+export declare function searchPluginPeople(request: PluginPersonSearchRequest): Promise<PluginPersonRecord[] | null>;
+/**
+ * The people a site holds that changed after a cursor, oldest first, or
+ * `null` when no plugin keeps people here or the one that does cannot walk
+ * them by change. The limit is clamped to 1–500. A failed read throws: a
+ * connector that skipped a page it could not read would advance past people
+ * it never copied.
+ */
+export declare function pluginPeopleChangedSince(request: PluginPersonChangesRequest): Promise<PluginPersonChangesPage | null>;

package/src/lib/plugin-manager/plugin-person-records.js

@@ -103,5 +103,31 @@ export const PLUGIN_PERSON_RECORDS = definePluginServiceContract('core.person-re
         return null;
     }
 }
+/**
+ * People a site may see matching what was typed, or `null` when no plugin
+ * keeps people here or the one that does keeps no search — which is not
+ * "nobody matched". Blank text answers no one without asking. A failed read
+ * throws, and the caller decides how to say so.
+ */ export async function searchPluginPeople(request) {
+    var _request_text;
+    const resolved = pluginPersonRecords();
+    if (!(resolved == null ? void 0 : resolved.records.search)) return null;
+    if (!String((_request_text = request.text) != null ? _request_text : '').trim() || !(request.limit > 0)) return [];
+    return await resolved.records.search(request);
+}
+/**
+ * The people a site holds that changed after a cursor, oldest first, or
+ * `null` when no plugin keeps people here or the one that does cannot walk
+ * them by change. The limit is clamped to 1–500. A failed read throws: a
+ * connector that skipped a page it could not read would advance past people
+ * it never copied.
+ */ export async function pluginPeopleChangedSince(request) {
+    const resolved = pluginPersonRecords();
+    if (!(resolved == null ? void 0 : resolved.records.changedSince)) return null;
+    const limit = Math.min(500, Math.max(1, Math.floor(Number(request.limit) || 0)));
+    return await resolved.records.changedSince(_extends({}, request, {
+        limit
+    }));
+}
 
 //# sourceMappingURL=plugin-person-records.js.map

package/src/lib/plugin-manager/plugin-person-records.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-person-records.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  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * THE PEOPLE A WORKSPACE KEEPS, asked for by the plugins that do not keep\n * them (AGL-3080).\n *\n * `plugin-contact-capture` is how a silo hands somebody it MET to the plugin\n * that keeps people. This is the other half: a plugin that has an address, or\n * a record the owner handed it, and needs the person behind it.\n *\n *  - a flow email asking whether the person agreed to marketing mail;\n *  - a campaign filling in the name a merge tag reads;\n *  - a refund taking money back off what a customer is worth;\n *  - an automation filing somebody under a campaign;\n *  - a sales sequence reading the people a rep enrolls.\n *\n * Each of those used to open the owner's collection itself — its path, its\n * address index, which site may see which document — and broke the day the\n * owner changed one. None of it is visible to `check:lib-boundaries`, because\n * a collection name is not an import.\n *\n * So the plugin that keeps people registers ONE service here, and every rule\n * stays the owner's: how an address is keyed, what an alternate address a\n * merge folded in still answers to, which site may see which record, and what\n * a refund or a filing writes.\n *\n * ## What a record is\n *\n * A {@link PluginPersonRecord} is a kind and an id in the owner's own words —\n * the words `plugin-record-routes` addresses the record by — the person's\n * primary address, and the record as the owner stores it. The fields the\n * PLATFORM defines on a person record (the consent basis\n * `marketing-consent.ts` reads, the `emailState` verdict, the `visibleTo`\n * scope) are read off it with the platform's own readers; anything else is\n * the owner's and is documented with its registration.\n *\n * ## Not registered is an answer\n *\n * Every reader answers `null` when no plugin keeps people in this process,\n * which is a workspace with no record system and is not \"nobody found\". A\n * caller treats the two differently: a send with no record system has no\n * basis to read, which is not the same as a person who declined.\n *\n * A single-implementation contract: a workspace keeps one set of people, so\n * a second plugin's service is refused naming both and the incumbent keeps\n * serving. Registered from the owner's server declarations, so it is in place\n * in a process that never loaded the owner's API surface.\n *\n * ## The caller proves who is asking\n *\n * Like the capture and timeline seams, the registry authenticates nobody. A\n * caller decides in its own terms, before it asks, that the read or the write\n * is the workspace's to make.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\n/** A person record, by the owner's word for its kind and its id. */\nexport interface PluginPersonRecordRef {\n  /** The owner's word for the record — the kind `plugin-record-routes` addresses it by. */\n  kind: string\n  id: string\n}\n\n/** One person record, as the plugin that keeps people shares it. */\nexport interface PluginPersonRecord extends PluginPersonRecordRef {\n  /** The record's primary address, normalized, or `null` when it holds none. */\n  email: string | null\n  /**\n   * The record as the owner stores it. The platform's own fields on it are\n   * read with the platform's readers; the rest is the owner's, documented\n   * with its registration.\n   */\n  data: Readonly<Record<string, unknown>>\n}\n\n/** Who to find by address, and where. */\nexport interface PluginPersonFindRequest {\n  /**\n   * The organization whose people are searched. A caller that knows only the\n   * site names `hostId` instead, and the owner reads the organization off it.\n   */\n  orgId?: string | null\n  /** The site asking. Required with {@link onlyVisibleToSite}. */\n  hostId?: string | null\n  /** Raw: the owner normalizes it, alternate addresses included. */\n  email: unknown\n  /**\n   * Answer only a record `hostId` may see. A record the address names but the\n   * site cannot see is `null`, never a reason to look further — one address\n   * names one person.\n   */\n  onlyVisibleToSite?: boolean\n  /**\n   * Look at every kind of record the owner keeps a person as, in the owner's\n   * order, instead of only the one a known person is held as. A send deciding\n   * whether it may mail somebody asks for this: a person not yet qualified is\n   * still a person whose answer counts.\n   */\n  anyKind?: boolean\n}\n\n/** Records to read, by the refs the owner handed out. */\nexport interface PluginPersonReadRequest {\n  orgId: string\n  records: readonly PluginPersonRecordRef[]\n}\n\n/**\n * File a person under containers (`plugin-containers.ts`) — the merchant's\n * own act, through an automation step or an enrollment. Filing is not\n * consent.\n */\nexport interface PluginPersonFileRequest {\n  /** The site filing them: the person is filed under the containers as this site holds them. */\n  hostId: string\n  orgId?: string | null\n  record: PluginPersonRecordRef\n  /** The container kind, as `plugin-containers.ts` declares it. */\n  containerKind: string\n  ids: readonly string[]\n}\n\n/**\n * Money handed back to a person a silo took it from: a refund, or a dispute\n * lost. The owner records it beside what the person is worth; it never\n * creates a person to hold it.\n */\nexport interface PluginPersonRefundRequest {\n  /** The site the money was taken on. */\n  hostId: string\n  /** The buyer's address as the sale recorded it. Raw: the owner normalizes it. */\n  email: unknown\n  /** Cents reversed by THIS refund, never the sale's total. */\n  amountCents: number\n  /** The silo's own document the money went back on — what a timeline entry points at. */\n  refId: string\n  /** True only for the refund that moved the sale into fully refunded. */\n  closedTheSale: boolean\n  /** `chargeback` for a dispute lost; a refund otherwise. */\n  reason?: 'refund' | 'chargeback'\n}\n\n/**\n * What became of a refund. `recorded`; `no-email` for a sale that never\n * named its buyer; `no-person` for an address the workspace holds nobody at;\n * `gone` for a person removed between the sale and the refund.\n */\nexport type PluginPersonRefundOutcome = 'recorded' | 'no-email' | 'no-person' | 'gone'\n\n/**\n * The people a saved selection the owner keeps names — a saved view of one of\n * its lists — taken for one site, as the people a sequence or a send works\n * through.\n */\nexport interface PluginPersonViewRequest {\n  orgId: string\n  /** The site the people are taken for: only records it holds are answered. */\n  hostId: string\n  /** The view, by the id the owner's record list handed out (`plugin-record-lists`). */\n  viewId: string\n  /** The member asking: a view they may not list does not exist for them. */\n  viewerUid: string\n  /** The most people answered. */\n  limit: number\n}\n\nexport type PluginPersonViewPeople =\n  | {\n      ok: true\n      people: PluginPersonRecordRef[]\n      /** How many the view selects, as far as the owner read it. */\n      total: number\n      /** The view selects more than `limit`, or more than the owner read. */\n      truncated: boolean\n    }\n  | {\n      ok: false\n      /**\n       * `not-found`: no such view, or not this member's to list.\n       * `not-people`: a view of something that is not people.\n       * `unsupported`: the view narrows by something the owner cannot apply\n       * outside its own list, so taking it would select more people than the\n       * view shows; `unsupported` names what, in the owner's words.\n       */\n      reason: 'not-found' | 'not-people' | 'unsupported'\n      unsupported?: string[]\n    }\n\n/** Records to ask about, by the refs the owner handed out. */\nexport interface PluginPersonWroteInRequest {\n  orgId: string\n  records: readonly PluginPersonRecordRef[]\n}\n\nexport interface PluginPersonRecords {\n  /** The person an address belongs to, or `null`. A read; may throw, and the caller decides which way a failure falls. */\n  find(request: PluginPersonFindRequest): Promise<PluginPersonRecord | null>\n  /** The records named, in the order asked; `null` for one that is gone. */\n  read(request: PluginPersonReadRequest): Promise<Array<PluginPersonRecord | null>>\n  /**\n   * Files the person under the containers. Optional: an owner that keeps no\n   * containers answers nothing. `filed: false` is a record the owner could\n   * not find for the site.\n   */\n  fileUnder?(request: PluginPersonFileRequest): Promise<{ filed: boolean }>\n  /** Records money handed back. Optional. Never throws: the money has already moved. */\n  recordRefund?(request: PluginPersonRefundRequest): Promise<PluginPersonRefundOutcome>\n  /** The people a saved view selects for a site. Optional: an owner that keeps no views answers nothing. */\n  peopleInView?(request: PluginPersonViewRequest): Promise<PluginPersonViewPeople>\n  /**\n   * Whether each person has ever written to the workspace — an email they\n   * sent, on their record — in the order asked; `null` for one the owner\n   * could not answer. Optional.\n   */\n  wroteIn?(request: PluginPersonWroteInRequest): Promise<Array<boolean | null>>\n}\n\nexport const PLUGIN_PERSON_RECORDS = definePluginServiceContract<PluginPersonRecords>(\n  'core.person-records',\n  { multiple: false },\n)\n\n/**\n * Registers the plugin that keeps people. The owner is the loader's marker\n * when a register fn is running, else `options.pluginId`; with neither the\n * registration throws, and a second plugin's service is refused naming both —\n * the incumbent keeps serving.\n */\nexport function registerPluginPersonRecords(\n  records: PluginPersonRecords,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PERSON_RECORDS, records, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginPersonRecords {\n  /** The plugin that keeps people. */\n  pluginId: string\n  records: PluginPersonRecords\n}\n\n/** The service with its owner, or `null` when no plugin keeps people here. */\nexport function pluginPersonRecords(): ResolvedPluginPersonRecords | null {\n  const entry = resolvePluginServices(PLUGIN_PERSON_RECORDS)[0]\n  return entry ? { pluginId: entry.pluginId, records: entry.impl } : null\n}\n\n/**\n * The person an address belongs to, or `null` — for nobody found, and for a\n * workspace no plugin keeps people for. A failed read is the owner's to\n * throw and the caller's to decide which way it falls.\n */\nexport async function findPluginPerson(\n  request: PluginPersonFindRequest,\n): Promise<PluginPersonRecord | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved) return null\n  return await resolved.records.find(request)\n}\n\n/**\n * The records named, in the order asked, `null` for each that is gone — or\n * `null` whole when no plugin keeps people here, which is not \"all gone\".\n */\nexport async function readPluginPeople(\n  request: PluginPersonReadRequest,\n): Promise<Array<PluginPersonRecord | null> | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved) return null\n  if (!request.records.length) return []\n  return await resolved.records.read(request)\n}\n\n/**\n * Files the person under the containers through whichever plugin keeps\n * people, or answers `null` when none does or the one that does keeps no\n * containers. A failed write throws, as the caller's own write would have.\n */\nexport async function filePluginPersonUnder(\n  request: PluginPersonFileRequest,\n): Promise<{ filed: boolean } | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.fileUnder) return null\n  if (!request.ids.length) return { filed: false }\n  return await resolved.records.fileUnder(request)\n}\n\n/**\n * Hands a refund to whichever plugin keeps people, or answers `null` when\n * none does. Never throws: every caller has already moved the money and\n * recorded it on its own document, and a person's figure is derived from it.\n */\nexport async function recordPluginPersonRefund(\n  request: PluginPersonRefundRequest,\n): Promise<PluginPersonRefundOutcome | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.recordRefund) return null\n  try {\n    return await resolved.records.recordRefund(request)\n  } catch (error) {\n    console.error('[person-records] the record system could not record a refund', error)\n    return null\n  }\n}\n\n/**\n * The people a saved view selects for a site, or `null` when no plugin keeps\n * people here or the one that does keeps no views. A failed read throws.\n */\nexport async function pluginPeopleInView(\n  request: PluginPersonViewRequest,\n): Promise<PluginPersonViewPeople | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.peopleInView) return null\n  return await resolved.records.peopleInView(request)\n}\n\n/**\n * Whether each person has ever written to the workspace, in the order asked\n * — `null` for each the owner could not answer, and `null` whole when no\n * plugin keeps people here or the one that does cannot say. Never throws: a\n * caller reads an unknown as unknown.\n */\nexport async function pluginPeopleWroteIn(\n  request: PluginPersonWroteInRequest,\n): Promise<Array<boolean | null> | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.wroteIn) return null\n  if (!request.records.length) return []\n  try {\n    return await resolved.records.wroteIn(request)\n  } catch (error) {\n    console.error('[person-records] the record system could not say who wrote in', error)\n    return null\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PERSON_RECORDS","multiple","registerPluginPersonRecords","records","options","pluginId","pluginPersonRecords","entry","impl","findPluginPerson","request","resolved","find","readPluginPeople","length","read","filePluginPersonUnder","fileUnder","ids","filed","recordPluginPersonRefund","recordRefund","error","console","pluginPeopleInView","peopleInView","pluginPeopleWroteIn","wroteIn"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2N1B,OAAO,MAAMC,wBAAwBH,4BACnC,uBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,4BACdC,OAA4B,EAC5BC,OAA+B;IAE/BN,sBAAsBE,uBAAuBG,SAAS,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,4EAA4E,GAC5E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,sBAAsB,CAAC,EAAE;IAC7D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,SAASI,MAAMC,IAAI;IAAC,IAAI;AACrE;AAEA;;;;CAIC,GACD,OAAO,eAAeC,iBACpBC,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,OAAO,MAAMA,SAASR,OAAO,CAACS,IAAI,CAACF;AACrC;AAEA;;;CAGC,GACD,OAAO,eAAeG,iBACpBH,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,IAAI,CAACD,QAAQP,OAAO,CAACW,MAAM,EAAE,OAAO,EAAE;IACtC,OAAO,MAAMH,SAASR,OAAO,CAACY,IAAI,CAACL;AACrC;AAEA;;;;CAIC,GACD,OAAO,eAAeM,sBACpBN,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACc,SAAS,GAAE,OAAO;IACzC,IAAI,CAACP,QAAQQ,GAAG,CAACJ,MAAM,EAAE,OAAO;QAAEK,OAAO;IAAM;IAC/C,OAAO,MAAMR,SAASR,OAAO,CAACc,SAAS,CAACP;AAC1C;AAEA;;;;CAIC,GACD,OAAO,eAAeU,yBACpBV,OAAkC;IAElC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACkB,YAAY,GAAE,OAAO;IAC5C,IAAI;QACF,OAAO,MAAMV,SAASR,OAAO,CAACkB,YAAY,CAACX;IAC7C,EAAE,OAAOY,OAAO;QACdC,QAAQD,KAAK,CAAC,gEAAgEA;QAC9E,OAAO;IACT;AACF;AAEA;;;CAGC,GACD,OAAO,eAAeE,mBACpBd,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACsB,YAAY,GAAE,OAAO;IAC5C,OAAO,MAAMd,SAASR,OAAO,CAACsB,YAAY,CAACf;AAC7C;AAEA;;;;;CAKC,GACD,OAAO,eAAegB,oBACpBhB,OAAmC;IAEnC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACwB,OAAO,GAAE,OAAO;IACvC,IAAI,CAACjB,QAAQP,OAAO,CAACW,MAAM,EAAE,OAAO,EAAE;IACtC,IAAI;QACF,OAAO,MAAMH,SAASR,OAAO,CAACwB,OAAO,CAACjB;IACxC,EAAE,OAAOY,OAAO;QACdC,QAAQD,KAAK,CAAC,iEAAiEA;QAC/E,OAAO;IACT;AACF"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-person-records.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  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * THE PEOPLE A WORKSPACE KEEPS, asked for by the plugins that do not keep\n * them (AGL-3080).\n *\n * `plugin-contact-capture` is how a silo hands somebody it MET to the plugin\n * that keeps people. This is the other half: a plugin that has an address, or\n * a record the owner handed it, and needs the person behind it.\n *\n *  - a flow email asking whether the person agreed to marketing mail;\n *  - a campaign filling in the name a merge tag reads;\n *  - a refund taking money back off what a customer is worth;\n *  - an automation filing somebody under a campaign;\n *  - a sales sequence reading the people a rep enrolls.\n *\n * Each of those used to open the owner's collection itself — its path, its\n * address index, which site may see which document — and broke the day the\n * owner changed one. None of it is visible to `check:lib-boundaries`, because\n * a collection name is not an import.\n *\n * So the plugin that keeps people registers ONE service here, and every rule\n * stays the owner's: how an address is keyed, what an alternate address a\n * merge folded in still answers to, which site may see which record, and what\n * a refund or a filing writes.\n *\n * ## What a record is\n *\n * A {@link PluginPersonRecord} is a kind and an id in the owner's own words —\n * the words `plugin-record-routes` addresses the record by — the person's\n * primary address, and the record as the owner stores it. The fields the\n * PLATFORM defines on a person record (the consent basis\n * `marketing-consent.ts` reads, the `emailState` verdict, the `visibleTo`\n * scope) are read off it with the platform's own readers; anything else is\n * the owner's and is documented with its registration.\n *\n * ## Not registered is an answer\n *\n * Every reader answers `null` when no plugin keeps people in this process,\n * which is a workspace with no record system and is not \"nobody found\". A\n * caller treats the two differently: a send with no record system has no\n * basis to read, which is not the same as a person who declined.\n *\n * A single-implementation contract: a workspace keeps one set of people, so\n * a second plugin's service is refused naming both and the incumbent keeps\n * serving. Registered from the owner's server declarations, so it is in place\n * in a process that never loaded the owner's API surface.\n *\n * ## The caller proves who is asking\n *\n * Like the capture and timeline seams, the registry authenticates nobody. A\n * caller decides in its own terms, before it asks, that the read or the write\n * is the workspace's to make.\n *\n * Server-side: reached by its own subpath, never through\n * `plugin-manager/index.ts`.\n */\n\n/** A person record, by the owner's word for its kind and its id. */\nexport interface PluginPersonRecordRef {\n  /** The owner's word for the record — the kind `plugin-record-routes` addresses it by. */\n  kind: string\n  id: string\n}\n\n/** One person record, as the plugin that keeps people shares it. */\nexport interface PluginPersonRecord extends PluginPersonRecordRef {\n  /** The record's primary address, normalized, or `null` when it holds none. */\n  email: string | null\n  /**\n   * The record as the owner stores it. The platform's own fields on it are\n   * read with the platform's readers; the rest is the owner's, documented\n   * with its registration.\n   */\n  data: Readonly<Record<string, unknown>>\n}\n\n/** Who to find by address, and where. */\nexport interface PluginPersonFindRequest {\n  /**\n   * The organization whose people are searched. A caller that knows only the\n   * site names `hostId` instead, and the owner reads the organization off it.\n   */\n  orgId?: string | null\n  /** The site asking. Required with {@link onlyVisibleToSite}. */\n  hostId?: string | null\n  /** Raw: the owner normalizes it, alternate addresses included. */\n  email: unknown\n  /**\n   * Answer only a record `hostId` may see. A record the address names but the\n   * site cannot see is `null`, never a reason to look further — one address\n   * names one person.\n   */\n  onlyVisibleToSite?: boolean\n  /**\n   * Look at every kind of record the owner keeps a person as, in the owner's\n   * order, instead of only the one a known person is held as. A send deciding\n   * whether it may mail somebody asks for this: a person not yet qualified is\n   * still a person whose answer counts.\n   */\n  anyKind?: boolean\n}\n\n/** Records to read, by the refs the owner handed out. */\nexport interface PluginPersonReadRequest {\n  orgId: string\n  records: readonly PluginPersonRecordRef[]\n}\n\n/**\n * File a person under containers (`plugin-containers.ts`) — the merchant's\n * own act, through an automation step or an enrollment. Filing is not\n * consent.\n */\nexport interface PluginPersonFileRequest {\n  /** The site filing them: the person is filed under the containers as this site holds them. */\n  hostId: string\n  orgId?: string | null\n  record: PluginPersonRecordRef\n  /** The container kind, as `plugin-containers.ts` declares it. */\n  containerKind: string\n  ids: readonly string[]\n}\n\n/**\n * Money handed back to a person a silo took it from: a refund, or a dispute\n * lost. The owner records it beside what the person is worth; it never\n * creates a person to hold it.\n */\nexport interface PluginPersonRefundRequest {\n  /** The site the money was taken on. */\n  hostId: string\n  /** The buyer's address as the sale recorded it. Raw: the owner normalizes it. */\n  email: unknown\n  /** Cents reversed by THIS refund, never the sale's total. */\n  amountCents: number\n  /** The silo's own document the money went back on — what a timeline entry points at. */\n  refId: string\n  /** True only for the refund that moved the sale into fully refunded. */\n  closedTheSale: boolean\n  /** `chargeback` for a dispute lost; a refund otherwise. */\n  reason?: 'refund' | 'chargeback'\n}\n\n/**\n * What became of a refund. `recorded`; `no-email` for a sale that never\n * named its buyer; `no-person` for an address the workspace holds nobody at;\n * `gone` for a person removed between the sale and the refund.\n */\nexport type PluginPersonRefundOutcome = 'recorded' | 'no-email' | 'no-person' | 'gone'\n\n/**\n * The people a saved selection the owner keeps names — a saved view of one of\n * its lists — taken for one site, as the people a sequence or a send works\n * through.\n */\nexport interface PluginPersonViewRequest {\n  orgId: string\n  /** The site the people are taken for: only records it holds are answered. */\n  hostId: string\n  /** The view, by the id the owner's record list handed out (`plugin-record-lists`). */\n  viewId: string\n  /** The member asking: a view they may not list does not exist for them. */\n  viewerUid: string\n  /** The most people answered. */\n  limit: number\n}\n\nexport type PluginPersonViewPeople =\n  | {\n      ok: true\n      people: PluginPersonRecordRef[]\n      /** How many the view selects, as far as the owner read it. */\n      total: number\n      /** The view selects more than `limit`, or more than the owner read. */\n      truncated: boolean\n    }\n  | {\n      ok: false\n      /**\n       * `not-found`: no such view, or not this member's to list.\n       * `not-people`: a view of something that is not people.\n       * `unsupported`: the view narrows by something the owner cannot apply\n       * outside its own list, so taking it would select more people than the\n       * view shows; `unsupported` names what, in the owner's words.\n       */\n      reason: 'not-found' | 'not-people' | 'unsupported'\n      unsupported?: string[]\n    }\n\n/**\n * People a site may see whose name, address or phone starts with what was\n * typed (AGL-3609) — a cashier looking a customer up at the register, a\n * picker anywhere a person is chosen by hand. One word: the owner answers it\n * from its own search index and never by scanning its records.\n */\nexport interface PluginPersonSearchRequest {\n  /** The site searching: only records it may see are answered. */\n  hostId: string\n  /** The organization, when the caller knows it; the owner reads it off `hostId` otherwise. */\n  orgId?: string | null\n  /** What was typed. Raw: the owner normalizes it, and reads a run of digits as a phone. */\n  text: string\n  /** The most people answered. The owner may answer fewer. */\n  limit: number\n}\n\n/** Records to ask about, by the refs the owner handed out. */\nexport interface PluginPersonWroteInRequest {\n  orgId: string\n  records: readonly PluginPersonRecordRef[]\n}\n\n/**\n * The people one site holds, oldest change first, after a cursor (AGL-3639)\n * — what a connector that mirrors a workspace's people into another system\n * walks, once from the start as a backfill and then from where it stopped.\n */\nexport interface PluginPersonChangesRequest {\n  /** The site the people are taken for: only records it may see are answered. */\n  hostId: string\n  orgId?: string | null\n  /**\n   * Where the last page stopped, exactly as the owner handed it out, or\n   * `null` to start from the earliest change. Opaque: only the owner reads\n   * it, so it can hold a change time finer than a millisecond and the id\n   * that breaks a tie, and a walk neither skips a person nor repeats one.\n   */\n  after: string | null\n  /** The most people answered; the owner may answer fewer. */\n  limit: number\n}\n\n/**\n * A person as a connector copies them out: the platform's own fields on the\n * record (`data`, read with the platform's readers — the consent basis\n * above all), and the owner's profile of them as this site holds it, in the\n * platform's words rather than the owner's storage.\n */\nexport interface PluginPersonChange extends PluginPersonRecord {\n  /** When the record last changed, epoch ms. */\n  changedAtMs: number\n  profile: {\n    name: string | null\n    phone: string | null\n    tags: string[]\n    /** What the person has spent at this site, integer cents, when the owner keeps it. */\n    lifetimeValueCents: number | null\n    ordersCount: number | null\n  }\n}\n\nexport interface PluginPersonChangesPage {\n  people: PluginPersonChange[]\n  /**\n   * Where the next page starts — the cursor to store. It moves past every\n   * record the owner READ, including one it left out for the site, so a page\n   * can be empty and still move on. `null` when nothing changed after the\n   * cursor: the walk has reached the latest change, and the caller keeps the\n   * cursor it asked with.\n   */\n  next: string | null\n}\n\nexport interface PluginPersonRecords {\n  /** The person an address belongs to, or `null`. A read; may throw, and the caller decides which way a failure falls. */\n  find(request: PluginPersonFindRequest): Promise<PluginPersonRecord | null>\n  /** The records named, in the order asked; `null` for one that is gone. */\n  read(request: PluginPersonReadRequest): Promise<Array<PluginPersonRecord | null>>\n  /**\n   * Files the person under the containers. Optional: an owner that keeps no\n   * containers answers nothing. `filed: false` is a record the owner could\n   * not find for the site.\n   */\n  fileUnder?(request: PluginPersonFileRequest): Promise<{ filed: boolean }>\n  /** Records money handed back. Optional. Never throws: the money has already moved. */\n  recordRefund?(request: PluginPersonRefundRequest): Promise<PluginPersonRefundOutcome>\n  /** The people a saved view selects for a site. Optional: an owner that keeps no views answers nothing. */\n  peopleInView?(request: PluginPersonViewRequest): Promise<PluginPersonViewPeople>\n  /**\n   * Whether each person has ever written to the workspace — an email they\n   * sent, on their record — in the order asked; `null` for one the owner\n   * could not answer. Optional.\n   */\n  wroteIn?(request: PluginPersonWroteInRequest): Promise<Array<boolean | null>>\n  /**\n   * People a site may see that match one typed word, best first. Optional:\n   * an owner that keeps no search index answers nothing. A read; may throw.\n   */\n  search?(request: PluginPersonSearchRequest): Promise<PluginPersonRecord[]>\n  /**\n   * The people a site holds that changed after a cursor, oldest first.\n   * Optional: an owner that cannot walk its records by change answers\n   * nothing. A failed read throws.\n   */\n  changedSince?(request: PluginPersonChangesRequest): Promise<PluginPersonChangesPage>\n}\n\nexport const PLUGIN_PERSON_RECORDS = definePluginServiceContract<PluginPersonRecords>(\n  'core.person-records',\n  { multiple: false },\n)\n\n/**\n * Registers the plugin that keeps people. The owner is the loader's marker\n * when a register fn is running, else `options.pluginId`; with neither the\n * registration throws, and a second plugin's service is refused naming both —\n * the incumbent keeps serving.\n */\nexport function registerPluginPersonRecords(\n  records: PluginPersonRecords,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PERSON_RECORDS, records, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\nexport interface ResolvedPluginPersonRecords {\n  /** The plugin that keeps people. */\n  pluginId: string\n  records: PluginPersonRecords\n}\n\n/** The service with its owner, or `null` when no plugin keeps people here. */\nexport function pluginPersonRecords(): ResolvedPluginPersonRecords | null {\n  const entry = resolvePluginServices(PLUGIN_PERSON_RECORDS)[0]\n  return entry ? { pluginId: entry.pluginId, records: entry.impl } : null\n}\n\n/**\n * The person an address belongs to, or `null` — for nobody found, and for a\n * workspace no plugin keeps people for. A failed read is the owner's to\n * throw and the caller's to decide which way it falls.\n */\nexport async function findPluginPerson(\n  request: PluginPersonFindRequest,\n): Promise<PluginPersonRecord | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved) return null\n  return await resolved.records.find(request)\n}\n\n/**\n * The records named, in the order asked, `null` for each that is gone — or\n * `null` whole when no plugin keeps people here, which is not \"all gone\".\n */\nexport async function readPluginPeople(\n  request: PluginPersonReadRequest,\n): Promise<Array<PluginPersonRecord | null> | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved) return null\n  if (!request.records.length) return []\n  return await resolved.records.read(request)\n}\n\n/**\n * Files the person under the containers through whichever plugin keeps\n * people, or answers `null` when none does or the one that does keeps no\n * containers. A failed write throws, as the caller's own write would have.\n */\nexport async function filePluginPersonUnder(\n  request: PluginPersonFileRequest,\n): Promise<{ filed: boolean } | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.fileUnder) return null\n  if (!request.ids.length) return { filed: false }\n  return await resolved.records.fileUnder(request)\n}\n\n/**\n * Hands a refund to whichever plugin keeps people, or answers `null` when\n * none does. Never throws: every caller has already moved the money and\n * recorded it on its own document, and a person's figure is derived from it.\n */\nexport async function recordPluginPersonRefund(\n  request: PluginPersonRefundRequest,\n): Promise<PluginPersonRefundOutcome | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.recordRefund) return null\n  try {\n    return await resolved.records.recordRefund(request)\n  } catch (error) {\n    console.error('[person-records] the record system could not record a refund', error)\n    return null\n  }\n}\n\n/**\n * The people a saved view selects for a site, or `null` when no plugin keeps\n * people here or the one that does keeps no views. A failed read throws.\n */\nexport async function pluginPeopleInView(\n  request: PluginPersonViewRequest,\n): Promise<PluginPersonViewPeople | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.peopleInView) return null\n  return await resolved.records.peopleInView(request)\n}\n\n/**\n * Whether each person has ever written to the workspace, in the order asked\n * — `null` for each the owner could not answer, and `null` whole when no\n * plugin keeps people here or the one that does cannot say. Never throws: a\n * caller reads an unknown as unknown.\n */\nexport async function pluginPeopleWroteIn(\n  request: PluginPersonWroteInRequest,\n): Promise<Array<boolean | null> | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.wroteIn) return null\n  if (!request.records.length) return []\n  try {\n    return await resolved.records.wroteIn(request)\n  } catch (error) {\n    console.error('[person-records] the record system could not say who wrote in', error)\n    return null\n  }\n}\n\n/**\n * People a site may see matching what was typed, or `null` when no plugin\n * keeps people here or the one that does keeps no search — which is not\n * \"nobody matched\". Blank text answers no one without asking. A failed read\n * throws, and the caller decides how to say so.\n */\nexport async function searchPluginPeople(\n  request: PluginPersonSearchRequest,\n): Promise<PluginPersonRecord[] | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.search) return null\n  if (!String(request.text ?? '').trim() || !(request.limit > 0)) return []\n  return await resolved.records.search(request)\n}\n\n/**\n * The people a site holds that changed after a cursor, oldest first, or\n * `null` when no plugin keeps people here or the one that does cannot walk\n * them by change. The limit is clamped to 1–500. A failed read throws: a\n * connector that skipped a page it could not read would advance past people\n * it never copied.\n */\nexport async function pluginPeopleChangedSince(\n  request: PluginPersonChangesRequest,\n): Promise<PluginPersonChangesPage | null> {\n  const resolved = pluginPersonRecords()\n  if (!resolved?.records.changedSince) return null\n  const limit = Math.min(500, Math.max(1, Math.floor(Number(request.limit) || 0)))\n  return await resolved.records.changedSince({ ...request, limit })\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PERSON_RECORDS","multiple","registerPluginPersonRecords","records","options","pluginId","pluginPersonRecords","entry","impl","findPluginPerson","request","resolved","find","readPluginPeople","length","read","filePluginPersonUnder","fileUnder","ids","filed","recordPluginPersonRefund","recordRefund","error","console","pluginPeopleInView","peopleInView","pluginPeopleWroteIn","wroteIn","searchPluginPeople","search","String","text","trim","limit","pluginPeopleChangedSince","changedSince","Math","min","max","floor","Number"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA0S1B,OAAO,MAAMC,wBAAwBH,4BACnC,uBACA;IAAEI,UAAU;AAAM,GACnB;AAED;;;;;CAKC,GACD,OAAO,SAASC,4BACdC,OAA4B,EAC5BC,OAA+B;IAE/BN,sBAAsBE,uBAAuBG,SAAS,aAChDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAQA,4EAA4E,GAC5E,OAAO,SAASC;IACd,MAAMC,QAAQR,sBAAsBC,sBAAsB,CAAC,EAAE;IAC7D,OAAOO,QAAQ;QAAEF,UAAUE,MAAMF,QAAQ;QAAEF,SAASI,MAAMC,IAAI;IAAC,IAAI;AACrE;AAEA;;;;CAIC,GACD,OAAO,eAAeC,iBACpBC,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,OAAO,MAAMA,SAASR,OAAO,CAACS,IAAI,CAACF;AACrC;AAEA;;;CAGC,GACD,OAAO,eAAeG,iBACpBH,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,CAACK,UAAU,OAAO;IACtB,IAAI,CAACD,QAAQP,OAAO,CAACW,MAAM,EAAE,OAAO,EAAE;IACtC,OAAO,MAAMH,SAASR,OAAO,CAACY,IAAI,CAACL;AACrC;AAEA;;;;CAIC,GACD,OAAO,eAAeM,sBACpBN,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACc,SAAS,GAAE,OAAO;IACzC,IAAI,CAACP,QAAQQ,GAAG,CAACJ,MAAM,EAAE,OAAO;QAAEK,OAAO;IAAM;IAC/C,OAAO,MAAMR,SAASR,OAAO,CAACc,SAAS,CAACP;AAC1C;AAEA;;;;CAIC,GACD,OAAO,eAAeU,yBACpBV,OAAkC;IAElC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACkB,YAAY,GAAE,OAAO;IAC5C,IAAI;QACF,OAAO,MAAMV,SAASR,OAAO,CAACkB,YAAY,CAACX;IAC7C,EAAE,OAAOY,OAAO;QACdC,QAAQD,KAAK,CAAC,gEAAgEA;QAC9E,OAAO;IACT;AACF;AAEA;;;CAGC,GACD,OAAO,eAAeE,mBACpBd,OAAgC;IAEhC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACsB,YAAY,GAAE,OAAO;IAC5C,OAAO,MAAMd,SAASR,OAAO,CAACsB,YAAY,CAACf;AAC7C;AAEA;;;;;CAKC,GACD,OAAO,eAAegB,oBACpBhB,OAAmC;IAEnC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACwB,OAAO,GAAE,OAAO;IACvC,IAAI,CAACjB,QAAQP,OAAO,CAACW,MAAM,EAAE,OAAO,EAAE;IACtC,IAAI;QACF,OAAO,MAAMH,SAASR,OAAO,CAACwB,OAAO,CAACjB;IACxC,EAAE,OAAOY,OAAO;QACdC,QAAQD,KAAK,CAAC,iEAAiEA;QAC/E,OAAO;IACT;AACF;AAEA;;;;;CAKC,GACD,OAAO,eAAeM,mBACpBlB,OAAkC;QAItBA;IAFZ,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAAC0B,MAAM,GAAE,OAAO;IACtC,IAAI,CAACC,QAAOpB,gBAAAA,QAAQqB,IAAI,YAAZrB,gBAAgB,IAAIsB,IAAI,MAAM,CAAEtB,CAAAA,QAAQuB,KAAK,GAAG,CAAA,GAAI,OAAO,EAAE;IACzE,OAAO,MAAMtB,SAASR,OAAO,CAAC0B,MAAM,CAACnB;AACvC;AAEA;;;;;;CAMC,GACD,OAAO,eAAewB,yBACpBxB,OAAmC;IAEnC,MAAMC,WAAWL;IACjB,IAAI,EAACK,4BAAAA,SAAUR,OAAO,CAACgC,YAAY,GAAE,OAAO;IAC5C,MAAMF,QAAQG,KAAKC,GAAG,CAAC,KAAKD,KAAKE,GAAG,CAAC,GAAGF,KAAKG,KAAK,CAACC,OAAO9B,QAAQuB,KAAK,KAAK;IAC5E,OAAO,MAAMtB,SAASR,OAAO,CAACgC,YAAY,CAAC,aAAKzB;QAASuB;;AAC3D"}

package/src/lib/plugin-manager/plugin-product-catalog.d.ts

@@ -0,0 +1,204 @@
+/**
+ * @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.
+ */
+/**
+ * A site's sellable catalog, read whole and in pages by a plugin that does
+ * not own it (AGL-3637).
+ *
+ * A product feed, a marketplace listing sync and an ad catalog all need the
+ * same thing: every offer a store sells, with the facts a shopping channel
+ * asks for — price in the store's currency, stock, photos, identifiers,
+ * shipping. The plugin that keeps the products answers it here, so a reader
+ * never learns where products are stored, how variants are modeled or what a
+ * deleted product looks like.
+ *
+ * ## One OFFER per sellable configuration
+ *
+ * A product with one configuration is one offer whose `id` is the product's
+ * own id. A product with several (sizes, colors) is one offer per
+ * configuration, each with its own `id` and the product's id as `groupId`,
+ * which is what every shopping channel calls the variant group.
+ *
+ * ## Money is integer minor units in the store's currency
+ *
+ * `priceMinor` and every other amount are integers (cents for USD) in
+ * {@link CatalogStore.currency}. A reader formats them; it never assumes a
+ * currency.
+ *
+ * ## Pages, not a list
+ *
+ * A store may hold far more products than one read should load, so the
+ * catalog is walked in pages: `page()` answers up to about `limit` offers and
+ * a `nextCursor` to continue from, `null` on the last page. A cursor is the
+ * owner's own opaque string; a reader passes it back untouched.
+ *
+ * ## One owner
+ *
+ * A slot, like the tax profile: a site has one catalog, so a second plugin's
+ * registration is refused and the incumbent keeps serving. No owner
+ * registered is an ordinary answer — {@link pluginProductCatalog} returns
+ * `undefined` and a reader serves nothing.
+ */
+/** The store an offer belongs to, as a channel needs it. */
+export interface CatalogStore {
+    hostId: string;
+    /** The store's name, as its site calls itself. */
+    name: string;
+    /**
+     * The origin the store's pages are served on (`https://shop.example.com`),
+     * or `null` when the site has no address yet.
+     */
+    origin: string | null;
+    /** ISO 4217, upper case. Every amount in the catalog is in it. */
+    currency: string;
+    /**
+     * Whether `/products/{slug}` pages are served. When `false`, every offer's
+     * `path` answers 404, and a channel will refuse the offers.
+     */
+    productPagesServed: boolean;
+    /**
+     * Countries the store's checkout prices shipping to by a live carrier
+     * quote rather than its own table (ISO 3166-1 alpha-2, upper case). An
+     * offer carries no {@link CatalogShippingPrice} for them, because the price
+     * depends on the address; a channel that calculates carrier rates itself
+     * prices them from the offer's weight and dimensions.
+     */
+    carrierPricedCountries: string[];
+}
+export type CatalogAvailability = 'in_stock' | 'out_of_stock' | 'backorder';
+export type CatalogCondition = 'new' | 'refurbished' | 'used';
+export type CatalogProductKind = 'physical' | 'digital' | 'service';
+/** What one offer costs to ship to one country, cheapest rate first chosen. */
+export interface CatalogShippingPrice {
+    /** ISO 3166-1 alpha-2, upper case. */
+    country: string;
+    /** The rate's name as the shopper sees it at checkout. */
+    service: string;
+    priceMinor: number;
+}
+/** One sellable configuration of a product. */
+export interface CatalogOffer {
+    /** Stable, unique within the store: the product id, or product and variant. */
+    id: string;
+    /** The product's id: the variant group every configuration shares. */
+    groupId: string;
+    /** Whether the product has more than one configuration. */
+    hasVariants: boolean;
+    productId: string;
+    variantId: string;
+    /** The product's name. */
+    productName: string;
+    /** The product's name with this configuration's choices, e.g. `Tee — Red / M`. */
+    title: string;
+    /** Plain text: no markup. May be empty. */
+    description: string;
+    /** Site-relative path of the product page, e.g. `/products/tee`. */
+    path: string;
+    /** Absolute URL of the photo shown for this configuration. */
+    imageUrl?: string;
+    /** Absolute URLs of the product's other photos, in order. */
+    additionalImageUrls: string[];
+    /** What the shopper pays, before any sale: the regular price. */
+    priceMinor: number;
+    /** A lower price the offer is on sale for now; absent when not on sale. */
+    salePriceMinor?: number;
+    availability: CatalogAvailability;
+    /** Units in stock, or `null` when stock is not tracked. */
+    quantity: number | null;
+    kind: CatalogProductKind;
+    /** Whether the product is sold only as a recurring subscription. */
+    subscriptionOnly: boolean;
+    /** What the merchant entered for shopping channels; absent when they did not. */
+    condition?: CatalogCondition;
+    brand?: string;
+    /** GTIN (UPC, EAN, ISBN, JAN, ITF-14) as entered, digits only. */
+    gtin?: string;
+    mpn?: string;
+    /** A Google product taxonomy id or full path, as entered. */
+    googleProductCategory?: string;
+    /** The store's own category path, e.g. `Apparel > Shirts`. */
+    productType?: string;
+    /** The configuration's choices, by option name. */
+    options: Readonly<Record<string, string>>;
+    /** The choice of an option named like a color, when there is one. */
+    color?: string;
+    /** The choice of an option named like a size, when there is one. */
+    size?: string;
+    weightGrams?: number;
+    /** One unit's packed size, in centimeters, when the merchant entered it. */
+    dimensionsCm?: {
+        length: number;
+        width: number;
+        height: number;
+    };
+    /** What it costs to ship one unit, per country the store ships to. */
+    shipping: CatalogShippingPrice[];
+    /** When the product last changed, epoch ms; absent when unknown. */
+    updatedAtMs?: number;
+}
+export interface CatalogPage {
+    offers: CatalogOffer[];
+    /** Where the next page starts, or `null` when this is the last one. */
+    nextCursor: string | null;
+}
+export interface PluginProductCatalog {
+    /** The store, or `null` for a site that does not sell. */
+    store(hostId: string): Promise<CatalogStore | null>;
+    /**
+     * One page of the store's live, listed offers: never a draft, archived or
+     * deleted product. About `limit` offers — a product's configurations are
+     * never split across pages, so a page may run over by one product's worth.
+     */
+    page(request: {
+        hostId: string;
+        cursor?: string | null;
+        limit: number;
+    }): Promise<CatalogPage>;
+}
+export declare const PLUGIN_PRODUCT_CATALOG: import("./plugin-services").PluginServiceContract<PluginProductCatalog>;
+/** Registers the store catalog. A second plugin's is refused, naming both. */
+export declare function registerPluginProductCatalog(catalog: PluginProductCatalog, options?: {
+    pluginId?: string;
+}): void;
+/** The registered catalog, or `undefined` when no plugin sells. */
+export declare function pluginProductCatalog(): PluginProductCatalog | undefined;
+/**
+ * The plugin that publishes the catalog to shopping channels, as the
+ * catalog's owner hands it an address of its own (AGL-3637).
+ *
+ * Before any plugin published feeds, the plugin that keeps the products
+ * served one feed itself, and merchants pasted that address into their
+ * channel. The address stays the owner's — a request for it reaches the
+ * owner's routes — but the feed is written by whoever publishes the catalog
+ * now, so the owner answers it from here. Nobody registered is an ordinary
+ * answer: {@link pluginCatalogFeed} returns `undefined` and the owner
+ * answers 404.
+ */
+export interface PluginCatalogFeed {
+    /**
+     * Answers a request for the owner's pre-existing feed address for the site
+     * `hostId`: the feed, a 404 when the site's publisher has retired the
+     * address or does not publish, or a 503 to try later.
+     */
+    serveLegacyFeed(request: Request, hostId: string): Promise<Response>;
+}
+export declare const PLUGIN_CATALOG_FEED: import("./plugin-services").PluginServiceContract<PluginCatalogFeed>;
+/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */
+export declare function registerPluginCatalogFeed(feed: PluginCatalogFeed, options?: {
+    pluginId?: string;
+}): void;
+/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */
+export declare function pluginCatalogFeed(): PluginCatalogFeed | undefined;

package/src/lib/plugin-manager/plugin-product-catalog.js

@@ -0,0 +1,43 @@
+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 { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_PRODUCT_CATALOG = definePluginServiceContract('core.product-catalog', {
+    multiple: false
+});
+/** Registers the store catalog. A second plugin's is refused, naming both. */ export function registerPluginProductCatalog(catalog, options) {
+    registerPluginService(PLUGIN_PRODUCT_CATALOG, catalog, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered catalog, or `undefined` when no plugin sells. */ export function pluginProductCatalog() {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(PLUGIN_PRODUCT_CATALOG)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+export const PLUGIN_CATALOG_FEED = definePluginServiceContract('core.catalog-feed', {
+    multiple: false
+});
+/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */ export function registerPluginCatalogFeed(feed, options) {
+    registerPluginService(PLUGIN_CATALOG_FEED, feed, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */ export function pluginCatalogFeed() {
+    var _resolvePluginServices_;
+    return (_resolvePluginServices_ = resolvePluginServices(PLUGIN_CATALOG_FEED)[0]) == null ? void 0 : _resolvePluginServices_.impl;
+}
+
+//# sourceMappingURL=plugin-product-catalog.js.map

package/src/lib/plugin-manager/plugin-product-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-product-catalog.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  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * A site's sellable catalog, read whole and in pages by a plugin that does\n * not own it (AGL-3637).\n *\n * A product feed, a marketplace listing sync and an ad catalog all need the\n * same thing: every offer a store sells, with the facts a shopping channel\n * asks for — price in the store's currency, stock, photos, identifiers,\n * shipping. The plugin that keeps the products answers it here, so a reader\n * never learns where products are stored, how variants are modeled or what a\n * deleted product looks like.\n *\n * ## One OFFER per sellable configuration\n *\n * A product with one configuration is one offer whose `id` is the product's\n * own id. A product with several (sizes, colors) is one offer per\n * configuration, each with its own `id` and the product's id as `groupId`,\n * which is what every shopping channel calls the variant group.\n *\n * ## Money is integer minor units in the store's currency\n *\n * `priceMinor` and every other amount are integers (cents for USD) in\n * {@link CatalogStore.currency}. A reader formats them; it never assumes a\n * currency.\n *\n * ## Pages, not a list\n *\n * A store may hold far more products than one read should load, so the\n * catalog is walked in pages: `page()` answers up to about `limit` offers and\n * a `nextCursor` to continue from, `null` on the last page. A cursor is the\n * owner's own opaque string; a reader passes it back untouched.\n *\n * ## One owner\n *\n * A slot, like the tax profile: a site has one catalog, so a second plugin's\n * registration is refused and the incumbent keeps serving. No owner\n * registered is an ordinary answer — {@link pluginProductCatalog} returns\n * `undefined` and a reader serves nothing.\n */\n\n/** The store an offer belongs to, as a channel needs it. */\nexport interface CatalogStore {\n  hostId: string\n  /** The store's name, as its site calls itself. */\n  name: string\n  /**\n   * The origin the store's pages are served on (`https://shop.example.com`),\n   * or `null` when the site has no address yet.\n   */\n  origin: string | null\n  /** ISO 4217, upper case. Every amount in the catalog is in it. */\n  currency: string\n  /**\n   * Whether `/products/{slug}` pages are served. When `false`, every offer's\n   * `path` answers 404, and a channel will refuse the offers.\n   */\n  productPagesServed: boolean\n  /**\n   * Countries the store's checkout prices shipping to by a live carrier\n   * quote rather than its own table (ISO 3166-1 alpha-2, upper case). An\n   * offer carries no {@link CatalogShippingPrice} for them, because the price\n   * depends on the address; a channel that calculates carrier rates itself\n   * prices them from the offer's weight and dimensions.\n   */\n  carrierPricedCountries: string[]\n}\n\nexport type CatalogAvailability = 'in_stock' | 'out_of_stock' | 'backorder'\nexport type CatalogCondition = 'new' | 'refurbished' | 'used'\nexport type CatalogProductKind = 'physical' | 'digital' | 'service'\n\n/** What one offer costs to ship to one country, cheapest rate first chosen. */\nexport interface CatalogShippingPrice {\n  /** ISO 3166-1 alpha-2, upper case. */\n  country: string\n  /** The rate's name as the shopper sees it at checkout. */\n  service: string\n  priceMinor: number\n}\n\n/** One sellable configuration of a product. */\nexport interface CatalogOffer {\n  /** Stable, unique within the store: the product id, or product and variant. */\n  id: string\n  /** The product's id: the variant group every configuration shares. */\n  groupId: string\n  /** Whether the product has more than one configuration. */\n  hasVariants: boolean\n  productId: string\n  variantId: string\n  /** The product's name. */\n  productName: string\n  /** The product's name with this configuration's choices, e.g. `Tee — Red / M`. */\n  title: string\n  /** Plain text: no markup. May be empty. */\n  description: string\n  /** Site-relative path of the product page, e.g. `/products/tee`. */\n  path: string\n  /** Absolute URL of the photo shown for this configuration. */\n  imageUrl?: string\n  /** Absolute URLs of the product's other photos, in order. */\n  additionalImageUrls: string[]\n  /** What the shopper pays, before any sale: the regular price. */\n  priceMinor: number\n  /** A lower price the offer is on sale for now; absent when not on sale. */\n  salePriceMinor?: number\n  availability: CatalogAvailability\n  /** Units in stock, or `null` when stock is not tracked. */\n  quantity: number | null\n  kind: CatalogProductKind\n  /** Whether the product is sold only as a recurring subscription. */\n  subscriptionOnly: boolean\n  /** What the merchant entered for shopping channels; absent when they did not. */\n  condition?: CatalogCondition\n  brand?: string\n  /** GTIN (UPC, EAN, ISBN, JAN, ITF-14) as entered, digits only. */\n  gtin?: string\n  mpn?: string\n  /** A Google product taxonomy id or full path, as entered. */\n  googleProductCategory?: string\n  /** The store's own category path, e.g. `Apparel > Shirts`. */\n  productType?: string\n  /** The configuration's choices, by option name. */\n  options: Readonly<Record<string, string>>\n  /** The choice of an option named like a color, when there is one. */\n  color?: string\n  /** The choice of an option named like a size, when there is one. */\n  size?: string\n  weightGrams?: number\n  /** One unit's packed size, in centimeters, when the merchant entered it. */\n  dimensionsCm?: { length: number; width: number; height: number }\n  /** What it costs to ship one unit, per country the store ships to. */\n  shipping: CatalogShippingPrice[]\n  /** When the product last changed, epoch ms; absent when unknown. */\n  updatedAtMs?: number\n}\n\nexport interface CatalogPage {\n  offers: CatalogOffer[]\n  /** Where the next page starts, or `null` when this is the last one. */\n  nextCursor: string | null\n}\n\nexport interface PluginProductCatalog {\n  /** The store, or `null` for a site that does not sell. */\n  store(hostId: string): Promise<CatalogStore | null>\n  /**\n   * One page of the store's live, listed offers: never a draft, archived or\n   * deleted product. About `limit` offers — a product's configurations are\n   * never split across pages, so a page may run over by one product's worth.\n   */\n  page(request: { hostId: string; cursor?: string | null; limit: number }): Promise<CatalogPage>\n}\n\nexport const PLUGIN_PRODUCT_CATALOG = definePluginServiceContract<PluginProductCatalog>(\n  'core.product-catalog',\n  { multiple: false },\n)\n\n/** Registers the store catalog. A second plugin's is refused, naming both. */\nexport function registerPluginProductCatalog(\n  catalog: PluginProductCatalog,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_PRODUCT_CATALOG, catalog, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered catalog, or `undefined` when no plugin sells. */\nexport function pluginProductCatalog(): PluginProductCatalog | undefined {\n  return resolvePluginServices(PLUGIN_PRODUCT_CATALOG)[0]?.impl\n}\n\n/**\n * The plugin that publishes the catalog to shopping channels, as the\n * catalog's owner hands it an address of its own (AGL-3637).\n *\n * Before any plugin published feeds, the plugin that keeps the products\n * served one feed itself, and merchants pasted that address into their\n * channel. The address stays the owner's — a request for it reaches the\n * owner's routes — but the feed is written by whoever publishes the catalog\n * now, so the owner answers it from here. Nobody registered is an ordinary\n * answer: {@link pluginCatalogFeed} returns `undefined` and the owner\n * answers 404.\n */\nexport interface PluginCatalogFeed {\n  /**\n   * Answers a request for the owner's pre-existing feed address for the site\n   * `hostId`: the feed, a 404 when the site's publisher has retired the\n   * address or does not publish, or a 503 to try later.\n   */\n  serveLegacyFeed(request: Request, hostId: string): Promise<Response>\n}\n\nexport const PLUGIN_CATALOG_FEED = definePluginServiceContract<PluginCatalogFeed>(\n  'core.catalog-feed',\n  { multiple: false },\n)\n\n/** Registers the catalog's feed publisher. A second plugin's is refused, naming both. */\nexport function registerPluginCatalogFeed(\n  feed: PluginCatalogFeed,\n  options?: { pluginId?: string },\n): void {\n  registerPluginService(PLUGIN_CATALOG_FEED, feed, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n  })\n}\n\n/** The registered feed publisher, or `undefined` when no plugin publishes feeds. */\nexport function pluginCatalogFeed(): PluginCatalogFeed | undefined {\n  return resolvePluginServices(PLUGIN_CATALOG_FEED)[0]?.impl\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_PRODUCT_CATALOG","multiple","registerPluginProductCatalog","catalog","options","pluginId","pluginProductCatalog","impl","PLUGIN_CATALOG_FEED","registerPluginCatalogFeed","feed","pluginCatalogFeed"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA2J1B,OAAO,MAAMC,yBAAyBH,4BACpC,wBACA;IAAEI,UAAU;AAAM,GACnB;AAED,4EAA4E,GAC5E,OAAO,SAASC,6BACdC,OAA6B,EAC7BC,OAA+B;IAE/BN,sBAAsBE,wBAAwBG,SAAS,aACjDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,iEAAiE,GACjE,OAAO,SAASC;QACPP;IAAP,QAAOA,0BAAAA,sBAAsBC,uBAAuB,CAAC,EAAE,qBAAhDD,wBAAkDQ,IAAI;AAC/D;AAuBA,OAAO,MAAMC,sBAAsBX,4BACjC,qBACA;IAAEI,UAAU;AAAM,GACnB;AAED,uFAAuF,GACvF,OAAO,SAASQ,0BACdC,IAAuB,EACvBN,OAA+B;IAE/BN,sBAAsBU,qBAAqBE,MAAM,aAC3CN,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC;AAE9D;AAEA,kFAAkF,GAClF,OAAO,SAASM;QACPZ;IAAP,QAAOA,0BAAAA,sBAAsBS,oBAAoB,CAAC,EAAE,qBAA7CT,wBAA+CQ,IAAI;AAC5D"}