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

package/src/lib/app-utils/platform-brand.d.ts

@@ -69,6 +69,16 @@ export declare const PLATFORM_BRAND_LEGAL_NAME: string;
  * console at all.
  */
 export declare const PLATFORM_SUPPORT_URL: string;
+/**
+ * This install's console origin, with no trailing slash — what a link in a
+ * notification or an email the platform sends is built on (AGL-3080).
+ *
+ * `NEXT_PUBLIC_CONSOLE_URL`, which every self-hosted install sets; Aglyn's
+ * own console only for a build that names none. One reading for the support
+ * page above and for every scheduled sender, a plugin's included, so none of
+ * them spells the fallback again.
+ */
+export declare function platformConsoleOrigin(): string;
 /** True when this deployment still answers to Aglyn's own brand. */
 export declare const isAglynOperatedBrand: () => boolean;
 /**

package/src/lib/app-utils/platform-brand.js

@@ -110,14 +110,25 @@ var _clean4;
  * platform sends. `app.aglyn.com` is left only for a build that names no
  * console at all.
  */ export const PLATFORM_SUPPORT_URL = (()=>{
-    var _clean;
     const configured = clean(process.env.NEXT_PUBLIC_PLATFORM_SUPPORT_URL);
     if (configured) return configured;
     const operatorEmail = clean(process.env.NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL);
     if (operatorEmail) return `mailto:${operatorEmail}`;
-    const consoleOrigin = (_clean = clean(process.env.NEXT_PUBLIC_CONSOLE_URL)) == null ? void 0 : _clean.replace(/\/+$/, '');
-    return `${consoleOrigin || 'https://app.aglyn.com'}/support`;
+    return `${platformConsoleOrigin()}/support`;
 })();
