@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/payments-configured.js

@@ -0,0 +1,88 @@
+/**
+ * @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 { PLATFORM_BRAND_NAME } from "./platform-brand.js";
+/**
+ * "Not configured" is not "failed" (AGL-2019).
+ *
+ * Every money door in this codebase answers `501` when the deployment has no
+ * Stripe key — server-side that is already correct and uniform. The defect was
+ * entirely on the client: the storefront cart had a `423` lockdown branch and
+ * no `501` branch, so an unconfigured-payments refusal fell through to the
+ * generic error tail and rendered as `<Alert severity="error">`. A shopper on a
+ * self-hosted store clicked **Checkout** and was shown a RED alert — which says
+ * *your payment failed* — for a store that had simply never been set up to take
+ * payments. Nothing failed. Nothing was even attempted.
+ *
+ * This is the same argument `lockdown.ts` makes for its `423`: a refusal that is
+ * not a failure needs its own state, not an error with gentler words, because
+ * the severity is read before the sentence is. The three states are distinct and
+ * must stay distinct:
+ *
+ *   423  paused      the operator switched writes off       — info
+ *   501  unconfigured this deployment never had payments    — info
+ *   4xx/5xx error     something was tried and went wrong    — error
+ *
+ * The copy is deliberately split by AUDIENCE, and that split is the reason this
+ * module exists rather than a bare status check at each call site:
+ *
+ *  - A STOREFRONT VISITOR is a stranger on someone else's site. They get a
+ *    neutral sentence about the store and NOTHING about the cause. Naming an
+ *    environment variable to a shopper leaks the operator's deployment shape to
+ *    the public internet, and there is nothing they could do with it anyway.
+ *  - A CONSOLE OPERATOR is the person who can fix it, so they are told what to
+ *    set. They also get `PLATFORM_BRAND_NAME`, because on a self-host install
+ *    the product is not called Aglyn.
+ */ /**
+ * The status a server uses to say "this deployment has no payments configured".
+ * Named so a call site reads as a concept rather than as a magic number.
+ */ export const PAYMENTS_NOT_CONFIGURED_STATUS = 501;
+/**
+ * Is this response the not-configured refusal rather than a failure?
+ *
+ * Deliberately a status-only test. The 501 bodies across commerce and
+ * marketplace do not share a machine-readable discriminator — some say
+ * "Purchases are not configured on this site.", others "Payments are not
+ * configured." — and matching on prose would break the moment one is reworded.
+ * The status is the contract.
+ */ export function isPaymentsNotConfigured(status) {
+    return status === PAYMENTS_NOT_CONFIGURED_STATUS;
+}
+/**
+ * What a STOREFRONT VISITOR is shown. No cause, no variable names, no mention
+ * of the platform — from the shopper's side this is a fact about the store.
+ *
+ * Present tense and permanent-sounding on purpose: "right now" or "temporarily"
+ * would imply a transient outage and invite a retry that cannot succeed.
+ */ export function storefrontPaymentsNotConfiguredText() {
+    return 'This store is not set up to take payments.';
+}
+/**
+ * What a CONSOLE OPERATOR is shown. They can act, so they are told how.
+ *
+ * `PLATFORM_BRAND_NAME` rather than a literal: a self-hoster who renamed the
+ * product should not read our name in an explanation of their own deployment.
+ */ export function operatorPaymentsNotConfiguredText() {
+    return `${PLATFORM_BRAND_NAME} is not configured to take payments on this ` + 'deployment. Set STRIPE_SECRET_KEY and restart to enable purchases, ' + 'payouts and subscriptions.';
+}
+/**
+ * The marketplace's own sentence. Browsing works without Stripe; only the
+ * money doors do not — so this says what still works, rather than presenting a
+ * whole feature as broken.
+ */ export function operatorMarketplaceNotConfiguredText() {
+    return 'Browsing and free installs work as normal. Paid listings, purchases and ' + 'publisher payouts need a Stripe platform account, which this deployment ' + 'does not have configured.';
+}
+
+//# sourceMappingURL=payments-configured.js.map

