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

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,139 @@
+/**
+ * @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
+ * CONTACT the sender means — 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>;