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

package/src/lib/hooks/use-crm-sharing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/hooks/use-crm-sharing.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'use client'\n\nimport { useUser } from '@aglyn/tenant-feature-instance'\nimport { useCallback, useEffect, useMemo, useState } from 'react'\nimport { type CrmSharingObject, type CrmSharingSite, readCrmSharingRules } from '../model/crm-sharing'\nimport { callCrmSharing, followUpCrmSharing } from '../model/crm-sharing-api'\nimport { crmTaskCallScope } from '../model/task-routes'\nimport { useCrmOrgMount } from './use-crm-org-mount'\nimport type { CrmOrgDoc } from './use-crm-scope'\n\nexport interface CrmSharingSites {\n  sites: CrmSharingSite[]\n  ready: boolean\n  /** How a site reads: its name, or a neutral phrase for one this reader cannot name. */\n  siteName: (hostId: string) => string\n}\n\n/**\n * The org's sites, for a sharing surface (AGL-3336).\n *\n * At the organization level the hub already holds them (`useCrmOrgMount`).\n * Under a site a member cannot list the org's other sites, so a MANAGER's\n * surface asks `crm/sharing` for them — the one reader a share is offered\n * to — and every other reader names them as \"another site\".\n */\nexport function useCrmSharingSites(input: {\n  hostId: string | null\n  orgId: string | null\n  enabled: boolean\n}): CrmSharingSites {\n  const { hostId, orgId, enabled } = input\n  const mount = useCrmOrgMount()\n  const { data: user } = useUser()\n  const [fetched, setFetched] = useState<{ key: string; sites: CrmSharingSite[] } | null>(null)\n  const scope = crmTaskCallScope(hostId, orgId)\n  const key = scope ? JSON.stringify(scope) : ''\n  const fromMount = mount && !hostId\n  useEffect(() => {\n    if (fromMount || !enabled || !scope || !user) return\n    let cancelled = false\n    callCrmSharing(user, scope, 'sites')\n      .then((answer) => {\n        if (!cancelled) setFetched({ key, sites: answer.sites ?? [] })\n      })\n      .catch(() => {\n        if (!cancelled) setFetched({ key, sites: [] })\n      })\n    return () => {\n      cancelled = true\n    }\n    // `scope` is keyed by `key`; the object itself is rebuilt every render.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [fromMount, enabled, key, user])\n  const sites = useMemo<CrmSharingSite[]>(\n    () =>\n      fromMount\n        ? mount.hosts.map((host) => ({ id: host.id, name: host.name }))\n        : fetched?.key === key\n          ? fetched.sites\n          : [],\n    [fromMount, mount, fetched, key],\n  )\n  const ready = fromMount ? mount.hostsReady : fetched?.key === key || !enabled\n  const siteName = useCallback(\n    (id: string) => sites.find((site) => site.id === id)?.name ?? (id === hostId ? 'This site' : 'another site'),\n    [sites, hostId],\n  )\n  return { sites, ready, siteName }\n}\n\n/** The org's sharing rules, off the org document the shell already passed. */\nexport function useCrmSharingRules(org: CrmOrgDoc) {\n  return useMemo(\n    () => readCrmSharingRules((org ?? null) as Record<string, unknown> | null),\n    [org],\n  )\n}\n\n\n/**\n * The follow-up a CLIENT-DIRECT write to a lead, a company or a deal owes\n * the org's sharing rules (AGL-3336): a server write is followed by the\n * core's record-written seam, a browser's by this. Fire-and-forget — the\n * save has landed whether or not a rule then shares the record.\n */\nexport function useCrmSharingFollowUp(\n  hostId: string | null | undefined,\n  orgId: string | null | undefined,\n): (object: CrmSharingObject, ids: readonly string[]) => void {\n  const { data: user } = useUser()\n  return useCallback(\n    (object: CrmSharingObject, ids: readonly string[]) => {\n      void followUpCrmSharing(user, crmTaskCallScope(hostId, orgId), object, ids)\n    },\n    [user, hostId, orgId],\n  )\n}\n"],"names":["useUser","useCallback","useEffect","useMemo","useState","readCrmSharingRules","callCrmSharing","followUpCrmSharing","crmTaskCallScope","useCrmOrgMount","useCrmSharingSites","input","hostId","orgId","enabled","mount","data","user","fetched","setFetched","scope","key","JSON","stringify","fromMount","cancelled","then","answer","sites","catch","hosts","map","host","id","name","ready","hostsReady","siteName","find","site","useCrmSharingRules","org","useCrmSharingFollowUp","object","ids"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAASA,OAAO,QAAQ,iCAAgC;AACxD,SAASC,WAAW,EAAEC,SAAS,EAAEC,OAAO,EAAEC,QAAQ,QAAQ,QAAO;AACjE,SAAqDC,mBAAmB,QAAQ,0BAAsB;AACtG,SAASC,cAAc,EAAEC,kBAAkB,QAAQ,8BAA0B;AAC7E,SAASC,gBAAgB,QAAQ,0BAAsB;AACvD,SAASC,cAAc,QAAQ,yBAAqB;AAUpD;;;;;;;CAOC,GACD,OAAO,SAASC,mBAAmBC,KAIlC;IACC,MAAM,EAAEC,MAAM,EAAEC,KAAK,EAAEC,OAAO,EAAE,GAAGH;IACnC,MAAMI,QAAQN;IACd,MAAM,EAAEO,MAAMC,IAAI,EAAE,GAAGjB;IACvB,MAAM,CAACkB,SAASC,WAAW,GAAGf,SAA0D;IACxF,MAAMgB,QAAQZ,iBAAiBI,QAAQC;IACvC,MAAMQ,MAAMD,QAAQE,KAAKC,SAAS,CAACH,SAAS;IAC5C,MAAMI,YAAYT,SAAS,CAACH;IAC5BV,UAAU;QACR,IAAIsB,aAAa,CAACV,WAAW,CAACM,SAAS,CAACH,MAAM;QAC9C,IAAIQ,YAAY;QAChBnB,eAAeW,MAAMG,OAAO,SACzBM,IAAI,CAAC,CAACC;gBACoCA;YAAzC,IAAI,CAACF,WAAWN,WAAW;gBAAEE;gBAAKO,KAAK,GAAED,gBAAAA,OAAOC,KAAK,YAAZD,gBAAgB,EAAE;YAAC;QAC9D,GACCE,KAAK,CAAC;YACL,IAAI,CAACJ,WAAWN,WAAW;gBAAEE;gBAAKO,OAAO,EAAE;YAAC;QAC9C;QACF,OAAO;YACLH,YAAY;QACd;IACA,wEAAwE;IACxE,uDAAuD;IACzD,GAAG;QAACD;QAAWV;QAASO;QAAKJ;KAAK;IAClC,MAAMW,QAAQzB,QACZ,IACEqB,YACIT,MAAMe,KAAK,CAACC,GAAG,CAAC,CAACC,OAAU,CAAA;gBAAEC,IAAID,KAAKC,EAAE;gBAAEC,MAAMF,KAAKE,IAAI;YAAC,CAAA,KAC1DhB,CAAAA,2BAAAA,QAASG,GAAG,MAAKA,MACfH,QAAQU,KAAK,GACb,EAAE,EACV;QAACJ;QAAWT;QAAOG;QAASG;KAAI;IAElC,MAAMc,QAAQX,YAAYT,MAAMqB,UAAU,GAAGlB,CAAAA,2BAAAA,QAASG,GAAG,MAAKA,OAAO,CAACP;IACtE,MAAMuB,WAAWpC,YACf,CAACgC;;YAAeL;wBAAAA,cAAAA,MAAMU,IAAI,CAAC,CAACC,OAASA,KAAKN,EAAE,KAAKA,wBAAjCL,YAAsCM,IAAI,mBAAKD,OAAOrB,SAAS,cAAc;OAC7F;QAACgB;QAAOhB;KAAO;IAEjB,OAAO;QAAEgB;QAAOO;QAAOE;IAAS;AAClC;AAEA,4EAA4E,GAC5E,OAAO,SAASG,mBAAmBC,GAAc;IAC/C,OAAOtC,QACL,IAAME,oBAAqBoC,cAAAA,MAAO,OAClC;QAACA;KAAI;AAET;AAGA;;;;;CAKC,GACD,OAAO,SAASC,sBACd9B,MAAiC,EACjCC,KAAgC;IAEhC,MAAM,EAAEG,MAAMC,IAAI,EAAE,GAAGjB;IACvB,OAAOC,YACL,CAAC0C,QAA0BC;QACzB,KAAKrC,mBAAmBU,MAAMT,iBAAiBI,QAAQC,QAAQ8B,QAAQC;IACzE,GACA;QAAC3B;QAAML;QAAQC;KAAM;AAEzB"}

package/src/lib/model/companies-csv.d.ts

@@ -28,7 +28,7 @@
  * because it is what a merchant reads the file for, and maps to "Do not
  * import" on the way back.
  */
-export { COMPANY_CSV_COLUMNS, companiesCsv, type CompanyCsvOptions, type CompanyCsvRow, } from '@aglyn/aglyn';
+export { COMPANY_CSV_COLUMNS, companiesCsv, type CompanyCsvOptions, type CompanyCsvRow, } from './crm-csv';
 /**
  * The file the Import drawer hands out to start from: the export's header
  * and nothing under it.

package/src/lib/model/companies-csv.js

@@ -26,8 +26,8 @@
  * column the import has no field for, the contacts count, is written last
  * because it is what a merchant reads the file for, and maps to "Do not
  * import" on the way back.
- */ /* The writer moved to `@aglyn/aglyn` under AGL-2662 — see `deals-csv.ts`. */ export { COMPANY_CSV_COLUMNS, companiesCsv } from "@aglyn/aglyn";
-import { companiesCsv } from "@aglyn/aglyn";
+ */ /* The writer is `crm-csv.ts`, shared with the server's export — see `deals-csv.ts`. */ export { COMPANY_CSV_COLUMNS, companiesCsv } from "./crm-csv.js";
+import { companiesCsv } from "./crm-csv.js";
 /**
  * The file the Import drawer hands out to start from: the export's header
  * and nothing under it.

package/src/lib/model/companies-csv.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/companies-csv.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The companies CSV — one file from the table's Export button and the bulk\n * bar's (AGL-2621).\n *\n * The same rule the contacts file follows: the header is the companies\n * IMPORT's own vocabulary — the first alias of every field\n * `guessCompanyImportMapping` reads — so an export re-imports without a\n * hand mapping, and the template the Import drawer hands out IS this header\n * over no rows. The owner is written by ADDRESS, because the import resolves\n * an owner by email and a uid is nothing a spreadsheet can read. The one\n * column the import has no field for, the contacts count, is written last\n * because it is what a merchant reads the file for, and maps to \"Do not\n * import\" on the way back.\n */\n\n/* The writer moved to `@aglyn/aglyn` under AGL-2662 — see `deals-csv.ts`. */\nexport {\n  COMPANY_CSV_COLUMNS,\n  companiesCsv,\n  type CompanyCsvOptions,\n  type CompanyCsvRow,\n} from '@aglyn/aglyn'\n\nimport { companiesCsv } from '@aglyn/aglyn'\n\n/**\n * The file the Import drawer hands out to start from: the export's header\n * and nothing under it.\n */\nexport function companyImportTemplateCsv(): string {\n  return companiesCsv([])\n}\n"],"names":["COMPANY_CSV_COLUMNS","companiesCsv","companyImportTemplateCsv"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;CAaC,GAED,2EAA2E,GAC3E,SACEA,mBAAmB,EACnBC,YAAY,QAGP,eAAc;AAErB,SAASA,YAAY,QAAQ,eAAc;AAE3C;;;CAGC,GACD,OAAO,SAASC;IACd,OAAOD,aAAa,EAAE;AACxB"}
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/companies-csv.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The companies CSV — one file from the table's Export button and the bulk\n * bar's (AGL-2621).\n *\n * The same rule the contacts file follows: the header is the companies\n * IMPORT's own vocabulary — the first alias of every field\n * `guessCompanyImportMapping` reads — so an export re-imports without a\n * hand mapping, and the template the Import drawer hands out IS this header\n * over no rows. The owner is written by ADDRESS, because the import resolves\n * an owner by email and a uid is nothing a spreadsheet can read. The one\n * column the import has no field for, the contacts count, is written last\n * because it is what a merchant reads the file for, and maps to \"Do not\n * import\" on the way back.\n */\n\n/* The writer is `crm-csv.ts`, shared with the server's export — see `deals-csv.ts`. */\nexport {\n  COMPANY_CSV_COLUMNS,\n  companiesCsv,\n  type CompanyCsvOptions,\n  type CompanyCsvRow,\n} from './crm-csv'\n\nimport { companiesCsv } from './crm-csv'\n\n/**\n * The file the Import drawer hands out to start from: the export's header\n * and nothing under it.\n */\nexport function companyImportTemplateCsv(): string {\n  return companiesCsv([])\n}\n"],"names":["COMPANY_CSV_COLUMNS","companiesCsv","companyImportTemplateCsv"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;CAaC,GAED,qFAAqF,GACrF,SACEA,mBAAmB,EACnBC,YAAY,QAGP,eAAW;AAElB,SAASA,YAAY,QAAQ,eAAW;AAExC;;;CAGC,GACD,OAAO,SAASC;IACd,OAAOD,aAAa,EAAE;AACxB"}

package/src/lib/model/contact-holder.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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 ConsentGroup } from '@aglyn/aglyn/app-utils/consent-groups';
+/**
+ * The holder of nothing: the group a contact is flattened through when no
+ * site has captured it and no facet exists — a row written by a path that
+ * predates attribution, read at the org level (AGL-2630).
+ *
+ * An empty `groupId` reads an empty facet (`readContactFacet` answers the
+ * empty facet for a key the map lacks) and REFUSES a write
+ * (`contactFacetPath` throws on an empty holder), which is the right pair:
+ * the row still shows its shared identity, and nothing edits a facet
+ * nobody holds. Exported so a surface can test for it rather than for an
+ * empty string.
+ */
+export declare const NO_HOLDER_GROUP: ConsentGroup;
+/**
+ * The group a LEAD is read and acted on through (AGL-3278).
+ *
+ * The same question {@link contactPrimaryGroup} answers, with a shorter
+ * answer: a lead is one flat document — no facets, one profile, one
+ * status — so there is nothing to choose between and the holder is simply
+ * the site that captured the person first. What it is FOR is the same: at
+ * the organization level the record page has no viewing site, and it needs
+ * one to read the consent basis against, to file an activity under, to
+ * offer a booking on and to convert as.
+ *
+ * A lead no site has captured — a row imported before attribution — reads
+ * through {@link NO_HOLDER_GROUP}, whose empty `hostId` is how a surface
+ * asks "is there a site here at all" without testing for an empty string.
+ */
+export declare function leadPrimaryGroup(lead: Record<string, unknown> | null | undefined, org: Record<string, unknown> | null | undefined): ConsentGroup;
+/**
+ * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).
+ *
+ * Under a site there is one answer for every row — the site's own group,
+ * `consentGroupForHost` — and the reader never asks this. At the
+ * organization level there is no viewing site, and a contact captured by
+ * three sites has up to three facets; the org-wide member reading them all
+ * needs ONE to show the row's profile, owner and stage under, and to write
+ * an edit back to. This picks the person's PRIMARY holder: the first
+ * capturing site, in capture order, whose group actually holds a facet;
+ * then any facet at all, resolved back to its declared group or to the
+ * site whose id it is keyed by; then the first capturing site even with no
+ * facet yet (the facet is written on the first edit). A row nobody captured
+ * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.
+ *
+ * Capture order rather than sorted order, deliberately: `capturedByHostIds`
+ * is maintained by `arrayUnion`, so its first entry is the site that met
+ * the person first, and that site's profile is the one a person reading
+ * across brands would expect to see. `contactCaptureHostIds` sorts the same
+ * array for RENDERING, where a stable order matters more than a first.
+ */
+export declare function contactPrimaryGroup(row: Record<string, unknown> | null | undefined, org: Record<string, unknown> | null | undefined): ConsentGroup;