+/**
+ * This install's console origin, with no trailing slash — what a link in a
+ * notification or an email the platform sends is built on (AGL-3080).
+ *
+ * `NEXT_PUBLIC_CONSOLE_URL`, which every self-hosted install sets; Aglyn's
+ * own console only for a build that names none. One reading for the support
+ * page above and for every scheduled sender, a plugin's included, so none of
+ * them spells the fallback again.
+ */ export function platformConsoleOrigin() {
+    var _clean;
+    const configured = (_clean = clean(process.env.NEXT_PUBLIC_CONSOLE_URL)) == null ? void 0 : _clean.replace(/\/+$/, '');
+    return configured || 'https://app.aglyn.com';
+}
 /** True when this deployment still answers to Aglyn's own brand. */ export const isAglynOperatedBrand = ()=>PLATFORM_BRAND_NAME === 'Aglyn';
 /**
  * Where the platform's own front door is — the marketing home, not the help

package/src/lib/app-utils/platform-brand.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-brand.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 this deployment calls itself (AGL-2153).\n *\n * the rule for the self-host path: *\"the self hosted owner should not have\n * to edit the source to update aglyn branded items urls or personal\n * identification items, should move these to env vars\"*. AGL-2016 did that for\n * the values where getting it wrong misroutes a legal notice. This is the\n * other half — the product name itself, which was a bare `'Aglyn'` literal in\n * nine places.\n *\n * ## Why one module rather than nine reads\n *\n * The literals were not merely duplicated, they were duplicated across a\n * boundary: `PLATFORM_GENERATOR_NAME` exists here AND as a hand-copied\n * constant in `apps/tenant/middleware.ts`, because the edge bundle cannot\n * import this lib. A single source they both read is what stops the copy from\n * drifting into a deployment that half-renames itself.\n *\n * ## Why a default at all, when operator-identity.ts refuses to have one\n *\n * `operator-identity.ts` sets out the rule and it is the right one: a value\n * whose wrongness is invisible to the operator and visible only off-site must\n * not be guessed. The brand is the opposite case. An operator who does not set\n * it sees \"Aglyn\" in their own browser tab on their own first page load, in\n * their own console. That is a default they can see and correct, which is a\n * default rather than a trap — the same test AGL-2022 applied to the tenant\n * apex.\n *\n * ## Why `NEXT_PUBLIC_`, and why dot notation is load-bearing\n *\n * The brand is printed to the public — that is what it is for — so\n * `NEXT_PUBLIC_` carries no disclosure risk. Next inlines `NEXT_PUBLIC_*` into\n * the browser bundle by textually substituting `process.env.NAME`; the\n * **bracket** form is never substituted and reads `undefined` in the browser\n * (AGL-2037). Every read below is dot notation on purpose.\n *\n * Build-time consequence for self-hosters: these are baked in when the image\n * is built, so they must be set *before* `docker compose build`, not merely\n * before `up`. `docs/SELF_HOSTING.md` says so.\n */\n\n/** A non-empty trimmed string, else undefined — `'   '` is a half-finished `.env`. */\nconst clean = (value: unknown): string | undefined => {\n  const text = typeof value === 'string' ? value.trim() : ''\n  return text.length ? text : undefined\n}\n\n/**\n * The product name, as shown to end users.\n *\n * This is the browser-tab affix, the PWA name, the WebAuthn relying-party name\n * the OS credential prompt displays, the `<meta name=\"generator\">` and\n * `x-powered-by` on published sites, and the platform default `productName` /\n * `fromName` every non-white-label org's surfaces resolve to.\n */\nexport const PLATFORM_BRAND_NAME =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_BRAND_NAME) ?? 'Aglyn'\n\n/**\n * The legal entity operating the software's own cloud, for copy that needs a\n * company rather than a product (`BRAND.ORG_NAME_LEGAL`).\n *\n * NOT the same thing as `operatorIdentity().name`, and the distinction matters.\n * This is a *brand* string with a visible default; that one is the identity a\n * statutory notice is addressed to and refuses to default. An operator who\n * sets only this has renamed the product, not published who they are.\n */\nexport const PLATFORM_BRAND_LEGAL_NAME =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_BRAND_LEGAL_NAME) ??\n  `${PLATFORM_BRAND_NAME} LLC`\n\n/**\n * Where a \"need help?\" line points.\n *\n * Falls through the operator's OWN support address before it falls back to\n * ours, deliberately: an operator who followed the runbook has already set\n * `NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL`, and making them discover a second\n * variable to stop pointing their customers at Aglyn's support desk — which\n * cannot help those customers with anything — is a trap dressed as a default.\n *\n * Read here rather than imported from `operator-identity.ts` so this module\n * stays dependency-free and safe to import from anywhere, including the places\n * that cannot take the operator module's weight.\n *\n * ## Why the last fallback is the CONSOLE and not the marketing site\n *\n * It was `aglyn.com/support`, which answers 404 and has never existed\n * (AGL-3262) — MEASURED against the live site, not inferred: `/support`,\n * `/help` and `/docs` all render the not-found page and none is in the\n * sitemap. A support URL that 404s is worse than none, because it is printed\n * on a receipt beside a charge the reader is already unsure about.\n *\n * `app.aglyn.com/support` is a real page (AGL-3265): it resolves the\n * workspace from the session, so a customer with one lands on its support\n * umbrella and a customer with several picks. That is the whole reason it\n * exists — it is the one support address that needs nothing interpolated\n * into it, which is exactly what this constant is.\n *\n * The console is THIS install's (AGL-3322). `/support` is a console route, so\n * every console serves its own, and `NEXT_PUBLIC_CONSOLE_URL` is required of\n * every self-hosted install — so one that configured neither variable above\n * sends its customers to its own support page rather than to ours, where they\n * have no account. The line is in the footer of every system email the\n * platform sends. `app.aglyn.com` is left only for a build that names no\n * console at all.\n */\nexport const PLATFORM_SUPPORT_URL: string = (() => {\n  const configured = clean(process.env.NEXT_PUBLIC_PLATFORM_SUPPORT_URL)\n  if (configured) return configured\n  const operatorEmail = clean(process.env.NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL)\n  if (operatorEmail) return `mailto:${operatorEmail}`\n  const consoleOrigin = clean(process.env.NEXT_PUBLIC_CONSOLE_URL)?.replace(\n    /\\/+$/,\n    '',\n  )\n  return `${consoleOrigin || 'https://app.aglyn.com'}/support`\n})()\n\n/** True when this deployment still answers to Aglyn's own brand. */\nexport const isAglynOperatedBrand = (): boolean =>\n  PLATFORM_BRAND_NAME === 'Aglyn'\n\n/**\n * Where the platform's own front door is — the marketing home, not the help\n * desk.\n *\n * ## Why this is not `PLATFORM_SUPPORT_URL`\n *\n * The \"Made with …\" badge on a published free-tier site used to link to\n * `supportUrl`, and on this deployment `supportUrl` falls through to\n * `mailto:` + the operator support address. So the one link the platform gets\n * on every free customer's site — its only organic acquisition surface —\n * opened the visitor's mail client addressed to our support desk. A visitor\n * who liked the site and clicked to find out what built it got a blank email,\n * and support got the misdirected replies.\n *\n * They are genuinely different destinations. `supportUrl` answers \"I am a\n * customer and something is wrong\"; this answers \"what is this, and can I have\n * one\". Keeping one value for both guarantees one of them is wrong.\n *\n * ## Why it is null rather than aglyn.com off-brand\n *\n * A self-hosted deployment that renamed the product but set no home URL has\n * nowhere honest to send that visitor: \"Made with Foo\" pointing at aglyn.com\n * advertises the wrong company on Foo's customers' sites. The badge already\n * renders as a plain label when it has no destination (AGL-2428), which is the\n * correct outcome — so the Aglyn default applies only while this really is the\n * Aglyn-operated brand.\n */\nexport const PLATFORM_HOME_URL: string | null =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_HOME_URL) ??\n  (isAglynOperatedBrand() ? 'https://aglyn.com' : null)\n\n/**\n * The platform's own logo MARK — the compact, square, no-wordmark form — as a\n * URL an `<img>` on a PUBLISHED SITE can load.\n *\n * Site-relative on purpose: every app that renders it serves\n * `public/_static/…` from its own origin, so one path works on\n * `{sub}.aglyn.app` and on a customer's custom domain alike without knowing\n * either. The white variant is the one that survives the badge's dark pill and\n * an org's `primaryColor` behind it.\n *\n * Null unless this is the Aglyn-operated brand, for the same reason as\n * {@link PLATFORM_HOME_URL}: a renamed deployment must not stamp our mark on\n * its customers' sites. Such an operator sets `NEXT_PUBLIC_PLATFORM_MARK_URL`\n * to their own, or gets a text-only badge.\n */\nexport const PLATFORM_MARK_URL: string | null =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_MARK_URL) ??\n  (isAglynOperatedBrand()\n    ? '/_static/images/brand/aglyn-logo-mark-white.svg'\n    : null)\n\n/** An absolute `https://` URL, else undefined — anything else has no origin in an inbox. */\nconst httpsUrl = (value: string | undefined): string | undefined => {\n  if (!value) return undefined\n  try {\n    return new URL(value).protocol === 'https:' ? value : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * The platform's logo as its own system email draws it: the header of mail\n * sent under the platform's brand (AGL-3322).\n *\n * ABSOLUTE and https, unlike {@link PLATFORM_MARK_URL}. That mark is a\n * site-relative path because every app that draws it serves the file from its\n * own origin; an inbox has no origin, so a relative path there is a\n * broken-image box. A configured value that is not an absolute `https://` URL\n * is ignored rather than handed on to fail in somebody's inbox.\n *\n * The WORDMARK rather than the square mark: a header is read at a glance, and\n * the wordmark names the sender where the mark would need the reader to\n * already know it.\n *\n * A PNG sized for the slot (AGL-3367): 396×120, three times the 132×40 the\n * header draws it at, about 15 KB, served as a static file off aglyn.com's\n * edge. The master-resolution file behind the media CDN's 60-second cache is\n * four times the bytes and makes the header the last thing in the email to\n * appear. Not an SVG: Gmail and Outlook do not draw SVG in mail, so every\n * recipient on either would get a broken-image box where the logo belongs.\n *\n * Null unless this is the Aglyn-operated brand, for the reason\n * {@link PLATFORM_HOME_URL} is: a renamed deployment must not put our logo at\n * the top of its customers' mail. Such an operator sets\n * `NEXT_PUBLIC_PLATFORM_EMAIL_LOGO_URL`, or gets its product name as the\n * header, in bold text.\n *\n * Deliberately NOT `PLATFORM_BRANDING_PROFILE.emailLogoUrl`, which stays null.\n * That field is an ORG's email logo: a white-label profile inherits it when\n * the org set none, and a send that carries one is read as an org's own mail.\n * Putting the platform's logo there would stamp it on every white-label org\n * that left the field blank.\n */\nexport const PLATFORM_EMAIL_LOGO_URL: string | null =\n  httpsUrl(clean(process.env.NEXT_PUBLIC_PLATFORM_EMAIL_LOGO_URL)) ??\n  (isAglynOperatedBrand()\n    ? 'https://aglyn.com/_static/images/brand/aglyn-email-wordmark.png'\n    : null)\n\n/**\n * The postal address printed beside {@link PLATFORM_BRAND_LEGAL_NAME} at the\n * foot of the platform's own system email (AGL-3322).\n *\n * A BRAND string, beside the legal name whose line it completes, rather than\n * a field of `operatorIdentity()`, and the difference is the default. The\n * operator identity is what a statutory notice is addressed to and refuses to\n * guess; this is a line in a footer the operator sees in their own mail and\n * can correct, and for the Aglyn-operated brand the right value is known: the\n * registered agent's address the Aglyn marketing site's email footer prints.\n *\n * Null unless this is the Aglyn-operated brand: a renamed deployment must\n * never print our address as its own. Such an operator sets\n * `NEXT_PUBLIC_PLATFORM_POSTAL_ADDRESS`, or their footer carries the legal\n * name alone. Line breaks in a configured value are folded into commas,\n * because the footer prints the address on one line.\n */\nexport const PLATFORM_POSTAL_ADDRESS: string | null =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_POSTAL_ADDRESS)\n    ?.split(/\\s*\\n\\s*/)\n    .filter(Boolean)\n    .join(', ') ??\n  (isAglynOperatedBrand()\n    ? 'c/o Northwest Registered Agent, LLC, 5900 Balcones Drive STE 100, Austin, TX 78731'\n    : null)\n\n/**\n * A branding profile with every field present — what a branded surface\n * renders. Image/color/domain fields are nullable (Aglyn's own surfaces\n * bake those in rather than carry a URL); the remaining text fields always\n * have a value so callers never string-concatenate `undefined`.\n *\n * `supportUrl` is nullable too, and it is the one field where null carries a\n * decision rather than an absence — see {@link resolveBrandingProfile}. A\n * caller must render NOTHING for it, never a placeholder and never a\n * substitute.\n */\nexport interface ResolvedBrandingProfile {\n  productName: string\n  logoUrl: string | null\n  /** The logo for dark grounds; null means {@link logoUrl} serves both. */\n  logoDarkUrl: string | null\n  faviconUrl: string | null\n  /** The favicon for a dark tab strip; null means {@link faviconUrl} serves both. */\n  faviconDarkUrl: string | null\n  primaryColor: string | null\n  supportUrl: string | null\n  /**\n   * The brand's own FRONT DOOR — where \"Made with <product>\" sends a visitor\n   * who wants to know what built the site they are looking at.\n   *\n   * Deliberately separate from {@link ResolvedBrandingProfile.supportUrl},\n   * which the badge used to borrow: a help-desk address is the wrong answer to\n   * \"what is this\", and on this deployment it resolves to a `mailto:`, so the\n   * badge opened a blank email instead of a web page.\n   *\n   * Nullable for the same reason `supportUrl` is — a brand with nowhere to\n   * send that visitor gets a plain label, never a substitute destination.\n   */\n  homeUrl: string | null\n  fromName: string\n  emailLogoUrl: string | null\n  customConsoleDomain: string | null\n}\n\n/**\n * The PLATFORM (non-white-label) brand — the fallback every surface gets when\n * an org lacks the `whiteLabel` entitlement, and the gap-filler for a partial\n * agency profile.\n *\n * It lives beside the literals it is assembled from rather than beside the\n * entitlement gate that hands it out, and that placement is load-bearing\n * rather than tidying. A published tenant page renders the attribution badge\n * from this constant and reads nothing else out of `plan-entitlements.ts`;\n * defining it there put that module's whole plan, quota and entitlement table\n * — the single largest first-party module a visitor could reach — into the\n * first load of every anonymous visitor to every customer site.\n * `plan-entitlements.ts` re-exports it, so every existing caller is unchanged.\n *\n * The name says the PLATFORM's brand rather than Aglyn's because on a\n * self-host install that assertion stops being true: which platform this is,\n * is configuration. `resolveBrandingProfile` is the single resolver EVERY\n * branded surface routes through — console chrome, published-site badge and\n * title, transactional email — and this is its fallback, so all of them get a\n * self-host brand without extending the white-label machinery at all.\n */\nexport const PLATFORM_BRANDING_PROFILE: ResolvedBrandingProfile = {\n  productName: PLATFORM_BRAND_NAME,\n  // The platform's own surfaces still bake their logo in — this is here for\n  // the surfaces that CANNOT, which is every surface rendered on somebody\n  // else's site. The free-tier attribution badge is the one that exists\n  // today, and it carried no mark at all while this was null.\n  logoUrl: PLATFORM_MARK_URL,\n  logoDarkUrl: null,\n  faviconUrl: null,\n  faviconDarkUrl: null,\n  primaryColor: null,\n  supportUrl: PLATFORM_SUPPORT_URL,\n  homeUrl: PLATFORM_HOME_URL,\n  fromName: PLATFORM_BRAND_NAME,\n  emailLogoUrl: null,\n  customConsoleDomain: null,\n}\n"],"names":["clean","httpsUrl","value","text","trim","length","undefined","PLATFORM_BRAND_NAME","process","env","NEXT_PUBLIC_PLATFORM_BRAND_NAME","PLATFORM_BRAND_LEGAL_NAME","NEXT_PUBLIC_PLATFORM_BRAND_LEGAL_NAME","PLATFORM_SUPPORT_URL","configured","NEXT_PUBLIC_PLATFORM_SUPPORT_URL","operatorEmail","NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL","consoleOrigin","NEXT_PUBLIC_CONSOLE_URL","replace","isAglynOperatedBrand","PLATFORM_HOME_URL","NEXT_PUBLIC_PLATFORM_HOME_URL","PLATFORM_MARK_URL","NEXT_PUBLIC_PLATFORM_MARK_URL","URL","protocol","PLATFORM_EMAIL_LOGO_URL","NEXT_PUBLIC_PLATFORM_EMAIL_LOGO_URL","PLATFORM_POSTAL_ADDRESS","NEXT_PUBLIC_PLATFORM_POSTAL_ADDRESS","split","filter","Boolean","join","PLATFORM_BRANDING_PROFILE","productName","logoUrl","logoDarkUrl","faviconUrl","faviconDarkUrl","primaryColor","supportUrl","homeUrl","fromName","emailLogoUrl","customConsoleDomain"],"mappings":"IAyEEA,QAYAA,SAkFAA,SAmBAA,SAiDAC;IAuBAD;AAlQF;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,oFAAoF,GACpF,MAAMA,QAAQ,CAACE;IACb,MAAMC,OAAO,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACxD,OAAOD,KAAKE,MAAM,GAAGF,OAAOG;AAC9B;AAEA;;;;;;;CAOC,GACD,OAAO,MAAMC,uBACXP,SAAAA,MAAMQ,QAAQC,GAAG,CAACC,+BAA+B,aAAjDV,SAAsD,QAAO;AAE/D;;;;;;;;CAQC,GACD,OAAO,MAAMW,6BACXX,UAAAA,MAAMQ,QAAQC,GAAG,CAACG,qCAAqC,aAAvDZ,UACA,GAAGO,oBAAoB,IAAI,CAAC,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GACD,OAAO,MAAMM,uBAA+B,AAAC,CAAA;QAKrBb;IAJtB,MAAMc,aAAad,MAAMQ,QAAQC,GAAG,CAACM,gCAAgC;IACrE,IAAID,YAAY,OAAOA;IACvB,MAAME,gBAAgBhB,MAAMQ,QAAQC,GAAG,CAACQ,kCAAkC;IAC1E,IAAID,eAAe,OAAO,CAAC,OAAO,EAAEA,eAAe;IACnD,MAAME,iBAAgBlB,SAAAA,MAAMQ,QAAQC,GAAG,CAACU,uBAAuB,sBAAzCnB,OAA4CoB,OAAO,CACvE,QACA;IAEF,OAAO,GAAGF,iBAAiB,wBAAwB,QAAQ,CAAC;AAC9D,CAAA,IAAI;AAEJ,kEAAkE,GAClE,OAAO,MAAMG,uBAAuB,IAClCd,wBAAwB,QAAO;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GACD,OAAO,MAAMe,qBACXtB,UAAAA,MAAMQ,QAAQC,GAAG,CAACc,6BAA6B,aAA/CvB,UACCqB,yBAAyB,sBAAsB,KAAK;AAEvD;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMG,qBACXxB,UAAAA,MAAMQ,QAAQC,GAAG,CAACgB,6BAA6B,aAA/CzB,UACCqB,yBACG,oDACA,KAAK;AAEX,0FAA0F,GAC1F,MAAMpB,WAAW,CAACC;IAChB,IAAI,CAACA,OAAO,OAAOI;IACnB,IAAI;QACF,OAAO,IAAIoB,IAAIxB,OAAOyB,QAAQ,KAAK,WAAWzB,QAAQI;IACxD,EAAE,eAAM;QACN,OAAOA;IACT;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,OAAO,MAAMsB,2BACX3B,YAAAA,SAASD,MAAMQ,QAAQC,GAAG,CAACoB,mCAAmC,cAA9D5B,YACCoB,yBACG,oEACA,KAAK;AAEX;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,MAAMS,mCACX9B,UAAAA,MAAMQ,QAAQC,GAAG,CAACsB,mCAAmC,sBAArD/B,QACIgC,KAAK,CAAC,YACPC,MAAM,CAACC,SACPC,IAAI,CAAC,wBACPd,yBACG,uFACA,KAAK;AAyCX;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAMe,4BAAqD;IAChEC,aAAa9B;IACb,0EAA0E;IAC1E,wEAAwE;IACxE,sEAAsE;IACtE,4DAA4D;IAC5D+B,SAASd;IACTe,aAAa;IACbC,YAAY;IACZC,gBAAgB;IAChBC,cAAc;IACdC,YAAY9B;IACZ+B,SAAStB;IACTuB,UAAUtC;IACVuC,cAAc;IACdC,qBAAqB;AACvB,EAAC"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-brand.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 this deployment calls itself (AGL-2153).\n *\n * the rule for the self-host path: *\"the self hosted owner should not have\n * to edit the source to update aglyn branded items urls or personal\n * identification items, should move these to env vars\"*. AGL-2016 did that for\n * the values where getting it wrong misroutes a legal notice. This is the\n * other half — the product name itself, which was a bare `'Aglyn'` literal in\n * nine places.\n *\n * ## Why one module rather than nine reads\n *\n * The literals were not merely duplicated, they were duplicated across a\n * boundary: `PLATFORM_GENERATOR_NAME` exists here AND as a hand-copied\n * constant in `apps/tenant/middleware.ts`, because the edge bundle cannot\n * import this lib. A single source they both read is what stops the copy from\n * drifting into a deployment that half-renames itself.\n *\n * ## Why a default at all, when operator-identity.ts refuses to have one\n *\n * `operator-identity.ts` sets out the rule and it is the right one: a value\n * whose wrongness is invisible to the operator and visible only off-site must\n * not be guessed. The brand is the opposite case. An operator who does not set\n * it sees \"Aglyn\" in their own browser tab on their own first page load, in\n * their own console. That is a default they can see and correct, which is a\n * default rather than a trap — the same test AGL-2022 applied to the tenant\n * apex.\n *\n * ## Why `NEXT_PUBLIC_`, and why dot notation is load-bearing\n *\n * The brand is printed to the public — that is what it is for — so\n * `NEXT_PUBLIC_` carries no disclosure risk. Next inlines `NEXT_PUBLIC_*` into\n * the browser bundle by textually substituting `process.env.NAME`; the\n * **bracket** form is never substituted and reads `undefined` in the browser\n * (AGL-2037). Every read below is dot notation on purpose.\n *\n * Build-time consequence for self-hosters: these are baked in when the image\n * is built, so they must be set *before* `docker compose build`, not merely\n * before `up`. `docs/SELF_HOSTING.md` says so.\n */\n\n/** A non-empty trimmed string, else undefined — `'   '` is a half-finished `.env`. */\nconst clean = (value: unknown): string | undefined => {\n  const text = typeof value === 'string' ? value.trim() : ''\n  return text.length ? text : undefined\n}\n\n/**\n * The product name, as shown to end users.\n *\n * This is the browser-tab affix, the PWA name, the WebAuthn relying-party name\n * the OS credential prompt displays, the `<meta name=\"generator\">` and\n * `x-powered-by` on published sites, and the platform default `productName` /\n * `fromName` every non-white-label org's surfaces resolve to.\n */\nexport const PLATFORM_BRAND_NAME =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_BRAND_NAME) ?? 'Aglyn'\n\n/**\n * The legal entity operating the software's own cloud, for copy that needs a\n * company rather than a product (`BRAND.ORG_NAME_LEGAL`).\n *\n * NOT the same thing as `operatorIdentity().name`, and the distinction matters.\n * This is a *brand* string with a visible default; that one is the identity a\n * statutory notice is addressed to and refuses to default. An operator who\n * sets only this has renamed the product, not published who they are.\n */\nexport const PLATFORM_BRAND_LEGAL_NAME =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_BRAND_LEGAL_NAME) ??\n  `${PLATFORM_BRAND_NAME} LLC`\n\n/**\n * Where a \"need help?\" line points.\n *\n * Falls through the operator's OWN support address before it falls back to\n * ours, deliberately: an operator who followed the runbook has already set\n * `NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL`, and making them discover a second\n * variable to stop pointing their customers at Aglyn's support desk — which\n * cannot help those customers with anything — is a trap dressed as a default.\n *\n * Read here rather than imported from `operator-identity.ts` so this module\n * stays dependency-free and safe to import from anywhere, including the places\n * that cannot take the operator module's weight.\n *\n * ## Why the last fallback is the CONSOLE and not the marketing site\n *\n * It was `aglyn.com/support`, which answers 404 and has never existed\n * (AGL-3262) — MEASURED against the live site, not inferred: `/support`,\n * `/help` and `/docs` all render the not-found page and none is in the\n * sitemap. A support URL that 404s is worse than none, because it is printed\n * on a receipt beside a charge the reader is already unsure about.\n *\n * `app.aglyn.com/support` is a real page (AGL-3265): it resolves the\n * workspace from the session, so a customer with one lands on its support\n * umbrella and a customer with several picks. That is the whole reason it\n * exists — it is the one support address that needs nothing interpolated\n * into it, which is exactly what this constant is.\n *\n * The console is THIS install's (AGL-3322). `/support` is a console route, so\n * every console serves its own, and `NEXT_PUBLIC_CONSOLE_URL` is required of\n * every self-hosted install — so one that configured neither variable above\n * sends its customers to its own support page rather than to ours, where they\n * have no account. The line is in the footer of every system email the\n * platform sends. `app.aglyn.com` is left only for a build that names no\n * console at all.\n */\nexport const PLATFORM_SUPPORT_URL: string = (() => {\n  const configured = clean(process.env.NEXT_PUBLIC_PLATFORM_SUPPORT_URL)\n  if (configured) return configured\n  const operatorEmail = clean(process.env.NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL)\n  if (operatorEmail) return `mailto:${operatorEmail}`\n  return `${platformConsoleOrigin()}/support`\n})()\n\n/**\n * This install's console origin, with no trailing slash — what a link in a\n * notification or an email the platform sends is built on (AGL-3080).\n *\n * `NEXT_PUBLIC_CONSOLE_URL`, which every self-hosted install sets; Aglyn's\n * own console only for a build that names none. One reading for the support\n * page above and for every scheduled sender, a plugin's included, so none of\n * them spells the fallback again.\n */\nexport function platformConsoleOrigin(): string {\n  const configured = clean(process.env.NEXT_PUBLIC_CONSOLE_URL)?.replace(/\\/+$/, '')\n  return configured || 'https://app.aglyn.com'\n}\n\n/** True when this deployment still answers to Aglyn's own brand. */\nexport const isAglynOperatedBrand = (): boolean =>\n  PLATFORM_BRAND_NAME === 'Aglyn'\n\n/**\n * Where the platform's own front door is — the marketing home, not the help\n * desk.\n *\n * ## Why this is not `PLATFORM_SUPPORT_URL`\n *\n * The \"Made with …\" badge on a published free-tier site used to link to\n * `supportUrl`, and on this deployment `supportUrl` falls through to\n * `mailto:` + the operator support address. So the one link the platform gets\n * on every free customer's site — its only organic acquisition surface —\n * opened the visitor's mail client addressed to our support desk. A visitor\n * who liked the site and clicked to find out what built it got a blank email,\n * and support got the misdirected replies.\n *\n * They are genuinely different destinations. `supportUrl` answers \"I am a\n * customer and something is wrong\"; this answers \"what is this, and can I have\n * one\". Keeping one value for both guarantees one of them is wrong.\n *\n * ## Why it is null rather than aglyn.com off-brand\n *\n * A self-hosted deployment that renamed the product but set no home URL has\n * nowhere honest to send that visitor: \"Made with Foo\" pointing at aglyn.com\n * advertises the wrong company on Foo's customers' sites. The badge already\n * renders as a plain label when it has no destination (AGL-2428), which is the\n * correct outcome — so the Aglyn default applies only while this really is the\n * Aglyn-operated brand.\n */\nexport const PLATFORM_HOME_URL: string | null =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_HOME_URL) ??\n  (isAglynOperatedBrand() ? 'https://aglyn.com' : null)\n\n/**\n * The platform's own logo MARK — the compact, square, no-wordmark form — as a\n * URL an `<img>` on a PUBLISHED SITE can load.\n *\n * Site-relative on purpose: every app that renders it serves\n * `public/_static/…` from its own origin, so one path works on\n * `{sub}.aglyn.app` and on a customer's custom domain alike without knowing\n * either. The white variant is the one that survives the badge's dark pill and\n * an org's `primaryColor` behind it.\n *\n * Null unless this is the Aglyn-operated brand, for the same reason as\n * {@link PLATFORM_HOME_URL}: a renamed deployment must not stamp our mark on\n * its customers' sites. Such an operator sets `NEXT_PUBLIC_PLATFORM_MARK_URL`\n * to their own, or gets a text-only badge.\n */\nexport const PLATFORM_MARK_URL: string | null =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_MARK_URL) ??\n  (isAglynOperatedBrand()\n    ? '/_static/images/brand/aglyn-logo-mark-white.svg'\n    : null)\n\n/** An absolute `https://` URL, else undefined — anything else has no origin in an inbox. */\nconst httpsUrl = (value: string | undefined): string | undefined => {\n  if (!value) return undefined\n  try {\n    return new URL(value).protocol === 'https:' ? value : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * The platform's logo as its own system email draws it: the header of mail\n * sent under the platform's brand (AGL-3322).\n *\n * ABSOLUTE and https, unlike {@link PLATFORM_MARK_URL}. That mark is a\n * site-relative path because every app that draws it serves the file from its\n * own origin; an inbox has no origin, so a relative path there is a\n * broken-image box. A configured value that is not an absolute `https://` URL\n * is ignored rather than handed on to fail in somebody's inbox.\n *\n * The WORDMARK rather than the square mark: a header is read at a glance, and\n * the wordmark names the sender where the mark would need the reader to\n * already know it.\n *\n * A PNG sized for the slot (AGL-3367): 396×120, three times the 132×40 the\n * header draws it at, about 15 KB, served as a static file off aglyn.com's\n * edge. The master-resolution file behind the media CDN's 60-second cache is\n * four times the bytes and makes the header the last thing in the email to\n * appear. Not an SVG: Gmail and Outlook do not draw SVG in mail, so every\n * recipient on either would get a broken-image box where the logo belongs.\n *\n * Null unless this is the Aglyn-operated brand, for the reason\n * {@link PLATFORM_HOME_URL} is: a renamed deployment must not put our logo at\n * the top of its customers' mail. Such an operator sets\n * `NEXT_PUBLIC_PLATFORM_EMAIL_LOGO_URL`, or gets its product name as the\n * header, in bold text.\n *\n * Deliberately NOT `PLATFORM_BRANDING_PROFILE.emailLogoUrl`, which stays null.\n * That field is an ORG's email logo: a white-label profile inherits it when\n * the org set none, and a send that carries one is read as an org's own mail.\n * Putting the platform's logo there would stamp it on every white-label org\n * that left the field blank.\n */\nexport const PLATFORM_EMAIL_LOGO_URL: string | null =\n  httpsUrl(clean(process.env.NEXT_PUBLIC_PLATFORM_EMAIL_LOGO_URL)) ??\n  (isAglynOperatedBrand()\n    ? 'https://aglyn.com/_static/images/brand/aglyn-email-wordmark.png'\n    : null)\n\n/**\n * The postal address printed beside {@link PLATFORM_BRAND_LEGAL_NAME} at the\n * foot of the platform's own system email (AGL-3322).\n *\n * A BRAND string, beside the legal name whose line it completes, rather than\n * a field of `operatorIdentity()`, and the difference is the default. The\n * operator identity is what a statutory notice is addressed to and refuses to\n * guess; this is a line in a footer the operator sees in their own mail and\n * can correct, and for the Aglyn-operated brand the right value is known: the\n * registered agent's address the Aglyn marketing site's email footer prints.\n *\n * Null unless this is the Aglyn-operated brand: a renamed deployment must\n * never print our address as its own. Such an operator sets\n * `NEXT_PUBLIC_PLATFORM_POSTAL_ADDRESS`, or their footer carries the legal\n * name alone. Line breaks in a configured value are folded into commas,\n * because the footer prints the address on one line.\n */\nexport const PLATFORM_POSTAL_ADDRESS: string | null =\n  clean(process.env.NEXT_PUBLIC_PLATFORM_POSTAL_ADDRESS)\n    ?.split(/\\s*\\n\\s*/)\n    .filter(Boolean)\n    .join(', ') ??\n  (isAglynOperatedBrand()\n    ? 'c/o Northwest Registered Agent, LLC, 5900 Balcones Drive STE 100, Austin, TX 78731'\n    : null)\n\n/**\n * A branding profile with every field present — what a branded surface\n * renders. Image/color/domain fields are nullable (Aglyn's own surfaces\n * bake those in rather than carry a URL); the remaining text fields always\n * have a value so callers never string-concatenate `undefined`.\n *\n * `supportUrl` is nullable too, and it is the one field where null carries a\n * decision rather than an absence — see {@link resolveBrandingProfile}. A\n * caller must render NOTHING for it, never a placeholder and never a\n * substitute.\n */\nexport interface ResolvedBrandingProfile {\n  productName: string\n  logoUrl: string | null\n  /** The logo for dark grounds; null means {@link logoUrl} serves both. */\n  logoDarkUrl: string | null\n  faviconUrl: string | null\n  /** The favicon for a dark tab strip; null means {@link faviconUrl} serves both. */\n  faviconDarkUrl: string | null\n  primaryColor: string | null\n  supportUrl: string | null\n  /**\n   * The brand's own FRONT DOOR — where \"Made with <product>\" sends a visitor\n   * who wants to know what built the site they are looking at.\n   *\n   * Deliberately separate from {@link ResolvedBrandingProfile.supportUrl},\n   * which the badge used to borrow: a help-desk address is the wrong answer to\n   * \"what is this\", and on this deployment it resolves to a `mailto:`, so the\n   * badge opened a blank email instead of a web page.\n   *\n   * Nullable for the same reason `supportUrl` is — a brand with nowhere to\n   * send that visitor gets a plain label, never a substitute destination.\n   */\n  homeUrl: string | null\n  fromName: string\n  emailLogoUrl: string | null\n  customConsoleDomain: string | null\n}\n\n/**\n * The PLATFORM (non-white-label) brand — the fallback every surface gets when\n * an org lacks the `whiteLabel` entitlement, and the gap-filler for a partial\n * agency profile.\n *\n * It lives beside the literals it is assembled from rather than beside the\n * entitlement gate that hands it out, and that placement is load-bearing\n * rather than tidying. A published tenant page renders the attribution badge\n * from this constant and reads nothing else out of `plan-entitlements.ts`;\n * defining it there put that module's whole plan, quota and entitlement table\n * — the single largest first-party module a visitor could reach — into the\n * first load of every anonymous visitor to every customer site.\n * `plan-entitlements.ts` re-exports it, so every existing caller is unchanged.\n *\n * The name says the PLATFORM's brand rather than Aglyn's because on a\n * self-host install that assertion stops being true: which platform this is,\n * is configuration. `resolveBrandingProfile` is the single resolver EVERY\n * branded surface routes through — console chrome, published-site badge and\n * title, transactional email — and this is its fallback, so all of them get a\n * self-host brand without extending the white-label machinery at all.\n */\nexport const PLATFORM_BRANDING_PROFILE: ResolvedBrandingProfile = {\n  productName: PLATFORM_BRAND_NAME,\n  // The platform's own surfaces still bake their logo in — this is here for\n  // the surfaces that CANNOT, which is every surface rendered on somebody\n  // else's site. The free-tier attribution badge is the one that exists\n  // today, and it carried no mark at all while this was null.\n  logoUrl: PLATFORM_MARK_URL,\n  logoDarkUrl: null,\n  faviconUrl: null,\n  faviconDarkUrl: null,\n  primaryColor: null,\n  supportUrl: PLATFORM_SUPPORT_URL,\n  homeUrl: PLATFORM_HOME_URL,\n  fromName: PLATFORM_BRAND_NAME,\n  emailLogoUrl: null,\n  customConsoleDomain: null,\n}\n"],"names":["clean","httpsUrl","value","text","trim","length","undefined","PLATFORM_BRAND_NAME","process","env","NEXT_PUBLIC_PLATFORM_BRAND_NAME","PLATFORM_BRAND_LEGAL_NAME","NEXT_PUBLIC_PLATFORM_BRAND_LEGAL_NAME","PLATFORM_SUPPORT_URL","configured","NEXT_PUBLIC_PLATFORM_SUPPORT_URL","operatorEmail","NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL","platformConsoleOrigin","NEXT_PUBLIC_CONSOLE_URL","replace","isAglynOperatedBrand","PLATFORM_HOME_URL","NEXT_PUBLIC_PLATFORM_HOME_URL","PLATFORM_MARK_URL","NEXT_PUBLIC_PLATFORM_MARK_URL","URL","protocol","PLATFORM_EMAIL_LOGO_URL","NEXT_PUBLIC_PLATFORM_EMAIL_LOGO_URL","PLATFORM_POSTAL_ADDRESS","NEXT_PUBLIC_PLATFORM_POSTAL_ADDRESS","split","filter","Boolean","join","PLATFORM_BRANDING_PROFILE","productName","logoUrl","logoDarkUrl","faviconUrl","faviconDarkUrl","primaryColor","supportUrl","homeUrl","fromName","emailLogoUrl","customConsoleDomain"],"mappings":"IAyEEA,QAYAA,SA4FAA,SAmBAA,SAiDAC;IAuBAD;AA5QF;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCC,GAED,oFAAoF,GACpF,MAAMA,QAAQ,CAACE;IACb,MAAMC,OAAO,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACxD,OAAOD,KAAKE,MAAM,GAAGF,OAAOG;AAC9B;AAEA;;;;;;;CAOC,GACD,OAAO,MAAMC,uBACXP,SAAAA,MAAMQ,QAAQC,GAAG,CAACC,+BAA+B,aAAjDV,SAAsD,QAAO;AAE/D;;;;;;;;CAQC,GACD,OAAO,MAAMW,6BACXX,UAAAA,MAAMQ,QAAQC,GAAG,CAACG,qCAAqC,aAAvDZ,UACA,GAAGO,oBAAoB,IAAI,CAAC,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkCC,GACD,OAAO,MAAMM,uBAA+B,AAAC,CAAA;IAC3C,MAAMC,aAAad,MAAMQ,QAAQC,GAAG,CAACM,gCAAgC;IACrE,IAAID,YAAY,OAAOA;IACvB,MAAME,gBAAgBhB,MAAMQ,QAAQC,GAAG,CAACQ,kCAAkC;IAC1E,IAAID,eAAe,OAAO,CAAC,OAAO,EAAEA,eAAe;IACnD,OAAO,GAAGE,wBAAwB,QAAQ,CAAC;AAC7C,CAAA,IAAI;AAEJ;;;;;;;;CAQC,GACD,OAAO,SAASA;QACKlB;IAAnB,MAAMc,cAAad,SAAAA,MAAMQ,QAAQC,GAAG,CAACU,uBAAuB,sBAAzCnB,OAA4CoB,OAAO,CAAC,QAAQ;IAC/E,OAAON,cAAc;AACvB;AAEA,kEAAkE,GAClE,OAAO,MAAMO,uBAAuB,IAClCd,wBAAwB,QAAO;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GACD,OAAO,MAAMe,qBACXtB,UAAAA,MAAMQ,QAAQC,GAAG,CAACc,6BAA6B,aAA/CvB,UACCqB,yBAAyB,sBAAsB,KAAK;AAEvD;;;;;;;;;;;;;;CAcC,GACD,OAAO,MAAMG,qBACXxB,UAAAA,MAAMQ,QAAQC,GAAG,CAACgB,6BAA6B,aAA/CzB,UACCqB,yBACG,oDACA,KAAK;AAEX,0FAA0F,GAC1F,MAAMpB,WAAW,CAACC;IAChB,IAAI,CAACA,OAAO,OAAOI;IACnB,IAAI;QACF,OAAO,IAAIoB,IAAIxB,OAAOyB,QAAQ,KAAK,WAAWzB,QAAQI;IACxD,EAAE,eAAM;QACN,OAAOA;IACT;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCC,GACD,OAAO,MAAMsB,2BACX3B,YAAAA,SAASD,MAAMQ,QAAQC,GAAG,CAACoB,mCAAmC,cAA9D5B,YACCoB,yBACG,oEACA,KAAK;AAEX;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,MAAMS,mCACX9B,UAAAA,MAAMQ,QAAQC,GAAG,CAACsB,mCAAmC,sBAArD/B,QACIgC,KAAK,CAAC,YACPC,MAAM,CAACC,SACPC,IAAI,CAAC,wBACPd,yBACG,uFACA,KAAK;AAyCX;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,MAAMe,4BAAqD;IAChEC,aAAa9B;IACb,0EAA0E;IAC1E,wEAAwE;IACxE,sEAAsE;IACtE,4DAA4D;IAC5D+B,SAASd;IACTe,aAAa;IACbC,YAAY;IACZC,gBAAgB;IAChBC,cAAc;IACdC,YAAY9B;IACZ+B,SAAStB;IACTuB,UAAUtC;IACVuC,cAAc;IACdC,qBAAqB;AACvB,EAAC"}

package/src/lib/app-utils/platform-marketing-consent.d.ts

@@ -14,11 +14,65 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/**
+ * Marketing consent for the PLATFORM's own product email (AGL-3185).
+ *
+ * The strict policy (`marketing-consent.ts`) means a person with no declared
+ * basis is unsendable, and until this module the only doors that declared
+ * one were the marketing site's forms. Somebody who created a console account
+ * — the warmest audience the platform has — was never asked. Three console
+ * doors ask now: a checkbox on the sign-up form, a switch in the account
+ * preferences, and a one-time prompt for accounts that predate the checkbox.
+ *
+ * ## One wording, versioned
+ *
+ * Every door shows {@link PLATFORM_MARKETING_CONSENT_TEXT} and every record
+ * stores {@link PLATFORM_MARKETING_CONSENT_TEXT_VERSION} beside the exact
+ * timestamp, so "what did this person agree to" is answered by a version and
+ * not by whatever the checkbox says today. Changing the sentence is a bump of
+ * the version in the same edit.
+ *
+ * ## The record lives in two places, and the two do not disagree
+ *
+ * The decision is written by the server onto the person's own `users/{uid}`
+ * document, so the console can show a preference without reading the
+ * operator's CRM, and onto the operator's marketing contact for the same
+ * person, so the send path sees a declared basis with provenance. The
+ * contact half is written only when the deployment names a marketing host
+ * (`PLATFORM_MARKETING_HOST_ID`, read in `@aglyn/tenant-data-admin`); a
+ * self-hosted install with no audience of its own records the preference
+ * and skips the contact — and keeps asking, so the answers are already on
+ * file the day the operator names a marketing host.
+ *
+ * ## An unsubscribe reaches the account, for its own list only (AGL-3305)
+ *
+ * The marketing site's emails carry their own way out, and a person who uses
+ * it has answered the console's question too — but only if what they left
+ * is the list the question was about. Leaving
+ * {@link PLATFORM_MARKETING_TOPIC_ID}, or everything the site sends, turns
+ * the account's answer to No through an email door; leaving the newsletter
+ * leaves it alone. The email doors write the account and nothing else: the
+ * site's lists already say what was left, and declining the contact's basis
+ * would stop every list, not the one the person chose.
+ *
+ * ## Absence is not refusal
+ *
+ * An unticked sign-up checkbox records nothing. A switch turned off and a
+ * prompt answered "no" record a refusal, which the strict policy already
+ * honors. A prompt dismissed without an answer records only the dismissal,
+ * and the prompt stays away for {@link PLATFORM_MARKETING_PROMPT_SNOOZE_MS}.
+ *
+ * Pure and dependency-light on purpose: the sign-up page renders the text,
+ * the console route validates the body, and the server library writes the
+ * record, all from this one module.
+ */
 import { type MarketingConsentSource } from './marketing-consent';
 /**
  * The list the account's answer stands for on the marketing site (AGL-3305):
- * the built-in "Product updates" topic, which is what the platform's own
- * announcements are sent on.
+ * the built-in "Product updates" stream, which is what the platform's own
+ * announcements are sent on. A wire value like every topic id — it keys the
+ * opt-outs already recorded on the marketing host — and the same stream the
+ * built-in catalog offers every site as "Product updates".
  *
  * Named so that "which unsubscribe is about this answer" has one spelling.
  * Leaving this list, or leaving everything the site sends, is a No to the

package/src/lib/app-utils/platform-marketing-consent.js

@@ -64,20 +64,21 @@
  * Pure and dependency-light on purpose: the sign-up page renders the text,
  * the console route validates the body, and the server library writes the
  * record, all from this one module.
- */ import { EMAIL_TOPIC_PRODUCT_UPDATES } from "./email-topics.js";
-import { MARKETING_CONSENT_FIELD, MARKETING_CONSENT_SOURCE_FIELD } from "./marketing-consent.js";
+ */ import { MARKETING_CONSENT_FIELD, MARKETING_CONSENT_SOURCE_FIELD } from "./marketing-consent.js";
 import { PLATFORM_BRAND_NAME } from "./platform-brand.js";
 /**
  * The list the account's answer stands for on the marketing site (AGL-3305):
- * the built-in "Product updates" topic, which is what the platform's own
- * announcements are sent on.
+ * the built-in "Product updates" stream, which is what the platform's own
+ * announcements are sent on. A wire value like every topic id — it keys the
+ * opt-outs already recorded on the marketing host — and the same stream the
+ * built-in catalog offers every site as "Product updates".
  *
  * Named so that "which unsubscribe is about this answer" has one spelling.
  * Leaving this list, or leaving everything the site sends, is a No to the
  * question the console asked. Leaving any other list is not, and must not
  * touch the answer: someone who stops the newsletter has said nothing about
  * product updates.
- */ export const PLATFORM_MARKETING_TOPIC_ID = EMAIL_TOPIC_PRODUCT_UPDATES;
+ */ export const PLATFORM_MARKETING_TOPIC_ID = 'product-updates';
 /** The console doors a decision can come through, as the record names them. */ export const PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS = [
     'console-signup',
     'console-preferences',

package/src/lib/app-utils/platform-marketing-consent.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-marketing-consent.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 * Marketing consent for the PLATFORM's own product email (AGL-3185).\n *\n * The strict policy (`marketing-consent.ts`) means a person with no declared\n * basis is unsendable, and until this module the only doors that declared\n * one were the marketing site's forms. Somebody who created a console account\n * — the warmest audience the platform has — was never asked. Three console\n * doors ask now: a checkbox on the sign-up form, a switch in the account\n * preferences, and a one-time prompt for accounts that predate the checkbox.\n *\n * ## One wording, versioned\n *\n * Every door shows {@link PLATFORM_MARKETING_CONSENT_TEXT} and every record\n * stores {@link PLATFORM_MARKETING_CONSENT_TEXT_VERSION} beside the exact\n * timestamp, so \"what did this person agree to\" is answered by a version and\n * not by whatever the checkbox says today. Changing the sentence is a bump of\n * the version in the same edit.\n *\n * ## The record lives in two places, and the two do not disagree\n *\n * The decision is written by the server onto the person's own `users/{uid}`\n * document, so the console can show a preference without reading the\n * operator's CRM, and onto the operator's marketing contact for the same\n * person, so the send path sees a declared basis with provenance. The\n * contact half is written only when the deployment names a marketing host\n * (`PLATFORM_MARKETING_HOST_ID`, read in `@aglyn/tenant-data-admin`); a\n * self-hosted install with no audience of its own records the preference\n * and skips the contact — and keeps asking, so the answers are already on\n * file the day the operator names a marketing host.\n *\n * ## An unsubscribe reaches the account, for its own list only (AGL-3305)\n *\n * The marketing site's emails carry their own way out, and a person who uses\n * it has answered the console's question too — but only if what they left\n * is the list the question was about. Leaving\n * {@link PLATFORM_MARKETING_TOPIC_ID}, or everything the site sends, turns\n * the account's answer to No through an email door; leaving the newsletter\n * leaves it alone. The email doors write the account and nothing else: the\n * site's lists already say what was left, and declining the contact's basis\n * would stop every list, not the one the person chose.\n *\n * ## Absence is not refusal\n *\n * An unticked sign-up checkbox records nothing. A switch turned off and a\n * prompt answered \"no\" record a refusal, which the strict policy already\n * honors. A prompt dismissed without an answer records only the dismissal,\n * and the prompt stays away for {@link PLATFORM_MARKETING_PROMPT_SNOOZE_MS}.\n *\n * Pure and dependency-light on purpose: the sign-up page renders the text,\n * the console route validates the body, and the server library writes the\n * record, all from this one module.\n */\n\nimport { EMAIL_TOPIC_PRODUCT_UPDATES } from './email-topics'\nimport {\n  MARKETING_CONSENT_FIELD,\n  MARKETING_CONSENT_SOURCE_FIELD,\n  type MarketingConsentSource,\n} from './marketing-consent'\nimport { PLATFORM_BRAND_NAME } from './platform-brand'\n\n/**\n * The list the account's answer stands for on the marketing site (AGL-3305):\n * the built-in \"Product updates\" topic, which is what the platform's own\n * announcements are sent on.\n *\n * Named so that \"which unsubscribe is about this answer\" has one spelling.\n * Leaving this list, or leaving everything the site sends, is a No to the\n * question the console asked. Leaving any other list is not, and must not\n * touch the answer: someone who stops the newsletter has said nothing about\n * product updates.\n */\nexport const PLATFORM_MARKETING_TOPIC_ID = EMAIL_TOPIC_PRODUCT_UPDATES\n\n/** The console doors a decision can come through, as the record names them. */\nexport const PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS = [\n  'console-signup',\n  'console-preferences',\n  'console-prompt',\n] as const\n\nexport type PlatformMarketingConsoleSourceKind =\n  (typeof PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS)[number]\n\n/**\n * The email doors (AGL-3305): the marketing site's own unsubscribe,\n * preference and resubscribe pages, when what the person changed there was\n * {@link PLATFORM_MARKETING_TOPIC_ID} or everything.\n *\n * Kept apart from the console doors because nothing the console sends may\n * claim one. The server records these from the signed link a recipient\n * followed; a console request naming one is refused, because a click in the\n * console is not a click in a mailbox.\n */\nexport const PLATFORM_MARKETING_EMAIL_SOURCE_KINDS = [\n  'email-unsubscribe',\n  'email-preferences',\n  'email-resubscribe',\n] as const\n\nexport type PlatformMarketingEmailSourceKind =\n  (typeof PLATFORM_MARKETING_EMAIL_SOURCE_KINDS)[number]\n\n/** Every door a stored decision can name. */\nexport const PLATFORM_MARKETING_CONSENT_SOURCE_KINDS = [\n  ...PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS,\n  ...PLATFORM_MARKETING_EMAIL_SOURCE_KINDS,\n] as const\n\nexport type PlatformMarketingConsentSourceKind =\n  (typeof PLATFORM_MARKETING_CONSENT_SOURCE_KINDS)[number]\n\n/** Any door, for READING a stored decision. */\nexport function isPlatformMarketingConsentSourceKind(\n  value: unknown,\n): value is PlatformMarketingConsentSourceKind {\n  return (PLATFORM_MARKETING_CONSENT_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** A console door: the only kind a console request may record. */\nexport function isPlatformMarketingConsoleSourceKind(\n  value: unknown,\n): value is PlatformMarketingConsoleSourceKind {\n  return (PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** An email door: a decision made from a link in one of the site's emails. */\nexport function isPlatformMarketingEmailSourceKind(\n  value: unknown,\n): value is PlatformMarketingEmailSourceKind {\n  return (PLATFORM_MARKETING_EMAIL_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** What a door records: a grant or a refusal. Absence is never recorded. */\nexport const PLATFORM_MARKETING_CONSENT_DECISIONS = ['granted', 'declined'] as const\n\nexport type PlatformMarketingConsentDecision =\n  (typeof PLATFORM_MARKETING_CONSENT_DECISIONS)[number]\n\nexport function isPlatformMarketingConsentDecision(\n  value: unknown,\n): value is PlatformMarketingConsentDecision {\n  return (PLATFORM_MARKETING_CONSENT_DECISIONS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/**\n * The version of the consent wording every door shows. Bumped in the same\n * edit as {@link platformMarketingConsentText}; a record stores the version\n * it was shown under, so the two must move together.\n */\nexport const PLATFORM_MARKETING_CONSENT_TEXT_VERSION = '2026-09-20'\n\n/**\n * The sentence the person agrees to, with the deployment's brand in it.\n *\n * Affirmative and standalone: it names what is sent, who sends it, and that\n * it can be stopped — never bundled with the terms acceptance, and never\n * pre-ticked anywhere it is rendered.\n */\nexport function platformMarketingConsentText(brandName: string): string {\n  return `Send me product updates from ${brandName}. You can opt out any time.`\n}\n\n/** {@link platformMarketingConsentText} for the brand this deployment wears. */\nexport const PLATFORM_MARKETING_CONSENT_TEXT = platformMarketingConsentText(\n  PLATFORM_BRAND_NAME,\n)\n\n/**\n * The `users/{uid}` fields the decision is mirrored onto.\n *\n * The same names the contact record uses for the same facts, so one reader\n * can parse either document. The prompt-dismissal stamp has no contact\n * counterpart: it is about what the console asked, not what the person\n * agreed to.\n */\nexport const USER_MARKETING_CONSENT_FIELD = MARKETING_CONSENT_FIELD\nexport const USER_MARKETING_CONSENT_AT_FIELD = 'marketingConsentAtMs'\nexport const USER_MARKETING_CONSENT_SOURCE_FIELD = MARKETING_CONSENT_SOURCE_FIELD\nexport const USER_MARKETING_PROMPT_DISMISSED_AT_FIELD =\n  'marketingConsentPromptDismissedAtMs'\n\n/** How long a dismissed prompt stays away: ninety days. */\nexport const PLATFORM_MARKETING_PROMPT_SNOOZE_MS = 90 * 24 * 60 * 60 * 1000\n\n/** What the person's own document says about product email. */\nexport interface PlatformMarketingConsentState {\n  /** `null` when nothing has been recorded — asked, but not answered. */\n  decision: PlatformMarketingConsentDecision | null\n  /** When the decision was recorded. */\n  atMs: number | null\n  /** The wording version the decision was made under. */\n  textVersion: string | null\n  /**\n   * Which door recorded it — a console door, or an email door for a decision\n   * mirrored from the marketing site's own pages. `null` for a record another\n   * writer left.\n   */\n  sourceKind: PlatformMarketingConsentSourceKind | null\n  /** When the prompt was last dismissed without an answer. */\n  promptDismissedAtMs: number | null\n}\n\nfunction finiteOrNull(value: unknown): number | null {\n  return typeof value === 'number' && Number.isFinite(value) ? value : null\n}\n\n/**\n * Reads the decision off a `users/{uid}` document, or off no document.\n *\n * Every unusable value reads as its absent case rather than throwing: a\n * malformed field must degrade to \"nothing recorded\", which asks again,\n * never to a grant.\n */\nexport function readPlatformMarketingConsent(\n  document: Record<string, unknown> | null | undefined,\n): PlatformMarketingConsentState {\n  const consent = document?.[USER_MARKETING_CONSENT_FIELD]\n  const rawSource = document?.[USER_MARKETING_CONSENT_SOURCE_FIELD]\n  const source =\n    rawSource && typeof rawSource === 'object' && !Array.isArray(rawSource)\n      ? (rawSource as Record<string, unknown>)\n      : null\n  const textVersion = source?.['textVersion']\n  return {\n    decision: consent === true ? 'granted' : consent === false ? 'declined' : null,\n    atMs: finiteOrNull(document?.[USER_MARKETING_CONSENT_AT_FIELD]),\n    textVersion:\n      typeof textVersion === 'string' && textVersion ? textVersion : null,\n    sourceKind: isPlatformMarketingConsentSourceKind(source?.['kind'])\n      ? source['kind']\n      : null,\n    promptDismissedAtMs: finiteOrNull(\n      document?.[USER_MARKETING_PROMPT_DISMISSED_AT_FIELD],\n    ),\n  }\n}\n\n/**\n * Whether the console should ask this person now.\n *\n * Never after a decision, in either direction: a \"no\" is an answer and a\n * \"yes\" needs no repeating. A dismissal is not an answer, so the prompt\n * returns once the snooze has run out.\n */\nexport function platformMarketingPromptDue(\n  state: Pick<PlatformMarketingConsentState, 'decision' | 'promptDismissedAtMs'>,\n  nowMs: number,\n): boolean {\n  if (state.decision !== null) return false\n  if (state.promptDismissedAtMs === null) return true\n  return nowMs - state.promptDismissedAtMs >= PLATFORM_MARKETING_PROMPT_SNOOZE_MS\n}\n\n/**\n * What each door did, in prose, for whoever audits the record later.\n *\n * Keyed by door and decision so the sentence is decided once, here, and the\n * three doors cannot describe the same act three different ways.\n */\nconst PROVENANCE_REASONS: Record<\n  PlatformMarketingConsoleSourceKind,\n  Record<PlatformMarketingConsentDecision, string>\n> = {\n  'console-signup': {\n    granted: 'Ticked the product-updates checkbox on the console sign-up form.',\n    declined: 'Declined product updates on the console sign-up form.',\n  },\n  'console-preferences': {\n    granted: 'Turned product updates on in the console account preferences.',\n    declined: 'Turned product updates off in the console account preferences.',\n  },\n  'console-prompt': {\n    granted: 'Answered yes to the product-updates prompt in the console.',\n    declined: 'Answered no to the product-updates prompt in the console.',\n  },\n}\n\n/**\n * The provenance stored with a console decision, on both documents.\n *\n * `actor: 'person'` is what keeps {@link MarketingConsentSource} honest here:\n * the reader treats provenance as an operator's assertion unless it says\n * otherwise, and this is the person's own click, carrying which door and\n * which wording. `by` is the account that clicked — the subject and the\n * actor are the same human, which is the fact the field records.\n */\nexport function platformMarketingConsentSource(input: {\n  kind: PlatformMarketingConsoleSourceKind\n  decision: PlatformMarketingConsentDecision\n  uid: string\n  atMs: number\n  textVersion: string\n}): MarketingConsentSource {\n  return {\n    kind: input.kind,\n    by: input.uid,\n    atMs: input.atMs,\n    reason: PROVENANCE_REASONS[input.kind][input.decision],\n    textVersion: input.textVersion,\n    actor: 'person',\n  }\n}\n\n/**\n * What an email door did, and which decisions each door can make.\n *\n * The pairs are the whole vocabulary: an unsubscribe only ever refuses, a\n * resubscribe only ever restores, and only the preference page does both.\n * Typed as the union rather than a free kind and decision, so an\n * \"unsubscribe that granted\" cannot be written down at all.\n */\nexport type PlatformMarketingEmailDecision =\n  | { kind: 'email-unsubscribe'; decision: 'declined' }\n  | { kind: 'email-preferences'; decision: PlatformMarketingConsentDecision }\n  | { kind: 'email-resubscribe'; decision: 'granted' }\n\nconst EMAIL_PROVENANCE_REASONS: {\n  [K in PlatformMarketingEmailDecision as `${K['kind']}:${K['decision']}`]: string\n} = {\n  'email-unsubscribe:declined':\n    'Unsubscribed from every email the marketing site sends, from a link in one of its emails.',\n  'email-preferences:declined':\n    'Left product updates on the marketing site’s email preference page.',\n  'email-preferences:granted':\n    'Chose product updates again on the marketing site’s email preference page.',\n  'email-resubscribe:granted':\n    'Resubscribed from the link in one of the marketing site’s emails.',\n}\n\n/**\n * The provenance stored with a decision mirrored from the marketing site's\n * own pages (AGL-3305), on the account only.\n *\n * Still `actor: 'person'`: the click was the recipient's, on a link signed\n * for their address. No `textVersion`, because those pages do not version\n * their wording; the field is absent rather than borrowing the console's\n * version for a sentence the person never saw.\n */\nexport function platformMarketingEmailSource(\n  input: PlatformMarketingEmailDecision & { uid: string; atMs: number },\n): MarketingConsentSource {\n  return {\n    kind: input.kind,\n    by: input.uid,\n    atMs: input.atMs,\n    // The union narrows the pair; the template type cannot see that, so the\n    // key is asserted to the table's own keys rather than widened to string.\n    reason: EMAIL_PROVENANCE_REASONS[\n      `${input.kind}:${input.decision}` as keyof typeof EMAIL_PROVENANCE_REASONS\n    ],\n    actor: 'person',\n  }\n}\n\n/**\n * The `users/{uid}` fields a decision writes, as one merge-able object.\n *\n * `false` for a refusal, not a deleted field: absence is the third state and\n * means \"never asked\", which a person who said no must never read as again.\n */\nexport function platformMarketingUserFields(input: {\n  decision: PlatformMarketingConsentDecision\n  atMs: number\n  source: MarketingConsentSource\n}): Record<string, unknown> {\n  return {\n    [USER_MARKETING_CONSENT_FIELD]: input.decision === 'granted',\n    [USER_MARKETING_CONSENT_AT_FIELD]: input.atMs,\n    [USER_MARKETING_CONSENT_SOURCE_FIELD]: input.source,\n  }\n}\n"],"names":["EMAIL_TOPIC_PRODUCT_UPDATES","MARKETING_CONSENT_FIELD","MARKETING_CONSENT_SOURCE_FIELD","PLATFORM_BRAND_NAME","PLATFORM_MARKETING_TOPIC_ID","PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS","PLATFORM_MARKETING_EMAIL_SOURCE_KINDS","PLATFORM_MARKETING_CONSENT_SOURCE_KINDS","isPlatformMarketingConsentSourceKind","value","includes","isPlatformMarketingConsoleSourceKind","isPlatformMarketingEmailSourceKind","PLATFORM_MARKETING_CONSENT_DECISIONS","isPlatformMarketingConsentDecision","PLATFORM_MARKETING_CONSENT_TEXT_VERSION","platformMarketingConsentText","brandName","PLATFORM_MARKETING_CONSENT_TEXT","USER_MARKETING_CONSENT_FIELD","USER_MARKETING_CONSENT_AT_FIELD","USER_MARKETING_CONSENT_SOURCE_FIELD","USER_MARKETING_PROMPT_DISMISSED_AT_FIELD","PLATFORM_MARKETING_PROMPT_SNOOZE_MS","finiteOrNull","Number","isFinite","readPlatformMarketingConsent","document","consent","rawSource","source","Array","isArray","textVersion","decision","atMs","sourceKind","promptDismissedAtMs","platformMarketingPromptDue","state","nowMs","PROVENANCE_REASONS","granted","declined","platformMarketingConsentSource","input","kind","by","uid","reason","actor","EMAIL_PROVENANCE_REASONS","platformMarketingEmailSource","platformMarketingUserFields"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/platform-marketing-consent.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 * Marketing consent for the PLATFORM's own product email (AGL-3185).\n *\n * The strict policy (`marketing-consent.ts`) means a person with no declared\n * basis is unsendable, and until this module the only doors that declared\n * one were the marketing site's forms. Somebody who created a console account\n * — the warmest audience the platform has — was never asked. Three console\n * doors ask now: a checkbox on the sign-up form, a switch in the account\n * preferences, and a one-time prompt for accounts that predate the checkbox.\n *\n * ## One wording, versioned\n *\n * Every door shows {@link PLATFORM_MARKETING_CONSENT_TEXT} and every record\n * stores {@link PLATFORM_MARKETING_CONSENT_TEXT_VERSION} beside the exact\n * timestamp, so \"what did this person agree to\" is answered by a version and\n * not by whatever the checkbox says today. Changing the sentence is a bump of\n * the version in the same edit.\n *\n * ## The record lives in two places, and the two do not disagree\n *\n * The decision is written by the server onto the person's own `users/{uid}`\n * document, so the console can show a preference without reading the\n * operator's CRM, and onto the operator's marketing contact for the same\n * person, so the send path sees a declared basis with provenance. The\n * contact half is written only when the deployment names a marketing host\n * (`PLATFORM_MARKETING_HOST_ID`, read in `@aglyn/tenant-data-admin`); a\n * self-hosted install with no audience of its own records the preference\n * and skips the contact — and keeps asking, so the answers are already on\n * file the day the operator names a marketing host.\n *\n * ## An unsubscribe reaches the account, for its own list only (AGL-3305)\n *\n * The marketing site's emails carry their own way out, and a person who uses\n * it has answered the console's question too — but only if what they left\n * is the list the question was about. Leaving\n * {@link PLATFORM_MARKETING_TOPIC_ID}, or everything the site sends, turns\n * the account's answer to No through an email door; leaving the newsletter\n * leaves it alone. The email doors write the account and nothing else: the\n * site's lists already say what was left, and declining the contact's basis\n * would stop every list, not the one the person chose.\n *\n * ## Absence is not refusal\n *\n * An unticked sign-up checkbox records nothing. A switch turned off and a\n * prompt answered \"no\" record a refusal, which the strict policy already\n * honors. A prompt dismissed without an answer records only the dismissal,\n * and the prompt stays away for {@link PLATFORM_MARKETING_PROMPT_SNOOZE_MS}.\n *\n * Pure and dependency-light on purpose: the sign-up page renders the text,\n * the console route validates the body, and the server library writes the\n * record, all from this one module.\n */\n\nimport {\n  MARKETING_CONSENT_FIELD,\n  MARKETING_CONSENT_SOURCE_FIELD,\n  type MarketingConsentSource,\n} from './marketing-consent'\nimport { PLATFORM_BRAND_NAME } from './platform-brand'\n\n/**\n * The list the account's answer stands for on the marketing site (AGL-3305):\n * the built-in \"Product updates\" stream, which is what the platform's own\n * announcements are sent on. A wire value like every topic id — it keys the\n * opt-outs already recorded on the marketing host — and the same stream the\n * built-in catalog offers every site as \"Product updates\".\n *\n * Named so that \"which unsubscribe is about this answer\" has one spelling.\n * Leaving this list, or leaving everything the site sends, is a No to the\n * question the console asked. Leaving any other list is not, and must not\n * touch the answer: someone who stops the newsletter has said nothing about\n * product updates.\n */\nexport const PLATFORM_MARKETING_TOPIC_ID = 'product-updates'\n\n/** The console doors a decision can come through, as the record names them. */\nexport const PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS = [\n  'console-signup',\n  'console-preferences',\n  'console-prompt',\n] as const\n\nexport type PlatformMarketingConsoleSourceKind =\n  (typeof PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS)[number]\n\n/**\n * The email doors (AGL-3305): the marketing site's own unsubscribe,\n * preference and resubscribe pages, when what the person changed there was\n * {@link PLATFORM_MARKETING_TOPIC_ID} or everything.\n *\n * Kept apart from the console doors because nothing the console sends may\n * claim one. The server records these from the signed link a recipient\n * followed; a console request naming one is refused, because a click in the\n * console is not a click in a mailbox.\n */\nexport const PLATFORM_MARKETING_EMAIL_SOURCE_KINDS = [\n  'email-unsubscribe',\n  'email-preferences',\n  'email-resubscribe',\n] as const\n\nexport type PlatformMarketingEmailSourceKind =\n  (typeof PLATFORM_MARKETING_EMAIL_SOURCE_KINDS)[number]\n\n/** Every door a stored decision can name. */\nexport const PLATFORM_MARKETING_CONSENT_SOURCE_KINDS = [\n  ...PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS,\n  ...PLATFORM_MARKETING_EMAIL_SOURCE_KINDS,\n] as const\n\nexport type PlatformMarketingConsentSourceKind =\n  (typeof PLATFORM_MARKETING_CONSENT_SOURCE_KINDS)[number]\n\n/** Any door, for READING a stored decision. */\nexport function isPlatformMarketingConsentSourceKind(\n  value: unknown,\n): value is PlatformMarketingConsentSourceKind {\n  return (PLATFORM_MARKETING_CONSENT_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** A console door: the only kind a console request may record. */\nexport function isPlatformMarketingConsoleSourceKind(\n  value: unknown,\n): value is PlatformMarketingConsoleSourceKind {\n  return (PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** An email door: a decision made from a link in one of the site's emails. */\nexport function isPlatformMarketingEmailSourceKind(\n  value: unknown,\n): value is PlatformMarketingEmailSourceKind {\n  return (PLATFORM_MARKETING_EMAIL_SOURCE_KINDS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/** What a door records: a grant or a refusal. Absence is never recorded. */\nexport const PLATFORM_MARKETING_CONSENT_DECISIONS = ['granted', 'declined'] as const\n\nexport type PlatformMarketingConsentDecision =\n  (typeof PLATFORM_MARKETING_CONSENT_DECISIONS)[number]\n\nexport function isPlatformMarketingConsentDecision(\n  value: unknown,\n): value is PlatformMarketingConsentDecision {\n  return (PLATFORM_MARKETING_CONSENT_DECISIONS as readonly unknown[]).includes(\n    value,\n  )\n}\n\n/**\n * The version of the consent wording every door shows. Bumped in the same\n * edit as {@link platformMarketingConsentText}; a record stores the version\n * it was shown under, so the two must move together.\n */\nexport const PLATFORM_MARKETING_CONSENT_TEXT_VERSION = '2026-09-20'\n\n/**\n * The sentence the person agrees to, with the deployment's brand in it.\n *\n * Affirmative and standalone: it names what is sent, who sends it, and that\n * it can be stopped — never bundled with the terms acceptance, and never\n * pre-ticked anywhere it is rendered.\n */\nexport function platformMarketingConsentText(brandName: string): string {\n  return `Send me product updates from ${brandName}. You can opt out any time.`\n}\n\n/** {@link platformMarketingConsentText} for the brand this deployment wears. */\nexport const PLATFORM_MARKETING_CONSENT_TEXT = platformMarketingConsentText(\n  PLATFORM_BRAND_NAME,\n)\n\n/**\n * The `users/{uid}` fields the decision is mirrored onto.\n *\n * The same names the contact record uses for the same facts, so one reader\n * can parse either document. The prompt-dismissal stamp has no contact\n * counterpart: it is about what the console asked, not what the person\n * agreed to.\n */\nexport const USER_MARKETING_CONSENT_FIELD = MARKETING_CONSENT_FIELD\nexport const USER_MARKETING_CONSENT_AT_FIELD = 'marketingConsentAtMs'\nexport const USER_MARKETING_CONSENT_SOURCE_FIELD = MARKETING_CONSENT_SOURCE_FIELD\nexport const USER_MARKETING_PROMPT_DISMISSED_AT_FIELD =\n  'marketingConsentPromptDismissedAtMs'\n\n/** How long a dismissed prompt stays away: ninety days. */\nexport const PLATFORM_MARKETING_PROMPT_SNOOZE_MS = 90 * 24 * 60 * 60 * 1000\n\n/** What the person's own document says about product email. */\nexport interface PlatformMarketingConsentState {\n  /** `null` when nothing has been recorded — asked, but not answered. */\n  decision: PlatformMarketingConsentDecision | null\n  /** When the decision was recorded. */\n  atMs: number | null\n  /** The wording version the decision was made under. */\n  textVersion: string | null\n  /**\n   * Which door recorded it — a console door, or an email door for a decision\n   * mirrored from the marketing site's own pages. `null` for a record another\n   * writer left.\n   */\n  sourceKind: PlatformMarketingConsentSourceKind | null\n  /** When the prompt was last dismissed without an answer. */\n  promptDismissedAtMs: number | null\n}\n\nfunction finiteOrNull(value: unknown): number | null {\n  return typeof value === 'number' && Number.isFinite(value) ? value : null\n}\n\n/**\n * Reads the decision off a `users/{uid}` document, or off no document.\n *\n * Every unusable value reads as its absent case rather than throwing: a\n * malformed field must degrade to \"nothing recorded\", which asks again,\n * never to a grant.\n */\nexport function readPlatformMarketingConsent(\n  document: Record<string, unknown> | null | undefined,\n): PlatformMarketingConsentState {\n  const consent = document?.[USER_MARKETING_CONSENT_FIELD]\n  const rawSource = document?.[USER_MARKETING_CONSENT_SOURCE_FIELD]\n  const source =\n    rawSource && typeof rawSource === 'object' && !Array.isArray(rawSource)\n      ? (rawSource as Record<string, unknown>)\n      : null\n  const textVersion = source?.['textVersion']\n  return {\n    decision: consent === true ? 'granted' : consent === false ? 'declined' : null,\n    atMs: finiteOrNull(document?.[USER_MARKETING_CONSENT_AT_FIELD]),\n    textVersion:\n      typeof textVersion === 'string' && textVersion ? textVersion : null,\n    sourceKind: isPlatformMarketingConsentSourceKind(source?.['kind'])\n      ? source['kind']\n      : null,\n    promptDismissedAtMs: finiteOrNull(\n      document?.[USER_MARKETING_PROMPT_DISMISSED_AT_FIELD],\n    ),\n  }\n}\n\n/**\n * Whether the console should ask this person now.\n *\n * Never after a decision, in either direction: a \"no\" is an answer and a\n * \"yes\" needs no repeating. A dismissal is not an answer, so the prompt\n * returns once the snooze has run out.\n */\nexport function platformMarketingPromptDue(\n  state: Pick<PlatformMarketingConsentState, 'decision' | 'promptDismissedAtMs'>,\n  nowMs: number,\n): boolean {\n  if (state.decision !== null) return false\n  if (state.promptDismissedAtMs === null) return true\n  return nowMs - state.promptDismissedAtMs >= PLATFORM_MARKETING_PROMPT_SNOOZE_MS\n}\n\n/**\n * What each door did, in prose, for whoever audits the record later.\n *\n * Keyed by door and decision so the sentence is decided once, here, and the\n * three doors cannot describe the same act three different ways.\n */\nconst PROVENANCE_REASONS: Record<\n  PlatformMarketingConsoleSourceKind,\n  Record<PlatformMarketingConsentDecision, string>\n> = {\n  'console-signup': {\n    granted: 'Ticked the product-updates checkbox on the console sign-up form.',\n    declined: 'Declined product updates on the console sign-up form.',\n  },\n  'console-preferences': {\n    granted: 'Turned product updates on in the console account preferences.',\n    declined: 'Turned product updates off in the console account preferences.',\n  },\n  'console-prompt': {\n    granted: 'Answered yes to the product-updates prompt in the console.',\n    declined: 'Answered no to the product-updates prompt in the console.',\n  },\n}\n\n/**\n * The provenance stored with a console decision, on both documents.\n *\n * `actor: 'person'` is what keeps {@link MarketingConsentSource} honest here:\n * the reader treats provenance as an operator's assertion unless it says\n * otherwise, and this is the person's own click, carrying which door and\n * which wording. `by` is the account that clicked — the subject and the\n * actor are the same human, which is the fact the field records.\n */\nexport function platformMarketingConsentSource(input: {\n  kind: PlatformMarketingConsoleSourceKind\n  decision: PlatformMarketingConsentDecision\n  uid: string\n  atMs: number\n  textVersion: string\n}): MarketingConsentSource {\n  return {\n    kind: input.kind,\n    by: input.uid,\n    atMs: input.atMs,\n    reason: PROVENANCE_REASONS[input.kind][input.decision],\n    textVersion: input.textVersion,\n    actor: 'person',\n  }\n}\n\n/**\n * What an email door did, and which decisions each door can make.\n *\n * The pairs are the whole vocabulary: an unsubscribe only ever refuses, a\n * resubscribe only ever restores, and only the preference page does both.\n * Typed as the union rather than a free kind and decision, so an\n * \"unsubscribe that granted\" cannot be written down at all.\n */\nexport type PlatformMarketingEmailDecision =\n  | { kind: 'email-unsubscribe'; decision: 'declined' }\n  | { kind: 'email-preferences'; decision: PlatformMarketingConsentDecision }\n  | { kind: 'email-resubscribe'; decision: 'granted' }\n\nconst EMAIL_PROVENANCE_REASONS: {\n  [K in PlatformMarketingEmailDecision as `${K['kind']}:${K['decision']}`]: string\n} = {\n  'email-unsubscribe:declined':\n    'Unsubscribed from every email the marketing site sends, from a link in one of its emails.',\n  'email-preferences:declined':\n    'Left product updates on the marketing site’s email preference page.',\n  'email-preferences:granted':\n    'Chose product updates again on the marketing site’s email preference page.',\n  'email-resubscribe:granted':\n    'Resubscribed from the link in one of the marketing site’s emails.',\n}\n\n/**\n * The provenance stored with a decision mirrored from the marketing site's\n * own pages (AGL-3305), on the account only.\n *\n * Still `actor: 'person'`: the click was the recipient's, on a link signed\n * for their address. No `textVersion`, because those pages do not version\n * their wording; the field is absent rather than borrowing the console's\n * version for a sentence the person never saw.\n */\nexport function platformMarketingEmailSource(\n  input: PlatformMarketingEmailDecision & { uid: string; atMs: number },\n): MarketingConsentSource {\n  return {\n    kind: input.kind,\n    by: input.uid,\n    atMs: input.atMs,\n    // The union narrows the pair; the template type cannot see that, so the\n    // key is asserted to the table's own keys rather than widened to string.\n    reason: EMAIL_PROVENANCE_REASONS[\n      `${input.kind}:${input.decision}` as keyof typeof EMAIL_PROVENANCE_REASONS\n    ],\n    actor: 'person',\n  }\n}\n\n/**\n * The `users/{uid}` fields a decision writes, as one merge-able object.\n *\n * `false` for a refusal, not a deleted field: absence is the third state and\n * means \"never asked\", which a person who said no must never read as again.\n */\nexport function platformMarketingUserFields(input: {\n  decision: PlatformMarketingConsentDecision\n  atMs: number\n  source: MarketingConsentSource\n}): Record<string, unknown> {\n  return {\n    [USER_MARKETING_CONSENT_FIELD]: input.decision === 'granted',\n    [USER_MARKETING_CONSENT_AT_FIELD]: input.atMs,\n    [USER_MARKETING_CONSENT_SOURCE_FIELD]: input.source,\n  }\n}\n"],"names":["MARKETING_CONSENT_FIELD","MARKETING_CONSENT_SOURCE_FIELD","PLATFORM_BRAND_NAME","PLATFORM_MARKETING_TOPIC_ID","PLATFORM_MARKETING_CONSOLE_SOURCE_KINDS","PLATFORM_MARKETING_EMAIL_SOURCE_KINDS","PLATFORM_MARKETING_CONSENT_SOURCE_KINDS","isPlatformMarketingConsentSourceKind","value","includes","isPlatformMarketingConsoleSourceKind","isPlatformMarketingEmailSourceKind","PLATFORM_MARKETING_CONSENT_DECISIONS","isPlatformMarketingConsentDecision","PLATFORM_MARKETING_CONSENT_TEXT_VERSION","platformMarketingConsentText","brandName","PLATFORM_MARKETING_CONSENT_TEXT","USER_MARKETING_CONSENT_FIELD","USER_MARKETING_CONSENT_AT_FIELD","USER_MARKETING_CONSENT_SOURCE_FIELD","USER_MARKETING_PROMPT_DISMISSED_AT_FIELD","PLATFORM_MARKETING_PROMPT_SNOOZE_MS","finiteOrNull","Number","isFinite","readPlatformMarketingConsent","document","consent","rawSource","source","Array","isArray","textVersion","decision","atMs","sourceKind","promptDismissedAtMs","platformMarketingPromptDue","state","nowMs","PROVENANCE_REASONS","granted","declined","platformMarketingConsentSource","input","kind","by","uid","reason","actor","EMAIL_PROVENANCE_REASONS","platformMarketingEmailSource","platformMarketingUserFields"],"mappings":"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"}

package/src/lib/app-utils/plugin-api-rate-limit.d.ts

@@ -16,7 +16,8 @@
  */
 /**
  * Policy for the tenant plugin-API dispatcher's visitor-write rate limit
- * (AGL-1770). Pure and dependency-free so it is unit-testable without a route
+ * (AGL-1770). Pure but for one read of the route registry, for a route its
+ * plugin registered as a machine's, so it is unit-testable without a route
  * harness — the durable half lives in `@aglyn/tenant-data-admin` beside
  * `visitorWriteRefusal`, exactly like the lockdown split.
  *
@@ -76,6 +77,11 @@ export declare const VISITOR_WRITE_RATE_WINDOW_MS = 60000;
 /**
  * Is this dispatcher path a credentialed machine surface (exempt), rather
  * than a visitor one (limited)? Unknown paths are visitor by default.
+ *
+ * A path is a machine's when it is on the list above, or when the plugin
+ * that registered it declared it one (`machine: true`, AGL-3080) — the same
+ * polarity as the list: a route is exempt only by saying so, and one that
+ * forgot is limited, which fails loudly as a 429 its scheduler retries.
  */
 export declare function isMachinePluginApiPath(path: string): boolean;
 /**

package/src/lib/app-utils/plugin-api-rate-limit.js

@@ -13,9 +13,11 @@
  * 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 { isPluginMachineRoute } from "./api-plugins.js";
+/**
  * Policy for the tenant plugin-API dispatcher's visitor-write rate limit
- * (AGL-1770). Pure and dependency-free so it is unit-testable without a route
+ * (AGL-1770). Pure but for one read of the route registry, for a route its
+ * plugin registered as a machine's, so it is unit-testable without a route
  * harness — the durable half lives in `@aglyn/tenant-data-admin` beside
  * `visitorWriteRefusal`, exactly like the lockdown split.
  *
@@ -150,10 +152,16 @@
 /**
  * Is this dispatcher path a credentialed machine surface (exempt), rather
  * than a visitor one (limited)? Unknown paths are visitor by default.
+ *
+ * A path is a machine's when it is on the list above, or when the plugin
+ * that registered it declared it one (`machine: true`, AGL-3080) — the same
+ * polarity as the list: a route is exempt only by saying so, and one that
+ * forgot is limited, which fails loudly as a 429 its scheduler retries.
  */ export function isMachinePluginApiPath(path) {
     const normalized = normalize(path);
     if (MACHINE_API_PATHS.has(normalized)) return true;
-    return MACHINE_API_PREFIXES.some((prefix)=>normalized.startsWith(prefix));
+    if (MACHINE_API_PREFIXES.some((prefix)=>normalized.startsWith(prefix))) return true;
+    return isPluginMachineRoute(normalized);
 }
 /**
  * The limiter key: one bucket per (site, client IP).

package/src/lib/app-utils/plugin-api-rate-limit.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/plugin-api-rate-limit.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 * Policy for the tenant plugin-API dispatcher's visitor-write rate limit\n * (AGL-1770). Pure and dependency-free so it is unit-testable without a route\n * harness — the durable half lives in `@aglyn/tenant-data-admin` beside\n * `visitorWriteRefusal`, exactly like the lockdown split.\n *\n * ## What this bounds\n *\n * `apps/tenant/app/api/[...pluginApi]/route.ts` dispatches every plugin's\n * visitor-facing handler and, before this, applied no rate limit of any kind.\n * The gates it did have each refuse something narrower: per-site enablement is\n * skipped by an unresolvable `hostId`, the release gate only checks that the\n * plugin is on, and `visitorWriteRefusal` refuses only a paused or suspended\n * site. None of them bounds volume from a working, enabled site — which is\n * every live merchant.\n *\n * AGL-1769 closed the *shape* of the unauthenticated cart write (the caller\n * chose the document path) and was explicit that it did not bound the\n * *quantity*: \"id control never multiplied volume; it bought shape\". This is\n * the other half. The cost of the unbounded half lands in the merchant's own\n * Firestore — document count and storage on a tenant who did nothing wrong.\n */\n\n/**\n * 120 writes per minute per (site, client IP).\n *\n * Deliberately generous, and the reasoning matters more than the number: a\n * limit that trips on genuine use is worse than no limit, because it gets\n * raised until it means nothing. Measured against what the storefront actually\n * emits:\n *\n * - `cart.tsx:214` puts the line-quantity `TextField`'s `onChange` straight\n *   onto a POST with no debounce, so *typing* `100` into a quantity box is\n *   three cart writes. Editing a few lines is a genuine ten-to-twenty-write\n *   burst in a couple of seconds.\n * - `experiments/track` is an A/B beacon: one exposure write per experiment\n *   per page view, so a visitor clicking through pages at ~1/s with two live\n *   experiments sustains ~2 writes/s legitimately.\n * - Every visitor write on a site shares ONE budget (see the key below), so\n *   these add rather than each getting their own headroom.\n *\n * What a tighter number would actually buy is small. At 120/min a single\n * source can still mint ~172k documents a day against one site; at 30/min it\n * is ~43k. Neither is \"safe\" in absolute terms — what the cap buys is turning\n * a one-line flood script from *millions* per day into something that needs a\n * distributed botnet to stay interesting, and turning an incident from\n * instantaneous into detectable. That property is bought at 120 as well as at\n * 30, and 30 would refuse real shoppers.\n *\n * 120/60s is also `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` — the same\n * pair the public REST API enforces — so this adds no bespoke number.\n */\nexport const VISITOR_WRITE_RATE_LIMIT = 120\n\n/**\n * Fixed 60s window, matching every other limiter in the codebase rather than\n * improving on it. A fixed window admits up to 2× the cap across a boundary;\n * consistency with the shared bucket ids, the degradation markers and\n * `/api/health/rate-limits` is worth more here than closing that.\n */\nexport const VISITOR_WRITE_RATE_WINDOW_MS = 60_000\n\n/**\n * Machine-caller paths on EITHER plugin-API surface: neither dispatcher rate\n * limits these.\n *\n * The membership rule, so this list is decidable rather than a taste call: the\n * caller proves a shared secret, a webhook signature or a console session that\n * a visitor has no way to obtain, and its request volume is set by campaign\n * size or cron schedule rather than by human behaviour. A 120/min cap does not\n * merely inconvenience these — Resend delivering open/click webhooks for one\n * 50k-recipient campaign arrives from a handful of IPs for a single host and\n * would be shredded by any shopper-sized ceiling.\n *\n * ### Why a path list is right here when the dispatcher argues against them\n *\n * The lockdown gate two lines below is keyed by METHOD precisely to avoid a\n * path list, \"for the same reason `useSiteFetch` draws the Preview boundary\n * that way: a per-path list means thirteen handlers each remembering and the\n * fourteenth silently not.\"\n *\n * That argument turns on POLARITY, and this list has the opposite one. The\n * lockdown list would have enumerated what to *protect*, so a forgotten entry\n * is silently unprotected — the failure you never find. This enumerates what\n * to *exempt*, so the default is limited: a new visitor endpoint added\n * tomorrow is covered by doing nothing, and a forgotten machine endpoint\n * fails loudly and recoverably as 429s with `Retry-After` on a caller that\n * retries. Safe default, noisy mistake.\n *\n * Each entry, with the credential that makes it a machine caller:\n *\n * - `email/events` — Resend's webhook; `verifySvix` over `svix-id`/\n *   `svix-timestamp`/`svix-signature` against `RESEND_WEBHOOK_SECRET`.\n * - `campaigns/send` — a Firebase ID token with a host member role, or\n *   `CRON_SECRET` for the scheduled-send path.\n * - `bookings/reminders` — `x-cron-secret` against `CRON_SECRET`; refuses\n *   outright when it is unset.\n * - `hooks/…` — the merchant's per-hook secret in `x-aglyn-secret`, compared\n *   with `timingSafeEqual`. It already carries its own 30/min per-hook\n *   limiter, so exempting it here removes nothing.\n *\n * The four below are registered on the CONSOLE surface only, and each is a\n * chunked cron sweep rather than a single beat — `sweepConsoleCron` follows\n * `nextCursor` up to `CRON_SWEEP_MAX_CHUNKS` (50) POSTs per route per run,\n * from one Cloud Functions address, and the key below carries no path. Three\n * such routes on one beat is 150 requests in a minute against a single\n * bucket, so this exemption is load-bearing and not decorative:\n *\n * - `campaigns/process-scheduled` — `x-cron-secret` against `CRON_SECRET`;\n *   refuses outright when it is unset.\n * - `lists/materialize` — the same header, the same refusal.\n * - `commerce/process-abandoned` — the same header, the same refusal.\n * - `commerce/process-restock` — the same header, the same refusal.\n *\n * Note what is deliberately NOT exempt: presence of an `authorization` or\n * `svix-signature` HEADER. Header presence is not a credential — the\n * dispatcher cannot verify signatures it does not own, so exempting on the\n * header would let any caller skip the limiter by attaching a garbage one to\n * a cart POST.\n *\n * Nor is `commerce/supplier-update`, whose HMAC token makes it a machine\n * caller but whose volume is set by a supplier's own system rather than by a\n * schedule. It fails the second half of the membership rule, and the polarity\n * above says which way to resolve a borderline case: leave it limited, where\n * a mistake is a recoverable 429.\n */\nconst MACHINE_API_PATHS: ReadonlySet<string> = new Set([\n  'email/events',\n  'campaigns/send',\n  'bookings/reminders',\n  'campaigns/process-scheduled',\n  'lists/materialize',\n  'commerce/process-abandoned',\n  'commerce/process-restock',\n])\n\n/** Prefixes whose whole subtree is a machine surface (`hooks/{host}/{hook}`). */\nconst MACHINE_API_PREFIXES: readonly string[] = ['hooks/']\n\n/** Leading/trailing slashes stripped, matching `normalizeApiPath`. */\nfunction normalize(path: string): string {\n  return String(path ?? '').replace(/^\\/+|\\/+$/g, '')\n}\n\n/**\n * Is this dispatcher path a credentialed machine surface (exempt), rather\n * than a visitor one (limited)? Unknown paths are visitor by default.\n */\nexport function isMachinePluginApiPath(path: string): boolean {\n  const normalized = normalize(path)\n  if (MACHINE_API_PATHS.has(normalized)) return true\n  return MACHINE_API_PREFIXES.some((prefix) => normalized.startsWith(prefix))\n}\n\n/**\n * The limiter key: one bucket per (site, client IP).\n *\n * ## Why compound, and why NOT a second limiter in either direction\n *\n * **Per-site alone is rejected.** A single attacker would consume the whole\n * merchant's allowance and every real shopper would then be refused — an\n * attacker-triggered denial of service against the victim, cheaper to mount\n * than the flood it replaces and costing the merchant *sales* rather than\n * storage. That is strictly worse than the growth it guards.\n *\n * **Per-IP alone is rejected.** Trivially distributed, and it would let one\n * merchant's traffic spend another's budget.\n *\n * **Compound is what \"per-host and per-IP together\" should mean here.** Each\n * source is bounded on each site, and no source can affect another's budget,\n * so the ceiling a site is exposed to is (distinct source IPs) × 120/min —\n * the same shape legitimate traffic has. What it does not stop is a genuine\n * botnet, and that is stated rather than papered over: bounding *that* needs\n * an edge WAF, not an application limiter, and every application-level scheme\n * that would catch it (a site-wide ceiling) reintroduces the self-DoS above.\n *\n * **A second, platform-wide per-IP limiter was considered and dropped.** It\n * would bound one source sweeping many merchants, but costs a second\n * Firestore transaction on every storefront write — tripling the ops on a\n * legitimate add-to-cart — to bound an attack that the compound key already\n * prices at one full budget per merchant. One transaction per visitor write\n * is the established cost here (`forms/submit`, `protection/unlock`); two\n * would be novel and is not paid for by what it buys.\n *\n * The path is **not** in the key, on purpose: one shared budget per (site,\n * IP) across cart, reviews, newsletter, bookings and beacons. Keying per path\n * would let a caller multiply its allowance by cycling endpoints, which is\n * free to do and defeats the point.\n *\n * `hostId` is frequently `''` — the dispatcher only resolves one from the\n * query or a JSON body, and a handler that self-gates may supply none. It is\n * kept in the key rather than skipped: AGL-1769 named \"an unresolvable\n * `hostId` skips the gate\" as an existing hole, and a limiter that a caller\n * turns off by declining to name a site is not a limiter. Host-less writes\n * simply share one bucket per IP.\n */\nexport function visitorWriteRateLimitKey(hostId: string, ip: string): string {\n  return `pluginwrite:${hostId || '-'}:${ip || 'unknown'}`\n}\n\n/**\n * Policy for the CONSOLE plugin-API dispatcher's write rate limit.\n *\n * `apps/console/app/api/[...pluginApi]/route.ts` dispatches every plugin's\n * console-facing handler — the marketplace installs and publishes, `ai/assist`,\n * gift cards, POS orders, refunds, the email list previews and the suppression\n * writes — and it carries no limiter of any kind. Its gates each refuse\n * something narrower: per-site enablement needs a resolvable `hostId`, the\n * release flag only asks whether the plugin is on, and lockdown only refuses\n * during an incident. None of them bounds volume from an ordinary signed-in\n * operator, which is every request the surface serves.\n *\n * The exposure is not the same one the visitor limiter closes. These handlers\n * are authenticated, so nobody is minting documents anonymously; what they do\n * instead is spend REAL money per call — a contact scan with a read budget, a\n * bundle download and verify, a model call to a paid vendor — on a surface\n * where a stuck retry loop in one console tab is indistinguishable from abuse.\n */\n\n/**\n * 120 requests per minute per console subject.\n *\n * `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` again, and the same pair the\n * visitor limiter and the public REST API use, so this introduces no bespoke\n * number to reason about. It is far above a person pressing buttons: the\n * costly routes on this surface are one-per-click, and the console's own\n * page-load traffic reaches Firestore through the client SDK rather than\n * through this dispatcher.\n *\n * Deliberately not tighter even though each call here costs more than a cart\n * write. A limit that trips on genuine use gets raised until it means nothing,\n * and the per-call cost is the wrong lever for that anyway — an entitlement or\n * a quota bounds spend per org over a month, where this bounds a runaway loop\n * over a minute. Two different jobs; this one only has to make the loop stop.\n */\nexport const CONSOLE_API_RATE_LIMIT = 120\n\n/** Fixed 60s window, matching every other limiter in the codebase. */\nexport const CONSOLE_API_RATE_WINDOW_MS = 60_000\n\n/**\n * The limiter key: one bucket per authenticated subject.\n *\n * ## Why this is NOT the visitor key\n *\n * `visitorWriteRateLimitKey` is compound because its surface is\n * unauthenticated, and both halves of that argument are answers to anonymity.\n * Per-site alone was rejected there because one attacker would spend a whole\n * merchant's allowance and refuse real shoppers — an attacker-triggered denial\n * of service against the victim. On the console the subject is a verified\n * `uid`, so a caller can only ever refuse ITSELF: the self-DoS the compound key\n * exists to prevent cannot be aimed at anyone else, and the isolation it buys\n * is already bought by the identity.\n *\n * `hostId` is therefore left OUT rather than added, which is the opposite of\n * the visitor key and for the reason the visitor key leaves the PATH out: an\n * operator with fifty sites would otherwise hold fifty budgets and could\n * multiply its allowance by cycling a field it controls. One person is one\n * budget across every site they can reach.\n *\n * ## The unauthenticated fallback\n *\n * A caller whose bearer token did not decode — a plugin key, a POS device, an\n * anonymous probe — has no `uid`, and its client address stands in. That\n * bucket is shared by every such caller behind one address, which is the\n * conservative direction: an unidentified caller on an authenticated surface\n * should not get a private allowance for declining to identify itself. Keeping\n * it counted at all is the point. A limiter a caller switches off by sending\n * no credential is not a limiter, and this surface's whole exposure is what\n * runs BEFORE a handler decides who is asking.\n */\nexport function consoleApiRateLimitKey(subject: string): string {\n  return `consoleapi:${subject || 'unknown'}`\n}\n"],"names":["VISITOR_WRITE_RATE_LIMIT","VISITOR_WRITE_RATE_WINDOW_MS","MACHINE_API_PATHS","Set","MACHINE_API_PREFIXES","normalize","path","String","replace","isMachinePluginApiPath","normalized","has","some","prefix","startsWith","visitorWriteRateLimitKey","hostId","ip","CONSOLE_API_RATE_LIMIT","CONSOLE_API_RATE_WINDOW_MS","consoleApiRateLimitKey","subject"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMA,2BAA2B,IAAG;AAE3C;;;;;CAKC,GACD,OAAO,MAAMC,+BAA+B,MAAM;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DC,GACD,MAAMC,oBAAyC,IAAIC,IAAI;IACrD;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,+EAA+E,GAC/E,MAAMC,uBAA0C;IAAC;CAAS;AAE1D,oEAAoE,GACpE,SAASC,UAAUC,IAAY;IAC7B,OAAOC,OAAOD,eAAAA,OAAQ,IAAIE,OAAO,CAAC,cAAc;AAClD;AAEA;;;CAGC,GACD,OAAO,SAASC,uBAAuBH,IAAY;IACjD,MAAMI,aAAaL,UAAUC;IAC7B,IAAIJ,kBAAkBS,GAAG,CAACD,aAAa,OAAO;IAC9C,OAAON,qBAAqBQ,IAAI,CAAC,CAACC,SAAWH,WAAWI,UAAU,CAACD;AACrE;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GACD,OAAO,SAASE,yBAAyBC,MAAc,EAAEC,EAAU;IACjE,OAAO,CAAC,YAAY,EAAED,UAAU,IAAI,CAAC,EAAEC,MAAM,WAAW;AAC1D;AAEA;;;;;;;;;;;;;;;;;CAiBC,GAED;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,yBAAyB,IAAG;AAEzC,oEAAoE,GACpE,OAAO,MAAMC,6BAA6B,MAAM;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASC,uBAAuBC,OAAe;IACpD,OAAO,CAAC,WAAW,EAAEA,WAAW,WAAW;AAC7C"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/plugin-api-rate-limit.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 { isPluginMachineRoute } from './api-plugins'\n\n/**\n * Policy for the tenant plugin-API dispatcher's visitor-write rate limit\n * (AGL-1770). Pure but for one read of the route registry, for a route its\n * plugin registered as a machine's, so it is unit-testable without a route\n * harness — the durable half lives in `@aglyn/tenant-data-admin` beside\n * `visitorWriteRefusal`, exactly like the lockdown split.\n *\n * ## What this bounds\n *\n * `apps/tenant/app/api/[...pluginApi]/route.ts` dispatches every plugin's\n * visitor-facing handler and, before this, applied no rate limit of any kind.\n * The gates it did have each refuse something narrower: per-site enablement is\n * skipped by an unresolvable `hostId`, the release gate only checks that the\n * plugin is on, and `visitorWriteRefusal` refuses only a paused or suspended\n * site. None of them bounds volume from a working, enabled site — which is\n * every live merchant.\n *\n * AGL-1769 closed the *shape* of the unauthenticated cart write (the caller\n * chose the document path) and was explicit that it did not bound the\n * *quantity*: \"id control never multiplied volume; it bought shape\". This is\n * the other half. The cost of the unbounded half lands in the merchant's own\n * Firestore — document count and storage on a tenant who did nothing wrong.\n */\n\n/**\n * 120 writes per minute per (site, client IP).\n *\n * Deliberately generous, and the reasoning matters more than the number: a\n * limit that trips on genuine use is worse than no limit, because it gets\n * raised until it means nothing. Measured against what the storefront actually\n * emits:\n *\n * - `cart.tsx:214` puts the line-quantity `TextField`'s `onChange` straight\n *   onto a POST with no debounce, so *typing* `100` into a quantity box is\n *   three cart writes. Editing a few lines is a genuine ten-to-twenty-write\n *   burst in a couple of seconds.\n * - `experiments/track` is an A/B beacon: one exposure write per experiment\n *   per page view, so a visitor clicking through pages at ~1/s with two live\n *   experiments sustains ~2 writes/s legitimately.\n * - Every visitor write on a site shares ONE budget (see the key below), so\n *   these add rather than each getting their own headroom.\n *\n * What a tighter number would actually buy is small. At 120/min a single\n * source can still mint ~172k documents a day against one site; at 30/min it\n * is ~43k. Neither is \"safe\" in absolute terms — what the cap buys is turning\n * a one-line flood script from *millions* per day into something that needs a\n * distributed botnet to stay interesting, and turning an incident from\n * instantaneous into detectable. That property is bought at 120 as well as at\n * 30, and 30 would refuse real shoppers.\n *\n * 120/60s is also `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` — the same\n * pair the public REST API enforces — so this adds no bespoke number.\n */\nexport const VISITOR_WRITE_RATE_LIMIT = 120\n\n/**\n * Fixed 60s window, matching every other limiter in the codebase rather than\n * improving on it. A fixed window admits up to 2× the cap across a boundary;\n * consistency with the shared bucket ids, the degradation markers and\n * `/api/health/rate-limits` is worth more here than closing that.\n */\nexport const VISITOR_WRITE_RATE_WINDOW_MS = 60_000\n\n/**\n * Machine-caller paths on EITHER plugin-API surface: neither dispatcher rate\n * limits these.\n *\n * The membership rule, so this list is decidable rather than a taste call: the\n * caller proves a shared secret, a webhook signature or a console session that\n * a visitor has no way to obtain, and its request volume is set by campaign\n * size or cron schedule rather than by human behaviour. A 120/min cap does not\n * merely inconvenience these — Resend delivering open/click webhooks for one\n * 50k-recipient campaign arrives from a handful of IPs for a single host and\n * would be shredded by any shopper-sized ceiling.\n *\n * ### Why a path list is right here when the dispatcher argues against them\n *\n * The lockdown gate two lines below is keyed by METHOD precisely to avoid a\n * path list, \"for the same reason `useSiteFetch` draws the Preview boundary\n * that way: a per-path list means thirteen handlers each remembering and the\n * fourteenth silently not.\"\n *\n * That argument turns on POLARITY, and this list has the opposite one. The\n * lockdown list would have enumerated what to *protect*, so a forgotten entry\n * is silently unprotected — the failure you never find. This enumerates what\n * to *exempt*, so the default is limited: a new visitor endpoint added\n * tomorrow is covered by doing nothing, and a forgotten machine endpoint\n * fails loudly and recoverably as 429s with `Retry-After` on a caller that\n * retries. Safe default, noisy mistake.\n *\n * Each entry, with the credential that makes it a machine caller:\n *\n * - `email/events` — Resend's webhook; `verifySvix` over `svix-id`/\n *   `svix-timestamp`/`svix-signature` against `RESEND_WEBHOOK_SECRET`.\n * - `campaigns/send` — a Firebase ID token with a host member role, or\n *   `CRON_SECRET` for the scheduled-send path.\n * - `bookings/reminders` — `x-cron-secret` against `CRON_SECRET`; refuses\n *   outright when it is unset.\n * - `hooks/…` — the merchant's per-hook secret in `x-aglyn-secret`, compared\n *   with `timingSafeEqual`. It already carries its own 30/min per-hook\n *   limiter, so exempting it here removes nothing.\n *\n * The four below are registered on the CONSOLE surface only, and each is a\n * chunked cron sweep rather than a single beat — `sweepConsoleCron` follows\n * `nextCursor` up to `CRON_SWEEP_MAX_CHUNKS` (50) POSTs per route per run,\n * from one Cloud Functions address, and the key below carries no path. Three\n * such routes on one beat is 150 requests in a minute against a single\n * bucket, so this exemption is load-bearing and not decorative:\n *\n * - `campaigns/process-scheduled` — `x-cron-secret` against `CRON_SECRET`;\n *   refuses outright when it is unset.\n * - `lists/materialize` — the same header, the same refusal.\n * - `commerce/process-abandoned` — the same header, the same refusal.\n * - `commerce/process-restock` — the same header, the same refusal.\n *\n * Note what is deliberately NOT exempt: presence of an `authorization` or\n * `svix-signature` HEADER. Header presence is not a credential — the\n * dispatcher cannot verify signatures it does not own, so exempting on the\n * header would let any caller skip the limiter by attaching a garbage one to\n * a cart POST.\n *\n * Nor is `commerce/supplier-update`, whose HMAC token makes it a machine\n * caller but whose volume is set by a supplier's own system rather than by a\n * schedule. It fails the second half of the membership rule, and the polarity\n * above says which way to resolve a borderline case: leave it limited, where\n * a mistake is a recoverable 429.\n */\nconst MACHINE_API_PATHS: ReadonlySet<string> = new Set([\n  'email/events',\n  'campaigns/send',\n  'bookings/reminders',\n  'campaigns/process-scheduled',\n  'lists/materialize',\n  'commerce/process-abandoned',\n  'commerce/process-restock',\n])\n\n/** Prefixes whose whole subtree is a machine surface (`hooks/{host}/{hook}`). */\nconst MACHINE_API_PREFIXES: readonly string[] = ['hooks/']\n\n/** Leading/trailing slashes stripped, matching `normalizeApiPath`. */\nfunction normalize(path: string): string {\n  return String(path ?? '').replace(/^\\/+|\\/+$/g, '')\n}\n\n/**\n * Is this dispatcher path a credentialed machine surface (exempt), rather\n * than a visitor one (limited)? Unknown paths are visitor by default.\n *\n * A path is a machine's when it is on the list above, or when the plugin\n * that registered it declared it one (`machine: true`, AGL-3080) — the same\n * polarity as the list: a route is exempt only by saying so, and one that\n * forgot is limited, which fails loudly as a 429 its scheduler retries.\n */\nexport function isMachinePluginApiPath(path: string): boolean {\n  const normalized = normalize(path)\n  if (MACHINE_API_PATHS.has(normalized)) return true\n  if (MACHINE_API_PREFIXES.some((prefix) => normalized.startsWith(prefix))) return true\n  return isPluginMachineRoute(normalized)\n}\n\n/**\n * The limiter key: one bucket per (site, client IP).\n *\n * ## Why compound, and why NOT a second limiter in either direction\n *\n * **Per-site alone is rejected.** A single attacker would consume the whole\n * merchant's allowance and every real shopper would then be refused — an\n * attacker-triggered denial of service against the victim, cheaper to mount\n * than the flood it replaces and costing the merchant *sales* rather than\n * storage. That is strictly worse than the growth it guards.\n *\n * **Per-IP alone is rejected.** Trivially distributed, and it would let one\n * merchant's traffic spend another's budget.\n *\n * **Compound is what \"per-host and per-IP together\" should mean here.** Each\n * source is bounded on each site, and no source can affect another's budget,\n * so the ceiling a site is exposed to is (distinct source IPs) × 120/min —\n * the same shape legitimate traffic has. What it does not stop is a genuine\n * botnet, and that is stated rather than papered over: bounding *that* needs\n * an edge WAF, not an application limiter, and every application-level scheme\n * that would catch it (a site-wide ceiling) reintroduces the self-DoS above.\n *\n * **A second, platform-wide per-IP limiter was considered and dropped.** It\n * would bound one source sweeping many merchants, but costs a second\n * Firestore transaction on every storefront write — tripling the ops on a\n * legitimate add-to-cart — to bound an attack that the compound key already\n * prices at one full budget per merchant. One transaction per visitor write\n * is the established cost here (`forms/submit`, `protection/unlock`); two\n * would be novel and is not paid for by what it buys.\n *\n * The path is **not** in the key, on purpose: one shared budget per (site,\n * IP) across cart, reviews, newsletter, bookings and beacons. Keying per path\n * would let a caller multiply its allowance by cycling endpoints, which is\n * free to do and defeats the point.\n *\n * `hostId` is frequently `''` — the dispatcher only resolves one from the\n * query or a JSON body, and a handler that self-gates may supply none. It is\n * kept in the key rather than skipped: AGL-1769 named \"an unresolvable\n * `hostId` skips the gate\" as an existing hole, and a limiter that a caller\n * turns off by declining to name a site is not a limiter. Host-less writes\n * simply share one bucket per IP.\n */\nexport function visitorWriteRateLimitKey(hostId: string, ip: string): string {\n  return `pluginwrite:${hostId || '-'}:${ip || 'unknown'}`\n}\n\n/**\n * Policy for the CONSOLE plugin-API dispatcher's write rate limit.\n *\n * `apps/console/app/api/[...pluginApi]/route.ts` dispatches every plugin's\n * console-facing handler — the marketplace installs and publishes, `ai/assist`,\n * gift cards, POS orders, refunds, the email list previews and the suppression\n * writes — and it carries no limiter of any kind. Its gates each refuse\n * something narrower: per-site enablement needs a resolvable `hostId`, the\n * release flag only asks whether the plugin is on, and lockdown only refuses\n * during an incident. None of them bounds volume from an ordinary signed-in\n * operator, which is every request the surface serves.\n *\n * The exposure is not the same one the visitor limiter closes. These handlers\n * are authenticated, so nobody is minting documents anonymously; what they do\n * instead is spend REAL money per call — a contact scan with a read budget, a\n * bundle download and verify, a model call to a paid vendor — on a surface\n * where a stuck retry loop in one console tab is indistinguishable from abuse.\n */\n\n/**\n * 120 requests per minute per console subject.\n *\n * `DEFAULT_RATE_LIMIT` / `DEFAULT_RATE_WINDOW_MS` again, and the same pair the\n * visitor limiter and the public REST API use, so this introduces no bespoke\n * number to reason about. It is far above a person pressing buttons: the\n * costly routes on this surface are one-per-click, and the console's own\n * page-load traffic reaches Firestore through the client SDK rather than\n * through this dispatcher.\n *\n * Deliberately not tighter even though each call here costs more than a cart\n * write. A limit that trips on genuine use gets raised until it means nothing,\n * and the per-call cost is the wrong lever for that anyway — an entitlement or\n * a quota bounds spend per org over a month, where this bounds a runaway loop\n * over a minute. Two different jobs; this one only has to make the loop stop.\n */\nexport const CONSOLE_API_RATE_LIMIT = 120\n\n/** Fixed 60s window, matching every other limiter in the codebase. */\nexport const CONSOLE_API_RATE_WINDOW_MS = 60_000\n\n/**\n * The limiter key: one bucket per authenticated subject.\n *\n * ## Why this is NOT the visitor key\n *\n * `visitorWriteRateLimitKey` is compound because its surface is\n * unauthenticated, and both halves of that argument are answers to anonymity.\n * Per-site alone was rejected there because one attacker would spend a whole\n * merchant's allowance and refuse real shoppers — an attacker-triggered denial\n * of service against the victim. On the console the subject is a verified\n * `uid`, so a caller can only ever refuse ITSELF: the self-DoS the compound key\n * exists to prevent cannot be aimed at anyone else, and the isolation it buys\n * is already bought by the identity.\n *\n * `hostId` is therefore left OUT rather than added, which is the opposite of\n * the visitor key and for the reason the visitor key leaves the PATH out: an\n * operator with fifty sites would otherwise hold fifty budgets and could\n * multiply its allowance by cycling a field it controls. One person is one\n * budget across every site they can reach.\n *\n * ## The unauthenticated fallback\n *\n * A caller whose bearer token did not decode — a plugin key, a POS device, an\n * anonymous probe — has no `uid`, and its client address stands in. That\n * bucket is shared by every such caller behind one address, which is the\n * conservative direction: an unidentified caller on an authenticated surface\n * should not get a private allowance for declining to identify itself. Keeping\n * it counted at all is the point. A limiter a caller switches off by sending\n * no credential is not a limiter, and this surface's whole exposure is what\n * runs BEFORE a handler decides who is asking.\n */\nexport function consoleApiRateLimitKey(subject: string): string {\n  return `consoleapi:${subject || 'unknown'}`\n}\n"],"names":["isPluginMachineRoute","VISITOR_WRITE_RATE_LIMIT","VISITOR_WRITE_RATE_WINDOW_MS","MACHINE_API_PATHS","Set","MACHINE_API_PREFIXES","normalize","path","String","replace","isMachinePluginApiPath","normalized","has","some","prefix","startsWith","visitorWriteRateLimitKey","hostId","ip","CONSOLE_API_RATE_LIMIT","CONSOLE_API_RATE_WINDOW_MS","consoleApiRateLimitKey","subject"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,oBAAoB,QAAQ,mBAAe;AAEpD;;;;;;;;;;;;;;;;;;;;;;CAsBC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,2BAA2B,IAAG;AAE3C;;;;;CAKC,GACD,OAAO,MAAMC,+BAA+B,MAAM;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DC,GACD,MAAMC,oBAAyC,IAAIC,IAAI;IACrD;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AAED,+EAA+E,GAC/E,MAAMC,uBAA0C;IAAC;CAAS;AAE1D,oEAAoE,GACpE,SAASC,UAAUC,IAAY;IAC7B,OAAOC,OAAOD,eAAAA,OAAQ,IAAIE,OAAO,CAAC,cAAc;AAClD;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASC,uBAAuBH,IAAY;IACjD,MAAMI,aAAaL,UAAUC;IAC7B,IAAIJ,kBAAkBS,GAAG,CAACD,aAAa,OAAO;IAC9C,IAAIN,qBAAqBQ,IAAI,CAAC,CAACC,SAAWH,WAAWI,UAAU,CAACD,UAAU,OAAO;IACjF,OAAOd,qBAAqBW;AAC9B;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyCC,GACD,OAAO,SAASK,yBAAyBC,MAAc,EAAEC,EAAU;IACjE,OAAO,CAAC,YAAY,EAAED,UAAU,IAAI,CAAC,EAAEC,MAAM,WAAW;AAC1D;AAEA;;;;;;;;;;;;;;;;;CAiBC,GAED;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,yBAAyB,IAAG;AAEzC,oEAAoE,GACpE,OAAO,MAAMC,6BAA6B,MAAM;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASC,uBAAuBC,OAAe;IACpD,OAAO,CAAC,WAAW,EAAEA,WAAW,WAAW;AAC7C"}

package/src/lib/app-utils/plugin-bundle-checks.js

@@ -496,11 +496,11 @@ const BASE64_BLOB = /^[A-Za-z0-9+/\r\n]+={0,2}$/;
     };
     missing('the site component', (_found_site = found.site) == null ? void 0 : _found_site.components, (_declared_site = declared.site) == null ? void 0 : _declared_site.components, 'a published page that places it would never load the plugin');
     missing('the site feature', (_found_site1 = found.site) == null ? void 0 : _found_site1.features, (_declared_site1 = declared.site) == null ? void 0 : _declared_site1.features, 'no published page would ever load the plugin to run it');
-    missing('a widget in the console slot', (_found_console = found.console) == null ? void 0 : _found_console.slots, (_declared_console = declared.console) == null ? void 0 : _declared_console.slots, 'a screen that renders the slot would never load the plugin');
+    missing('a widget in the console slot', (_found_console = found.console) == null ? void 0 : _found_console.slots, (_declared_console = declared.console) == null ? void 0 : _declared_console.slots, 'a console page that renders the slot would never load the plugin');
     missing('the console route', (_found_console1 = found.console) == null ? void 0 : _found_console1.routes, (_declared_console1 = declared.console) == null ? void 0 : _declared_console1.routes, 'the route would not find the plugin that serves it');
     missing('the console organization route', (_found_console2 = found.console) == null ? void 0 : _found_console2.orgRoutes, (_declared_console2 = declared.console) == null ? void 0 : _declared_console2.orgRoutes, 'the route would not find the plugin that serves it');
     if (((_found_console3 = found.console) == null ? void 0 : _found_console3.shell) && !((_declared_console3 = declared.console) == null ? void 0 : _declared_console3.shell)) {
-        add('error', 'contributions', 'register() adds a nav tab, a provider or another entry the console ' + 'shell draws on every screen, and the manifest does not declare ' + '"console": { "shell": true } — the shell would draw it only on ' + 'screens that happened to load the plugin for something else');
+        add('error', 'contributions', 'register() adds a nav tab, a provider or another entry the console ' + 'shell draws on every page, and the manifest does not declare ' + '"console": { "shell": true } — the shell would draw it only on ' + 'pages that happened to load the plugin for something else');
     }
     if (detected.unresolved.length) {
         add('warning', 'contributions', `the checker could not read ${detected.unresolved.join('; ')} — ` + 'confirm the declaration covers what it registers');