package/src/lib/app-utils/payments-configured.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/payments-configured.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 { PLATFORM_BRAND_NAME } from './platform-brand'\n\n/**\n * \"Not configured\" is not \"failed\" (AGL-2019).\n *\n * Every money door in this codebase answers `501` when the deployment has no\n * Stripe key — server-side that is already correct and uniform. The defect was\n * entirely on the client: the storefront cart had a `423` lockdown branch and\n * no `501` branch, so an unconfigured-payments refusal fell through to the\n * generic error tail and rendered as `<Alert severity=\"error\">`. A shopper on a\n * self-hosted store clicked **Checkout** and was shown a RED alert — which says\n * *your payment failed* — for a store that had simply never been set up to take\n * payments. Nothing failed. Nothing was even attempted.\n *\n * This is the same argument `lockdown.ts` makes for its `423`: a refusal that is\n * not a failure needs its own state, not an error with gentler words, because\n * the severity is read before the sentence is. The three states are distinct and\n * must stay distinct:\n *\n *   423  paused      the operator switched writes off       — info\n *   501  unconfigured this deployment never had payments    — info\n *   4xx/5xx error     something was tried and went wrong    — error\n *\n * The copy is deliberately split by AUDIENCE, and that split is the reason this\n * module exists rather than a bare status check at each call site:\n *\n *  - A STOREFRONT VISITOR is a stranger on someone else's site. They get a\n *    neutral sentence about the store and NOTHING about the cause. Naming an\n *    environment variable to a shopper leaks the operator's deployment shape to\n *    the public internet, and there is nothing they could do with it anyway.\n *  - A CONSOLE OPERATOR is the person who can fix it, so they are told what to\n *    set. They also get `PLATFORM_BRAND_NAME`, because on a self-host install\n *    the product is not called Aglyn.\n */\n\n/**\n * The status a server uses to say \"this deployment has no payments configured\".\n * Named so a call site reads as a concept rather than as a magic number.\n */\nexport const PAYMENTS_NOT_CONFIGURED_STATUS = 501\n\n/**\n * Is this response the not-configured refusal rather than a failure?\n *\n * Deliberately a status-only test. The 501 bodies across commerce and\n * marketplace do not share a machine-readable discriminator — some say\n * \"Purchases are not configured on this site.\", others \"Payments are not\n * configured.\" — and matching on prose would break the moment one is reworded.\n * The status is the contract.\n */\nexport function isPaymentsNotConfigured(status: number | null | undefined) {\n  return status === PAYMENTS_NOT_CONFIGURED_STATUS\n}\n\n/**\n * What a STOREFRONT VISITOR is shown. No cause, no variable names, no mention\n * of the platform — from the shopper's side this is a fact about the store.\n *\n * Present tense and permanent-sounding on purpose: \"right now\" or \"temporarily\"\n * would imply a transient outage and invite a retry that cannot succeed.\n */\nexport function storefrontPaymentsNotConfiguredText() {\n  return 'This store is not set up to take payments.'\n}\n\n/**\n * What a CONSOLE OPERATOR is shown. They can act, so they are told how.\n *\n * `PLATFORM_BRAND_NAME` rather than a literal: a self-hoster who renamed the\n * product should not read our name in an explanation of their own deployment.\n */\nexport function operatorPaymentsNotConfiguredText() {\n  return (\n    `${PLATFORM_BRAND_NAME} is not configured to take payments on this ` +\n    'deployment. Set STRIPE_SECRET_KEY and restart to enable purchases, ' +\n    'payouts and subscriptions.'\n  )\n}\n\n/**\n * The marketplace's own sentence. Browsing works without Stripe; only the\n * money doors do not — so this says what still works, rather than presenting a\n * whole feature as broken.\n */\nexport function operatorMarketplaceNotConfiguredText() {\n  return (\n    'Browsing and free installs work as normal. Paid listings, purchases and ' +\n    'publisher payouts need a Stripe platform account, which this deployment ' +\n    'does not have configured.'\n  )\n}\n"],"names":["PLATFORM_BRAND_NAME","PAYMENTS_NOT_CONFIGURED_STATUS","isPaymentsNotConfigured","status","storefrontPaymentsNotConfiguredText","operatorPaymentsNotConfiguredText","operatorMarketplaceNotConfiguredText"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,mBAAmB,QAAQ,sBAAkB;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BC,GAED;;;CAGC,GACD,OAAO,MAAMC,iCAAiC,IAAG;AAEjD;;;;;;;;CAQC,GACD,OAAO,SAASC,wBAAwBC,MAAiC;IACvE,OAAOA,WAAWF;AACpB;AAEA;;;;;;CAMC,GACD,OAAO,SAASG;IACd,OAAO;AACT;AAEA;;;;;CAKC,GACD,OAAO,SAASC;IACd,OACE,GAAGL,oBAAoB,4CAA4C,CAAC,GACpE,wEACA;AAEJ;AAEA;;;;CAIC,GACD,OAAO,SAASM;IACd,OACE,6EACA,6EACA;AAEJ"}

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

