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

package/src/lib/server/assign-contact-owner.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/assign-contact-owner.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  assignmentRuleMatches,\n  consentGroupForHost,\n  contactFacetPath,\n  type ContactSource,\n  CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH,\n  type CrmAssignmentTarget,\n  personKey,\n  readContactFacet,\n  readCrmAssignmentSettings,\n  roundRobinOrder,\n} from '@aglyn/aglyn/server'\nimport {\n  firebaseAdmin,\n  getHostDocAdmin,\n  getOrgForHost,\n  hostDisplayName,\n  notifyUsers,\n  restampCrmListFieldsAt,\n} from '@aglyn/tenant-data-admin'\nimport { FieldValue } from 'firebase-admin/firestore'\n\n/**\n * WHO A NEW RECORD BELONGS TO — the one place an owner is decided on the\n * server (AGL-2618).\n *\n * Two entry points over one transaction. `assignOwnerForCapture` is the\n * capture door's pass: it runs the org's assignment rules in order, falls\n * back to the capturing site's default owner, and touches only a record\n * that has NO owner — a door that named one (the console's drawer, an\n * import column, a conversion with a picked owner) has expressed a person's\n * choice. `reassignContactOwner` is the automation's: an author who put\n * \"assign an owner\" on a stage change means to reassign, and the step hands\n * this either a member or the rotation.\n *\n * ## One transaction, because the pointer is shared\n *\n * The round-robin pool's pointer lives on the org document, and two\n * captures landing together must take two different members. Firestore\n * transactions serialize on what they read, so the org document, the\n * contact and the roster documents are all read inside the transaction and\n * the pointer is advanced in the same commit that writes the owner: a\n * concurrent capture that read the same pointer retries and reads the moved\n * one. The alternative — read the pointer, decide, then write — is exactly\n * the read-then-write shape that lets two captures pick the same person.\n *\n * ## The roster is checked, once per member per attempt\n *\n * A rule may name a member who has since left, and a pool may hold one. A\n * rule naming nobody on the roster is passed over rather than stopping the\n * pass — the next rule may well assign — and a pool member who is gone is\n * skipped for the next in the order. `orgs/{orgId}/members/{uid}` is keyed\n * by uid, so the check is one document read per candidate, and only the\n * roster is consulted: a project-level Auth lookup would admit people who\n * are not on this organization at all (AGL-1122).\n *\n * ## The lead follows the contact\n *\n * The capture doors that file a lead (`addHostLead`: a form routed to leads,\n * a sign-up, a booking) key it by `personKey(email)`, so the lead's document\n * is addressable from the capture alone. When it exists it is given the same\n * owner in the same transaction; two doors write the lead AFTER the contact\n * they `void`ed, so for those sources the mirror is retried a few times over\n * the next seconds, detached, and the person's Leads list shows the owner\n * as soon as the lead is there.\n *\n * ## The owner is told, unless they chose themselves\n *\n * One console notification per assignment, for the record the recipient\n * will open: the lead when the site holds one for this person, the contact\n * otherwise. Not when the actor IS the new owner — a rep who converts a\n * lead into their own contact has not been handed anything.\n *\n * ## Never rejects\n *\n * The capture has already succeeded and a form submission must not fail\n * because the CRM could not decide who follows up; a failure is logged and\n * answered as `none`, and the record is exactly as assignable by hand as it\n * was before this existed. The automation executor turns a `none` into the\n * step's recorded error.\n */\n\nexport interface OwnerAssignmentInput {\n  hostId: string\n  /** `orgs/{orgId}/contacts/{contactId}` — the record the owner is written on. */\n  contactId: string\n  /** The contact's address, which keys the lead and names the person in the notification. */\n  email: string\n  /**\n   * The signed-in person making the assignment, when there is one. Never\n   * notified about their own choice; absent for a capture and an automation.\n   */\n  actorUid?: string | null\n}\n\nexport interface CaptureAssignmentInput extends OwnerAssignmentInput {\n  source: ContactSource\n  /** The form the capture came through, for a rule conditioned on it. */\n  formId?: string | null\n  /** The tags the capture carried; the contact's own are read from the facet. */\n  tags?: readonly string[]\n}\n\nexport interface ReassignmentInput extends OwnerAssignmentInput {\n  assign: CrmAssignmentTarget\n}\n\n/** Why an assignment assigned nobody — the automation reports these verbatim. */\nexport type OwnerAssignmentRefusal =\n  | 'no-org'\n  | 'no-contact'\n  | 'no-lead'\n  | 'no-rule'\n  | 'empty-pool'\n  | 'not-a-member'\n  | 'failed'\n\n/** What decided an assignment: a rule, the site default, the step's member, or the rotation. */\nexport type OwnerAssignedBy = 'rule' | 'default' | 'member' | 'roundRobin'\n\nexport type OwnerAssignment =\n  | {\n      outcome: 'assigned'\n      ownerUid: string\n      by: OwnerAssignedBy\n      /** The rule that decided it, when one did. */\n      ruleId?: string\n      /** The lead document existed and now carries the owner too. */\n      leadMirrored: boolean\n      /** A notification was fanned out to the new owner. */\n      notified: boolean\n    }\n  /** The record already had this owner (a capture), or the same one was named again (a reassignment). */\n  | { outcome: 'unchanged'; ownerUid: string }\n  | { outcome: 'none'; reason: OwnerAssignmentRefusal }\n\n/** The words the run history and the log give each refusal. */\nexport const OWNER_ASSIGNMENT_REFUSALS: Record<OwnerAssignmentRefusal, string> = {\n  'no-org': 'this site has no organization',\n  'no-contact': 'the contact no longer exists',\n  'no-lead': 'the lead no longer exists',\n  'no-rule': 'no assignment rule matched and the site has no default owner',\n  'empty-pool': 'the round-robin pool has nobody on the roster in it',\n  'not-a-member': 'the owner named is not on the team',\n  failed: 'the owner could not be assigned',\n}\n\n/**\n * The doors whose lead lands after the contact they `void`ed — the ones the\n * mirror is worth retrying for. An order, an import, a manual add and an\n * API call file no lead, and a retry for them would be reads for nothing.\n */\nconst LEAD_FILING_SOURCES: ReadonlySet<ContactSource> = new Set([\n  'form',\n  'member',\n  'booking',\n])\n\n/** How long the detached lead mirror waits between its looks, in order. */\nconst LEAD_MIRROR_RETRY_MS: readonly number[] = [1_000, 2_000, 3_000]\n\ntype Policy =\n  | { kind: 'capture'; input: CaptureAssignmentInput }\n  | { kind: 'reassign'; input: ReassignmentInput }\n\ninterface Decision {\n  ownerUid: string\n  by: OwnerAssignedBy\n  ruleId?: string\n  /** The pointer moves only when the rotation chose. */\n  advancePointer: boolean\n}\n\n/**\n * The console path the owner's notification opens, in the `/{hostDocId}/rest`\n * shape every host notification uses — the console rewrites it to\n * `/{orgSlug}/hosts/{subdomain}/rest` when the link is followed, which is\n * why `hostId` and `orgId` travel on the document. The same spelling the\n * CRM's task notification uses; the hub's own route builder lives in the\n * plugin, which this layer cannot import.\n */\nfunction recordLink(hostId: string, record: AssignedRecord): string {\n  const section = record.kind === 'contact' ? 'contacts' : 'leads'\n  return `/${hostId}/crm/${section}/${encodeURIComponent(record.id)}`\n}\n\n/** The record an assignment notification opens. */\nexport type AssignedRecord =\n  | { kind: 'contact'; id: string }\n  | { kind: 'lead'; id: string }\n\n/**\n * Tells a member a record is now theirs — one console notification, typed\n * by the record it opens — unless the member handed it to themselves.\n * Shared by the pass above and by the routes where a person picks the\n * owner outright (a lead conversion naming a colleague), so every server\n * path that writes `ownerUid` says so in the same words. Never throws;\n * the fan-out swallows its own failures.\n */\nexport async function notifyRecordAssigned(input: {\n  hostId: string\n  orgId: string\n  ownerUid: string\n  actorUid?: string | null\n  record: AssignedRecord\n  /** How the person reads in the message: their name, else their address. */\n  who: string\n}): Promise<boolean> {\n  if (!input.ownerUid || input.ownerUid === (input.actorUid ?? '')) return false\n  const lead = input.record.kind === 'lead'\n  /*\n   * THE BODY SAYS WHAT HAPPENED, AND ON WHICH SITE (AGL-3432).\n   *\n   * It was the bare name, so a member who owns records on several sites read\n   * \"Ada\" in an email body and could not tell what Ada was or where. The\n   * site's name is one request-cached read of a document most callers have\n   * already paid for, taken only when somebody is actually notified; a read\n   * that fails drops the \"on {site}\" clause rather than the notification.\n   */\n  let site = ''\n  try {\n    const host = await getHostDocAdmin(input.hostId)\n    if (host) site = ` on ${hostDisplayName(host, input.hostId)}`\n  } catch {\n    // The clause goes, never the notification.\n  }\n  await notifyUsers([input.ownerUid], {\n    type: lead ? 'content.leadAssigned' : 'content.contactAssigned',\n    title: lead ? 'Lead assigned to you' : 'Contact assigned to you',\n    body: `${input.who} was assigned to you as a ${lead ? 'lead' : 'contact'}${site}.`,\n    link: recordLink(input.hostId, input.record),\n    orgId: input.orgId,\n    hostId: input.hostId,\n  })\n  return true\n}\n\n/**\n * The roster checks one assignment transaction makes: whether a uid is on the\n * team, and who a target names — a member as named, or the next member of\n * the round-robin pool who is still on the roster. One read per candidate\n * per attempt; a retried transaction builds a fresh one and reads afresh, as\n * it must.\n */\nfunction rosterResolver(\n  tx: FirebaseFirestore.Transaction,\n  membersRef: FirebaseFirestore.CollectionReference,\n  settings: ReturnType<typeof readCrmAssignmentSettings>,\n): {\n  isMember: (uid: string) => Promise<boolean>\n  resolveTarget: (\n    target: CrmAssignmentTarget,\n  ) => Promise<{ uid: string; advancePointer: boolean } | null>\n} {\n  const onRoster = new Map<string, Promise<boolean>>()\n  const isMember = (uid: string): Promise<boolean> => {\n    let known = onRoster.get(uid)\n    if (!known) {\n      known = tx.get(membersRef.doc(uid)).then((snapshot) => snapshot.exists)\n      onRoster.set(uid, known)\n    }\n    return known\n  }\n  const fromPool = async (): Promise<string | null> => {\n    for (const uid of roundRobinOrder(\n      settings.pool.memberUids,\n      settings.pool.lastAssignedUid,\n    )) {\n      if (await isMember(uid)) return uid\n    }\n    return null\n  }\n  const resolveTarget = async (\n    target: CrmAssignmentTarget,\n  ): Promise<{ uid: string; advancePointer: boolean } | null> => {\n    if ('roundRobin' in target) {\n      const uid = await fromPool()\n      return uid ? { uid, advancePointer: true } : null\n    }\n    return (await isMember(target.memberUid))\n      ? { uid: target.memberUid, advancePointer: false }\n      : null\n  }\n  return { isMember, resolveTarget }\n}\n\nasync function assignOwner(policy: Policy): Promise<OwnerAssignment> {\n  const { input } = policy\n  try {\n    const resolved = await getOrgForHost(input.hostId)\n    if (!resolved) return { outcome: 'none', reason: 'no-org' }\n    const { orgId } = resolved\n    const firestore = firebaseAdmin.app().firestore()\n    const orgRef = firestore.collection('orgs').doc(orgId)\n    const contactRef = orgRef.collection('contacts').doc(input.contactId)\n    const membersRef = orgRef.collection('members')\n    const leadKey = personKey(input.email)\n    // Beside the contact on the org, keyed by the same address (AGL-3275).\n    const leadRef = leadKey ? orgRef.collection('leads').doc(leadKey) : null\n\n    let contactName = ''\n    const verdict = await firestore.runTransaction(\n      async (tx): Promise<OwnerAssignment> => {\n        /*\n         * ALL READS BEFORE THE WRITE, which Firestore requires. The org\n         * document is read here rather than trusted from `getOrgForHost`,\n         * because the pointer it carries is the one thing a concurrent\n         * capture may have moved, and the rules and the pool are read from\n         * the same snapshot so the decision and the pointer agree.\n         */\n        const [orgSnapshot, contactSnapshot, leadSnapshot] = await Promise.all([\n          tx.get(orgRef),\n          tx.get(contactRef),\n          leadRef ? tx.get(leadRef) : Promise.resolve(null),\n        ])\n        if (!contactSnapshot.exists) {\n          return { outcome: 'none', reason: 'no-contact' }\n        }\n        const org = (orgSnapshot.data() ?? {}) as Record<string, unknown>\n        const contact = (contactSnapshot.data() ?? {}) as Record<string, unknown>\n        contactName = String(contact['name'] ?? '')\n        const group = consentGroupForHost(org, input.hostId)\n        const facet = readContactFacet(contact, group.groupId)\n        const current = typeof facet.ownerUid === 'string' ? facet.ownerUid : ''\n        if (policy.kind === 'capture' && current) {\n          return { outcome: 'unchanged', ownerUid: current }\n        }\n        const settings = readCrmAssignmentSettings(org)\n        const { isMember, resolveTarget } = rosterResolver(tx, membersRef, settings)\n\n        let decision: Decision | null = null\n        let refusal: OwnerAssignmentRefusal = 'no-rule'\n        if (policy.kind === 'capture') {\n          const capture = {\n            source: policy.input.source,\n            email: input.email,\n            formId: policy.input.formId ?? null,\n            tags: [...(policy.input.tags ?? []), ...(facet.tags ?? [])],\n          }\n          for (const rule of settings.rules) {\n            if (!assignmentRuleMatches(rule.when, capture)) continue\n            const hit = await resolveTarget(rule.assign)\n            if (hit) {\n              decision = { ...hit, ownerUid: hit.uid, by: 'rule', ruleId: rule.id }\n              break\n            }\n          }\n          const fallback = settings.hostDefaultOwners[input.hostId]\n          if (!decision && fallback && (await isMember(fallback))) {\n            decision = { ownerUid: fallback, by: 'default', advancePointer: false }\n          }\n        } else {\n          const { assign } = policy.input\n          const hit = await resolveTarget(assign)\n          if (hit) {\n            decision = {\n              ...hit,\n              ownerUid: hit.uid,\n              by: 'roundRobin' in assign ? 'roundRobin' : 'member',\n            }\n          } else {\n            refusal = 'roundRobin' in assign ? 'empty-pool' : 'not-a-member'\n          }\n        }\n        if (!decision) return { outcome: 'none', reason: refusal }\n        if (decision.ownerUid === current) {\n          return { outcome: 'unchanged', ownerUid: current }\n        }\n\n        tx.update(contactRef, {\n          [contactFacetPath(group.groupId, 'ownerUid')]: decision.ownerUid,\n          updatedAt: FieldValue.serverTimestamp(),\n        })\n        if (decision.advancePointer) {\n          tx.update(orgRef, {\n            [CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH]: decision.ownerUid,\n          })\n        }\n        /*\n         * A lead somebody already assigned by hand keeps its owner on a\n         * capture — the contact was new, the lead may not have been — and\n         * follows the contact on a deliberate reassignment.\n         */\n        const leadOwner = String(leadSnapshot?.get('ownerUid') ?? '')\n        const leadMirrored = Boolean(\n          leadSnapshot?.exists && (policy.kind === 'reassign' || !leadOwner),\n        )\n        if (leadMirrored && leadRef) {\n          tx.update(leadRef, {\n            ownerUid: decision.ownerUid,\n            updatedAt: FieldValue.serverTimestamp(),\n          })\n        }\n        return {\n          outcome: 'assigned',\n          ownerUid: decision.ownerUid,\n          by: decision.by,\n          ...(decision.ruleId ? { ruleId: decision.ruleId } : {}),\n          leadMirrored,\n          notified: false,\n        }\n      },\n    )\n    if (verdict.outcome !== 'assigned') return verdict\n    // The owner is what the Contacts list filters by (AGL-3321).\n    await restampCrmListFieldsAt(contactRef, 'contacts')\n\n    if (\n      !verdict.leadMirrored &&\n      leadRef &&\n      policy.kind === 'capture' &&\n      LEAD_FILING_SOURCES.has(policy.input.source)\n    ) {\n      void mirrorOwnerOntoLeadLater(leadRef, verdict.ownerUid)\n    }\n\n    const notified = await notifyRecordAssigned({\n      hostId: input.hostId,\n      orgId,\n      ownerUid: verdict.ownerUid,\n      actorUid: input.actorUid,\n      record:\n        verdict.leadMirrored && leadKey\n          ? { kind: 'lead', id: leadKey }\n          : { kind: 'contact', id: input.contactId },\n      who: contactName || input.email,\n    })\n    return { ...verdict, notified }\n  } catch (error) {\n    console.error(\n      'assignContactOwner failed',\n      input.hostId,\n      input.contactId,\n      error,\n    )\n    return { outcome: 'none', reason: 'failed' }\n  }\n}\n\n/**\n * The detached second look for a lead that lands after the contact.\n *\n * Bounded, and only ever ADDS an owner: a lead that arrived with one (a\n * person assigned it in the meantime) is left alone, and a lead that never\n * arrives costs three reads over six seconds and nothing else. Detached\n * because the capture must not hold `contactCreated` back for it — an\n * automation welcoming the contact has nothing to do with the lead's owner\n * column.\n */\nasync function mirrorOwnerOntoLeadLater(\n  leadRef: FirebaseFirestore.DocumentReference,\n  ownerUid: string,\n  delaysMs: readonly number[] = LEAD_MIRROR_RETRY_MS,\n): Promise<boolean> {\n  for (const delay of delaysMs) {\n    await new Promise((resolve) => setTimeout(resolve, delay))\n    try {\n      const lead = await leadRef.get()\n      if (!lead.exists) continue\n      if (String(lead.get('ownerUid') ?? '')) return false\n      await leadRef.update({\n        ownerUid,\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n      return true\n    } catch (error) {\n      console.error('assignContactOwner lead mirror failed', leadRef.path, error)\n      return false\n    }\n  }\n  return false\n}\n\n/**\n * The capture door's pass: the org's rules in order, then the capturing\n * site's default owner, on a record that has no owner yet. See the module\n * comment for the whole of it.\n */\nexport function assignOwnerForCapture(\n  input: CaptureAssignmentInput,\n): Promise<OwnerAssignment> {\n  return assignOwner({ kind: 'capture', input })\n}\n\n/**\n * The deliberate assignment — the `assignContactOwner` step, and a person\n * handing a record to somebody: a member by uid (verified on the roster) or\n * the next in the round-robin pool, overwriting whoever held it. Naming the\n * owner the record already has changes nothing and tells nobody.\n */\nexport function reassignContactOwner(\n  input: ReassignmentInput,\n): Promise<OwnerAssignment> {\n  return assignOwner({ kind: 'reassign', input })\n}\n\n/** The deliberate assignment of a LEAD the site holds and no contact has absorbed yet. */\nexport interface LeadReassignmentInput {\n  hostId: string\n  /** `orgs/{orgId}/leads/{leadId}` — the person's key. */\n  leadId: string\n  assign: CrmAssignmentTarget\n  /** As {@link OwnerAssignmentInput.actorUid}: never told about their own choice. */\n  actorUid?: string | null\n}\n\n/**\n * {@link reassignContactOwner} for a person who is still a LEAD (AGL-3458).\n *\n * A lead-routed form files a lead and no contact (AGL-3232), so an\n * automation welcoming that person — \"assign an owner, then book them a\n * call\" — has only the lead to act on. The owner is the lead's own\n * `ownerUid`, the field the Leads list's Owner column and filter read and a\n * conversion hands to the contact. Same transaction shape as a contact's:\n * the org document, the lead and every roster candidate are read inside it,\n * and the round-robin pointer moves in the commit that writes the owner, so\n * a lead and a contact assigned at the same moment take two different\n * members of the one rotation.\n *\n * Never rejects; a failure is logged and answered as `none`, which the\n * automation records as the step's error.\n */\nexport async function reassignLeadOwner(\n  input: LeadReassignmentInput,\n): Promise<OwnerAssignment> {\n  try {\n    const resolved = await getOrgForHost(input.hostId)\n    if (!resolved) return { outcome: 'none', reason: 'no-org' }\n    const { orgId } = resolved\n    const firestore = firebaseAdmin.app().firestore()\n    const orgRef = firestore.collection('orgs').doc(orgId)\n    const leadRef = orgRef.collection('leads').doc(input.leadId)\n    const membersRef = orgRef.collection('members')\n    let who = ''\n    const verdict = await firestore.runTransaction(\n      async (tx): Promise<OwnerAssignment> => {\n        const [orgSnapshot, leadSnapshot] = await Promise.all([\n          tx.get(orgRef),\n          tx.get(leadRef),\n        ])\n        if (!leadSnapshot.exists) return { outcome: 'none', reason: 'no-lead' }\n        const lead = (leadSnapshot.data() ?? {}) as Record<string, unknown>\n        who = String(lead['name'] ?? '') || String(lead['email'] ?? '')\n        const current = String(lead['ownerUid'] ?? '')\n        const settings = readCrmAssignmentSettings(\n          (orgSnapshot.data() ?? {}) as Record<string, unknown>,\n        )\n        const { resolveTarget } = rosterResolver(tx, membersRef, settings)\n        const hit = await resolveTarget(input.assign)\n        if (!hit) {\n          return {\n            outcome: 'none',\n            reason: 'roundRobin' in input.assign ? 'empty-pool' : 'not-a-member',\n          }\n        }\n        if (hit.uid === current) return { outcome: 'unchanged', ownerUid: current }\n        tx.update(leadRef, {\n          ownerUid: hit.uid,\n          updatedAt: FieldValue.serverTimestamp(),\n        })\n        if (hit.advancePointer) {\n          tx.update(orgRef, { [CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH]: hit.uid })\n        }\n        return {\n          outcome: 'assigned',\n          ownerUid: hit.uid,\n          by: 'roundRobin' in input.assign ? 'roundRobin' : 'member',\n          leadMirrored: false,\n          notified: false,\n        }\n      },\n    )\n    if (verdict.outcome !== 'assigned') return verdict\n    const notified = await notifyRecordAssigned({\n      hostId: input.hostId,\n      orgId,\n      ownerUid: verdict.ownerUid,\n      actorUid: input.actorUid,\n      record: { kind: 'lead', id: input.leadId },\n      who,\n    })\n    return { ...verdict, notified }\n  } catch (error) {\n    console.error('assignLeadOwner failed', input.hostId, input.leadId, error)\n    return { outcome: 'none', reason: 'failed' }\n  }\n}\n\nexport default assignOwnerForCapture\n"],"names":["assignmentRuleMatches","consentGroupForHost","contactFacetPath","CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH","personKey","readContactFacet","readCrmAssignmentSettings","roundRobinOrder","firebaseAdmin","getHostDocAdmin","getOrgForHost","hostDisplayName","notifyUsers","restampCrmListFieldsAt","FieldValue","OWNER_ASSIGNMENT_REFUSALS","failed","LEAD_FILING_SOURCES","Set","LEAD_MIRROR_RETRY_MS","recordLink","hostId","record","section","kind","encodeURIComponent","id","notifyRecordAssigned","input","ownerUid","actorUid","lead","site","host","type","title","body","who","link","orgId","rosterResolver","tx","membersRef","settings","onRoster","Map","isMember","uid","known","get","doc","then","snapshot","exists","set","fromPool","pool","memberUids","lastAssignedUid","resolveTarget","target","advancePointer","memberUid","assignOwner","policy","resolved","outcome","reason","firestore","app","orgRef","collection","contactRef","contactId","leadKey","email","leadRef","contactName","verdict","runTransaction","orgSnapshot","contactSnapshot","contact","leadSnapshot","Promise","all","resolve","org","data","String","group","facet","groupId","current","decision","refusal","capture","source","formId","tags","rule","rules","when","hit","assign","by","ruleId","fallback","hostDefaultOwners","update","updatedAt","serverTimestamp","leadOwner","leadMirrored","Boolean","notified","has","mirrorOwnerOntoLeadLater","error","console","delaysMs","delay","setTimeout","path","assignOwnerForCapture","reassignContactOwner","reassignLeadOwner","leadId"],"mappings":"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"}

package/src/lib/server/associate-company-by-domain.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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 } from '@aglyn/tenant-data-admin';
+/** What the association did, for the spec and the log. */
+export type CompanyAssociation = {
+    outcome: 'linked' | 'created';
+    companyId: string;
+} | {
+    outcome: 'none';
+    reason: 'no-domain' | 'no-org' | 'ambiguous' | 'no-match' | 'failed';
+};
+/**
+ * Link a NEW contact to the company its email domain names (AGL-2613).
+ *
+ * HubSpot associates a contact with a company on domain the moment the
+ * contact exists, and that is the moment this runs: once, from the capture
+ * door, for a person the org did not hold before. A repeat visit by somebody
+ * already held is not a new person and re-asks nothing; a door that already
+ * knew the company — the console's create drawer, an import row naming one
+ * — has said so in the facet and this is not called at all.
+ *
+ * ## Bounded: one query, one commit
+ *
+ * The query is `companies where domain == d and visibleTo array-contains-any
+ * (the capturing scope's read tokens)`, capped at two — the `(visibleTo
+ * CONTAINS, domain ASC)` composite serves it. Two rather than one because
+ * the answer has to be "exactly one": two companies at one domain visible
+ * to this site is an ambiguity a capture must not resolve by picking the
+ * first, and the contact waits for a person. The scope predicate is the
+ * console's own listener predicate, so a company this site could not open
+ * is not a match — an agency's client at `acme.com` is not linked to a
+ * sibling client's Acme.
+ *
+ * The write is one batch: the facet and the mirror on the contact, and the
+ * count on the company. The contact is fresh, so the plan is the trivial
+ * one — no previous link, nothing held elsewhere — and needs no read of the
+ * document.
+ *
+ * ## Creating is a setting, and off by default
+ *
+ * With `crm.autoCreateCompanies` on the org document, a domain no visible
+ * company carries becomes one, named after the domain and scoped exactly as
+ * the contact was — `crmScopeTokens`, the stamp every CRM creator uses —
+ * with the count starting at one. Public mailbox domains never reach this
+ * branch, because `companyDomainForEmail` answers `null` for them: a
+ * workspace's consumer list is not a list of accounts.
+ *
+ * ## The same posture as the capture
+ *
+ * Never throws. The capture has already succeeded and a form submission
+ * must not fail because the CRM could not file its author; a failure is
+ * logged and answered as `none`, and the person is exactly as capturable
+ * by hand as they were before this existed.
+ */
+export declare function associateCompanyByDomain(created: Pick<HostContactCreated, 'hostId' | 'contactId' | 'email'>): Promise<CompanyAssociation>;
+export default associateCompanyByDomain;

package/src/lib/server/associate-company-by-domain.js

@@ -0,0 +1,153 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { companyDomainForEmail, companyNameForDomain, CRM_COLLECTIONS, crmReadTokens, crmScopeTokens, nameSearchFields, orgAutoCreatesCompanies } from "@aglyn/aglyn/server";
+import { consentGroupForSite, contactCompanyLinkFields, firebaseAdmin, getOrgForHost, restampCrmListFieldsAt, writeContactCompanyLink } from "@aglyn/tenant-data-admin";
+import { COMPANY_CONTACTS_COUNT_FIELD, crmNewRecordListFields, planContactCompanyLink } from "@aglyn/aglyn/server";
+import { FieldValue } from "firebase-admin/firestore";
+/**
+ * Link a NEW contact to the company its email domain names (AGL-2613).
+ *
+ * HubSpot associates a contact with a company on domain the moment the
+ * contact exists, and that is the moment this runs: once, from the capture
+ * door, for a person the org did not hold before. A repeat visit by somebody
+ * already held is not a new person and re-asks nothing; a door that already
+ * knew the company — the console's create drawer, an import row naming one
+ * — has said so in the facet and this is not called at all.
+ *
+ * ## Bounded: one query, one commit
+ *
+ * The query is `companies where domain == d and visibleTo array-contains-any
+ * (the capturing scope's read tokens)`, capped at two — the `(visibleTo
+ * CONTAINS, domain ASC)` composite serves it. Two rather than one because
+ * the answer has to be "exactly one": two companies at one domain visible
+ * to this site is an ambiguity a capture must not resolve by picking the
+ * first, and the contact waits for a person. The scope predicate is the
+ * console's own listener predicate, so a company this site could not open
+ * is not a match — an agency's client at `acme.com` is not linked to a
+ * sibling client's Acme.
+ *
+ * The write is one batch: the facet and the mirror on the contact, and the
+ * count on the company. The contact is fresh, so the plan is the trivial
+ * one — no previous link, nothing held elsewhere — and needs no read of the
+ * document.
+ *
+ * ## Creating is a setting, and off by default
+ *
+ * With `crm.autoCreateCompanies` on the org document, a domain no visible
+ * company carries becomes one, named after the domain and scoped exactly as
+ * the contact was — `crmScopeTokens`, the stamp every CRM creator uses —
+ * with the count starting at one. Public mailbox domains never reach this
+ * branch, because `companyDomainForEmail` answers `null` for them: a
+ * workspace's consumer list is not a list of accounts.
+ *
+ * ## The same posture as the capture
+ *
+ * Never throws. The capture has already succeeded and a form submission
+ * must not fail because the CRM could not file its author; a failure is
+ * logged and answered as `none`, and the person is exactly as capturable
+ * by hand as they were before this existed.
+ */ export async function associateCompanyByDomain(created) {
+    const domain = companyDomainForEmail(created.email);
+    if (!domain) return {
+        outcome: 'none',
+        reason: 'no-domain'
+    };
+    try {
+        const resolved = await getOrgForHost(created.hostId);
+        if (!resolved) return {
+            outcome: 'none',
+            reason: 'no-org'
+        };
+        const org = resolved.org;
+        const group = await consentGroupForSite(created.hostId, org);
+        const firestore = firebaseAdmin.app().firestore();
+        const orgRef = firestore.collection('orgs').doc(resolved.orgId);
+        const companiesRef = orgRef.collection(CRM_COLLECTIONS.companies);
+        const contactRef = orgRef.collection('contacts').doc(created.contactId);
+        const matches = await companiesRef.where('domain', '==', domain).where('visibleTo', 'array-contains-any', crmReadTokens(group)).limit(2).get();
+        if (matches.size > 1) return {
+            outcome: 'none',
+            reason: 'ambiguous'
+        };
+        if (matches.size === 1) {
+            const companyId = matches.docs[0].id;
+            await writeContactCompanyLink({
+                firestore,
+                contactRef,
+                contact: null,
+                companiesRef,
+                groupId: group.groupId,
+                companyId
+            });
+            return {
+                outcome: 'linked',
+                companyId
+            };
+        }
+        if (!orgAutoCreatesCompanies(org)) {
+            return {
+                outcome: 'none',
+                reason: 'no-match'
+            };
+        }
+        /*
+     * The company and the link in one commit, so a company never exists
+     * with a count of one and no contact naming it — or the reverse. The
+     * count is written as a value rather than an increment because the
+     * document is being created in the same batch, and the plan's `+1` is
+     * exactly what a fresh company with one contact stores.
+     */ const plan = planContactCompanyLink({
+            companyId: null,
+            companyIds: [],
+            heldElsewhere: []
+        }, companiesRef.doc().id);
+        if (!(plan == null ? void 0 : plan.companyId)) return {
+            outcome: 'none',
+            reason: 'failed'
+        };
+        const companyRef = companiesRef.doc(plan.companyId);
+        const batch = firestore.batch();
+        const company = _extends({}, nameSearchFields(companyNameForDomain(domain)), {
+            domain,
+            visibleTo: crmScopeTokens(org, group),
+            hostId: created.hostId,
+            [COMPANY_CONTACTS_COUNT_FIELD]: 1,
+            createdAt: FieldValue.serverTimestamp(),
+            updatedAt: FieldValue.serverTimestamp()
+        });
+        batch.set(companyRef, _extends({}, company, crmNewRecordListFields('companies', company)));
+        batch.update(contactRef, _extends({}, contactCompanyLinkFields(plan, group.groupId), {
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        await batch.commit();
+        // The company is what the Contacts list filters by (AGL-3321).
+        await restampCrmListFieldsAt(contactRef, 'contacts');
+        return {
+            outcome: 'created',
+            companyId: plan.companyId
+        };
+    } catch (error) {
+        console.error('associateCompanyByDomain failed', created.hostId, created.contactId, error);
+        return {
+            outcome: 'none',
+            reason: 'failed'
+        };
+    }
+}
+export default associateCompanyByDomain;
+
+//# sourceMappingURL=associate-company-by-domain.js.map

package/src/lib/server/associate-company-by-domain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/associate-company-by-domain.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  companyDomainForEmail,\n  companyNameForDomain,\n  CRM_COLLECTIONS,\n  crmReadTokens,\n  crmScopeTokens,\n  nameSearchFields,\n  orgAutoCreatesCompanies,\n} from '@aglyn/aglyn/server'\nimport {\n  consentGroupForSite,\n  contactCompanyLinkFields,\n  firebaseAdmin,\n  getOrgForHost,\n  type HostContactCreated,\n  restampCrmListFieldsAt,\n  writeContactCompanyLink,\n} from '@aglyn/tenant-data-admin'\nimport {\n  COMPANY_CONTACTS_COUNT_FIELD,\n  crmNewRecordListFields,\n  planContactCompanyLink,\n} from '@aglyn/aglyn/server'\nimport { FieldValue } from 'firebase-admin/firestore'\n\n/** What the association did, for the spec and the log. */\nexport type CompanyAssociation =\n  | { outcome: 'linked' | 'created'; companyId: string }\n  | {\n      outcome: 'none'\n      reason: 'no-domain' | 'no-org' | 'ambiguous' | 'no-match' | 'failed'\n    }\n\n/**\n * Link a NEW contact to the company its email domain names (AGL-2613).\n *\n * HubSpot associates a contact with a company on domain the moment the\n * contact exists, and that is the moment this runs: once, from the capture\n * door, for a person the org did not hold before. A repeat visit by somebody\n * already held is not a new person and re-asks nothing; a door that already\n * knew the company — the console's create drawer, an import row naming one\n * — has said so in the facet and this is not called at all.\n *\n * ## Bounded: one query, one commit\n *\n * The query is `companies where domain == d and visibleTo array-contains-any\n * (the capturing scope's read tokens)`, capped at two — the `(visibleTo\n * CONTAINS, domain ASC)` composite serves it. Two rather than one because\n * the answer has to be \"exactly one\": two companies at one domain visible\n * to this site is an ambiguity a capture must not resolve by picking the\n * first, and the contact waits for a person. The scope predicate is the\n * console's own listener predicate, so a company this site could not open\n * is not a match — an agency's client at `acme.com` is not linked to a\n * sibling client's Acme.\n *\n * The write is one batch: the facet and the mirror on the contact, and the\n * count on the company. The contact is fresh, so the plan is the trivial\n * one — no previous link, nothing held elsewhere — and needs no read of the\n * document.\n *\n * ## Creating is a setting, and off by default\n *\n * With `crm.autoCreateCompanies` on the org document, a domain no visible\n * company carries becomes one, named after the domain and scoped exactly as\n * the contact was — `crmScopeTokens`, the stamp every CRM creator uses —\n * with the count starting at one. Public mailbox domains never reach this\n * branch, because `companyDomainForEmail` answers `null` for them: a\n * workspace's consumer list is not a list of accounts.\n *\n * ## The same posture as the capture\n *\n * Never throws. The capture has already succeeded and a form submission\n * must not fail because the CRM could not file its author; a failure is\n * logged and answered as `none`, and the person is exactly as capturable\n * by hand as they were before this existed.\n */\nexport async function associateCompanyByDomain(\n  created: Pick<HostContactCreated, 'hostId' | 'contactId' | 'email'>,\n): Promise<CompanyAssociation> {\n  const domain = companyDomainForEmail(created.email)\n  if (!domain) return { outcome: 'none', reason: 'no-domain' }\n  try {\n    const resolved = await getOrgForHost(created.hostId)\n    if (!resolved) return { outcome: 'none', reason: 'no-org' }\n    const org = resolved.org as Record<string, unknown>\n    const group = await consentGroupForSite(created.hostId, org)\n    const firestore = firebaseAdmin.app().firestore()\n    const orgRef = firestore.collection('orgs').doc(resolved.orgId)\n    const companiesRef = orgRef.collection(CRM_COLLECTIONS.companies)\n    const contactRef = orgRef.collection('contacts').doc(created.contactId)\n\n    const matches = await companiesRef\n      .where('domain', '==', domain)\n      .where('visibleTo', 'array-contains-any', crmReadTokens(group))\n      .limit(2)\n      .get()\n    if (matches.size > 1) return { outcome: 'none', reason: 'ambiguous' }\n    if (matches.size === 1) {\n      const companyId = matches.docs[0].id\n      await writeContactCompanyLink({\n        firestore,\n        contactRef,\n        contact: null,\n        companiesRef,\n        groupId: group.groupId,\n        companyId,\n      })\n      return { outcome: 'linked', companyId }\n    }\n    if (!orgAutoCreatesCompanies(org)) {\n      return { outcome: 'none', reason: 'no-match' }\n    }\n\n    /*\n     * The company and the link in one commit, so a company never exists\n     * with a count of one and no contact naming it — or the reverse. The\n     * count is written as a value rather than an increment because the\n     * document is being created in the same batch, and the plan's `+1` is\n     * exactly what a fresh company with one contact stores.\n     */\n    const plan = planContactCompanyLink(\n      { companyId: null, companyIds: [], heldElsewhere: [] },\n      companiesRef.doc().id,\n    )\n    if (!plan?.companyId) return { outcome: 'none', reason: 'failed' }\n    const companyRef = companiesRef.doc(plan.companyId)\n    const batch = firestore.batch()\n    const company: Record<string, unknown> = {\n      ...nameSearchFields(companyNameForDomain(domain)),\n      domain,\n      visibleTo: crmScopeTokens(org, group),\n      hostId: created.hostId,\n      [COMPANY_CONTACTS_COUNT_FIELD]: 1,\n      createdAt: FieldValue.serverTimestamp(),\n      updatedAt: FieldValue.serverTimestamp(),\n    }\n    batch.set(companyRef, {\n      ...company,\n      // What the Companies list searches and filters by (AGL-3321).\n      ...crmNewRecordListFields('companies', company),\n    })\n    batch.update(contactRef, {\n      ...contactCompanyLinkFields(plan, group.groupId),\n      updatedAt: FieldValue.serverTimestamp(),\n    })\n    await batch.commit()\n    // The company is what the Contacts list filters by (AGL-3321).\n    await restampCrmListFieldsAt(contactRef, 'contacts')\n    return { outcome: 'created', companyId: plan.companyId }\n  } catch (error) {\n    console.error(\n      'associateCompanyByDomain failed',\n      created.hostId,\n      created.contactId,\n      error,\n    )\n    return { outcome: 'none', reason: 'failed' }\n  }\n}\n\nexport default associateCompanyByDomain\n"],"names":["companyDomainForEmail","companyNameForDomain","CRM_COLLECTIONS","crmReadTokens","crmScopeTokens","nameSearchFields","orgAutoCreatesCompanies","consentGroupForSite","contactCompanyLinkFields","firebaseAdmin","getOrgForHost","restampCrmListFieldsAt","writeContactCompanyLink","COMPANY_CONTACTS_COUNT_FIELD","crmNewRecordListFields","planContactCompanyLink","FieldValue","associateCompanyByDomain","created","domain","email","outcome","reason","resolved","hostId","org","group","firestore","app","orgRef","collection","doc","orgId","companiesRef","companies","contactRef","contactId","matches","where","limit","get","size","companyId","docs","id","contact","groupId","plan","companyIds","heldElsewhere","companyRef","batch","company","visibleTo","createdAt","serverTimestamp","updatedAt","set","update","commit","error","console"],"mappings":"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"}

package/src/lib/server/automation-steps.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @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 CrmActivityDirection, type CrmTaskPriority } from '@aglyn/aglyn/server';
+import type { PluginRecordEmailPrepareRequest, PluginRecordPreparedEmail } from '@aglyn/aglyn/plugin-manager/plugin-record-timeline';
+import type { ServerStepAnswer, ServerStepRequest } from '@aglyn/aglyn/plugin-manager/plugin-server-steps';
+import type { InteractionStepGuard } from '@aglyn/aglyn/app-utils/site-interactions';
+import type { ContactLifecycleStage, CrmActivityKind, CrmTaskKind } from '@aglyn/aglyn/app-utils/crm-kinds';
+import type { CRM_STEP_TYPES } from '../constants/bundle-common';
+/**
+ * THE AUTOMATION STEPS THAT WRITE THE CRM (AGL-2605), run for the automation
+ * engine through the platform's server-step seam (`plugin-server-steps`,
+ * AGL-3080): `setContactStage`, `addContactTag`, `assignContactOwner`,
+ * `createCrmTask` and `logCrmActivity`.
+ *
+ * The engine keeps the step's guard, the run's order, its history and the
+ * nesting cap; this answers what the step did. A refusal is ANSWERED as
+ * `error`, never thrown, and its words are the line the run history carries —
+ * the same words the engine wrote when these steps were its own.
+ *
+ * The five share one shape no other step has: each begins by finding THE
+ * PERSON the event is about, and each writes either inside the site's facet on
+ * that person or a record stamped with the site's scope. One resolver and one
+ * scope expression, used five times, rather than five copies drifting apart.
+ *
+ * ## The person is the event's, never the step's
+ *
+ * A step carries no contact reference. The contact is whoever the event
+ * names — by `contactId` when the emitting door knew the document, and by
+ * `email` otherwise, which is what every pre-CRM event carries. Both lookups
+ * are scoped to what THIS site may see: a document the id names but the site
+ * cannot read is treated as absent, exactly as the scoped query would have
+ * treated it, so an event replayed against the wrong site reaches nobody.
+ *
+ * ## A missing person is a reported no-op
+ *
+ * Nothing is written and the step's error names the reason, which lands in
+ * the run summary beside the trigger — the same place "why didn't it fire?"
+ * is answered for every other step. Silence here would make a mis-wired
+ * trigger (a form with no email field) indistinguishable from a working one.
+ *
+ * ## The plan gate is the CRM's
+ *
+ * Every step is refused on a workspace whose plan does not carry the CRM,
+ * into the run history with the tier that carries it, so a Free workspace
+ * whose flow names a CRM step reads why the step did nothing rather than a
+ * log that says it ran. The org document is the one the run's gate already
+ * read, handed over with the step, so the check costs no read.
+ *
+ * The same module answers the record timeline's `prepareEmail` (AGL-2615): an
+ * automation's email addressed to the contact the event is about is filed on
+ * that contact's timeline — see {@link prepareCrmRecordEmail}.
+ */
+/** One of the steps this module runs. */
+export type CrmStepType = (typeof CRM_STEP_TYPES)[number];
+/**
+ * A CRM step, as it is stored: the CRM's own shapes of the steps it runs. The
+ * automation editor writes them and checks them; `apps/console/specs/
+ * crm-automation-steps.spec.ts` runs what it writes through this module.
+ */
+export type CrmAutomationStep = ({
+    type: 'setContactStage';
+    lifecycleStage: ContactLifecycleStage;
+} | {
+    type: 'addContactTag';
+    tag: string;
+} | {
+    type: 'assignContactOwner';
+    ownerUid?: string;
+    ownerEmail?: string;
+    roundRobin?: boolean;
+} | {
+    type: 'createCrmTask';
+    title: string;
+    kind: CrmTaskKind;
+    /** `normal` when absent — the steps written before priorities were (AGL-3517). */
+    priority?: CrmTaskPriority;
+    dueInDays: number;
+    assigneeUid?: string;
+    assigneeEmail?: string;
+} | {
+    type: 'logCrmActivity';
+    kind: CrmActivityKind;
+    body: string;
+    /** Which way a call or an email went (AGL-3517). */
+    direction?: CrmActivityDirection;
+}) & {
+    when?: InteractionStepGuard | null;
+} & {
+    type: CrmStepType;
+};
+/**
+ * Runs one CRM step for the person the event names: the executor the CRM
+ * registers on the server-step seam for every type in `CRM_STEP_TYPES`.
+ *
+ * Never throws for a plan without the CRM, a missing person, an unknown owner
+ * or a site with no org — those are answered as `error` so the run records
+ * them; a Firestore failure propagates, and the engine records it the same
+ * way.
+ */
+export declare function runCrmAutomationStep(request: ServerStepRequest, nowMs?: number): Promise<ServerStepAnswer>;
+/**
+ * Whether — and where — an email a plugin is about to send lands on a
+ * timeline: the CRM's answer to the record timeline's `prepareEmail`.
+ *
+ * An automation's `sendEmail` step is not a CRM step: it mails whatever
+ * address the event carries, to a person who may be nobody the CRM knows. It
+ * earns a row on exactly one condition, that the message is ADDRESSED TO THE
+ * PERSON the sender means — a contact, else the lead a lead-routed form filed
+ * (AGL-3458), whose row lands on the lead's timeline — the person the request's link finds, at the
+ * address the row holds. A welcome sequence to a new contact is that; an
+ * internal alert routed to a merchant's own address through `toField` is not,
+ * and a row for it would put the merchant's inbox on a customer's history.
+ *
+ * Prepared ahead of the send, for the reason the console route mints its id
+ * first: the delivery webhook has nothing but the tags on the message to find
+ * the row with. Nothing is written until `file` is called, once the provider
+ * accepted the message. A workspace whose plan does not carry the CRM, a
+ * record at the activity ceiling and a site with no org earn no row — the
+ * message still goes, because the ceiling bounds the log and not the mail.
+ *
+ * **Never throws**, and neither does `file`. The row is bookkeeping beside a
+ * send, and a lookup that fails must not become a message that never left —
+ * the posture every meter beside a send takes. A failure is logged and the
+ * message goes out untagged.
+ */
+export declare function prepareCrmRecordEmail(request: PluginRecordEmailPrepareRequest): Promise<PluginRecordPreparedEmail | null>;