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

package/src/lib/app-utils/page-record-sources.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @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 { PageRecordScope } from './expand-repeatables';
+/**
+ * WHICH RECORD A PAGE IS DRAWN FOR, ON THE BESIGNER'S CANVAS (AGL-3475).
+ *
+ * A record template renders once per record on the published site: the
+ * composition hands it the routed record (`PageRecordScope`) and its
+ * `{{item.*}}` tokens fill in. The canvas has no routed record — it edits the
+ * template — so without one it shows the raw tokens, and the author designs a
+ * page of `{{item.name}}` placeholders.
+ *
+ * So a plugin that serves pages per record answers here, for the page in the
+ * editor: whether it is a template of theirs, and if so a record to draw it
+ * for, with the others an author may switch to. The canvas lays that record
+ * over every element's render copy exactly as a repeat lays its first record
+ * over its template (AGL-3111) — the nodes keep their tokens, and a save
+ * writes the template.
+ *
+ * The editor's side only: a hook, mounted by the console beside the canvas,
+ * because the designer reads no database. `repeat-sources.ts` is the same
+ * shape for a repeat's rows.
+ */
+/** One record an author can preview the page with. */
+export interface PageRecordChoice {
+    /** The record's id. */
+    id: string;
+    /** What the picker shows for it. */
+    label: string;
+}
+/** What a source answers for one page. */
+export type PageRecordAnswer = 
+/** Not a page this source serves records on. */
+{
+    status: 'none';
+} | {
+    status: 'loading';
+} | (PageRecordScope & {
+    status: 'ready';
+    /** What the page is a template of: "Services". */
+    label: string;
+    /** The record being drawn. */
+    selectedId: string;
+    /** Every record the picker offers, the drawn one included. */
+    choices: readonly PageRecordChoice[];
+    /** Draws the page for another of the choices. */
+    select: (id: string) => void;
+});
+/** What a source is asked. */
+export interface PageRecordRequest {
+    hostId: string;
+    screenId: string;
+}
+export interface PageRecordSource {
+    /** Stable id; one source per id. */
+    id: string;
+    /**
+     * A React hook, called once per source for the page in the editor, every
+     * render. Answers `none` for a page it does not serve.
+     */
+    usePageRecord: (request: PageRecordRequest) => PageRecordAnswer;
+}
+/**
+ * Registers a source, replacing any under its id. Returns the unregister,
+ * which removes it only while it is still the one registered. Call it from a
+ * registration function the plugin loader calls by name, never from a
+ * module's top level (AGL-3025).
+ */
+export declare function registerPageRecordSource(source: PageRecordSource): () => void;
+/** Every registered source, the SAME array until the set changes. */
+export declare function listPageRecordSources(): readonly PageRecordSource[];
+/** Called after the registered set changes. Returns the unsubscribe. */
+export declare function subscribePageRecordSources(listener: () => void): () => void;

package/src/lib/app-utils/page-record-sources.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ const sources = new Map();
+const listeners = new Set();
+/** Replaced only when the set changes: the snapshot a store compares. */ let snapshot = [];
+const notify = ()=>{
+    snapshot = [
+        ...sources.values()
+    ];
+    for (const listener of [
+        ...listeners
+    ])listener();
+};
+/**
+ * Registers a source, replacing any under its id. Returns the unregister,
+ * which removes it only while it is still the one registered. Call it from a
+ * registration function the plugin loader calls by name, never from a
+ * module's top level (AGL-3025).
+ */ export function registerPageRecordSource(source) {
+    if (sources.get(source.id) !== source) {
+        sources.set(source.id, source);
+        notify();
+    }
+    return ()=>{
+        if (sources.get(source.id) !== source) return;
+        sources.delete(source.id);
+        notify();
+    };
+}
+/** Every registered source, the SAME array until the set changes. */ export function listPageRecordSources() {
+    return snapshot;
+}
+/** Called after the registered set changes. Returns the unsubscribe. */ export function subscribePageRecordSources(listener) {
+    listeners.add(listener);
+    return ()=>{
+        listeners.delete(listener);
+    };
+}
+
+//# sourceMappingURL=page-record-sources.js.map

package/src/lib/app-utils/page-record-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/page-record-sources.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { PageRecordScope } from './expand-repeatables'\n\n/**\n * WHICH RECORD A PAGE IS DRAWN FOR, ON THE BESIGNER'S CANVAS (AGL-3475).\n *\n * A record template renders once per record on the published site: the\n * composition hands it the routed record (`PageRecordScope`) and its\n * `{{item.*}}` tokens fill in. The canvas has no routed record — it edits the\n * template — so without one it shows the raw tokens, and the author designs a\n * page of `{{item.name}}` placeholders.\n *\n * So a plugin that serves pages per record answers here, for the page in the\n * editor: whether it is a template of theirs, and if so a record to draw it\n * for, with the others an author may switch to. The canvas lays that record\n * over every element's render copy exactly as a repeat lays its first record\n * over its template (AGL-3111) — the nodes keep their tokens, and a save\n * writes the template.\n *\n * The editor's side only: a hook, mounted by the console beside the canvas,\n * because the designer reads no database. `repeat-sources.ts` is the same\n * shape for a repeat's rows.\n */\n\n/** One record an author can preview the page with. */\nexport interface PageRecordChoice {\n  /** The record's id. */\n  id: string\n  /** What the picker shows for it. */\n  label: string\n}\n\n/** What a source answers for one page. */\nexport type PageRecordAnswer =\n  /** Not a page this source serves records on. */\n  | { status: 'none' }\n  | { status: 'loading' }\n  | (PageRecordScope & {\n      status: 'ready'\n      /** What the page is a template of: \"Services\". */\n      label: string\n      /** The record being drawn. */\n      selectedId: string\n      /** Every record the picker offers, the drawn one included. */\n      choices: readonly PageRecordChoice[]\n      /** Draws the page for another of the choices. */\n      select: (id: string) => void\n    })\n\n/** What a source is asked. */\nexport interface PageRecordRequest {\n  hostId: string\n  screenId: string\n}\n\nexport interface PageRecordSource {\n  /** Stable id; one source per id. */\n  id: string\n  /**\n   * A React hook, called once per source for the page in the editor, every\n   * render. Answers `none` for a page it does not serve.\n   */\n  usePageRecord: (request: PageRecordRequest) => PageRecordAnswer\n}\n\nconst sources = new Map<string, PageRecordSource>()\nconst listeners = new Set<() => void>()\n/** Replaced only when the set changes: the snapshot a store compares. */\nlet snapshot: readonly PageRecordSource[] = []\n\nconst notify = () => {\n  snapshot = [...sources.values()]\n  for (const listener of [...listeners]) listener()\n}\n\n/**\n * Registers a source, replacing any under its id. Returns the unregister,\n * which removes it only while it is still the one registered. Call it from a\n * registration function the plugin loader calls by name, never from a\n * module's top level (AGL-3025).\n */\nexport function registerPageRecordSource(source: PageRecordSource): () => void {\n  if (sources.get(source.id) !== source) {\n    sources.set(source.id, source)\n    notify()\n  }\n  return () => {\n    if (sources.get(source.id) !== source) return\n    sources.delete(source.id)\n    notify()\n  }\n}\n\n/** Every registered source, the SAME array until the set changes. */\nexport function listPageRecordSources(): readonly PageRecordSource[] {\n  return snapshot\n}\n\n/** Called after the registered set changes. Returns the unsubscribe. */\nexport function subscribePageRecordSources(listener: () => void): () => void {\n  listeners.add(listener)\n  return () => {\n    listeners.delete(listener)\n  }\n}\n"],"names":["sources","Map","listeners","Set","snapshot","notify","values","listener","registerPageRecordSource","source","get","id","set","delete","listPageRecordSources","subscribePageRecordSources","add"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAkED,MAAMA,UAAU,IAAIC;AACpB,MAAMC,YAAY,IAAIC;AACtB,uEAAuE,GACvE,IAAIC,WAAwC,EAAE;AAE9C,MAAMC,SAAS;IACbD,WAAW;WAAIJ,QAAQM,MAAM;KAAG;IAChC,KAAK,MAAMC,YAAY;WAAIL;KAAU,CAAEK;AACzC;AAEA;;;;;CAKC,GACD,OAAO,SAASC,yBAAyBC,MAAwB;IAC/D,IAAIT,QAAQU,GAAG,CAACD,OAAOE,EAAE,MAAMF,QAAQ;QACrCT,QAAQY,GAAG,CAACH,OAAOE,EAAE,EAAEF;QACvBJ;IACF;IACA,OAAO;QACL,IAAIL,QAAQU,GAAG,CAACD,OAAOE,EAAE,MAAMF,QAAQ;QACvCT,QAAQa,MAAM,CAACJ,OAAOE,EAAE;QACxBN;IACF;AACF;AAEA,mEAAmE,GACnE,OAAO,SAASS;IACd,OAAOV;AACT;AAEA,sEAAsE,GACtE,OAAO,SAASW,2BAA2BR,QAAoB;IAC7DL,UAAUc,GAAG,CAACT;IACd,OAAO;QACLL,UAAUW,MAAM,CAACN;IACnB;AACF"}