package/src/lib/model/contact-holder.js

@@ -0,0 +1,129 @@
+/**
+ * @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.
+ */ /**
+ * WHICH HOLDER A CROSS-SITE READER SEES A CONTACT THROUGH (AGL-2630).
+ *
+ * A contact document carries one facet per holder, and every field but the
+ * shared identity lives in one of them. A surface standing on a site reads
+ * that site's group; a surface standing at the organization — the org-level
+ * Contacts list, and the whole-collection export that writes the same file
+ * — has no site to read as and needs one answer per row.
+ *
+ * In the library rather than in the CRM plugin because both of those
+ * readers need it and one of them is an app: an app may not import a
+ * feature plugin (AGL-2662).
+ */ import { CONTACT_FACETS_FIELD } from "@aglyn/aglyn/app-utils/contacts";
+import { CAPTURED_BY_HOST_FIELD } from "@aglyn/aglyn/app-utils/marketing-consent";
+import { consentGroupForHost, consentGroupsAwaitConfirmation, readConsentGroups, soloConsentGroup } from "@aglyn/aglyn/app-utils/consent-groups";
+/**
+ * The holder of nothing: the group a contact is flattened through when no
+ * site has captured it and no facet exists — a row written by a path that
+ * predates attribution, read at the org level (AGL-2630).
+ *
+ * An empty `groupId` reads an empty facet (`readContactFacet` answers the
+ * empty facet for a key the map lacks) and REFUSES a write
+ * (`contactFacetPath` throws on an empty holder), which is the right pair:
+ * the row still shows its shared identity, and nothing edits a facet
+ * nobody holds. Exported so a surface can test for it rather than for an
+ * empty string.
+ */ export const NO_HOLDER_GROUP = Object.freeze({
+    hostId: '',
+    groupId: '',
+    name: null,
+    hostIds: [],
+    declared: false,
+    awaitsConfirmation: false
+});
+/**
+ * The sites that captured this person, in CAPTURE order — the order
+ * `arrayUnion` left, so the first entry is the site that met them first.
+ *
+ * `contactCaptureHostIds` sorts the same array for RENDERING, where a
+ * stable order matters more than a first. Both readers below want the
+ * first, so neither may use the sorted one.
+ */ function captureOrder(record) {
+    const raw = (record != null ? record : {})[CAPTURED_BY_HOST_FIELD];
+    if (!Array.isArray(raw)) return [];
+    return raw.map((id)=>String(id != null ? id : '').trim()).filter(Boolean);
+}
+/**
+ * The group a LEAD is read and acted on through (AGL-3278).
+ *
+ * The same question {@link contactPrimaryGroup} answers, with a shorter
+ * answer: a lead is one flat document — no facets, one profile, one
+ * status — so there is nothing to choose between and the holder is simply
+ * the site that captured the person first. What it is FOR is the same: at
+ * the organization level the record page has no viewing site, and it needs
+ * one to read the consent basis against, to file an activity under, to
+ * offer a booking on and to convert as.
+ *
+ * A lead no site has captured — a row imported before attribution — reads
+ * through {@link NO_HOLDER_GROUP}, whose empty `hostId` is how a surface
+ * asks "is there a site here at all" without testing for an empty string.
+ */ export function leadPrimaryGroup(lead, org) {
+    const captured = captureOrder(lead);
+    return captured.length ? consentGroupForHost(org, captured[0]) : NO_HOLDER_GROUP;
+}
+/**
+ * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).
+ *
+ * Under a site there is one answer for every row — the site's own group,
+ * `consentGroupForHost` — and the reader never asks this. At the
+ * organization level there is no viewing site, and a contact captured by
+ * three sites has up to three facets; the org-wide member reading them all
+ * needs ONE to show the row's profile, owner and stage under, and to write
+ * an edit back to. This picks the person's PRIMARY holder: the first
+ * capturing site, in capture order, whose group actually holds a facet;
+ * then any facet at all, resolved back to its declared group or to the
+ * site whose id it is keyed by; then the first capturing site even with no
+ * facet yet (the facet is written on the first edit). A row nobody captured
+ * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.
+ *
+ * Capture order rather than sorted order, deliberately: `capturedByHostIds`
+ * is maintained by `arrayUnion`, so its first entry is the site that met
+ * the person first, and that site's profile is the one a person reading
+ * across brands would expect to see. `contactCaptureHostIds` sorts the same
+ * array for RENDERING, where a stable order matters more than a first.
+ */ export function contactPrimaryGroup(row, org) {
+    const record = row != null ? row : {};
+    const facets = record[CONTACT_FACETS_FIELD];
+    const facetKeys = facets && typeof facets === 'object' && !Array.isArray(facets) ? Object.keys(facets) : [];
+    const captured = captureOrder(record);
+    for (const hostId of captured){
+        const group = consentGroupForHost(org, hostId);
+        if (facetKeys.includes(group.groupId)) return group;
+    }
+    for (const key of facetKeys){
+        const declared = readConsentGroups(org)[key];
+        if (declared) {
+            return {
+                hostId: declared.hostIds[0],
+                groupId: key,
+                name: declared.name,
+                hostIds: [
+                    ...declared.hostIds
+                ],
+                declared: true,
+                awaitsConfirmation: consentGroupsAwaitConfirmation(org)
+            };
+        }
+        return soloConsentGroup(key);
+    }
+    if (captured.length) return consentGroupForHost(org, captured[0]);
+    return NO_HOLDER_GROUP;
+}
+
+//# sourceMappingURL=contact-holder.js.map

