@aglyn/tenant-data-admin 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/server/retained-refusals.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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 RetainedRefusals } from '@aglyn/aglyn/app-utils/retained-refusals';
+import { type ContactDetach } from '@aglyn/aglyn/app-utils/contacts';
+import type { ConsentGroupCarry } from '@aglyn/aglyn/app-utils/consent-group-change';
+import type { ConsentGroupCarryPage } from './consent-group-carry';
+type Doc = Record<string, unknown>;
+/** The organization document, or a collection directly under it. */
+export type RetainedRefusalsAnchor = FirebaseFirestore.DocumentReference | FirebaseFirestore.CollectionReference;
+/** Keys one `getAll` of the store reads. */
+export declare const RETAINED_REFUSALS_READ_CHUNK = 100;
+/** Documents one page of the carry reads. */
+export declare const RETAINED_REFUSALS_CARRY_PAGE = 300;
+/** The store under the organization `anchor` is, or is directly under. */
+export declare function retainedRefusalsStore(anchor: RetainedRefusalsAnchor): FirebaseFirestore.CollectionReference;
+export interface RetainRefusalsInput {
+    /** The organization document — or `contactsRef`, the collection the record was in. */
+    orgRef?: FirebaseFirestore.DocumentReference;
+    contactsRef?: FirebaseFirestore.CollectionReference;
+    /**
+     * The address the person is known by — or every one, when a merge left the
+     * record answering to more than one: each is kept under its own key.
+     */
+    email: string | readonly string[];
+    /** The record the refusals come from, stamped on each entry. */
+    contactId: string;
+    /** What `planContactDetach`'s delete (or `refusalsOf`) named. */
+    retained: RetainedRefusals | null | undefined;
+    nowMs: number;
+    /** The delete's transaction, so the retention and the delete land together. */
+    transaction?: FirebaseFirestore.Transaction;
+}
+/**
+ * Keeps a record's refusals in the store, one document per address, and
+ * answers how many documents it wrote.
+ *
+ * Each site's entry is written under its own field path, replacing that
+ * site's entry and leaving every other site retained earlier as it was; the
+ * unscoped refusal is written only when there is one, so it is never
+ * cleared by a later record that had none. Nothing is written when there is
+ * nothing to keep.
+ *
+ * Inside a transaction the writes join it, and the caller must have done its
+ * reads first, as a transaction requires. Outside one they are a batch.
+ */
+export declare function retainRefusals(input: RetainRefusalsInput): Promise<number>;
+/** What {@link removeContactKeepingRefusals} did to one contact. */
+export type ContactRemoval = {
+    outcome: 'missing';
+} | {
+    outcome: 'refused';
+    error: string;
+} | {
+    outcome: 'detached';
+} | {
+    outcome: 'deleted';
+    /** Retained documents written, one per address the contact answered to. */
+    retained: number;
+};
+export interface RemoveContactInput {
+    contactRef: FirebaseFirestore.DocumentReference;
+    /**
+     * What letting go of this contact means, decided against the document as
+     * the transaction read it: `planContactDetach` for a holder letting go,
+     * {@link deleteWholeContact} for a delete regardless of holders, or a
+     * sentence refusing it.
+     */
+    decide: (contact: Doc) => ContactDetach | {
+        refused: string;
+    };
+    nowMs: number;
+}
+/** The decision `DELETE /v1/contacts/{id}` makes: the document goes, every refusal on it kept. */
+export declare const deleteWholeContact: (contact: Doc) => ContactDetach;
+/**
+ * Lets go of one contact in one transaction, keeping every refusal it holds.
+ *
+ * A DETACH drops the leaving holder's facet, its consent GRANTS, its scope
+ * tokens and its capture attribution; a refusal entry is not among the
+ * removals `planContactDetach` names, so it stays for the holders that
+ * remain. A DELETE copies every refusal on the document into the store under
+ * each address the contact answers to — the primary and every one a merge
+ * folded in, since the list gate may be asked about any of them — and
+ * deletes the document in the same commit.
+ *
+ * ⛔ Not the erasure path, which removes the person everywhere and closes the
+ * door with suppression rows before it deletes anything.
+ */
+export declare function removeContactKeepingRefusals(input: RemoveContactInput): Promise<ContactRemoval>;
+/**
+ * The retained documents for these addresses, keyed by the normalized
+ * address; an address with nothing retained is absent.
+ *
+ * Throws when a read fails, and deliberately: every caller decides whether
+ * an operator may enroll somebody, and a read that could not see a refusal
+ * has to reach the caller's failed-read branch rather than read as none.
+ */
+export declare function readRetainedRefusals(anchor: RetainedRefusalsAnchor, emails: readonly string[]): Promise<Map<string, Doc>>;
+export interface CarryRetainedRefusalsOptions {
+    firestore: FirebaseFirestore.Firestore;
+    orgId: string;
+    carry: ConsentGroupCarry;
+    changeId: string;
+    cursor: string | null;
+    /** Only documents written at or after this instant — the catch-up. */
+    sinceMs?: number | null;
+    pageSize?: number;
+    dryRun?: boolean;
+}
+/**
+ * One page of the carry `to ← from` over the store: every retained refusal
+ * `from` holds is given to `to` where `to` has no entry, with where it came
+ * from and which change carried it. See `retainedRefusalCarry`.
+ *
+ * The full pass reads only the documents refusing `from`, by id. The
+ * catch-up reads everything written since `sinceMs`, by `updatedAt` then id,
+ * and decides each document in hand: an equality on a site's entry beside a
+ * range on `updatedAt` would need a composite index per site, which no
+ * index file can declare.
+ *
+ * Idempotent, like every carry: a write only fills an entry `to` lacks, so
+ * a page re-run after a crash, the catch-up and the sweep write nothing that
+ * was already carried. A write that raced another writer is decided again
+ * once from a fresh read; failing twice throws, and the executor retries the
+ * page from its cursor.
+ */
+export declare function carryRetainedRefusals(options: CarryRetainedRefusalsOptions): Promise<ConsentGroupCarryPage>;
+export {};

