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

package/src/lib/app-utils/analytics-provider.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { VisitorConsentHost } from './visitor-consent';
+/**
+ * Third-party analytics tags, behind one contract (AGL-3080).
+ *
+ * A site can send its visitors' measurement to an analytics vendor it chose:
+ * a measurement id or a tag container, saved in the site's analytics
+ * settings. The platform owns everything around that tag — whether this
+ * visitor may be measured at all (`visitor-consent.ts`), the consent banner,
+ * the first-party pageview beacon that meters the site (`analytics-beacon.ts`,
+ * which is not a tag and never goes through here) — and names no vendor. A
+ * plugin's ADAPTER is what knows a vendor: what its tag looks like on the
+ * page, how a resident tag is told the visitor's answer changed, and how an
+ * event reaches it.
+ *
+ * ## Declared, then loaded where it is used
+ *
+ * Two questions, answered by two different mechanisms, because their readers
+ * cannot wait for the same thing:
+ *
+ * - "Does this site run a tag, so is there anything to ask its visitors?" is
+ *   asked synchronously, during render, by the consent gate on the published
+ *   page and by the console's banner card and preview. A registry one of
+ *   those had not filled yet would answer "no tag" — no banner, and nothing to
+ *   gate — so the answer is COMPILED: the plugin declares which of the site's
+ *   analytics settings it mounts a tag for (`analyticsProvider.settings` in
+ *   `plugins.config.json`), and `hostConfiguresAnalyticsTag` in
+ *   `visitor-consent.ts` reads that list. With no provider declared, no setting configures a tag, and a site
+ *   with nothing that could mount asks its visitors nothing.
+ * - Everything else — mounting the tag, telling it the answer changed,
+ *   handing it an event — happens after the adapter has loaded. The adapter
+ *   is a chunk of its own, reached through each app's generated
+ *   `plugins.analytics.generated.ts` and fetched only by a document that uses
+ *   it: a published page whose site configures a tag, and the console, whose
+ *   own measurement tag the consent controls answer to. A page whose site
+ *   configures none never fetches it.
+ *
+ * ## What an unloaded adapter means
+ *
+ * A tag is mounted only by its adapter, so until the adapter has loaded there
+ * is no tag of its to silence or to send to, and nothing is lost by the wait:
+ * events find no resident tag and drop, exactly as they do for a visitor who
+ * has not granted.
+ *
+ * A tag this document did not mount — the console's, which its analytics SDK
+ * injects — can be resident before the adapter arrives. So the last answer
+ * {@link applyAnalyticsConsent} was given is kept, and an adapter that
+ * registers later is handed it at once: a withdrawal made in that window
+ * reaches the tag the moment something can speak to it.
+ */
+/**
+ * What a provider declares about itself, compiled from `plugins.config.json`.
+ * `settings` are keys of the site's `analytics` settings; each is validated
+ * by the pattern `ANALYTICS_SETTING_PATTERNS` in `visitor-consent.ts` holds
+ * for it.
+ */
+export interface AnalyticsProviderDeclaration {
+    /** The plugin that provides the adapter. */
+    pluginId: string;
+    /** The analytics settings this provider mounts a tag for. */
+    settings: readonly string[];
+}
+/** The visitor's answer, in the platform's two categories. */
+export interface AnalyticsGrants {
+    analytics: boolean;
+    advertising: boolean;
+}
+/**
+ * One tag on a published page: an inline boot that runs first, then the
+ * vendor's library. The page renders the pair in order, under the consent
+ * gate and with the request's nonce, as `${id}-init` and `${id}-src`.
+ *
+ * Both strings land in the document. `boot` is inline script, so an adapter
+ * builds it from constants and format-checked ids only.
+ */
+export interface AnalyticsTagMount {
+    /** Element id prefix. Stable: specs and the CSP report read it. */
+    id: string;
+    /** Inline script that runs before the library. */
+    boot: string;
+    /** The library URL. */
+    src: string;
+    /**
+     * A marker for the library this pair loads, for an advertising vendor that
+     * rides the same library instead of fetching it again (`sharesLibrary` in
+     * `advertising-tags.ts`).
+     */
+    library?: string;
+}
+/** What the page tells an adapter about the pageview it mounts tags for. */
+export interface AnalyticsMountOptions {
+    /**
+     * Whether the site runs the platform's consent machinery. When it does, the
+     * tag is told the visitor's answer before it measures anything; when the
+     * host runs a consent solution of its own, that solution tells it.
+     */
+    consentRequired: boolean;
+    /** Whether this visitor granted advertising storage on this site. */
+    advertising: boolean;
+}
+export interface AnalyticsEventOptions {
+    /**
+     * Address only the measurement destinations of the resident tag, not any
+     * advertising destination sharing its library. Set for events that no
+     * advertising report reads, such as Core Web Vitals.
+     */
+    measurementOnly?: boolean;
+}
+/** A vendor's adapter. */
+export interface AnalyticsProvider {
+    /**
+     * The tags a granted pageview mounts for `host`, in order; empty when the
+     * host configures none of this provider's settings, or configures them
+     * malformed. Called only once the page's consent gate has said yes.
+     */
+    mounts(host: VisitorConsentHost | null | undefined, options: AnalyticsMountOptions): readonly AnalyticsTagMount[];
+    /**
+     * Make every resident tag of this vendor agree with `grants`, and answer
+     * the ids it acted on. A page cannot unload a script, so a withdrawal in
+     * the middle of a pageview has to be told to the tag that is already there.
+     */
+    applyConsent(grants: AnalyticsGrants): readonly string[];
+    /** Whether a tag of this vendor is resident and can take an event now. */
+    resident(): boolean;
+    /** Hand one event to the resident tag. Never throws. */
+    sendEvent(name: string, params: Record<string, unknown>, options?: AnalyticsEventOptions): void;
+}
+/** An adapter module, as an app's generated manifest loads it. */
+export interface AnalyticsProviderModule {
+    analyticsProvider: AnalyticsProvider;
+}
+/** One row of an app's generated `plugins.analytics.generated.ts`. */
+export interface AnalyticsProviderLoader {
+    pluginId: string;
+    load: () => Promise<AnalyticsProviderModule>;
+}
+/**
+ * Registers `pluginId`'s adapter. The same plugin registering again replaces
+ * its adapter. If a consent answer was already given in this document, the
+ * adapter is told it before anything else can reach it.
+ */
+export declare function registerAnalyticsProvider(pluginId: string, provider: AnalyticsProvider): void;
+/** The registered adapters, in registration order. A stable array. */
+export declare function analyticsProviders(): readonly AnalyticsProvider[];
+/** Hears every registration. Answers the unsubscribe. */
+export declare function subscribeAnalyticsProviders(listener: () => void): () => void;
+/**
+ * Tell every resident tag the visitor's answer, and answer the ids acted on.
+ * Advertising is clamped to analytics: a refusal withdraws both.
+ */
+export declare function applyAnalyticsConsent(grants: AnalyticsGrants): string[];
+/** Whether any registered adapter has a tag resident that can take an event. */
+export declare function analyticsTagResident(): boolean;
+/**
+ * Hand one event to every resident tag. Answers whether any took it, so a
+ * caller that may hold an event while a tag is still loading knows to.
+ */
+export declare function sendAnalyticsProviderEvent(name: string, params: Record<string, unknown>, options?: AnalyticsEventOptions): boolean;
+/**
+ * Fetch and register each adapter once per document. Idempotent and safe to
+ * call during render: it starts the fetch, never waits for it, and a loader
+ * that fails leaves that provider unregistered — the vendor's tag then never
+ * mounts, which is the outcome a failed vendor library has anyway.
+ */
+export declare function loadAnalyticsProviders(loaders: readonly AnalyticsProviderLoader[]): Promise<void>;
+/** Test seam — forgets every adapter, load and consent answer. */
+export declare function resetAnalyticsProviders(): void;

package/src/lib/app-utils/analytics-provider.js

