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

package/src/lib/server/crm-booking-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/crm-booking-activity.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  checkEntitlement,\n  consentGroupForHost,\n  CRM_COLLECTIONS,\n  type CrmActivity,\n  type CrmActivityLink,\n  type CrmTask,\n  crmActivityLogHasRoom,\n  crmBookingFollowUpDueMs,\n  crmBookingFollowUpTitle,\n  crmBookingMeetingBody,\n  crmScopeTokens,\n  isHostPluginEnabled,\n  parseCrmBookingRef,\n  readContactFacet,\n  visibleToHost,\n} from '@aglyn/aglyn/server'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { findContactByEmail } from './contact-email-index'\nimport { countCrmActivitiesForRecord } from './crm-records'\n\n/**\n * WHAT A BOOKING FILES ON THE CRM RECORD (AGL-2660).\n *\n * A confirmed booking is a meeting the record has on its calendar, and the\n * timeline should say so without a rep logging it by hand. So once a\n * booking's row is written — at creation for a free service, on payment\n * for a paid one — the record is found and a `meeting` activity filed under\n * it, with a follow-up task beside it when the service asks for one.\n *\n * ## Which record\n *\n * The reference the booking link carried wins: `crmRef` names the contact,\n * lead or deal the rep dropped the link from, and a booking made through\n * that link belongs to that record even when the booker typed a different\n * address. Without one — a booking taken off the widget cold — the booker's\n * address is looked up through the org's address index, narrowed to this\n * site, exactly as the automation steps resolve an event's contact. A\n * reference to a record the site cannot see, or that no longer exists,\n * falls through to the address rather than filing under nobody.\n *\n * ## Where it lives\n *\n * In the admin library rather than the Bookings plugin, because the row is\n * a CRM record: its scope, its ceiling and its collections are the CRM's,\n * and a plugin that stamped its own would be a second creator to keep in\n * step with `crmScopeTokens`. The Bookings plugin passes what it already\n * holds and reads the outcome; the CRM plugin is never imported.\n *\n * Firestore is a parameter, as in `crm-records.ts`: the callers hold one,\n * and a module that reached for the Admin app itself would drag it into\n * every spec that only wants the arithmetic.\n *\n * ## Failure posture\n *\n * **Never throws.** A booking that could not be filed on the CRM is still\n * a booking — the guest has the slot and the confirmation — so a failure\n * here is logged and reported in the outcome, never raised into the\n * request that took the booking or the webhook that confirmed it.\n */\n\n/** The CRM plugin's id, as `enabledPlugins` and `disabledPlugins` name it. */\nconst CRM_PLUGIN_ID = 'crm'\n\nexport interface CrmBookingRecordInput {\n  hostId: string\n  /**\n   * The owning org, as `getOrgForHost` returns it — the plugin set, the\n   * consent groups and the scope default are all read off it.\n   */\n  org: Record<string, unknown> | null | undefined\n  orgId: string\n  /** The booking as its row was written. */\n  booking: {\n    id: string\n    serviceId?: string\n    serviceName?: string\n    email?: string\n    startsAtMs: number\n    endsAtMs: number\n    /** The `crm` query value the link carried, kept on the row. */\n    crmRef?: string | null\n  }\n  /** The service as stored: its two CRM switches and its timezone. */\n  service:\n    | {\n        name?: string\n        timezone?: string\n        crmFollowUpTask?: boolean\n        crmMeetingActivity?: boolean\n      }\n    | null\n    | undefined\n  /**\n   * The host document's plugin fields, when the caller already holds them;\n   * read here otherwise. The deny-list is per site, and a site that has\n   * switched the CRM off must file nothing.\n   */\n  host?: { disabledPlugins?: string[]; enabledPlugins?: string[] } | null\n}\n\nexport type CrmBookingRecordOutcome =\n  | {\n      filed: false\n      reason:\n        /** The CRM plugin does not run on this site. */\n        | 'crm-off'\n        /**\n         * The org's plan does not carry the CRM suite, whose activities and\n         * tasks these are (AGL-2787).\n         */\n        | 'not-entitled'\n        /** Neither the reference nor the address named a record. */\n        | 'no-record'\n        /** A meeting for this booking is already on the timeline. */\n        | 'already-filed'\n        /** The service asks for neither a meeting nor a follow-up. */\n        | 'nothing-to-file'\n        /** A read or a write threw; logged, and nothing is promised. */\n        | 'failed'\n    }\n  | {\n      filed: true\n      /** How the record was found. */\n      matchedBy: 'crmRef' | 'email'\n      link: CrmActivityLink\n      /** The meeting's id, or `null` when the service files no meeting. */\n      activityId: string | null\n      /** The follow-up's id, or `null` when the service asks for none. */\n      taskId: string | null\n    }\n\ninterface ResolvedRecord {\n  link: CrmActivityLink\n  matchedBy: 'crmRef' | 'email'\n  /** Whoever holds the relationship, for the follow-up's assignee. */\n  ownerUid?: string\n}\n\n/**\n * The record a booking belongs to — the reference first, the address second.\n */\nasync function resolveBookingRecord(\n  firestore: FirebaseFirestore.Firestore,\n  input: CrmBookingRecordInput,\n  groupId: string,\n): Promise<ResolvedRecord | null> {\n  const { hostId, orgId } = input\n  const orgRef = firestore.collection('orgs').doc(orgId)\n  const contactsRef = orgRef.collection('contacts')\n  const ref = parseCrmBookingRef(input.booking.crmRef)\n  if (ref?.kind === 'contact') {\n    const contact = await contactsRef.doc(ref.id).get()\n    if (contact.exists && visibleToHost(contact.get('visibleTo'), hostId)) {\n      const facet = readContactFacet(contact.data() ?? {}, groupId)\n      return {\n        link: {\n          contactId: contact.id,\n          ...(facet.companyId ? { companyId: facet.companyId } : {}),\n        },\n        matchedBy: 'crmRef',\n        ...(facet.ownerUid ? { ownerUid: facet.ownerUid } : {}),\n      }\n    }\n  }\n  if (ref?.kind === 'deal') {\n    const deal = await orgRef.collection(CRM_COLLECTIONS.deals).doc(ref.id).get()\n    if (deal.exists && visibleToHost(deal.get('visibleTo'), hostId)) {\n      const contactId = String(deal.get('contactId') ?? '')\n      const companyId = String(deal.get('companyId') ?? '')\n      const ownerUid = String(deal.get('ownerUid') ?? '')\n      return {\n        link: {\n          dealId: deal.id,\n          ...(contactId ? { contactId } : {}),\n          ...(companyId ? { companyId } : {}),\n        },\n        matchedBy: 'crmRef',\n        ...(ownerUid ? { ownerUid } : {}),\n      }\n    }\n  }\n  if (ref?.kind === 'lead') {\n    // A lead is host-scoped by path and carries no `visibleTo` of its own.\n    const lead = await firestore\n      .collection('hosts')\n      .doc(hostId)\n      .collection('leads')\n      .doc(ref.id)\n      .get()\n    if (lead.exists) {\n      const ownerUid = String(lead.get('ownerUid') ?? '')\n      return {\n        link: { leadId: lead.id },\n        matchedBy: 'crmRef',\n        ...(ownerUid ? { ownerUid } : {}),\n      }\n    }\n  }\n  const hit = await findContactByEmail(contactsRef, input.booking.email, { hostId })\n  if (!hit) return null\n  const facet = readContactFacet(hit.data() ?? {}, groupId)\n  return {\n    link: {\n      contactId: hit.id,\n      ...(facet.companyId ? { companyId: facet.companyId } : {}),\n    },\n    matchedBy: 'email',\n    ...(facet.ownerUid ? { ownerUid: facet.ownerUid } : {}),\n  }\n}\n\n/**\n * Files what a confirmed booking owes the CRM: the meeting, and the\n * follow-up when the service asks for one. See the module comment.\n */\nexport async function recordCrmBooking(\n  firestore: FirebaseFirestore.Firestore,\n  input: CrmBookingRecordInput,\n): Promise<CrmBookingRecordOutcome> {\n  const { hostId, orgId, booking, service } = input\n  try {\n    if (!hostId || !orgId || !booking?.id) return { filed: false, reason: 'failed' }\n    const wantsMeeting = service?.crmMeetingActivity !== false\n    const wantsTask = service?.crmFollowUpTask === true\n    if (!wantsMeeting && !wantsTask) return { filed: false, reason: 'nothing-to-file' }\n\n    const host =\n      input.host === undefined\n        ? ((await firestore.collection('hosts').doc(hostId).get()).data() as\n            | { disabledPlugins?: string[]; enabledPlugins?: string[] }\n            | undefined) ?? null\n        : input.host\n    if (!isHostPluginEnabled(input.org ?? null, host, CRM_PLUGIN_ID)) {\n      return { filed: false, reason: 'crm-off' }\n    }\n    if (!checkEntitlement(input.org as Parameters<typeof checkEntitlement>[0], 'crm')) {\n      return { filed: false, reason: 'not-entitled' }\n    }\n\n    const orgRef = firestore.collection('orgs').doc(orgId)\n    const activities = orgRef.collection(CRM_COLLECTIONS.activities)\n    // One meeting per booking, whatever path re-enters: the paid webhook is\n    // redelivered for days after any 500, and its own guard is the status,\n    // which this row is not part of.\n    const already = await activities.where('bookingId', '==', booking.id).limit(1).get()\n    if (!already.empty) return { filed: false, reason: 'already-filed' }\n\n    const group = consentGroupForHost(input.org ?? null, hostId)\n    const record = await resolveBookingRecord(firestore, input, group.groupId)\n    if (!record) return { filed: false, reason: 'no-record' }\n\n    const visibleTo = crmScopeTokens(input.org ?? null, group)\n    const serviceName = String(service?.name ?? booking.serviceName ?? '').trim()\n    const timezone = service?.timezone || undefined\n\n    let activityId: string | null = null\n    if (wantsMeeting) {\n      // The per-record ceiling (AGL-2611): a full log refuses the meeting\n      // but not the follow-up — a task is owed either way.\n      const logged = await countCrmActivitiesForRecord(orgRef, record.link)\n      if (crmActivityLogHasRoom(logged)) {\n        const activity: CrmActivity = {\n          kind: 'meeting',\n          body: crmBookingMeetingBody({\n            serviceName,\n            startsAtMs: booking.startsAtMs,\n            timezone,\n          }),\n          // When it HAPPENS, which is the slot — not when it was booked.\n          atMs: booking.startsAtMs,\n          byUid: '',\n          ...record.link,\n          bookingId: booking.id,\n          hostId,\n          visibleTo,\n          createdAt: FieldValue.serverTimestamp(),\n          updatedAt: FieldValue.serverTimestamp(),\n        }\n        const written = await activities.add(activity)\n        activityId = written.id\n      }\n    }\n\n    let taskId: string | null = null\n    if (wantsTask) {\n      const task: CrmTask = {\n        title: crmBookingFollowUpTitle(serviceName),\n        kind: 'todo',\n        priority: 'normal',\n        status: 'open',\n        dueAtMs: crmBookingFollowUpDueMs(booking.endsAtMs, timezone),\n        ...(record.ownerUid ? { assigneeUid: record.ownerUid } : {}),\n        createdByUid: '',\n        ...record.link,\n        hostId,\n        visibleTo,\n        createdAt: FieldValue.serverTimestamp(),\n        updatedAt: FieldValue.serverTimestamp(),\n      }\n      const written = await orgRef.collection(CRM_COLLECTIONS.tasks).add(task)\n      taskId = written.id\n    }\n\n    return { filed: true, matchedBy: record.matchedBy, link: record.link, activityId, taskId }\n  } catch (error) {\n    console.error('[crm] booking could not be filed', hostId, booking?.id, error)\n    return { filed: false, reason: 'failed' }\n  }\n}\n"],"names":["checkEntitlement","consentGroupForHost","CRM_COLLECTIONS","crmActivityLogHasRoom","crmBookingFollowUpDueMs","crmBookingFollowUpTitle","crmBookingMeetingBody","crmScopeTokens","isHostPluginEnabled","parseCrmBookingRef","readContactFacet","visibleToHost","FieldValue","findContactByEmail","countCrmActivitiesForRecord","CRM_PLUGIN_ID","resolveBookingRecord","firestore","input","groupId","hit","hostId","orgId","orgRef","collection","doc","contactsRef","ref","booking","crmRef","kind","contact","id","get","exists","facet","data","link","contactId","companyId","matchedBy","ownerUid","deal","deals","String","dealId","lead","leadId","email","recordCrmBooking","service","filed","reason","wantsMeeting","crmMeetingActivity","wantsTask","crmFollowUpTask","host","undefined","org","activities","already","where","limit","empty","group","record","visibleTo","serviceName","name","trim","timezone","activityId","logged","activity","body","startsAtMs","atMs","byUid","bookingId","createdAt","serverTimestamp","updatedAt","written","add","taskId","task","title","priority","status","dueAtMs","endsAtMs","assigneeUid","createdByUid","tasks","error","console"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SACEA,gBAAgB,EAChBC,mBAAmB,EACnBC,eAAe,EAIfC,qBAAqB,EACrBC,uBAAuB,EACvBC,uBAAuB,EACvBC,qBAAqB,EACrBC,cAAc,EACdC,mBAAmB,EACnBC,kBAAkB,EAClBC,gBAAgB,EAChBC,aAAa,QACR,sBAAqB;AAC5B,SAASC,UAAU,QAAQ,2BAA0B;AACrD,SAASC,kBAAkB,QAAQ,2BAAuB;AAC1D,SAASC,2BAA2B,QAAQ,mBAAe;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCC,GAED,4EAA4E,GAC5E,MAAMC,gBAAgB;AA6EtB;;CAEC,GACD,eAAeC,qBACbC,SAAsC,EACtCC,KAA4B,EAC5BC,OAAe;QAwDgBC;IAtD/B,MAAM,EAAEC,MAAM,EAAEC,KAAK,EAAE,GAAGJ;IAC1B,MAAMK,SAASN,UAAUO,UAAU,CAAC,QAAQC,GAAG,CAACH;IAChD,MAAMI,cAAcH,OAAOC,UAAU,CAAC;IACtC,MAAMG,MAAMlB,mBAAmBS,MAAMU,OAAO,CAACC,MAAM;IACnD,IAAIF,CAAAA,uBAAAA,IAAKG,IAAI,MAAK,WAAW;QAC3B,MAAMC,UAAU,MAAML,YAAYD,GAAG,CAACE,IAAIK,EAAE,EAAEC,GAAG;QACjD,IAAIF,QAAQG,MAAM,IAAIvB,cAAcoB,QAAQE,GAAG,CAAC,cAAcZ,SAAS;gBACtCU;YAA/B,MAAMI,QAAQzB,kBAAiBqB,gBAAAA,QAAQK,IAAI,cAAZL,gBAAkB,CAAC,GAAGZ;YACrD,OAAO;gBACLkB,MAAM;oBACJC,WAAWP,QAAQC,EAAE;mBACjBG,MAAMI,SAAS,GAAG;oBAAEA,WAAWJ,MAAMI,SAAS;gBAAC,IAAI,CAAC;gBAE1DC,WAAW;eACPL,MAAMM,QAAQ,GAAG;gBAAEA,UAAUN,MAAMM,QAAQ;YAAC,IAAI,CAAC;QAEzD;IACF;IACA,IAAId,CAAAA,uBAAAA,IAAKG,IAAI,MAAK,QAAQ;QACxB,MAAMY,OAAO,MAAMnB,OAAOC,UAAU,CAACtB,gBAAgByC,KAAK,EAAElB,GAAG,CAACE,IAAIK,EAAE,EAAEC,GAAG;QAC3E,IAAIS,KAAKR,MAAM,IAAIvB,cAAc+B,KAAKT,GAAG,CAAC,cAAcZ,SAAS;gBACtCqB,WACAA,YACDA;YAFxB,MAAMJ,YAAYM,QAAOF,YAAAA,KAAKT,GAAG,CAAC,wBAATS,YAAyB;YAClD,MAAMH,YAAYK,QAAOF,aAAAA,KAAKT,GAAG,CAAC,wBAATS,aAAyB;YAClD,MAAMD,WAAWG,QAAOF,aAAAA,KAAKT,GAAG,CAAC,uBAATS,aAAwB;YAChD,OAAO;gBACLL,MAAM;oBACJQ,QAAQH,KAAKV,EAAE;mBACXM,YAAY;oBAAEA;gBAAU,IAAI,CAAC,GAC7BC,YAAY;oBAAEA;gBAAU,IAAI,CAAC;gBAEnCC,WAAW;eACPC,WAAW;gBAAEA;YAAS,IAAI,CAAC;QAEnC;IACF;IACA,IAAId,CAAAA,uBAAAA,IAAKG,IAAI,MAAK,QAAQ;QACxB,uEAAuE;QACvE,MAAMgB,OAAO,MAAM7B,UAChBO,UAAU,CAAC,SACXC,GAAG,CAACJ,QACJG,UAAU,CAAC,SACXC,GAAG,CAACE,IAAIK,EAAE,EACVC,GAAG;QACN,IAAIa,KAAKZ,MAAM,EAAE;gBACSY;YAAxB,MAAML,WAAWG,QAAOE,YAAAA,KAAKb,GAAG,CAAC,uBAATa,YAAwB;YAChD,OAAO;gBACLT,MAAM;oBAAEU,QAAQD,KAAKd,EAAE;gBAAC;gBACxBQ,WAAW;eACPC,WAAW;gBAAEA;YAAS,IAAI,CAAC;QAEnC;IACF;IACA,MAAMrB,MAAM,MAAMP,mBAAmBa,aAAaR,MAAMU,OAAO,CAACoB,KAAK,EAAE;QAAE3B;IAAO;IAChF,IAAI,CAACD,KAAK,OAAO;IACjB,MAAMe,QAAQzB,kBAAiBU,YAAAA,IAAIgB,IAAI,cAARhB,YAAc,CAAC,GAAGD;IACjD,OAAO;QACLkB,MAAM;YACJC,WAAWlB,IAAIY,EAAE;WACbG,MAAMI,SAAS,GAAG;YAAEA,WAAWJ,MAAMI,SAAS;QAAC,IAAI,CAAC;QAE1DC,WAAW;OACPL,MAAMM,QAAQ,GAAG;QAAEA,UAAUN,MAAMM,QAAQ;IAAC,IAAI,CAAC;AAEzD;AAEA;;;CAGC,GACD,OAAO,eAAeQ,iBACpBhC,SAAsC,EACtCC,KAA4B;IAE5B,MAAM,EAAEG,MAAM,EAAEC,KAAK,EAAEM,OAAO,EAAEsB,OAAO,EAAE,GAAGhC;IAC5C,IAAI;YAQK,OAIkBA,YAeSA,aAIDA,aACNgC;QA/B3B,IAAI,CAAC7B,UAAU,CAACC,SAAS,EAACM,2BAAAA,QAASI,EAAE,GAAE,OAAO;YAAEmB,OAAO;YAAOC,QAAQ;QAAS;QAC/E,MAAMC,eAAeH,CAAAA,2BAAAA,QAASI,kBAAkB,MAAK;QACrD,MAAMC,YAAYL,CAAAA,2BAAAA,QAASM,eAAe,MAAK;QAC/C,IAAI,CAACH,gBAAgB,CAACE,WAAW,OAAO;YAAEJ,OAAO;YAAOC,QAAQ;QAAkB;QAElF,MAAMK,OACJvC,MAAMuC,IAAI,KAAKC,aACV,QAAA,AAAC,CAAA,MAAMzC,UAAUO,UAAU,CAAC,SAASC,GAAG,CAACJ,QAAQY,GAAG,EAAC,EAAGG,IAAI,cAA5D,QAEiB,OAClBlB,MAAMuC,IAAI;QAChB,IAAI,CAACjD,qBAAoBU,aAAAA,MAAMyC,GAAG,YAATzC,aAAa,MAAMuC,MAAM1C,gBAAgB;YAChE,OAAO;gBAAEoC,OAAO;gBAAOC,QAAQ;YAAU;QAC3C;QACA,IAAI,CAACpD,iBAAiBkB,MAAMyC,GAAG,EAA4C,QAAQ;YACjF,OAAO;gBAAER,OAAO;gBAAOC,QAAQ;YAAe;QAChD;QAEA,MAAM7B,SAASN,UAAUO,UAAU,CAAC,QAAQC,GAAG,CAACH;QAChD,MAAMsC,aAAarC,OAAOC,UAAU,CAACtB,gBAAgB0D,UAAU;QAC/D,wEAAwE;QACxE,uEAAuE;QACvE,iCAAiC;QACjC,MAAMC,UAAU,MAAMD,WAAWE,KAAK,CAAC,aAAa,MAAMlC,QAAQI,EAAE,EAAE+B,KAAK,CAAC,GAAG9B,GAAG;QAClF,IAAI,CAAC4B,QAAQG,KAAK,EAAE,OAAO;YAAEb,OAAO;YAAOC,QAAQ;QAAgB;QAEnE,MAAMa,QAAQhE,qBAAoBiB,cAAAA,MAAMyC,GAAG,YAATzC,cAAa,MAAMG;QACrD,MAAM6C,SAAS,MAAMlD,qBAAqBC,WAAWC,OAAO+C,MAAM9C,OAAO;QACzE,IAAI,CAAC+C,QAAQ,OAAO;YAAEf,OAAO;YAAOC,QAAQ;QAAY;QAExD,MAAMe,YAAY5D,gBAAeW,cAAAA,MAAMyC,GAAG,YAATzC,cAAa,MAAM+C;QACpD,MAAMG,cAAcxB,QAAOM,gBAAAA,2BAAAA,QAASmB,IAAI,oBAAIzC,QAAQwC,WAAW,YAApClB,OAAwC,IAAIoB,IAAI;QAC3E,MAAMC,WAAWrB,CAAAA,2BAAAA,QAASqB,QAAQ,KAAIb;QAEtC,IAAIc,aAA4B;QAChC,IAAInB,cAAc;YAChB,oEAAoE;YACpE,qDAAqD;YACrD,MAAMoB,SAAS,MAAM3D,4BAA4BS,QAAQ2C,OAAO7B,IAAI;YACpE,IAAIlC,sBAAsBsE,SAAS;gBACjC,MAAMC,WAAwB;oBAC5B5C,MAAM;oBACN6C,MAAMrE,sBAAsB;wBAC1B8D;wBACAQ,YAAYhD,QAAQgD,UAAU;wBAC9BL;oBACF;oBACA,+DAA+D;oBAC/DM,MAAMjD,QAAQgD,UAAU;oBACxBE,OAAO;mBACJZ,OAAO7B,IAAI;oBACd0C,WAAWnD,QAAQI,EAAE;oBACrBX;oBACA8C;oBACAa,WAAWpE,WAAWqE,eAAe;oBACrCC,WAAWtE,WAAWqE,eAAe;;gBAEvC,MAAME,UAAU,MAAMvB,WAAWwB,GAAG,CAACV;gBACrCF,aAAaW,QAAQnD,EAAE;YACzB;QACF;QAEA,IAAIqD,SAAwB;QAC5B,IAAI9B,WAAW;YACb,MAAM+B,OAAgB;gBACpBC,OAAOlF,wBAAwB+D;gBAC/BtC,MAAM;gBACN0D,UAAU;gBACVC,QAAQ;gBACRC,SAAStF,wBAAwBwB,QAAQ+D,QAAQ,EAAEpB;eAC/CL,OAAOzB,QAAQ,GAAG;gBAAEmD,aAAa1B,OAAOzB,QAAQ;YAAC,IAAI,CAAC;gBAC1DoD,cAAc;eACX3B,OAAO7B,IAAI;gBACdhB;gBACA8C;gBACAa,WAAWpE,WAAWqE,eAAe;gBACrCC,WAAWtE,WAAWqE,eAAe;;YAEvC,MAAME,UAAU,MAAM5D,OAAOC,UAAU,CAACtB,gBAAgB4F,KAAK,EAAEV,GAAG,CAACE;YACnED,SAASF,QAAQnD,EAAE;QACrB;QAEA,OAAO;YAAEmB,OAAO;YAAMX,WAAW0B,OAAO1B,SAAS;YAAEH,MAAM6B,OAAO7B,IAAI;YAAEmC;YAAYa;QAAO;IAC3F,EAAE,OAAOU,OAAO;QACdC,QAAQD,KAAK,CAAC,oCAAoC1E,QAAQO,2BAAAA,QAASI,EAAE,EAAE+D;QACvE,OAAO;YAAE5C,OAAO;YAAOC,QAAQ;QAAS;IAC1C;AACF"}

package/src/lib/server/crm-email-activity.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @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 CrmActivity, type CrmEmailDeliveryState } from '@aglyn/aglyn/server';
+/**
+ * The activity row a one-to-one email is logged as, on the server side
+ * (AGL-2615): where it lives, how it is written, and how the delivery
+ * webhook moves its state.
+ *
+ * Two writers log a sent email — the console's `crm/email-send` route and
+ * the `sendEmail` automation step — and one reader advances it, the Resend
+ * event webhook. The reader has to find the row from nothing but the tags
+ * on the message, so the id is minted BEFORE the send and stamped on it,
+ * and the row is written only after the provider accepted the message. A
+ * row written first would be an "email" on the timeline for a message that
+ * never left.
+ *
+ * Firestore is a parameter throughout, as in `crm-records.ts`: the callers
+ * hold one, and a module that reached for the Admin app itself would drag
+ * it into every spec that only wants the arithmetic.
+ */
+/** `orgs/{orgId}/crmActivities/{activityId}`. */
+export declare function crmActivityRef(firestore: FirebaseFirestore.Firestore, orgId: string, activityId: string): FirebaseFirestore.DocumentReference;
+/**
+ * A fresh reference for the row a send is about to earn — `doc()` with no
+ * id mints one locally and reads nothing, so the id can ride the message
+ * as a tag before anything is written.
+ */
+export declare function newCrmActivityRef(firestore: FirebaseFirestore.Firestore, orgId: string): FirebaseFirestore.DocumentReference;
+/**
+ * Writes the row a sent email is logged as, stamped with the server clock.
+ *
+ * `set` rather than `add`, because the id was minted ahead of the send and
+ * is already on the message; a second id here would be the one the webhook
+ * could not find.
+ */
+export declare function writeCrmEmailActivity(ref: FirebaseFirestore.DocumentReference, activity: CrmActivity): Promise<void>;
+/**
+ * Which delivery state one normalized delivery event moves a row to, or
+ * `null` for an event that moves nothing.
+ *
+ * Takes the log's own vocabulary (`EmailDeliveryEventType`) rather than the
+ * provider's wire strings: `normalizeResendDeliveryEvents` is the one place
+ * that reads those, and this module must not become a second. The five
+ * states the timeline shows share the log's names exactly, so the mapping
+ * is membership; `delayed` and `failed` are the log's own and the row keeps
+ * whatever it held.
+ */
+export declare function crmEmailDeliveryStateForEvent(type: string | null | undefined): CrmEmailDeliveryState | null;
+export type CrmEmailDeliveryOutcome = 
+/** The row moved to the incoming state. */
+'advanced'
+/** The row already held this state or a later one; nothing written. */
+ | 'unchanged'
+/** No email activity by that id in that org; nothing written. */
+ | 'missing'
+/** The read or the write threw; logged, and nothing is promised. */
+ | 'failed';
+/**
+ * One delivery event, onto the activity row it names (AGL-2615).
+ *
+ * A TRANSACTION, because the rule is "keep the later state" and two events
+ * for one message routinely arrive together — `delivered` and `opened`
+ * within the same second from a mail client that fetches images on
+ * receipt. Two plain read-then-writes interleaved would let the earlier
+ * event land last and print "Delivered" over an open that already
+ * happened; inside a transaction the second read sees the first write and
+ * `nextCrmEmailDeliveryState` answers "unchanged".
+ *
+ * A row that is not an email activity is left alone: the tag named it, but
+ * a delivery state on a call log would be a chip the timeline has no way to
+ * explain. **Never throws** — the webhook answers the provider 200 whatever
+ * happens here, so a failure is logged and reported rather than raised.
+ */
+export declare function recordCrmEmailDelivery(firestore: FirebaseFirestore.Firestore, input: {
+    orgId: string;
+    activityId: string;
+    state: CrmEmailDeliveryState;
+    /** When the provider says it happened, epoch ms. */
+    atMs: number;
+}): Promise<CrmEmailDeliveryOutcome>;
+/**
+ * `orgs/{orgId}/crmActivities/{id}` for a CAPTURED message (AGL-2657), with
+ * the id derived from the message's key — its `Message-ID`, else the
+ * provider's id — so a second delivery of one message addresses the row
+ * the first delivery wrote. A hash rather than the key itself, because a
+ * `Message-ID` carries `<`, `@` and `/`, which a document id may not.
+ */
+export declare function crmCapturedEmailActivityRef(firestore: FirebaseFirestore.Firestore, orgId: string, key: string): FirebaseFirestore.DocumentReference;
+/** What a create answered: the row is new, or it was already there. */
+export type CrmEmailActivityCreateOutcome = 'created' | 'duplicate';
+/**
+ * Writes a captured message's row ONCE: `create()`, which refuses a
+ * document that already exists, is what makes two deliveries of one
+ * message one row even when they arrive together — the second create is
+ * the one Firestore refuses, and this answers `duplicate` for it. Any
+ * other failure is the caller's.
+ */
+export declare function createCrmEmailActivity(ref: FirebaseFirestore.DocumentReference, activity: CrmActivity): Promise<CrmEmailActivityCreateOutcome>;

package/src/lib/server/crm-email-activity.js

@@ -0,0 +1,143 @@
+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 { CRM_COLLECTIONS, isCrmEmailDeliveryState, nextCrmEmailDeliveryState } from "@aglyn/aglyn/server";
+import { createHash } from "crypto";
+import { FieldValue } from "firebase-admin/firestore";
+/**
+ * The activity row a one-to-one email is logged as, on the server side
+ * (AGL-2615): where it lives, how it is written, and how the delivery
+ * webhook moves its state.
+ *
+ * Two writers log a sent email — the console's `crm/email-send` route and
+ * the `sendEmail` automation step — and one reader advances it, the Resend
+ * event webhook. The reader has to find the row from nothing but the tags
+ * on the message, so the id is minted BEFORE the send and stamped on it,
+ * and the row is written only after the provider accepted the message. A
+ * row written first would be an "email" on the timeline for a message that
+ * never left.
+ *
+ * Firestore is a parameter throughout, as in `crm-records.ts`: the callers
+ * hold one, and a module that reached for the Admin app itself would drag
+ * it into every spec that only wants the arithmetic.
+ */ /** `orgs/{orgId}/crmActivities/{activityId}`. */ export function crmActivityRef(firestore, orgId, activityId) {
+    return firestore.collection('orgs').doc(orgId).collection(CRM_COLLECTIONS.activities).doc(activityId);
+}
+/**
+ * A fresh reference for the row a send is about to earn — `doc()` with no
+ * id mints one locally and reads nothing, so the id can ride the message
+ * as a tag before anything is written.
+ */ export function newCrmActivityRef(firestore, orgId) {
+    return firestore.collection('orgs').doc(orgId).collection(CRM_COLLECTIONS.activities).doc();
+}
+/**
+ * Writes the row a sent email is logged as, stamped with the server clock.
+ *
+ * `set` rather than `add`, because the id was minted ahead of the send and
+ * is already on the message; a second id here would be the one the webhook
+ * could not find.
+ */ export async function writeCrmEmailActivity(ref, activity) {
+    await ref.set(_extends({}, activity, {
+        createdAt: FieldValue.serverTimestamp(),
+        updatedAt: FieldValue.serverTimestamp()
+    }));
+}
+/**
+ * Which delivery state one normalized delivery event moves a row to, or
+ * `null` for an event that moves nothing.
+ *
+ * Takes the log's own vocabulary (`EmailDeliveryEventType`) rather than the
+ * provider's wire strings: `normalizeResendDeliveryEvents` is the one place
+ * that reads those, and this module must not become a second. The five
+ * states the timeline shows share the log's names exactly, so the mapping
+ * is membership; `delayed` and `failed` are the log's own and the row keeps
+ * whatever it held.
+ */ export function crmEmailDeliveryStateForEvent(type) {
+    return isCrmEmailDeliveryState(type) ? type : null;
+}
+/**
+ * One delivery event, onto the activity row it names (AGL-2615).
+ *
+ * A TRANSACTION, because the rule is "keep the later state" and two events
+ * for one message routinely arrive together — `delivered` and `opened`
+ * within the same second from a mail client that fetches images on
+ * receipt. Two plain read-then-writes interleaved would let the earlier
+ * event land last and print "Delivered" over an open that already
+ * happened; inside a transaction the second read sees the first write and
+ * `nextCrmEmailDeliveryState` answers "unchanged".
+ *
+ * A row that is not an email activity is left alone: the tag named it, but
+ * a delivery state on a call log would be a chip the timeline has no way to
+ * explain. **Never throws** — the webhook answers the provider 200 whatever
+ * happens here, so a failure is logged and reported rather than raised.
+ */ export async function recordCrmEmailDelivery(firestore, input) {
+    const { orgId, activityId, state } = input;
+    if (!orgId || !activityId) return 'missing';
+    const ref = crmActivityRef(firestore, orgId, activityId);
+    try {
+        return await firestore.runTransaction(async (transaction)=>{
+            const snapshot = await transaction.get(ref);
+            if (!snapshot.exists || snapshot.get('kind') !== 'email') return 'missing';
+            const current = snapshot.get('deliveryState');
+            const next = nextCrmEmailDeliveryState(current, state);
+            if (next === current) return 'unchanged';
+            transaction.update(ref, {
+                deliveryState: next,
+                deliveryAtMs: Number.isFinite(input.atMs) ? input.atMs : Date.now(),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+            return 'advanced';
+        });
+    } catch (error) {
+        console.error('[crm] email delivery state write failed', orgId, activityId, error);
+        return 'failed';
+    }
+}
+/**
+ * `orgs/{orgId}/crmActivities/{id}` for a CAPTURED message (AGL-2657), with
+ * the id derived from the message's key — its `Message-ID`, else the
+ * provider's id — so a second delivery of one message addresses the row
+ * the first delivery wrote. A hash rather than the key itself, because a
+ * `Message-ID` carries `<`, `@` and `/`, which a document id may not.
+ */ export function crmCapturedEmailActivityRef(firestore, orgId, key) {
+    const digest = createHash('sha256').update(key).digest('hex').slice(0, 28);
+    return crmActivityRef(firestore, orgId, `cap_${digest}`);
+}
+const isAlreadyExists = (error)=>{
+    var _ref;
+    const failure = error;
+    return (failure == null ? void 0 : failure.code) === 6 || (failure == null ? void 0 : failure.code) === 'already-exists' || /ALREADY_EXISTS/i.test(String((_ref = failure == null ? void 0 : failure.message) != null ? _ref : ''));
+};
+/**
+ * Writes a captured message's row ONCE: `create()`, which refuses a
+ * document that already exists, is what makes two deliveries of one
+ * message one row even when they arrive together — the second create is
+ * the one Firestore refuses, and this answers `duplicate` for it. Any
+ * other failure is the caller's.
+ */ export async function createCrmEmailActivity(ref, activity) {
+    try {
+        await ref.create(_extends({}, activity, {
+            createdAt: FieldValue.serverTimestamp(),
+            updatedAt: FieldValue.serverTimestamp()
+        }));
+        return 'created';
+    } catch (error) {
+        if (isAlreadyExists(error)) return 'duplicate';
+        throw error;
+    }
+}
+
+//# sourceMappingURL=crm-email-activity.js.map

package/src/lib/server/crm-email-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/crm-email-activity.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  CRM_COLLECTIONS,\n  type CrmActivity,\n  type CrmEmailDeliveryState,\n  isCrmEmailDeliveryState,\n  nextCrmEmailDeliveryState,\n} from '@aglyn/aglyn/server'\nimport { createHash } from 'crypto'\nimport { FieldValue } from 'firebase-admin/firestore'\n\n/**\n * The activity row a one-to-one email is logged as, on the server side\n * (AGL-2615): where it lives, how it is written, and how the delivery\n * webhook moves its state.\n *\n * Two writers log a sent email — the console's `crm/email-send` route and\n * the `sendEmail` automation step — and one reader advances it, the Resend\n * event webhook. The reader has to find the row from nothing but the tags\n * on the message, so the id is minted BEFORE the send and stamped on it,\n * and the row is written only after the provider accepted the message. A\n * row written first would be an \"email\" on the timeline for a message that\n * never left.\n *\n * Firestore is a parameter throughout, as in `crm-records.ts`: the callers\n * hold one, and a module that reached for the Admin app itself would drag\n * it into every spec that only wants the arithmetic.\n */\n\n/** `orgs/{orgId}/crmActivities/{activityId}`. */\nexport function crmActivityRef(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  activityId: string,\n): FirebaseFirestore.DocumentReference {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(CRM_COLLECTIONS.activities)\n    .doc(activityId)\n}\n\n/**\n * A fresh reference for the row a send is about to earn — `doc()` with no\n * id mints one locally and reads nothing, so the id can ride the message\n * as a tag before anything is written.\n */\nexport function newCrmActivityRef(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n): FirebaseFirestore.DocumentReference {\n  return firestore\n    .collection('orgs')\n    .doc(orgId)\n    .collection(CRM_COLLECTIONS.activities)\n    .doc()\n}\n\n/**\n * Writes the row a sent email is logged as, stamped with the server clock.\n *\n * `set` rather than `add`, because the id was minted ahead of the send and\n * is already on the message; a second id here would be the one the webhook\n * could not find.\n */\nexport async function writeCrmEmailActivity(\n  ref: FirebaseFirestore.DocumentReference,\n  activity: CrmActivity,\n): Promise<void> {\n  await ref.set({\n    ...activity,\n    createdAt: FieldValue.serverTimestamp(),\n    updatedAt: FieldValue.serverTimestamp(),\n  })\n}\n\n/**\n * Which delivery state one normalized delivery event moves a row to, or\n * `null` for an event that moves nothing.\n *\n * Takes the log's own vocabulary (`EmailDeliveryEventType`) rather than the\n * provider's wire strings: `normalizeResendDeliveryEvents` is the one place\n * that reads those, and this module must not become a second. The five\n * states the timeline shows share the log's names exactly, so the mapping\n * is membership; `delayed` and `failed` are the log's own and the row keeps\n * whatever it held.\n */\nexport function crmEmailDeliveryStateForEvent(\n  type: string | null | undefined,\n): CrmEmailDeliveryState | null {\n  return isCrmEmailDeliveryState(type) ? type : null\n}\n\nexport type CrmEmailDeliveryOutcome =\n  /** The row moved to the incoming state. */\n  | 'advanced'\n  /** The row already held this state or a later one; nothing written. */\n  | 'unchanged'\n  /** No email activity by that id in that org; nothing written. */\n  | 'missing'\n  /** The read or the write threw; logged, and nothing is promised. */\n  | 'failed'\n\n/**\n * One delivery event, onto the activity row it names (AGL-2615).\n *\n * A TRANSACTION, because the rule is \"keep the later state\" and two events\n * for one message routinely arrive together — `delivered` and `opened`\n * within the same second from a mail client that fetches images on\n * receipt. Two plain read-then-writes interleaved would let the earlier\n * event land last and print \"Delivered\" over an open that already\n * happened; inside a transaction the second read sees the first write and\n * `nextCrmEmailDeliveryState` answers \"unchanged\".\n *\n * A row that is not an email activity is left alone: the tag named it, but\n * a delivery state on a call log would be a chip the timeline has no way to\n * explain. **Never throws** — the webhook answers the provider 200 whatever\n * happens here, so a failure is logged and reported rather than raised.\n */\nexport async function recordCrmEmailDelivery(\n  firestore: FirebaseFirestore.Firestore,\n  input: {\n    orgId: string\n    activityId: string\n    state: CrmEmailDeliveryState\n    /** When the provider says it happened, epoch ms. */\n    atMs: number\n  },\n): Promise<CrmEmailDeliveryOutcome> {\n  const { orgId, activityId, state } = input\n  if (!orgId || !activityId) return 'missing'\n  const ref = crmActivityRef(firestore, orgId, activityId)\n  try {\n    return await firestore.runTransaction(async (transaction) => {\n      const snapshot = await transaction.get(ref)\n      if (!snapshot.exists || snapshot.get('kind') !== 'email') return 'missing'\n      const current = snapshot.get('deliveryState')\n      const next = nextCrmEmailDeliveryState(current, state)\n      if (next === current) return 'unchanged'\n      transaction.update(ref, {\n        deliveryState: next,\n        deliveryAtMs: Number.isFinite(input.atMs) ? input.atMs : Date.now(),\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n      return 'advanced'\n    })\n  } catch (error) {\n    console.error('[crm] email delivery state write failed', orgId, activityId, error)\n    return 'failed'\n  }\n}\n\n/**\n * `orgs/{orgId}/crmActivities/{id}` for a CAPTURED message (AGL-2657), with\n * the id derived from the message's key — its `Message-ID`, else the\n * provider's id — so a second delivery of one message addresses the row\n * the first delivery wrote. A hash rather than the key itself, because a\n * `Message-ID` carries `<`, `@` and `/`, which a document id may not.\n */\nexport function crmCapturedEmailActivityRef(\n  firestore: FirebaseFirestore.Firestore,\n  orgId: string,\n  key: string,\n): FirebaseFirestore.DocumentReference {\n  const digest = createHash('sha256').update(key).digest('hex').slice(0, 28)\n  return crmActivityRef(firestore, orgId, `cap_${digest}`)\n}\n\n/** What a create answered: the row is new, or it was already there. */\nexport type CrmEmailActivityCreateOutcome = 'created' | 'duplicate'\n\nconst isAlreadyExists = (error: unknown): boolean => {\n  const failure = error as { code?: unknown; message?: unknown } | null\n  return (\n    failure?.code === 6 ||\n    failure?.code === 'already-exists' ||\n    /ALREADY_EXISTS/i.test(String(failure?.message ?? ''))\n  )\n}\n\n/**\n * Writes a captured message's row ONCE: `create()`, which refuses a\n * document that already exists, is what makes two deliveries of one\n * message one row even when they arrive together — the second create is\n * the one Firestore refuses, and this answers `duplicate` for it. Any\n * other failure is the caller's.\n */\nexport async function createCrmEmailActivity(\n  ref: FirebaseFirestore.DocumentReference,\n  activity: CrmActivity,\n): Promise<CrmEmailActivityCreateOutcome> {\n  try {\n    await ref.create({\n      ...activity,\n      createdAt: FieldValue.serverTimestamp(),\n      updatedAt: FieldValue.serverTimestamp(),\n    })\n    return 'created'\n  } catch (error) {\n    if (isAlreadyExists(error)) return 'duplicate'\n    throw error\n  }\n}\n"],"names":["CRM_COLLECTIONS","isCrmEmailDeliveryState","nextCrmEmailDeliveryState","createHash","FieldValue","crmActivityRef","firestore","orgId","activityId","collection","doc","activities","newCrmActivityRef","writeCrmEmailActivity","ref","activity","set","createdAt","serverTimestamp","updatedAt","crmEmailDeliveryStateForEvent","type","recordCrmEmailDelivery","input","state","runTransaction","transaction","snapshot","get","exists","current","next","update","deliveryState","deliveryAtMs","Number","isFinite","atMs","Date","now","error","console","crmCapturedEmailActivityRef","key","digest","slice","isAlreadyExists","failure","code","test","String","message","createCrmEmailActivity","create"],"mappings":"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"}

package/src/lib/server/crm-inbound-email.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @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 CrmActivityLink, type CrmEmailDirection, type CrmInboundCandidate, type CrmInboundMember } from '@aglyn/aglyn/server';
+import type { ReceivedEmail } from '@aglyn/shared-util-email';
+/**
+ * EMAIL CAPTURE (AGL-2657): the half with Firestore.
+ *
+ * The org's capture token — minted once, replaced on a rotation, found
+ * again from a message's recipient — and the filing of one received
+ * message: which record it was with, whether it has been filed before, and
+ * the row it becomes. The pure rules are `@aglyn/aglyn`'s
+ * `crm-inbound.ts`; this module is the reads and the one write.
+ *
+ * Firestore is a parameter throughout, as in `crm-records.ts` and
+ * `crm-email-activity.ts`: the routes hold one, and a module that reached
+ * for the Admin app itself would drag it into every spec that only wants
+ * the matching. The roster is read through that same store by
+ * `loadCrmInboundRoster`, and the caller writes the org's feed line, so a
+ * spec of this module needs a store and nothing else.
+ */
+/** The most candidate addresses one message is matched by. */
+export declare const CRM_INBOUND_CANDIDATE_MAX = 6;
+/** The most sites whose leads are consulted for one message. */
+export declare const CRM_INBOUND_LEAD_HOST_MAX = 50;
+export interface CrmInboundTokenResult {
+    token: string;
+    createdAtMs: number;
+    rotatedAtMs?: number;
+    /** True when this call replaced a token that existed. */
+    rotated: boolean;
+}
+/**
+ * The org's capture token, minted the first time anybody asks and kept
+ * thereafter; with `rotate`, replaced. A transaction, so two members
+ * opening the settings page at once mint one token and not two, and a
+ * rotation lands on the token the reader saw.
+ */
+export declare function ensureCrmInboundToken(firestore: FirebaseFirestore.Firestore, orgId: string, options?: {
+    rotate?: boolean;
+    nowMs?: number;
+}): Promise<CrmInboundTokenResult>;
+/**
+ * The org a capture token names, or `null`. One equality on
+ * `crmInbound.token`, which Firestore indexes on its own; a token that is
+ * not one by shape is refused before the query, so a malformed local part
+ * costs no read.
+ */
+export declare function findOrgByCrmInboundToken(firestore: FirebaseFirestore.Firestore, token: unknown): Promise<{
+    orgId: string;
+    org: Record<string, unknown>;
+} | null>;
+/**
+ * Every site of the organization, by id, up to the ceiling — the set a
+ * message's lead lookup sweeps. One equality on `hosts.orgId`.
+ */
+export declare function crmInboundHostIds(firestore: FirebaseFirestore.Firestore, orgId: string): Promise<string[]>;
+/** The record one of a message's addresses resolved to. */
+export interface CrmInboundMatch {
+    email: string;
+    direction: CrmEmailDirection;
+    kind: 'contact' | 'lead';
+    /** Where the row is filed. */
+    link: CrmActivityLink;
+    /** The site the row is stamped with — the record's own. */
+    hostId: string;
+    /** Who may list the row — the record's own tokens. */
+    visibleTo: string[];
+}
+/**
+ * The first candidate that is a contact of the org — through the address
+ * index, so a merged record's alternate address answers — or a lead on any
+ * of its sites. Candidates are tried in the order the rule gave them and
+ * the first hit wins; a contact is looked for before a lead at each
+ * address, because a converted lead's address is its contact's.
+ */
+export declare function matchCrmInboundCorrespondent(firestore: FirebaseFirestore.Firestore, input: {
+    orgId: string;
+    org: Record<string, unknown>;
+    candidates: readonly CrmInboundCandidate[];
+    hostIds: readonly string[];
+}): Promise<CrmInboundMatch | null>;
+/**
+ * The workspace's roster as the filer matches against it: the member
+ * documents and every member's stored alias document, two reads under the
+ * org, reduced by `crmInboundRoster` to each member's sign-in address and
+ * the aliases they have confirmed (AGL-2975).
+ */
+export declare function loadCrmInboundRoster(firestore: FirebaseFirestore.Firestore, orgId: string): Promise<CrmInboundMember[]>;
+export type CrmInboundFileOutcome = 
+/** A row was written. */
+{
+    outcome: 'filed';
+    activityId: string;
+    match: CrmInboundMatch;
+}
+/** The message had been filed before; nothing written. */
+ | {
+    outcome: 'duplicate';
+    activityId: string;
+}
+/** No address on the message is a record of the org; nothing written. */
+ | {
+    outcome: 'unmatched';
+    senderDomain: string | null;
+}
+/** The record's activity log is at its ceiling; nothing written. */
+ | {
+    outcome: 'ceiling';
+    match: CrmInboundMatch;
+};
+/**
+ * Files one received message on the record it was with (AGL-2657).
+ *
+ * The order is the cost: the candidate rule is arithmetic; the match is
+ * the reads that decide everything after it; a message filed before is
+ * answered off one read of the row it would write, before the ceiling's
+ * aggregate; the ceiling comes last and refuses rather than dropping a row
+ * on a full log. The write is a `create`, so two deliveries racing past
+ * the read still yield one row. The BODY never leaves this function except
+ * as the bounded excerpt in the row.
+ */
+export declare function fileCrmInboundEmail(firestore: FirebaseFirestore.Firestore, input: {
+    orgId: string;
+    org: Record<string, unknown>;
+    message: ReceivedEmail;
+    /** The capture domain, so the capture address is never the correspondent. */
+    domain: string;
+    /** The roster, from `loadCrmInboundRoster`: sign-in addresses and confirmed aliases. */
+    members: readonly CrmInboundMember[];
+    hostIds: readonly string[];
+}): Promise<CrmInboundFileOutcome>;