@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/plugin-manager/plugin-record-index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 plugin's records, listed and read for ANOTHER plugin (AGL-3080).
+ *
+ * A plugin that works over records it does not own — an AI job enriching a
+ * site's products, a composer binding the products an email names — used to
+ * read the owner's Firestore collection itself: the path, the field names,
+ * what "deleted" looks like. That is a plugin's storage reached around the
+ * plugin, invisible to `check:lib-boundaries` because a collection name is
+ * not an import, and it breaks the day the owner changes a field.
+ *
+ * So the owner publishes an INDEX for each record kind it keeps: `list` names
+ * the live records of a scope, `get` reads one — each as an id, a name and the
+ * FACTS the owner chooses to share, in a shape its registration documents.
+ * The reader never learns where the records are stored or what a deleted one
+ * looks like; the owner answers only live records.
+ *
+ * Its siblings: `plugin-record-cards` (how one record LOOKS, for a campaign
+ * sender) and `plugin-record-facts` (what a record SAYS, for a summary);
+ * `plugin-resource-drafts` is the WRITE side. This is the side that finds and
+ * reads records to work on.
+ *
+ * ## Not registered is an answer
+ *
+ * No index for a kind means no plugin keeps it in this process — the owner is
+ * not installed, or not loaded. A reader treats that as "none here" and says
+ * so, rather than reaching for the collection itself. Registered from the
+ * owner's server declarations, so every server process that boots the
+ * declarations has it.
+ *
+ * ## One index per kind
+ *
+ * A second plugin registering an index for a kind another plugin already
+ * keeps is refused, naming both, and the incumbent keeps serving.
+ */
+/** One record, as its owner shares it. */
+export interface PluginIndexedRecord {
+    id: string;
+    /** What a person calls it. Never empty: the owner leaves an unnamed record out. */
+    name: string;
+    /** What else the owner shares, in the shape its registration documents. */
+    facts: Readonly<Record<string, unknown>>;
+}
+/** Which records a reader asks about. */
+export interface PluginRecordIndexScope {
+    /** The organization the records belong to, where the kind is org-scoped. */
+    orgId?: string | null;
+    /** The site the records belong to, where the kind is site-scoped. */
+    hostId?: string | null;
+}
+export interface PluginRecordIndex {
+    /**
+     * The live records of the scope, at most `limit`, in the owner's order.
+     * `truncated` says the scope holds more than were answered.
+     */
+    list(request: PluginRecordIndexScope & {
+        limit: number;
+    }): Promise<{
+        records: PluginIndexedRecord[];
+        truncated: boolean;
+    }>;
+    /** One live record, or `null` — gone, deleted, or not the scope's. */
+    get(request: PluginRecordIndexScope & {
+        id: string;
+    }): Promise<PluginIndexedRecord | null>;
+}
+export declare const PLUGIN_RECORD_INDEXES: import("./plugin-services").PluginServiceContract<PluginRecordIndex>;
+/**
+ * Publishes the index for one record kind. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A kind another plugin keeps throws naming both.
+ */
+export declare function registerPluginRecordIndex(kind: string, index: PluginRecordIndex, options?: {
+    pluginId?: string;
+}): void;
+/** The index for a kind, with the plugin that keeps it, or `null` when none does here. */
+export declare function pluginRecordIndex(kind: string): {
+    pluginId: string;
+    index: PluginRecordIndex;
+} | null;

package/src/lib/plugin-manager/plugin-record-index.js