@@ -0,0 +1,133 @@
+/**
+ * @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.
+ */ const providers = new Map();
+const listeners = new Set();
+let snapshot = [];
+let lastGrants = null;
+function publish() {
+    snapshot = [
+        ...providers.values()
+    ];
+    for (const listener of [
+        ...listeners
+    ]){
+        try {
+            listener();
+        } catch (unused) {
+        // One listener cannot stop the others hearing about the provider.
+        }
+    }
+}
+/**
+ * Registers `pluginId`'s adapter. The same plugin registering again replaces
+ * its adapter. If a consent answer was already given in this document, the
+ * adapter is told it before anything else can reach it.
+ */ export function registerAnalyticsProvider(pluginId, provider) {
+    providers.set(pluginId, provider);
+    if (lastGrants) {
+        try {
+            provider.applyConsent(lastGrants);
+        } catch (unused) {
+        // An adapter that throws on its own consent call is one we cannot
+        // silence; the cookie sweep still stands.
+        }
+    }
+    publish();
+}
+/** The registered adapters, in registration order. A stable array. */ export function analyticsProviders() {
+    return snapshot;
+}
+/** Hears every registration. Answers the unsubscribe. */ export function subscribeAnalyticsProviders(listener) {
+    listeners.add(listener);
+    return ()=>{
+        listeners.delete(listener);
+    };
+}
+/**
+ * Tell every resident tag the visitor's answer, and answer the ids acted on.
+ * Advertising is clamped to analytics: a refusal withdraws both.
+ */ export function applyAnalyticsConsent(grants) {
+    const analytics = grants.analytics === true;
+    const clamped = {
+        analytics,
+        advertising: analytics && grants.advertising === true
+    };
+    lastGrants = clamped;
+    const ids = [];
+    for (const provider of snapshot){
+        try {
+            ids.push(...provider.applyConsent(clamped));
+        } catch (unused) {
+        // See `registerAnalyticsProvider`.
+        }
+    }
+    return ids;
+}
+/** Whether any registered adapter has a tag resident that can take an event. */ export function analyticsTagResident() {
+    return snapshot.some((provider)=>{
+        try {
+            return provider.resident();
+        } catch (unused) {
+            return false;
+        }
+    });
+}
+/**
+ * Hand one event to every resident tag. Answers whether any took it, so a
+ * caller that may hold an event while a tag is still loading knows to.
+ */ export function sendAnalyticsProviderEvent(name, params, options) {
+    let sent = false;
+    for (const provider of snapshot){
+        try {
+            if (!provider.resident()) continue;
+            provider.sendEvent(name, params, options);
+            sent = true;
+        } catch (unused) {
+        // Analytics never breaks the page.
+        }
+    }
+    return sent;
+}
+const loading = new Map();
+/**
+ * Fetch and register each adapter once per document. Idempotent and safe to
+ * call during render: it starts the fetch, never waits for it, and a loader
+ * that fails leaves that provider unregistered — the vendor's tag then never
+ * mounts, which is the outcome a failed vendor library has anyway.
+ */ export function loadAnalyticsProviders(loaders) {
+    return Promise.all(loaders.map((loader)=>{
+        let pending = loading.get(loader.pluginId);
+        if (!pending) {
+            pending = loader.load().then((module)=>{
+                if (module == null ? void 0 : module.analyticsProvider) {
+                    registerAnalyticsProvider(loader.pluginId, module.analyticsProvider);
+                }
+            }).catch(()=>{
+            // No adapter, no tag — see above.
+            });
+            loading.set(loader.pluginId, pending);
+        }
+        return pending;
+    })).then(()=>undefined);
+}
+/** Test seam — forgets every adapter, load and consent answer. */ export function resetAnalyticsProviders() {
+    providers.clear();
+    loading.clear();
+    lastGrants = null;
+    publish();
+}
+
+//# sourceMappingURL=analytics-provider.js.map

