@aglyn/aglyn 1.0.0-beta.218 → 1.0.0-beta.220

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[]>;

package/src/lib/plugin-manager/plugin-revenue-sources.js

@@ -0,0 +1,194 @@
+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.
+ */ /**
+ * 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.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export { PLUGIN_REVENUE_SOURCES };
+/** Every source answers; one per plugin. */ export const REVENUE_SOURCES = definePluginServiceContract('core.revenue-sources', {
+    multiple: true
+});
+/** Installs a plugin's source; registering again replaces it. */ export function registerRevenueSource(source, options) {
+    if (typeof (source == null ? void 0 : source.read) !== 'function') {
+        throw new Error('a revenue source needs a read function');
+    }
+    registerPluginService(REVENUE_SOURCES, source, _extends({}, (options == null ? void 0 : options.pluginId) ? {
+        pluginId: options.pluginId
+    } : {}));
+}
+/** The plugins with a registered source, in the order they answer. */ export function listRevenueSources() {
+    return resolvePluginServices(REVENUE_SOURCES).map((entry)=>entry.pluginId);
+}
+/**
+ * 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 function groupRevenueAttribution(entries, limit, unattributedLabel) {
+    const byKey = new Map();
+    for (const entry of entries != null ? entries : []){
+        var _byKey_get, _entry_detail;
+        const key = entry.key || unattributedLabel;
+        const row = (_byKey_get = byKey.get(key)) != null ? _byKey_get : {
+            key,
+            name: key === unattributedLabel ? unattributedLabel : key,
+            detail: (_entry_detail = entry.detail) != null ? _entry_detail : '',
+            gainCents: 0,
+            lossCents: 0,
+            count: 0
+        };
+        row.gainCents += entry.gain;
+        row.lossCents += entry.loss;
+        row.count += 1;
+        if (!row.detail && entry.detail) row.detail = entry.detail;
+        byKey.set(key, row);
+    }
+    const rows = [
+        ...byKey.values()
+    ].sort((a, b)=>b.gainCents - a.gainCents || b.lossCents - a.lossCents || a.key.localeCompare(b.key));
+    const kept = rows.slice(0, Math.max(0, limit));
+    const dropped = rows.slice(Math.max(0, limit));
+    return {
+        rows: kept,
+        omittedRows: dropped.length,
+        omittedGainCents: dropped.reduce((sum, row)=>sum + row.gainCents, 0),
+        omittedLossCents: dropped.reduce((sum, row)=>sum + row.lossCents, 0)
+    };
+}
+const isText = (value)=>typeof value === 'string' && value.trim().length > 0;
+/** What is wrong with an answer, or null when it can be printed. */ function malformed(answer) {
+    var _answer_earned, _answer_earned1;
+    if (!answer || typeof answer !== 'object') return 'no report';
+    if (!isText(answer.id) || !isText(answer.name)) return 'a report with no id or name';
+    const cents = (_answer_earned = answer.earned) == null ? void 0 : _answer_earned.cents;
+    if (typeof cents !== 'number' || !Number.isFinite(cents)) return 'no earned figure';
+    if (!isText((_answer_earned1 = answer.earned) == null ? void 0 : _answer_earned1.label)) return 'an earned figure with no label';
+    if (typeof answer.truncated !== 'boolean') return 'no truncation flag';
+    for (const key of [
+        'grossToNet',
+        'notes',
+        'attribution'
+    ]){
+        if (!Array.isArray(answer[key])) return `no ${key}`;
+    }
+    const badLine = answer.grossToNet.find((line)=>typeof (line == null ? void 0 : line.cents) !== 'number' || !Number.isFinite(line.cents));
+    if (badLine) return 'a gross-to-net line with no figure';
+    return null;
+}
+/**
+ * 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 async function readRevenueSources(request, declared = PLUGIN_REVENUE_SOURCES) {
+    const registered = resolvePluginServices(REVENUE_SOURCES);
+    const order = [
+        ...declared,
+        ...registered.map((entry)=>entry.pluginId).filter((pluginId)=>!declared.includes(pluginId))
+    ].filter((pluginId, index, all)=>all.indexOf(pluginId) === index);
+    const answers = await Promise.all(order.map(async (pluginId)=>{
+        var _registered_find;
+        const source = (_registered_find = registered.find((entry)=>entry.pluginId === pluginId)) == null ? void 0 : _registered_find.impl;
+        if (!source) {
+            console.error(`[revenue] "${pluginId}" declares a revenue source and none is ` + 'registered in this process; its earnings cannot be read.');
+            return {
+                outcome: 'refused',
+                pluginId,
+                id: pluginId,
+                reason: `The “${pluginId}” plugin earns through the platform and registered ` + 'nothing to read its earnings with.'
+            };
+        }
+        try {
+            const answer = await source.read(request);
+            const problem = malformed(answer);
+            if (problem) {
+                return {
+                    outcome: 'refused',
+                    pluginId,
+                    id: pluginId,
+                    reason: `The “${pluginId}” plugin answered ${problem}.`
+                };
+            }
+            return _extends({}, answer, {
+                outcome: 'answered',
+                pluginId
+            });
+        } catch (error) {
+            console.error(`[revenue] "${pluginId}" failed to read its earnings`, error);
+            return {
+                outcome: 'refused',
+                pluginId,
+                id: pluginId,
+                reason: `The “${pluginId}” plugin could not read its earnings for this period.`
+            };
+        }
+    }));
+    const seen = new Set();
+    return answers.map((section)=>{
+        if (section.outcome !== 'answered') return section;
+        if (!seen.has(section.id)) {
+            seen.add(section.id);
+            return section;
+        }
+        return {
+            outcome: 'refused',
+            pluginId: section.pluginId,
+            id: section.pluginId,
+            reason: `The “${section.pluginId}” plugin answered as “${section.id}”, which ` + 'another source already is.'
+        };
+    });
+}
+
+//# sourceMappingURL=plugin-revenue-sources.js.map

package/src/lib/plugin-manager/plugin-revenue-sources.js.map

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

package/src/lib/plugin-manager/plugin-site-beacons.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @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 own beacons, posted to the platform's site collector.
+ *
+ * A published page has one place to report what visitors did — the
+ * collector behind `sendAnalyticsBeacon` — and that endpoint owns what every
+ * beacon owes before anything is counted: the host must exist, a platform,
+ * org or site lockdown refuses it silently, and the per-address rate limit
+ * applies. What a plugin's site runtime reports beyond a pageview (an
+ * announcement bar seen, a popup dismissed) is the plugin's to count, in its
+ * own documents.
+ *
+ * So the plugin registers a beacon by the body FIELD that marks it as its
+ * own, and the collector hands a beacon carrying that field to the plugin
+ * after its own gates, then answers 204 without counting a pageview. The
+ * field is the beacon's whole claim: one owner per field, refused naming
+ * both, and the incumbent keeps serving.
+ *
+ * Registered from the plugin's `serverDeclarations`, so every server process
+ * has it from boot; keep the registration light and import the counting
+ * code on the first beacon.
+ */
+/** What the collector hands the owner, after the host and lockdown gates. */
+export interface PluginSiteBeaconRequest {
+    hostId: string;
+    /** The collector's day bucket, `YYYY-MM-DD` in UTC. */
+    day: string;
+    /**
+     * When the site's analytics document for {@link day} expires: the
+     * platform's retention. An owner that writes into that document stamps it,
+     * so a document created by its beacons alone is still swept.
+     */
+    dayExpiresAt: Date;
+    /** The beacon as the browser sent it. Untrusted: validate every field read. */
+    body: Readonly<Record<string, unknown>>;
+}
+export interface PluginSiteBeacon {
+    /** The body field whose non-empty string marks a beacon as this plugin's. */
+    field: string;
+    /** Counts one beacon. A throw is logged by the collector, never surfaced. */
+    count(request: PluginSiteBeaconRequest): Promise<void>;
+}
+export declare const PLUGIN_SITE_BEACONS: import("./plugin-services").PluginServiceContract<PluginSiteBeacon>;
+/**
+ * Registers a beacon. The owner is the loader's marker inside a register fn,
+ * else `options.pluginId`; with neither the registration throws. A field
+ * another plugin claims throws naming both.
+ */
+export declare function registerPluginSiteBeacon(beacon: PluginSiteBeacon, options?: {
+    pluginId?: string;
+}): void;
+/** The owner of a beacon body, or `null` when no registered field marks it. */
+export declare function pluginSiteBeaconFor(body: Readonly<Record<string, unknown>>): {
+    pluginId: string;
+    beacon: PluginSiteBeacon;
+} | null;