package/src/lib/model/contact-holder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/contact-holder.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 * WHICH HOLDER A CROSS-SITE READER SEES A CONTACT THROUGH (AGL-2630).\n *\n * A contact document carries one facet per holder, and every field but the\n * shared identity lives in one of them. A surface standing on a site reads\n * that site's group; a surface standing at the organization — the org-level\n * Contacts list, and the whole-collection export that writes the same file\n * — has no site to read as and needs one answer per row.\n *\n * In the library rather than in the CRM plugin because both of those\n * readers need it and one of them is an app: an app may not import a\n * feature plugin (AGL-2662).\n */\n\nimport { CONTACT_FACETS_FIELD } from '@aglyn/aglyn/app-utils/contacts'\nimport { CAPTURED_BY_HOST_FIELD } from '@aglyn/aglyn/app-utils/marketing-consent'\nimport {\n  type ConsentGroup,\n  consentGroupForHost,\n  consentGroupsAwaitConfirmation,\n  readConsentGroups,\n  soloConsentGroup,\n} from '@aglyn/aglyn/app-utils/consent-groups'\n\n/**\n * The holder of nothing: the group a contact is flattened through when no\n * site has captured it and no facet exists — a row written by a path that\n * predates attribution, read at the org level (AGL-2630).\n *\n * An empty `groupId` reads an empty facet (`readContactFacet` answers the\n * empty facet for a key the map lacks) and REFUSES a write\n * (`contactFacetPath` throws on an empty holder), which is the right pair:\n * the row still shows its shared identity, and nothing edits a facet\n * nobody holds. Exported so a surface can test for it rather than for an\n * empty string.\n */\nexport const NO_HOLDER_GROUP: ConsentGroup = Object.freeze({\n  hostId: '',\n  groupId: '',\n  name: null,\n  hostIds: [],\n  declared: false,\n  awaitsConfirmation: false,\n}) as ConsentGroup\n\n/**\n * The sites that captured this person, in CAPTURE order — the order\n * `arrayUnion` left, so the first entry is the site that met them first.\n *\n * `contactCaptureHostIds` sorts the same array for RENDERING, where a\n * stable order matters more than a first. Both readers below want the\n * first, so neither may use the sorted one.\n */\nfunction captureOrder(\n  record: Record<string, unknown> | null | undefined,\n): string[] {\n  const raw = (record ?? {})[CAPTURED_BY_HOST_FIELD]\n  if (!Array.isArray(raw)) return []\n  return raw.map((id) => String(id ?? '').trim()).filter(Boolean)\n}\n\n/**\n * The group a LEAD is read and acted on through (AGL-3278).\n *\n * The same question {@link contactPrimaryGroup} answers, with a shorter\n * answer: a lead is one flat document — no facets, one profile, one\n * status — so there is nothing to choose between and the holder is simply\n * the site that captured the person first. What it is FOR is the same: at\n * the organization level the record page has no viewing site, and it needs\n * one to read the consent basis against, to file an activity under, to\n * offer a booking on and to convert as.\n *\n * A lead no site has captured — a row imported before attribution — reads\n * through {@link NO_HOLDER_GROUP}, whose empty `hostId` is how a surface\n * asks \"is there a site here at all\" without testing for an empty string.\n */\nexport function leadPrimaryGroup(\n  lead: Record<string, unknown> | null | undefined,\n  org: Record<string, unknown> | null | undefined,\n): ConsentGroup {\n  const captured = captureOrder(lead)\n  return captured.length ? consentGroupForHost(org, captured[0]) : NO_HOLDER_GROUP\n}\n\n/**\n * The group a CROSS-HOLDER reader flattens one contact through (AGL-2630).\n *\n * Under a site there is one answer for every row — the site's own group,\n * `consentGroupForHost` — and the reader never asks this. At the\n * organization level there is no viewing site, and a contact captured by\n * three sites has up to three facets; the org-wide member reading them all\n * needs ONE to show the row's profile, owner and stage under, and to write\n * an edit back to. This picks the person's PRIMARY holder: the first\n * capturing site, in capture order, whose group actually holds a facet;\n * then any facet at all, resolved back to its declared group or to the\n * site whose id it is keyed by; then the first capturing site even with no\n * facet yet (the facet is written on the first edit). A row nobody captured\n * and nobody wrote a facet for reads through {@link NO_HOLDER_GROUP}.\n *\n * Capture order rather than sorted order, deliberately: `capturedByHostIds`\n * is maintained by `arrayUnion`, so its first entry is the site that met\n * the person first, and that site's profile is the one a person reading\n * across brands would expect to see. `contactCaptureHostIds` sorts the same\n * array for RENDERING, where a stable order matters more than a first.\n */\nexport function contactPrimaryGroup(\n  row: Record<string, unknown> | null | undefined,\n  org: Record<string, unknown> | null | undefined,\n): ConsentGroup {\n  const record = row ?? {}\n  const facets = record[CONTACT_FACETS_FIELD]\n  const facetKeys =\n    facets && typeof facets === 'object' && !Array.isArray(facets)\n      ? Object.keys(facets as Record<string, unknown>)\n      : []\n  const captured = captureOrder(record)\n  for (const hostId of captured) {\n    const group = consentGroupForHost(org, hostId)\n    if (facetKeys.includes(group.groupId)) return group\n  }\n  for (const key of facetKeys) {\n    const declared = readConsentGroups(org)[key]\n    if (declared) {\n      return {\n        hostId: declared.hostIds[0],\n        groupId: key,\n        name: declared.name,\n        hostIds: [...declared.hostIds],\n        declared: true,\n        awaitsConfirmation: consentGroupsAwaitConfirmation(org),\n      }\n    }\n    return soloConsentGroup(key)\n  }\n  if (captured.length) return consentGroupForHost(org, captured[0])\n  return NO_HOLDER_GROUP\n}"],"names":["CONTACT_FACETS_FIELD","CAPTURED_BY_HOST_FIELD","consentGroupForHost","consentGroupsAwaitConfirmation","readConsentGroups","soloConsentGroup","NO_HOLDER_GROUP","Object","freeze","hostId","groupId","name","hostIds","declared","awaitsConfirmation","captureOrder","record","raw","Array","isArray","map","id","String","trim","filter","Boolean","leadPrimaryGroup","lead","org","captured","length","contactPrimaryGroup","row","facets","facetKeys","keys","group","includes","key"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;CAYC,GAED,SAASA,oBAAoB,QAAQ,kCAAiC;AACtE,SAASC,sBAAsB,QAAQ,2CAA0C;AACjF,SAEEC,mBAAmB,EACnBC,8BAA8B,EAC9BC,iBAAiB,EACjBC,gBAAgB,QACX,wCAAuC;AAE9C;;;;;;;;;;;CAWC,GACD,OAAO,MAAMC,kBAAgCC,OAAOC,MAAM,CAAC;IACzDC,QAAQ;IACRC,SAAS;IACTC,MAAM;IACNC,SAAS,EAAE;IACXC,UAAU;IACVC,oBAAoB;AACtB,GAAkB;AAElB;;;;;;;CAOC,GACD,SAASC,aACPC,MAAkD;IAElD,MAAMC,MAAM,CAACD,iBAAAA,SAAU,CAAC,EAAE,CAACf,uBAAuB;IAClD,IAAI,CAACiB,MAAMC,OAAO,CAACF,MAAM,OAAO,EAAE;IAClC,OAAOA,IAAIG,GAAG,CAAC,CAACC,KAAOC,OAAOD,aAAAA,KAAM,IAAIE,IAAI,IAAIC,MAAM,CAACC;AACzD;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,iBACdC,IAAgD,EAChDC,GAA+C;IAE/C,MAAMC,WAAWd,aAAaY;IAC9B,OAAOE,SAASC,MAAM,GAAG5B,oBAAoB0B,KAAKC,QAAQ,CAAC,EAAE,IAAIvB;AACnE;AAEA;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASyB,oBACdC,GAA+C,EAC/CJ,GAA+C;IAE/C,MAAMZ,SAASgB,cAAAA,MAAO,CAAC;IACvB,MAAMC,SAASjB,MAAM,CAAChB,qBAAqB;IAC3C,MAAMkC,YACJD,UAAU,OAAOA,WAAW,YAAY,CAACf,MAAMC,OAAO,CAACc,UACnD1B,OAAO4B,IAAI,CAACF,UACZ,EAAE;IACR,MAAMJ,WAAWd,aAAaC;IAC9B,KAAK,MAAMP,UAAUoB,SAAU;QAC7B,MAAMO,QAAQlC,oBAAoB0B,KAAKnB;QACvC,IAAIyB,UAAUG,QAAQ,CAACD,MAAM1B,OAAO,GAAG,OAAO0B;IAChD;IACA,KAAK,MAAME,OAAOJ,UAAW;QAC3B,MAAMrB,WAAWT,kBAAkBwB,IAAI,CAACU,IAAI;QAC5C,IAAIzB,UAAU;YACZ,OAAO;gBACLJ,QAAQI,SAASD,OAAO,CAAC,EAAE;gBAC3BF,SAAS4B;gBACT3B,MAAME,SAASF,IAAI;gBACnBC,SAAS;uBAAIC,SAASD,OAAO;iBAAC;gBAC9BC,UAAU;gBACVC,oBAAoBX,+BAA+ByB;YACrD;QACF;QACA,OAAOvB,iBAAiBiC;IAC1B;IACA,IAAIT,SAASC,MAAM,EAAE,OAAO5B,oBAAoB0B,KAAKC,QAAQ,CAAC,EAAE;IAChE,OAAOvB;AACT"}