package/src/lib/app-utils/paid-media-source.d.ts

@@ -56,13 +56,9 @@ export type PaidMediaSource =
  */
 export declare function parsePaidMediaSource(stored: unknown): PaidMediaSource;
 /**
- * The library asset a media object key belongs to, or null.
- *
- * Every writer keys an asset's object as `{base}/media/[folders/]{mediaId}`,
- * with `base` either `hosts/{hostId}` or `orgs/{orgId}`. So a key in that
- * shape whose last segment is id-shaped IS that asset, wherever a folder move
- * has since put it. Derived objects (`…__r720p.mp4`, `…__poster.webp`) carry
- * a dot and are no asset's key.
+ * The library asset a media object key belongs to, or null. The grammar is
+ * {@link mediaAssetOfObjectKey}'s, which the render-time resolver shares
+ * (AGL-3506); this name stays for the paid-media callers.
  *
  * This names the asset and decides nothing about access: a caller that signs
  * still has to check the bucket and that the library is its own.

package/src/lib/app-utils/paid-media-source.js

@@ -13,7 +13,7 @@
  * 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 { isFirstPartyHost, MEDIA_CDN_ROUTE, MEDIA_REF_PREFIX, parseMediaRef } from "./media-ref.js";
+ */ import { isFirstPartyHost, MEDIA_CDN_ROUTE, mediaAssetOfObjectKey, MEDIA_REF_PREFIX, parseMediaRef } from "./media-ref.js";
 const STORAGE_DOWNLOAD_HOST = 'firebasestorage.googleapis.com';
 const GCS_HOST = 'storage.googleapis.com';
 /**
@@ -131,28 +131,14 @@ const GCS_HOST = 'storage.googleapis.com';
     };
 }
 /**
- * The library asset a media object key belongs to, or null.
- *
- * Every writer keys an asset's object as `{base}/media/[folders/]{mediaId}`,
- * with `base` either `hosts/{hostId}` or `orgs/{orgId}`. So a key in that
- * shape whose last segment is id-shaped IS that asset, wherever a folder move
- * has since put it. Derived objects (`…__r720p.mp4`, `…__poster.webp`) carry
- * a dot and are no asset's key.
+ * The library asset a media object key belongs to, or null. The grammar is
+ * {@link mediaAssetOfObjectKey}'s, which the render-time resolver shares
+ * (AGL-3506); this name stays for the paid-media callers.
  *
  * This names the asset and decides nothing about access: a caller that signs
  * still has to check the bucket and that the library is its own.
  */ export function paidMediaAssetOfObject(objectPath) {
-    const segments = String(objectPath != null ? objectPath : '').split('/');
-    if (segments.length < 4 || segments[2] !== 'media') return null;
-    if (segments.some((segment)=>!segment || segment === '..')) return null;
-    const [root, scopeId] = segments;
-    const scope = root === 'hosts' ? scopeId : root === 'orgs' ? `org:${scopeId}` : null;
-    if (!scope) return null;
-    const ref = parseMediaRef(`${MEDIA_REF_PREFIX}${scope}/${segments[segments.length - 1]}`);
-    return ref ? {
-        scope: ref.scope,
-        mediaId: ref.mediaId
-    } : null;
+    return mediaAssetOfObjectKey(objectPath);
 }
 /**
  * The library asset a stored paid-media URL names, in whichever form it was

package/src/lib/app-utils/paid-media-source.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/paid-media-source.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  isFirstPartyHost,\n  MEDIA_CDN_ROUTE,\n  MEDIA_REF_PREFIX,\n  parseMediaRef,\n} from './media-ref'\n\n/**\n * What a URL stored on a product's paid media names (AGL-2814).\n *\n * A members video is stored as whatever wrote it: the paid-media picker's\n * reference, an older picker's CDN path, the raw Storage download URL a\n * free-tier library hands out, or a hotlink typed into an import. Three\n * places have to agree on which ASSET that is: the stream route that signs\n * it, the console that shows the author whether it is protected, and the\n * media route that refuses to publish a file a product still sells. One\n * grammar, here, so they cannot disagree.\n *\n * Pure and environment-light: nothing here reads Firestore, Storage or a\n * secret, so the console bundle can carry it.\n */\nexport type PaidMediaSource =\n  /** A media-library asset, named by scope segment and id. */\n  | { kind: 'asset'; scope: string; mediaId: string }\n  /** An object in a Storage bucket, from a download or GCS URL. */\n  | { kind: 'storage-object'; bucket: string; objectPath: string }\n  /** Somebody else's server. */\n  | { kind: 'external'; url: string }\n  /** Nothing that can be delivered, including a Storage URL we cannot read. */\n  | { kind: 'malformed' }\n\nconst STORAGE_DOWNLOAD_HOST = 'firebasestorage.googleapis.com'\nconst GCS_HOST = 'storage.googleapis.com'\n\n/**\n * The Storage emulator's `host:port`, whose download URLs have the same shape\n * as production's. Read per call so a test can set it.\n */\nfunction storageEmulatorHost(): string {\n  const env =\n    typeof process === 'undefined' ? undefined : process.env?.['FIREBASE_STORAGE_EMULATOR_HOST']\n  return String(env ?? '')\n    .trim()\n    .toLowerCase()\n}\n\n/** A library asset from `/api/media/cdn/{scope}/{mediaId}[/{hash}]`. */\nfunction assetFromCdnPath(path: string): PaidMediaSource {\n  const rest = path.slice(`${MEDIA_CDN_ROUTE}/`.length).split(/[?#]/)[0]\n  const segments = rest.split('/')\n  if (segments.length < 2 || segments.length > 3) return { kind: 'malformed' }\n  let scope: string\n  try {\n    scope = decodeURIComponent(segments[0])\n  } catch {\n    return { kind: 'malformed' }\n  }\n  // Parsed through the reference grammar rather than a second copy of it. A\n  // content pin in the path is dropped: a paid link names the asset, and the\n  // stable URL always serves its current bytes.\n  const ref = parseMediaRef(`${MEDIA_REF_PREFIX}${scope}/${segments[1]}`)\n  return ref\n    ? { kind: 'asset', scope: ref.scope, mediaId: ref.mediaId }\n    : { kind: 'malformed' }\n}\n\n/** Decodes each `/`-separated piece of a path; null when one is malformed. */\nfunction decodePath(pieces: string[]): string | null {\n  try {\n    return pieces.map((piece) => decodeURIComponent(piece)).join('/')\n  } catch {\n    return null\n  }\n}\n\n/**\n * Classifies a stored value. The same input always gives the same answer, so\n * every branch is checkable without a project.\n */\nexport function parsePaidMediaSource(stored: unknown): PaidMediaSource {\n  const value = typeof stored === 'string' ? stored.trim() : ''\n  if (!value) return { kind: 'malformed' }\n  if (value.startsWith(MEDIA_REF_PREFIX)) {\n    const ref = parseMediaRef(value)\n    return ref\n      ? { kind: 'asset', scope: ref.scope, mediaId: ref.mediaId }\n      : { kind: 'malformed' }\n  }\n  if (value.startsWith(`${MEDIA_CDN_ROUTE}/`)) return assetFromCdnPath(value)\n  if (!/^https?:\\/\\//i.test(value)) return { kind: 'malformed' }\n  let url: URL\n  try {\n    url = new URL(value)\n  } catch {\n    return { kind: 'malformed' }\n  }\n  const hostname = url.hostname.toLowerCase()\n  const emulator = storageEmulatorHost()\n  if (\n    hostname === STORAGE_DOWNLOAD_HOST ||\n    (emulator && url.host.toLowerCase() === emulator)\n  ) {\n    // `/v0/b/{bucket}/o/{object}`, with the object key percent-encoded as one\n    // segment. A download URL in any other shape is still a token URL, so it\n    // is refused rather than handed through as a hotlink.\n    const match = /^\\/v0\\/b\\/([^/]+)\\/o\\/([^/]+)$/.exec(url.pathname)\n    const bucket = match ? decodePath([match[1]]) : null\n    const objectPath = match ? decodePath([match[2]]) : null\n    return bucket && objectPath\n      ? { kind: 'storage-object', bucket, objectPath }\n      : { kind: 'malformed' }\n  }\n  if (hostname === GCS_HOST) {\n    const [, bucketPiece, ...objectPieces] = url.pathname.split('/')\n    const bucket = bucketPiece ? decodePath([bucketPiece]) : null\n    const objectPath = objectPieces.length ? decodePath(objectPieces) : null\n    return bucket && objectPath\n      ? { kind: 'storage-object', bucket, objectPath }\n      : { kind: 'malformed' }\n  }\n  if (\n    isFirstPartyHost(hostname) &&\n    url.pathname.startsWith(`${MEDIA_CDN_ROUTE}/`)\n  ) {\n    return assetFromCdnPath(url.pathname)\n  }\n  return { kind: 'external', url: value }\n}\n\n/**\n * The library asset a media object key belongs to, or null.\n *\n * Every writer keys an asset's object as `{base}/media/[folders/]{mediaId}`,\n * with `base` either `hosts/{hostId}` or `orgs/{orgId}`. So a key in that\n * shape whose last segment is id-shaped IS that asset, wherever a folder move\n * has since put it. Derived objects (`…__r720p.mp4`, `…__poster.webp`) carry\n * a dot and are no asset's key.\n *\n * This names the asset and decides nothing about access: a caller that signs\n * still has to check the bucket and that the library is its own.\n */\nexport function paidMediaAssetOfObject(\n  objectPath: string,\n): { scope: string; mediaId: string } | null {\n  const segments = String(objectPath ?? '').split('/')\n  if (segments.length < 4 || segments[2] !== 'media') return null\n  if (segments.some((segment) => !segment || segment === '..')) return null\n  const [root, scopeId] = segments\n  const scope =\n    root === 'hosts' ? scopeId : root === 'orgs' ? `org:${scopeId}` : null\n  if (!scope) return null\n  const ref = parseMediaRef(\n    `${MEDIA_REF_PREFIX}${scope}/${segments[segments.length - 1]}`,\n  )\n  return ref ? { scope: ref.scope, mediaId: ref.mediaId } : null\n}\n\n/**\n * The library asset a stored paid-media URL names, in whichever form it was\n * written, or null for a hotlink, a malformed value, or a Storage URL that\n * names no asset. Pass `bucket` to refuse a download URL from any other\n * bucket, which is what every server-side caller should do.\n */\nexport function paidMediaAssetOf(\n  stored: unknown,\n  options?: { bucket?: string },\n): { scope: string; mediaId: string } | null {\n  const source = parsePaidMediaSource(stored)\n  if (source.kind === 'asset') {\n    return { scope: source.scope, mediaId: source.mediaId }\n  }\n  if (source.kind !== 'storage-object') return null\n  if (options?.bucket !== undefined && source.bucket !== options.bucket) {\n    return null\n  }\n  return paidMediaAssetOfObject(source.objectPath)\n}\n\n/**\n * Whether two scope segments name the same library: the same host, or the\n * same org whatever site either is qualified with.\n */\nexport function samePaidMediaLibrary(a: string, b: string): boolean {\n  const library = (scope: string) =>\n    scope.startsWith('org:') ? `org:${scope.slice(4).split(':')[0]}` : scope\n  return library(a) === library(b)\n}\n"],"names":["isFirstPartyHost","MEDIA_CDN_ROUTE","MEDIA_REF_PREFIX","parseMediaRef","STORAGE_DOWNLOAD_HOST","GCS_HOST","storageEmulatorHost","process","env","undefined","String","trim","toLowerCase","assetFromCdnPath","path","rest","slice","length","split","segments","kind","scope","decodeURIComponent","ref","mediaId","decodePath","pieces","map","piece","join","parsePaidMediaSource","stored","value","startsWith","test","url","URL","hostname","emulator","host","match","exec","pathname","bucket","objectPath","bucketPiece","objectPieces","paidMediaAssetOfObject","some","segment","root","scopeId","paidMediaAssetOf","options","source","samePaidMediaLibrary","a","b","library"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/paid-media-source.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  isFirstPartyHost,\n  MEDIA_CDN_ROUTE,\n  mediaAssetOfObjectKey,\n  MEDIA_REF_PREFIX,\n  parseMediaRef,\n} from './media-ref'\n\n/**\n * What a URL stored on a product's paid media names (AGL-2814).\n *\n * A members video is stored as whatever wrote it: the paid-media picker's\n * reference, an older picker's CDN path, the raw Storage download URL a\n * free-tier library hands out, or a hotlink typed into an import. Three\n * places have to agree on which ASSET that is: the stream route that signs\n * it, the console that shows the author whether it is protected, and the\n * media route that refuses to publish a file a product still sells. One\n * grammar, here, so they cannot disagree.\n *\n * Pure and environment-light: nothing here reads Firestore, Storage or a\n * secret, so the console bundle can carry it.\n */\nexport type PaidMediaSource =\n  /** A media-library asset, named by scope segment and id. */\n  | { kind: 'asset'; scope: string; mediaId: string }\n  /** An object in a Storage bucket, from a download or GCS URL. */\n  | { kind: 'storage-object'; bucket: string; objectPath: string }\n  /** Somebody else's server. */\n  | { kind: 'external'; url: string }\n  /** Nothing that can be delivered, including a Storage URL we cannot read. */\n  | { kind: 'malformed' }\n\nconst STORAGE_DOWNLOAD_HOST = 'firebasestorage.googleapis.com'\nconst GCS_HOST = 'storage.googleapis.com'\n\n/**\n * The Storage emulator's `host:port`, whose download URLs have the same shape\n * as production's. Read per call so a test can set it.\n */\nfunction storageEmulatorHost(): string {\n  const env =\n    typeof process === 'undefined' ? undefined : process.env?.['FIREBASE_STORAGE_EMULATOR_HOST']\n  return String(env ?? '')\n    .trim()\n    .toLowerCase()\n}\n\n/** A library asset from `/api/media/cdn/{scope}/{mediaId}[/{hash}]`. */\nfunction assetFromCdnPath(path: string): PaidMediaSource {\n  const rest = path.slice(`${MEDIA_CDN_ROUTE}/`.length).split(/[?#]/)[0]\n  const segments = rest.split('/')\n  if (segments.length < 2 || segments.length > 3) return { kind: 'malformed' }\n  let scope: string\n  try {\n    scope = decodeURIComponent(segments[0])\n  } catch {\n    return { kind: 'malformed' }\n  }\n  // Parsed through the reference grammar rather than a second copy of it. A\n  // content pin in the path is dropped: a paid link names the asset, and the\n  // stable URL always serves its current bytes.\n  const ref = parseMediaRef(`${MEDIA_REF_PREFIX}${scope}/${segments[1]}`)\n  return ref\n    ? { kind: 'asset', scope: ref.scope, mediaId: ref.mediaId }\n    : { kind: 'malformed' }\n}\n\n/** Decodes each `/`-separated piece of a path; null when one is malformed. */\nfunction decodePath(pieces: string[]): string | null {\n  try {\n    return pieces.map((piece) => decodeURIComponent(piece)).join('/')\n  } catch {\n    return null\n  }\n}\n\n/**\n * Classifies a stored value. The same input always gives the same answer, so\n * every branch is checkable without a project.\n */\nexport function parsePaidMediaSource(stored: unknown): PaidMediaSource {\n  const value = typeof stored === 'string' ? stored.trim() : ''\n  if (!value) return { kind: 'malformed' }\n  if (value.startsWith(MEDIA_REF_PREFIX)) {\n    const ref = parseMediaRef(value)\n    return ref\n      ? { kind: 'asset', scope: ref.scope, mediaId: ref.mediaId }\n      : { kind: 'malformed' }\n  }\n  if (value.startsWith(`${MEDIA_CDN_ROUTE}/`)) return assetFromCdnPath(value)\n  if (!/^https?:\\/\\//i.test(value)) return { kind: 'malformed' }\n  let url: URL\n  try {\n    url = new URL(value)\n  } catch {\n    return { kind: 'malformed' }\n  }\n  const hostname = url.hostname.toLowerCase()\n  const emulator = storageEmulatorHost()\n  if (\n    hostname === STORAGE_DOWNLOAD_HOST ||\n    (emulator && url.host.toLowerCase() === emulator)\n  ) {\n    // `/v0/b/{bucket}/o/{object}`, with the object key percent-encoded as one\n    // segment. A download URL in any other shape is still a token URL, so it\n    // is refused rather than handed through as a hotlink.\n    const match = /^\\/v0\\/b\\/([^/]+)\\/o\\/([^/]+)$/.exec(url.pathname)\n    const bucket = match ? decodePath([match[1]]) : null\n    const objectPath = match ? decodePath([match[2]]) : null\n    return bucket && objectPath\n      ? { kind: 'storage-object', bucket, objectPath }\n      : { kind: 'malformed' }\n  }\n  if (hostname === GCS_HOST) {\n    const [, bucketPiece, ...objectPieces] = url.pathname.split('/')\n    const bucket = bucketPiece ? decodePath([bucketPiece]) : null\n    const objectPath = objectPieces.length ? decodePath(objectPieces) : null\n    return bucket && objectPath\n      ? { kind: 'storage-object', bucket, objectPath }\n      : { kind: 'malformed' }\n  }\n  if (\n    isFirstPartyHost(hostname) &&\n    url.pathname.startsWith(`${MEDIA_CDN_ROUTE}/`)\n  ) {\n    return assetFromCdnPath(url.pathname)\n  }\n  return { kind: 'external', url: value }\n}\n\n/**\n * The library asset a media object key belongs to, or null. The grammar is\n * {@link mediaAssetOfObjectKey}'s, which the render-time resolver shares\n * (AGL-3506); this name stays for the paid-media callers.\n *\n * This names the asset and decides nothing about access: a caller that signs\n * still has to check the bucket and that the library is its own.\n */\nexport function paidMediaAssetOfObject(\n  objectPath: string,\n): { scope: string; mediaId: string } | null {\n  return mediaAssetOfObjectKey(objectPath)\n}\n\n/**\n * The library asset a stored paid-media URL names, in whichever form it was\n * written, or null for a hotlink, a malformed value, or a Storage URL that\n * names no asset. Pass `bucket` to refuse a download URL from any other\n * bucket, which is what every server-side caller should do.\n */\nexport function paidMediaAssetOf(\n  stored: unknown,\n  options?: { bucket?: string },\n): { scope: string; mediaId: string } | null {\n  const source = parsePaidMediaSource(stored)\n  if (source.kind === 'asset') {\n    return { scope: source.scope, mediaId: source.mediaId }\n  }\n  if (source.kind !== 'storage-object') return null\n  if (options?.bucket !== undefined && source.bucket !== options.bucket) {\n    return null\n  }\n  return paidMediaAssetOfObject(source.objectPath)\n}\n\n/**\n * Whether two scope segments name the same library: the same host, or the\n * same org whatever site either is qualified with.\n */\nexport function samePaidMediaLibrary(a: string, b: string): boolean {\n  const library = (scope: string) =>\n    scope.startsWith('org:') ? `org:${scope.slice(4).split(':')[0]}` : scope\n  return library(a) === library(b)\n}\n"],"names":["isFirstPartyHost","MEDIA_CDN_ROUTE","mediaAssetOfObjectKey","MEDIA_REF_PREFIX","parseMediaRef","STORAGE_DOWNLOAD_HOST","GCS_HOST","storageEmulatorHost","process","env","undefined","String","trim","toLowerCase","assetFromCdnPath","path","rest","slice","length","split","segments","kind","scope","decodeURIComponent","ref","mediaId","decodePath","pieces","map","piece","join","parsePaidMediaSource","stored","value","startsWith","test","url","URL","hostname","emulator","host","match","exec","pathname","bucket","objectPath","bucketPiece","objectPieces","paidMediaAssetOfObject","paidMediaAssetOf","options","source","samePaidMediaLibrary","a","b","library"],"mappings":"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"}

package/src/lib/app-utils/person-erasure.d.ts

@@ -71,8 +71,11 @@ export interface PersonErasureRequest {
      */
     pendingSinceMs?: number;
     erasedAtMs?: number;
-    /** Counts only — what the sweep removed or anonymized, for the audit. */
-    result?: Record<string, number>;
+    /**
+     * Counts only — what the sweep removed or anonymized, for the audit: the
+     * platform's own figures, and each plugin's share under `plugins`.
+     */
+    result?: Readonly<Record<string, unknown>>;
     failedAtMs?: number;
     failureCount?: number;
     /** The last failure's message, for the staff reader. Never the data. */

package/src/lib/app-utils/person-erasure.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/person-erasure.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 * Privacy erasure of one PERSON from one workspace (AGL-2623).\n *\n * The CRM's **Delete contact** is a detach: one site lets go of a shared row\n * and the document dies only when the last holder does. A privacy erasure is\n * the opposite act — the person is removed from every site in the workspace\n * regardless of who holds them, together with everything the workspace keeps\n * beside them — and it is filed as a REQUEST rather than executed on the\n * click, so that the same daily job that executes workspace erasures\n * executes these, with one audit trail and one place to watch the queue.\n *\n * A request lives at `personErasures/{orgId}__{sha256(email)}`: keyed by\n * the workspace AND the person, because the workspace is the controller of\n * this data and a second workspace that also knows the person has a\n * relationship of its own that this request has no claim on. The id is\n * deterministic so a second request for the same person is the same\n * document rather than a second one, and the address itself is carried only\n * while the request is pending — the sweep needs it to find the records,\n * and the completed request keeps the hash alone.\n *\n * Pure data module: names, types and the small helpers the dialog, the\n * route and the job would otherwise each write for themselves. No\n * Firestore, no React, no `node:` import — the client barrel re-exports it.\n */\n\nimport { normalizeContactEmail } from './contacts'\n\n/** Top-level collection holding one document per (workspace, person). */\nexport const PERSON_ERASURES_COLLECTION = 'personErasures'\n\n/**\n * The document id: workspace first, then the person's key, joined by a\n * separator neither can contain. A Firestore id may not hold a `/`, and a\n * person key is hex, so a double underscore is unambiguous.\n */\nexport function personErasureId(orgId: string, personKey: string): string {\n  if (!orgId || !personKey) {\n    throw new Error('a person erasure names a workspace and a person')\n  }\n  return `${orgId}__${personKey}`\n}\n\n/**\n * The field a pending request stamps on the records it covers — the contact\n * document and each site's lead — so a record page can show the state off\n * the document it already listens to, with no second read. Epoch millis.\n *\n * A marker, not the request: the job reads the queue, never this field, so\n * a client write that strips it hides the banner and changes nothing else.\n */\nexport const CONTACT_ERASURE_REQUESTED_FIELD = 'erasureRequestedAtMs'\n\n/** When a record's erasure was requested, or null for a record with none. */\nexport function readErasureRequestedAtMs(\n  row: Record<string, unknown> | null | undefined,\n): number | null {\n  const value = (row ?? {})[CONTACT_ERASURE_REQUESTED_FIELD]\n  return typeof value === 'number' && Number.isFinite(value) && value > 0\n    ? value\n    : null\n}\n\n/**\n * Where a request is in its life.\n *\n * - `pending` — filed, waiting for the next run. `pendingSinceMs` is set,\n *   which is what the job orders on.\n * - `erased` — the sweep ran and reported its counts. The address is gone\n *   from the document.\n * - `failed` — the sweep threw. The request stays pending (it keeps\n *   `pendingSinceMs`, moved to the back of the queue) so the next run tries\n *   again, and the failure is on the document for a staff member to read.\n */\nexport type PersonErasureStatus = 'pending' | 'erased' | 'failed'\n\n/** `personErasures/{orgId}__{personKey}` document shape. */\nexport interface PersonErasureRequest {\n  orgId: string\n  /** `sha256(normalizedEmail)` — the same key `emailDeliveries` files under. */\n  personKey: string\n  status: PersonErasureStatus\n  /**\n   * The address, present ONLY while the request is pending: the sweep\n   * queries by it, and nothing else may. Deleted by the job on completion.\n   */\n  email?: string\n  requestedAtMs: number\n  /** The workspace admin who filed it. */\n  requestedByUid: string\n  /** The site the request was filed from — for the activity feed's link. */\n  hostId?: string\n  /** The record it was filed from, when it was a contact. */\n  contactId?: string\n  /** The record it was filed from, when it was a lead. */\n  leadId?: string\n  /**\n   * Set while pending. Absent once erased, so `orderBy('pendingSinceMs')`\n   * lists exactly the queue — a document without the field is not returned.\n   */\n  pendingSinceMs?: number\n  erasedAtMs?: number\n  /** Counts only — what the sweep removed or anonymized, for the audit. */\n  result?: Record<string, number>\n  failedAtMs?: number\n  failureCount?: number\n  /** The last failure's message, for the staff reader. Never the data. */\n  lastError?: string\n}\n\n/**\n * The `reason` a per-site suppression row carries when it was written by\n * an erasure. Such a row keeps NO address — the id is the hash — and does\n * two jobs the ordinary suppression already does one of: every campaign\n * gate refuses the address, and the contact capture path refuses to create\n * a record for it, so a later form fill or order does not quietly rebuild\n * the person the workspace just erased.\n */\nexport const PERSON_ERASURE_SUPPRESSION_REASON = 'erasure'\n\n/**\n * What a door says when it refuses to create a record for an erased address\n * — the contact create route and both lead-convert doors alike. The person\n * asked to be removed and a workspace admin filed it; a record cannot be\n * re-created by hand any more than by a form, and the sentence says where\n * the decision lives rather than implying the address is malformed.\n */\nexport const CONTACT_ERASED_MESSAGE =\n  'This person was erased from your workspace at their request, so a ' +\n  'record cannot be created for this address.'\n\n/**\n * What one request removes across the workspace — the dialog's list and the\n * docs' list, from one source so the two cannot drift. Each line names a\n * thing a reader recognizes from the console, not a collection.\n */\nexport const PERSON_ERASURE_REMOVES: readonly string[] = [\n  'The contact record on every site in this workspace — profile, notes, tags, timeline and custom fields',\n  'Every lead for this address, on every site',\n  'The tasks and logged activities filed against the person',\n  'The person on any email audience list',\n  'The campaign delivery log — every message sent to the address, with its opens and clicks',\n]\n\n/**\n * What survives, and how. Orders and bookings are the workspace's financial\n * and appointment records, and tax law keeps them; the person is taken off\n * them rather than the record destroyed. A deal is the team's own pipeline\n * record and is unlinked, not deleted.\n */\nexport const PERSON_ERASURE_RETAINS: readonly string[] = [\n  'Orders and bookings stay as financial records with the name, email, phone and addresses removed',\n  'Deals stay on the pipeline, unlinked from the person',\n  'Companies stay, with their contact count reduced',\n]\n\n/**\n * What the request does not reach, so the admin can finish the job by hand\n * where the person asked for everything. A form submission keeps the\n * address inside the answers it recorded, under whatever the form called\n * the field, so there is no key to find them by; a site member holds a\n * login of their own.\n */\nexport const PERSON_ERASURE_NOT_REACHED: readonly string[] = [\n  'Form submissions — delete them from the Inbox',\n  'A site member account — close it from the site’s Members page',\n]\n\n/**\n * Whether the typed confirmation names the record's address.\n *\n * Normalized on both sides, so `Jane@Example.com` confirms `jane@example.com`\n * — the confirmation is there to make the admin read the address, not to\n * test their capitalization.\n */\nexport function personErasureConfirmationMatches(\n  typed: unknown,\n  email: unknown,\n): boolean {\n  const wanted = normalizeContactEmail(email)\n  if (!wanted) return false\n  return normalizeContactEmail(typed) === wanted\n}\n"],"names":["normalizeContactEmail","PERSON_ERASURES_COLLECTION","personErasureId","orgId","personKey","Error","CONTACT_ERASURE_REQUESTED_FIELD","readErasureRequestedAtMs","row","value","Number","isFinite","PERSON_ERASURE_SUPPRESSION_REASON","CONTACT_ERASED_MESSAGE","PERSON_ERASURE_REMOVES","PERSON_ERASURE_RETAINS","PERSON_ERASURE_NOT_REACHED","personErasureConfirmationMatches","typed","email","wanted"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAED,SAASA,qBAAqB,QAAQ,gBAAY;AAElD,uEAAuE,GACvE,OAAO,MAAMC,6BAA6B,iBAAgB;AAE1D;;;;CAIC,GACD,OAAO,SAASC,gBAAgBC,KAAa,EAAEC,SAAiB;IAC9D,IAAI,CAACD,SAAS,CAACC,WAAW;QACxB,MAAM,IAAIC,MAAM;IAClB;IACA,OAAO,GAAGF,MAAM,EAAE,EAAEC,WAAW;AACjC;AAEA;;;;;;;CAOC,GACD,OAAO,MAAME,kCAAkC,uBAAsB;AAErE,2EAA2E,GAC3E,OAAO,SAASC,yBACdC,GAA+C;IAE/C,MAAMC,QAAQ,CAACD,cAAAA,MAAO,CAAC,EAAE,CAACF,gCAAgC;IAC1D,OAAO,OAAOG,UAAU,YAAYC,OAAOC,QAAQ,CAACF,UAAUA,QAAQ,IAClEA,QACA;AACN;AAiDA;;;;;;;CAOC,GACD,OAAO,MAAMG,oCAAoC,UAAS;AAE1D;;;;;;CAMC,GACD,OAAO,MAAMC,yBACX,uEACA,6CAA4C;AAE9C;;;;CAIC,GACD,OAAO,MAAMC,yBAA4C;IACvD;IACA;IACA;IACA;IACA;CACD,CAAA;AAED;;;;;CAKC,GACD,OAAO,MAAMC,yBAA4C;IACvD;IACA;IACA;CACD,CAAA;AAED;;;;;;CAMC,GACD,OAAO,MAAMC,6BAAgD;IAC3D;IACA;CACD,CAAA;AAED;;;;;;CAMC,GACD,OAAO,SAASC,iCACdC,KAAc,EACdC,KAAc;IAEd,MAAMC,SAASpB,sBAAsBmB;IACrC,IAAI,CAACC,QAAQ,OAAO;IACpB,OAAOpB,sBAAsBkB,WAAWE;AAC1C"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/person-erasure.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 * Privacy erasure of one PERSON from one workspace (AGL-2623).\n *\n * The CRM's **Delete contact** is a detach: one site lets go of a shared row\n * and the document dies only when the last holder does. A privacy erasure is\n * the opposite act — the person is removed from every site in the workspace\n * regardless of who holds them, together with everything the workspace keeps\n * beside them — and it is filed as a REQUEST rather than executed on the\n * click, so that the same daily job that executes workspace erasures\n * executes these, with one audit trail and one place to watch the queue.\n *\n * A request lives at `personErasures/{orgId}__{sha256(email)}`: keyed by\n * the workspace AND the person, because the workspace is the controller of\n * this data and a second workspace that also knows the person has a\n * relationship of its own that this request has no claim on. The id is\n * deterministic so a second request for the same person is the same\n * document rather than a second one, and the address itself is carried only\n * while the request is pending — the sweep needs it to find the records,\n * and the completed request keeps the hash alone.\n *\n * Pure data module: names, types and the small helpers the dialog, the\n * route and the job would otherwise each write for themselves. No\n * Firestore, no React, no `node:` import — the client barrel re-exports it.\n */\n\nimport { normalizeContactEmail } from './contacts'\n\n/** Top-level collection holding one document per (workspace, person). */\nexport const PERSON_ERASURES_COLLECTION = 'personErasures'\n\n/**\n * The document id: workspace first, then the person's key, joined by a\n * separator neither can contain. A Firestore id may not hold a `/`, and a\n * person key is hex, so a double underscore is unambiguous.\n */\nexport function personErasureId(orgId: string, personKey: string): string {\n  if (!orgId || !personKey) {\n    throw new Error('a person erasure names a workspace and a person')\n  }\n  return `${orgId}__${personKey}`\n}\n\n/**\n * The field a pending request stamps on the records it covers — the contact\n * document and each site's lead — so a record page can show the state off\n * the document it already listens to, with no second read. Epoch millis.\n *\n * A marker, not the request: the job reads the queue, never this field, so\n * a client write that strips it hides the banner and changes nothing else.\n */\nexport const CONTACT_ERASURE_REQUESTED_FIELD = 'erasureRequestedAtMs'\n\n/** When a record's erasure was requested, or null for a record with none. */\nexport function readErasureRequestedAtMs(\n  row: Record<string, unknown> | null | undefined,\n): number | null {\n  const value = (row ?? {})[CONTACT_ERASURE_REQUESTED_FIELD]\n  return typeof value === 'number' && Number.isFinite(value) && value > 0\n    ? value\n    : null\n}\n\n/**\n * Where a request is in its life.\n *\n * - `pending` — filed, waiting for the next run. `pendingSinceMs` is set,\n *   which is what the job orders on.\n * - `erased` — the sweep ran and reported its counts. The address is gone\n *   from the document.\n * - `failed` — the sweep threw. The request stays pending (it keeps\n *   `pendingSinceMs`, moved to the back of the queue) so the next run tries\n *   again, and the failure is on the document for a staff member to read.\n */\nexport type PersonErasureStatus = 'pending' | 'erased' | 'failed'\n\n/** `personErasures/{orgId}__{personKey}` document shape. */\nexport interface PersonErasureRequest {\n  orgId: string\n  /** `sha256(normalizedEmail)` — the same key `emailDeliveries` files under. */\n  personKey: string\n  status: PersonErasureStatus\n  /**\n   * The address, present ONLY while the request is pending: the sweep\n   * queries by it, and nothing else may. Deleted by the job on completion.\n   */\n  email?: string\n  requestedAtMs: number\n  /** The workspace admin who filed it. */\n  requestedByUid: string\n  /** The site the request was filed from — for the activity feed's link. */\n  hostId?: string\n  /** The record it was filed from, when it was a contact. */\n  contactId?: string\n  /** The record it was filed from, when it was a lead. */\n  leadId?: string\n  /**\n   * Set while pending. Absent once erased, so `orderBy('pendingSinceMs')`\n   * lists exactly the queue — a document without the field is not returned.\n   */\n  pendingSinceMs?: number\n  erasedAtMs?: number\n  /**\n   * Counts only — what the sweep removed or anonymized, for the audit: the\n   * platform's own figures, and each plugin's share under `plugins`.\n   */\n  result?: Readonly<Record<string, unknown>>\n  failedAtMs?: number\n  failureCount?: number\n  /** The last failure's message, for the staff reader. Never the data. */\n  lastError?: string\n}\n\n/**\n * The `reason` a per-site suppression row carries when it was written by\n * an erasure. Such a row keeps NO address — the id is the hash — and does\n * two jobs the ordinary suppression already does one of: every campaign\n * gate refuses the address, and the contact capture path refuses to create\n * a record for it, so a later form fill or order does not quietly rebuild\n * the person the workspace just erased.\n */\nexport const PERSON_ERASURE_SUPPRESSION_REASON = 'erasure'\n\n/**\n * What a door says when it refuses to create a record for an erased address\n * — the contact create route and both lead-convert doors alike. The person\n * asked to be removed and a workspace admin filed it; a record cannot be\n * re-created by hand any more than by a form, and the sentence says where\n * the decision lives rather than implying the address is malformed.\n */\nexport const CONTACT_ERASED_MESSAGE =\n  'This person was erased from your workspace at their request, so a ' +\n  'record cannot be created for this address.'\n\n/**\n * What one request removes across the workspace — the dialog's list and the\n * docs' list, from one source so the two cannot drift. Each line names a\n * thing a reader recognizes from the console, not a collection.\n */\nexport const PERSON_ERASURE_REMOVES: readonly string[] = [\n  'The contact record on every site in this workspace — profile, notes, tags, timeline and custom fields',\n  'Every lead for this address, on every site',\n  'The tasks and logged activities filed against the person',\n  'The person on any email audience list',\n  'The campaign delivery log — every message sent to the address, with its opens and clicks',\n]\n\n/**\n * What survives, and how. Orders and bookings are the workspace's financial\n * and appointment records, and tax law keeps them; the person is taken off\n * them rather than the record destroyed. A deal is the team's own pipeline\n * record and is unlinked, not deleted.\n */\nexport const PERSON_ERASURE_RETAINS: readonly string[] = [\n  'Orders and bookings stay as financial records with the name, email, phone and addresses removed',\n  'Deals stay on the pipeline, unlinked from the person',\n  'Companies stay, with their contact count reduced',\n]\n\n/**\n * What the request does not reach, so the admin can finish the job by hand\n * where the person asked for everything. A form submission keeps the\n * address inside the answers it recorded, under whatever the form called\n * the field, so there is no key to find them by; a site member holds a\n * login of their own.\n */\nexport const PERSON_ERASURE_NOT_REACHED: readonly string[] = [\n  'Form submissions — delete them from the Inbox',\n  'A site member account — close it from the site’s Members page',\n]\n\n/**\n * Whether the typed confirmation names the record's address.\n *\n * Normalized on both sides, so `Jane@Example.com` confirms `jane@example.com`\n * — the confirmation is there to make the admin read the address, not to\n * test their capitalization.\n */\nexport function personErasureConfirmationMatches(\n  typed: unknown,\n  email: unknown,\n): boolean {\n  const wanted = normalizeContactEmail(email)\n  if (!wanted) return false\n  return normalizeContactEmail(typed) === wanted\n}\n"],"names":["normalizeContactEmail","PERSON_ERASURES_COLLECTION","personErasureId","orgId","personKey","Error","CONTACT_ERASURE_REQUESTED_FIELD","readErasureRequestedAtMs","row","value","Number","isFinite","PERSON_ERASURE_SUPPRESSION_REASON","CONTACT_ERASED_MESSAGE","PERSON_ERASURE_REMOVES","PERSON_ERASURE_RETAINS","PERSON_ERASURE_NOT_REACHED","personErasureConfirmationMatches","typed","email","wanted"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GAED,SAASA,qBAAqB,QAAQ,gBAAY;AAElD,uEAAuE,GACvE,OAAO,MAAMC,6BAA6B,iBAAgB;AAE1D;;;;CAIC,GACD,OAAO,SAASC,gBAAgBC,KAAa,EAAEC,SAAiB;IAC9D,IAAI,CAACD,SAAS,CAACC,WAAW;QACxB,MAAM,IAAIC,MAAM;IAClB;IACA,OAAO,GAAGF,MAAM,EAAE,EAAEC,WAAW;AACjC;AAEA;;;;;;;CAOC,GACD,OAAO,MAAME,kCAAkC,uBAAsB;AAErE,2EAA2E,GAC3E,OAAO,SAASC,yBACdC,GAA+C;IAE/C,MAAMC,QAAQ,CAACD,cAAAA,MAAO,CAAC,EAAE,CAACF,gCAAgC;IAC1D,OAAO,OAAOG,UAAU,YAAYC,OAAOC,QAAQ,CAACF,UAAUA,QAAQ,IAClEA,QACA;AACN;AAoDA;;;;;;;CAOC,GACD,OAAO,MAAMG,oCAAoC,UAAS;AAE1D;;;;;;CAMC,GACD,OAAO,MAAMC,yBACX,uEACA,6CAA4C;AAE9C;;;;CAIC,GACD,OAAO,MAAMC,yBAA4C;IACvD;IACA;IACA;IACA;IACA;CACD,CAAA;AAED;;;;;CAKC,GACD,OAAO,MAAMC,yBAA4C;IACvD;IACA;IACA;CACD,CAAA;AAED;;;;;;CAMC,GACD,OAAO,MAAMC,6BAAgD;IAC3D;IACA;CACD,CAAA;AAED;;;;;;CAMC,GACD,OAAO,SAASC,iCACdC,KAAc,EACdC,KAAc;IAEd,MAAMC,SAASpB,sBAAsBmB;IACrC,IAAI,CAACC,QAAQ,OAAO;IACpB,OAAOpB,sBAAsBkB,WAAWE;AAC1C"}

package/src/lib/app-utils/picklists.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @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.
+ */
+/** The most values one list holds — a menu, not a table. */
+export declare const PICKLIST_VALUES_MAX = 200;
+/** The longest label a value carries. */
+export declare const PICKLIST_LABEL_MAX = 120;
+/** One value of a list. `id` never changes; `label` is what records store. */
+export interface PicklistValue {
+    id: string;
+    label: string;
+    active: boolean;
+    /**
+     * The group the value is listed under, by group id; `null` for none.
+     * Present only on a list whose spec has groups.
+     */
+    group?: string | null;
+    /**
+     * What the value MEANS to the platform, from the spec's `meanings`;
+     * `null` for an added value that names none. Present only on a list whose
+     * spec has meanings, and fixed by the spec for a standard value.
+     */
+    meaning?: string | null;
+}
+/** A list as stored and as every reader takes it. */
+export interface PicklistValueSet {
+    /** In the order every picker lists them. */
+    values: PicklistValue[];
+    /** The value a new record starts with, by id — `null` for none. */
+    defaultValueId: string | null;
+}
+/** One value a spec ships to every organization. */
+export interface PicklistStandardValue {
+    id: string;
+    label: string;
+    group?: string;
+    meaning?: string;
+}
+/** One heading values may be listed under. */
+export interface PicklistGroup {
+    id: string;
+    label: string;
+}
+/** What the engine needs to know of a picklist. */
+export interface PicklistSpec {
+    /**
+     * A restricted list refuses a write naming a value it does not hold; an
+     * unrestricted one stores it as typed.
+     */
+    restricted: boolean;
+    /** The values every organization has, in their starting order. */
+    standardValues: readonly PicklistStandardValue[];
+    /** The value a new record starts with while the organization has stored no list. */
+    defaultValueId?: string;
+    /** The headings values are listed under, in order; ungrouped values come last. */
+    groups?: readonly PicklistGroup[];
+    /**
+     * The platform's own vocabulary for what a value means, when it has one.
+     * Every value carries one of these or `null`, and a value deleted with a
+     * replacement moves its records only to a value of the SAME meaning.
+     */
+    meanings?: readonly string[];
+}
+/** A label as a list stores it: trimmed, single-spaced, capped. */
+export declare function normalizePicklistLabel(value: unknown): string;
+/** The key two labels are compared by: case and spacing do not make a new value. */
+export declare function picklistLabelKey(label: unknown): string;
+/**
+ * A new value's id: the label as a slug, suffixed until it is not one of
+ * `taken`. Derived rather than random so a list reads the same in every
+ * organization, and never reused, because a default names a value by it.
+ * A caller minting an ADDED value counts every standard id as taken, so an
+ * added value can never be mistaken for a standard one.
+ */
+export declare function mintPicklistValueId(label: string, taken: Iterable<string>): string;
+/** A list of active values from labels, in order, with no default. */
+export declare function picklistFromLabels(labels: readonly string[]): PicklistValueSet;
+/** The standard value an id names under `spec`, or `null`. */
+export declare function picklistStandardValue(spec: PicklistSpec, id: string | null | undefined): PicklistStandardValue | null;
+/** Whether `id` is one of the spec's standard values — computed, never stored. */
+export declare function isStandardPicklistValueId(spec: PicklistSpec, id: string | null | undefined): boolean;
+/**
+ * A stored document as a list, or `null` for one that holds none.
+ *
+ * Tolerant, because the document is client-written: a value with no label
+ * is dropped, a second value with the same label (in any case) or the same
+ * id is dropped, `active` is true unless it is `false`, and a default that
+ * names no value is no default. With a `spec`, each value's group and
+ * meaning are read against it as well.
+ */
+export declare function normalizePicklistValueSet(raw: unknown, spec?: PicklistSpec): PicklistValueSet | null;
+/**
+ * The effective list: `stored` (already normalized against `spec`) with
+ * every standard value it lacks — see the block header. `null` for an
+ * organization that stored nothing answers the standard values in order,
+ * with the spec's default.
+ */
+export declare function mergePicklistStandard(spec: PicklistSpec, stored: PicklistValueSet | null): PicklistValueSet;
+/** A stored document as every reader should take it under `spec`. */
+export declare function effectivePicklistValueSet(spec: PicklistSpec, raw: unknown): PicklistValueSet;
+/** The value a label names, in any case or spacing — `null` for none. */
+export declare function picklistValueByLabel(set: PicklistValueSet, label: unknown): PicklistValue | null;
+/** The values a picker offers. */
+export declare function picklistActiveValues(set: PicklistValueSet): PicklistValue[];
+/** The label a new record starts with — only while the default value is active. */
+export declare function picklistDefaultLabel(set: PicklistValueSet): string | null;
+/**
+ * The sentence a value outside a restricted list is refused with, naming
+ * what the list allows: `{field} must be one of: …`. A long list is cut at
+ * twenty names so the sentence stays one a person can read; `empty` is the
+ * sentence for a list with no active value at all.
+ */
+export declare function picklistRefusalSentence(set: PicklistValueSet, words: {
+    field: string;
+    empty: string;
+}): string;
+/** What a judged write stores, or why it is refused. */
+export type PicklistJudgement = {
+    ok: true;
+    value: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Whether a write may store `value` on a record, and the label it stores.
+ *
+ *  - Blank or `null` clears the field.
+ *  - An ACTIVE value, in any case or spacing, stores that value's label.
+ *  - The record's `current` value is kept even when it is inactive or no
+ *    longer listed: re-saving a record must never be refused for a value
+ *    somebody else deactivated.
+ *  - On an unrestricted list anything else is stored — as the list spells
+ *    it when the list holds it, else as typed.
+ *  - On a restricted list anything else is refused with `refusal()`.
+ */
+export declare function judgePicklistValue(set: PicklistValueSet, value: unknown, options: {
+    restricted: boolean;
+    current?: unknown;
+    refusal: () => string;
+}): PicklistJudgement;
+/** One option of a select over a list. */
+export interface PicklistOption {
+    label: string;
+    /** Listed but deactivated — shown with an "(inactive)" hint. */
+    inactive: boolean;
+    /** Not in the list at all — a value written before the list held it. */
+    unlisted: boolean;
+    /** The group it is listed under, when the list has groups; `null` for none. */
+    group?: string | null;
+}
+/**
+ * What a select offers for a record holding `current`: every active value
+ * in order, then the record's own value when the list would not otherwise
+ * show it, so the select keeps what the record holds until it is changed.
+ */
+export declare function picklistOptions(set: PicklistValueSet, current?: unknown): PicklistOption[];
+/** One heading of a grouped select and the options under it; `group` null is the ungrouped tail. */
+export interface PicklistOptionGroup {
+    group: PicklistGroup | null;
+    options: PicklistOption[];
+}
+/**
+ * Options under their headings: each group in the spec's order, then every
+ * option with no group (or an unknown one) last. A heading with no option
+ * is left out, and the list's own order holds within each.
+ */
+export declare function groupPicklistOptions(options: readonly PicklistOption[], groups: readonly PicklistGroup[]): PicklistOptionGroup[];
+/**
+ * Where a label sorts: its value's position in the list, unlisted values
+ * after every listed one, and a record with none last. The order the admin
+ * chose is the order a sort by the field reads in.
+ */
+export declare function picklistRank(set: PicklistValueSet, label: unknown): number;