@@ -0,0 +1,126 @@
+/**
+ * @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.
+ */
+/** Top-level collection holding one document per (workspace, person). */
+export declare const PERSON_ERASURES_COLLECTION = "personErasures";
+/**
+ * The document id: workspace first, then the person's key, joined by a
+ * separator neither can contain. A Firestore id may not hold a `/`, and a
+ * person key is hex, so a double underscore is unambiguous.
+ */
+export declare function personErasureId(orgId: string, personKey: string): string;
+/**
+ * The field a pending request stamps on the records it covers — the contact
+ * document and each site's lead — so a record page can show the state off
+ * the document it already listens to, with no second read. Epoch millis.
+ *
+ * A marker, not the request: the job reads the queue, never this field, so
+ * a client write that strips it hides the banner and changes nothing else.
+ */
+export declare const CONTACT_ERASURE_REQUESTED_FIELD = "erasureRequestedAtMs";
+/** When a record's erasure was requested, or null for a record with none. */
+export declare function readErasureRequestedAtMs(row: Record<string, unknown> | null | undefined): number | null;
+/**
+ * Where a request is in its life.
+ *
+ * - `pending` — filed, waiting for the next run. `pendingSinceMs` is set,
+ *   which is what the job orders on.
+ * - `erased` — the sweep ran and reported its counts. The address is gone
+ *   from the document.
+ * - `failed` — the sweep threw. The request stays pending (it keeps
+ *   `pendingSinceMs`, moved to the back of the queue) so the next run tries
+ *   again, and the failure is on the document for a staff member to read.
+ */
+export type PersonErasureStatus = 'pending' | 'erased' | 'failed';
+/** `personErasures/{orgId}__{personKey}` document shape. */
+export interface PersonErasureRequest {
+    orgId: string;
+    /** `sha256(normalizedEmail)` — the same key `emailDeliveries` files under. */
+    personKey: string;
+    status: PersonErasureStatus;
+    /**
+     * The address, present ONLY while the request is pending: the sweep
+     * queries by it, and nothing else may. Deleted by the job on completion.
+     */
+    email?: string;
+    requestedAtMs: number;
+    /** The workspace admin who filed it. */
+    requestedByUid: string;
+    /** The site the request was filed from — for the activity feed's link. */
+    hostId?: string;
+    /** The record it was filed from, when it was a contact. */
+    contactId?: string;
+    /** The record it was filed from, when it was a lead. */
+    leadId?: string;
+    /**
+     * Set while pending. Absent once erased, so `orderBy('pendingSinceMs')`
+     * lists exactly the queue — a document without the field is not returned.
+     */
+    pendingSinceMs?: number;
+    erasedAtMs?: number;
+    /** Counts only — what the sweep removed or anonymized, for the audit. */
+    result?: Record<string, number>;
+    failedAtMs?: number;
+    failureCount?: number;
+    /** The last failure's message, for the staff reader. Never the data. */
+    lastError?: string;
+}
+/**
+ * The `reason` a per-site suppression row carries when it was written by
+ * an erasure. Such a row keeps NO address — the id is the hash — and does
+ * two jobs the ordinary suppression already does one of: every campaign
+ * gate refuses the address, and the contact capture path refuses to create
+ * a record for it, so a later form fill or order does not quietly rebuild
+ * the person the workspace just erased.
+ */
+export declare const PERSON_ERASURE_SUPPRESSION_REASON = "erasure";
+/**
+ * What a door says when it refuses to create a record for an erased address
+ * — the contact create route and both lead-convert doors alike. The person
+ * asked to be removed and a workspace admin filed it; a record cannot be
+ * re-created by hand any more than by a form, and the sentence says where
+ * the decision lives rather than implying the address is malformed.
+ */
+export declare const CONTACT_ERASED_MESSAGE: string;
+/**
+ * What one request removes across the workspace — the dialog's list and the
+ * docs' list, from one source so the two cannot drift. Each line names a
+ * thing a reader recognizes from the console, not a collection.
+ */
+export declare const PERSON_ERASURE_REMOVES: readonly string[];
+/**
+ * What survives, and how. Orders and bookings are the workspace's financial
+ * and appointment records, and tax law keeps them; the person is taken off
+ * them rather than the record destroyed. A deal is the team's own pipeline
+ * record and is unlinked, not deleted.
+ */
+export declare const PERSON_ERASURE_RETAINS: readonly string[];
+/**
+ * What the request does not reach, so the admin can finish the job by hand
+ * where the person asked for everything. A form submission keeps the
+ * address inside the answers it recorded, under whatever the form called
+ * the field, so there is no key to find them by; a site member holds a
+ * login of their own.
+ */
+export declare const PERSON_ERASURE_NOT_REACHED: readonly string[];
+/**
+ * Whether the typed confirmation names the record's address.
+ *
+ * Normalized on both sides, so `Jane@Example.com` confirms `jane@example.com`
+ * — the confirmation is there to make the admin read the address, not to
+ * test their capitalization.
+ */
+export declare function personErasureConfirmationMatches(typed: unknown, email: unknown): boolean;

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