package/src/lib/model/contact-interaction-links.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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 { ContactInteraction, ContactSource } from '@aglyn/aglyn';
+import { type PluginRecordRouteContext } from '@aglyn/aglyn/plugin-manager/plugin-record-routes';
+/**
+ * Where a contact's captured history points back at (AGL-2622): the record
+ * each capture door left, where the console reads it.
+ *
+ * The submission, the order and the booking are other plugins' records, so
+ * their addresses are the ones those plugins publish on the record-route seam
+ * (`formSubmission`, `order`, `booking` — AGL-3080), and an entry whose owner
+ * is not loaded carries no link. A member sign-up lands on the platform's own
+ * Users page.
+ */
+/**
+ * What the link on a captured timeline entry says. Only the doors that
+ * leave a record the console can open are named; a newsletter opt-in, an
+ * API create, an import or a by-hand add leave nothing to open, so they
+ * carry no link and no label.
+ */
+export declare const INTERACTION_LINK_LABELS: Partial<Record<ContactSource, string>>;
+/**
+ * The console page a captured interaction points back at, or `null` when
+ * the door left nothing to open, or its owner publishes no address here.
+ *
+ * A submission and an order are addressed by the `refId` the capture door
+ * stamped — `formSubmissions/{id}`, `orders/{id}` — and an interaction that
+ * predates the stamp lands on nothing rather than on a list that would read
+ * as "the record is gone". A booking and a member sign-up land on their
+ * pages, which list them; neither page addresses one row.
+ */
+export declare function contactInteractionHref(interaction: Pick<ContactInteraction, 'type' | 'refId'>, context: PluginRecordRouteContext): string | null;