package/src/lib/plugin-manager/plugin-site-beacons.js

@@ -0,0 +1,54 @@
+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 { getRegisteringPluginId } from "../app-utils/registering-plugin.js";
+import { definePluginServiceContract, registerPluginService, resolvePluginServices } from "./plugin-services.js";
+export const PLUGIN_SITE_BEACONS = definePluginServiceContract('core.site-beacons', {
+    multiple: true
+});
+/**
+ * Registers a beacon. The owner is the loader's marker inside a register fn,
+ * else `options.pluginId`; with neither the registration throws. A field
+ * another plugin claims throws naming both.
+ */ export function registerPluginSiteBeacon(beacon, options) {
+    var _beacon_field, _ref, _getRegisteringPluginId;
+    const field = String((_beacon_field = beacon.field) != null ? _beacon_field : '').trim();
+    if (!field) throw new Error('a site beacon needs the body field that marks it');
+    const pluginId = ((_ref = (_getRegisteringPluginId = getRegisteringPluginId()) != null ? _getRegisteringPluginId : options == null ? void 0 : options.pluginId) != null ? _ref : '').trim();
+    if (!pluginId) throw new Error(`the site beacon "${field}" was registered with no owner`);
+    const incumbent = resolvePluginServices(PLUGIN_SITE_BEACONS).find((entry)=>entry.key === field);
+    if (incumbent && incumbent.pluginId !== pluginId) {
+        throw new Error(`site beacon field "${field}" is already counted by "${incumbent.pluginId}"; refused "${pluginId}"`);
+    }
+    registerPluginService(PLUGIN_SITE_BEACONS, _extends({}, beacon, {
+        field
+    }), {
+        pluginId,
+        key: field
+    });
+}
+/** The owner of a beacon body, or `null` when no registered field marks it. */ export function pluginSiteBeaconFor(body) {
+    for (const entry of resolvePluginServices(PLUGIN_SITE_BEACONS)){
+        const value = body[entry.impl.field];
+        if (typeof value === 'string' && value) return {
+            pluginId: entry.pluginId,
+            beacon: entry.impl
+        };
+    }
+    return null;
+}
+
+//# sourceMappingURL=plugin-site-beacons.js.map

