@aglyn/plugins-crm 1.0.0-beta.221 → 1.0.0-beta.222

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

@@ -16,12 +16,15 @@
  */ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { CONTACT_SOURCE_LABELS } from "@aglyn/aglyn/app-utils/contacts";
 import { formLeadSource } from "@aglyn/aglyn/app-utils/forms";
+import { normalizePhone } from "@aglyn/aglyn/foundation/definitions/contact.types";
 import { isCrmLeadOpen, normalizeContactEmail, personKey } from "@aglyn/aglyn/server";
-import { captureHostContact } from "@aglyn/tenant-runtime/capture-host-contact";
+import { captureHostContact } from "./capture-host-contact.js";
 import { contactCaptureActor } from "@aglyn/tenant-runtime/capture-actor";
 import { emitHostEvent } from "@aglyn/tenant-runtime/emit-host-event";
 import { addHostLeadOutcome, findContactByEmail, firebaseAdmin, orgDataCollectionForHost, readLeadForHost } from "@aglyn/tenant-data-admin";
+import { CONVERSION_TOUCH_DETAIL } from "@aglyn/aglyn/plugin-manager/plugin-conversion-credit";
 import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
+import { crmRecordOriginWriter } from "./record-origin.js";
 /**
  * The CRM answering the platform's contact-capture contract (AGL-3080).
  *
@@ -78,11 +81,12 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
     if (!normalizeContactEmail(request.identity.email)) return refusedEmail();
     try {
         if (surface === 'lead') {
-            if (!await heldAsContact(request)) return await fileLead(request);
+            if (!await heldAsContact(request)) return await stampedAfter(request, fileLead(request));
         } else if (surface === 'touch') {
-            if (await openLeadFor(request)) return await fileLead(request);
+            if (await openLeadFor(request)) return await stampedAfter(request, fileLead(request));
         }
         const verdict = await captureOnContact(request);
+        if (verdict.ok) await stampOrigin(request);
         if (verdict.ok && verdict.record === 'contact' && surface === 'relationship') {
             var _request_purchaseCents;
             await convertOpenLeadOntoContact({
@@ -104,6 +108,26 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
         };
     }
 }
+/**
+ * WHERE THE PERSON CAME FROM (AGL-3519): the door's word — a form, a
+ * booking, a newsletter, a member, an order — as the built-in Lead source
+ * it names, on a record the capture just started and that names none. A
+ * person met before keeps whatever lead source they hold, or the lack of one.
+ * Never fails the capture: the writer swallows its own errors.
+ */ async function stampOrigin(request) {
+    var _normalizeContactEmail;
+    await crmRecordOriginWriter.stamp({
+        hostId: request.hostId,
+        email: (_normalizeContactEmail = normalizeContactEmail(request.identity.email)) != null ? _normalizeContactEmail : '',
+        origin: request.interaction.source,
+        firstTouchOnly: true
+    });
+}
+/** A filed lead's verdict, after its origin is stamped when the filing took. */ async function stampedAfter(request, filed) {
+    const verdict = await filed;
+    if (verdict.ok) await stampOrigin(request);
+    return verdict;
+}
 /** The refusal every door gets for an address nothing can key. */ function refusedEmail() {
     return {
         ok: false,
@@ -159,9 +183,9 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
             source
         }, request.marketingConsent ? {
             marketingConsent: true
-        } : {}, disclosureOf(request))
-    }, campaignTouchOf(request.detail).campaignTouch ? {
-        touch: campaignTouchOf(request.detail).campaignTouch
+        } : {}, disclosureOf(request), phoneFillOf(request))
+    }, conversionTouchOf(request.detail).conversionTouch ? {
+        touch: conversionTouchOf(request.detail).conversionTouch
     } : {}));
     if (!outcome.stored) {
         return {
@@ -209,7 +233,7 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
             } : {}, request.interaction.summary ? {
                 summary: request.interaction.summary
             } : {}, entryPointOf(request.detail))
-        }, campaignTouchOf(request.detail), request.marketingConsent === undefined ? {} : {
+        }, conversionTouchOf(request.detail), request.marketingConsent === undefined ? {} : {
             marketingConsent: request.marketingConsent
         }, disclosureOf(request), ((_request_tags = request.tags) == null ? void 0 : _request_tags.length) ? {
             tags: request.tags
@@ -221,6 +245,10 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
             initialLifecycleStage: request.lifecycleFloor
         } : {}, request.profile ? {
             facet: request.profile
+        } : {}, phoneFillOf(request).phoneFill ? {
+            facetFill: {
+                phone: phoneFillOf(request).phoneFill
+            }
         } : {}));
         if ('refused' in verdict) {
             return {
@@ -263,6 +291,22 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
         disclosedConsentGroup: key
     } : {};
 }