package/src/lib/model/contact-interaction-links.js

@@ -0,0 +1,65 @@
+/**
+ * @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 { buildRoute, Route } from "@aglyn/aglyn/app-utils/console-routes";
+import { pluginRecordHref, pluginRecordListHref } from "@aglyn/aglyn/plugin-manager/plugin-record-routes";
+/**
+ * Where a contact's captured history points back at (AGL-2622): the record
+ * each capture door left, where the console reads it.
+ *
+ * The submission, the order and the booking are other plugins' records, so
+ * their addresses are the ones those plugins publish on the record-route seam
+ * (`formSubmission`, `order`, `booking` — AGL-3080), and an entry whose owner
+ * is not loaded carries no link. A member sign-up lands on the platform's own
+ * Users page.
+ */ /**
+ * What the link on a captured timeline entry says. Only the doors that
+ * leave a record the console can open are named; a newsletter opt-in, an
+ * API create, an import or a by-hand add leave nothing to open, so they
+ * carry no link and no label.
+ */ export const INTERACTION_LINK_LABELS = {
+    form: 'Open submission',
+    order: 'Open order',
+    booking: 'Open bookings',
+    member: 'Open site users'
+};
+/**
+ * The console page a captured interaction points back at, or `null` when
+ * the door left nothing to open, or its owner publishes no address here.
+ *
+ * A submission and an order are addressed by the `refId` the capture door
+ * stamped — `formSubmissions/{id}`, `orders/{id}` — and an interaction that
+ * predates the stamp lands on nothing rather than on a list that would read
+ * as "the record is gone". A booking and a member sign-up land on their
+ * pages, which list them; neither page addresses one row.
+ */ export function contactInteractionHref(interaction, context) {
+    switch(interaction.type){
+        case 'form':
+            return interaction.refId ? pluginRecordHref('formSubmission', context, interaction.refId) : null;
+        case 'order':
+            return interaction.refId ? pluginRecordHref('order', context, interaction.refId) : null;
+        case 'booking':
+            return pluginRecordListHref('booking', context);
+        case 'member':
+            return context.host ? buildRoute(Route.HOST_USERS, {
+                orgSlug: context.orgSlug,
+                host: context.host
+            }) : null;
+        default:
+            return null;
+    }
+}
+
+//# sourceMappingURL=contact-interaction-links.js.map

