@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/operator-identity.js

@@ -0,0 +1,186 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Who runs *this* deployment, and where its notices go (AGL-2016).
+ *
+ * the rule for the self-host path: *"the self hosted owner should probably
+ * not have to edit the source to update aglyn branded items urls or personal
+ * identification items, should probably move these to env vars"*. This module
+ * is that, for the one class of value where getting it wrong is not cosmetic —
+ * the identity a legal notice is addressed to.
+ *
+ * ## The defect this exists to close
+ *
+ * `ABUSE_REPORT_CONTACT_EMAIL` was `'support@aglyn.com'`, a bare literal, and
+ * it rendered on the **public, unauthenticated** abuse-report form that every
+ * deployment ships. So a self-hoster running their own Firebase published a
+ * DMCA/abuse intake instructing third-party reporters to send statutory
+ * notices to **Aglyn** — about content Aglyn does not host, cannot see and
+ * cannot remove.
+ *
+ * That is wrong in both directions at once. The reporter's notice goes to a
+ * desk with no ability to act on it while their clock runs, and Aglyn is made
+ * to look like it holds a takedown duty for a site it does not operate.
+ * §512's obligations attach to the entity that actually hosts and controls the
+ * material, which on a self-host install is the operator and nobody else.
+ *
+ * ## Why the default is EMPTY, and not our address
+ *
+ * AGL-2016 originally proposed our address as the default "so Aglyn's own
+ * deployment is unchanged". That is the wrong default *for this value*, and
+ * the distinction is worth stating because the sibling fixes went the other
+ * way and were right to.
+ *
+ * `TENANT_PRODUCTION_ROOT` (AGL-2022) defaults to `aglyn.app`, and an operator
+ * who does not set it gets links that are merely *wrong* — visibly, on the
+ * first click, in their own console. A contact address that defaults to ours
+ * fails **silently and off-site**: nothing in the operator's product looks
+ * broken, and the only party who learns is a copyright holder whose notice
+ * landed with a stranger. A wrong default that is invisible to the person who
+ * could fix it is not a default, it is a trap.
+ *
+ * So: absent is a first-class state, exactly as AGL-2021 established for the
+ * Texas registration identifiers, and for the same reason — an explicit
+ * "not configured" beats a blank that reads as an address, and beats a
+ * plausible-looking value that reads as fact. The cost is that Aglyn's own
+ * deployment must now configure these like any other operator. That is the
+ * point: it is what makes this configuration rather than a rename.
+ *
+ * ## Why `NEXT_PUBLIC_`, and why dot notation is load-bearing
+ *
+ * Every value here is printed to the public — that is what it is *for* — so
+ * `NEXT_PUBLIC_` carries no disclosure risk, unlike AGL-2021's staff-gated
+ * identifiers, which are deliberately server-only.
+ *
+ * Next inlines `NEXT_PUBLIC_*` into the browser bundle by textually
+ * substituting `process.env.NAME`. The **bracket** form is never substituted
+ * and reads `undefined` in the browser. AGL-2037 is that bug live in
+ * `tenant-dns.ts`; AGL-2022's `tenant-links.ts` is the corrected reference.
+ * Every read below is dot notation on purpose — do not "tidy" it to brackets,
+ * and do not introduce a parallel server-only `OPERATOR_*` name: AGL-733 is
+ * the record of what happens when one value acquires two env names.
+ *
+ * Note the build-time consequence for self-hosters: `NEXT_PUBLIC_*` is baked
+ * in when the image is built, so these must be set *before* `docker compose
+ * build`, not merely before `up`. `docs/SELF_HOSTING.md` says so.
+ *
+ * ## Empty vs whitespace
+ *
+ * `'   '` is the shape a half-finished `.env` actually takes and it satisfies
+ * a truthiness check. Every read is trimmed and treated as absent, so a
+ * half-finished file cannot produce a mailto with nothing behind it.
+ */ /** The entity operating this deployment, as far as configuration knows. */ /**
+ * What a surface prints where an operator address would go when the
+ * deployment has not configured one.
+ *
+ * NOT an empty string, and NOT a plausible placeholder. A blank in a contact
+ * slot reads as "nobody filled it in yet" — harmless on a settings screen,
+ * actively misleading on a page whose entire job is to tell a copyright
+ * holder where to send a statutory notice. Same argument, same shape, as
+ * AGL-2021's `TX_REGISTRATION_UNSET`: say what is true and name the fix.
+ */ export const OPERATOR_CONTACT_UNSET = 'not configured — this deployment has published no contact address';
+/**
+ * The lede an unconfigured intake shows instead of naming an operator.
+ *
+ * Deliberately tells the reporter to stop and go elsewhere. A form that
+ * silently routes a legal notice to the wrong entity is worse than a form
+ * that admits it is unconfigured, because the first one consumes the
+ * reporter's time and their statutory clock before failing.
+ */ export const OPERATOR_UNCONFIGURED_NOTICE = 'This deployment has not published who operates it or where notices should ' + 'be sent. It is self-hosted software; the operator of this site — not the ' + 'authors of the software — is responsible for its content. Contact the ' + 'operator through whatever channel you already have for them. Reports sent ' + 'through this form are stored for the operator of this site only.';
+const clean = (value)=>{
+    const text = typeof value === 'string' ? value.trim() : '';
+    return text.length ? text : null;
+};
+/** `true` only for an explicit, unambiguous opt-in. */ const flag = (value)=>typeof value === 'string' && value.trim().toLowerCase() === 'true';
+/**
+ * Resolve the operator from configuration.
+ *
+ * A function rather than module-scope constants, deliberately. Module-scope
+ * capture is what forced AGL-2022's spec into `jest.resetModules()` gymnastics
+ * to prove it read configuration at all — and a guard that cannot cheaply
+ * re-read config tends to end up only testing the default, which is exactly
+ * the failure this issue is about. Reading per call also means a test that
+ * sets the env and one that does not can sit next to each other in one file
+ * and prove the asymmetry.
+ *
+ * Next's build-time substitution is unaffected: `process.env.NEXT_PUBLIC_*` is
+ * replaced textually wherever it appears, function bodies included.
+ */ export function operatorIdentity() {
+    var _clean;
+    var _clean1;
+    const name = clean(process.env.NEXT_PUBLIC_OPERATOR_NAME);
+    const supportEmail = clean(process.env.NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL);
+    const legalEmail = (_clean = clean(process.env.NEXT_PUBLIC_OPERATOR_LEGAL_EMAIL)) != null ? _clean : supportEmail;
+    const legalOrigin = (_clean1 = clean(process.env.NEXT_PUBLIC_OPERATOR_LEGAL_ORIGIN)) == null ? void 0 : _clean1.replace(/\/+$/, '');
+    return {
+        name,
+        supportEmail,
+        legalEmail,
+        legalOrigin: legalOrigin != null ? legalOrigin : null,
+        configured: Boolean(name) && Boolean(supportEmail)
+    };
+}
+/**
+ * The operator's designated agent, or `null` when they have not designated
+ * one — which is the correct answer for every deployment except one that has
+ * actually filed.
+ *
+ * `name` and `address` are both required because a designation without a
+ * physical address is not a designation; the Copyright Office directory
+ * record carries both, and a notice sender is entitled to either.
+ *
+ * `registered` is separately gated on an explicit `true`. An operator who
+ * fills in an agent block so their form has a name on it has *not* thereby
+ * claimed a Copyright Office registration, and the product must not upgrade
+ * their configuration into a legal assertion on their behalf.
+ */ export function operatorDmcaAgent() {
+    const name = clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_NAME);
+    const address = clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_ADDRESS);
+    if (!name || !address) return null;
+    return {
+        name,
+        address,
+        email: clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_EMAIL),
+        phone: clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_PHONE),
+        registered: flag(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_REGISTERED)
+    };
+}
+/**
+ * The address a contact line should print, or {@link OPERATOR_CONTACT_UNSET}.
+ *
+ * `kind: 'legal'` prefers the legal mailbox; everything else takes support.
+ * Returns the marker rather than `null` so a caller cannot accidentally
+ * interpolate `null` into copy — `String(null)` is `'null'`, which reads as a
+ * value.
+ */ export function operatorContactLine(kind = 'support') {
+    const identity = operatorIdentity();
+    const address = kind === 'legal' ? identity.legalEmail : identity.supportEmail;
+    return {
+        address,
+        text: address != null ? address : OPERATOR_CONTACT_UNSET
+    };
+}
+/**
+ * How the intake should name whoever runs this deployment, in running prose.
+ *
+ * `'the operator of this site'` when unconfigured — true on every deployment,
+ * including ours, and it never names the wrong company.
+ */ export function operatorDisplayName() {
+    var _operatorIdentity_name;
+    return (_operatorIdentity_name = operatorIdentity().name) != null ? _operatorIdentity_name : 'the operator of this site';
+}
+
+//# sourceMappingURL=operator-identity.js.map