package/src/lib/plugin-manager/plugin-site-beacons.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/plugin-manager/plugin-site-beacons.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 own beacons, posted to the platform's site collector.\n *\n * A published page has one place to report what visitors did — the\n * collector behind `sendAnalyticsBeacon` — and that endpoint owns what every\n * beacon owes before anything is counted: the host must exist, a platform,\n * org or site lockdown refuses it silently, and the per-address rate limit\n * applies. What a plugin's site runtime reports beyond a pageview (an\n * announcement bar seen, a popup dismissed) is the plugin's to count, in its\n * own documents.\n *\n * So the plugin registers a beacon by the body FIELD that marks it as its\n * own, and the collector hands a beacon carrying that field to the plugin\n * after its own gates, then answers 204 without counting a pageview. The\n * field is the beacon's whole claim: one owner per field, refused naming\n * both, and the incumbent keeps serving.\n *\n * Registered from the plugin's `serverDeclarations`, so every server process\n * has it from boot; keep the registration light and import the counting\n * code on the first beacon.\n */\n\n/** What the collector hands the owner, after the host and lockdown gates. */\nexport interface PluginSiteBeaconRequest {\n  hostId: string\n  /** The collector's day bucket, `YYYY-MM-DD` in UTC. */\n  day: string\n  /**\n   * When the site's analytics document for {@link day} expires: the\n   * platform's retention. An owner that writes into that document stamps it,\n   * so a document created by its beacons alone is still swept.\n   */\n  dayExpiresAt: Date\n  /** The beacon as the browser sent it. Untrusted: validate every field read. */\n  body: Readonly<Record<string, unknown>>\n}\n\nexport interface PluginSiteBeacon {\n  /** The body field whose non-empty string marks a beacon as this plugin's. */\n  field: string\n  /** Counts one beacon. A throw is logged by the collector, never surfaced. */\n  count(request: PluginSiteBeaconRequest): Promise<void>\n}\n\nexport const PLUGIN_SITE_BEACONS = definePluginServiceContract<PluginSiteBeacon>(\n  'core.site-beacons',\n  { multiple: true },\n)\n\n/**\n * Registers a beacon. The owner is the loader's marker inside a register fn,\n * else `options.pluginId`; with neither the registration throws. A field\n * another plugin claims throws naming both.\n */\nexport function registerPluginSiteBeacon(\n  beacon: PluginSiteBeacon,\n  options?: { pluginId?: string },\n): void {\n  const field = String(beacon.field ?? '').trim()\n  if (!field) throw new Error('a site beacon needs the body field that marks it')\n  const pluginId = (getRegisteringPluginId() ?? options?.pluginId ?? '').trim()\n  if (!pluginId) throw new Error(`the site beacon \"${field}\" was registered with no owner`)\n  const incumbent = resolvePluginServices(PLUGIN_SITE_BEACONS).find((entry) => entry.key === field)\n  if (incumbent && incumbent.pluginId !== pluginId) {\n    throw new Error(\n      `site beacon field \"${field}\" is already counted by \"${incumbent.pluginId}\"; refused \"${pluginId}\"`,\n    )\n  }\n  registerPluginService(PLUGIN_SITE_BEACONS, { ...beacon, field }, { pluginId, key: field })\n}\n\n/** The owner of a beacon body, or `null` when no registered field marks it. */\nexport function pluginSiteBeaconFor(\n  body: Readonly<Record<string, unknown>>,\n): { pluginId: string; beacon: PluginSiteBeacon } | null {\n  for (const entry of resolvePluginServices(PLUGIN_SITE_BEACONS)) {\n    const value = body[entry.impl.field]\n    if (typeof value === 'string' && value) return { pluginId: entry.pluginId, beacon: entry.impl }\n  }\n  return null\n}\n"],"names":["getRegisteringPluginId","definePluginServiceContract","registerPluginService","resolvePluginServices","PLUGIN_SITE_BEACONS","multiple","registerPluginSiteBeacon","beacon","options","field","String","trim","Error","pluginId","incumbent","find","entry","key","pluginSiteBeaconFor","body","value","impl"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,sBAAsB,QAAQ,qCAAiC;AACxE,SACEC,2BAA2B,EAC3BC,qBAAqB,EACrBC,qBAAqB,QAChB,uBAAmB;AA8C1B,OAAO,MAAMC,sBAAsBH,4BACjC,qBACA;IAAEI,UAAU;AAAK,GAClB;AAED;;;;CAIC,GACD,OAAO,SAASC,yBACdC,MAAwB,EACxBC,OAA+B;QAEVD,eAEHP,MAAAA;IAFlB,MAAMS,QAAQC,QAAOH,gBAAAA,OAAOE,KAAK,YAAZF,gBAAgB,IAAII,IAAI;IAC7C,IAAI,CAACF,OAAO,MAAM,IAAIG,MAAM;IAC5B,MAAMC,WAAW,EAACb,QAAAA,0BAAAA,oCAAAA,0BAA4BQ,2BAAAA,QAASK,QAAQ,YAA7Cb,OAAiD,IAAIW,IAAI;IAC3E,IAAI,CAACE,UAAU,MAAM,IAAID,MAAM,CAAC,iBAAiB,EAAEH,MAAM,8BAA8B,CAAC;IACxF,MAAMK,YAAYX,sBAAsBC,qBAAqBW,IAAI,CAAC,CAACC,QAAUA,MAAMC,GAAG,KAAKR;IAC3F,IAAIK,aAAaA,UAAUD,QAAQ,KAAKA,UAAU;QAChD,MAAM,IAAID,MACR,CAAC,mBAAmB,EAAEH,MAAM,yBAAyB,EAAEK,UAAUD,QAAQ,CAAC,YAAY,EAAEA,SAAS,CAAC,CAAC;IAEvG;IACAX,sBAAsBE,qBAAqB,aAAKG;QAAQE;QAAS;QAAEI;QAAUI,KAAKR;IAAM;AAC1F;AAEA,6EAA6E,GAC7E,OAAO,SAASS,oBACdC,IAAuC;IAEvC,KAAK,MAAMH,SAASb,sBAAsBC,qBAAsB;QAC9D,MAAMgB,QAAQD,IAAI,CAACH,MAAMK,IAAI,CAACZ,KAAK,CAAC;QACpC,IAAI,OAAOW,UAAU,YAAYA,OAAO,OAAO;YAAEP,UAAUG,MAAMH,QAAQ;YAAEN,QAAQS,MAAMK,IAAI;QAAC;IAChG;IACA,OAAO;AACT"}