package/src/lib/model/contact-interaction-links.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/model/contact-interaction-links.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 { ContactInteraction, ContactSource } from '@aglyn/aglyn'\nimport { buildRoute, Route } from '@aglyn/aglyn/app-utils/console-routes'\nimport {\n  pluginRecordHref,\n  pluginRecordListHref,\n  type PluginRecordRouteContext,\n} from '@aglyn/aglyn/plugin-manager/plugin-record-routes'\n\n/**\n * Where a contact's captured history points back at (AGL-2622): the record\n * each capture door left, where the console reads it.\n *\n * The submission, the order and the booking are other plugins' records, so\n * their addresses are the ones those plugins publish on the record-route seam\n * (`formSubmission`, `order`, `booking` — AGL-3080), and an entry whose owner\n * is not loaded carries no link. A member sign-up lands on the platform's own\n * Users page.\n */\n\n/**\n * What the link on a captured timeline entry says. Only the doors that\n * leave a record the console can open are named; a newsletter opt-in, an\n * API create, an import or a by-hand add leave nothing to open, so they\n * carry no link and no label.\n */\nexport const INTERACTION_LINK_LABELS: Partial<Record<ContactSource, string>> = {\n  form: 'Open submission',\n  order: 'Open order',\n  booking: 'Open bookings',\n  member: 'Open site users',\n}\n\n/**\n * The console page a captured interaction points back at, or `null` when\n * the door left nothing to open, or its owner publishes no address here.\n *\n * A submission and an order are addressed by the `refId` the capture door\n * stamped — `formSubmissions/{id}`, `orders/{id}` — and an interaction that\n * predates the stamp lands on nothing rather than on a list that would read\n * as \"the record is gone\". A booking and a member sign-up land on their\n * pages, which list them; neither page addresses one row.\n */\nexport function contactInteractionHref(\n  interaction: Pick<ContactInteraction, 'type' | 'refId'>,\n  context: PluginRecordRouteContext,\n): string | null {\n  switch (interaction.type) {\n    case 'form':\n      return interaction.refId ? pluginRecordHref('formSubmission', context, interaction.refId) : null\n    case 'order':\n      return interaction.refId ? pluginRecordHref('order', context, interaction.refId) : null\n    case 'booking':\n      return pluginRecordListHref('booking', context)\n    case 'member':\n      return context.host\n        ? buildRoute(Route.HOST_USERS, { orgSlug: context.orgSlug, host: context.host })\n        : null\n    default:\n      return null\n  }\n}\n"],"names":["buildRoute","Route","pluginRecordHref","pluginRecordListHref","INTERACTION_LINK_LABELS","form","order","booking","member","contactInteractionHref","interaction","context","type","refId","host","HOST_USERS","orgSlug"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAGD,SAASA,UAAU,EAAEC,KAAK,QAAQ,wCAAuC;AACzE,SACEC,gBAAgB,EAChBC,oBAAoB,QAEf,mDAAkD;AAEzD;;;;;;;;;CASC,GAED;;;;;CAKC,GACD,OAAO,MAAMC,0BAAkE;IAC7EC,MAAM;IACNC,OAAO;IACPC,SAAS;IACTC,QAAQ;AACV,EAAC;AAED;;;;;;;;;CASC,GACD,OAAO,SAASC,uBACdC,WAAuD,EACvDC,OAAiC;IAEjC,OAAQD,YAAYE,IAAI;QACtB,KAAK;YACH,OAAOF,YAAYG,KAAK,GAAGX,iBAAiB,kBAAkBS,SAASD,YAAYG,KAAK,IAAI;QAC9F,KAAK;YACH,OAAOH,YAAYG,KAAK,GAAGX,iBAAiB,SAASS,SAASD,YAAYG,KAAK,IAAI;QACrF,KAAK;YACH,OAAOV,qBAAqB,WAAWQ;QACzC,KAAK;YACH,OAAOA,QAAQG,IAAI,GACfd,WAAWC,MAAMc,UAAU,EAAE;gBAAEC,SAASL,QAAQK,OAAO;gBAAEF,MAAMH,QAAQG,IAAI;YAAC,KAC5E;QACN;YACE,OAAO;IACX;AACF"}

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