package/src/lib/server/retained-refusals.js

@@ -0,0 +1,325 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 RETAINED-REFUSAL STORE, ON THE ADMIN SDK (AGL-3338):
+ * `orgs/{orgId}/retainedRefusals/{personKey}`.
+ *
+ * What the store is for, and why it holds what it holds, is the pure
+ * module's note (`@aglyn/aglyn/app-utils/retained-refusals`). This is its
+ * server doors:
+ *
+ *  - {@link removeContactKeepingRefusals} — the one way a contact is let go
+ *    of outside an erasure: the CRM's delete and `DELETE /v1/contacts/{id}`.
+ *    It decides against the document read in its own transaction, so a
+ *    refusal written a moment before the delete is still the one kept;
+ *  - {@link retainRefusals} — the write a record's delete makes, inside the
+ *    delete's own transaction when it has one, so a record is never gone
+ *    with its refusals unkept;
+ *  - {@link readRetainedRefusals} — the read the list gate and the Inbox's
+ *    add-to-list make beside the records, which THROWS on a failed read: a
+ *    reader that cannot see whether somebody refused must not read them as
+ *    somebody who did not;
+ *  - {@link carryRetainedRefusals} — one page of a consent group change's
+ *    carry over the store, the org-level twin of the per-site carries in
+ *    `consent-group-carry.ts`.
+ *
+ * Anchored on the organization document, or on any collection under it —
+ * the caller already holds the records it is reading or deleting, and the
+ * store is their sibling.
+ */ import { personKey } from "@aglyn/aglyn/app-utils/person-key";
+import { MARKETING_CONSENT_BY_HOST_FIELD, MARKETING_CONSENT_FIELD } from "@aglyn/aglyn/app-utils/marketing-consent";
+import { RETAINED_AT_FIELD, RETAINED_REFUSALS_COLLECTION, refusalsOf, retainedEntries, retainedRefusalCarry } from "@aglyn/aglyn/app-utils/retained-refusals";
+import { contactEmails, normalizeContactEmail } from "@aglyn/aglyn/app-utils/contacts";
+import { FieldPath, FieldValue, Timestamp } from "firebase-admin/firestore";
+/** Keys one `getAll` of the store reads. */ export const RETAINED_REFUSALS_READ_CHUNK = 100;
+/** Documents one page of the carry reads. */ export const RETAINED_REFUSALS_CARRY_PAGE = 300;
+/** The organization document `anchor` is, or is directly under. */ function orgOf(anchor) {
+    const orgRef = typeof anchor.collection === 'function' ? anchor : anchor.parent;
+    if (!orgRef) throw new Error('[retained-refusals] a root collection has no organization');
+    return orgRef;
+}
+/** The store under the organization `anchor` is, or is directly under. */ export function retainedRefusalsStore(anchor) {
+    return orgOf(anchor).collection(RETAINED_REFUSALS_COLLECTION);
+}
+/**
+ * Keeps a record's refusals in the store, one document per address, and
+ * answers how many documents it wrote.
+ *
+ * Each site's entry is written under its own field path, replacing that
+ * site's entry and leaving every other site retained earlier as it was; the
+ * unscoped refusal is written only when there is one, so it is never
+ * cleared by a later record that had none. Nothing is written when there is
+ * nothing to keep.
+ *
+ * Inside a transaction the writes join it, and the caller must have done its
+ * reads first, as a transaction requires. Outside one they are a batch.
+ */ export async function retainRefusals(input) {
+    var _ref, _input_orgRef;
+    const { retained } = input;
+    const hostIds = Object.keys((_ref = retained == null ? void 0 : retained.byHost) != null ? _ref : {});
+    if (!retained || !hostIds.length && !retained.unscoped) return 0;
+    const anchor = (_input_orgRef = input.orgRef) != null ? _input_orgRef : input.contactsRef;
+    if (!anchor) throw new Error('[retained-refusals] name the organization or its contacts');
+    const orgRef = orgOf(anchor);
+    const store = orgRef.collection(RETAINED_REFUSALS_COLLECTION);
+    const emails = typeof input.email === 'string' ? [
+        input.email
+    ] : input.email;
+    const keys = [
+        ...new Set(emails.map((email)=>personKey(email)).filter((key)=>Boolean(key)))
+    ];
+    if (!keys.length) return 0;
+    const data = {
+        [MARKETING_CONSENT_BY_HOST_FIELD]: retainedEntries(retained, input.contactId, input.nowMs),
+        [RETAINED_AT_FIELD]: input.nowMs,
+        updatedAt: FieldValue.serverTimestamp()
+    };
+    const fields = [
+        ...hostIds.map((hostId)=>new FieldPath(MARKETING_CONSENT_BY_HOST_FIELD, hostId)),
+        RETAINED_AT_FIELD,
+        'updatedAt'
+    ];
+    if (retained.unscoped) {
+        data[MARKETING_CONSENT_FIELD] = false;
+        fields.push(MARKETING_CONSENT_FIELD);
+    }
+    if (input.transaction) {
+        for (const key of keys)input.transaction.set(store.doc(key), data, {
+            mergeFields: fields
+        });
+        return keys.length;
+    }
+    const batch = orgRef.firestore.batch();
+    for (const key of keys)batch.set(store.doc(key), data, {
+        mergeFields: fields
+    });
+    await batch.commit();
+    return keys.length;
+}
+/** The decision `DELETE /v1/contacts/{id}` makes: the document goes, every refusal on it kept. */ export const deleteWholeContact = (contact)=>({
+        action: 'delete',
+        retained: refusalsOf(contact)
+    });
+/**
+ * Lets go of one contact in one transaction, keeping every refusal it holds.
+ *
+ * A DETACH drops the leaving holder's facet, its consent GRANTS, its scope
+ * tokens and its capture attribution; a refusal entry is not among the
+ * removals `planContactDetach` names, so it stays for the holders that
+ * remain. A DELETE copies every refusal on the document into the store under
+ * each address the contact answers to — the primary and every one a merge
+ * folded in, since the list gate may be asked about any of them — and
+ * deletes the document in the same commit.
+ *
+ * ⛔ Not the erasure path, which removes the person everywhere and closes the
+ * door with suppression rows before it deletes anything.
+ */ export async function removeContactKeepingRefusals(input) {
+    const { contactRef, nowMs } = input;
+    const orgRef = contactRef.parent.parent;
+    if (!orgRef) throw new Error('[retained-refusals] a contact lives under an organization');
+    return contactRef.firestore.runTransaction(async (transaction)=>{
+        var _snapshot_data;
+        const snapshot = await transaction.get(contactRef);
+        if (!snapshot.exists) return {
+            outcome: 'missing'
+        };
+        const contact = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+        const decided = input.decide(contact);
+        if ('refused' in decided) return {
+            outcome: 'refused',
+            error: decided.refused
+        };
+        if (decided.action === 'delete') {
+            const retained = await retainRefusals({
+                orgRef,
+                email: contactEmails(contact),
+                contactId: contactRef.id,
+                retained: decided.retained,
+                nowMs,
+                transaction
+            });
+            transaction.delete(contactRef);
+            return {
+                outcome: 'deleted',
+                retained
+            };
+        }
+        transaction.update(contactRef, _extends({}, Object.fromEntries(decided.remove.map((path)=>[
+                path,
+                FieldValue.delete()
+            ])), {
+            visibleTo: FieldValue.arrayRemove(...decided.removeTokens),
+            capturedByHostIds: FieldValue.arrayRemove(...decided.removeHostIds),
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        return {
+            outcome: 'detached'
+        };
+    });
+}
+/**
+ * The retained documents for these addresses, keyed by the normalized
+ * address; an address with nothing retained is absent.
+ *
+ * Throws when a read fails, and deliberately: every caller decides whether
+ * an operator may enroll somebody, and a read that could not see a refusal
+ * has to reach the caller's failed-read branch rather than read as none.
+ */ export async function readRetainedRefusals(anchor, emails) {
+    const found = new Map();
+    const byKey = new Map();
+    for (const raw of emails){
+        const email = normalizeContactEmail(raw);
+        const key = email ? personKey(email) : null;
+        if (email && key) byKey.set(key, email);
+    }
+    if (!byKey.size) return found;
+    const orgRef = orgOf(anchor);
+    const store = orgRef.collection(RETAINED_REFUSALS_COLLECTION);
+    const keys = [
+        ...byKey.keys()
+    ];
+    for(let at = 0; at < keys.length; at += RETAINED_REFUSALS_READ_CHUNK){
+        const chunk = keys.slice(at, at + RETAINED_REFUSALS_READ_CHUNK);
+        const snapshots = await orgRef.firestore.getAll(...chunk.map((key)=>store.doc(key)));
+        for (const snapshot of snapshots){
+            var _snapshot_data;
+            const email = byKey.get(snapshot.id);
+            if (email && snapshot.exists) found.set(email, (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {});
+        }
+    }
+    return found;
+}
+function readCursor(raw) {
+    if (!raw) return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof (parsed == null ? void 0 : parsed.id) === 'string' ? parsed : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/** The error codes that mean "somebody wrote this document since I read it". */ const RACED = new Set([
+    5,
+    9
+]);
+const codeOf = (error)=>error == null ? void 0 : error.code;
+/**
+ * One page of the carry `to ← from` over the store: every retained refusal
+ * `from` holds is given to `to` where `to` has no entry, with where it came
+ * from and which change carried it. See `retainedRefusalCarry`.
+ *
+ * The full pass reads only the documents refusing `from`, by id. The
+ * catch-up reads everything written since `sinceMs`, by `updatedAt` then id,
+ * and decides each document in hand: an equality on a site's entry beside a
+ * range on `updatedAt` would need a composite index per site, which no
+ * index file can declare.
+ *
+ * Idempotent, like every carry: a write only fills an entry `to` lacks, so
+ * a page re-run after a crash, the catch-up and the sweep write nothing that
+ * was already carried. A write that raced another writer is decided again
+ * once from a fresh read; failing twice throws, and the executor retries the
+ * page from its cursor.
+ */ export async function carryRetainedRefusals(options) {
+    var _options_pageSize, _options_sinceMs;
+    const { firestore, carry, changeId } = options;
+    const store = firestore.collection('orgs').doc(options.orgId).collection(RETAINED_REFUSALS_COLLECTION);
+    const limit = (_options_pageSize = options.pageSize) != null ? _options_pageSize : RETAINED_REFUSALS_CARRY_PAGE;
+    const cursor = readCursor(options.cursor);
+    const since = (_options_sinceMs = options.sinceMs) != null ? _options_sinceMs : null;
+    let query;
+    if (since !== null) {
+        query = store.where('updatedAt', '>=', Timestamp.fromMillis(since)).orderBy('updatedAt').orderBy(FieldPath.documentId());
+        if (cursor == null ? void 0 : cursor.at) query = query.startAfter(new Timestamp(cursor.at.seconds, cursor.at.nanoseconds), cursor.id);
+    } else {
+        query = store.where(`${MARKETING_CONSENT_BY_HOST_FIELD}.${carry.fromHostId}.${MARKETING_CONSENT_FIELD}`, '==', false).orderBy(FieldPath.documentId());
+        if (cursor) query = query.startAfter(cursor.id);
+    }
+    const page = await query.limit(limit).get();
+    if (page.empty) return {
+        done: true,
+        cursor: null,
+        read: 0,
+        written: 0
+    };
+    const decide = (snapshot)=>{
+        const patch = snapshot.exists ? retainedRefusalCarry(snapshot.data(), carry, changeId) : null;
+        return patch ? {
+            snapshot,
+            patch
+        } : null;
+    };
+    const due = page.docs.map(decide).filter((entry)=>entry !== null);
+    const written = options.dryRun ? due.length : await writeCarried(firestore, carry, due, decide);
+    const last = page.docs[page.docs.length - 1];
+    const next = {
+        id: last.id
+    };
+    if (since !== null) {
+        const value = last.get('updatedAt');
+        if (value instanceof Timestamp) next.at = {
+            seconds: value.seconds,
+            nanoseconds: value.nanoseconds
+        };
+    }
+    const done = page.size < limit;
+    return {
+        done,
+        cursor: done ? null : JSON.stringify(next),
+        read: page.size,
+        written
+    };
+}
+/**
+ * Writes one page's patches through a `BulkWriter`, each guarded by the read
+ * it was decided from, and decides the ones that raced once more.
+ */ async function writeCarried(firestore, carry, due, decide) {
+    let written = 0;
+    for(let round = 0; round < 2 && due.length; round += 1){
+        const writer = firestore.bulkWriter();
+        const outcomes = due.map(({ snapshot, patch })=>writer.update(snapshot.ref, _extends({}, patch, {
+                updatedAt: FieldValue.serverTimestamp()
+            }), {
+                lastUpdateTime: snapshot.updateTime
+            }).then(()=>({
+                    snapshot,
+                    error: null
+                }), (error)=>({
+                    snapshot,
+                    error: error != null ? error : new Error('The write failed')
+                })));
+        await writer.close();
+        const raced = [];
+        for (const { snapshot, error } of (await Promise.all(outcomes))){
+            if (error === null) {
+                written += 1;
+                continue;
+            }
+            const code = codeOf(error);
+            if (code === undefined || !RACED.has(code)) throw error;
+            raced.push(snapshot);
+        }
+        if (!raced.length) return written;
+        const fresh = await firestore.getAll(...raced.map((snapshot)=>snapshot.ref));
+        due = fresh.map(decide).filter((entry)=>entry !== null);
+    }
+    if (due.length) {
+        throw new Error(`[retained-refusals] ${due.length} document(s) kept changing under the carry to ${carry.toHostId}`);
+    }
+    return written;
+}
+
+//# sourceMappingURL=retained-refusals.js.map

package/src/lib/server/retained-refusals.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/retained-refusals.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 RETAINED-REFUSAL STORE, ON THE ADMIN SDK (AGL-3338):\n * `orgs/{orgId}/retainedRefusals/{personKey}`.\n *\n * What the store is for, and why it holds what it holds, is the pure\n * module's note (`@aglyn/aglyn/app-utils/retained-refusals`). This is its\n * server doors:\n *\n *  - {@link removeContactKeepingRefusals} — the one way a contact is let go\n *    of outside an erasure: the CRM's delete and `DELETE /v1/contacts/{id}`.\n *    It decides against the document read in its own transaction, so a\n *    refusal written a moment before the delete is still the one kept;\n *  - {@link retainRefusals} — the write a record's delete makes, inside the\n *    delete's own transaction when it has one, so a record is never gone\n *    with its refusals unkept;\n *  - {@link readRetainedRefusals} — the read the list gate and the Inbox's\n *    add-to-list make beside the records, which THROWS on a failed read: a\n *    reader that cannot see whether somebody refused must not read them as\n *    somebody who did not;\n *  - {@link carryRetainedRefusals} — one page of a consent group change's\n *    carry over the store, the org-level twin of the per-site carries in\n *    `consent-group-carry.ts`.\n *\n * Anchored on the organization document, or on any collection under it —\n * the caller already holds the records it is reading or deleting, and the\n * store is their sibling.\n */\n\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport {\n  MARKETING_CONSENT_BY_HOST_FIELD,\n  MARKETING_CONSENT_FIELD,\n} from '@aglyn/aglyn/app-utils/marketing-consent'\nimport {\n  RETAINED_AT_FIELD,\n  RETAINED_REFUSALS_COLLECTION,\n  type RetainedRefusals,\n  refusalsOf,\n  retainedEntries,\n  retainedRefusalCarry,\n} from '@aglyn/aglyn/app-utils/retained-refusals'\nimport {\n  type ContactDetach,\n  contactEmails,\n  normalizeContactEmail,\n} from '@aglyn/aglyn/app-utils/contacts'\nimport type { ConsentGroupCarry } from '@aglyn/aglyn/app-utils/consent-group-change'\nimport { FieldPath, FieldValue, Timestamp } from 'firebase-admin/firestore'\nimport type { ConsentGroupCarryPage } from './consent-group-carry'\n\ntype Doc = Record<string, unknown>\n\n/** The organization document, or a collection directly under it. */\nexport type RetainedRefusalsAnchor =\n  | FirebaseFirestore.DocumentReference\n  | FirebaseFirestore.CollectionReference\n\n/** Keys one `getAll` of the store reads. */\nexport const RETAINED_REFUSALS_READ_CHUNK = 100\n\n/** Documents one page of the carry reads. */\nexport const RETAINED_REFUSALS_CARRY_PAGE = 300\n\n/** The organization document `anchor` is, or is directly under. */\nfunction orgOf(anchor: RetainedRefusalsAnchor): FirebaseFirestore.DocumentReference {\n  const orgRef =\n    typeof (anchor as FirebaseFirestore.DocumentReference).collection === 'function'\n      ? (anchor as FirebaseFirestore.DocumentReference)\n      : (anchor as FirebaseFirestore.CollectionReference).parent\n  if (!orgRef) throw new Error('[retained-refusals] a root collection has no organization')\n  return orgRef\n}\n\n/** The store under the organization `anchor` is, or is directly under. */\nexport function retainedRefusalsStore(anchor: RetainedRefusalsAnchor): FirebaseFirestore.CollectionReference {\n  return orgOf(anchor).collection(RETAINED_REFUSALS_COLLECTION)\n}\n\nexport interface RetainRefusalsInput {\n  /** The organization document — or `contactsRef`, the collection the record was in. */\n  orgRef?: FirebaseFirestore.DocumentReference\n  contactsRef?: FirebaseFirestore.CollectionReference\n  /**\n   * The address the person is known by — or every one, when a merge left the\n   * record answering to more than one: each is kept under its own key.\n   */\n  email: string | readonly string[]\n  /** The record the refusals come from, stamped on each entry. */\n  contactId: string\n  /** What `planContactDetach`'s delete (or `refusalsOf`) named. */\n  retained: RetainedRefusals | null | undefined\n  nowMs: number\n  /** The delete's transaction, so the retention and the delete land together. */\n  transaction?: FirebaseFirestore.Transaction\n}\n\n/**\n * Keeps a record's refusals in the store, one document per address, and\n * answers how many documents it wrote.\n *\n * Each site's entry is written under its own field path, replacing that\n * site's entry and leaving every other site retained earlier as it was; the\n * unscoped refusal is written only when there is one, so it is never\n * cleared by a later record that had none. Nothing is written when there is\n * nothing to keep.\n *\n * Inside a transaction the writes join it, and the caller must have done its\n * reads first, as a transaction requires. Outside one they are a batch.\n */\nexport async function retainRefusals(input: RetainRefusalsInput): Promise<number> {\n  const { retained } = input\n  const hostIds = Object.keys(retained?.byHost ?? {})\n  if (!retained || (!hostIds.length && !retained.unscoped)) return 0\n  const anchor = input.orgRef ?? input.contactsRef\n  if (!anchor) throw new Error('[retained-refusals] name the organization or its contacts')\n  const orgRef = orgOf(anchor)\n  const store = orgRef.collection(RETAINED_REFUSALS_COLLECTION)\n  const emails = typeof input.email === 'string' ? [input.email] : input.email\n  const keys = [\n    ...new Set(emails.map((email) => personKey(email)).filter((key): key is string => Boolean(key))),\n  ]\n  if (!keys.length) return 0\n\n  const data: Doc = {\n    [MARKETING_CONSENT_BY_HOST_FIELD]: retainedEntries(retained, input.contactId, input.nowMs),\n    [RETAINED_AT_FIELD]: input.nowMs,\n    updatedAt: FieldValue.serverTimestamp(),\n  }\n  const fields: Array<string | FirebaseFirestore.FieldPath> = [\n    ...hostIds.map((hostId) => new FieldPath(MARKETING_CONSENT_BY_HOST_FIELD, hostId)),\n    RETAINED_AT_FIELD,\n    'updatedAt',\n  ]\n  if (retained.unscoped) {\n    data[MARKETING_CONSENT_FIELD] = false\n    fields.push(MARKETING_CONSENT_FIELD)\n  }\n\n  if (input.transaction) {\n    for (const key of keys) input.transaction.set(store.doc(key), data, { mergeFields: fields })\n    return keys.length\n  }\n  const batch = orgRef.firestore.batch()\n  for (const key of keys) batch.set(store.doc(key), data, { mergeFields: fields })\n  await batch.commit()\n  return keys.length\n}\n\n/** What {@link removeContactKeepingRefusals} did to one contact. */\nexport type ContactRemoval =\n  | { outcome: 'missing' }\n  | { outcome: 'refused'; error: string }\n  | { outcome: 'detached' }\n  | {\n      outcome: 'deleted'\n      /** Retained documents written, one per address the contact answered to. */\n      retained: number\n    }\n\nexport interface RemoveContactInput {\n  contactRef: FirebaseFirestore.DocumentReference\n  /**\n   * What letting go of this contact means, decided against the document as\n   * the transaction read it: `planContactDetach` for a holder letting go,\n   * {@link deleteWholeContact} for a delete regardless of holders, or a\n   * sentence refusing it.\n   */\n  decide: (contact: Doc) => ContactDetach | { refused: string }\n  nowMs: number\n}\n\n/** The decision `DELETE /v1/contacts/{id}` makes: the document goes, every refusal on it kept. */\nexport const deleteWholeContact = (contact: Doc): ContactDetach => ({\n  action: 'delete',\n  retained: refusalsOf(contact),\n})\n\n/**\n * Lets go of one contact in one transaction, keeping every refusal it holds.\n *\n * A DETACH drops the leaving holder's facet, its consent GRANTS, its scope\n * tokens and its capture attribution; a refusal entry is not among the\n * removals `planContactDetach` names, so it stays for the holders that\n * remain. A DELETE copies every refusal on the document into the store under\n * each address the contact answers to — the primary and every one a merge\n * folded in, since the list gate may be asked about any of them — and\n * deletes the document in the same commit.\n *\n * ⛔ Not the erasure path, which removes the person everywhere and closes the\n * door with suppression rows before it deletes anything.\n */\nexport async function removeContactKeepingRefusals(\n  input: RemoveContactInput,\n): Promise<ContactRemoval> {\n  const { contactRef, nowMs } = input\n  const orgRef = contactRef.parent.parent\n  if (!orgRef) throw new Error('[retained-refusals] a contact lives under an organization')\n  return contactRef.firestore.runTransaction(async (transaction) => {\n    const snapshot = await transaction.get(contactRef)\n    if (!snapshot.exists) return { outcome: 'missing' } as const\n    const contact = (snapshot.data() ?? {}) as Doc\n    const decided = input.decide(contact)\n    if ('refused' in decided) return { outcome: 'refused', error: decided.refused } as const\n    if (decided.action === 'delete') {\n      const retained = await retainRefusals({\n        orgRef,\n        email: contactEmails(contact),\n        contactId: contactRef.id,\n        retained: decided.retained,\n        nowMs,\n        transaction,\n      })\n      transaction.delete(contactRef)\n      return { outcome: 'deleted', retained } as const\n    }\n    transaction.update(contactRef, {\n      ...Object.fromEntries(decided.remove.map((path) => [path, FieldValue.delete()])),\n      visibleTo: FieldValue.arrayRemove(...decided.removeTokens),\n      capturedByHostIds: FieldValue.arrayRemove(...decided.removeHostIds),\n      updatedAt: FieldValue.serverTimestamp(),\n    })\n    return { outcome: 'detached' } as const\n  })\n}\n\n/**\n * The retained documents for these addresses, keyed by the normalized\n * address; an address with nothing retained is absent.\n *\n * Throws when a read fails, and deliberately: every caller decides whether\n * an operator may enroll somebody, and a read that could not see a refusal\n * has to reach the caller's failed-read branch rather than read as none.\n */\nexport async function readRetainedRefusals(\n  anchor: RetainedRefusalsAnchor,\n  emails: readonly string[],\n): Promise<Map<string, Doc>> {\n  const found = new Map<string, Doc>()\n  const byKey = new Map<string, string>()\n  for (const raw of emails) {\n    const email = normalizeContactEmail(raw)\n    const key = email ? personKey(email) : null\n    if (email && key) byKey.set(key, email)\n  }\n  if (!byKey.size) return found\n  const orgRef = orgOf(anchor)\n  const store = orgRef.collection(RETAINED_REFUSALS_COLLECTION)\n  const keys = [...byKey.keys()]\n  for (let at = 0; at < keys.length; at += RETAINED_REFUSALS_READ_CHUNK) {\n    const chunk = keys.slice(at, at + RETAINED_REFUSALS_READ_CHUNK)\n    const snapshots = await orgRef.firestore.getAll(...chunk.map((key) => store.doc(key)))\n    for (const snapshot of snapshots) {\n      const email = byKey.get(snapshot.id)\n      if (email && snapshot.exists) found.set(email, (snapshot.data() ?? {}) as Doc)\n    }\n  }\n  return found\n}\n\nexport interface CarryRetainedRefusalsOptions {\n  firestore: FirebaseFirestore.Firestore\n  orgId: string\n  carry: ConsentGroupCarry\n  changeId: string\n  cursor: string | null\n  /** Only documents written at or after this instant — the catch-up. */\n  sinceMs?: number | null\n  pageSize?: number\n  dryRun?: boolean\n}\n\ninterface Cursor {\n  id: string\n  /** `updatedAt` on the last document a catch-up read. */\n  at?: { seconds: number; nanoseconds: number }\n}\n\nfunction readCursor(raw: string | null): Cursor | null {\n  if (!raw) return null\n  try {\n    const parsed = JSON.parse(raw) as Cursor\n    return typeof parsed?.id === 'string' ? parsed : null\n  } catch {\n    return null\n  }\n}\n\n/** The error codes that mean \"somebody wrote this document since I read it\". */\nconst RACED = new Set([5, 9])\nconst codeOf = (error: unknown): number | undefined => (error as { code?: number } | null)?.code\n\n/**\n * One page of the carry `to ← from` over the store: every retained refusal\n * `from` holds is given to `to` where `to` has no entry, with where it came\n * from and which change carried it. See `retainedRefusalCarry`.\n *\n * The full pass reads only the documents refusing `from`, by id. The\n * catch-up reads everything written since `sinceMs`, by `updatedAt` then id,\n * and decides each document in hand: an equality on a site's entry beside a\n * range on `updatedAt` would need a composite index per site, which no\n * index file can declare.\n *\n * Idempotent, like every carry: a write only fills an entry `to` lacks, so\n * a page re-run after a crash, the catch-up and the sweep write nothing that\n * was already carried. A write that raced another writer is decided again\n * once from a fresh read; failing twice throws, and the executor retries the\n * page from its cursor.\n */\nexport async function carryRetainedRefusals(\n  options: CarryRetainedRefusalsOptions,\n): Promise<ConsentGroupCarryPage> {\n  const { firestore, carry, changeId } = options\n  const store = firestore.collection('orgs').doc(options.orgId).collection(RETAINED_REFUSALS_COLLECTION)\n  const limit = options.pageSize ?? RETAINED_REFUSALS_CARRY_PAGE\n  const cursor = readCursor(options.cursor)\n  const since = options.sinceMs ?? null\n\n  let query: FirebaseFirestore.Query\n  if (since !== null) {\n    query = store\n      .where('updatedAt', '>=', Timestamp.fromMillis(since))\n      .orderBy('updatedAt')\n      .orderBy(FieldPath.documentId())\n    if (cursor?.at) query = query.startAfter(new Timestamp(cursor.at.seconds, cursor.at.nanoseconds), cursor.id)\n  } else {\n    query = store\n      .where(`${MARKETING_CONSENT_BY_HOST_FIELD}.${carry.fromHostId}.${MARKETING_CONSENT_FIELD}`, '==', false)\n      .orderBy(FieldPath.documentId())\n    if (cursor) query = query.startAfter(cursor.id)\n  }\n  const page = await query.limit(limit).get()\n  if (page.empty) return { done: true, cursor: null, read: 0, written: 0 }\n\n  const decide = (snapshot: FirebaseFirestore.DocumentSnapshot) => {\n    const patch = snapshot.exists ? retainedRefusalCarry(snapshot.data(), carry, changeId) : null\n    return patch ? { snapshot, patch } : null\n  }\n  const due = page.docs.map(decide).filter((entry): entry is NonNullable<typeof entry> => entry !== null)\n  const written = options.dryRun ? due.length : await writeCarried(firestore, carry, due, decide)\n\n  const last = page.docs[page.docs.length - 1]\n  const next: Cursor = { id: last.id }\n  if (since !== null) {\n    const value = last.get('updatedAt')\n    if (value instanceof Timestamp) next.at = { seconds: value.seconds, nanoseconds: value.nanoseconds }\n  }\n  const done = page.size < limit\n  return { done, cursor: done ? null : JSON.stringify(next), read: page.size, written }\n}\n\ntype Carried = { snapshot: FirebaseFirestore.DocumentSnapshot; patch: Doc }\n\n/**\n * Writes one page's patches through a `BulkWriter`, each guarded by the read\n * it was decided from, and decides the ones that raced once more.\n */\nasync function writeCarried(\n  firestore: FirebaseFirestore.Firestore,\n  carry: ConsentGroupCarry,\n  due: Carried[],\n  decide: (snapshot: FirebaseFirestore.DocumentSnapshot) => Carried | null,\n): Promise<number> {\n  let written = 0\n  for (let round = 0; round < 2 && due.length; round += 1) {\n    const writer = firestore.bulkWriter()\n    const outcomes = due.map(({ snapshot, patch }) =>\n      writer\n        .update(\n          snapshot.ref,\n          { ...patch, updatedAt: FieldValue.serverTimestamp() },\n          { lastUpdateTime: snapshot.updateTime as FirebaseFirestore.Timestamp },\n        )\n        .then(\n          () => ({ snapshot, error: null as unknown }),\n          (error: unknown) => ({ snapshot, error: error ?? new Error('The write failed') }),\n        ),\n    )\n    await writer.close()\n    const raced: FirebaseFirestore.DocumentSnapshot[] = []\n    for (const { snapshot, error } of await Promise.all(outcomes)) {\n      if (error === null) {\n        written += 1\n        continue\n      }\n      const code = codeOf(error)\n      if (code === undefined || !RACED.has(code)) throw error\n      raced.push(snapshot)\n    }\n    if (!raced.length) return written\n    const fresh = await firestore.getAll(...raced.map((snapshot) => snapshot.ref))\n    due = fresh.map(decide).filter((entry): entry is Carried => entry !== null)\n  }\n  if (due.length) {\n    throw new Error(\n      `[retained-refusals] ${due.length} document(s) kept changing under the carry to ${carry.toHostId}`,\n    )\n  }\n  return written\n}\n"],"names":["personKey","MARKETING_CONSENT_BY_HOST_FIELD","MARKETING_CONSENT_FIELD","RETAINED_AT_FIELD","RETAINED_REFUSALS_COLLECTION","refusalsOf","retainedEntries","retainedRefusalCarry","contactEmails","normalizeContactEmail","FieldPath","FieldValue","Timestamp","RETAINED_REFUSALS_READ_CHUNK","RETAINED_REFUSALS_CARRY_PAGE","orgOf","anchor","orgRef","collection","parent","Error","retainedRefusalsStore","retainRefusals","input","retained","hostIds","Object","keys","byHost","length","unscoped","contactsRef","store","emails","email","Set","map","filter","key","Boolean","data","contactId","nowMs","updatedAt","serverTimestamp","fields","hostId","push","transaction","set","doc","mergeFields","batch","firestore","commit","deleteWholeContact","contact","action","removeContactKeepingRefusals","contactRef","runTransaction","snapshot","get","exists","outcome","decided","decide","error","refused","id","delete","update","fromEntries","remove","path","visibleTo","arrayRemove","removeTokens","capturedByHostIds","removeHostIds","readRetainedRefusals","found","Map","byKey","raw","size","at","chunk","slice","snapshots","getAll","readCursor","parsed","JSON","parse","RACED","codeOf","code","carryRetainedRefusals","options","carry","changeId","orgId","limit","pageSize","cursor","since","sinceMs","query","where","fromMillis","orderBy","documentId","startAfter","seconds","nanoseconds","fromHostId","page","empty","done","read","written","patch","due","docs","entry","dryRun","writeCarried","last","next","value","stringify","round","writer","bulkWriter","outcomes","ref","lastUpdateTime","updateTime","then","close","raced","Promise","all","undefined","has","fresh","toHostId"],"mappings":"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"}

package/src/lib/server/risk-notice.d.ts

@@ -14,7 +14,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type ResolvedRiskAction, type RiskEventKind } from '@aglyn/shared-util-email/risk-notice-catalog';
+import { type ResolvedRiskAction, type RiskEventKind, type RiskNoticeSeverity } from '@aglyn/shared-util-email/risk-notice-catalog';
+import type { NotificationLevel } from '@aglyn/aglyn/server';
 import { type SendEmailOptions, type SendEmailResult } from '@aglyn/shared-util-email';
 import { type HeldPageSubject, type HeldPageTarget, type PageHoldNoticeKind } from '@aglyn/shared-util-email/held-page';
 import { type NotificationPayload, type NotifyUsersOptions } from './notifications';
@@ -25,6 +26,11 @@ export declare const RISK_NOTICE_COLLECTION = "riskNotices";
 export declare const RISK_NOTICE_LEDGER_COLLECTION = "riskNoticeLedger";
 /** The in-app notification type every owner notice is written as. */
 export declare const RISK_NOTICE_NOTIFICATION_TYPE: "system.riskNotice";
+/**
+ * The level an owner notice is drawn at (AGL-3437), from its kind's
+ * severity: a release or a lift is `info`, not the red of the hold it ends.
+ */
+export declare const RISK_NOTICE_LEVELS: Record<RiskNoticeSeverity, NotificationLevel>;
 /**
  * The burst allowance: how many notices one workspace's owners, and staff
  * about one workspace, receive one by one in {@link RISK_NOTICE_BURST.windowMs}
@@ -66,7 +72,20 @@ export interface RiskEventInput {
     occurredAtMs?: number;
     /** `$56.00 USD`. */
     amount?: string | null;
+    /**
+     * What happened to the payment, finishing "the payment was …"
+     * (`RISK_PAYMENT_EVENTS`): a fraud report, a review, a dispute.
+     */
+    paymentEvent?: string | null;
     evidenceDueByMs?: number | null;
+    /**
+     * A new publisher's payout schedule: how many days each payout waits, and
+     * the workspace age it waits until.
+     */
+    payout?: {
+        delayDays: number;
+        untilWorkspaceAgeDays: number;
+    } | null;
     /** Staff only: the Stripe Dashboard page for the charge, review or dispute. */
     stripeUrl?: string | null;
     lock?: {
@@ -87,6 +106,11 @@ export interface RiskEventInput {
     staffEvidence?: string | null;
     /** Overrides the default dedupe key. */
     dedupeKey?: string | null;
+    /**
+     * A closing notice's opening kind. The closing goes to the people the
+     * opening went to: the site's managers too, when the opening told them.
+     */
+    openedAs?: RiskEventKind | null;
     /**
      * `false` to send no owner EMAIL for this event (a lock placed under a
      * legal hold). The in-app notice and the record are still written.
@@ -178,6 +202,13 @@ export interface RenderedRiskNoticeEmail {
  * platform does (holds, locks, lifts, cancellations, reviews).
  */
 export declare function riskNoticeEmailBrand(kind: RiskEventKind | null, orgId: string | null): Promise<SystemEmailBrand>;
+/**
+ * The product name a notice's own words use (`your Aglyn account`): the one
+ * the email it rides in is branded with, so the sentence and the header
+ * never disagree — the platform's for platform mail, a white-label
+ * workspace's own for the notices sent in its brand.
+ */
+export declare function riskNoticeProductName(brand: SystemEmailBrand): string;
 /**
  * Renders one notice email through the System emails seam (AGL-3367): the
  * published design for the kind's own `risk-…` key, or its built-in copy,