package/src/lib/app-utils/analytics-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/analytics-provider.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 type { VisitorConsentHost } from './visitor-consent'\n\n/**\n * Third-party analytics tags, behind one contract (AGL-3080).\n *\n * A site can send its visitors' measurement to an analytics vendor it chose:\n * a measurement id or a tag container, saved in the site's analytics\n * settings. The platform owns everything around that tag — whether this\n * visitor may be measured at all (`visitor-consent.ts`), the consent banner,\n * the first-party pageview beacon that meters the site (`analytics-beacon.ts`,\n * which is not a tag and never goes through here) — and names no vendor. A\n * plugin's ADAPTER is what knows a vendor: what its tag looks like on the\n * page, how a resident tag is told the visitor's answer changed, and how an\n * event reaches it.\n *\n * ## Declared, then loaded where it is used\n *\n * Two questions, answered by two different mechanisms, because their readers\n * cannot wait for the same thing:\n *\n * - \"Does this site run a tag, so is there anything to ask its visitors?\" is\n *   asked synchronously, during render, by the consent gate on the published\n *   page and by the console's banner card and preview. A registry one of\n *   those had not filled yet would answer \"no tag\" — no banner, and nothing to\n *   gate — so the answer is COMPILED: the plugin declares which of the site's\n *   analytics settings it mounts a tag for (`analyticsProvider.settings` in\n *   `plugins.config.json`), and `hostConfiguresAnalyticsTag` in\n *   `visitor-consent.ts` reads that list. With no provider declared, no setting configures a tag, and a site\n *   with nothing that could mount asks its visitors nothing.\n * - Everything else — mounting the tag, telling it the answer changed,\n *   handing it an event — happens after the adapter has loaded. The adapter\n *   is a chunk of its own, reached through each app's generated\n *   `plugins.analytics.generated.ts` and fetched only by a document that uses\n *   it: a published page whose site configures a tag, and the console, whose\n *   own measurement tag the consent controls answer to. A page whose site\n *   configures none never fetches it.\n *\n * ## What an unloaded adapter means\n *\n * A tag is mounted only by its adapter, so until the adapter has loaded there\n * is no tag of its to silence or to send to, and nothing is lost by the wait:\n * events find no resident tag and drop, exactly as they do for a visitor who\n * has not granted.\n *\n * A tag this document did not mount — the console's, which its analytics SDK\n * injects — can be resident before the adapter arrives. So the last answer\n * {@link applyAnalyticsConsent} was given is kept, and an adapter that\n * registers later is handed it at once: a withdrawal made in that window\n * reaches the tag the moment something can speak to it.\n */\n\n/**\n * What a provider declares about itself, compiled from `plugins.config.json`.\n * `settings` are keys of the site's `analytics` settings; each is validated\n * by the pattern `ANALYTICS_SETTING_PATTERNS` in `visitor-consent.ts` holds\n * for it.\n */\nexport interface AnalyticsProviderDeclaration {\n  /** The plugin that provides the adapter. */\n  pluginId: string\n  /** The analytics settings this provider mounts a tag for. */\n  settings: readonly string[]\n}\n\n/** The visitor's answer, in the platform's two categories. */\nexport interface AnalyticsGrants {\n  analytics: boolean\n  advertising: boolean\n}\n\n/**\n * One tag on a published page: an inline boot that runs first, then the\n * vendor's library. The page renders the pair in order, under the consent\n * gate and with the request's nonce, as `${id}-init` and `${id}-src`.\n *\n * Both strings land in the document. `boot` is inline script, so an adapter\n * builds it from constants and format-checked ids only.\n */\nexport interface AnalyticsTagMount {\n  /** Element id prefix. Stable: specs and the CSP report read it. */\n  id: string\n  /** Inline script that runs before the library. */\n  boot: string\n  /** The library URL. */\n  src: string\n  /**\n   * A marker for the library this pair loads, for an advertising vendor that\n   * rides the same library instead of fetching it again (`sharesLibrary` in\n   * `advertising-tags.ts`).\n   */\n  library?: string\n}\n\n/** What the page tells an adapter about the pageview it mounts tags for. */\nexport interface AnalyticsMountOptions {\n  /**\n   * Whether the site runs the platform's consent machinery. When it does, the\n   * tag is told the visitor's answer before it measures anything; when the\n   * host runs a consent solution of its own, that solution tells it.\n   */\n  consentRequired: boolean\n  /** Whether this visitor granted advertising storage on this site. */\n  advertising: boolean\n}\n\nexport interface AnalyticsEventOptions {\n  /**\n   * Address only the measurement destinations of the resident tag, not any\n   * advertising destination sharing its library. Set for events that no\n   * advertising report reads, such as Core Web Vitals.\n   */\n  measurementOnly?: boolean\n}\n\n/** A vendor's adapter. */\nexport interface AnalyticsProvider {\n  /**\n   * The tags a granted pageview mounts for `host`, in order; empty when the\n   * host configures none of this provider's settings, or configures them\n   * malformed. Called only once the page's consent gate has said yes.\n   */\n  mounts(\n    host: VisitorConsentHost | null | undefined,\n    options: AnalyticsMountOptions,\n  ): readonly AnalyticsTagMount[]\n  /**\n   * Make every resident tag of this vendor agree with `grants`, and answer\n   * the ids it acted on. A page cannot unload a script, so a withdrawal in\n   * the middle of a pageview has to be told to the tag that is already there.\n   */\n  applyConsent(grants: AnalyticsGrants): readonly string[]\n  /** Whether a tag of this vendor is resident and can take an event now. */\n  resident(): boolean\n  /** Hand one event to the resident tag. Never throws. */\n  sendEvent(\n    name: string,\n    params: Record<string, unknown>,\n    options?: AnalyticsEventOptions,\n  ): void\n}\n\n/** An adapter module, as an app's generated manifest loads it. */\nexport interface AnalyticsProviderModule {\n  analyticsProvider: AnalyticsProvider\n}\n\n/** One row of an app's generated `plugins.analytics.generated.ts`. */\nexport interface AnalyticsProviderLoader {\n  pluginId: string\n  load: () => Promise<AnalyticsProviderModule>\n}\n\nconst providers = new Map<string, AnalyticsProvider>()\nconst listeners = new Set<() => void>()\nlet snapshot: readonly AnalyticsProvider[] = []\nlet lastGrants: AnalyticsGrants | null = null\n\nfunction publish(): void {\n  snapshot = [...providers.values()]\n  for (const listener of [...listeners]) {\n    try {\n      listener()\n    } catch {\n      // One listener cannot stop the others hearing about the provider.\n    }\n  }\n}\n\n/**\n * Registers `pluginId`'s adapter. The same plugin registering again replaces\n * its adapter. If a consent answer was already given in this document, the\n * adapter is told it before anything else can reach it.\n */\nexport function registerAnalyticsProvider(\n  pluginId: string,\n  provider: AnalyticsProvider,\n): void {\n  providers.set(pluginId, provider)\n  if (lastGrants) {\n    try {\n      provider.applyConsent(lastGrants)\n    } catch {\n      // An adapter that throws on its own consent call is one we cannot\n      // silence; the cookie sweep still stands.\n    }\n  }\n  publish()\n}\n\n/** The registered adapters, in registration order. A stable array. */\nexport function analyticsProviders(): readonly AnalyticsProvider[] {\n  return snapshot\n}\n\n/** Hears every registration. Answers the unsubscribe. */\nexport function subscribeAnalyticsProviders(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n\n/**\n * Tell every resident tag the visitor's answer, and answer the ids acted on.\n * Advertising is clamped to analytics: a refusal withdraws both.\n */\nexport function applyAnalyticsConsent(grants: AnalyticsGrants): string[] {\n  const analytics = grants.analytics === true\n  const clamped: AnalyticsGrants = {\n    analytics,\n    advertising: analytics && grants.advertising === true,\n  }\n  lastGrants = clamped\n  const ids: string[] = []\n  for (const provider of snapshot) {\n    try {\n      ids.push(...provider.applyConsent(clamped))\n    } catch {\n      // See `registerAnalyticsProvider`.\n    }\n  }\n  return ids\n}\n\n/** Whether any registered adapter has a tag resident that can take an event. */\nexport function analyticsTagResident(): boolean {\n  return snapshot.some((provider) => {\n    try {\n      return provider.resident()\n    } catch {\n      return false\n    }\n  })\n}\n\n/**\n * Hand one event to every resident tag. Answers whether any took it, so a\n * caller that may hold an event while a tag is still loading knows to.\n */\nexport function sendAnalyticsProviderEvent(\n  name: string,\n  params: Record<string, unknown>,\n  options?: AnalyticsEventOptions,\n): boolean {\n  let sent = false\n  for (const provider of snapshot) {\n    try {\n      if (!provider.resident()) continue\n      provider.sendEvent(name, params, options)\n      sent = true\n    } catch {\n      // Analytics never breaks the page.\n    }\n  }\n  return sent\n}\n\nconst loading = new Map<string, Promise<void>>()\n\n/**\n * Fetch and register each adapter once per document. Idempotent and safe to\n * call during render: it starts the fetch, never waits for it, and a loader\n * that fails leaves that provider unregistered — the vendor's tag then never\n * mounts, which is the outcome a failed vendor library has anyway.\n */\nexport function loadAnalyticsProviders(\n  loaders: readonly AnalyticsProviderLoader[],\n): Promise<void> {\n  return Promise.all(\n    loaders.map((loader) => {\n      let pending = loading.get(loader.pluginId)\n      if (!pending) {\n        pending = loader\n          .load()\n          .then((module) => {\n            if (module?.analyticsProvider) {\n              registerAnalyticsProvider(loader.pluginId, module.analyticsProvider)\n            }\n          })\n          .catch(() => {\n            // No adapter, no tag — see above.\n          })\n        loading.set(loader.pluginId, pending)\n      }\n      return pending\n    }),\n  ).then((): void => undefined)\n}\n\n/** Test seam — forgets every adapter, load and consent answer. */\nexport function resetAnalyticsProviders(): void {\n  providers.clear()\n  loading.clear()\n  lastGrants = null\n  publish()\n}\n"],"names":["providers","Map","listeners","Set","snapshot","lastGrants","publish","values","listener","registerAnalyticsProvider","pluginId","provider","set","applyConsent","analyticsProviders","subscribeAnalyticsProviders","add","delete","applyAnalyticsConsent","grants","analytics","clamped","advertising","ids","push","analyticsTagResident","some","resident","sendAnalyticsProviderEvent","name","params","options","sent","sendEvent","loading","loadAnalyticsProviders","loaders","Promise","all","map","loader","pending","get","load","then","module","analyticsProvider","catch","undefined","resetAnalyticsProviders","clear"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GA0JD,MAAMA,YAAY,IAAIC;AACtB,MAAMC,YAAY,IAAIC;AACtB,IAAIC,WAAyC,EAAE;AAC/C,IAAIC,aAAqC;AAEzC,SAASC;IACPF,WAAW;WAAIJ,UAAUO,MAAM;KAAG;IAClC,KAAK,MAAMC,YAAY;WAAIN;KAAU,CAAE;QACrC,IAAI;YACFM;QACF,EAAE,eAAM;QACN,kEAAkE;QACpE;IACF;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASC,0BACdC,QAAgB,EAChBC,QAA2B;IAE3BX,UAAUY,GAAG,CAACF,UAAUC;IACxB,IAAIN,YAAY;QACd,IAAI;YACFM,SAASE,YAAY,CAACR;QACxB,EAAE,eAAM;QACN,kEAAkE;QAClE,0CAA0C;QAC5C;IACF;IACAC;AACF;AAEA,oEAAoE,GACpE,OAAO,SAASQ;IACd,OAAOV;AACT;AAEA,uDAAuD,GACvD,OAAO,SAASW,4BAA4BP,QAAoB;IAC9DN,UAAUc,GAAG,CAACR;IACd,OAAO;QACLN,UAAUe,MAAM,CAACT;IACnB;AACF;AAEA;;;CAGC,GACD,OAAO,SAASU,sBAAsBC,MAAuB;IAC3D,MAAMC,YAAYD,OAAOC,SAAS,KAAK;IACvC,MAAMC,UAA2B;QAC/BD;QACAE,aAAaF,aAAaD,OAAOG,WAAW,KAAK;IACnD;IACAjB,aAAagB;IACb,MAAME,MAAgB,EAAE;IACxB,KAAK,MAAMZ,YAAYP,SAAU;QAC/B,IAAI;YACFmB,IAAIC,IAAI,IAAIb,SAASE,YAAY,CAACQ;QACpC,EAAE,eAAM;QACN,mCAAmC;QACrC;IACF;IACA,OAAOE;AACT;AAEA,8EAA8E,GAC9E,OAAO,SAASE;IACd,OAAOrB,SAASsB,IAAI,CAAC,CAACf;QACpB,IAAI;YACF,OAAOA,SAASgB,QAAQ;QAC1B,EAAE,eAAM;YACN,OAAO;QACT;IACF;AACF;AAEA;;;CAGC,GACD,OAAO,SAASC,2BACdC,IAAY,EACZC,MAA+B,EAC/BC,OAA+B;IAE/B,IAAIC,OAAO;IACX,KAAK,MAAMrB,YAAYP,SAAU;QAC/B,IAAI;YACF,IAAI,CAACO,SAASgB,QAAQ,IAAI;YAC1BhB,SAASsB,SAAS,CAACJ,MAAMC,QAAQC;YACjCC,OAAO;QACT,EAAE,eAAM;QACN,mCAAmC;QACrC;IACF;IACA,OAAOA;AACT;AAEA,MAAME,UAAU,IAAIjC;AAEpB;;;;;CAKC,GACD,OAAO,SAASkC,uBACdC,OAA2C;IAE3C,OAAOC,QAAQC,GAAG,CAChBF,QAAQG,GAAG,CAAC,CAACC;QACX,IAAIC,UAAUP,QAAQQ,GAAG,CAACF,OAAO9B,QAAQ;QACzC,IAAI,CAAC+B,SAAS;YACZA,UAAUD,OACPG,IAAI,GACJC,IAAI,CAAC,CAACC;gBACL,IAAIA,0BAAAA,OAAQC,iBAAiB,EAAE;oBAC7BrC,0BAA0B+B,OAAO9B,QAAQ,EAAEmC,OAAOC,iBAAiB;gBACrE;YACF,GACCC,KAAK,CAAC;YACL,kCAAkC;YACpC;YACFb,QAAQtB,GAAG,CAAC4B,OAAO9B,QAAQ,EAAE+B;QAC/B;QACA,OAAOA;IACT,IACAG,IAAI,CAAC,IAAYI;AACrB;AAEA,gEAAgE,GAChE,OAAO,SAASC;IACdjD,UAAUkD,KAAK;IACfhB,QAAQgB,KAAK;IACb7C,aAAa;IACbC;AACF"}

package/src/lib/app-utils/api-plugins.d.ts

@@ -137,6 +137,39 @@ export interface PluginApiRouteOptions {
      * authenticates the link itself, by a signature it verifies.
      */
     recipientLink?: boolean;
+    /**
+     * The route is called by a MACHINE that proves itself with a credential
+     * the route verifies — a scheduler's shared secret, a provider's signed
+     * webhook — and names no site and no member (AGL-3080).
+     *
+     * Such a request has no subject the dispatcher could gate on before the
+     * route has verified it: a sweep spans every organization, and a webhook's
+     * workspace is inside a payload only a verified signature makes worth
+     * reading. Gated anonymously, a plugin on a partial rollout would refuse
+     * every delivery. So both dispatchers skip their per-site enablement and
+     * release gates for it, and — because a chunked sweep posts from one
+     * address, and a provider retries in bursts — their write limit and their
+     * cross-origin check (`isMachinePluginApiPath`); lockdown still applies.
+     * The flag grants nothing by itself: the route authenticates its caller,
+     * and judges the plugin's release and plan for each organization it
+     * resolves from what it verified.
+     */
+    machine?: boolean;
+    /**
+     * The route hands a workspace the records a plugin keeps for it — a
+     * data-portability export — which the workspace is owed whether or not the
+     * plugin is switched on or released for it now (AGL-3080).
+     *
+     * Exporting the people a workspace holds is an obligation, not a feature:
+     * a workspace that switched the plugin off, or a plugin paused by its
+     * kill switch, still has to be able to take its data away. So both
+     * dispatchers skip their per-site enablement and release gates for it —
+     * and nothing else: lockdown, the email-verification gate and the rate
+     * limit still apply. The flag grants nothing by itself: the route
+     * authenticates the member, and asks the plugin's release and plan itself
+     * of anything it serves beyond what the workspace is owed.
+     */
+    portability?: boolean;
     /**
      * The route OPENS A CARD PAYMENT for whoever calls it: a Checkout Session,
      * a PaymentIntent or a SetupIntent (AGL-3363).
@@ -194,6 +227,19 @@ export declare function resolvePluginApiMatch(path: string): PluginApiMatch | un
  * before their enablement and release gates (AGL-2981).
  */
 export declare function isPluginRecipientLinkRoute(path: string): boolean;
+/**
+ * Whether a request path resolves to a route registered as a
+ * {@link PluginApiRouteOptions.machine} caller's — what both dispatchers ask
+ * before their enablement and release gates, and the write limits before
+ * they count (AGL-3080).
+ */
+export declare function isPluginMachineRoute(path: string): boolean;
+/**
+ * Whether a request path resolves to a route registered as a
+ * {@link PluginApiRouteOptions.portability} export — what both dispatchers
+ * ask before their enablement and release gates (AGL-3080).
+ */
+export declare function isPluginPortabilityRoute(path: string): boolean;
 /**
  * Whether a request path resolves to a route registered with
  * {@link PluginApiRouteOptions.cardPayment} — what the tenant dispatcher

package/src/lib/app-utils/api-plugins.js

@@ -157,6 +157,25 @@ export function unregisterPluginApiRoute(path) {
     const matched = matchRegisteredApiKey(path);
     return matched ? ((_apiRouteOptions_get = apiRouteOptions.get(matched.key)) == null ? void 0 : _apiRouteOptions_get.recipientLink) === true : false;
 }
+/**
+ * Whether a request path resolves to a route registered as a
+ * {@link PluginApiRouteOptions.machine} caller's — what both dispatchers ask
+ * before their enablement and release gates, and the write limits before
+ * they count (AGL-3080).
+ */ export function isPluginMachineRoute(path) {
+    var _apiRouteOptions_get;
+    const matched = matchRegisteredApiKey(path);
+    return matched ? ((_apiRouteOptions_get = apiRouteOptions.get(matched.key)) == null ? void 0 : _apiRouteOptions_get.machine) === true : false;
+}
+/**
+ * Whether a request path resolves to a route registered as a
+ * {@link PluginApiRouteOptions.portability} export — what both dispatchers
+ * ask before their enablement and release gates (AGL-3080).
+ */ export function isPluginPortabilityRoute(path) {
+    var _apiRouteOptions_get;
+    const matched = matchRegisteredApiKey(path);
+    return matched ? ((_apiRouteOptions_get = apiRouteOptions.get(matched.key)) == null ? void 0 : _apiRouteOptions_get.portability) === true : false;
+}
 /**
  * Whether a request path resolves to a route registered with
  * {@link PluginApiRouteOptions.cardPayment} — what the tenant dispatcher

package/src/lib/app-utils/api-plugins.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/api-plugins.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 * Server half of the plugin pattern (AGL-396): the API-route registry, the\n * server counterpart to the ConsoleExtension registry. A feature plugin\n * registers request handlers here from its `/server` entry point (never its\n * client barrel, so firebase-admin and other server-only deps stay out of\n * the browser bundle). The app ships one catch-all dispatcher route per\n * Next app that resolves a request path to a registered handler — so moving\n * a feature's API into its plugin needs no new app route and keeps the same\n * URL. Reference implementation: events-calendar `events/list` (AGL-396).\n *\n * The request/response shapes are structural (not `next` types) so plugins\n * stay framework-light; `NextApiRequest`/`NextApiResponse` satisfy them, so\n * the dispatcher passes Next's objects straight through.\n */\n\nexport interface PluginApiRequest {\n  method?: string\n  query: Partial<Record<string, string | string[]>>\n  // `any` mirrors NextApiRequest.body (parsed JSON/form/text); handlers\n  // validate it themselves, as they did as Next routes.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  body: any\n  /**\n   * The unparsed request text, for handlers that verify signatures over the\n   * exact payload (Stripe/Svix webhooks registered as plugin API paths).\n   * UTF-8 re-encoding of the text is byte-identical for valid UTF-8 JSON.\n   */\n  rawBody?: string\n  headers: Partial<Record<string, string | string[]>>\n  cookies: Partial<Record<string, string>>\n  /**\n   * Node socket — the client-address fallback (`remoteAddress`).\n   *\n   * On the console's Pages Router this is the real transport peer. Behind the\n   * App Router adapter there is no socket, and `api-adapter.ts` fills it from\n   * the shared client-address reader so a handler falling back to it gets the\n   * same trusted hop rather than a caller-supplied one.\n   */\n  socket: { remoteAddress?: string }\n}\n\nexport interface PluginApiResponse {\n  status(code: number): PluginApiResponse\n  json(body: unknown): void\n  send(body: unknown): void\n  setHeader(name: string, value: string | number | readonly string[]): void\n  redirect(url: string): void\n  redirect(status: number, url: string): void\n  end(): void\n}\n\nexport type PluginApiHandler = (\n  req: PluginApiRequest,\n  res: PluginApiResponse,\n) => void | Promise<void>\n\n/**\n * A handler in the Web shape (AGL-2939): the dispatcher's own `Request`\n * in, a `Response` out — with a streamed body when the door streams, as\n * the assistant's chat and a job's event feed do. `params` carries the\n * dispatcher's path segments and any `:name` segment the registered path\n * declared.\n */\nexport type PluginWebApiHandler = (\n  request: Request,\n  context: { params: Record<string, string | string[]> },\n) => Response | Promise<Response>\n\n/** What a route registers: the (req, res) shape, or a Web handler. */\nexport type PluginApiRoute = PluginApiHandler | { web: PluginWebApiHandler }\n\n/** A registered route matched to a request path, with its `:name` segments filled. */\nexport interface PluginApiMatch {\n  route: PluginApiRoute\n  params: Record<string, string>\n}\n\n/**\n * Who a request is FOR, as far as the dispatchers' release gate is concerned\n * (AGL-2978).\n *\n * The gate buckets a rollout and reads per-org overrides on an org id, and a\n * dispatcher learns that id from the site a request names (`hostId`). Two\n * kinds of request name no site and still belong to one organization:\n *\n * - a request to an ORGANIZATION-level surface (`ConsoleExtension.orgNavItems`,\n *   AGL-2974), which names its org rather than a site;\n * - a request that arrives with no bearer token by design — a provider's\n *   OAuth redirect back to the platform, which carries only what the platform\n *   signed into it.\n *\n * Without a subject the gate treats both as anonymous, so a plugin released to\n * one organization by override refused that organization's own requests, and\n * a staff member previewing a dark plugin could not complete a redirect their\n * own session had started.\n */\nexport interface PluginApiRequestSubject {\n  /** The organization: the rollout bucket and the override key. */\n  orgId: string | null\n  /**\n   * The account the request acts for, read ONLY when the request carries no\n   * bearer token — a token speaks for itself. A route may name one only when\n   * it verified a signature binding the uid to the request, because the gate\n   * lets a staff account named here preview a released-off plugin.\n   */\n  uid?: string | null\n}\n\n/** Reads a request's subject; answers `null` when the request names none. */\nexport type PluginApiSubjectResolver = (\n  request: Request,\n) => PluginApiRequestSubject | null | Promise<PluginApiRequestSubject | null>\n\n/** What a registration may say about its route beyond the handler. */\nexport interface PluginApiRouteOptions {\n  /**\n   * How a request to this route names its subject when it names no site.\n   * Consulted by both dispatchers before their release gate, and only for a\n   * request with no `hostId`: a named site always decides the org.\n   */\n  subject?: PluginApiSubjectResolver\n  /**\n   * The route answers a link the platform MAILED to somebody — an\n   * unsubscribe in a message's `List-Unsubscribe` header — rather than a door\n   * a member uses (AGL-2981).\n   *\n   * Such a link has to keep working whether or not its plugin is released,\n   * or switched on, for the workspace NOW. A recipient's way out does not\n   * close when a rollout is paused or a workspace turns the plugin off:\n   * CAN-SPAM holds an opt-out open for thirty days after the send, and an\n   * unsubscribe that 404s the day a kill switch is flipped is one nobody can\n   * use. So both dispatchers skip their per-site enablement and release\n   * gates for it — and nothing else: lockdown and the rate limit still\n   * apply. The flag says nothing about who may act, so the route\n   * authenticates the link itself, by a signature it verifies.\n   */\n  recipientLink?: boolean\n  /**\n   * The route OPENS A CARD PAYMENT for whoever calls it: a Checkout Session,\n   * a PaymentIntent or a SetupIntent (AGL-3363).\n   *\n   * The tenant dispatcher holds such a route to the card-testing counters\n   * (`card-payment-velocity.ts`) on top of its ordinary write limit, so a\n   * plugin's payment door is covered by declaring itself here rather than by\n   * carrying a limiter of its own. A console door (a signed-in merchant's\n   * POS or draft order) does not declare it: a register ringing up a queue\n   * is not a card tester. The 3-D Secure sweep\n   * (`card-payments-request-3ds.spec.ts`) classifies every file that creates\n   * a payment, so a new visitor door cannot skip the declaration.\n   */\n  cardPayment?: boolean\n}\n\n/** Leading/trailing slashes stripped so '/events/list' and 'events/list' key alike. */\nfunction normalizeApiPath(path: string): string {\n  return path.replace(/^\\/+|\\/+$/g, '')\n}\n\nconst apiRoutes = new Map<string, PluginApiRoute>()\nconst apiRouteOwners = new Map<string, string>()\nconst apiRouteOptions = new Map<string, PluginApiRouteOptions>()\n\n/**\n * The \"currently registering plugin\" marker moved to a leaf module\n * (`registering-plugin`) so `site-page-hooks` can read it too — this file is\n * only reachable through the `/server` entry, and importing it from the shared\n * plugin-manager barrel formed a cycle (AGL-1289). Re-exported here so the\n * plugin loader's existing import keeps working unchanged.\n */\nimport { getRegisteringPluginId } from './registering-plugin'\n\nexport {\n  setRegisteringPluginId,\n  getRegisteringPluginId,\n} from './registering-plugin'\n\n/**\n * Registers a plugin API handler at a host-relative path (e.g.\n * 'events/list'), served by the app dispatcher at `/api/events/list`.\n *\n * Idempotent by path FOR ITS OWNER — re-registration by the plugin that\n * holds the path replaces the previous handler, which is what a hot reload,\n * a second surface, and a repeated init all depend on.\n *\n * A different plugin is REFUSED (AGL-2484). This map is process-global and\n * was last-writer-wins on the path alone, while Aglyn's own commission-taking\n * handlers sit at `marketplace/checkout` and `commerce/checkout` — and the\n * tenant dispatcher calls `ensureRemoteServerBundles()` after the first-party\n * loader has run, so a remote bundle registering either path was simply the\n * later writer. Getting there needs `PLUGIN_REMOTE_SERVER=enabled` (off by\n * default), realm trust and a valid signature, so this is the last of several\n * doors rather than the only one; it is also the one the registry could close\n * by itself, because it already recorded who registered what.\n *\n * Anonymous registration — no loader marker — is an IDENTITY here, not a\n * wildcard: it may replace itself and nothing else may take it.\n */\nexport function registerPluginApiRoute(\n  path: string,\n  handler: PluginApiRoute,\n  options?: PluginApiRouteOptions,\n): void {\n  const key = normalizeApiPath(path)\n  const owner = getRegisteringPluginId() ?? ANONYMOUS_OWNER\n  const incumbent = apiRouteOwners.get(key)\n  if (incumbent !== undefined && incumbent !== owner) {\n    // Loud, because the silent version of this is a payment route quietly\n    // answering from someone else's code. Refusing is the safe direction:\n    // the incumbent keeps serving.\n    console.error(\n      `[plugins] refused API route \"${key}\" to \"${owner}\": already ` +\n        `registered by \"${incumbent}\"`,\n    )\n    return\n  }\n  apiRoutes.set(key, handler)\n  apiRouteOwners.set(key, owner)\n  // Replaced with the handler, never merged: a re-registration that drops its\n  // subject resolver must not keep answering with the previous one.\n  if (options) apiRouteOptions.set(key, options)\n  else apiRouteOptions.delete(key)\n}\n\n/** The marker for a registration made outside any loader context. */\nconst ANONYMOUS_OWNER = ''\n\n/** The plugin that registered a path, for per-org enablement gating. */\nexport function pluginIdForRegisteredApiPath(path: string): string | undefined {\n  const owner = apiRouteOwners.get(normalizeApiPath(path))\n  // An anonymous registration has no plugin to gate on, and this has always\n  // answered `undefined` for one — the sentinel must not leak out as an id.\n  return owner === undefined || owner === ANONYMOUS_OWNER ? undefined : owner\n}\n\nexport function unregisterPluginApiRoute(path: string): void {\n  const key = normalizeApiPath(path)\n  apiRoutes.delete(key)\n  // Release the CLAIM too, or the refusal above outlives the route and the\n  // path can never be re-registered for the life of the process.\n  apiRouteOwners.delete(key)\n  apiRouteOptions.delete(key)\n}\n\n/**\n * The registered key a request path resolves to, with its `:name` segments.\n *\n * An exact registration wins; otherwise a registration whose path carries\n * `:name` segments matches segment for segment. One matcher for the route and\n * for its options, so a request can never be answered by one registration and\n * gated with another's subject.\n */\nfunction matchRegisteredApiKey(\n  path: string,\n): { key: string; params: Record<string, string> } | undefined {\n  const key = normalizeApiPath(path)\n  if (apiRoutes.has(key)) return { key, params: {} }\n  const segments = key.split('/')\n  for (const registered of apiRoutes.keys()) {\n    if (!registered.includes(':')) continue\n    const pattern = registered.split('/')\n    if (pattern.length !== segments.length) continue\n    const params: Record<string, string> = {}\n    let matched = true\n    for (let index = 0; index < pattern.length; index += 1) {\n      const part = pattern[index]\n      if (part.startsWith(':') && segments[index]) {\n        params[part.slice(1)] = segments[index]\n      } else if (part !== segments[index]) {\n        matched = false\n        break\n      }\n    }\n    if (matched) return { key: registered, params }\n  }\n  return undefined\n}\n\n/**\n * The route for a request path, or undefined when nothing is registered.\n *\n * An exact registration wins; otherwise a registration whose path carries\n * `:name` segments matches segment for segment (`ai/jobs/:jobId/cancel`\n * answers `ai/jobs/abc/cancel`), and the named segments come back as\n * `params`. Patterns are tried in registration order and a static segment\n * beats a named one only by being registered exactly.\n */\nexport function resolvePluginApiMatch(path: string): PluginApiMatch | undefined {\n  const matched = matchRegisteredApiKey(path)\n  if (!matched) return undefined\n  const route = apiRoutes.get(matched.key)\n  return route ? { route, params: matched.params } : undefined\n}\n\n/**\n * Whether a request path resolves to a route registered as a\n * {@link PluginApiRouteOptions.recipientLink} — what both dispatchers ask\n * before their enablement and release gates (AGL-2981).\n */\nexport function isPluginRecipientLinkRoute(path: string): boolean {\n  const matched = matchRegisteredApiKey(path)\n  return matched ? apiRouteOptions.get(matched.key)?.recipientLink === true : false\n}\n\n/**\n * Whether a request path resolves to a route registered with\n * {@link PluginApiRouteOptions.cardPayment} — what the tenant dispatcher\n * asks before its card-testing counters (AGL-3363).\n */\nexport function isPluginCardPaymentRoute(path: string): boolean {\n  const matched = matchRegisteredApiKey(path)\n  return matched ? apiRouteOptions.get(matched.key)?.cardPayment === true : false\n}\n\n/** An id a subject may carry: a non-empty path segment, not a path. */\nconst SUBJECT_ID = /^[^/\\s]{1,128}$/\n\nconst subjectId = (value: unknown): string | null =>\n  typeof value === 'string' && SUBJECT_ID.test(value) ? value : null\n\n/**\n * The subject a request to a registered route names, or `null` (AGL-2978).\n *\n * `null` when the route declared no resolver, when the resolver answered\n * nothing, and when it THREW: a resolver that cannot read its request has\n * named no subject, and the gate then treats the request as anonymous — the\n * conservative direction. The resolver reads a clone, so the handler still\n * receives the untouched body. Ids are held to a plain path segment, so a\n * resolver cannot hand the gate a path to read overrides from.\n */\nexport async function resolvePluginApiRequestSubject(\n  path: string,\n  request: Request,\n): Promise<PluginApiRequestSubject | null> {\n  const matched = matchRegisteredApiKey(path)\n  const resolve = matched ? apiRouteOptions.get(matched.key)?.subject : undefined\n  if (!resolve) return null\n  try {\n    const subject = await resolve(request.clone())\n    if (!subject) return null\n    const orgId = subjectId(subject.orgId)\n    const uid = subjectId(subject.uid)\n    if (!orgId && !uid) return null\n    return { orgId, ...(uid ? { uid } : {}) }\n  } catch {\n    return null\n  }\n}\n\n/**\n * The legacy (node-style) handler at a request path, or undefined when\n * nothing is registered there or the route is a web handler — a web route\n * is reached through `resolvePluginApiMatch` and `runPluginApiMatch`, since\n * it takes the `Request` and the filled `:name` segments, not a `req`/`res`\n * pair.\n */\nexport function resolvePluginApiRoute(path: string): PluginApiHandler | undefined {\n  const route = resolvePluginApiMatch(path)?.route\n  return typeof route === 'function' ? route : undefined\n}\n\n/**\n * Runs a matched route against the dispatcher's request: a Web handler is\n * called as it is, and a (req, res) handler goes through the adapter the\n * caller supplies — the adapter lives on the `/server` entry, which this\n * module may not import.\n */\nexport async function runPluginApiMatch(\n  match: PluginApiMatch,\n  request: Request,\n  params: Record<string, string | string[]>,\n  runLegacy: (\n    handler: PluginApiHandler,\n    request: Request,\n    params: Record<string, string | string[]>,\n  ) => Promise<Response>,\n): Promise<Response> {\n  const merged = { ...params, ...match.params }\n  const route = match.route as { web?: PluginWebApiHandler }\n  if (typeof route === 'object' && route !== null && typeof route.web === 'function') {\n    return route.web(request, { params: merged })\n  }\n  return runLegacy(match.route as PluginApiHandler, request, merged)\n}\n\n/** Registered paths, for diagnostics. */\nexport function listPluginApiRoutes(): string[] {\n  return Array.from(apiRoutes.keys())\n}\n"],"names":["normalizeApiPath","path","replace","apiRoutes","Map","apiRouteOwners","apiRouteOptions","getRegisteringPluginId","setRegisteringPluginId","registerPluginApiRoute","handler","options","key","owner","ANONYMOUS_OWNER","incumbent","get","undefined","console","error","set","delete","pluginIdForRegisteredApiPath","unregisterPluginApiRoute","matchRegisteredApiKey","has","params","segments","split","registered","keys","includes","pattern","length","matched","index","part","startsWith","slice","resolvePluginApiMatch","route","isPluginRecipientLinkRoute","recipientLink","isPluginCardPaymentRoute","cardPayment","SUBJECT_ID","subjectId","value","test","resolvePluginApiRequestSubject","request","resolve","subject","clone","orgId","uid","resolvePluginApiRoute","runPluginApiMatch","match","runLegacy","merged","web","listPluginApiRoutes","Array","from"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/api-plugins.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 * Server half of the plugin pattern (AGL-396): the API-route registry, the\n * server counterpart to the ConsoleExtension registry. A feature plugin\n * registers request handlers here from its `/server` entry point (never its\n * client barrel, so firebase-admin and other server-only deps stay out of\n * the browser bundle). The app ships one catch-all dispatcher route per\n * Next app that resolves a request path to a registered handler — so moving\n * a feature's API into its plugin needs no new app route and keeps the same\n * URL. Reference implementation: events-calendar `events/list` (AGL-396).\n *\n * The request/response shapes are structural (not `next` types) so plugins\n * stay framework-light; `NextApiRequest`/`NextApiResponse` satisfy them, so\n * the dispatcher passes Next's objects straight through.\n */\n\nexport interface PluginApiRequest {\n  method?: string\n  query: Partial<Record<string, string | string[]>>\n  // `any` mirrors NextApiRequest.body (parsed JSON/form/text); handlers\n  // validate it themselves, as they did as Next routes.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  body: any\n  /**\n   * The unparsed request text, for handlers that verify signatures over the\n   * exact payload (Stripe/Svix webhooks registered as plugin API paths).\n   * UTF-8 re-encoding of the text is byte-identical for valid UTF-8 JSON.\n   */\n  rawBody?: string\n  headers: Partial<Record<string, string | string[]>>\n  cookies: Partial<Record<string, string>>\n  /**\n   * Node socket — the client-address fallback (`remoteAddress`).\n   *\n   * On the console's Pages Router this is the real transport peer. Behind the\n   * App Router adapter there is no socket, and `api-adapter.ts` fills it from\n   * the shared client-address reader so a handler falling back to it gets the\n   * same trusted hop rather than a caller-supplied one.\n   */\n  socket: { remoteAddress?: string }\n}\n\nexport interface PluginApiResponse {\n  status(code: number): PluginApiResponse\n  json(body: unknown): void\n  send(body: unknown): void\n  setHeader(name: string, value: string | number | readonly string[]): void\n  redirect(url: string): void\n  redirect(status: number, url: string): void\n  end(): void\n}\n\nexport type PluginApiHandler = (\n  req: PluginApiRequest,\n  res: PluginApiResponse,\n) => void | Promise<void>\n\n/**\n * A handler in the Web shape (AGL-2939): the dispatcher's own `Request`\n * in, a `Response` out — with a streamed body when the door streams, as\n * the assistant's chat and a job's event feed do. `params` carries the\n * dispatcher's path segments and any `:name` segment the registered path\n * declared.\n */\nexport type PluginWebApiHandler = (\n  request: Request,\n  context: { params: Record<string, string | string[]> },\n) => Response | Promise<Response>\n\n/** What a route registers: the (req, res) shape, or a Web handler. */\nexport type PluginApiRoute = PluginApiHandler | { web: PluginWebApiHandler }\n\n/** A registered route matched to a request path, with its `:name` segments filled. */\nexport interface PluginApiMatch {\n  route: PluginApiRoute\n  params: Record<string, string>\n}\n\n/**\n * Who a request is FOR, as far as the dispatchers' release gate is concerned\n * (AGL-2978).\n *\n * The gate buckets a rollout and reads per-org overrides on an org id, and a\n * dispatcher learns that id from the site a request names (`hostId`). Two\n * kinds of request name no site and still belong to one organization:\n *\n * - a request to an ORGANIZATION-level surface (`ConsoleExtension.orgNavItems`,\n *   AGL-2974), which names its org rather than a site;\n * - a request that arrives with no bearer token by design — a provider's\n *   OAuth redirect back to the platform, which carries only what the platform\n *   signed into it.\n *\n * Without a subject the gate treats both as anonymous, so a plugin released to\n * one organization by override refused that organization's own requests, and\n * a staff member previewing a dark plugin could not complete a redirect their\n * own session had started.\n */\nexport interface PluginApiRequestSubject {\n  /** The organization: the rollout bucket and the override key. */\n  orgId: string | null\n  /**\n   * The account the request acts for, read ONLY when the request carries no\n   * bearer token — a token speaks for itself. A route may name one only when\n   * it verified a signature binding the uid to the request, because the gate\n   * lets a staff account named here preview a released-off plugin.\n   */\n  uid?: string | null\n}\n\n/** Reads a request's subject; answers `null` when the request names none. */\nexport type PluginApiSubjectResolver = (\n  request: Request,\n) => PluginApiRequestSubject | null | Promise<PluginApiRequestSubject | null>\n\n/** What a registration may say about its route beyond the handler. */\nexport interface PluginApiRouteOptions {\n  /**\n   * How a request to this route names its subject when it names no site.\n   * Consulted by both dispatchers before their release gate, and only for a\n   * request with no `hostId`: a named site always decides the org.\n   */\n  subject?: PluginApiSubjectResolver\n  /**\n   * The route answers a link the platform MAILED to somebody — an\n   * unsubscribe in a message's `List-Unsubscribe` header — rather than a door\n   * a member uses (AGL-2981).\n   *\n   * Such a link has to keep working whether or not its plugin is released,\n   * or switched on, for the workspace NOW. A recipient's way out does not\n   * close when a rollout is paused or a workspace turns the plugin off:\n   * CAN-SPAM holds an opt-out open for thirty days after the send, and an\n   * unsubscribe that 404s the day a kill switch is flipped is one nobody can\n   * use. So both dispatchers skip their per-site enablement and release\n   * gates for it — and nothing else: lockdown and the rate limit still\n   * apply. The flag says nothing about who may act, so the route\n   * authenticates the link itself, by a signature it verifies.\n   */\n  recipientLink?: boolean\n  /**\n   * The route is called by a MACHINE that proves itself with a credential\n   * the route verifies — a scheduler's shared secret, a provider's signed\n   * webhook — and names no site and no member (AGL-3080).\n   *\n   * Such a request has no subject the dispatcher could gate on before the\n   * route has verified it: a sweep spans every organization, and a webhook's\n   * workspace is inside a payload only a verified signature makes worth\n   * reading. Gated anonymously, a plugin on a partial rollout would refuse\n   * every delivery. So both dispatchers skip their per-site enablement and\n   * release gates for it, and — because a chunked sweep posts from one\n   * address, and a provider retries in bursts — their write limit and their\n   * cross-origin check (`isMachinePluginApiPath`); lockdown still applies.\n   * The flag grants nothing by itself: the route authenticates its caller,\n   * and judges the plugin's release and plan for each organization it\n   * resolves from what it verified.\n   */\n  machine?: boolean\n  /**\n   * The route hands a workspace the records a plugin keeps for it — a\n   * data-portability export — which the workspace is owed whether or not the\n   * plugin is switched on or released for it now (AGL-3080).\n   *\n   * Exporting the people a workspace holds is an obligation, not a feature:\n   * a workspace that switched the plugin off, or a plugin paused by its\n   * kill switch, still has to be able to take its data away. So both\n   * dispatchers skip their per-site enablement and release gates for it —\n   * and nothing else: lockdown, the email-verification gate and the rate\n   * limit still apply. The flag grants nothing by itself: the route\n   * authenticates the member, and asks the plugin's release and plan itself\n   * of anything it serves beyond what the workspace is owed.\n   */\n  portability?: boolean\n  /**\n   * The route OPENS A CARD PAYMENT for whoever calls it: a Checkout Session,\n   * a PaymentIntent or a SetupIntent (AGL-3363).\n   *\n   * The tenant dispatcher holds such a route to the card-testing counters\n   * (`card-payment-velocity.ts`) on top of its ordinary write limit, so a\n   * plugin's payment door is covered by declaring itself here rather than by\n   * carrying a limiter of its own. A console door (a signed-in merchant's\n   * POS or draft order) does not declare it: a register ringing up a queue\n   * is not a card tester. The 3-D Secure sweep\n   * (`card-payments-request-3ds.spec.ts`) classifies every file that creates\n   * a payment, so a new visitor door cannot skip the declaration.\n   */\n  cardPayment?: boolean\n}\n\n/** Leading/trailing slashes stripped so '/events/list' and 'events/list' key alike. */\nfunction normalizeApiPath(path: string): string {\n  return path.replace(/^\\/+|\\/+$/g, '')\n}\n\nconst apiRoutes = new Map<string, PluginApiRoute>()\nconst apiRouteOwners = new Map<string, string>()\nconst apiRouteOptions = new Map<string, PluginApiRouteOptions>()\n\n/**\n * The \"currently registering plugin\" marker moved to a leaf module\n * (`registering-plugin`) so `site-page-hooks` can read it too — this file is\n * only reachable through the `/server` entry, and importing it from the shared\n * plugin-manager barrel formed a cycle (AGL-1289). Re-exported here so the\n * plugin loader's existing import keeps working unchanged.\n */\nimport { getRegisteringPluginId } from './registering-plugin'\n\nexport {\n  setRegisteringPluginId,\n  getRegisteringPluginId,\n} from './registering-plugin'\n\n/**\n * Registers a plugin API handler at a host-relative path (e.g.\n * 'events/list'), served by the app dispatcher at `/api/events/list`.\n *\n * Idempotent by path FOR ITS OWNER — re-registration by the plugin that\n * holds the path replaces the previous handler, which is what a hot reload,\n * a second surface, and a repeated init all depend on.\n *\n * A different plugin is REFUSED (AGL-2484). This map is process-global and\n * was last-writer-wins on the path alone, while Aglyn's own commission-taking\n * handlers sit at `marketplace/checkout` and `commerce/checkout` — and the\n * tenant dispatcher calls `ensureRemoteServerBundles()` after the first-party\n * loader has run, so a remote bundle registering either path was simply the\n * later writer. Getting there needs `PLUGIN_REMOTE_SERVER=enabled` (off by\n * default), realm trust and a valid signature, so this is the last of several\n * doors rather than the only one; it is also the one the registry could close\n * by itself, because it already recorded who registered what.\n *\n * Anonymous registration — no loader marker — is an IDENTITY here, not a\n * wildcard: it may replace itself and nothing else may take it.\n */\nexport function registerPluginApiRoute(\n  path: string,\n  handler: PluginApiRoute,\n  options?: PluginApiRouteOptions,\n): void {\n  const key = normalizeApiPath(path)\n  const owner = getRegisteringPluginId() ?? ANONYMOUS_OWNER\n  const incumbent = apiRouteOwners.get(key)\n  if (incumbent !== undefined && incumbent !== owner) {\n    // Loud, because the silent version of this is a payment route quietly\n    // answering from someone else's code. Refusing is the safe direction:\n    // the incumbent keeps serving.\n    console.error(\n      `[plugins] refused API route \"${key}\" to \"${owner}\": already ` +\n        `registered by \"${incumbent}\"`,\n    )\n    return\n  }\n  apiRoutes.set(key, handler)\n  apiRouteOwners.set(key, owner)\n  // Replaced with the handler, never merged: a re-registration that drops its\n  // subject resolver must not keep answering with the previous one.\n  if (options) apiRouteOptions.set(key, options)\n  else apiRouteOptions.delete(key)\n}\n\n/** The marker for a registration made outside any loader context. */\nconst ANONYMOUS_OWNER = ''\n\n/** The plugin that registered a path, for per-org enablement gating. */\nexport function pluginIdForRegisteredApiPath(path: string): string | undefined {\n  const owner = apiRouteOwners.get(normalizeApiPath(path))\n  // An anonymous registration has no plugin to gate on, and this has always\n  // answered `undefined` for one — the sentinel must not leak out as an id.\n  return owner === undefined || owner === ANONYMOUS_OWNER ? undefined : owner\n}\n\nexport function unregisterPluginApiRoute(path: string): void {\n  const key = normalizeApiPath(path)\n  apiRoutes.delete(key)\n  // Release the CLAIM too, or the refusal above outlives the route and the\n  // path can never be re-registered for the life of the process.\n  apiRouteOwners.delete(key)\n  apiRouteOptions.delete(key)\n}\n\n/**\n * The registered key a request path resolves to, with its `:name` segments.\n *\n * An exact registration wins; otherwise a registration whose path carries\n * `:name` segments matches segment for segment. One matcher for the route and\n * for its options, so a request can never be answered by one registration and\n * gated with another's subject.\n */\nfunction matchRegisteredApiKey(\n  path: string,\n): { key: string; params: Record<string, string> } | undefined {\n  const key = normalizeApiPath(path)\n  if (apiRoutes.has(key)) return { key, params: {} }\n  const segments = key.split('/')\n  for (const registered of apiRoutes.keys()) {\n    if (!registered.includes(':')) continue\n    const pattern = registered.split('/')\n    if (pattern.length !== segments.length) continue\n    const params: Record<string, string> = {}\n    let matched = true\n    for (let index = 0; index < pattern.length; index += 1) {\n      const part = pattern[index]\n      if (part.startsWith(':') && segments[index]) {\n        params[part.slice(1)] = segments[index]\n      } else if (part !== segments[index]) {\n        matched = false\n        break\n      }\n    }\n    if (matched) return { key: registered, params }\n  }\n  return undefined\n}\n\n/**\n * The route for a request path, or undefined when nothing is registered.\n *\n * An exact registration wins; otherwise a registration whose path carries\n * `:name` segments matches segment for segment (`ai/jobs/:jobId/cancel`\n * answers `ai/jobs/abc/cancel`), and the named segments come back as\n * `params`. Patterns are tried in registration order and a static segment\n * beats a named one only by being registered exactly.\n */\nexport function resolvePluginApiMatch(path: string): PluginApiMatch | undefined {\n  const matched = matchRegisteredApiKey(path)\n  if (!matched) return undefined\n  const route = apiRoutes.get(matched.key)\n  return route ? { route, params: matched.params } : undefined\n}\n\n/**\n * Whether a request path resolves to a route registered as a\n * {@link PluginApiRouteOptions.recipientLink} — what both dispatchers ask\n * before their enablement and release gates (AGL-2981).\n */\nexport function isPluginRecipientLinkRoute(path: string): boolean {\n  const matched = matchRegisteredApiKey(path)\n  return matched ? apiRouteOptions.get(matched.key)?.recipientLink === true : false\n}\n\n/**\n * Whether a request path resolves to a route registered as a\n * {@link PluginApiRouteOptions.machine} caller's — what both dispatchers ask\n * before their enablement and release gates, and the write limits before\n * they count (AGL-3080).\n */\nexport function isPluginMachineRoute(path: string): boolean {\n  const matched = matchRegisteredApiKey(path)\n  return matched ? apiRouteOptions.get(matched.key)?.machine === true : false\n}\n\n/**\n * Whether a request path resolves to a route registered as a\n * {@link PluginApiRouteOptions.portability} export — what both dispatchers\n * ask before their enablement and release gates (AGL-3080).\n */\nexport function isPluginPortabilityRoute(path: string): boolean {\n  const matched = matchRegisteredApiKey(path)\n  return matched ? apiRouteOptions.get(matched.key)?.portability === true : false\n}\n\n/**\n * Whether a request path resolves to a route registered with\n * {@link PluginApiRouteOptions.cardPayment} — what the tenant dispatcher\n * asks before its card-testing counters (AGL-3363).\n */\nexport function isPluginCardPaymentRoute(path: string): boolean {\n  const matched = matchRegisteredApiKey(path)\n  return matched ? apiRouteOptions.get(matched.key)?.cardPayment === true : false\n}\n\n/** An id a subject may carry: a non-empty path segment, not a path. */\nconst SUBJECT_ID = /^[^/\\s]{1,128}$/\n\nconst subjectId = (value: unknown): string | null =>\n  typeof value === 'string' && SUBJECT_ID.test(value) ? value : null\n\n/**\n * The subject a request to a registered route names, or `null` (AGL-2978).\n *\n * `null` when the route declared no resolver, when the resolver answered\n * nothing, and when it THREW: a resolver that cannot read its request has\n * named no subject, and the gate then treats the request as anonymous — the\n * conservative direction. The resolver reads a clone, so the handler still\n * receives the untouched body. Ids are held to a plain path segment, so a\n * resolver cannot hand the gate a path to read overrides from.\n */\nexport async function resolvePluginApiRequestSubject(\n  path: string,\n  request: Request,\n): Promise<PluginApiRequestSubject | null> {\n  const matched = matchRegisteredApiKey(path)\n  const resolve = matched ? apiRouteOptions.get(matched.key)?.subject : undefined\n  if (!resolve) return null\n  try {\n    const subject = await resolve(request.clone())\n    if (!subject) return null\n    const orgId = subjectId(subject.orgId)\n    const uid = subjectId(subject.uid)\n    if (!orgId && !uid) return null\n    return { orgId, ...(uid ? { uid } : {}) }\n  } catch {\n    return null\n  }\n}\n\n/**\n * The legacy (node-style) handler at a request path, or undefined when\n * nothing is registered there or the route is a web handler — a web route\n * is reached through `resolvePluginApiMatch` and `runPluginApiMatch`, since\n * it takes the `Request` and the filled `:name` segments, not a `req`/`res`\n * pair.\n */\nexport function resolvePluginApiRoute(path: string): PluginApiHandler | undefined {\n  const route = resolvePluginApiMatch(path)?.route\n  return typeof route === 'function' ? route : undefined\n}\n\n/**\n * Runs a matched route against the dispatcher's request: a Web handler is\n * called as it is, and a (req, res) handler goes through the adapter the\n * caller supplies — the adapter lives on the `/server` entry, which this\n * module may not import.\n */\nexport async function runPluginApiMatch(\n  match: PluginApiMatch,\n  request: Request,\n  params: Record<string, string | string[]>,\n  runLegacy: (\n    handler: PluginApiHandler,\n    request: Request,\n    params: Record<string, string | string[]>,\n  ) => Promise<Response>,\n): Promise<Response> {\n  const merged = { ...params, ...match.params }\n  const route = match.route as { web?: PluginWebApiHandler }\n  if (typeof route === 'object' && route !== null && typeof route.web === 'function') {\n    return route.web(request, { params: merged })\n  }\n  return runLegacy(match.route as PluginApiHandler, request, merged)\n}\n\n/** Registered paths, for diagnostics. */\nexport function listPluginApiRoutes(): string[] {\n  return Array.from(apiRoutes.keys())\n}\n"],"names":["normalizeApiPath","path","replace","apiRoutes","Map","apiRouteOwners","apiRouteOptions","getRegisteringPluginId","setRegisteringPluginId","registerPluginApiRoute","handler","options","key","owner","ANONYMOUS_OWNER","incumbent","get","undefined","console","error","set","delete","pluginIdForRegisteredApiPath","unregisterPluginApiRoute","matchRegisteredApiKey","has","params","segments","split","registered","keys","includes","pattern","length","matched","index","part","startsWith","slice","resolvePluginApiMatch","route","isPluginRecipientLinkRoute","recipientLink","isPluginMachineRoute","machine","isPluginPortabilityRoute","portability","isPluginCardPaymentRoute","cardPayment","SUBJECT_ID","subjectId","value","test","resolvePluginApiRequestSubject","request","resolve","subject","clone","orgId","uid","resolvePluginApiRoute","runPluginApiMatch","match","runLegacy","merged","web","listPluginApiRoutes","Array","from"],"mappings":"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"}

package/src/lib/app-utils/{marketplace-overrides.d.ts → artifact-overrides.d.ts}

@@ -14,11 +14,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type ResolvedProvenance } from './marketplace-provenance';
+import { type ResolvedProvenance } from './artifact-provenance';
 /**
  * The override layer (AGL-1019) — own the patch, never the copy.
  *
- * Customising a marketplace artifact and updating it are only compatible if
+ * Customising an installed artifact and updating it are only compatible if
  * they are two different documents. Today they are one: you change a theme's
  * primary colour and that edits the theme, so the publisher's v2 can be taken
  * only by discarding your colour, or refused only by missing their fix.
@@ -34,10 +34,13 @@ import { type ResolvedProvenance } from './marketplace-provenance';
  * * a conflict is narrow: only where the patch touches a path the update also
  *   changed, which the marketplace plugin's three-way update plan already names.
  *
- * Pure and content-shaped, exactly like the merge module it sits next to: it
- * knows nothing about Firestore or artifact types, so one resolver serves a
- * theme, a node tree and a plugin settings map, and every rule below is
- * testable without a database.
+ * Pure and content-shaped: it knows nothing about Firestore, artifact types
+ * or who installed the artifact, so one resolver serves a theme, a node tree
+ * and a plugin settings map, and every rule below is testable without a
+ * database. The platform's rather than the installer's (AGL-3080), because the
+ * readers are: the site's theme resolution, the theme editor and its library.
+ * The three-way update plan that writes a new base under a patch is the
+ * installer's own (the marketplace's `model/artifact-merge.ts`).
  *
  * ## Which "base" a reader resolves against
  *

package/src/lib/app-utils/{marketplace-overrides.js → artifact-overrides.js}

@@ -14,11 +14,11 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * 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 { stableStringify } from "./marketplace-provenance.js";
+ */ import { stableStringify } from "./artifact-provenance.js";
 /**
  * The override layer (AGL-1019) — own the patch, never the copy.
  *
- * Customising a marketplace artifact and updating it are only compatible if
+ * Customising an installed artifact and updating it are only compatible if
  * they are two different documents. Today they are one: you change a theme's
  * primary colour and that edits the theme, so the publisher's v2 can be taken
  * only by discarding your colour, or refused only by missing their fix.
@@ -34,10 +34,13 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * * a conflict is narrow: only where the patch touches a path the update also
  *   changed, which the marketplace plugin's three-way update plan already names.
  *
- * Pure and content-shaped, exactly like the merge module it sits next to: it
- * knows nothing about Firestore or artifact types, so one resolver serves a
- * theme, a node tree and a plugin settings map, and every rule below is
- * testable without a database.
+ * Pure and content-shaped: it knows nothing about Firestore, artifact types
+ * or who installed the artifact, so one resolver serves a theme, a node tree
+ * and a plugin settings map, and every rule below is testable without a
+ * database. The platform's rather than the installer's (AGL-3080), because the
+ * readers are: the site's theme resolution, the theme editor and its library.
+ * The three-way update plan that writes a new base under a patch is the
+ * installer's own (the marketplace's `model/artifact-merge.ts`).
  *
  * ## Which "base" a reader resolves against
  *
@@ -459,4 +462,4 @@ function resolveKeyedArray(base, patch) {
     return cursor;
 }
 
-//# sourceMappingURL=marketplace-overrides.js.map
+//# sourceMappingURL=artifact-overrides.js.map