package/src/lib/app-utils/operator-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/operator-identity.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 * Who runs *this* deployment, and where its notices go (AGL-2016).\n *\n * the rule for the self-host path: *\"the self hosted owner should probably\n * not have to edit the source to update aglyn branded items urls or personal\n * identification items, should probably move these to env vars\"*. This module\n * is that, for the one class of value where getting it wrong is not cosmetic —\n * the identity a legal notice is addressed to.\n *\n * ## The defect this exists to close\n *\n * `ABUSE_REPORT_CONTACT_EMAIL` was `'support@aglyn.com'`, a bare literal, and\n * it rendered on the **public, unauthenticated** abuse-report form that every\n * deployment ships. So a self-hoster running their own Firebase published a\n * DMCA/abuse intake instructing third-party reporters to send statutory\n * notices to **Aglyn** — about content Aglyn does not host, cannot see and\n * cannot remove.\n *\n * That is wrong in both directions at once. The reporter's notice goes to a\n * desk with no ability to act on it while their clock runs, and Aglyn is made\n * to look like it holds a takedown duty for a site it does not operate.\n * §512's obligations attach to the entity that actually hosts and controls the\n * material, which on a self-host install is the operator and nobody else.\n *\n * ## Why the default is EMPTY, and not our address\n *\n * AGL-2016 originally proposed our address as the default \"so Aglyn's own\n * deployment is unchanged\". That is the wrong default *for this value*, and\n * the distinction is worth stating because the sibling fixes went the other\n * way and were right to.\n *\n * `TENANT_PRODUCTION_ROOT` (AGL-2022) defaults to `aglyn.app`, and an operator\n * who does not set it gets links that are merely *wrong* — visibly, on the\n * first click, in their own console. A contact address that defaults to ours\n * fails **silently and off-site**: nothing in the operator's product looks\n * broken, and the only party who learns is a copyright holder whose notice\n * landed with a stranger. A wrong default that is invisible to the person who\n * could fix it is not a default, it is a trap.\n *\n * So: absent is a first-class state, exactly as AGL-2021 established for the\n * Texas registration identifiers, and for the same reason — an explicit\n * \"not configured\" beats a blank that reads as an address, and beats a\n * plausible-looking value that reads as fact. The cost is that Aglyn's own\n * deployment must now configure these like any other operator. That is the\n * point: it is what makes this configuration rather than a rename.\n *\n * ## Why `NEXT_PUBLIC_`, and why dot notation is load-bearing\n *\n * Every value here is printed to the public — that is what it is *for* — so\n * `NEXT_PUBLIC_` carries no disclosure risk, unlike AGL-2021's staff-gated\n * identifiers, which are deliberately server-only.\n *\n * Next inlines `NEXT_PUBLIC_*` into the browser bundle by textually\n * substituting `process.env.NAME`. The **bracket** form is never substituted\n * and reads `undefined` in the browser. AGL-2037 is that bug live in\n * `tenant-dns.ts`; AGL-2022's `tenant-links.ts` is the corrected reference.\n * Every read below is dot notation on purpose — do not \"tidy\" it to brackets,\n * and do not introduce a parallel server-only `OPERATOR_*` name: AGL-733 is\n * the record of what happens when one value acquires two env names.\n *\n * Note the build-time consequence for self-hosters: `NEXT_PUBLIC_*` is baked\n * in when the image is built, so these must be set *before* `docker compose\n * build`, not merely before `up`. `docs/SELF_HOSTING.md` says so.\n *\n * ## Empty vs whitespace\n *\n * `'   '` is the shape a half-finished `.env` actually takes and it satisfies\n * a truthiness check. Every read is trimmed and treated as absent, so a\n * half-finished file cannot produce a mailto with nothing behind it.\n */\n\n/** The entity operating this deployment, as far as configuration knows. */\nexport interface OperatorIdentity {\n  /** Legal/display name of the operator, e.g. `Aglyn LLC`. */\n  name: string | null\n  /** Where support and abuse correspondence goes. */\n  supportEmail: string | null\n  /**\n   * Where legal notices go. Falls back to {@link OperatorIdentity.supportEmail}\n   * when unset, because an operator with one mailbox is the common case and a\n   * missing legal address must not silently become *no* address.\n   */\n  legalEmail: string | null\n  /** Origin serving the operator's published legal pages, no trailing slash. */\n  legalOrigin: string | null\n  /**\n   * True when this deployment has published enough to be addressed at all —\n   * a name AND a way to reach it. Anything less renders the honest\n   * unconfigured state rather than a half-identity.\n   */\n  configured: boolean\n}\n\n/**\n * The operator's §512 designated agent, when — and only when — the operator\n * has actually designated one.\n *\n * Separate from {@link OperatorIdentity} on purpose. Having a support address\n * is not having a designated agent: the designation is a filing with the U.S.\n * Copyright Office, it costs money, it must be renewed every three years, and\n * it is what a service provider's safe harbour under 17 U.S.C. §512(c) hangs\n * on. Aglyn has made that filing. A self-hoster who has merely set a support\n * address has not, and is not covered by ours.\n *\n * So the designation is never inferred from the presence of an address. It\n * renders only from its own configuration, and the *claim of registration* —\n * the sentence that is legally load-bearing and legally false if borrowed —\n * requires a further explicit opt-in. See {@link operatorDmcaAgent}.\n */\nexport interface OperatorDmcaAgent {\n  /** Name of the designated agent (a person or a department). */\n  name: string\n  /** Physical address, as filed. Newlines permitted. */\n  address: string\n  /** Address notices are accepted at. */\n  email: string | null\n  /** Phone, as filed. */\n  phone: string | null\n  /**\n   * Whether the operator asserts the designation is **registered with the\n   * U.S. Copyright Office**. Only this makes the product state it.\n   */\n  registered: boolean\n}\n\n/**\n * What a surface prints where an operator address would go when the\n * deployment has not configured one.\n *\n * NOT an empty string, and NOT a plausible placeholder. A blank in a contact\n * slot reads as \"nobody filled it in yet\" — harmless on a settings screen,\n * actively misleading on a page whose entire job is to tell a copyright\n * holder where to send a statutory notice. Same argument, same shape, as\n * AGL-2021's `TX_REGISTRATION_UNSET`: say what is true and name the fix.\n */\nexport const OPERATOR_CONTACT_UNSET =\n  'not configured — this deployment has published no contact address'\n\n/**\n * The lede an unconfigured intake shows instead of naming an operator.\n *\n * Deliberately tells the reporter to stop and go elsewhere. A form that\n * silently routes a legal notice to the wrong entity is worse than a form\n * that admits it is unconfigured, because the first one consumes the\n * reporter's time and their statutory clock before failing.\n */\nexport const OPERATOR_UNCONFIGURED_NOTICE =\n  'This deployment has not published who operates it or where notices should ' +\n  'be sent. It is self-hosted software; the operator of this site — not the ' +\n  'authors of the software — is responsible for its content. Contact the ' +\n  'operator through whatever channel you already have for them. Reports sent ' +\n  'through this form are stored for the operator of this site only.'\n\nconst clean = (value: unknown): string | null => {\n  const text = typeof value === 'string' ? value.trim() : ''\n  return text.length ? text : null\n}\n\n/** `true` only for an explicit, unambiguous opt-in. */\nconst flag = (value: unknown): boolean =>\n  typeof value === 'string' && value.trim().toLowerCase() === 'true'\n\n/**\n * Resolve the operator from configuration.\n *\n * A function rather than module-scope constants, deliberately. Module-scope\n * capture is what forced AGL-2022's spec into `jest.resetModules()` gymnastics\n * to prove it read configuration at all — and a guard that cannot cheaply\n * re-read config tends to end up only testing the default, which is exactly\n * the failure this issue is about. Reading per call also means a test that\n * sets the env and one that does not can sit next to each other in one file\n * and prove the asymmetry.\n *\n * Next's build-time substitution is unaffected: `process.env.NEXT_PUBLIC_*` is\n * replaced textually wherever it appears, function bodies included.\n */\nexport function operatorIdentity(): OperatorIdentity {\n  const name = clean(process.env.NEXT_PUBLIC_OPERATOR_NAME)\n  const supportEmail = clean(process.env.NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL)\n  const legalEmail =\n    clean(process.env.NEXT_PUBLIC_OPERATOR_LEGAL_EMAIL) ?? supportEmail\n  const legalOrigin = clean(\n    process.env.NEXT_PUBLIC_OPERATOR_LEGAL_ORIGIN,\n  )?.replace(/\\/+$/, '')\n  return {\n    name,\n    supportEmail,\n    legalEmail,\n    legalOrigin: legalOrigin ?? null,\n    configured: Boolean(name) && Boolean(supportEmail),\n  }\n}\n\n/**\n * The operator's designated agent, or `null` when they have not designated\n * one — which is the correct answer for every deployment except one that has\n * actually filed.\n *\n * `name` and `address` are both required because a designation without a\n * physical address is not a designation; the Copyright Office directory\n * record carries both, and a notice sender is entitled to either.\n *\n * `registered` is separately gated on an explicit `true`. An operator who\n * fills in an agent block so their form has a name on it has *not* thereby\n * claimed a Copyright Office registration, and the product must not upgrade\n * their configuration into a legal assertion on their behalf.\n */\nexport function operatorDmcaAgent(): OperatorDmcaAgent | null {\n  const name = clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_NAME)\n  const address = clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_ADDRESS)\n  if (!name || !address) return null\n  return {\n    name,\n    address,\n    email: clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_EMAIL),\n    phone: clean(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_PHONE),\n    registered: flag(process.env.NEXT_PUBLIC_OPERATOR_DMCA_AGENT_REGISTERED),\n  }\n}\n\n/**\n * The address a contact line should print, or {@link OPERATOR_CONTACT_UNSET}.\n *\n * `kind: 'legal'` prefers the legal mailbox; everything else takes support.\n * Returns the marker rather than `null` so a caller cannot accidentally\n * interpolate `null` into copy — `String(null)` is `'null'`, which reads as a\n * value.\n */\nexport function operatorContactLine(kind: 'support' | 'legal' = 'support'): {\n  address: string | null\n  text: string\n} {\n  const identity = operatorIdentity()\n  const address =\n    kind === 'legal' ? identity.legalEmail : identity.supportEmail\n  return { address, text: address ?? OPERATOR_CONTACT_UNSET }\n}\n\n/**\n * How the intake should name whoever runs this deployment, in running prose.\n *\n * `'the operator of this site'` when unconfigured — true on every deployment,\n * including ours, and it never names the wrong company.\n */\nexport function operatorDisplayName(): string {\n  return operatorIdentity().name ?? 'the operator of this site'\n}\n"],"names":["OPERATOR_CONTACT_UNSET","OPERATOR_UNCONFIGURED_NOTICE","clean","value","text","trim","length","flag","toLowerCase","operatorIdentity","name","process","env","NEXT_PUBLIC_OPERATOR_NAME","supportEmail","NEXT_PUBLIC_OPERATOR_SUPPORT_EMAIL","legalEmail","NEXT_PUBLIC_OPERATOR_LEGAL_EMAIL","legalOrigin","NEXT_PUBLIC_OPERATOR_LEGAL_ORIGIN","replace","configured","Boolean","operatorDmcaAgent","NEXT_PUBLIC_OPERATOR_DMCA_AGENT_NAME","address","NEXT_PUBLIC_OPERATOR_DMCA_AGENT_ADDRESS","email","NEXT_PUBLIC_OPERATOR_DMCA_AGENT_EMAIL","phone","NEXT_PUBLIC_OPERATOR_DMCA_AGENT_PHONE","registered","NEXT_PUBLIC_OPERATOR_DMCA_AGENT_REGISTERED","operatorContactLine","kind","identity","operatorDisplayName"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqEC,GAED,yEAAyE,GAsDzE;;;;;;;;;CASC,GACD,OAAO,MAAMA,yBACX,oEAAmE;AAErE;;;;;;;CAOC,GACD,OAAO,MAAMC,+BACX,+EACA,8EACA,2EACA,+EACA,mEAAkE;AAEpE,MAAMC,QAAQ,CAACC;IACb,MAAMC,OAAO,OAAOD,UAAU,WAAWA,MAAME,IAAI,KAAK;IACxD,OAAOD,KAAKE,MAAM,GAAGF,OAAO;AAC9B;AAEA,qDAAqD,GACrD,MAAMG,OAAO,CAACJ,QACZ,OAAOA,UAAU,YAAYA,MAAME,IAAI,GAAGG,WAAW,OAAO;AAE9D;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC;QAIZP;QACkBA;IAJpB,MAAMQ,OAAOR,MAAMS,QAAQC,GAAG,CAACC,yBAAyB;IACxD,MAAMC,eAAeZ,MAAMS,QAAQC,GAAG,CAACG,kCAAkC;IACzE,MAAMC,cACJd,SAAAA,MAAMS,QAAQC,GAAG,CAACK,gCAAgC,aAAlDf,SAAuDY;IACzD,MAAMI,eAAchB,UAAAA,MAClBS,QAAQC,GAAG,CAACO,iCAAiC,sBAD3BjB,QAEjBkB,OAAO,CAAC,QAAQ;IACnB,OAAO;QACLV;QACAI;QACAE;QACAE,WAAW,EAAEA,sBAAAA,cAAe;QAC5BG,YAAYC,QAAQZ,SAASY,QAAQR;IACvC;AACF;AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASS;IACd,MAAMb,OAAOR,MAAMS,QAAQC,GAAG,CAACY,oCAAoC;IACnE,MAAMC,UAAUvB,MAAMS,QAAQC,GAAG,CAACc,uCAAuC;IACzE,IAAI,CAAChB,QAAQ,CAACe,SAAS,OAAO;IAC9B,OAAO;QACLf;QACAe;QACAE,OAAOzB,MAAMS,QAAQC,GAAG,CAACgB,qCAAqC;QAC9DC,OAAO3B,MAAMS,QAAQC,GAAG,CAACkB,qCAAqC;QAC9DC,YAAYxB,KAAKI,QAAQC,GAAG,CAACoB,0CAA0C;IACzE;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,oBAAoBC,OAA4B,SAAS;IAIvE,MAAMC,WAAW1B;IACjB,MAAMgB,UACJS,SAAS,UAAUC,SAASnB,UAAU,GAAGmB,SAASrB,YAAY;IAChE,OAAO;QAAEW;QAASrB,IAAI,EAAEqB,kBAAAA,UAAWzB;IAAuB;AAC5D;AAEA;;;;;CAKC,GACD,OAAO,SAASoC;QACP3B;IAAP,QAAOA,yBAAAA,mBAAmBC,IAAI,YAAvBD,yBAA2B;AACpC"}

package/src/lib/app-utils/org-billing-doc.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { OrgSeatAddons, OrgSubscription } from '../foundation/definitions/org-billing.types';
+/**
+ * Where the commercial keys live now that they are off the org doc (AGL-1028).
+ *
+ * `orgs/{orgId}` has to stay readable by any member — it carries `plan` and
+ * `entitlements`, which every console surface gates features on, so denying it
+ * locks a site collaborator out of the site they were invited to. Firestore has
+ * no field-level reads, so the only way to narrow "readable" is to move the
+ * fields somewhere with its own rule. This subcollection is that somewhere, and
+ * it is gated on `canManageOrg()`.
+ *
+ * What did NOT move, and why. AGL-1028 originally listed `seatAddons` and all
+ * of `subscription` as movers; measuring the readers changed that:
+ *
+ * - `plan` / `entitlements` — the whole reason the org doc stays readable.
+ * - `seatAddons` — NOT a commercial secret, an ENTITLEMENT INPUT.
+ *   `resolveOrgEntitlements` stacks it on top of the plan: `seatAddons.hosts`
+ *   raises `hostLimit`, `posRegisters` raises `posRegisters`, `eventCalendar`
+ *   switches a feature on. It resolves at 29 call sites including the tenant
+ *   runtime and non-manager console components — none of which can read a
+ *   manager-gated doc. Moving it would silently drop every paying org to base
+ *   plan limits for exactly the users the org doc stays readable for.
+ * - `subscription.status`, as the derived `billingStatus` mirror — same reason.
+ *   `resolveEffectivePlan` downgrades a paid plan to free on a dead
+ *   subscription, and `resolvePurchasedAddons` stops counting add-ons on one.
+ *   Entitlement resolution therefore needs the status word, so the status word
+ *   cannot be manager-gated. The rest of `subscription` — price ids, amounts,
+ *   interval, period end, custom enterprise pricing — moves.
+ * - `suspendedAt` / `suspendedReason` — the tenant runtime reads suspension on
+ *   EVERY published page render, off an org doc it already fetches for plan and
+ *   branding. Moving it would add a Firestore read to the hot path AGL-1152 is
+ *   trying to shrink, and would hide nothing: the org doc stays member-readable
+ *   regardless. "Your sites are offline" is also something every member needs
+ *   to see, unlike a Stripe customer id.
+ *
+ * So what a scoped collaborator can still see is their plan, their capacity and
+ * a status word — the things they need — and what they lose is the Stripe
+ * customer id, price ids, amounts, billing interval, renewal date and any
+ * negotiated enterprise rate.
+ */
+export declare const ORG_BILLING_SUBCOLLECTION = "billing";
+/**
+ * Single document id, not one doc per concern. The reads are always "all of
+ * it" (the billing page, the webhook, the staff MRR roll-up), so splitting it
+ * would only buy extra round trips.
+ */
+export declare const ORG_BILLING_DOC_ID = "stripe";
+/**
+ * Reverse index `stripeCustomers/{stripeCustomerId} -> { orgId }`, written by
+ * the webhook alongside the billing doc.
+ *
+ * It exists because the webhook has to answer "which org is this Stripe
+ * customer?" on `invoice.payment_failed`, and it did that with
+ * `.where('stripeCustomerId', '==', …)` on the orgs collection. Once the field
+ * moves into a subcollection that query cannot work: the alternative is a
+ * collection-group query, which needs a collection-group index that the
+ * emulator will never ask for and production will (AGL-1028). A mapping doc is
+ * an O(1) `get`, needs no index, and stops the webhook scanning `orgs` at all.
+ *
+ * Admin-SDK only — nothing client-side has any business reading it.
+ */
+export declare const STRIPE_CUSTOMER_INDEX_COLLECTION = "stripeCustomers";
+/**
+ * The keys that moved off `orgs/{orgId}` and into the billing doc.
+ *
+ * `seatAddons` is deliberately NOT here — see the note above; it is an
+ * entitlement input, not a commercial secret.
+ */
+export declare const ORG_BILLING_MOVED_KEYS: readonly ["stripeCustomerId", "subscription"];
+export type OrgBillingMovedKey = (typeof ORG_BILLING_MOVED_KEYS)[number];
+/**
+ * The TEST-mode Stripe customer id, stored beside the live one (AGL-2486).
+ *
+ * `stripeCustomerId` held ONE id with no notion of Stripe livemode, so an org
+ * that had been through live checkout could never be exercised in test mode
+ * and vice versa: every billing call answered
+ *
+ *   No such customer: 'cus_…'; a similar object exists in live mode, but a
+ *   test mode key was used to make this request.
+ *
+ * — a raw 502 out of `/api/billing/checkout`, `/invoices` and `/addons`. For a
+ * team running both modes against ONE Firestore that is permanent, and it made
+ * the test-mode path we need before September 1 unusable on any real org.
+ *
+ * Worse than the 502, and the reason this is a stored-shape change rather than
+ * a better error message: a test-mode run that COMPLETED would write its test
+ * customer into the single slot and destroy the live linkage — silently, with
+ * every subsequent live invoice scattering onto a customer the Billing page no
+ * longer queries.
+ *
+ * ## Why a second field and not a mode-keyed map
+ *
+ * The live id stays at `stripeCustomerId`, untouched. That makes the migration
+ * EMPTY — every value production holds today was written by a `sk_live_`
+ * deployment and is already in the right slot — and it makes the change a
+ * NO-OP in live mode by construction: the live path reads the same field name
+ * it always read. Only test mode, which is 100% broken today, behaves
+ * differently. A `{live,test}` map would have required rewriting every
+ * existing document to gain nothing.
+ *
+ * The `stripeCustomers` reverse index needs NO equivalent treatment: it is
+ * keyed BY the customer id, and Stripe customer ids are unique across modes, so
+ * a test and a live entry are simply two documents that both resolve to the
+ * same org. That is why this fix is contained.
+ *
+ * Physical field names are an implementation detail of `org-billing.ts` — read
+ * and write through `readOrgBilling`/`writeOrgBilling`, which project the
+ * deployment's mode onto the logical `stripeCustomerId` key. Nothing else
+ * should name this constant.
+ */
+export declare const STRIPE_CUSTOMER_ID_TEST_FIELD = "stripeCustomerIdTest";
+/** The manager-gated document's shape. */
+export interface OrgBillingDoc {
+    stripeCustomerId?: string | null;
+    /**
+     * The test-mode twin. Present on the stored document only; the accessors
+     * collapse the pair to `stripeCustomerId` for every reader.
+     */
+    stripeCustomerIdTest?: string | null;
+    subscription?: OrgSubscription | null;
+}
+/**
+ * `seatAddons` stays on the org doc, so this is the shape of what the org doc
+ * still carries commercially. Named for clarity at the call sites that have to
+ * keep the two apart.
+ */
+export interface OrgInlineBilling {
+    seatAddons?: OrgSeatAddons | null;
+    billingStatus?: string | null;
+}
+/**
+ * The non-sensitive mirror that STAYS on the org doc.
+ *
+ * The AGL-275 dunning banner keys on `subscription.status === 'past_due'` and
+ * is shown to every member on purpose — a contractor who cannot see the invoice
+ * still benefits from knowing the workspace is about to lapse. Putting
+ * `subscription` behind `canManageOrg()` would have silently switched that
+ * banner off for non-managers, so the webhook mirrors the status string (and
+ * nothing else: no amounts, no price ids, no customer id) back onto the org doc
+ * for the banner to read.
+ */
+export type OrgBillingStatus = string;
+/**
+ * Picks the moved keys off an org-shaped object, dropping `undefined` so a
+ * partial update never writes holes over good data.
+ *
+ * `null` is preserved deliberately — the webhook uses it to mean "Stripe says
+ * this is gone", which is a real value and not an absence.
+ */
+export declare function pickOrgBillingFields(source: Partial<Record<OrgBillingMovedKey, unknown>> | null | undefined): Partial<OrgBillingDoc>;
+/**
+ * The status string to mirror onto the org doc for the dunning banner.
+ *
+ * Returns `null` when there is no subscription at all, which the banner treats
+ * the same as a healthy one — a pre-billing workspace is not in dunning.
+ */
+export declare function orgBillingStatusFrom(billing: Partial<OrgBillingDoc> | null | undefined): OrgBillingStatus | null;
+/**
+ * True when a subscription STATUS word means the subscription is live.
+ *
+ * The status-string half of the predicate, for the call sites that hold a
+ * Stripe subscription object rather than an org billing document — the
+ * `subscriptions?customer=…&status=all` list responses in
+ * `/api/billing/subscription`, `/api/billing/addons` and
+ * `/api/admin/org-discount`, and the webhook status word that
+ * `metered-backfill` decides on. Those cannot be typed as an `OrgBillingDoc`
+ * without lying, and wrapping them in one just to unwrap it again is a cast
+ * that hides the shape. Same list, one entry point per shape.
+ */
+export declare function isLiveSubscriptionStatus(status: unknown): boolean;
+/**
+ * True when this org already has a live subscription and must not be sold or
+ * provisioned a second one (AGL-1697, AGL-1714).
+ *
+ * Lives here rather than at the call site because the failure mode of the
+ * copies is asymmetric in the expensive direction: if one call site's list ever
+ * narrows relative to another's, a subscribed org gets sold a second
+ * subscription and both bill. AGL-1715 repointed the older inline copies at
+ * this predicate (or at `isLiveSubscriptionStatus` where the value in hand is
+ * a Stripe object): the Billing page, `/api/billing/checkout`,
+ * `/api/billing/subscription`, `/api/billing/addons`,
+ * `/api/admin/org-discount` and `utils/server/metered-backfill`.
+ */
+export declare function isOrgSubscriptionLive(billing: Partial<OrgBillingDoc> | null | undefined): boolean;
+/**
+ * True when an org record still carries the moved keys inline — i.e. it has not
+ * been through the backfill yet. Used by the read path to decide whether the
+ * org doc is a trustworthy fallback, and by the backfill to skip work it has
+ * already done.
+ */
+export declare function hasInlineOrgBilling(source: Partial<Record<OrgBillingMovedKey, unknown>> | null | undefined): boolean;
+/**
+ * Merge the manager-gated billing doc over an org doc WITHOUT letting the
+ * billing doc's identity win (AGL-1991).
+ *
+ * The billing page merges `orgs/{orgId}/billing/stripe` over `orgs/{orgId}` so
+ * that every `org.subscription…` reference keeps working after AGL-1028 moved
+ * those keys. The trap: the console's `useConfirmedDoc` stamps the DOCUMENT ID
+ * into the payload it hands back (`{ $id: id, ...payload }`), so the billing
+ * doc arrives carrying `$id === ORG_BILLING_DOC_ID` — the literal string
+ * `'stripe'`. A plain spread puts that second, so the merged object's `$id`
+ * silently became `'stripe'` and every child deriving its org id from it read
+ * `orgs/stripe/…`, which is not an org and is denied by the rules.
+ *
+ * That is why this is a helper and not an inline `$id:` re-assert at the call
+ * site: `useConfirmedDoc` stamping `$id` makes ANY merge of two documents
+ * identity-swapping, so the safe merge belongs somewhere it can be reused and
+ * named rather than re-derived correctly each time.
+ *
+ * The org doc's `$id` wins unconditionally — including when it is absent, in
+ * which case the result carries no `$id` at all rather than inheriting the
+ * billing doc's. A missing org id must read as "unknown", never as a
+ * confidently wrong path.
+ */
+export declare function mergeOrgBillingOverOrg<TOrg extends Record<string, unknown>, TBilling extends Record<string, unknown>>(orgDoc: TOrg | null | undefined, orgBilling: TBilling | null | undefined): TOrg & Partial<TBilling>;