@aglyn/tenant-data-admin 1.0.0-beta.143

package/src/lib/server/contact-merge.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @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 { HostActivityActor } from '@aglyn/aglyn/app-utils/activity-presenter';
+export interface MergeContactsOptions {
+    firestore: FirebaseFirestore.Firestore;
+    /** `orgs/{orgId}` — the org whose contacts both records are. */
+    orgRef: FirebaseFirestore.DocumentReference;
+    /** The record that stays, and keeps its address as the identity. */
+    survivorId: string;
+    /** The record folded in and deleted. */
+    mergedId: string;
+    actor: HostActivityActor;
+    /**
+     * The site whose console did the work: where the activity feed entry
+     * lands, and the site a timeline note is filed under. `null` for a door
+     * with no site — the REST API — which logs no host entry.
+     */
+    hostId: string | null;
+    /** The actor's display name for the timeline note, when the door knows it. */
+    actorName?: string | null;
+}
+export interface MergeContactsRepointed {
+    deals: number;
+    tasks: number;
+    activities: number;
+    leads: number;
+}
+export type MergeContactsResult = {
+    ok: true;
+    survivorId: string;
+    survivorEmail: string;
+    mergedId: string;
+    mergedEmail: string;
+    /** Every address the survivor answers to now, primary first. */
+    emails: string[];
+    repointed: MergeContactsRepointed;
+} | {
+    ok: false;
+    reason: 'same-record' | 'survivor-missing' | 'merged-missing';
+};
+export declare function mergeContacts(options: MergeContactsOptions): Promise<MergeContactsResult>;

package/src/lib/server/contact-merge.js