@@ -0,0 +1,51 @@
+/**
+ * @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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_RECORD_INDEXES = definePluginServiceContract('core.record-index', {
+    multiple: true
+});
+/**
+ * Publishes the index for one record kind. The owner is the loader's marker
+ * when a register fn is running, else `options.pluginId`; with neither the
+ * registration throws. A kind another plugin keeps throws naming both.
+ */ export function registerPluginRecordIndex(kind, index, options) {
+    var _ref, _getRegisteringPluginId;
+    const key = kind.trim();
+    if (!key) throw new Error('a record index needs a record kind');
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) {
+        throw new Error(`the record index for "${key}" was registered with no owner`);
+    }
+    const incumbent = resolvePluginServices(PLUGIN_RECORD_INDEXES).find((entry)=>entry.key === key);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`record kind "${key}" is already indexed by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_RECORD_INDEXES, index, {
+        pluginId,
+        key
+    });
+}
+/** The index for a kind, with the plugin that keeps it, or `null` when none does here. */ export function pluginRecordIndex(kind) {
+    const key = kind.trim();
+    const entry = resolvePluginServices(PLUGIN_RECORD_INDEXES).find((one)=>one.key === key);
+    return entry ? {
+        pluginId: entry.pluginId,
+        index: entry.impl
+    } : null;
+}
+
+//# sourceMappingURL=plugin-record-index.js.map

package/src/lib/plugin-manager/plugin-record-index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-index.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 { getRegisteringPluginId } from '../app-utils/registering-plugin'\nimport {\n  definePluginServiceContract,\n  registerPluginService,\n  resolvePluginServices,\n} from './plugin-services'\n\n/**\n * A plugin's records, listed and read for ANOTHER plugin (AGL-3080).\n *\n * A plugin that works over records it does not own — an AI job enriching a\n * site's products, a composer binding the products an email names — used to\n * read the owner's Firestore collection itself: the path, the field names,\n * what \"deleted\" looks like. That is a plugin's storage reached around the\n * plugin, invisible to `check:lib-boundaries` because a collection name is\n * not an import, and it breaks the day the owner changes a field.\n *\n * So the owner publishes an INDEX for each record kind it keeps: `list` names\n * the live records of a scope, `get` reads one — each as an id, a name and the\n * FACTS the owner chooses to share, in a shape its registration documents.\n * The reader never learns where the records are stored or what a deleted one\n * looks like; the owner answers only live records.\n *\n * Its siblings: `plugin-record-cards` (how one record LOOKS, for a campaign\n * sender) and `plugin-record-facts` (what a record SAYS, for a summary);\n * `plugin-resource-drafts` is the WRITE side. This is the side that finds and\n * reads records to work on.\n *\n * ## Not registered is an answer\n *\n * No index for a kind means no plugin keeps it in this process — the owner is\n * not installed, or not loaded. A reader treats that as \"none here\" and says\n * so, rather than reaching for the collection itself. Registered from the\n * owner's server declarations, so every server process that boots the\n * declarations has it.\n *\n * ## One index per kind\n *\n * A second plugin registering an index for a kind another plugin already\n * keeps is refused, naming both, and the incumbent keeps serving.\n */\n\n/** One record, as its owner shares it. */\nexport interface PluginIndexedRecord {\n  id: string\n  /** What a person calls it. Never empty: the owner leaves an unnamed record out. */\n  name: string\n  /** What else the owner shares, in the shape its registration documents. */\n  facts: Readonly<Record<string, unknown>>\n}\n\n/** Which records a reader asks about. */\nexport interface PluginRecordIndexScope {\n  /** The organization the records belong to, where the kind is org-scoped. */\n  orgId?: string | null\n  /** The site the records belong to, where the kind is site-scoped. */\n  hostId?: string | null\n}\n\nexport interface PluginRecordIndex {\n  /**\n   * The live records of the scope, at most `limit`, in the owner's order.\n   * `truncated` says the scope holds more than were answered.\n   */\n  list(\n    request: PluginRecordIndexScope & { limit: number },\n  ): Promise<{ records: PluginIndexedRecord[]; truncated: boolean }>\n  /** One live record, or `null` — gone, deleted, or not the scope's. */\n  get(request: PluginRecordIndexScope & { id: string }): Promise<PluginIndexedRecord | null>\n}\n\nexport const PLUGIN_RECORD_INDEXES = definePluginServiceContract<PluginRecordIndex>(\n  'core.record-index',\n  { multiple: true },\n)\n\n/**\n * Publishes the index for one record kind. The owner is the loader's marker\n * when a register fn is running, else `options.pluginId`; with neither the\n * registration throws. A kind another plugin keeps throws naming both.\n */\nexport function registerPluginRecordIndex(\n  kind: string,\n  index: PluginRecordIndex,\n  options?: { pluginId?: string },\n): void {\n  const key = kind.trim()\n  if (!key) throw new Error('a record index needs a record kind')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) {\n    throw new Error(`the record index for \"${key}\" was registered with no owner`)\n  }\n  const incumbent = resolvePluginServices(PLUGIN_RECORD_INDEXES).find(\n    (entry) => entry.key === key,\n  )\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `record kind \"${key}\" is already indexed by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_RECORD_INDEXES, index, { pluginId, key })\n}\n\n/** The index for a kind, with the plugin that keeps it, or `null` when none does here. */\nexport function pluginRecordIndex(\n  kind: string,\n): { pluginId: string; index: PluginRecordIndex } | null {\n  const key = kind.trim()\n  const entry = resolvePluginServices(PLUGIN_RECORD_INDEXES).find((one) => one.key === key)\n  return entry ? { pluginId: entry.pluginId, index: entry.impl } : null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_INDEXES","multiple","registerPluginRecordIndex","kind","index","options","key","trim","Error","pluginId","incumbent","find","entry","pluginRecordIndex","one","impl"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAkE1B,OAAO,MAAMC,wBAAwBH,4BACnC,qBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,0BACdC,IAAY,EACZC,KAAwB,EACxBC,OAA+B;QAIbT,MAAAA;IAFlB,MAAMU,MAAMH,KAAKI,IAAI;IACrB,IAAI,CAACD,KAAK,MAAM,IAAIE,MAAM;IAC1B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BS,2BAAAA,QAASI,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,IAAI,CAACE,UAAU;QACb,MAAM,IAAID,MAAM,CAAC,sBAAsB,EAAEF,IAAI,8BAA8B,CAAC;IAC9E;IACA,MAAMI,YAAYX,sBAAsBC,uBAAuBW,IAAI,CACjE,CAACC,QAAUA,MAAMN,GAAG,KAAKA;IAE3B,IAAII,aAAaA,UAAUD,QAAQ,KAAKA,UAAU;QAChD,MAAM,IAAID,MACR,CAAC,aAAa,EAAEF,IAAI,yBAAyB,EAAEI,UAAUD,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAE/F;IACAX,sBAAsBE,uBAAuBI,OAAO;QAAEK;QAAUH;IAAI;AACtE;AAEA,wFAAwF,GACxF,OAAO,SAASO,kBACdV,IAAY;IAEZ,MAAMG,MAAMH,KAAKI,IAAI;IACrB,MAAMK,QAAQb,sBAAsBC,uBAAuBW,IAAI,CAAC,CAACG,MAAQA,IAAIR,GAAG,KAAKA;IACrF,OAAOM,QAAQ;QAAEH,UAAUG,MAAMH,QAAQ;QAAEL,OAAOQ,MAAMG,IAAI;IAAC,IAAI;AACnE"}