+/**
+ * THE PHONE A CAPTURE LEARNED IN PASSING (AGL-3493), off `profileFill`.
+ *
+ * Normalized here so a lead and a contact written by one capture keep the
+ * same E.164 string, and dropped when it will not normalize: a fill is an
+ * enrichment, and a number in some other shape on the record is the
+ * "stored three ways" failure `normalizePhone` exists to end. Both writers
+ * put it only where the record holds no phone.
+ */ function phoneFillOf(request) {
+    var _request_profileFill;
+    const raw = (_request_profileFill = request.profileFill) == null ? void 0 : _request_profileFill['phone'];
+    const phone = typeof raw === 'string' ? normalizePhone(raw) : null;
+    return phone ? {
+        phoneFill: phone
+    } : {};
+}
 /**
  * THE ENTRY POINT, off the silo's own `detail` bag (AGL-3080).
  *
@@ -305,21 +349,21 @@ import { convertOpenLeadOntoContact } from "./convert-open-lead.js";
  *
  * ⚠️ A different fact from `campaignIds` and the two must never be folded
  * together — `upsert-contact.ts` says so at the field itself. A touch is the
- * ad or the link the visitor arrived by, already resolved through the
- * allowlist by the silo; `campaignIds` is which campaigns the merchant filed
- * the capture SURFACE under, which is true of everybody who fills that form
- * in. Folding them would credit a campaign for a visitor who typed the
- * address.
+ * ad or the link the visitor arrived by, already resolved by the plugin that
+ * credits outcomes (`plugin-conversion-credit`) at the silo's door;
+ * `campaignIds` is which campaigns the merchant filed the capture SURFACE
+ * under, which is true of everybody who fills that form in. Folding them
+ * would credit a campaign for a visitor who typed the address.
  *
- * Passed through as the silo resolved it, unread: the touch's shape belongs
- * to whatever resolves it, and re-validating it here would be a second copy
- * of a rule that has already run. Only its presence is decided here, because
- * `null` and absent mean the same thing to the writer and a caller should
- * not have to know which one it sends.
- */ function campaignTouchOf(detail) {
-    const touch = detail == null ? void 0 : detail['campaignTouch'];
-    return touch ? {
-        campaignTouch: touch
+ * Passed through as the silo handed it, unread: the touch's shape belongs
+ * to the creditor that resolved it, and the creditor checks it again when
+ * the contact or the lead is credited. Only its presence is decided here,
+ * because `null` and absent mean the same thing to the writer and a caller
+ * should not have to know which one it sends.
+ */ function conversionTouchOf(detail) {
+    const touch = detail == null ? void 0 : detail[CONVERSION_TOUCH_DETAIL];
+    return touch && typeof touch === 'object' ? {
+        conversionTouch: touch
     } : {};
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/capture-contact.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  PluginContactCaptureRequest,\n  PluginContactCaptured,\n} from '@aglyn/aglyn/plugin-manager/plugin-contact-capture'\nimport {\n  CONTACT_SOURCE_LABELS,\n  type ContactSource,\n} from '@aglyn/aglyn/app-utils/contacts'\nimport { formLeadSource } from '@aglyn/aglyn/app-utils/forms'\nimport {\n  type CrmLeadFields,\n  isCrmLeadOpen,\n  normalizeContactEmail,\n  personKey,\n} from '@aglyn/aglyn/server'\nimport { captureHostContact } from '@aglyn/tenant-runtime/capture-host-contact'\nimport { contactCaptureActor } from '@aglyn/tenant-runtime/capture-actor'\nimport { emitHostEvent } from '@aglyn/tenant-runtime/emit-host-event'\nimport {\n  addHostLeadOutcome,\n  findContactByEmail,\n  firebaseAdmin,\n  orgDataCollectionForHost,\n  readLeadForHost,\n  type UpsertHostContactOptions,\n} from '@aglyn/tenant-data-admin'\nimport type { ResolvedCampaignTouch } from '@aglyn/tenant-data-admin/server/campaign-conversion-attribution'\nimport { convertOpenLeadOntoContact } from './convert-open-lead'\n\n/**\n * The CRM answering the platform's contact-capture contract (AGL-3080).\n *\n * Four silos meet the same person — a form submission, a member signing up,\n * an order, a booking — and none of them is the record system. Each holds an\n * address, a name and the fact that something happened, and each wants the\n * workspace's person record to know. Today each imports `captureHostContact`\n * directly, which is the highest fan-in edge in the repo and makes the CRM\n * something a storefront cannot take a payment without.\n *\n * So this is the CRM's side of the seam: the silo reports what it saw, and\n * the plugin that keeps people decides everything a record system decides —\n * keying the address, whether this is somebody new, the audience band, the\n * erasure rows, the company, the owner, and what a new person sets off.\n * `captureHostContact` already does all of that; this translates the\n * contract's vocabulary into its options and its verdict back.\n *\n * ⚠️ IT NEVER THROWS. Every caller has already done the thing it is\n * recording — the submission was accepted, the order was paid — so a refusal\n * is RETURNED and costs the silo nothing. A throw here would lose an order\n * for a contact that could not be filed.\n */\n/**\n * WHICH RECORD A CAPTURE LANDS ON (AGL-3232) — the Salesforce rule, decided\n * here because the CRM is the plugin that models both records.\n *\n * One person is one record: a LEAD until somebody qualifies them, a CONTACT\n * after. Every door used to write both — a lead-routed form filed a lead\n * AND a contact at stage Lead — so one person sat in two lists and the Leads\n * queue was never the whole story. Now a door says what kind of surface it\n * is (`request.surface`) and this decides:\n *\n *  - a LEAD surface files a lead, unless the workspace already holds the\n *    address as a contact — a customer who books a demo is a customer's\n *    interaction, not a new lead — in which case the capture lands on the\n *    contact and no lead is filed;\n *  - a RELATIONSHIP (a member account, a purchase) makes the contact, and\n *    an open lead the site held for the address is stamped converted onto\n *    it, so nobody keeps working a lead who already joined or bought;\n *  - a TOUCH (an unrouted form, a newsletter opt-in) lands on the open lead\n *    when the site holds one — its consent and its history stay on the one\n *    record the rep is working — and on the contact otherwise.\n *\n * A lead is filed through `addHostLead`, the one writer of the leads silo,\n * so it is keyed on the person, counted against the ceiling and carries the\n * campaign touch the door resolved. A NEW lead announces itself with the\n * `lead` host event, which is what a \"new lead\" automation listens for; a\n * repeat capture on a lead the site already held announces nothing, the\n * way a repeat visit by a contact is an interaction and not a creation.\n */\nexport async function captureContactForCrm(\n  request: PluginContactCaptureRequest,\n): Promise<PluginContactCaptured> {\n  const surface = request.surface ?? 'touch'\n  // The one refusal every surface shares, answered before any read: an\n  // address nothing can key is a person nothing can record.\n  if (!normalizeContactEmail(request.identity.email)) return refusedEmail()\n  try {\n    if (surface === 'lead') {\n      if (!(await heldAsContact(request))) return await fileLead(request)\n    } else if (surface === 'touch') {\n      if (await openLeadFor(request)) return await fileLead(request)\n    }\n    const verdict = await captureOnContact(request)\n    if (verdict.ok && verdict.record === 'contact' && surface === 'relationship') {\n      await convertOpenLeadOntoContact({\n        hostId: request.hostId,\n        email: request.identity.email,\n        contactId: verdict.contactId,\n        // Money changing hands is a purchase whichever door took it — a paid\n        // booking or a stay is one as much as an order is.\n        by:\n          request.interaction.source === 'order' || (request.purchaseCents ?? 0) > 0\n            ? 'purchase'\n            : 'signup',\n      })\n    }\n    return verdict\n  } catch (error) {\n    console.error('crm contact capture failed', error)\n    return {\n      ok: false,\n      reason: 'error',\n      error: 'The contact could not be recorded. Nothing else was affected.',\n    }\n  }\n}\n\n/** The refusal every door gets for an address nothing can key. */\nfunction refusedEmail(): PluginContactCaptured {\n  return { ok: false, reason: 'invalid-email', error: refusalText('invalid-email') }\n}\n\n/**\n * Whether the workspace already holds the address as a contact — the\n * address index first, then the query, the same lookup every dedupe uses.\n * ORG-wide, not scoped to the capturing site: the contact door dedupes\n * across every site in the org, so a person any site holds as a contact\n * is a contact, whichever site met them this time.\n */\nasync function heldAsContact(request: PluginContactCaptureRequest): Promise<boolean> {\n  const contacts = await orgDataCollectionForHost(request.hostId, 'contacts')\n  return (await findContactByEmail(contacts, request.identity.email)) !== null\n}\n\n/** Whether the site holds an OPEN lead for the address — neither converted nor closed. */\nasync function openLeadFor(request: PluginContactCaptureRequest): Promise<boolean> {\n  const key = personKey(request.identity.email) as string\n  /*\n   * Through the seam, which reads the org row and falls back to a lead the\n   * backfill has not reached (AGL-3275). UNSCOPED on purpose: a sibling brand\n   * in the same consent group has to find this person, or its door concludes\n   * there is no lead and files the duplicate this migration exists to end.\n   */\n  const snapshot = await readLeadForHost(request.hostId, key)\n  if (!snapshot) return false\n  const lead = (snapshot.data() ?? {}) as Record<string, unknown> & CrmLeadFields\n  return !lead.convertedContactId && isCrmLeadOpen(lead)\n}\n\n/**\n * The capture as a LEAD. The source string is the lead silo's own\n * vocabulary — `form:{formId}` for a form, the door's word otherwise — so\n * a lead's provenance survives the form being renamed, as the submission's\n * does.\n */\nasync function fileLead(request: PluginContactCaptureRequest): Promise<PluginContactCaptured> {\n  const email = normalizeContactEmail(request.identity.email) as string\n  const key = personKey(email) as string\n  const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(request.hostId)\n  // `addHostLead` resolves and writes the org collection itself (AGL-3275);\n  // this only needs to know whether the person is new, which decides the event.\n  const created = !(await readLeadForHost(request.hostId, key))\n  const { formId } = entryPointOf(request.detail)\n  const source =\n    request.interaction.source === 'form' && formId\n      ? formLeadSource(formId)\n      : request.interaction.source\n  const outcome = await addHostLeadOutcome({\n    hostRef,\n    hostId: request.hostId,\n    lead: {\n      email,\n      ...(request.identity.name ? { name: request.identity.name } : {}),\n      source,\n      ...(request.marketingConsent ? { marketingConsent: true } : {}),\n      ...disclosureOf(request),\n    },\n    ...(campaignTouchOf(request.detail).campaignTouch\n      ? { touch: campaignTouchOf(request.detail).campaignTouch }\n      : {}),\n  })\n  if (!outcome.stored) {\n    return {\n      ok: false,\n      reason: 'band',\n      error: 'This site is at the number of leads it may hold, so the lead was not recorded.',\n    }\n  }\n  if (created) {\n    const cause = contactCaptureActor(\n      request.interaction.source,\n      email,\n      request.actor,\n    )\n    await emitHostEvent(\n      request.hostId,\n      'lead',\n      {\n        email,\n        source,\n        leadId: key,\n        ...(request.identity.name ? { name: request.identity.name } : {}),\n      },\n      cause ? { actor: cause } : {},\n    )\n  }\n  return { ok: true, record: 'lead', leadId: key, created, sourceAdded: outcome.sourceAdded }\n}\n\n/** The capture as a CONTACT — what every capture was before the rule above. */\nasync function captureOnContact(\n  request: PluginContactCaptureRequest,\n): Promise<PluginContactCaptured> {\n  try {\n    const verdict = await captureHostContact({\n      ...(request.actor ? { actor: request.actor } : {}),\n      hostId: request.hostId,\n      email: request.identity.email,\n      ...(request.identity.name ? { name: request.identity.name } : {}),\n      source: contactSourceOf(request.interaction.source),\n      interaction: {\n        ...(request.interaction.atMs === undefined\n          ? {}\n          : { atMs: request.interaction.atMs }),\n        ...(request.interaction.refId ? { refId: request.interaction.refId } : {}),\n        ...(request.interaction.summary\n          ? { summary: request.interaction.summary }\n          : {}),\n        ...entryPointOf(request.detail),\n      },\n      ...campaignTouchOf(request.detail),\n      ...(request.marketingConsent === undefined\n        ? {}\n        : { marketingConsent: request.marketingConsent }),\n      ...disclosureOf(request),\n      ...(request.tags?.length ? { tags: request.tags } : {}),\n      ...campaignsFiledUnder(request),\n      ...(request.purchaseCents === undefined\n        ? {}\n        : { purchaseCents: request.purchaseCents }),\n      ...(request.purchaseCurrency\n        ? { purchaseCurrency: request.purchaseCurrency }\n        : {}),\n      ...(request.lifecycleFloor\n        ? { initialLifecycleStage: request.lifecycleFloor as never }\n        : {}),\n      ...(request.profile ? { facet: request.profile as never } : {}),\n    })\n    if ('refused' in verdict) {\n      return { ok: false, reason: verdict.refused, error: refusalText(verdict.refused) }\n    }\n    return {\n      ok: true,\n      record: 'contact',\n      contactId: verdict.contactId,\n      created: verdict.created,\n    }\n  } catch (error) {\n    /*\n     * The contract's `error` is the last state, not a channel for a stack:\n     * a silo may show or log it as it stands, so it says what happened and\n     * names nothing internal. The detail goes to the log, where whoever is\n     * debugging a missing contact will look.\n     */\n    console.error('crm contact capture failed', error)\n    return {\n      ok: false,\n      reason: 'error',\n      error: 'The contact could not be recorded. Nothing else was affected.',\n    }\n  }\n}\n\n/**\n * THE DISCLOSURE the capture surface rendered, handed to whichever record the\n * capture lands on (AGL-3320).\n *\n * Passed through unread: both writers resolve the site's group themselves and\n * pool the opt-in only when this is its current key, so a lead and a contact\n * written by one capture record the same sites. A string or nothing, since\n * the writers compare it exactly and anything else could only fail to match.\n */\nfunction disclosureOf(\n  request: PluginContactCaptureRequest,\n): { disclosedConsentGroup?: string } {\n  const key = request.disclosedConsentGroup\n  return typeof key === 'string' && key ? { disclosedConsentGroup: key } : {}\n}\n\n/**\n * THE ENTRY POINT, off the silo's own `detail` bag (AGL-3080).\n *\n * The contract carries a capture's silo-side facts opaquely, so the two the\n * CRM models are picked out here rather than typed into the platform. Both\n * ride the INTERACTION, which is where `upsertHostContact` already keeps\n * them: which form a person came in through routes the owner-assignment\n * rules and rides the `contactCreated` payload, and the page is what a\n * timeline row says about where they were.\n *\n * Absent, misspelled or the wrong type is the same answer as a door that\n * never had one — a capture without an entry point, which is every capture\n * that did not come through a form. It is never a reason to refuse: the\n * person is the part that matters.\n */\nfunction entryPointOf(\n  detail: Readonly<Record<string, unknown>> | undefined,\n): { formId?: string; path?: string } {\n  const text = (value: unknown): string | undefined =>\n    typeof value === 'string' && value.trim() ? value : undefined\n  const formId = text(detail?.['formId'])\n  const path = text(detail?.['path'])\n  return {\n    ...(formId ? { formId } : {}),\n    ...(path ? { path } : {}),\n  }\n}\n\n/**\n * The campaigns the capture surface is filed under, as the contact writer\n * records them. A capture names what its surface is filed under by container\n * kind; the CRM keeps the `campaign` kind on the person's site facet, and a\n * kind it does not keep is the capture's to name and the CRM's to ignore.\n */\nfunction campaignsFiledUnder(\n  request: PluginContactCaptureRequest,\n): Pick<UpsertHostContactOptions, 'campaignIds'> {\n  const ids = request.containers?.['campaign'] ?? []\n  return ids.length ? { campaignIds: ids } : {}\n}\n\n/**\n * WHERE THE VISITOR CAME FROM, off the same bag.\n *\n * ⚠️ A different fact from `campaignIds` and the two must never be folded\n * together — `upsert-contact.ts` says so at the field itself. A touch is the\n * ad or the link the visitor arrived by, already resolved through the\n * allowlist by the silo; `campaignIds` is which campaigns the merchant filed\n * the capture SURFACE under, which is true of everybody who fills that form\n * in. Folding them would credit a campaign for a visitor who typed the\n * address.\n *\n * Passed through as the silo resolved it, unread: the touch's shape belongs\n * to whatever resolves it, and re-validating it here would be a second copy\n * of a rule that has already run. Only its presence is decided here, because\n * `null` and absent mean the same thing to the writer and a caller should\n * not have to know which one it sends.\n */\nfunction campaignTouchOf(\n  detail: Readonly<Record<string, unknown>> | undefined,\n): Pick<UpsertHostContactOptions, 'campaignTouch'> {\n  const touch = detail?.['campaignTouch']\n  return touch ? { campaignTouch: touch as ResolvedCampaignTouch } : {}\n}\n\n/**\n * The silo's word for its door, as a source the CRM stores.\n *\n * ⚠️ `ContactSource` is a CLOSED union and the contract's `source` is an open\n * string, deliberately: a silo declares its door with\n * `registerPluginContactSource` rather than core enumerating every plugin's.\n * The two meet here, and a word outside the union is passed through rather\n * than rejected — refusing it would lose a third-party plugin's capture over\n * a label, and the capture is the part that matters.\n *\n * ⛔ What it costs, until the union is widened: the console's source filter\n * and `SOURCE_LABELS` key on these values, so an undeclared word renders raw\n * and matches no filter. Every first-party silo uses a word in the union, so\n * nothing does that today.\n */\nexport function contactSourceOf(source: string): ContactSource {\n  const word = String(source ?? '').trim()\n  if (!Object.hasOwn(CONTACT_SOURCE_LABELS, word)) {\n    // Said once, where somebody debugging an unlabelled row will find it.\n    // Not a refusal: the capture is worth more than the label.\n    console.warn(\n      `crm contact capture: source \"${word}\" has no label, so it will render ` +\n        'raw and match no filter in the console.',\n    )\n  }\n  return word as ContactSource\n}\n\n/** What a refused caller is told — customer-safe, and never a key. */\nfunction refusalText(reason: 'invalid-email' | 'band' | 'erased' | 'error'): string {\n  switch (reason) {\n    case 'invalid-email':\n      return 'That address could not be read, so no contact was recorded.'\n    case 'band':\n      return 'This workspace is at the number of contacts its plan holds.'\n    case 'erased':\n      return 'This person was erased from this workspace and was not recreated.'\n    default:\n      return 'The contact could not be recorded. Nothing else was affected.'\n  }\n}\n"],"names":["CONTACT_SOURCE_LABELS","formLeadSource","isCrmLeadOpen","normalizeContactEmail","personKey","captureHostContact","contactCaptureActor","emitHostEvent","addHostLeadOutcome","findContactByEmail","firebaseAdmin","orgDataCollectionForHost","readLeadForHost","convertOpenLeadOntoContact","captureContactForCrm","request","surface","identity","email","refusedEmail","heldAsContact","fileLead","openLeadFor","verdict","captureOnContact","ok","record","hostId","contactId","by","interaction","source","purchaseCents","error","console","reason","refusalText","contacts","snapshot","key","lead","data","convertedContactId","hostRef","app","firestore","collection","doc","created","formId","entryPointOf","detail","outcome","name","marketingConsent","disclosureOf","campaignTouchOf","campaignTouch","touch","stored","cause","actor","leadId","sourceAdded","contactSourceOf","atMs","undefined","refId","summary","tags","length","campaignsFiledUnder","purchaseCurrency","lifecycleFloor","initialLifecycleStage","profile","facet","refused","disclosedConsentGroup","text","value","trim","path","ids","containers","campaignIds","word","String","Object","hasOwn","warn"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/capture-contact.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  PluginContactCaptureRequest,\n  PluginContactCaptured,\n} from '@aglyn/aglyn/plugin-manager/plugin-contact-capture'\nimport {\n  CONTACT_SOURCE_LABELS,\n  type ContactSource,\n} from '@aglyn/aglyn/app-utils/contacts'\nimport { formLeadSource } from '@aglyn/aglyn/app-utils/forms'\nimport { normalizePhone } from '@aglyn/aglyn/foundation/definitions/contact.types'\nimport {\n  type CrmLeadFields,\n  isCrmLeadOpen,\n  normalizeContactEmail,\n  personKey,\n} from '@aglyn/aglyn/server'\nimport { captureHostContact } from './capture-host-contact'\nimport { contactCaptureActor } from '@aglyn/tenant-runtime/capture-actor'\nimport { emitHostEvent } from '@aglyn/tenant-runtime/emit-host-event'\nimport {\n  addHostLeadOutcome,\n  findContactByEmail,\n  firebaseAdmin,\n  orgDataCollectionForHost,\n  readLeadForHost,\n  type UpsertHostContactOptions,\n} from '@aglyn/tenant-data-admin'\nimport {\n  CONVERSION_TOUCH_DETAIL,\n  type PluginConversionTouch,\n} from '@aglyn/aglyn/plugin-manager/plugin-conversion-credit'\nimport { convertOpenLeadOntoContact } from './convert-open-lead'\nimport { crmRecordOriginWriter } from './record-origin'\n\n/**\n * The CRM answering the platform's contact-capture contract (AGL-3080).\n *\n * Four silos meet the same person — a form submission, a member signing up,\n * an order, a booking — and none of them is the record system. Each holds an\n * address, a name and the fact that something happened, and each wants the\n * workspace's person record to know. Today each imports `captureHostContact`\n * directly, which is the highest fan-in edge in the repo and makes the CRM\n * something a storefront cannot take a payment without.\n *\n * So this is the CRM's side of the seam: the silo reports what it saw, and\n * the plugin that keeps people decides everything a record system decides —\n * keying the address, whether this is somebody new, the audience band, the\n * erasure rows, the company, the owner, and what a new person sets off.\n * `captureHostContact` already does all of that; this translates the\n * contract's vocabulary into its options and its verdict back.\n *\n * ⚠️ IT NEVER THROWS. Every caller has already done the thing it is\n * recording — the submission was accepted, the order was paid — so a refusal\n * is RETURNED and costs the silo nothing. A throw here would lose an order\n * for a contact that could not be filed.\n */\n/**\n * WHICH RECORD A CAPTURE LANDS ON (AGL-3232) — the Salesforce rule, decided\n * here because the CRM is the plugin that models both records.\n *\n * One person is one record: a LEAD until somebody qualifies them, a CONTACT\n * after. Every door used to write both — a lead-routed form filed a lead\n * AND a contact at stage Lead — so one person sat in two lists and the Leads\n * queue was never the whole story. Now a door says what kind of surface it\n * is (`request.surface`) and this decides:\n *\n *  - a LEAD surface files a lead, unless the workspace already holds the\n *    address as a contact — a customer who books a demo is a customer's\n *    interaction, not a new lead — in which case the capture lands on the\n *    contact and no lead is filed;\n *  - a RELATIONSHIP (a member account, a purchase) makes the contact, and\n *    an open lead the site held for the address is stamped converted onto\n *    it, so nobody keeps working a lead who already joined or bought;\n *  - a TOUCH (an unrouted form, a newsletter opt-in) lands on the open lead\n *    when the site holds one — its consent and its history stay on the one\n *    record the rep is working — and on the contact otherwise.\n *\n * A lead is filed through `addHostLead`, the one writer of the leads silo,\n * so it is keyed on the person, counted against the ceiling and carries the\n * campaign touch the door resolved. A NEW lead announces itself with the\n * `lead` host event, which is what a \"new lead\" automation listens for; a\n * repeat capture on a lead the site already held announces nothing, the\n * way a repeat visit by a contact is an interaction and not a creation.\n */\nexport async function captureContactForCrm(\n  request: PluginContactCaptureRequest,\n): Promise<PluginContactCaptured> {\n  const surface = request.surface ?? 'touch'\n  // The one refusal every surface shares, answered before any read: an\n  // address nothing can key is a person nothing can record.\n  if (!normalizeContactEmail(request.identity.email)) return refusedEmail()\n  try {\n    if (surface === 'lead') {\n      if (!(await heldAsContact(request))) return await stampedAfter(request, fileLead(request))\n    } else if (surface === 'touch') {\n      if (await openLeadFor(request)) return await stampedAfter(request, fileLead(request))\n    }\n    const verdict = await captureOnContact(request)\n    if (verdict.ok) await stampOrigin(request)\n    if (verdict.ok && verdict.record === 'contact' && surface === 'relationship') {\n      await convertOpenLeadOntoContact({\n        hostId: request.hostId,\n        email: request.identity.email,\n        contactId: verdict.contactId,\n        // Money changing hands is a purchase whichever door took it — a paid\n        // booking or a stay is one as much as an order is.\n        by:\n          request.interaction.source === 'order' || (request.purchaseCents ?? 0) > 0\n            ? 'purchase'\n            : 'signup',\n      })\n    }\n    return verdict\n  } catch (error) {\n    console.error('crm contact capture failed', error)\n    return {\n      ok: false,\n      reason: 'error',\n      error: 'The contact could not be recorded. Nothing else was affected.',\n    }\n  }\n}\n\n/**\n * WHERE THE PERSON CAME FROM (AGL-3519): the door's word — a form, a\n * booking, a newsletter, a member, an order — as the built-in Lead source\n * it names, on a record the capture just started and that names none. A\n * person met before keeps whatever lead source they hold, or the lack of one.\n * Never fails the capture: the writer swallows its own errors.\n */\nasync function stampOrigin(request: PluginContactCaptureRequest): Promise<void> {\n  await crmRecordOriginWriter.stamp({\n    hostId: request.hostId,\n    email: normalizeContactEmail(request.identity.email) ?? '',\n    origin: request.interaction.source,\n    firstTouchOnly: true,\n  })\n}\n\n/** A filed lead's verdict, after its origin is stamped when the filing took. */\nasync function stampedAfter(\n  request: PluginContactCaptureRequest,\n  filed: Promise<PluginContactCaptured>,\n): Promise<PluginContactCaptured> {\n  const verdict = await filed\n  if (verdict.ok) await stampOrigin(request)\n  return verdict\n}\n\n/** The refusal every door gets for an address nothing can key. */\nfunction refusedEmail(): PluginContactCaptured {\n  return { ok: false, reason: 'invalid-email', error: refusalText('invalid-email') }\n}\n\n/**\n * Whether the workspace already holds the address as a contact — the\n * address index first, then the query, the same lookup every dedupe uses.\n * ORG-wide, not scoped to the capturing site: the contact door dedupes\n * across every site in the org, so a person any site holds as a contact\n * is a contact, whichever site met them this time.\n */\nasync function heldAsContact(request: PluginContactCaptureRequest): Promise<boolean> {\n  const contacts = await orgDataCollectionForHost(request.hostId, 'contacts')\n  return (await findContactByEmail(contacts, request.identity.email)) !== null\n}\n\n/** Whether the site holds an OPEN lead for the address — neither converted nor closed. */\nasync function openLeadFor(request: PluginContactCaptureRequest): Promise<boolean> {\n  const key = personKey(request.identity.email) as string\n  /*\n   * Through the seam, which reads the org row and falls back to a lead the\n   * backfill has not reached (AGL-3275). UNSCOPED on purpose: a sibling brand\n   * in the same consent group has to find this person, or its door concludes\n   * there is no lead and files the duplicate this migration exists to end.\n   */\n  const snapshot = await readLeadForHost(request.hostId, key)\n  if (!snapshot) return false\n  const lead = (snapshot.data() ?? {}) as Record<string, unknown> & CrmLeadFields\n  return !lead.convertedContactId && isCrmLeadOpen(lead)\n}\n\n/**\n * The capture as a LEAD. The source string is the lead silo's own\n * vocabulary — `form:{formId}` for a form, the door's word otherwise — so\n * a lead's provenance survives the form being renamed, as the submission's\n * does.\n */\nasync function fileLead(request: PluginContactCaptureRequest): Promise<PluginContactCaptured> {\n  const email = normalizeContactEmail(request.identity.email) as string\n  const key = personKey(email) as string\n  const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(request.hostId)\n  // `addHostLead` resolves and writes the org collection itself (AGL-3275);\n  // this only needs to know whether the person is new, which decides the event.\n  const created = !(await readLeadForHost(request.hostId, key))\n  const { formId } = entryPointOf(request.detail)\n  const source =\n    request.interaction.source === 'form' && formId\n      ? formLeadSource(formId)\n      : request.interaction.source\n  const outcome = await addHostLeadOutcome({\n    hostRef,\n    hostId: request.hostId,\n    lead: {\n      email,\n      ...(request.identity.name ? { name: request.identity.name } : {}),\n      source,\n      ...(request.marketingConsent ? { marketingConsent: true } : {}),\n      ...disclosureOf(request),\n      ...phoneFillOf(request),\n    },\n    ...(conversionTouchOf(request.detail).conversionTouch\n      ? { touch: conversionTouchOf(request.detail).conversionTouch }\n      : {}),\n  })\n  if (!outcome.stored) {\n    return {\n      ok: false,\n      reason: 'band',\n      error: 'This site is at the number of leads it may hold, so the lead was not recorded.',\n    }\n  }\n  if (created) {\n    const cause = contactCaptureActor(\n      request.interaction.source,\n      email,\n      request.actor,\n    )\n    await emitHostEvent(\n      request.hostId,\n      'lead',\n      {\n        email,\n        source,\n        leadId: key,\n        ...(request.identity.name ? { name: request.identity.name } : {}),\n      },\n      cause ? { actor: cause } : {},\n    )\n  }\n  return { ok: true, record: 'lead', leadId: key, created, sourceAdded: outcome.sourceAdded }\n}\n\n/** The capture as a CONTACT — what every capture was before the rule above. */\nasync function captureOnContact(\n  request: PluginContactCaptureRequest,\n): Promise<PluginContactCaptured> {\n  try {\n    const verdict = await captureHostContact({\n      ...(request.actor ? { actor: request.actor } : {}),\n      hostId: request.hostId,\n      email: request.identity.email,\n      ...(request.identity.name ? { name: request.identity.name } : {}),\n      source: contactSourceOf(request.interaction.source),\n      interaction: {\n        ...(request.interaction.atMs === undefined\n          ? {}\n          : { atMs: request.interaction.atMs }),\n        ...(request.interaction.refId ? { refId: request.interaction.refId } : {}),\n        ...(request.interaction.summary\n          ? { summary: request.interaction.summary }\n          : {}),\n        ...entryPointOf(request.detail),\n      },\n      ...conversionTouchOf(request.detail),\n      ...(request.marketingConsent === undefined\n        ? {}\n        : { marketingConsent: request.marketingConsent }),\n      ...disclosureOf(request),\n      ...(request.tags?.length ? { tags: request.tags } : {}),\n      ...campaignsFiledUnder(request),\n      ...(request.purchaseCents === undefined\n        ? {}\n        : { purchaseCents: request.purchaseCents }),\n      ...(request.purchaseCurrency\n        ? { purchaseCurrency: request.purchaseCurrency }\n        : {}),\n      ...(request.lifecycleFloor\n        ? { initialLifecycleStage: request.lifecycleFloor as never }\n        : {}),\n      ...(request.profile ? { facet: request.profile as never } : {}),\n      ...(phoneFillOf(request).phoneFill\n        ? { facetFill: { phone: phoneFillOf(request).phoneFill } }\n        : {}),\n    })\n    if ('refused' in verdict) {\n      return { ok: false, reason: verdict.refused, error: refusalText(verdict.refused) }\n    }\n    return {\n      ok: true,\n      record: 'contact',\n      contactId: verdict.contactId,\n      created: verdict.created,\n    }\n  } catch (error) {\n    /*\n     * The contract's `error` is the last state, not a channel for a stack:\n     * a silo may show or log it as it stands, so it says what happened and\n     * names nothing internal. The detail goes to the log, where whoever is\n     * debugging a missing contact will look.\n     */\n    console.error('crm contact capture failed', error)\n    return {\n      ok: false,\n      reason: 'error',\n      error: 'The contact could not be recorded. Nothing else was affected.',\n    }\n  }\n}\n\n/**\n * THE DISCLOSURE the capture surface rendered, handed to whichever record the\n * capture lands on (AGL-3320).\n *\n * Passed through unread: both writers resolve the site's group themselves and\n * pool the opt-in only when this is its current key, so a lead and a contact\n * written by one capture record the same sites. A string or nothing, since\n * the writers compare it exactly and anything else could only fail to match.\n */\nfunction disclosureOf(\n  request: PluginContactCaptureRequest,\n): { disclosedConsentGroup?: string } {\n  const key = request.disclosedConsentGroup\n  return typeof key === 'string' && key ? { disclosedConsentGroup: key } : {}\n}\n\n/**\n * THE PHONE A CAPTURE LEARNED IN PASSING (AGL-3493), off `profileFill`.\n *\n * Normalized here so a lead and a contact written by one capture keep the\n * same E.164 string, and dropped when it will not normalize: a fill is an\n * enrichment, and a number in some other shape on the record is the\n * \"stored three ways\" failure `normalizePhone` exists to end. Both writers\n * put it only where the record holds no phone.\n */\nfunction phoneFillOf(request: PluginContactCaptureRequest): { phoneFill?: string } {\n  const raw = request.profileFill?.['phone']\n  const phone = typeof raw === 'string' ? normalizePhone(raw) : null\n  return phone ? { phoneFill: phone } : {}\n}\n\n/**\n * THE ENTRY POINT, off the silo's own `detail` bag (AGL-3080).\n *\n * The contract carries a capture's silo-side facts opaquely, so the two the\n * CRM models are picked out here rather than typed into the platform. Both\n * ride the INTERACTION, which is where `upsertHostContact` already keeps\n * them: which form a person came in through routes the owner-assignment\n * rules and rides the `contactCreated` payload, and the page is what a\n * timeline row says about where they were.\n *\n * Absent, misspelled or the wrong type is the same answer as a door that\n * never had one — a capture without an entry point, which is every capture\n * that did not come through a form. It is never a reason to refuse: the\n * person is the part that matters.\n */\nfunction entryPointOf(\n  detail: Readonly<Record<string, unknown>> | undefined,\n): { formId?: string; path?: string } {\n  const text = (value: unknown): string | undefined =>\n    typeof value === 'string' && value.trim() ? value : undefined\n  const formId = text(detail?.['formId'])\n  const path = text(detail?.['path'])\n  return {\n    ...(formId ? { formId } : {}),\n    ...(path ? { path } : {}),\n  }\n}\n\n/**\n * The campaigns the capture surface is filed under, as the contact writer\n * records them. A capture names what its surface is filed under by container\n * kind; the CRM keeps the `campaign` kind on the person's site facet, and a\n * kind it does not keep is the capture's to name and the CRM's to ignore.\n */\nfunction campaignsFiledUnder(\n  request: PluginContactCaptureRequest,\n): Pick<UpsertHostContactOptions, 'campaignIds'> {\n  const ids = request.containers?.['campaign'] ?? []\n  return ids.length ? { campaignIds: ids } : {}\n}\n\n/**\n * WHERE THE VISITOR CAME FROM, off the same bag.\n *\n * ⚠️ A different fact from `campaignIds` and the two must never be folded\n * together — `upsert-contact.ts` says so at the field itself. A touch is the\n * ad or the link the visitor arrived by, already resolved by the plugin that\n * credits outcomes (`plugin-conversion-credit`) at the silo's door;\n * `campaignIds` is which campaigns the merchant filed the capture SURFACE\n * under, which is true of everybody who fills that form in. Folding them\n * would credit a campaign for a visitor who typed the address.\n *\n * Passed through as the silo handed it, unread: the touch's shape belongs\n * to the creditor that resolved it, and the creditor checks it again when\n * the contact or the lead is credited. Only its presence is decided here,\n * because `null` and absent mean the same thing to the writer and a caller\n * should not have to know which one it sends.\n */\nfunction conversionTouchOf(\n  detail: Readonly<Record<string, unknown>> | undefined,\n): Pick<UpsertHostContactOptions, 'conversionTouch'> {\n  const touch = detail?.[CONVERSION_TOUCH_DETAIL]\n  return touch && typeof touch === 'object'\n    ? { conversionTouch: touch as PluginConversionTouch }\n    : {}\n}\n\n/**\n * The silo's word for its door, as a source the CRM stores.\n *\n * ⚠️ `ContactSource` is a CLOSED union and the contract's `source` is an open\n * string, deliberately: a silo declares its door with\n * `registerPluginContactSource` rather than core enumerating every plugin's.\n * The two meet here, and a word outside the union is passed through rather\n * than rejected — refusing it would lose a third-party plugin's capture over\n * a label, and the capture is the part that matters.\n *\n * ⛔ What it costs, until the union is widened: the console's source filter\n * and `SOURCE_LABELS` key on these values, so an undeclared word renders raw\n * and matches no filter. Every first-party silo uses a word in the union, so\n * nothing does that today.\n */\nexport function contactSourceOf(source: string): ContactSource {\n  const word = String(source ?? '').trim()\n  if (!Object.hasOwn(CONTACT_SOURCE_LABELS, word)) {\n    // Said once, where somebody debugging an unlabelled row will find it.\n    // Not a refusal: the capture is worth more than the label.\n    console.warn(\n      `crm contact capture: source \"${word}\" has no label, so it will render ` +\n        'raw and match no filter in the console.',\n    )\n  }\n  return word as ContactSource\n}\n\n/** What a refused caller is told — customer-safe, and never a key. */\nfunction refusalText(reason: 'invalid-email' | 'band' | 'erased' | 'error'): string {\n  switch (reason) {\n    case 'invalid-email':\n      return 'That address could not be read, so no contact was recorded.'\n    case 'band':\n      return 'This workspace is at the number of contacts its plan holds.'\n    case 'erased':\n      return 'This person was erased from this workspace and was not recreated.'\n    default:\n      return 'The contact could not be recorded. Nothing else was affected.'\n  }\n}\n"],"names":["CONTACT_SOURCE_LABELS","formLeadSource","normalizePhone","isCrmLeadOpen","normalizeContactEmail","personKey","captureHostContact","contactCaptureActor","emitHostEvent","addHostLeadOutcome","findContactByEmail","firebaseAdmin","orgDataCollectionForHost","readLeadForHost","CONVERSION_TOUCH_DETAIL","convertOpenLeadOntoContact","crmRecordOriginWriter","captureContactForCrm","request","surface","identity","email","refusedEmail","heldAsContact","stampedAfter","fileLead","openLeadFor","verdict","captureOnContact","ok","stampOrigin","record","hostId","contactId","by","interaction","source","purchaseCents","error","console","reason","stamp","origin","firstTouchOnly","filed","refusalText","contacts","snapshot","key","lead","data","convertedContactId","hostRef","app","firestore","collection","doc","created","formId","entryPointOf","detail","outcome","name","marketingConsent","disclosureOf","phoneFillOf","conversionTouchOf","conversionTouch","touch","stored","cause","actor","leadId","sourceAdded","contactSourceOf","atMs","undefined","refId","summary","tags","length","campaignsFiledUnder","purchaseCurrency","lifecycleFloor","initialLifecycleStage","profile","facet","phoneFill","facetFill","phone","refused","disclosedConsentGroup","raw","profileFill","text","value","trim","path","ids","containers","campaignIds","word","String","Object","hasOwn","warn"],"mappings":"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"}

package/src/lib/server/capture-host-contact.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @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 HostContactCreated, type UpsertHostContactOptions, type UpsertHostContactVerdict } from '@aglyn/tenant-data-admin';
+import type { HostEventActor, HostEventPayload } from '@aglyn/tenant-runtime/host-event-listeners';
+/**
+ * THE contact capture door for a server path (AGL-2605).
+ *
+ * `upsertHostContact` writes the contact and reports, through its
+ * `onCreated` hook, when the write made a NEW person. This wrapper is the
+ * one place that hook is bound to `contactCreated`, and it is the function
+ * every server door calls — the forms route, the membership and newsletter
+ * handlers, the order and booking webhooks. A door that calls
+ * `upsertHostContact` directly still captures the contact and fires nothing,
+ * which is a contact no automation can welcome; `capture-host-contact.spec`
+ * scans for exactly that call.
+ *
+ * ## Why the binding lives here and not in the data library
+ *
+ * What listens for the event — the automation engine among them — imports
+ * the data library for its Firestore handle, its org helpers and its
+ * senders. The data library emitting an event would import the listeners
+ * back, which is a cycle, and the module boundaries (`scope:data` depends on
+ * data and util only) refuse it in any case. So the lower layer reports a
+ * fact and this layer, which already knows how to announce one, announces
+ * it. The alternative — a sink the runtime registers into when its module
+ * happens to be imported — would fire only in a process that had loaded the
+ * runtime, and a Stripe webhook that created a contact in a process that had
+ * not would announce nothing with no error anywhere. The listeners themselves
+ * are registered by a call made at boot (`host-event-listeners.ts`), so every
+ * process has them before its first request.
+ *
+ * Fire-and-forget in the same sense the capture itself is: the hook's
+ * failure is caught inside `upsertHostContact`, so a runner that throws
+ * costs the door nothing, and this function never rejects.
+ *
+ * ## The company, before the announcement (AGL-2613)
+ *
+ * A new person with a work email address is linked to the company at that
+ * domain here, in the same hook, BEFORE `contactCreated` goes out — so an
+ * automation that reads the new contact finds them already filed, rather
+ * than racing a link that lands a moment later. Only when the door did not
+ * name a company itself: the console's drawer and an import row that
+ * carried one have written it into the facet, and the capture must not
+ * second-guess a person's choice with a domain match. The association never
+ * rejects, and its own catch keeps a failed lookup from costing the event.
+ *
+ * ## The owner, on the same terms (AGL-2618)
+ *
+ * Then the org's assignment rules and the site's default owner decide who
+ * follows the new person up — again before `contactCreated`, so an
+ * automation's "create a task for the owner" finds one — and again only
+ * when the door named none: a drawer, an import column or a conversion
+ * that picked an owner has said whose the record is. The pass reads the
+ * form and the tags off the same options the data library was handed,
+ * because the created-report carries the identity and not the routing.
+ * It never rejects either; a record it could not assign is one somebody
+ * assigns by hand, which is what every record was before this existed.
+ *
+ * What this does NOT do is close a lead (AGL-3232): a lead is the CRM's
+ * record, and which relationship closes one is the CRM's rule, answered in
+ * its capture writer for the doors that report through the capture seam.
+ * The order doors call this directly and close nothing — a buyer with an
+ * open lead is a lead the rep converts, as in Salesforce.
+ */
+export declare function captureHostContact(captureOptions: Omit<UpsertHostContactOptions, 'onCreated'> & {
+    /** Who caused the capture, when the door knows (AGL-3376). */
+    actor?: HostEventActor;
+}): Promise<UpsertHostContactVerdict>;
+/**
+ * The `contactCreated` payload, as the scalars an event may carry.
+ *
+ * `HostEventPayload` holds strings, numbers and booleans and nothing
+ * nested, because the payload seeds an expression scope and a condition
+ * editor whose operators compare strings. So `campaignIds` rides as one
+ * comma-joined string — `contains` still finds a campaign in it — and is
+ * present only when the capture had campaigns, so `notEmpty` on it reads
+ * as "came in through a campaign form". `name` and `lifecycleStage` are
+ * always present, empty when the door had none, so a condition on either
+ * never sees a missing key: `lifecycleStage == "lead"` is the filter that
+ * picks the form captures out of the sign-ups (AGL-2612).
+ *
+ * `formId` rides the same way `campaignIds` does — present only when the
+ * capture came through a form — because the created-report carries the
+ * person's identity and not the routing, and the form is routing: it is
+ * read off the interaction the door was handed. Present, it is what lets a
+ * condition say `formId` equals this form and no other (AGL-2626); absent,
+ * `notEmpty` on it reads as "came in through a form".
+ */
+export declare function contactCreatedPayload(created: HostContactCreated, formId?: string | null): HostEventPayload;
+export default captureHostContact;

package/src/lib/server/capture-host-contact.js

@@ -0,0 +1,151 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+/**
+ * @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 { upsertHostContact } from "@aglyn/tenant-data-admin";
+import { assignOwnerForCapture } from "./assign-contact-owner.js";
+import { associateCompanyByDomain } from "./associate-company-by-domain.js";
+import { emitHostEvent } from "@aglyn/tenant-runtime/emit-host-event";
+import { contactCaptureActor } from "@aglyn/tenant-runtime/capture-actor";
+/**
+ * THE contact capture door for a server path (AGL-2605).
+ *
+ * `upsertHostContact` writes the contact and reports, through its
+ * `onCreated` hook, when the write made a NEW person. This wrapper is the
+ * one place that hook is bound to `contactCreated`, and it is the function
+ * every server door calls — the forms route, the membership and newsletter
+ * handlers, the order and booking webhooks. A door that calls
+ * `upsertHostContact` directly still captures the contact and fires nothing,
+ * which is a contact no automation can welcome; `capture-host-contact.spec`
+ * scans for exactly that call.
+ *
+ * ## Why the binding lives here and not in the data library
+ *
+ * What listens for the event — the automation engine among them — imports
+ * the data library for its Firestore handle, its org helpers and its
+ * senders. The data library emitting an event would import the listeners
+ * back, which is a cycle, and the module boundaries (`scope:data` depends on
+ * data and util only) refuse it in any case. So the lower layer reports a
+ * fact and this layer, which already knows how to announce one, announces
+ * it. The alternative — a sink the runtime registers into when its module
+ * happens to be imported — would fire only in a process that had loaded the
+ * runtime, and a Stripe webhook that created a contact in a process that had
+ * not would announce nothing with no error anywhere. The listeners themselves
+ * are registered by a call made at boot (`host-event-listeners.ts`), so every
+ * process has them before its first request.
+ *
+ * Fire-and-forget in the same sense the capture itself is: the hook's
+ * failure is caught inside `upsertHostContact`, so a runner that throws
+ * costs the door nothing, and this function never rejects.
+ *
+ * ## The company, before the announcement (AGL-2613)
+ *
+ * A new person with a work email address is linked to the company at that
+ * domain here, in the same hook, BEFORE `contactCreated` goes out — so an
+ * automation that reads the new contact finds them already filed, rather
+ * than racing a link that lands a moment later. Only when the door did not
+ * name a company itself: the console's drawer and an import row that
+ * carried one have written it into the facet, and the capture must not
+ * second-guess a person's choice with a domain match. The association never
+ * rejects, and its own catch keeps a failed lookup from costing the event.
+ *
+ * ## The owner, on the same terms (AGL-2618)
+ *
+ * Then the org's assignment rules and the site's default owner decide who
+ * follows the new person up — again before `contactCreated`, so an
+ * automation's "create a task for the owner" finds one — and again only
+ * when the door named none: a drawer, an import column or a conversion
+ * that picked an owner has said whose the record is. The pass reads the
+ * form and the tags off the same options the data library was handed,
+ * because the created-report carries the identity and not the routing.
+ * It never rejects either; a record it could not assign is one somebody
+ * assigns by hand, which is what every record was before this existed.
+ *
+ * What this does NOT do is close a lead (AGL-3232): a lead is the CRM's
+ * record, and which relationship closes one is the CRM's rule, answered in
+ * its capture writer for the doors that report through the capture seam.
+ * The order doors call this directly and close nothing — a buyer with an
+ * open lead is a lead the rep converts, as in Salesforce.
+ */ export async function captureHostContact(captureOptions) {
+    const { actor } = captureOptions, options = _object_without_properties_loose(captureOptions, [
+        "actor"
+    ]);
+    return upsertHostContact(_extends({}, options, {
+        onCreated: async (created)=>{
+            var _options_facet, _options_facet1;
+            if (!((_options_facet = options.facet) == null ? void 0 : _options_facet.companyId)) {
+                await associateCompanyByDomain(created).catch((error)=>{
+                    console.error('captureHostContact company association failed', error);
+                });
+            }
+            if (!((_options_facet1 = options.facet) == null ? void 0 : _options_facet1.ownerUid)) {
+                var _options_interaction_formId;
+                await assignOwnerForCapture({
+                    hostId: created.hostId,
+                    contactId: created.contactId,
+                    email: created.email,
+                    source: created.source,
+                    formId: (_options_interaction_formId = options.interaction.formId) != null ? _options_interaction_formId : null,
+                    tags: options.tags
+                }).catch((error)=>{
+                    console.error('captureHostContact owner assignment failed', error);
+                });
+            }
+            const cause = contactCaptureActor(created.source, created.email, actor);
+            await emitHostEvent(created.hostId, 'contactCreated', contactCreatedPayload(created, options.interaction.formId), cause ? {
+                actor: cause
+            } : {});
+        }
+    }));
+}
+/**
+ * The `contactCreated` payload, as the scalars an event may carry.
+ *
+ * `HostEventPayload` holds strings, numbers and booleans and nothing
+ * nested, because the payload seeds an expression scope and a condition
+ * editor whose operators compare strings. So `campaignIds` rides as one
+ * comma-joined string — `contains` still finds a campaign in it — and is
+ * present only when the capture had campaigns, so `notEmpty` on it reads
+ * as "came in through a campaign form". `name` and `lifecycleStage` are
+ * always present, empty when the door had none, so a condition on either
+ * never sees a missing key: `lifecycleStage == "lead"` is the filter that
+ * picks the form captures out of the sign-ups (AGL-2612).
+ *
+ * `formId` rides the same way `campaignIds` does — present only when the
+ * capture came through a form — because the created-report carries the
+ * person's identity and not the routing, and the form is routing: it is
+ * read off the interaction the door was handed. Present, it is what lets a
+ * condition say `formId` equals this form and no other (AGL-2626); absent,
+ * `notEmpty` on it reads as "came in through a form".
+ */ export function contactCreatedPayload(created, formId) {
+    var _created_name, _created_lifecycleStage;
+    const form = String(formId != null ? formId : '').trim();
+    return _extends({
+        contactId: created.contactId,
+        email: created.email,
+        name: (_created_name = created.name) != null ? _created_name : '',
+        source: created.source,
+        hostId: created.hostId,
+        lifecycleStage: (_created_lifecycleStage = created.lifecycleStage) != null ? _created_lifecycleStage : ''
+    }, created.campaignIds.length ? {
+        campaignIds: created.campaignIds.join(',')
+    } : {}, form ? {
+        formId: form
+    } : {});
+}
+export default captureHostContact;
+
+//# sourceMappingURL=capture-host-contact.js.map

package/src/lib/server/capture-host-contact.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/capture-host-contact.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  type HostContactCreated,\n  upsertHostContact,\n  type UpsertHostContactOptions,\n  type UpsertHostContactVerdict,\n} from '@aglyn/tenant-data-admin'\nimport { assignOwnerForCapture } from './assign-contact-owner'\nimport { associateCompanyByDomain } from './associate-company-by-domain'\nimport { emitHostEvent } from '@aglyn/tenant-runtime/emit-host-event'\nimport { contactCaptureActor } from '@aglyn/tenant-runtime/capture-actor'\nimport type { HostEventActor, HostEventPayload } from '@aglyn/tenant-runtime/host-event-listeners'\n\n\n/**\n * THE contact capture door for a server path (AGL-2605).\n *\n * `upsertHostContact` writes the contact and reports, through its\n * `onCreated` hook, when the write made a NEW person. This wrapper is the\n * one place that hook is bound to `contactCreated`, and it is the function\n * every server door calls — the forms route, the membership and newsletter\n * handlers, the order and booking webhooks. A door that calls\n * `upsertHostContact` directly still captures the contact and fires nothing,\n * which is a contact no automation can welcome; `capture-host-contact.spec`\n * scans for exactly that call.\n *\n * ## Why the binding lives here and not in the data library\n *\n * What listens for the event — the automation engine among them — imports\n * the data library for its Firestore handle, its org helpers and its\n * senders. The data library emitting an event would import the listeners\n * back, which is a cycle, and the module boundaries (`scope:data` depends on\n * data and util only) refuse it in any case. So the lower layer reports a\n * fact and this layer, which already knows how to announce one, announces\n * it. The alternative — a sink the runtime registers into when its module\n * happens to be imported — would fire only in a process that had loaded the\n * runtime, and a Stripe webhook that created a contact in a process that had\n * not would announce nothing with no error anywhere. The listeners themselves\n * are registered by a call made at boot (`host-event-listeners.ts`), so every\n * process has them before its first request.\n *\n * Fire-and-forget in the same sense the capture itself is: the hook's\n * failure is caught inside `upsertHostContact`, so a runner that throws\n * costs the door nothing, and this function never rejects.\n *\n * ## The company, before the announcement (AGL-2613)\n *\n * A new person with a work email address is linked to the company at that\n * domain here, in the same hook, BEFORE `contactCreated` goes out — so an\n * automation that reads the new contact finds them already filed, rather\n * than racing a link that lands a moment later. Only when the door did not\n * name a company itself: the console's drawer and an import row that\n * carried one have written it into the facet, and the capture must not\n * second-guess a person's choice with a domain match. The association never\n * rejects, and its own catch keeps a failed lookup from costing the event.\n *\n * ## The owner, on the same terms (AGL-2618)\n *\n * Then the org's assignment rules and the site's default owner decide who\n * follows the new person up — again before `contactCreated`, so an\n * automation's \"create a task for the owner\" finds one — and again only\n * when the door named none: a drawer, an import column or a conversion\n * that picked an owner has said whose the record is. The pass reads the\n * form and the tags off the same options the data library was handed,\n * because the created-report carries the identity and not the routing.\n * It never rejects either; a record it could not assign is one somebody\n * assigns by hand, which is what every record was before this existed.\n *\n * What this does NOT do is close a lead (AGL-3232): a lead is the CRM's\n * record, and which relationship closes one is the CRM's rule, answered in\n * its capture writer for the doors that report through the capture seam.\n * The order doors call this directly and close nothing — a buyer with an\n * open lead is a lead the rep converts, as in Salesforce.\n */\nexport async function captureHostContact(\n  captureOptions: Omit<UpsertHostContactOptions, 'onCreated'> & {\n    /** Who caused the capture, when the door knows (AGL-3376). */\n    actor?: HostEventActor\n  },\n): Promise<UpsertHostContactVerdict> {\n  const { actor, ...options } = captureOptions\n  return upsertHostContact({\n    ...options,\n    onCreated: async (created) => {\n      if (!options.facet?.companyId) {\n        await associateCompanyByDomain(created).catch((error: unknown) => {\n          console.error('captureHostContact company association failed', error)\n        })\n      }\n      if (!options.facet?.ownerUid) {\n        await assignOwnerForCapture({\n          hostId: created.hostId,\n          contactId: created.contactId,\n          email: created.email,\n          source: created.source,\n          formId: options.interaction.formId ?? null,\n          tags: options.tags,\n        }).catch((error: unknown) => {\n          console.error('captureHostContact owner assignment failed', error)\n        })\n      }\n      const cause = contactCaptureActor(created.source, created.email, actor)\n      await emitHostEvent(\n        created.hostId,\n        'contactCreated',\n        contactCreatedPayload(created, options.interaction.formId),\n        cause ? { actor: cause } : {},\n      )\n    },\n  })\n}\n\n/**\n * The `contactCreated` payload, as the scalars an event may carry.\n *\n * `HostEventPayload` holds strings, numbers and booleans and nothing\n * nested, because the payload seeds an expression scope and a condition\n * editor whose operators compare strings. So `campaignIds` rides as one\n * comma-joined string — `contains` still finds a campaign in it — and is\n * present only when the capture had campaigns, so `notEmpty` on it reads\n * as \"came in through a campaign form\". `name` and `lifecycleStage` are\n * always present, empty when the door had none, so a condition on either\n * never sees a missing key: `lifecycleStage == \"lead\"` is the filter that\n * picks the form captures out of the sign-ups (AGL-2612).\n *\n * `formId` rides the same way `campaignIds` does — present only when the\n * capture came through a form — because the created-report carries the\n * person's identity and not the routing, and the form is routing: it is\n * read off the interaction the door was handed. Present, it is what lets a\n * condition say `formId` equals this form and no other (AGL-2626); absent,\n * `notEmpty` on it reads as \"came in through a form\".\n */\nexport function contactCreatedPayload(\n  created: HostContactCreated,\n  formId?: string | null,\n): HostEventPayload {\n  const form = String(formId ?? '').trim()\n  return {\n    contactId: created.contactId,\n    email: created.email,\n    name: created.name ?? '',\n    source: created.source,\n    hostId: created.hostId,\n    lifecycleStage: created.lifecycleStage ?? '',\n    ...(created.campaignIds.length\n      ? { campaignIds: created.campaignIds.join(',') }\n      : {}),\n    ...(form ? { formId: form } : {}),\n  }\n}\n\nexport default captureHostContact\n"],"names":["upsertHostContact","assignOwnerForCapture","associateCompanyByDomain","emitHostEvent","contactCaptureActor","captureHostContact","captureOptions","actor","options","onCreated","created","facet","companyId","catch","error","console","ownerUid","hostId","contactId","email","source","formId","interaction","tags","cause","contactCreatedPayload","form","String","trim","name","lifecycleStage","campaignIds","length","join"],"mappings":";;AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAEEA,iBAAiB,QAGZ,2BAA0B;AACjC,SAASC,qBAAqB,QAAQ,4BAAwB;AAC9D,SAASC,wBAAwB,QAAQ,mCAA+B;AACxE,SAASC,aAAa,QAAQ,wCAAuC;AACrE,SAASC,mBAAmB,QAAQ,sCAAqC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2DC,GACD,OAAO,eAAeC,mBACpBC,cAGC;IAED,MAAM,EAAEC,KAAK,EAAc,GAAGD,gBAAZE,2CAAYF;;;IAC9B,OAAON,kBAAkB,aACpBQ;QACHC,WAAW,OAAOC;gBACXF,gBAKAA;YALL,IAAI,GAACA,iBAAAA,QAAQG,KAAK,qBAAbH,eAAeI,SAAS,GAAE;gBAC7B,MAAMV,yBAAyBQ,SAASG,KAAK,CAAC,CAACC;oBAC7CC,QAAQD,KAAK,CAAC,iDAAiDA;gBACjE;YACF;YACA,IAAI,GAACN,kBAAAA,QAAQG,KAAK,qBAAbH,gBAAeQ,QAAQ,GAAE;oBAMlBR;gBALV,MAAMP,sBAAsB;oBAC1BgB,QAAQP,QAAQO,MAAM;oBACtBC,WAAWR,QAAQQ,SAAS;oBAC5BC,OAAOT,QAAQS,KAAK;oBACpBC,QAAQV,QAAQU,MAAM;oBACtBC,MAAM,GAAEb,8BAAAA,QAAQc,WAAW,CAACD,MAAM,YAA1Bb,8BAA8B;oBACtCe,MAAMf,QAAQe,IAAI;gBACpB,GAAGV,KAAK,CAAC,CAACC;oBACRC,QAAQD,KAAK,CAAC,8CAA8CA;gBAC9D;YACF;YACA,MAAMU,QAAQpB,oBAAoBM,QAAQU,MAAM,EAAEV,QAAQS,KAAK,EAAEZ;YACjE,MAAMJ,cACJO,QAAQO,MAAM,EACd,kBACAQ,sBAAsBf,SAASF,QAAQc,WAAW,CAACD,MAAM,GACzDG,QAAQ;gBAAEjB,OAAOiB;YAAM,IAAI,CAAC;QAEhC;;AAEJ;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,sBACdf,OAA2B,EAC3BW,MAAsB;QAMdX,eAGUA;IAPlB,MAAMgB,OAAOC,OAAON,iBAAAA,SAAU,IAAIO,IAAI;IACtC,OAAO;QACLV,WAAWR,QAAQQ,SAAS;QAC5BC,OAAOT,QAAQS,KAAK;QACpBU,IAAI,GAAEnB,gBAAAA,QAAQmB,IAAI,YAAZnB,gBAAgB;QACtBU,QAAQV,QAAQU,MAAM;QACtBH,QAAQP,QAAQO,MAAM;QACtBa,cAAc,GAAEpB,0BAAAA,QAAQoB,cAAc,YAAtBpB,0BAA0B;OACtCA,QAAQqB,WAAW,CAACC,MAAM,GAC1B;QAAED,aAAarB,QAAQqB,WAAW,CAACE,IAAI,CAAC;IAAK,IAC7C,CAAC,GACDP,OAAO;QAAEL,QAAQK;IAAK,IAAI,CAAC;AAEnC;AAEA,eAAerB,mBAAkB"}

package/src/lib/server/company-children.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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.
+ */
+/**
+ * Clear `parentCompanyId` on at most `limit` companies under `companyId`
+ * (AGL-3514), and say whether more remain. Shared by `crm/company-delete`
+ * and the REST resource's delete, which calls it until none remain.
+ */
+export declare function detachChildCompanies(firestore: FirebaseFirestore.Firestore, companies: FirebaseFirestore.CollectionReference, companyId: string, limit?: number): Promise<{
+    detached: number;
+    moreRemain: boolean;
+}>;

package/src/lib/server/company-children.js

@@ -0,0 +1,42 @@
+/**
+ * @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 { FieldValue } from "firebase-admin/firestore";
+import { COMPANY_DETACH_LIMIT } from "../model/company-delete-route.js";
+/**
+ * Clear `parentCompanyId` on at most `limit` companies under `companyId`
+ * (AGL-3514), and say whether more remain. Shared by `crm/company-delete`
+ * and the REST resource's delete, which calls it until none remain.
+ */ export async function detachChildCompanies(firestore, companies, companyId, limit = COMPANY_DETACH_LIMIT) {
+    // One past the bound, so "more remain" is a fact from the probe row.
+    const probe = await companies.where('parentCompanyId', '==', companyId).limit(limit + 1).get();
+    const children = probe.docs.slice(0, limit);
+    if (children.length) {
+        const batch = firestore.batch();
+        for (const child of children){
+            batch.update(child.ref, {
+                parentCompanyId: FieldValue.delete(),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+        }
+        await batch.commit();
+    }
+    return {
+        detached: children.length,
+        moreRemain: probe.docs.length > limit
+    };
+}
+
+//# sourceMappingURL=company-children.js.map