@@ -0,0 +1,136 @@
+/**
+ * @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 CONTACT DOCUMENTS INTO ONE (AGL-2625) — the pure half.
+ *
+ * Contacts are keyed by email, so exact duplicates cannot exist; one human
+ * with `jane@acme.com` and `jane@gmail.com` is two documents, with tags,
+ * deals, tasks and a timeline split between them. A merge folds the second
+ * into the first: the SURVIVOR keeps its address as the identity, the MERGED
+ * record's address becomes an alternate on it, and every field is combined
+ * by one rule the dialog can show before the write happens.
+ *
+ * ## The rule
+ *
+ *  - A scalar — a name, a phone, a title, a stage, an owner — is the
+ *    survivor's where the survivor has one, and fills from the merged record
+ *    where the survivor is empty. Nothing the survivor holds is overwritten.
+ *  - A list — tags, campaign filings, the timeline, the sites that captured
+ *    the person, the forms, the companies — is the UNION, deduplicated and
+ *    bounded where the write paths bound it.
+ *  - A figure that counts something — orders, lifetime value, refunds — is
+ *    the SUM: two records of one person's purchases are one person's
+ *    purchases. A "first" is the earlier, a "last" is the later.
+ *  - Notes are appended, survivor first: a note is a list of sentences, and
+ *    dropping the merged record's would be the one silent loss in a merge
+ *    that is otherwise lossless.
+ *  - A recorded REFUSAL of marketing mail on either record stands on the
+ *    survivor. The merge asserts the two are one person, and that person
+ *    said no.
+ *
+ * Applied per holder: each group's facet on the merged record is folded
+ * into the same group's facet on the survivor, and a group only the merged
+ * record had comes across whole. No holder's records reach another holder's
+ * facet, which is the guarantee the facet shape exists for.
+ *
+ * ## Why this is a plan and not a write
+ *
+ * The console shows the two records side by side and says which value wins
+ * before anything is committed; the server performs the write. Both read
+ * this function, so the preview cannot show one outcome and the write land
+ * another. The plan is plain values — no sentinels — so it can be rendered,
+ * and it is shaped for a merge-`set`, which deep-merges the facet map one
+ * holder at a time and replaces an array whole: exactly the two behaviors
+ * the rule above needs.
+ */
+import { type ContactInteraction } from '@aglyn/aglyn/app-utils/contacts';
+export interface ContactMergePlan {
+    /**
+     * What the survivor becomes, as a merge-`set` payload: every derived
+     * field with its full value, and only the groups the merged record held
+     * under `facets`. Plain values throughout — the writer adds its own
+     * `updatedAt`.
+     */
+    survivor: Record<string, unknown>;
+    /** Every address the survivor answers to afterwards, primary first. */
+    emails: string[];
+    /** The merged record's addresses — what its leads and index entries are keyed by. */
+    mergedEmails: string[];
+    /**
+     * The companies that lose a contact: those BOTH records were filed under,
+     * which counted two people and now count one. A company only one record
+     * named keeps its count — the survivor still names it.
+     */
+    companyCounts: Array<{
+        companyId: string;
+        delta: -1;
+    }>;
+    /** The union of both records' scope tokens — who may read the survivor. */
+    visibleTo: string[];
+}
+type Doc = Record<string, unknown>;
+/**
+ * Both timelines as one: deduplicated by event, newest first, and capped
+ * the way every capture caps it — so a merge of two full timelines keeps
+ * the fifty most recent visits rather than growing the document past what
+ * a capture may write.
+ */
+export declare function mergeInteractions(survivor: readonly ContactInteraction[] | undefined, merged: readonly ContactInteraction[] | undefined): ContactInteraction[];
+/**
+ * One holder's facet after the merge.
+ *
+ * `survivor` is that holder's facet on the surviving record — possibly
+ * absent, when only the merged record was held by this group — and `merged`
+ * the same holder's facet on the record being folded in.
+ */
+export declare function mergeContactFacet(survivor: Doc | undefined, merged: Doc | undefined): Doc;
+/**
+ * The plan for folding `merged` into `survivor`.
+ *
+ * Both are the stored documents as read. The survivor's `email` is the
+ * identity that stands; the merged record's becomes an alternate.
+ */
+export declare function planContactMerge(survivor: Doc, merged: Doc): ContactMergePlan;
+/** Where a previewed value comes from. */
+export type ContactMergeSource = 'survivor' | 'merged' | 'both' | 'none';
+/** One line of the side-by-side the dialog shows. */
+export interface ContactMergePreviewRow {
+    key: string;
+    label: string;
+    /** The surviving record's value, as text. */
+    survivor: string;
+    /** The merged record's value, as text. */
+    merged: string;
+    /** What the survivor carries afterwards. */
+    result: string;
+    from: ContactMergeSource;
+}
+export interface ContactMergePreviewOptions {
+    /** The owner's display name for a uid; the uid itself when absent. */
+    memberName?: (uid: string) => string;
+}
+/**
+ * The merge as the viewing group would see it, field by field.
+ *
+ * Reads through ONE group's facet, the way the record page does, so a
+ * holder previewing a merge sees its own values and never another holder's.
+ * Every row carries the survivor's value, the merged record's, and the
+ * result the plan would write, so the dialog is a rendering and not a second
+ * opinion.
+ */
+export declare function contactMergePreview(survivor: Doc, merged: Doc, groupId: string, options?: ContactMergePreviewOptions): ContactMergePreviewRow[];
+export {};