package/src/lib/plugin-manager/plugin-record-written.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 record changed": the one signal every server writer of an org record
+ * already gives (AGL-3336).
+ *
+ * The capture doors, the conversion, the merge, an automation's step, the
+ * record system's own routes — each of them, after it writes a record under
+ * `orgs/{orgId}/{collection}`, restamps the fields that record's list
+ * queries (`restampCrmListFieldsAt`). That restamp is the only place all of
+ * them pass, so it is where a plugin that needs to act on the record AFTER
+ * any write — re-evaluating the sharing rules that match it, say — is told.
+ * A listener registered here is the alternative to editing every writer.
+ *
+ * ## What a listener may do
+ *
+ * Read the record and write it again, in its own transaction. It must not
+ * call back into the restamp, which is what would loop; the restamp
+ * notifies after its own write, once. A listener that throws is logged and
+ * the next one still runs: the write it is told about already landed.
+ */
+/**
+ * A written record, by its path: the listener opens its own reference, so
+ * core names no database SDK.
+ */
+export interface PluginRecordWrittenEvent {
+    /** `orgs/{orgId}/{collection}/{id}`. */
+    path: string;
+    /** The collection's name under the org. */
+    collection: string;
+}
+export type PluginRecordWrittenListener = (event: PluginRecordWrittenEvent) => Promise<void>;
+export declare const PLUGIN_RECORD_WRITTEN: import("./plugin-services").PluginServiceContract<PluginRecordWrittenListener>;
+/**
+ * Registers a listener. The owner is the loader's marker when a register fn
+ * is running, else `options.pluginId`; registering twice under one key
+ * replaces in place.
+ */
+export declare function registerPluginRecordWrittenListener(listener: PluginRecordWrittenListener, options?: {
+    pluginId?: string;
+    key?: string;
+}): void;
+/** Tells every listener. Never throws. */
+export declare function notifyPluginRecordWritten(event: PluginRecordWrittenEvent): Promise<void>;

package/src/lib/plugin-manager/plugin-record-written.js