@@ -0,0 +1,279 @@
+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.
+ */ /**
+ * MERGING TWO CONTACTS — the write (AGL-2625).
+ *
+ * `planContactMerge` says what the survivor becomes; this performs it, and
+ * moves everything that pointed at the merged record. One function behind
+ * two doors — the console's `crm/contacts-merge` route and
+ * `POST /v1/contacts/{id}/merge` — so the REST caller and the record page
+ * cannot merge two different ways.
+ *
+ * ## The order is the crash-safety argument
+ *
+ *  1. Every deal, task and activity naming the merged contact is repointed
+ *     at the survivor, and every lead converted into it. Batched, bounded,
+ *     idempotent: a re-run finds nothing left to move.
+ *  2. Then, in ONE transaction: the survivor takes the plan, every address
+ *     it now answers to is indexed at it, and the merged document is
+ *     deleted — with both records re-read inside the transaction, so two
+ *     merges racing on one pair cannot both succeed and a plan is never
+ *     computed on a document that changed under it.
+ *
+ * Children first because a process that dies between the two steps leaves
+ * children pointing at a record that EXISTS — the survivor — while the merged
+ * document is still there for a retry to fold in. The other order would
+ * leave deals pointing at a deleted contact, which is a record nobody can
+ * open from anywhere.
+ *
+ * ## What it does not move
+ *
+ * List memberships, suppression entries and the delivery log are keyed by
+ * ADDRESS, not by contact id, and stay under the merged address; a capture
+ * on that address resolves to the survivor through the index, which is the
+ * fact those keys need. A company's contacts count drops only for a company
+ * both records named — the survivor still names the rest.
+ */ import { CONTACT_EMAIL_INDEX_COLLECTION, contactEmails } from "@aglyn/aglyn/app-utils/contacts";
+import { planContactMerge } from "@aglyn/aglyn/app-utils/contact-merge";
+import { CRM_COLLECTIONS } from "@aglyn/aglyn/app-utils/crm";
+import { personKey } from "@aglyn/aglyn/app-utils/person-key";
+import { FieldValue } from "firebase-admin/firestore";
+import { settleCompanyContactsCounts } from "./contact-company-link.js";
+import { recomputeCrmNextTaskAt } from "./crm-next-activity.js";
+import { logHostActivity } from "./organizations.js";
+/** How many pointing rows one repoint pass reads — and one batch writes. */ const REPOINT_PAGE = 400;
+/** A ceiling on passes, so a query that keeps answering cannot loop forever. */ const REPOINT_PASSES = 25;
+/**
+ * Point every row of `collection` whose `contactId` is `from` at `to`.
+ *
+ * Page, batch, repeat: each pass reads the rows still pointing at the
+ * merged record — the ones a previous pass moved no longer match — so the
+ * loop ends when a pass finds nothing. `updatedAt` moves with the pointer
+ * because an integration syncing by `updatedAfter` has to see the change.
+ */ async function repointContactId(firestore, collection, from, to) {
+    let moved = 0;
+    for(let pass = 0; pass < REPOINT_PASSES; pass += 1){
+        const page = await collection.where('contactId', '==', from).limit(REPOINT_PAGE).get();
+        if (page.empty) break;
+        const batch = firestore.batch();
+        for (const row of page.docs){
+            batch.update(row.ref, {
+                contactId: to,
+                updatedAt: FieldValue.serverTimestamp()
+            });
+        }
+        await batch.commit();
+        moved += page.size;
+        if (page.size < REPOINT_PAGE) break;
+    }
+    return moved;
+}
+/**
+ * The leads converted into the merged contact, restamped at the survivor.
+ *
+ * A lead lives at `hosts/{hostId}/leads/{personKey(email)}`, so there is no
+ * query: each site that met either record is asked for a lead under each of
+ * the merged record's addresses, and one that names the merged contact is
+ * moved. Bounded by sites times addresses, both small.
+ */ async function repointLeads(firestore, hostIds, emails, from, to) {
+    let moved = 0;
+    for (const hostId of hostIds){
+        for (const email of emails){
+            const key = personKey(email);
+            if (!key) continue;
+            const leadRef = firestore.collection('hosts').doc(hostId).collection('leads').doc(key);
+            const lead = await leadRef.get();
+            if (!lead.exists || lead.get('convertedContactId') !== from) continue;
+            await leadRef.update({
+                convertedContactId: to,
+                updatedAt: FieldValue.serverTimestamp()
+            });
+            moved += 1;
+        }
+    }
+    return moved;
+}
+function strings(value) {
+    return Array.isArray(value) ? value.filter((item)=>typeof item === 'string' && item !== '') : [];
+}
+export async function mergeContacts(options) {
+    var _mergedBefore_data, _survivorBefore_data, _contactEmails_, _plan_emails_;
+    const { firestore, orgRef, survivorId, mergedId, actor, hostId } = options;
+    if (!survivorId || !mergedId || survivorId === mergedId) {
+        return {
+            ok: false,
+            reason: 'same-record'
+        };
+    }
+    const contactsRef = orgRef.collection('contacts');
+    const survivorRef = contactsRef.doc(survivorId);
+    const mergedRef = contactsRef.doc(mergedId);
+    const [survivorBefore, mergedBefore] = await Promise.all([
+        survivorRef.get(),
+        mergedRef.get()
+    ]);
+    if (!survivorBefore.exists) return {
+        ok: false,
+        reason: 'survivor-missing'
+    };
+    if (!mergedBefore.exists) return {
+        ok: false,
+        reason: 'merged-missing'
+    };
+    const mergedData = (_mergedBefore_data = mergedBefore.data()) != null ? _mergedBefore_data : {};
+    const survivorData = (_survivorBefore_data = survivorBefore.data()) != null ? _survivorBefore_data : {};
+    /*==========================================
+   * 1. THE CHILDREN — before the parent, for the reason the header gives.
+   *=========================================*/ const [deals, tasks, activities] = await Promise.all([
+        repointContactId(firestore, orgRef.collection(CRM_COLLECTIONS.deals), mergedId, survivorId),
+        repointContactId(firestore, orgRef.collection(CRM_COLLECTIONS.tasks), mergedId, survivorId),
+        repointContactId(firestore, orgRef.collection(CRM_COLLECTIONS.activities), mergedId, survivorId)
+    ]);
+    const leadHosts = [
+        ...new Set([
+            ...strings(mergedData['capturedByHostIds']),
+            ...strings(survivorData['capturedByHostIds']),
+            ...strings([
+                mergedData['hostId'],
+                survivorData['hostId'],
+                hostId
+            ])
+        ])
+    ];
+    const leads = await repointLeads(firestore, leadHosts, contactEmails(mergedData), mergedId, survivorId);
+    /*==========================================
+   * 2. THE SWAP — one transaction over both documents and the index.
+   *=========================================*/ const index = orgRef.collection(CONTACT_EMAIL_INDEX_COLLECTION);
+    const swapped = await firestore.runTransaction(async (transaction)=>{
+        var _survivor_data, _merged_data, _survivor_data1;
+        const [survivor, merged] = await Promise.all([
+            transaction.get(survivorRef),
+            transaction.get(mergedRef)
+        ]);
+        if (!survivor.exists) return {
+            reason: 'survivor-missing'
+        };
+        if (!merged.exists) return {
+            reason: 'merged-missing'
+        };
+        const plan = planContactMerge((_survivor_data = survivor.data()) != null ? _survivor_data : {}, (_merged_data = merged.data()) != null ? _merged_data : {});
+        transaction.set(survivorRef, _extends({}, plan.survivor, {
+            updatedAt: FieldValue.serverTimestamp()
+        }), {
+            merge: true
+        });
+        for (const email of plan.emails){
+            const key = personKey(email);
+            if (!key) continue;
+            transaction.set(index.doc(key), {
+                email,
+                contactId: survivorId,
+                updatedAt: FieldValue.serverTimestamp()
+            }, {
+                merge: true
+            });
+        }
+        transaction.delete(mergedRef);
+        return {
+            plan,
+            survivor: (_survivor_data1 = survivor.data()) != null ? _survivor_data1 : {}
+        };
+    });
+    if ('reason' in swapped) return {
+        ok: false,
+        reason: swapped.reason
+    };
+    const { plan } = swapped;
+    /*
+   * The companies both records named counted two people and now count one
+   * (AGL-2613). Settled after the swap the way the capture settles its
+   * counts: a figure that could not move is logged, and the company page's
+   * live aggregate corrects it.
+   */ await settleCompanyContactsCounts(orgRef.collection(CRM_COLLECTIONS.companies), {
+        companyId: null,
+        mirror: null,
+        counts: plan.companyCounts
+    });
+    /*
+   * The survivor now owns the merged record's open tasks too, so its next
+   * activity is the earliest of both (AGL-2661). Settled the same way: a
+   * figure that could not move is logged, and the Fields section's
+   * recompute corrects it.
+   */ await recomputeCrmNextTaskAt(firestore, orgRef.id, [
+        {
+            contactId: survivorId
+        }
+    ]).catch((error)=>{
+        console.error('contact merge next activity could not be recomputed', survivorId, error);
+    });
+    const mergedEmail = (_contactEmails_ = contactEmails(mergedData)[0]) != null ? _contactEmails_ : '';
+    const survivorEmail = (_plan_emails_ = plan.emails[0]) != null ? _plan_emails_ : '';
+    // The canonical name — the one identity every holder shares — for the
+    // feed; the address stands in for a person nobody has named.
+    const survivorName = typeof swapped.survivor['name'] === 'string' ? swapped.survivor['name'] : '';
+    /*
+   * THE TIMELINE NOTE, on the survivor: the merge is an event in this
+   * person's history, and the record page is where a reader looks for one.
+   * Filed under the calling site, or the survivor's first site for a door
+   * with none; its own catch, because a note that could not be written must
+   * not read as a merge that did not happen.
+   */ try {
+        var _survivorData_hostId;
+        await orgRef.collection(CRM_COLLECTIONS.activities).add(_extends({
+            kind: 'note',
+            body: `Merged with ${mergedEmail}`,
+            atMs: Date.now(),
+            byUid: actor.uid
+        }, options.actorName || actor.email ? {
+            byName: options.actorName || actor.email
+        } : {}, {
+            contactId: survivorId,
+            visibleTo: plan.visibleTo,
+            hostId: hostId != null ? hostId : String((_survivorData_hostId = survivorData['hostId']) != null ? _survivorData_hostId : ''),
+            createdByUid: actor.uid,
+            createdAt: FieldValue.serverTimestamp(),
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+    } catch (error) {
+        console.error('[contact-merge] timeline note failed', survivorId, error);
+    }
+    // The audit line (AGL-2622), in the feed of the site whose console did
+    // the work. A door with no site — the API — has no host feed to write.
+    if (hostId) {
+        await logHostActivity(hostId, actor, `Merged with ${mergedEmail}`, {
+            type: 'contact',
+            id: survivorId,
+            name: survivorName || survivorEmail
+        });
+    }
+    return {
+        ok: true,
+        survivorId,
+        survivorEmail,
+        mergedId,
+        mergedEmail,
+        emails: plan.emails,
+        repointed: {
+            deals,
+            tasks,
+            activities,
+            leads
+        }
+    };
+}
+
+//# sourceMappingURL=contact-merge.js.map

package/src/lib/server/contact-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/contact-merge.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 * MERGING TWO CONTACTS — the write (AGL-2625).\n *\n * `planContactMerge` says what the survivor becomes; this performs it, and\n * moves everything that pointed at the merged record. One function behind\n * two doors — the console's `crm/contacts-merge` route and\n * `POST /v1/contacts/{id}/merge` — so the REST caller and the record page\n * cannot merge two different ways.\n *\n * ## The order is the crash-safety argument\n *\n *  1. Every deal, task and activity naming the merged contact is repointed\n *     at the survivor, and every lead converted into it. Batched, bounded,\n *     idempotent: a re-run finds nothing left to move.\n *  2. Then, in ONE transaction: the survivor takes the plan, every address\n *     it now answers to is indexed at it, and the merged document is\n *     deleted — with both records re-read inside the transaction, so two\n *     merges racing on one pair cannot both succeed and a plan is never\n *     computed on a document that changed under it.\n *\n * Children first because a process that dies between the two steps leaves\n * children pointing at a record that EXISTS — the survivor — while the merged\n * document is still there for a retry to fold in. The other order would\n * leave deals pointing at a deleted contact, which is a record nobody can\n * open from anywhere.\n *\n * ## What it does not move\n *\n * List memberships, suppression entries and the delivery log are keyed by\n * ADDRESS, not by contact id, and stay under the merged address; a capture\n * on that address resolves to the survivor through the index, which is the\n * fact those keys need. A company's contacts count drops only for a company\n * both records named — the survivor still names the rest.\n */\n\nimport {\n  CONTACT_EMAIL_INDEX_COLLECTION,\n  contactEmails,\n} from '@aglyn/aglyn/app-utils/contacts'\nimport type { HostActivityActor } from '@aglyn/aglyn/app-utils/activity-presenter'\nimport { planContactMerge } from '@aglyn/aglyn/app-utils/contact-merge'\nimport { CRM_COLLECTIONS } from '@aglyn/aglyn/app-utils/crm'\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { settleCompanyContactsCounts } from './contact-company-link'\nimport { recomputeCrmNextTaskAt } from './crm-next-activity'\nimport { logHostActivity } from './organizations'\n\n/** How many pointing rows one repoint pass reads — and one batch writes. */\nconst REPOINT_PAGE = 400\n/** A ceiling on passes, so a query that keeps answering cannot loop forever. */\nconst REPOINT_PASSES = 25\n\nexport interface MergeContactsOptions {\n  firestore: FirebaseFirestore.Firestore\n  /** `orgs/{orgId}` — the org whose contacts both records are. */\n  orgRef: FirebaseFirestore.DocumentReference\n  /** The record that stays, and keeps its address as the identity. */\n  survivorId: string\n  /** The record folded in and deleted. */\n  mergedId: string\n  actor: HostActivityActor\n  /**\n   * The site whose console did the work: where the activity feed entry\n   * lands, and the site a timeline note is filed under. `null` for a door\n   * with no site — the REST API — which logs no host entry.\n   */\n  hostId: string | null\n  /** The actor's display name for the timeline note, when the door knows it. */\n  actorName?: string | null\n}\n\nexport interface MergeContactsRepointed {\n  deals: number\n  tasks: number\n  activities: number\n  leads: number\n}\n\nexport type MergeContactsResult =\n  | {\n      ok: true\n      survivorId: string\n      survivorEmail: string\n      mergedId: string\n      mergedEmail: string\n      /** Every address the survivor answers to now, primary first. */\n      emails: string[]\n      repointed: MergeContactsRepointed\n    }\n  | { ok: false; reason: 'same-record' | 'survivor-missing' | 'merged-missing' }\n\n/**\n * Point every row of `collection` whose `contactId` is `from` at `to`.\n *\n * Page, batch, repeat: each pass reads the rows still pointing at the\n * merged record — the ones a previous pass moved no longer match — so the\n * loop ends when a pass finds nothing. `updatedAt` moves with the pointer\n * because an integration syncing by `updatedAfter` has to see the change.\n */\nasync function repointContactId(\n  firestore: FirebaseFirestore.Firestore,\n  collection: FirebaseFirestore.CollectionReference,\n  from: string,\n  to: string,\n): Promise<number> {\n  let moved = 0\n  for (let pass = 0; pass < REPOINT_PASSES; pass += 1) {\n    const page = await collection\n      .where('contactId', '==', from)\n      .limit(REPOINT_PAGE)\n      .get()\n    if (page.empty) break\n    const batch = firestore.batch()\n    for (const row of page.docs) {\n      batch.update(row.ref, {\n        contactId: to,\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n    }\n    await batch.commit()\n    moved += page.size\n    if (page.size < REPOINT_PAGE) break\n  }\n  return moved\n}\n\n/**\n * The leads converted into the merged contact, restamped at the survivor.\n *\n * A lead lives at `hosts/{hostId}/leads/{personKey(email)}`, so there is no\n * query: each site that met either record is asked for a lead under each of\n * the merged record's addresses, and one that names the merged contact is\n * moved. Bounded by sites times addresses, both small.\n */\nasync function repointLeads(\n  firestore: FirebaseFirestore.Firestore,\n  hostIds: readonly string[],\n  emails: readonly string[],\n  from: string,\n  to: string,\n): Promise<number> {\n  let moved = 0\n  for (const hostId of hostIds) {\n    for (const email of emails) {\n      const key = personKey(email)\n      if (!key) continue\n      const leadRef = firestore\n        .collection('hosts')\n        .doc(hostId)\n        .collection('leads')\n        .doc(key)\n      const lead = await leadRef.get()\n      if (!lead.exists || lead.get('convertedContactId') !== from) continue\n      await leadRef.update({\n        convertedContactId: to,\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n      moved += 1\n    }\n  }\n  return moved\n}\n\nfunction strings(value: unknown): string[] {\n  return Array.isArray(value)\n    ? value.filter((item): item is string => typeof item === 'string' && item !== '')\n    : []\n}\n\nexport async function mergeContacts(\n  options: MergeContactsOptions,\n): Promise<MergeContactsResult> {\n  const { firestore, orgRef, survivorId, mergedId, actor, hostId } = options\n  if (!survivorId || !mergedId || survivorId === mergedId) {\n    return { ok: false, reason: 'same-record' }\n  }\n  const contactsRef = orgRef.collection('contacts')\n  const survivorRef = contactsRef.doc(survivorId)\n  const mergedRef = contactsRef.doc(mergedId)\n  const [survivorBefore, mergedBefore] = await Promise.all([\n    survivorRef.get(),\n    mergedRef.get(),\n  ])\n  if (!survivorBefore.exists) return { ok: false, reason: 'survivor-missing' }\n  if (!mergedBefore.exists) return { ok: false, reason: 'merged-missing' }\n  const mergedData = (mergedBefore.data() ?? {}) as Record<string, unknown>\n  const survivorData = (survivorBefore.data() ?? {}) as Record<string, unknown>\n\n  /*==========================================\n   * 1. THE CHILDREN — before the parent, for the reason the header gives.\n   *=========================================*/\n  const [deals, tasks, activities] = await Promise.all([\n    repointContactId(firestore, orgRef.collection(CRM_COLLECTIONS.deals), mergedId, survivorId),\n    repointContactId(firestore, orgRef.collection(CRM_COLLECTIONS.tasks), mergedId, survivorId),\n    repointContactId(\n      firestore,\n      orgRef.collection(CRM_COLLECTIONS.activities),\n      mergedId,\n      survivorId,\n    ),\n  ])\n  const leadHosts = [\n    ...new Set([\n      ...strings(mergedData['capturedByHostIds']),\n      ...strings(survivorData['capturedByHostIds']),\n      ...strings([mergedData['hostId'], survivorData['hostId'], hostId]),\n    ]),\n  ]\n  const leads = await repointLeads(\n    firestore,\n    leadHosts,\n    contactEmails(mergedData),\n    mergedId,\n    survivorId,\n  )\n\n  /*==========================================\n   * 2. THE SWAP — one transaction over both documents and the index.\n   *=========================================*/\n  const index = orgRef.collection(CONTACT_EMAIL_INDEX_COLLECTION)\n  const swapped = await firestore.runTransaction(async (transaction) => {\n    const [survivor, merged] = await Promise.all([\n      transaction.get(survivorRef),\n      transaction.get(mergedRef),\n    ])\n    if (!survivor.exists) return { reason: 'survivor-missing' as const }\n    if (!merged.exists) return { reason: 'merged-missing' as const }\n    const plan = planContactMerge(\n      (survivor.data() ?? {}) as Record<string, unknown>,\n      (merged.data() ?? {}) as Record<string, unknown>,\n    )\n    transaction.set(\n      survivorRef,\n      { ...plan.survivor, updatedAt: FieldValue.serverTimestamp() },\n      { merge: true },\n    )\n    for (const email of plan.emails) {\n      const key = personKey(email)\n      if (!key) continue\n      transaction.set(\n        index.doc(key),\n        { email, contactId: survivorId, updatedAt: FieldValue.serverTimestamp() },\n        { merge: true },\n      )\n    }\n    transaction.delete(mergedRef)\n    return { plan, survivor: (survivor.data() ?? {}) as Record<string, unknown> }\n  })\n  if ('reason' in swapped) return { ok: false, reason: swapped.reason }\n  const { plan } = swapped\n\n  /*\n   * The companies both records named counted two people and now count one\n   * (AGL-2613). Settled after the swap the way the capture settles its\n   * counts: a figure that could not move is logged, and the company page's\n   * live aggregate corrects it.\n   */\n  await settleCompanyContactsCounts(orgRef.collection(CRM_COLLECTIONS.companies), {\n    companyId: null,\n    mirror: null,\n    counts: plan.companyCounts,\n  })\n  /*\n   * The survivor now owns the merged record's open tasks too, so its next\n   * activity is the earliest of both (AGL-2661). Settled the same way: a\n   * figure that could not move is logged, and the Fields section's\n   * recompute corrects it.\n   */\n  await recomputeCrmNextTaskAt(firestore, orgRef.id, [{ contactId: survivorId }]).catch(\n    (error: unknown) => {\n      console.error('contact merge next activity could not be recomputed', survivorId, error)\n    },\n  )\n\n  const mergedEmail = contactEmails(mergedData)[0] ?? ''\n  const survivorEmail = plan.emails[0] ?? ''\n  // The canonical name — the one identity every holder shares — for the\n  // feed; the address stands in for a person nobody has named.\n  const survivorName =\n    typeof swapped.survivor['name'] === 'string' ? swapped.survivor['name'] : ''\n\n  /*\n   * THE TIMELINE NOTE, on the survivor: the merge is an event in this\n   * person's history, and the record page is where a reader looks for one.\n   * Filed under the calling site, or the survivor's first site for a door\n   * with none; its own catch, because a note that could not be written must\n   * not read as a merge that did not happen.\n   */\n  try {\n    await orgRef.collection(CRM_COLLECTIONS.activities).add({\n      kind: 'note',\n      body: `Merged with ${mergedEmail}`,\n      atMs: Date.now(),\n      byUid: actor.uid,\n      ...(options.actorName || actor.email\n        ? { byName: options.actorName || actor.email }\n        : {}),\n      contactId: survivorId,\n      visibleTo: plan.visibleTo,\n      hostId: hostId ?? String(survivorData['hostId'] ?? ''),\n      createdByUid: actor.uid,\n      createdAt: FieldValue.serverTimestamp(),\n      updatedAt: FieldValue.serverTimestamp(),\n    })\n  } catch (error) {\n    console.error('[contact-merge] timeline note failed', survivorId, error)\n  }\n\n  // The audit line (AGL-2622), in the feed of the site whose console did\n  // the work. A door with no site — the API — has no host feed to write.\n  if (hostId) {\n    await logHostActivity(hostId, actor, `Merged with ${mergedEmail}`, {\n      type: 'contact',\n      id: survivorId,\n      name: survivorName || survivorEmail,\n    })\n  }\n\n  return {\n    ok: true,\n    survivorId,\n    survivorEmail,\n    mergedId,\n    mergedEmail,\n    emails: plan.emails,\n    repointed: { deals, tasks, activities, leads },\n  }\n}\n"],"names":["CONTACT_EMAIL_INDEX_COLLECTION","contactEmails","planContactMerge","CRM_COLLECTIONS","personKey","FieldValue","settleCompanyContactsCounts","recomputeCrmNextTaskAt","logHostActivity","REPOINT_PAGE","REPOINT_PASSES","repointContactId","firestore","collection","from","to","moved","pass","page","where","limit","get","empty","batch","row","docs","update","ref","contactId","updatedAt","serverTimestamp","commit","size","repointLeads","hostIds","emails","hostId","email","key","leadRef","doc","lead","exists","convertedContactId","strings","value","Array","isArray","filter","item","mergeContacts","options","mergedBefore","survivorBefore","plan","orgRef","survivorId","mergedId","actor","ok","reason","contactsRef","survivorRef","mergedRef","Promise","all","mergedData","data","survivorData","deals","tasks","activities","leadHosts","Set","leads","index","swapped","runTransaction","transaction","survivor","merged","set","merge","delete","companies","companyId","mirror","counts","companyCounts","id","catch","error","console","mergedEmail","survivorEmail","survivorName","add","kind","body","atMs","Date","now","byUid","uid","actorName","byName","visibleTo","String","createdByUid","createdAt","type","name","repointed"],"mappings":"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"}

package/src/lib/server/contact-suppression.d.ts

@@ -0,0 +1,153 @@
+/**
+ * @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.
+ */
+export declare const CONTACT_SUPPRESSIONS_COLLECTION = "contactSuppressions";
+/**
+ * The channels §11 names. Kept as an explicit list rather than a boolean
+ * because they are governed differently — a STOP text is a texting opt-out by
+ * statute, and reading it as a calling opt-out too would be us inventing a
+ * request the person did not make. Callers that mean both say both.
+ */
+export declare const CONTACT_CHANNELS: readonly ["calls", "texts"];
+export type ContactChannel = (typeof CONTACT_CHANNELS)[number];
+/** Where the request came in. Every route §11 offers, plus staff-initiated. */
+export type ContactSuppressionSource = 
+/** Reply STOP (or another CTIA keyword) to a marketing text. */
+'sms-keyword'
+/** Emailed privacy@aglyn.com and a human recorded it. */
+ | 'email'
+/** Said so on a call and a human recorded it. */
+ | 'verbal'
+/** The user asked us to delete the number they had on file. */
+ | 'erasure-request'
+/** Recorded by staff for any other reason (a complaint, a bounce, a court). */
+ | 'staff';
+export interface SuppressPhoneContactInput {
+    /** Anything `normalizePhone` accepts; stored as E.164. */
+    phoneNumber: string;
+    /** Defaults to BOTH channels — the conservative reading of an ambiguous ask. */
+    channels?: ContactChannel[];
+    source: ContactSuppressionSource;
+    /** The account the request was matched to, when it was matched to one. */
+    uid?: string | null;
+    /** Staff member who took the email or the call. */
+    recordedByUid?: string | null;
+    /** Free text: what they actually said, the ticket id, the case number. */
+    note?: string | null;
+    /**
+     * True only when the person also asked us to stop holding the number.
+     * `seedUserProfile` reads this to refuse an IdP re-assertion, so it is the
+     * difference between "do not call me" and "do not keep my number".
+     */
+    erasePhoneOnFile?: boolean;
+    /** Injectable for tests; defaults to the admin app's Firestore. */
+    firestore?: any;
+}
+export interface ContactSuppressionRecord {
+    phoneNumber: string;
+    channels: ContactChannel[];
+    source: ContactSuppressionSource;
+    uid: string | null;
+    recordedByUid: string | null;
+    note: string | null;
+    erasePhoneOnFile: boolean;
+    /** Non-null once the person opted back in. A revoked record does not suppress. */
+    revokedAt: unknown | null;
+}
+/**
+ * Document id for an E.164 number: the digits, with the `+` dropped.
+ *
+ * The `+` is a legal Firestore id character, but it is also the one character
+ * that means "space" in a form-encoded query string, so a number carried
+ * through a URL somewhere down the line would silently become a different
+ * number. Dropping it here costs nothing — the full E.164 is stored in the
+ * document — and removes the whole class of bug in advance.
+ *
+ * @returns the id, or `null` when the input is not a number we can be sure of.
+ *          Never a best-guess id: suppressing the wrong subscriber and
+ *          believing you suppressed the right one is worse than refusing.
+ */
+export declare function contactSuppressionKey(phoneNumber: string | null | undefined): string | null;
+/**
+ * Record a do-not-contact request. Idempotent by document id, so a retried
+ * request or a second STOP cannot produce a second record.
+ *
+ * Merging rather than replacing, and the channel list UNIONS with whatever is
+ * already recorded: someone who opted out of texts in March and calls in June
+ * is opted out of both in July. Narrowing a suppression is `releasePhoneContact`
+ * and nothing else — no write on this path may ever make a person MORE
+ * reachable than they already were.
+ *
+ * A previously revoked record is un-revoked, because a fresh request is a
+ * fresh request.
+ *
+ * @throws when the number cannot be normalized. Deliberately NOT best-effort:
+ *         a silently dropped opt-out is the exact failure this issue exists to
+ *         fix, so the caller has to see it.
+ */
+export declare function suppressPhoneContact(input: SuppressPhoneContactInput): Promise<{
+    phoneNumber: string;
+    channels: ContactChannel[];
+    created: boolean;
+}>;
+/**
+ * Opt back in (a START/UNSTOP reply, or a staff correction of a mis-recorded
+ * opt-out). The record is kept and marked revoked, never deleted.
+ *
+ * IMPORTANT — this does NOT create consent. Clearing a suppression only
+ * removes a prohibition; it does not manufacture the prior express written
+ * consent that TCPA requires before a marketing call or text may be placed at
+ * all. That mechanism does not exist yet (AGL-1564, and the privacy benchmark
+ * items 9–10), so after this call the correct number of marketing messages to
+ * send is still zero.
+ *
+ * @returns false when there was no record to revoke.
+ */
+export declare function releasePhoneContact(input: {
+    phoneNumber: string;
+    releasedByUid?: string | null;
+    note?: string | null;
+    firestore?: any;
+}): Promise<boolean>;
+/**
+ * The dial-time gate. Every outbound marketing call or text MUST pass through
+ * this before the number reaches a provider.
+ *
+ * FAILS CLOSED. A read that throws — rules, quota, a cold Firestore — answers
+ * `true`, meaning "treat as suppressed". The alternative is a list outage that
+ * silently turns into a round of calls to people who asked us never to call
+ * again, which is a statutory violation per call rather than a delayed
+ * campaign. Never "fix" a flaky read here by returning false.
+ */
+export declare function isPhoneContactSuppressed(phoneNumber: string | null | undefined, channel?: ContactChannel, injectedFirestore?: any): Promise<boolean>;
+/**
+ * Read one record, for the staff surface and for `seedUserProfile`'s
+ * re-assertion guard.
+ */
+export declare function getContactSuppression(phoneNumber: string | null | undefined, injectedFirestore?: any): Promise<(ContactSuppressionRecord & {
+    $id: string;
+}) | null>;
+/**
+ * The staff queue, newest first. Ordered by `updatedAt` so a re-recorded or
+ * revoked entry surfaces again — the operator's question is "what changed",
+ * not "what was first written".
+ */
+export declare function listContactSuppressions(options?: {
+    limit?: number;
+    firestore?: any;
+}): Promise<Array<ContactSuppressionRecord & {
+    $id: string;
+}>>;