@aglyn/plugins-crm 1.0.0-beta.218 → 1.0.0-beta.220

package/src/lib/server/merge-contacts.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/merge-contacts.js

@@ -0,0 +1,274 @@
+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 "../model/contact-merge.js";
+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 "@aglyn/tenant-data-admin/server/contact-company-link";
+import { recomputeCrmNextTaskAt } from "@aglyn/tenant-data-admin/server/crm-next-activity";
+import { restampCrmListFieldsAt } from "@aglyn/tenant-data-admin/server/crm-records";
+import { logHostActivity } from "@aglyn/tenant-data-admin/server/organizations";
+/** 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 `orgs/{orgId}/leads/{personKey(email)}` (AGL-3275), so there
+ * is still no query — one document per address, asked for directly. This used
+ * to be bounded by sites TIMES addresses because a lead lived under each site;
+ * it is bounded by addresses now, and the sites drop out of the signature
+ * because the collection no longer has one per site to walk.
+ */ async function repointLeads(orgRef, emails, from, to) {
+    let moved = 0;
+    /*
+   * ONE ROW PER ADDRESS, on the org (AGL-3275). This walked the sites because
+   * there was a lead under each of them; re-pointing the same document once
+   * per site would now be the same write repeated, and the second would find
+   * `convertedContactId` already moved and skip — a silent undercount rather
+   * than a wrong answer, but an undercount the caller reports to the operator.
+   */ for (const email of emails){
+        const key = personKey(email);
+        if (!key) continue;
+        const leadRef = orgRef.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;
+}
+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 leads = await repointLeads(orgRef, 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 survivor now carries both records' addresses, holders and facets —
+    // what the Contacts list searches and filters by (AGL-3321).
+    await restampCrmListFieldsAt(survivorRef, 'contacts');
+    /*
+   * 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=merge-contacts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/merge-contacts.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 '../model/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 '@aglyn/tenant-data-admin/server/contact-company-link'\nimport { recomputeCrmNextTaskAt } from '@aglyn/tenant-data-admin/server/crm-next-activity'\nimport { restampCrmListFieldsAt } from '@aglyn/tenant-data-admin/server/crm-records'\nimport { logHostActivity } from '@aglyn/tenant-data-admin/server/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 `orgs/{orgId}/leads/{personKey(email)}` (AGL-3275), so there\n * is still no query — one document per address, asked for directly. This used\n * to be bounded by sites TIMES addresses because a lead lived under each site;\n * it is bounded by addresses now, and the sites drop out of the signature\n * because the collection no longer has one per site to walk.\n */\nasync function repointLeads(\n  orgRef: FirebaseFirestore.DocumentReference,\n  emails: readonly string[],\n  from: string,\n  to: string,\n): Promise<number> {\n  let moved = 0\n  /*\n   * ONE ROW PER ADDRESS, on the org (AGL-3275). This walked the sites because\n   * there was a lead under each of them; re-pointing the same document once\n   * per site would now be the same write repeated, and the second would find\n   * `convertedContactId` already moved and skip — a silent undercount rather\n   * than a wrong answer, but an undercount the caller reports to the operator.\n   */\n  for (const email of emails) {\n    const key = personKey(email)\n    if (!key) continue\n    const leadRef = orgRef.collection('leads').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  return moved\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 leads = await repointLeads(\n    orgRef,\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  // The survivor now carries both records' addresses, holders and facets —\n  // what the Contacts list searches and filters by (AGL-3321).\n  await restampCrmListFieldsAt(survivorRef, 'contacts')\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","restampCrmListFieldsAt","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","orgRef","emails","email","key","leadRef","doc","lead","exists","convertedContactId","mergeContacts","options","mergedBefore","survivorBefore","plan","survivorId","mergedId","actor","hostId","ok","reason","contactsRef","survivorRef","mergedRef","Promise","all","mergedData","data","survivorData","deals","tasks","activities","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/pipeline-record-index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @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 { PluginRecordIndex } from '@aglyn/aglyn/plugin-manager/plugin-record-index';
+/**
+ * The CRM's `pipeline` index (AGL-3080): the organization's deal pipelines
+ * and their stages, as another plugin reads them — an automation drafted by
+ * the AI names a stage a deal moves to — without knowing where pipelines are
+ * stored or what an archived one looks like.
+ *
+ * Org-scoped (`orgId` required; a site-only scope answers nothing). With a
+ * `hostId`, only the pipelines that site can see — the ones shared with it
+ * or with every site — which is the set that site's CRM offers. An archived
+ * pipeline is left out of every answer.
+ *
+ * `name` is the pipeline's, or `Untitled pipeline` for one saved without,
+ * which is what the CRM itself calls it. A pipeline's `facts`:
+ *   `stages: Array<{ id: string, name: string }>`, in the pipeline's order,
+ *   each stage that has an id (a stage saved without a name has `name: ''`).
+ */
+/** What the CRM calls a pipeline saved without a name. */
+export declare const UNTITLED_PIPELINE = "Untitled pipeline";
+export declare const pipelineRecordIndex: PluginRecordIndex;

package/src/lib/server/pipeline-record-index.js

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { firebaseAdmin } from "@aglyn/tenant-data-admin/server/firebase-admin";
+import { scopedToHost } from "@aglyn/tenant-data-admin/server/organizations";
+/**
+ * The CRM's `pipeline` index (AGL-3080): the organization's deal pipelines
+ * and their stages, as another plugin reads them — an automation drafted by
+ * the AI names a stage a deal moves to — without knowing where pipelines are
+ * stored or what an archived one looks like.
+ *
+ * Org-scoped (`orgId` required; a site-only scope answers nothing). With a
+ * `hostId`, only the pipelines that site can see — the ones shared with it
+ * or with every site — which is the set that site's CRM offers. An archived
+ * pipeline is left out of every answer.
+ *
+ * `name` is the pipeline's, or `Untitled pipeline` for one saved without,
+ * which is what the CRM itself calls it. A pipeline's `facts`:
+ *   `stages: Array<{ id: string, name: string }>`, in the pipeline's order,
+ *   each stage that has an id (a stage saved without a name has `name: ''`).
+ */ /** What the CRM calls a pipeline saved without a name. */ export const UNTITLED_PIPELINE = 'Untitled pipeline';
+const PIPELINE_FIELDS = [
+    'name',
+    'stages',
+    'archivedAt'
+];
+const str = (value)=>typeof value === 'string' ? value.trim() : '';
+function pipelineRecord(id, data) {
+    if (!data || Number(data['archivedAt']) > 0) return null;
+    const stages = (Array.isArray(data['stages']) ? data['stages'] : []).map((stage)=>{
+        const entry = stage != null ? stage : {};
+        return {
+            id: str(entry['id']),
+            name: str(entry['name'])
+        };
+    }).filter((stage)=>stage.id);
+    return {
+        id,
+        name: str(data['name']) || UNTITLED_PIPELINE,
+        facts: {
+            stages
+        }
+    };
+}
+function pipelineCollection(orgId) {
+    return firebaseAdmin.app().firestore().collection('orgs').doc(orgId).collection('pipelines');
+}
+export const pipelineRecordIndex = {
+    async list ({ orgId, hostId, limit }) {
+        if (!orgId || limit <= 0) return {
+            records: [],
+            truncated: false
+        };
+        const collection = pipelineCollection(orgId);
+        // One more than asked, so `truncated` is a fact rather than a guess; the
+        // archived rows are filtered after the read.
+        const snapshot = await (hostId ? scopedToHost(collection, hostId) : collection).select(...PIPELINE_FIELDS).limit(limit + 1).get();
+        const records = snapshot.docs.slice(0, limit).map((doc)=>pipelineRecord(doc.id, doc.data())).filter((record)=>record !== null);
+        return {
+            records,
+            truncated: snapshot.docs.length > limit
+        };
+    },
+    async get ({ orgId, hostId, id }) {
+        if (!orgId || !id) return null;
+        const snapshot = await pipelineCollection(orgId).doc(id).get();
+        const data = snapshot.exists ? snapshot.data() : undefined;
+        // A site asks about the pipelines it can see, and no other.
+        if (hostId && !visibleToHost(data == null ? void 0 : data['visibleTo'], hostId)) return null;
+        return pipelineRecord(snapshot.id, data);
+    }
+};
+
+//# sourceMappingURL=pipeline-record-index.js.map

package/src/lib/server/pipeline-record-index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/pipeline-record-index.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type {\n  PluginIndexedRecord,\n  PluginRecordIndex,\n} from '@aglyn/aglyn/plugin-manager/plugin-record-index'\nimport { visibleToHost } from '@aglyn/aglyn/app-utils/scope-tokens'\nimport { firebaseAdmin } from '@aglyn/tenant-data-admin/server/firebase-admin'\nimport { scopedToHost } from '@aglyn/tenant-data-admin/server/organizations'\n\n/**\n * The CRM's `pipeline` index (AGL-3080): the organization's deal pipelines\n * and their stages, as another plugin reads them — an automation drafted by\n * the AI names a stage a deal moves to — without knowing where pipelines are\n * stored or what an archived one looks like.\n *\n * Org-scoped (`orgId` required; a site-only scope answers nothing). With a\n * `hostId`, only the pipelines that site can see — the ones shared with it\n * or with every site — which is the set that site's CRM offers. An archived\n * pipeline is left out of every answer.\n *\n * `name` is the pipeline's, or `Untitled pipeline` for one saved without,\n * which is what the CRM itself calls it. A pipeline's `facts`:\n *   `stages: Array<{ id: string, name: string }>`, in the pipeline's order,\n *   each stage that has an id (a stage saved without a name has `name: ''`).\n */\n\n/** What the CRM calls a pipeline saved without a name. */\nexport const UNTITLED_PIPELINE = 'Untitled pipeline'\n\nconst PIPELINE_FIELDS = ['name', 'stages', 'archivedAt'] as const\n\nconst str = (value: unknown): string => (typeof value === 'string' ? value.trim() : '')\n\nfunction pipelineRecord(\n  id: string,\n  data: Record<string, unknown> | undefined,\n): PluginIndexedRecord | null {\n  if (!data || Number(data['archivedAt']) > 0) return null\n  const stages = (Array.isArray(data['stages']) ? data['stages'] : [])\n    .map((stage) => {\n      const entry = (stage ?? {}) as Record<string, unknown>\n      return { id: str(entry['id']), name: str(entry['name']) }\n    })\n    .filter((stage) => stage.id)\n  return { id, name: str(data['name']) || UNTITLED_PIPELINE, facts: { stages } }\n}\n\nfunction pipelineCollection(orgId: string): FirebaseFirestore.CollectionReference {\n  return firebaseAdmin.app().firestore().collection('orgs').doc(orgId).collection('pipelines')\n}\n\nexport const pipelineRecordIndex: PluginRecordIndex = {\n  async list({ orgId, hostId, limit }) {\n    if (!orgId || limit <= 0) return { records: [], truncated: false }\n    const collection = pipelineCollection(orgId)\n    // One more than asked, so `truncated` is a fact rather than a guess; the\n    // archived rows are filtered after the read.\n    const snapshot = await (hostId ? scopedToHost(collection, hostId) : collection)\n      .select(...PIPELINE_FIELDS)\n      .limit(limit + 1)\n      .get()\n    const records = snapshot.docs\n      .slice(0, limit)\n      .map((doc) => pipelineRecord(doc.id, doc.data()))\n      .filter((record): record is PluginIndexedRecord => record !== null)\n    return { records, truncated: snapshot.docs.length > limit }\n  },\n  async get({ orgId, hostId, id }) {\n    if (!orgId || !id) return null\n    const snapshot = await pipelineCollection(orgId).doc(id).get()\n    const data = snapshot.exists ? snapshot.data() : undefined\n    // A site asks about the pipelines it can see, and no other.\n    if (hostId && !visibleToHost(data?.['visibleTo'] as string[] | undefined, hostId)) return null\n    return pipelineRecord(snapshot.id, data)\n  },\n}\n"],"names":["visibleToHost","firebaseAdmin","scopedToHost","UNTITLED_PIPELINE","PIPELINE_FIELDS","str","value","trim","pipelineRecord","id","data","Number","stages","Array","isArray","map","stage","entry","name","filter","facts","pipelineCollection","orgId","app","firestore","collection","doc","pipelineRecordIndex","list","hostId","limit","records","truncated","snapshot","select","get","docs","slice","record","length","exists","undefined"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAMD,SAASA,aAAa,QAAQ,sCAAqC;AACnE,SAASC,aAAa,QAAQ,iDAAgD;AAC9E,SAASC,YAAY,QAAQ,gDAA+C;AAE5E;;;;;;;;;;;;;;;CAeC,GAED,wDAAwD,GACxD,OAAO,MAAMC,oBAAoB,oBAAmB;AAEpD,MAAMC,kBAAkB;IAAC;IAAQ;IAAU;CAAa;AAExD,MAAMC,MAAM,CAACC,QAA4B,OAAOA,UAAU,WAAWA,MAAMC,IAAI,KAAK;AAEpF,SAASC,eACPC,EAAU,EACVC,IAAyC;IAEzC,IAAI,CAACA,QAAQC,OAAOD,IAAI,CAAC,aAAa,IAAI,GAAG,OAAO;IACpD,MAAME,SAAS,AAACC,CAAAA,MAAMC,OAAO,CAACJ,IAAI,CAAC,SAAS,IAAIA,IAAI,CAAC,SAAS,GAAG,EAAE,AAAD,EAC/DK,GAAG,CAAC,CAACC;QACJ,MAAMC,QAASD,gBAAAA,QAAS,CAAC;QACzB,OAAO;YAAEP,IAAIJ,IAAIY,KAAK,CAAC,KAAK;YAAGC,MAAMb,IAAIY,KAAK,CAAC,OAAO;QAAE;IAC1D,GACCE,MAAM,CAAC,CAACH,QAAUA,MAAMP,EAAE;IAC7B,OAAO;QAAEA;QAAIS,MAAMb,IAAIK,IAAI,CAAC,OAAO,KAAKP;QAAmBiB,OAAO;YAAER;QAAO;IAAE;AAC/E;AAEA,SAASS,mBAAmBC,KAAa;IACvC,OAAOrB,cAAcsB,GAAG,GAAGC,SAAS,GAAGC,UAAU,CAAC,QAAQC,GAAG,CAACJ,OAAOG,UAAU,CAAC;AAClF;AAEA,OAAO,MAAME,sBAAyC;IACpD,MAAMC,MAAK,EAAEN,KAAK,EAAEO,MAAM,EAAEC,KAAK,EAAE;QACjC,IAAI,CAACR,SAASQ,SAAS,GAAG,OAAO;YAAEC,SAAS,EAAE;YAAEC,WAAW;QAAM;QACjE,MAAMP,aAAaJ,mBAAmBC;QACtC,yEAAyE;QACzE,6CAA6C;QAC7C,MAAMW,WAAW,MAAM,AAACJ,CAAAA,SAAS3B,aAAauB,YAAYI,UAAUJ,UAAS,EAC1ES,MAAM,IAAI9B,iBACV0B,KAAK,CAACA,QAAQ,GACdK,GAAG;QACN,MAAMJ,UAAUE,SAASG,IAAI,CAC1BC,KAAK,CAAC,GAAGP,OACTf,GAAG,CAAC,CAACW,MAAQlB,eAAekB,IAAIjB,EAAE,EAAEiB,IAAIhB,IAAI,KAC5CS,MAAM,CAAC,CAACmB,SAA0CA,WAAW;QAChE,OAAO;YAAEP;YAASC,WAAWC,SAASG,IAAI,CAACG,MAAM,GAAGT;QAAM;IAC5D;IACA,MAAMK,KAAI,EAAEb,KAAK,EAAEO,MAAM,EAAEpB,EAAE,EAAE;QAC7B,IAAI,CAACa,SAAS,CAACb,IAAI,OAAO;QAC1B,MAAMwB,WAAW,MAAMZ,mBAAmBC,OAAOI,GAAG,CAACjB,IAAI0B,GAAG;QAC5D,MAAMzB,OAAOuB,SAASO,MAAM,GAAGP,SAASvB,IAAI,KAAK+B;QACjD,4DAA4D;QAC5D,IAAIZ,UAAU,CAAC7B,cAAcU,wBAAAA,IAAM,CAAC,YAAY,EAA0BmB,SAAS,OAAO;QAC1F,OAAOrB,eAAeyB,SAASxB,EAAE,EAAEC;IACrC;AACF,EAAC"}

package/src/lib/server/record-email-state.js

@@ -19,6 +19,8 @@ import { CRM_EMAIL_STATUS_FIELD, CRM_EMAIL_STATUS_NONE, EMAIL_STATE_FIELD, nextE
 import { findContactByEmail, firebaseAdmin } from "@aglyn/tenant-data-admin";
 import { FieldValue } from "firebase-admin/firestore";
 import { BUNDLE_ID } from "../constants/bundle-common.js";
+import { recordContactEmailEngagement } from "./contact-email-engagement.js";
+import { nurtureReachedLeads } from "./lead-nurturing.js";
 const NONE = {
     records: 0
 };
@@ -121,6 +123,27 @@ export function createCrmRecordEmailStateWriter(deps) {
             return {
                 records
             };
+        },
+        async engaged (request) {
+            try {
+                const records = await recordContactEmailEngagement({
+                    hostId: request.hostId,
+                    events: request.events,
+                    firestore: deps.firestore()
+                });
+                return {
+                    records
+                };
+            } catch (error) {
+                console.error('[crm] the contacts could not be stamped with an engagement', request.hostId, error);
+                return NONE;
+            }
+        },
+        // A delivered campaign moves the New leads it reached to Nurturing (AGL-3446).
+        async reached (request) {
+            return {
+                records: await nurtureReachedLeads(deps.firestore(), request)
+            };
         }
     };
 }

package/src/lib/server/record-email-state.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/record-email-state.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  registerPluginRecordEmailStateWriter,\n  type PluginRecordEmailStateReport,\n  type PluginRecordEmailStateRequest,\n  type PluginRecordEmailStateWriter,\n} from '@aglyn/aglyn/plugin-manager/plugin-record-email-state'\nimport {\n  CRM_EMAIL_STATUS_FIELD,\n  CRM_EMAIL_STATUS_NONE,\n  EMAIL_STATE_FIELD,\n  nextEmailState,\n  normalizeContactEmail,\n  personKey,\n  readEmailState,\n  type EmailState,\n} from '@aglyn/aglyn/server'\nimport { findContactByEmail, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { BUNDLE_ID } from '../constants/bundle-common'\n\n/**\n * THE CRM'S WRITER ON THE CORE'S RECORD EMAIL-STATE SEAM (AGL-3245).\n *\n * A sender filed a verdict on an address — the outreach runtime's bounce,\n * the campaign webhook's complaint, a member's do-not-contact mark, the\n * unsubscribe link — and says so here; this writes it onto every record\n * the address is, as `emailState`, so the record a person reads and the\n * lists a send consults agree.\n *\n * One address can be several records: the contact the organization holds\n * (found through the address index, `findContactByEmail`), and a lead on\n * each site the organization owns — leads are keyed by `personKey`, so a\n * lead is addressed directly under every host. All of them are stamped;\n * the verdict is about the address, not about which record a rep opened.\n * A caller that knows only the site reads the organization off it.\n *\n * The write keeps the STRONGER verdict (`nextEmailState`): a member's\n * do-not-contact mark is not undone by a later bounce, and `ok` lands only\n * when a caller forces it. `updatedAt` is left alone — a verdict is\n * something that happened to the person, not an edit the team made, and a\n * list sorted on recency must not reshuffle on a bounce.\n *\n * Never throws: the list is the control, and a record that could not be\n * stamped is a chip a page goes without, logged.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\n\nexport interface CrmRecordEmailStateDeps {\n  firestore(): Firestore\n}\n\nconst NONE: PluginRecordEmailStateReport = { records: 0 }\n\n/**\n * Applies the verdict to one record; answers whether it moved. A read then\n * a merge rather than a transaction: two verdicts landing together each\n * compare against a state at least as old as their own, and the ranking\n * makes the order of two writes of the same rank immaterial.\n */\nasync function stampRecord(\n  ref: FirebaseFirestore.DocumentReference,\n  incoming: EmailState,\n  force: boolean,\n  withdraw = false,\n): Promise<boolean> {\n  const snapshot = await ref.get()\n  if (!snapshot.exists) return false\n  const current = readEmailState(snapshot.data() as Record<string, unknown>)\n  /*\n   * A WITHDRAWAL takes back the one verdict it names (AGL-3328): the\n   * deliverability check's \"Would bounce\" once the domain takes mail again.\n   * Any other standing verdict — a bounce DNS cannot see — is left alone.\n   */\n  if (withdraw) {\n    if (current?.status !== incoming.status) return false\n    await ref.update({\n      [EMAIL_STATE_FIELD]: FieldValue.delete(),\n      [CRM_EMAIL_STATUS_FIELD]: CRM_EMAIL_STATUS_NONE,\n    })\n    return true\n  }\n  // The deliverability check saying again what the record already holds:\n  // the date it was first found is the one worth keeping.\n  if (incoming.source === 'check' && current?.status === incoming.status) return false\n  const next = nextEmailState(current, incoming, { force })\n  // The current verdict stood, or the same verdict arrived again — a second\n  // run of the caller — and there is nothing to write.\n  if (\n    next === current ||\n    (current &&\n      next.status === current.status &&\n      next.atMs === current.atMs &&\n      next.source === current.source &&\n      next.detail === current.detail)\n  ) {\n    return false\n  }\n  // `emailStatus` beside it: the verdict as the CRM lists filter by it\n  // (AGL-3321) — a key a query can ask, where the state is a map.\n  await ref.set(\n    { [EMAIL_STATE_FIELD]: next, [CRM_EMAIL_STATUS_FIELD]: next.status },\n    { merge: true },\n  )\n  return true\n}\n\n/** The organization a request names, or the one its site belongs to. */\nasync function resolveOrgId(firestore: Firestore, request: PluginRecordEmailStateRequest): Promise<string> {\n  const named = String(request.orgId ?? '').trim()\n  if (named) return named\n  const hostId = String(request.hostId ?? '').trim()\n  if (!hostId) return ''\n  const host = await firestore.collection('hosts').doc(hostId).get()\n  return host.exists ? String(host.get('orgId') ?? '') : ''\n}\n\nexport function createCrmRecordEmailStateWriter(deps: CrmRecordEmailStateDeps): PluginRecordEmailStateWriter {\n  return {\n    async stamp(request) {\n      const email = normalizeContactEmail(request.email)\n      const key = email ? personKey(email) : null\n      if (!email || !key) return NONE\n      const firestore = deps.firestore()\n      let orgId: string\n      try {\n        orgId = await resolveOrgId(firestore, request)\n      } catch (error) {\n        console.error('[crm] the site’s organization could not be read for an email state', request.hostId, error)\n        return NONE\n      }\n      if (!orgId) return NONE\n      const state: EmailState = {\n        status: request.state.status,\n        atMs: Number.isFinite(request.state.atMs) && request.state.atMs > 0 ? request.state.atMs : Date.now(),\n        source: request.state.source,\n        detail: request.state.detail\n          ? String(request.state.detail).replace(/\\s+/g, ' ').trim().slice(0, 500)\n          : null,\n        ...(request.state.enrollmentId ? { enrollmentId: request.state.enrollmentId } : {}),\n      }\n      const force = request.force === true\n      const withdraw = request.withdraw === true\n      let records = 0\n      try {\n        const contacts = firestore.collection('orgs').doc(orgId).collection('contacts')\n        const contact = await findContactByEmail(contacts, email)\n        if (contact && (await stampRecord(contact.ref, state, force, withdraw))) records += 1\n      } catch (error) {\n        console.error('[crm] the contact could not be stamped with an email state', orgId, error)\n      }\n      try {\n        /*\n         * ONE ORG ROW. A bounce or a do-not-contact mark is the platform's\n         * verdict on the ADDRESS, and since AGL-3277 there is one document\n         * carrying it — the per-site loop beside this had nothing left to\n         * find once AGL-3276 emptied the host path.\n         */\n        if (await stampRecord(\n          firestore.collection('orgs').doc(orgId).collection('leads').doc(key),\n          state,\n          force,\n          withdraw,\n        )) {\n          records += 1\n        }\n      } catch (error) {\n        console.error('[crm] the leads could not be stamped with an email state', orgId, error)\n      }\n      return { records }\n    },\n  }\n}\n\n/** The platform's own dependencies. Specs build their own. */\nexport function defaultCrmRecordEmailStateDeps(): CrmRecordEmailStateDeps {\n  return { firestore: () => firebaseAdmin.app().firestore() }\n}\n\n/** Registers the CRM as the workspace's record system on the email-state seam. */\nexport function registerCrmRecordEmailStateWriter(\n  deps: CrmRecordEmailStateDeps = defaultCrmRecordEmailStateDeps(),\n): void {\n  registerPluginRecordEmailStateWriter(createCrmRecordEmailStateWriter(deps), { pluginId: BUNDLE_ID })\n}\n"],"names":["registerPluginRecordEmailStateWriter","CRM_EMAIL_STATUS_FIELD","CRM_EMAIL_STATUS_NONE","EMAIL_STATE_FIELD","nextEmailState","normalizeContactEmail","personKey","readEmailState","findContactByEmail","firebaseAdmin","FieldValue","BUNDLE_ID","NONE","records","stampRecord","ref","incoming","force","withdraw","snapshot","get","exists","current","data","status","update","delete","source","next","atMs","detail","set","merge","resolveOrgId","firestore","request","host","named","String","orgId","trim","hostId","collection","doc","createCrmRecordEmailStateWriter","deps","stamp","email","key","error","console","state","Number","isFinite","Date","now","replace","slice","enrollmentId","contacts","contact","defaultCrmRecordEmailStateDeps","app","registerCrmRecordEmailStateWriter","pluginId"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/record-email-state.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  registerPluginRecordEmailStateWriter,\n  type PluginRecordEmailStateReport,\n  type PluginRecordEmailStateRequest,\n  type PluginRecordEmailStateWriter,\n} from '@aglyn/aglyn/plugin-manager/plugin-record-email-state'\nimport {\n  CRM_EMAIL_STATUS_FIELD,\n  CRM_EMAIL_STATUS_NONE,\n  EMAIL_STATE_FIELD,\n  nextEmailState,\n  normalizeContactEmail,\n  personKey,\n  readEmailState,\n  type EmailState,\n} from '@aglyn/aglyn/server'\nimport { findContactByEmail, firebaseAdmin } from '@aglyn/tenant-data-admin'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { BUNDLE_ID } from '../constants/bundle-common'\nimport { recordContactEmailEngagement } from './contact-email-engagement'\nimport { nurtureReachedLeads } from './lead-nurturing'\n\n/**\n * THE CRM'S WRITER ON THE CORE'S RECORD EMAIL-STATE SEAM (AGL-3245).\n *\n * A sender filed a verdict on an address — the outreach runtime's bounce,\n * the campaign webhook's complaint, a member's do-not-contact mark, the\n * unsubscribe link — and says so here; this writes it onto every record\n * the address is, as `emailState`, so the record a person reads and the\n * lists a send consults agree.\n *\n * One address can be several records: the contact the organization holds\n * (found through the address index, `findContactByEmail`), and a lead on\n * each site the organization owns — leads are keyed by `personKey`, so a\n * lead is addressed directly under every host. All of them are stamped;\n * the verdict is about the address, not about which record a rep opened.\n * A caller that knows only the site reads the organization off it.\n *\n * The write keeps the STRONGER verdict (`nextEmailState`): a member's\n * do-not-contact mark is not undone by a later bounce, and `ok` lands only\n * when a caller forces it. `updatedAt` is left alone — a verdict is\n * something that happened to the person, not an edit the team made, and a\n * list sorted on recency must not reshuffle on a bounce.\n *\n * Never throws: the list is the control, and a record that could not be\n * stamped is a chip a page goes without, logged.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\n\nexport interface CrmRecordEmailStateDeps {\n  firestore(): Firestore\n}\n\nconst NONE: PluginRecordEmailStateReport = { records: 0 }\n\n/**\n * Applies the verdict to one record; answers whether it moved. A read then\n * a merge rather than a transaction: two verdicts landing together each\n * compare against a state at least as old as their own, and the ranking\n * makes the order of two writes of the same rank immaterial.\n */\nasync function stampRecord(\n  ref: FirebaseFirestore.DocumentReference,\n  incoming: EmailState,\n  force: boolean,\n  withdraw = false,\n): Promise<boolean> {\n  const snapshot = await ref.get()\n  if (!snapshot.exists) return false\n  const current = readEmailState(snapshot.data() as Record<string, unknown>)\n  /*\n   * A WITHDRAWAL takes back the one verdict it names (AGL-3328): the\n   * deliverability check's \"Would bounce\" once the domain takes mail again.\n   * Any other standing verdict — a bounce DNS cannot see — is left alone.\n   */\n  if (withdraw) {\n    if (current?.status !== incoming.status) return false\n    await ref.update({\n      [EMAIL_STATE_FIELD]: FieldValue.delete(),\n      [CRM_EMAIL_STATUS_FIELD]: CRM_EMAIL_STATUS_NONE,\n    })\n    return true\n  }\n  // The deliverability check saying again what the record already holds:\n  // the date it was first found is the one worth keeping.\n  if (incoming.source === 'check' && current?.status === incoming.status) return false\n  const next = nextEmailState(current, incoming, { force })\n  // The current verdict stood, or the same verdict arrived again — a second\n  // run of the caller — and there is nothing to write.\n  if (\n    next === current ||\n    (current &&\n      next.status === current.status &&\n      next.atMs === current.atMs &&\n      next.source === current.source &&\n      next.detail === current.detail)\n  ) {\n    return false\n  }\n  // `emailStatus` beside it: the verdict as the CRM lists filter by it\n  // (AGL-3321) — a key a query can ask, where the state is a map.\n  await ref.set(\n    { [EMAIL_STATE_FIELD]: next, [CRM_EMAIL_STATUS_FIELD]: next.status },\n    { merge: true },\n  )\n  return true\n}\n\n/** The organization a request names, or the one its site belongs to. */\nasync function resolveOrgId(firestore: Firestore, request: PluginRecordEmailStateRequest): Promise<string> {\n  const named = String(request.orgId ?? '').trim()\n  if (named) return named\n  const hostId = String(request.hostId ?? '').trim()\n  if (!hostId) return ''\n  const host = await firestore.collection('hosts').doc(hostId).get()\n  return host.exists ? String(host.get('orgId') ?? '') : ''\n}\n\nexport function createCrmRecordEmailStateWriter(deps: CrmRecordEmailStateDeps): PluginRecordEmailStateWriter {\n  return {\n    async stamp(request) {\n      const email = normalizeContactEmail(request.email)\n      const key = email ? personKey(email) : null\n      if (!email || !key) return NONE\n      const firestore = deps.firestore()\n      let orgId: string\n      try {\n        orgId = await resolveOrgId(firestore, request)\n      } catch (error) {\n        console.error('[crm] the site’s organization could not be read for an email state', request.hostId, error)\n        return NONE\n      }\n      if (!orgId) return NONE\n      const state: EmailState = {\n        status: request.state.status,\n        atMs: Number.isFinite(request.state.atMs) && request.state.atMs > 0 ? request.state.atMs : Date.now(),\n        source: request.state.source,\n        detail: request.state.detail\n          ? String(request.state.detail).replace(/\\s+/g, ' ').trim().slice(0, 500)\n          : null,\n        ...(request.state.enrollmentId ? { enrollmentId: request.state.enrollmentId } : {}),\n      }\n      const force = request.force === true\n      const withdraw = request.withdraw === true\n      let records = 0\n      try {\n        const contacts = firestore.collection('orgs').doc(orgId).collection('contacts')\n        const contact = await findContactByEmail(contacts, email)\n        if (contact && (await stampRecord(contact.ref, state, force, withdraw))) records += 1\n      } catch (error) {\n        console.error('[crm] the contact could not be stamped with an email state', orgId, error)\n      }\n      try {\n        /*\n         * ONE ORG ROW. A bounce or a do-not-contact mark is the platform's\n         * verdict on the ADDRESS, and since AGL-3277 there is one document\n         * carrying it — the per-site loop beside this had nothing left to\n         * find once AGL-3276 emptied the host path.\n         */\n        if (await stampRecord(\n          firestore.collection('orgs').doc(orgId).collection('leads').doc(key),\n          state,\n          force,\n          withdraw,\n        )) {\n          records += 1\n        }\n      } catch (error) {\n        console.error('[crm] the leads could not be stamped with an email state', orgId, error)\n      }\n      return { records }\n    },\n    async engaged(request) {\n      try {\n        const records = await recordContactEmailEngagement({\n          hostId: request.hostId,\n          events: request.events,\n          firestore: deps.firestore(),\n        })\n        return { records }\n      } catch (error) {\n        console.error('[crm] the contacts could not be stamped with an engagement', request.hostId, error)\n        return NONE\n      }\n    },\n    // A delivered campaign moves the New leads it reached to Nurturing (AGL-3446).\n    async reached(request) {\n      return { records: await nurtureReachedLeads(deps.firestore(), request) }\n    },\n  }\n}\n\n/** The platform's own dependencies. Specs build their own. */\nexport function defaultCrmRecordEmailStateDeps(): CrmRecordEmailStateDeps {\n  return { firestore: () => firebaseAdmin.app().firestore() }\n}\n\n/** Registers the CRM as the workspace's record system on the email-state seam. */\nexport function registerCrmRecordEmailStateWriter(\n  deps: CrmRecordEmailStateDeps = defaultCrmRecordEmailStateDeps(),\n): void {\n  registerPluginRecordEmailStateWriter(createCrmRecordEmailStateWriter(deps), { pluginId: BUNDLE_ID })\n}\n"],"names":["registerPluginRecordEmailStateWriter","CRM_EMAIL_STATUS_FIELD","CRM_EMAIL_STATUS_NONE","EMAIL_STATE_FIELD","nextEmailState","normalizeContactEmail","personKey","readEmailState","findContactByEmail","firebaseAdmin","FieldValue","BUNDLE_ID","recordContactEmailEngagement","nurtureReachedLeads","NONE","records","stampRecord","ref","incoming","force","withdraw","snapshot","get","exists","current","data","status","update","delete","source","next","atMs","detail","set","merge","resolveOrgId","firestore","request","host","named","String","orgId","trim","hostId","collection","doc","createCrmRecordEmailStateWriter","deps","stamp","email","key","error","console","state","Number","isFinite","Date","now","replace","slice","enrollmentId","contacts","contact","engaged","events","reached","defaultCrmRecordEmailStateDeps","app","registerCrmRecordEmailStateWriter","pluginId"],"mappings":"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"}

package/src/lib/server/record-facts.js

@@ -15,11 +15,12 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */ import { registerPluginRecordFactsReader } from "@aglyn/aglyn/plugin-manager/plugin-record-facts";
-import { CRM_COLLECTIONS, contactPrimaryGroup, crmReadTokens, isOrgWideMember } from "@aglyn/aglyn/server";
+import { CRM_COLLECTIONS, crmReadTokens, isOrgWideMember } from "@aglyn/aglyn/server";
 import { consentGroupForSite, firebaseAdmin, getOrgDoc, memberHasOrgPermission, readLeadForHost, resolveOrgIdForHost, resolveOrgMembership } from "@aglyn/tenant-data-admin";
 import { BUNDLE_ID } from "../constants/bundle-common.js";
 import { CRM_IMPORT_FACTS_RESOURCE, CRM_RECORD_FACTS_RESOURCES, companyFacts, contactFacts, dealFacts, importFacts, isCrmImportFactsCollection, leadFacts } from "../model/record-facts.js";
 import { crmSuiteRefusal } from "./suite-gate.js";
+import { contactPrimaryGroup } from "../model/contact-holder.js";
 /** The org collection a contact lives in, beside the CRM's own. */ const CONTACTS_COLLECTION = 'contacts';
 /** Logged activities read per record before visibility and the timeline cut. */ export const CRM_FACTS_ACTIVITIES_READ = 40;
 /** Tasks read per record, the record page's own window. */ export const CRM_FACTS_TASKS_READ = 50;