@@ -0,0 +1,42 @@
+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_RECORD_WRITTEN = definePluginServiceContract('core.record-written', {
+    multiple: true
+});
+/**
+ * Registers a listener. The owner is the loader's marker when a register fn
+ * is running, else `options.pluginId`; registering twice under one key
+ * replaces in place.
+ */ export function registerPluginRecordWrittenListener(listener, options) {
+    registerPluginService(PLUGIN_RECORD_WRITTEN, listener, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}, (options == null ? void 0 : options.key) ? {
+        key: options.key
+    } : {}));
+}
+/** Tells every listener. Never throws. */ export async function notifyPluginRecordWritten(event) {
+    for (const entry of resolvePluginServices(PLUGIN_RECORD_WRITTEN)){
+        try {
+            await entry.impl(event);
+        } catch (error) {
+            console.error(`[record-written] ${entry.pluginId} failed on ${event.path}`, error);
+        }
+    }
+}
+
+//# sourceMappingURL=plugin-record-written.js.map

package/src/lib/plugin-manager/plugin-record-written.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-record-written.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 record changed\": the one signal every server writer of an org record\n * already gives (AGL-3336).\n *\n * The capture doors, the conversion, the merge, an automation's step, the\n * record system's own routes — each of them, after it writes a record under\n * `orgs/{orgId}/{collection}`, restamps the fields that record's list\n * queries (`restampCrmListFieldsAt`). That restamp is the only place all of\n * them pass, so it is where a plugin that needs to act on the record AFTER\n * any write — re-evaluating the sharing rules that match it, say — is told.\n * A listener registered here is the alternative to editing every writer.\n *\n * ## What a listener may do\n *\n * Read the record and write it again, in its own transaction. It must not\n * call back into the restamp, which is what would loop; the restamp\n * notifies after its own write, once. A listener that throws is logged and\n * the next one still runs: the write it is told about already landed.\n */\n\n/**\n * A written record, by its path: the listener opens its own reference, so\n * core names no database SDK.\n */\nexport interface PluginRecordWrittenEvent {\n  /** `orgs/{orgId}/{collection}/{id}`. */\n  path: string\n  /** The collection's name under the org. */\n  collection: string\n}\n\nexport type PluginRecordWrittenListener = (event: PluginRecordWrittenEvent) => Promise<void>\n\nexport const PLUGIN_RECORD_WRITTEN = definePluginServiceContract<PluginRecordWrittenListener>(\n  'core.record-written',\n  { multiple: true },\n)\n\n/**\n * Registers a listener. The owner is the loader's marker when a register fn\n * is running, else `options.pluginId`; registering twice under one key\n * replaces in place.\n */\nexport function registerPluginRecordWrittenListener(\n  listener: PluginRecordWrittenListener,\n  options?: { pluginId?: string; key?: string },\n): void {\n  registerPluginService(PLUGIN_RECORD_WRITTEN, listener, {\n    ...(options?.pluginId ? { pluginId: options.pluginId } : {}),\n    ...(options?.key ? { key: options.key } : {}),\n  })\n}\n\n/** Tells every listener. Never throws. */\nexport async function notifyPluginRecordWritten(event: PluginRecordWrittenEvent): Promise<void> {\n  for (const entry of resolvePluginServices(PLUGIN_RECORD_WRITTEN)) {\n    try {\n      await entry.impl(event)\n    } catch (error) {\n      console.error(\n        `[record-written] ${entry.pluginId} failed on ${event.path}`,\n        error,\n      )\n    }\n  }\n}\n"],"names":["definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_RECORD_WRITTEN","multiple","registerPluginRecordWrittenListener","listener","options","pluginId","key","notifyPluginRecordWritten","event","entry","impl","error","console","path"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AAmC1B,OAAO,MAAMC,wBAAwBH,4BACnC,uBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,oCACdC,QAAqC,EACrCC,OAA6C;IAE7CN,sBAAsBE,uBAAuBG,UAAU,aACjDC,CAAAA,2BAAAA,QAASC,QAAQ,IAAG;QAAEA,UAAUD,QAAQC,QAAQ;IAAC,IAAI,CAAC,GACtDD,CAAAA,2BAAAA,QAASE,GAAG,IAAG;QAAEA,KAAKF,QAAQE,GAAG;IAAC,IAAI,CAAC;AAE/C;AAEA,wCAAwC,GACxC,OAAO,eAAeC,0BAA0BC,KAA+B;IAC7E,KAAK,MAAMC,SAASV,sBAAsBC,uBAAwB;QAChE,IAAI;YACF,MAAMS,MAAMC,IAAI,CAACF;QACnB,EAAE,OAAOG,OAAO;YACdC,QAAQD,KAAK,CACX,CAAC,iBAAiB,EAAEF,MAAMJ,QAAQ,CAAC,WAAW,EAAEG,MAAMK,IAAI,EAAE,EAC5DF;QAEJ;IACF;AACF"}

package/src/lib/plugin-manager/plugin-revenue-sources.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @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.
+ */
+/**
+ * WHAT A PLUGIN EARNED THE OPERATOR, ON THE STAFF REVENUE REPORT (AGL-3080).
+ *
+ * The operator's revenue report states what the deployment actually kept in a
+ * period. Its own subscription invoices are platform billing and the report
+ * folds them itself. A plugin that sells through the platform's account — a
+ * storefront's application fee, a marketplace's commission — earns the
+ * operator a take the report cannot compute without knowing that plugin's
+ * storage and its fee rules, and it has no business restating either.
+ *
+ * So the division is: the REPORT is the platform's — the period, the two
+ * bases, the gap, the sweep ceiling, the read budget for names and the page.
+ * What a plugin's sales earned, net of what is not the operator's, and who
+ * produced it, are the plugin's. A source answers one period with a
+ * {@link RevenueSourceAnswer}: its earned line, its gross-to-net lines, its
+ * qualifications, its attribution tables and its own settled figures.
+ *
+ * ## ⛔ AN UNREAD SOURCE IS NEVER A ZERO
+ *
+ * A source that answered nothing reads, on a total, exactly like one that
+ * earned nothing, and a revenue total quoted short is a figure somebody
+ * repeats. So, as the tax return's sources do:
+ *
+ * - every plugin that earns through the platform declares
+ *   `"revenueSource": true` in `plugins.config.json`, compiled into
+ *   {@link PLUGIN_REVENUE_SOURCES}; a declared plugin with no registration, a
+ *   source that threw and a malformed answer each come back
+ *   `outcome: 'refused'`, and the page says whose earnings are missing;
+ * - a source whose own read could not run answers with `failure` and figures
+ *   it does NOT claim, and one whose sweep stopped at the ceiling answers
+ *   `truncated` — the page names both rather than quoting the total.
+ *
+ * {@link readRevenueSources} never throws and never drops a declared source.
+ * The reader is the staff revenue route, which awaits `ensureAll` on the
+ * `consoleApi` surface before it asks.
+ */
+import { PLUGIN_REVENUE_SOURCES } from './first-party-plugins.generated';
+export { PLUGIN_REVENUE_SOURCES };
+/**
+ * Pages a query to exhaustion under the operator's ceiling. The ceiling is the
+ * platform's policy about its own request, so a source is handed the sweep
+ * rather than choosing one; `truncated` means the ceiling stopped it.
+ */
+export type RevenueSweep = <Doc>(query: unknown, orderField: unknown) => Promise<{
+    docs: Doc[];
+    truncated: boolean;
+}>;
+/** One attributed row: who produced a gain, and the loss beside it. */
+export interface RevenueAttributionRow {
+    key: string;
+    /** Display name, filled in by a bounded lookup; the id until then. */
+    name: string;
+    /** Secondary identity — plugin id, publisher, subdomain. */
+    detail: string;
+    /** Revenue earned, net of its own reversals. */
+    gainCents: number;
+    /** Money handed back. Already deducted from `gainCents`. */
+    lossCents: number;
+    count: number;
+}
+/** A capped attribution: shown rows plus the remainder, as figures. */
+export interface RevenueAttribution {
+    rows: RevenueAttributionRow[];
+    omittedRows: number;
+    omittedGainCents: number;
+    omittedLossCents: number;
+}
+/** What the report asks every source, once per period. */
+export interface RevenueSourceRequest {
+    /** `2026-08` or `2026-Q3`, echoed for the record. */
+    period: string;
+    /** Half-open UTC bounds of the period. */
+    start: Date;
+    end: Date;
+    /** Rows per attribution table the page shows; the rest is carried as figures. */
+    attributionLimit: number;
+    sweep: RevenueSweep;
+    /**
+     * Display names for organizations — which the report has already read, so
+     * naming a publisher costs nothing.
+     */
+    orgNames(orgIds: readonly string[]): Promise<ReadonlyMap<string, string>>;
+    /**
+     * Names the rows a source will SHOW from a collection's documents, in place:
+     * `name` from `nameField`, `detail` from `detailField`, and `(deleted)` for a
+     * document that is gone. Called AFTER capping, so the read is bounded by what
+     * is displayed rather than by how many sales the period holds.
+     */
+    nameRows(rows: RevenueAttributionRow[], from: {
+        collection: string;
+        nameField: string;
+        detailField: string;
+    }): Promise<void>;
+}
+/** A line of the report's gross-versus-net reconciliation. */
+export interface RevenueSourceLine {
+    label: string;
+    cents: number;
+    /** Subtracted on the way from gross to what the operator kept. */
+    deduction: boolean;
+    /** Whose money it is — the sentence that says why it is or is not revenue. */
+    note: string;
+}
+/** A table of who produced a source's earnings. */
+export interface RevenueAttributionTable extends RevenueAttribution {
+    id: string;
+    heading: string;
+    /** The column naming what a row is: `Listing`, `Storefront`. */
+    unit: string;
+    /** The column counting what was summed: `Sales`, `Orders`. */
+    countLabel: string;
+    empty: string;
+    /** Draw the rows as ranked bars above the table, saying this when there are none. */
+    chartEmpty?: string;
+}
+/** What a source answers for one period. */
+export interface RevenueSourceAnswer {
+    /** Stable key, unique on the report. */
+    id: string;
+    /** How the report names it when its read stopped short: `marketplace`. */
+    name: string;
+    /** Its line of "where the money came from", net of everything not the operator's. */
+    earned: {
+        label: string;
+        cents: number;
+        note: string;
+    };
+    grossToNet: RevenueSourceLine[];
+    /** Qualifications worth stating beside the figures. Only those that apply. */
+    notes: Array<{
+        label: string;
+        tone: 'warning' | 'neutral';
+    }>;
+    /** Each sums to `earned`. */
+    attribution: RevenueAttributionTable[];
+    /** A sentence under the source's attribution tables. */
+    attributionNote?: string;
+    /** The sweep stopped at the ceiling: every figure is a LOWER BOUND. */
+    truncated: boolean;
+    /**
+     * The source's read could not run at all, so its figures are not counted —
+     * never a cap, which is a different state with a different remedy.
+     */
+    failure: {
+        title: string;
+        detail: string;
+    } | null;
+    /** The source's own settled figures, carried whole for the audit. */
+    summary: unknown;
+}
+/** One source on the report: its answer, or why there is none. */
+export type RevenueSection = ({
+    outcome: 'answered';
+    pluginId: string;
+} & RevenueSourceAnswer) | {
+    outcome: 'refused';
+    pluginId: string;
+    /** The plugin id: a refused source never said what it calls itself. */
+    id: string;
+    reason: string;
+};
+export interface RevenueSource {
+    /** This plugin's earnings for one period. May throw: the report refuses it. */
+    read(request: RevenueSourceRequest): Promise<RevenueSourceAnswer>;
+}
+/** Every source answers; one per plugin. */
+export declare const REVENUE_SOURCES: import("./plugin-services").PluginServiceContract<RevenueSource>;
+/** Installs a plugin's source; registering again replaces it. */
+export declare function registerRevenueSource(source: RevenueSource, options?: {
+    pluginId?: string;
+}): void;
+/** The plugins with a registered source, in the order they answer. */
+export declare function listRevenueSources(): string[];
+/**
+ * Group, sort and cap — every attribution table's shared half.
+ *
+ * A row whose key is missing is NOT dropped. It is grouped under an explicit
+ * unattributed key, because a sale nobody can attribute still happened and
+ * dropping it would make the rows sum below the total — the one property that
+ * makes any of these tables worth reading. The cap carries its remainder as
+ * FIGURES, so the table stays a complete accounting even when it is not a
+ * complete list.
+ */
+export declare function groupRevenueAttribution(entries: ReadonlyArray<{
+    key: string;
+    detail: string;
+    gain: number;
+    loss: number;
+}>, limit: number, unattributedLabel: string): RevenueAttribution;
+/**
+ * Every source's answer for one period — declared sources first, in the
+ * compiled order, then any other registered source.
+ *
+ * NEVER THROWS and never drops a declared source. `declared` is the compiled
+ * {@link PLUGIN_REVENUE_SOURCES} unless a spec passes its own.
+ */
+export declare function readRevenueSources(request: RevenueSourceRequest, declared?: readonly string[]): Promise<RevenueSection[]>;