@@ -0,0 +1,121 @@
+/**
+ * @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.
+ */ /**
+ * Privacy erasure of one PERSON from one workspace (AGL-2623).
+ *
+ * The CRM's **Delete contact** is a detach: one site lets go of a shared row
+ * and the document dies only when the last holder does. A privacy erasure is
+ * the opposite act — the person is removed from every site in the workspace
+ * regardless of who holds them, together with everything the workspace keeps
+ * beside them — and it is filed as a REQUEST rather than executed on the
+ * click, so that the same daily job that executes workspace erasures
+ * executes these, with one audit trail and one place to watch the queue.
+ *
+ * A request lives at `personErasures/{orgId}__{sha256(email)}`: keyed by
+ * the workspace AND the person, because the workspace is the controller of
+ * this data and a second workspace that also knows the person has a
+ * relationship of its own that this request has no claim on. The id is
+ * deterministic so a second request for the same person is the same
+ * document rather than a second one, and the address itself is carried only
+ * while the request is pending — the sweep needs it to find the records,
+ * and the completed request keeps the hash alone.
+ *
+ * Pure data module: names, types and the small helpers the dialog, the
+ * route and the job would otherwise each write for themselves. No
+ * Firestore, no React, no `node:` import — the client barrel re-exports it.
+ */ import { normalizeContactEmail } from "./contacts.js";
+/** Top-level collection holding one document per (workspace, person). */ export const PERSON_ERASURES_COLLECTION = 'personErasures';
+/**
+ * The document id: workspace first, then the person's key, joined by a
+ * separator neither can contain. A Firestore id may not hold a `/`, and a
+ * person key is hex, so a double underscore is unambiguous.
+ */ export function personErasureId(orgId, personKey) {
+    if (!orgId || !personKey) {
+        throw new Error('a person erasure names a workspace and a person');
+    }
+    return `${orgId}__${personKey}`;
+}
+/**
+ * The field a pending request stamps on the records it covers — the contact
+ * document and each site's lead — so a record page can show the state off
+ * the document it already listens to, with no second read. Epoch millis.
+ *
+ * A marker, not the request: the job reads the queue, never this field, so
+ * a client write that strips it hides the banner and changes nothing else.
+ */ export const CONTACT_ERASURE_REQUESTED_FIELD = 'erasureRequestedAtMs';
+/** When a record's erasure was requested, or null for a record with none. */ export function readErasureRequestedAtMs(row) {
+    const value = (row != null ? row : {})[CONTACT_ERASURE_REQUESTED_FIELD];
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+/**
+ * The `reason` a per-site suppression row carries when it was written by
+ * an erasure. Such a row keeps NO address — the id is the hash — and does
+ * two jobs the ordinary suppression already does one of: every campaign
+ * gate refuses the address, and the contact capture path refuses to create
+ * a record for it, so a later form fill or order does not quietly rebuild
+ * the person the workspace just erased.
+ */ export const PERSON_ERASURE_SUPPRESSION_REASON = 'erasure';
+/**
+ * What a door says when it refuses to create a record for an erased address
+ * — the contact create route and both lead-convert doors alike. The person
+ * asked to be removed and a workspace admin filed it; a record cannot be
+ * re-created by hand any more than by a form, and the sentence says where
+ * the decision lives rather than implying the address is malformed.
+ */ export const CONTACT_ERASED_MESSAGE = 'This person was erased from your workspace at their request, so a ' + 'record cannot be created for this address.';
+/**
+ * What one request removes across the workspace — the dialog's list and the
+ * docs' list, from one source so the two cannot drift. Each line names a
+ * thing a reader recognizes from the console, not a collection.
+ */ export const PERSON_ERASURE_REMOVES = [
+    'The contact record on every site in this workspace — profile, notes, tags, timeline and custom fields',
+    'Every lead for this address, on every site',
+    'The tasks and logged activities filed against the person',
+    'The person on any email audience list',
+    'The campaign delivery log — every message sent to the address, with its opens and clicks'
+];
+/**
+ * What survives, and how. Orders and bookings are the workspace's financial
+ * and appointment records, and tax law keeps them; the person is taken off
+ * them rather than the record destroyed. A deal is the team's own pipeline
+ * record and is unlinked, not deleted.
+ */ export const PERSON_ERASURE_RETAINS = [
+    'Orders and bookings stay as financial records with the name, email, phone and addresses removed',
+    'Deals stay on the pipeline, unlinked from the person',
+    'Companies stay, with their contact count reduced'
+];
+/**
+ * What the request does not reach, so the admin can finish the job by hand
+ * where the person asked for everything. A form submission keeps the
+ * address inside the answers it recorded, under whatever the form called
+ * the field, so there is no key to find them by; a site member holds a
+ * login of their own.
+ */ export const PERSON_ERASURE_NOT_REACHED = [
+    'Form submissions — delete them from the Inbox',
+    'A site member account — close it from the site’s Members page'
+];
+/**
+ * Whether the typed confirmation names the record's address.
+ *
+ * Normalized on both sides, so `Jane@Example.com` confirms `jane@example.com`
+ * — the confirmation is there to make the admin read the address, not to
+ * test their capitalization.
+ */ export function personErasureConfirmationMatches(typed, email) {
+    const wanted = normalizeContactEmail(email);
+    if (!wanted) return false;
+    return normalizeContactEmail(typed) === wanted;
+}
+
+//# sourceMappingURL=person-erasure.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,32 @@
+/**
+ * @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.
+ */
+/**
+ * `sha256` of the normalized address, as full hex.
+ *
+ * Normalizing first is what stops `Bob@x.com` and `bob@x.com` keying two
+ * documents, and it is why the input is the raw value rather than an
+ * already-trimmed one: a caller that has to remember to normalize is a caller
+ * that can forget.
+ *
+ * The digest is never truncated. Truncating it is one of the three reasons the
+ * two list-member derivations this replaces were incompatible.
+ *
+ * @returns the key, or `null` for anything that is not a usable address.
+ *          Never a best-guess key: two people sharing one document is worse
+ *          than refusing to key an unusable value.
+ */
+export declare function personKey(email: unknown): string | null;

package/src/lib/app-utils/person-key.js

@@ -0,0 +1,62 @@
+/**
+ * @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 one address-derived document id in this product.
+ *
+ * `docs/specs/email-overhaul.md` §3d names this derivation for a list
+ * membership's `memberKey`; `docs/specs/reusable-forms.md` §4 names the same
+ * one for a lead's `personKey`. Both specs say in as many words that whichever
+ * ships second imports the first's helper rather than adding a third copy, so
+ * there is exactly one function and both meanings are the same value.
+ *
+ * ## Why this file, and not `contacts.ts` where the specs put it
+ *
+ * `node:crypto` cannot go into `contacts.ts`. That module is re-exported by
+ * `app-utils/server`, which `app-utils/index` re-exports, which the full
+ * `@aglyn/aglyn` barrel re-exports — the barrel client code bundles. Three
+ * modules next door (`api-adapter`, `api-idempotency`, `plugin-bundle-checks`)
+ * are held out of that barrel and exposed only through `@aglyn/aglyn/server`
+ * for exactly this reason; the third was measured at 39 KB gzipped off every
+ * published customer page. A hashing helper in `contacts.ts` would put a Node
+ * builtin on the same path.
+ *
+ * So the derivation is the specs', to the byte, and only the file is
+ * different. `normalizeContactEmail` still comes from `contacts.ts` — this
+ * composes the existing normalizer rather than restating it, which is how
+ * `emailSuppressionKey` and `suppressionId` came to disagree.
+ */ import { createHash } from "node:crypto";
+import { normalizeContactEmail } from "./contacts.js";
+/**
+ * `sha256` of the normalized address, as full hex.
+ *
+ * Normalizing first is what stops `Bob@x.com` and `bob@x.com` keying two
+ * documents, and it is why the input is the raw value rather than an
+ * already-trimmed one: a caller that has to remember to normalize is a caller
+ * that can forget.
+ *
+ * The digest is never truncated. Truncating it is one of the three reasons the
+ * two list-member derivations this replaces were incompatible.
+ *
+ * @returns the key, or `null` for anything that is not a usable address.
+ *          Never a best-guess key: two people sharing one document is worse
+ *          than refusing to key an unusable value.
+ */ export function personKey(email) {
+    const normalized = normalizeContactEmail(email);
+    if (!normalized) return null;
+    return createHash('sha256').update(normalized).digest('hex');
+}
+
+//# sourceMappingURL=person-key.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/person-key.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 * The one address-derived document id in this product.\n *\n * `docs/specs/email-overhaul.md` §3d names this derivation for a list\n * membership's `memberKey`; `docs/specs/reusable-forms.md` §4 names the same\n * one for a lead's `personKey`. Both specs say in as many words that whichever\n * ships second imports the first's helper rather than adding a third copy, so\n * there is exactly one function and both meanings are the same value.\n *\n * ## Why this file, and not `contacts.ts` where the specs put it\n *\n * `node:crypto` cannot go into `contacts.ts`. That module is re-exported by\n * `app-utils/server`, which `app-utils/index` re-exports, which the full\n * `@aglyn/aglyn` barrel re-exports — the barrel client code bundles. Three\n * modules next door (`api-adapter`, `api-idempotency`, `plugin-bundle-checks`)\n * are held out of that barrel and exposed only through `@aglyn/aglyn/server`\n * for exactly this reason; the third was measured at 39 KB gzipped off every\n * published customer page. A hashing helper in `contacts.ts` would put a Node\n * builtin on the same path.\n *\n * So the derivation is the specs', to the byte, and only the file is\n * different. `normalizeContactEmail` still comes from `contacts.ts` — this\n * composes the existing normalizer rather than restating it, which is how\n * `emailSuppressionKey` and `suppressionId` came to disagree.\n */\n\nimport { createHash } from 'node:crypto'\nimport { normalizeContactEmail } from './contacts'\n\n/**\n * `sha256` of the normalized address, as full hex.\n *\n * Normalizing first is what stops `Bob@x.com` and `bob@x.com` keying two\n * documents, and it is why the input is the raw value rather than an\n * already-trimmed one: a caller that has to remember to normalize is a caller\n * that can forget.\n *\n * The digest is never truncated. Truncating it is one of the three reasons the\n * two list-member derivations this replaces were incompatible.\n *\n * @returns the key, or `null` for anything that is not a usable address.\n *          Never a best-guess key: two people sharing one document is worse\n *          than refusing to key an unusable value.\n */\nexport function personKey(email: unknown): string | null {\n  const normalized = normalizeContactEmail(email)\n  if (!normalized) return null\n  return createHash('sha256').update(normalized).digest('hex')\n}\n"],"names":["createHash","normalizeContactEmail","personKey","email","normalized","update","digest"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GAED,SAASA,UAAU,QAAQ,cAAa;AACxC,SAASC,qBAAqB,QAAQ,gBAAY;AAElD;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,UAAUC,KAAc;IACtC,MAAMC,aAAaH,sBAAsBE;IACzC,IAAI,CAACC,YAAY,OAAO;IACxB,OAAOJ,WAAW,UAAUK,MAAM,CAACD,YAAYE,MAAM,CAAC;AACxD"}