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

package/src/lib/server/assign-contact-owner.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @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 ContactSource, type CrmAssignmentTarget } from '@aglyn/aglyn/server';
+/**
+ * WHO A NEW RECORD BELONGS TO — the one place an owner is decided on the
+ * server (AGL-2618).
+ *
+ * Two entry points over one transaction. `assignOwnerForCapture` is the
+ * capture door's pass: it runs the org's assignment rules in order, falls
+ * back to the capturing site's default owner, and touches only a record
+ * that has NO owner — a door that named one (the console's drawer, an
+ * import column, a conversion with a picked owner) has expressed a person's
+ * choice. `reassignContactOwner` is the automation's: an author who put
+ * "assign an owner" on a stage change means to reassign, and the step hands
+ * this either a member or the rotation.
+ *
+ * ## One transaction, because the pointer is shared
+ *
+ * The round-robin pool's pointer lives on the org document, and two
+ * captures landing together must take two different members. Firestore
+ * transactions serialize on what they read, so the org document, the
+ * contact and the roster documents are all read inside the transaction and
+ * the pointer is advanced in the same commit that writes the owner: a
+ * concurrent capture that read the same pointer retries and reads the moved
+ * one. The alternative — read the pointer, decide, then write — is exactly
+ * the read-then-write shape that lets two captures pick the same person.
+ *
+ * ## The roster is checked, once per member per attempt
+ *
+ * A rule may name a member who has since left, and a pool may hold one. A
+ * rule naming nobody on the roster is passed over rather than stopping the
+ * pass — the next rule may well assign — and a pool member who is gone is
+ * skipped for the next in the order. `orgs/{orgId}/members/{uid}` is keyed
+ * by uid, so the check is one document read per candidate, and only the
+ * roster is consulted: a project-level Auth lookup would admit people who
+ * are not on this organization at all (AGL-1122).
+ *
+ * ## The lead follows the contact
+ *
+ * The capture doors that file a lead (`addHostLead`: a form routed to leads,
+ * a sign-up, a booking) key it by `personKey(email)`, so the lead's document
+ * is addressable from the capture alone. When it exists it is given the same
+ * owner in the same transaction; two doors write the lead AFTER the contact
+ * they `void`ed, so for those sources the mirror is retried a few times over
+ * the next seconds, detached, and the person's Leads list shows the owner
+ * as soon as the lead is there.
+ *
+ * ## The owner is told, unless they chose themselves
+ *
+ * One console notification per assignment, for the record the recipient
+ * will open: the lead when the site holds one for this person, the contact
+ * otherwise. Not when the actor IS the new owner — a rep who converts a
+ * lead into their own contact has not been handed anything.
+ *
+ * ## Never rejects
+ *
+ * The capture has already succeeded and a form submission must not fail
+ * because the CRM could not decide who follows up; a failure is logged and
+ * answered as `none`, and the record is exactly as assignable by hand as it
+ * was before this existed. The automation executor turns a `none` into the
+ * step's recorded error.
+ */
+export interface OwnerAssignmentInput {
+    hostId: string;
+    /** `orgs/{orgId}/contacts/{contactId}` — the record the owner is written on. */
+    contactId: string;
+    /** The contact's address, which keys the lead and names the person in the notification. */
+    email: string;
+    /**
+     * The signed-in person making the assignment, when there is one. Never
+     * notified about their own choice; absent for a capture and an automation.
+     */
+    actorUid?: string | null;
+}
+export interface CaptureAssignmentInput extends OwnerAssignmentInput {
+    source: ContactSource;
+    /** The form the capture came through, for a rule conditioned on it. */
+    formId?: string | null;
+    /** The tags the capture carried; the contact's own are read from the facet. */
+    tags?: readonly string[];
+}
+export interface ReassignmentInput extends OwnerAssignmentInput {
+    assign: CrmAssignmentTarget;
+}
+/** Why an assignment assigned nobody — the automation reports these verbatim. */
+export type OwnerAssignmentRefusal = 'no-org' | 'no-contact' | 'no-rule' | 'empty-pool' | 'not-a-member' | 'failed';
+/** What decided an assignment: a rule, the site default, the step's member, or the rotation. */
+export type OwnerAssignedBy = 'rule' | 'default' | 'member' | 'roundRobin';
+export type OwnerAssignment = {
+    outcome: 'assigned';
+    ownerUid: string;
+    by: OwnerAssignedBy;
+    /** The rule that decided it, when one did. */
+    ruleId?: string;
+    /** The lead document existed and now carries the owner too. */
+    leadMirrored: boolean;
+    /** A notification was fanned out to the new owner. */
+    notified: boolean;
+}
+/** The record already had this owner (a capture), or the same one was named again (a reassignment). */
+ | {
+    outcome: 'unchanged';
+    ownerUid: string;
+} | {
+    outcome: 'none';
+    reason: OwnerAssignmentRefusal;
+};
+/** The words the run history and the log give each refusal. */
+export declare const OWNER_ASSIGNMENT_REFUSALS: Record<OwnerAssignmentRefusal, string>;
+/** The record an assignment notification opens. */
+export type AssignedRecord = {
+    kind: 'contact';
+    id: string;
+} | {
+    kind: 'lead';
+    id: string;
+};
+/**
+ * Tells a member a record is now theirs — one console notification, typed
+ * by the record it opens — unless the member handed it to themselves.
+ * Shared by the pass above and by the routes where a person picks the
+ * owner outright (a lead conversion naming a colleague), so every server
+ * path that writes `ownerUid` says so in the same words. Never throws;
+ * the fan-out swallows its own failures.
+ */
+export declare function notifyRecordAssigned(input: {
+    hostId: string;
+    orgId: string;
+    ownerUid: string;
+    actorUid?: string | null;
+    record: AssignedRecord;
+    /** How the person reads in the message: their name, else their address. */
+    who: string;
+}): Promise<boolean>;
+/**
+ * The capture door's pass: the org's rules in order, then the capturing
+ * site's default owner, on a record that has no owner yet. See the module
+ * comment for the whole of it.
+ */
+export declare function assignOwnerForCapture(input: CaptureAssignmentInput): Promise<OwnerAssignment>;
+/**
+ * The deliberate assignment — the `assignContactOwner` step, and a person
+ * handing a record to somebody: a member by uid (verified on the roster) or
+ * the next in the round-robin pool, overwriting whoever held it. Naming the
+ * owner the record already has changes nothing and tells nobody.
+ */
+export declare function reassignContactOwner(input: ReassignmentInput): Promise<OwnerAssignment>;
+export default assignOwnerForCapture;

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

@@ -0,0 +1,340 @@
+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 { assignmentRuleMatches, consentGroupForHost, contactFacetPath, CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH, personKey, readContactFacet, readCrmAssignmentSettings, roundRobinOrder } from "@aglyn/aglyn/server";
+import { firebaseAdmin, getHostDocAdmin, getOrgForHost, hostDisplayName, notifyUsers, restampCrmListFieldsAt } from "@aglyn/tenant-data-admin";
+import { FieldValue } from "firebase-admin/firestore";
+/** The words the run history and the log give each refusal. */ export const OWNER_ASSIGNMENT_REFUSALS = {
+    'no-org': 'this site has no organization',
+    'no-contact': 'the contact no longer exists',
+    'no-rule': 'no assignment rule matched and the site has no default owner',
+    'empty-pool': 'the round-robin pool has nobody on the roster in it',
+    'not-a-member': 'the owner named is not on the team',
+    failed: 'the owner could not be assigned'
+};
+/**
+ * The doors whose lead lands after the contact they `void`ed — the ones the
+ * mirror is worth retrying for. An order, an import, a manual add and an
+ * API call file no lead, and a retry for them would be reads for nothing.
+ */ const LEAD_FILING_SOURCES = new Set([
+    'form',
+    'member',
+    'booking'
+]);
+/** How long the detached lead mirror waits between its looks, in order. */ const LEAD_MIRROR_RETRY_MS = [
+    1000,
+    2000,
+    3000
+];
+/**
+ * The console path the owner's notification opens, in the `/{hostDocId}/rest`
+ * shape every host notification uses — the console rewrites it to
+ * `/{orgSlug}/hosts/{subdomain}/rest` when the link is followed, which is
+ * why `hostId` and `orgId` travel on the document. The same spelling the
+ * CRM's task notification uses; the hub's own route builder lives in the
+ * plugin, which this layer cannot import.
+ */ function recordLink(hostId, record) {
+    const section = record.kind === 'contact' ? 'contacts' : 'leads';
+    return `/${hostId}/crm/${section}/${encodeURIComponent(record.id)}`;
+}
+/**
+ * Tells a member a record is now theirs — one console notification, typed
+ * by the record it opens — unless the member handed it to themselves.
+ * Shared by the pass above and by the routes where a person picks the
+ * owner outright (a lead conversion naming a colleague), so every server
+ * path that writes `ownerUid` says so in the same words. Never throws;
+ * the fan-out swallows its own failures.
+ */ export async function notifyRecordAssigned(input) {
+    var _input_actorUid;
+    if (!input.ownerUid || input.ownerUid === ((_input_actorUid = input.actorUid) != null ? _input_actorUid : '')) return false;
+    const lead = input.record.kind === 'lead';
+    /*
+   * THE BODY SAYS WHAT HAPPENED, AND ON WHICH SITE (AGL-3432).
+   *
+   * It was the bare name, so a member who owns records on several sites read
+   * "Ada" in an email body and could not tell what Ada was or where. The
+   * site's name is one request-cached read of a document most callers have
+   * already paid for, taken only when somebody is actually notified; a read
+   * that fails drops the "on {site}" clause rather than the notification.
+   */ let site = '';
+    try {
+        const host = await getHostDocAdmin(input.hostId);
+        if (host) site = ` on ${hostDisplayName(host, input.hostId)}`;
+    } catch (unused) {
+    // The clause goes, never the notification.
+    }
+    await notifyUsers([
+        input.ownerUid
+    ], {
+        type: lead ? 'content.leadAssigned' : 'content.contactAssigned',
+        title: lead ? 'Lead assigned to you' : 'Contact assigned to you',
+        body: `${input.who} was assigned to you as a ${lead ? 'lead' : 'contact'}${site}.`,
+        link: recordLink(input.hostId, input.record),
+        orgId: input.orgId,
+        hostId: input.hostId
+    });
+    return true;
+}
+async function assignOwner(policy) {
+    const { input } = policy;
+    try {
+        const resolved = await getOrgForHost(input.hostId);
+        if (!resolved) return {
+            outcome: 'none',
+            reason: 'no-org'
+        };
+        const { orgId } = resolved;
+        const firestore = firebaseAdmin.app().firestore();
+        const orgRef = firestore.collection('orgs').doc(orgId);
+        const contactRef = orgRef.collection('contacts').doc(input.contactId);
+        const membersRef = orgRef.collection('members');
+        const leadKey = personKey(input.email);
+        // Beside the contact on the org, keyed by the same address (AGL-3275).
+        const leadRef = leadKey ? orgRef.collection('leads').doc(leadKey) : null;
+        let contactName = '';
+        const verdict = await firestore.runTransaction(async (tx)=>{
+            var _orgSnapshot_data, _contactSnapshot_data, _contact_name, _ref;
+            /*
+         * ALL READS BEFORE THE WRITE, which Firestore requires. The org
+         * document is read here rather than trusted from `getOrgForHost`,
+         * because the pointer it carries is the one thing a concurrent
+         * capture may have moved, and the rules and the pool are read from
+         * the same snapshot so the decision and the pointer agree.
+         */ const [orgSnapshot, contactSnapshot, leadSnapshot] = await Promise.all([
+                tx.get(orgRef),
+                tx.get(contactRef),
+                leadRef ? tx.get(leadRef) : Promise.resolve(null)
+            ]);
+            if (!contactSnapshot.exists) {
+                return {
+                    outcome: 'none',
+                    reason: 'no-contact'
+                };
+            }
+            const org = (_orgSnapshot_data = orgSnapshot.data()) != null ? _orgSnapshot_data : {};
+            const contact = (_contactSnapshot_data = contactSnapshot.data()) != null ? _contactSnapshot_data : {};
+            contactName = String((_contact_name = contact['name']) != null ? _contact_name : '');
+            const group = consentGroupForHost(org, input.hostId);
+            const facet = readContactFacet(contact, group.groupId);
+            const current = typeof facet.ownerUid === 'string' ? facet.ownerUid : '';
+            if (policy.kind === 'capture' && current) {
+                return {
+                    outcome: 'unchanged',
+                    ownerUid: current
+                };
+            }
+            const settings = readCrmAssignmentSettings(org);
+            // One read per candidate per attempt; a retried transaction reads
+            // afresh, as it must.
+            const onRoster = new Map();
+            const isMember = (uid)=>{
+                let known = onRoster.get(uid);
+                if (!known) {
+                    known = tx.get(membersRef.doc(uid)).then((snapshot)=>snapshot.exists);
+                    onRoster.set(uid, known);
+                }
+                return known;
+            };
+            const fromPool = async ()=>{
+                for (const uid of roundRobinOrder(settings.pool.memberUids, settings.pool.lastAssignedUid)){
+                    if (await isMember(uid)) return uid;
+                }
+                return null;
+            };
+            const resolveTarget = async (target)=>{
+                if ('roundRobin' in target) {
+                    const uid = await fromPool();
+                    return uid ? {
+                        uid,
+                        advancePointer: true
+                    } : null;
+                }
+                return await isMember(target.memberUid) ? {
+                    uid: target.memberUid,
+                    advancePointer: false
+                } : null;
+            };
+            let decision = null;
+            let refusal = 'no-rule';
+            if (policy.kind === 'capture') {
+                var _policy_input_formId, _policy_input_tags, _facet_tags;
+                const capture = {
+                    source: policy.input.source,
+                    email: input.email,
+                    formId: (_policy_input_formId = policy.input.formId) != null ? _policy_input_formId : null,
+                    tags: [
+                        ...(_policy_input_tags = policy.input.tags) != null ? _policy_input_tags : [],
+                        ...(_facet_tags = facet.tags) != null ? _facet_tags : []
+                    ]
+                };
+                for (const rule of settings.rules){
+                    if (!assignmentRuleMatches(rule.when, capture)) continue;
+                    const hit = await resolveTarget(rule.assign);
+                    if (hit) {
+                        decision = _extends({}, hit, {
+                            ownerUid: hit.uid,
+                            by: 'rule',
+                            ruleId: rule.id
+                        });
+                        break;
+                    }
+                }
+                const fallback = settings.hostDefaultOwners[input.hostId];
+                if (!decision && fallback && await isMember(fallback)) {
+                    decision = {
+                        ownerUid: fallback,
+                        by: 'default',
+                        advancePointer: false
+                    };
+                }
+            } else {
+                const { assign } = policy.input;
+                const hit = await resolveTarget(assign);
+                if (hit) {
+                    decision = _extends({}, hit, {
+                        ownerUid: hit.uid,
+                        by: 'roundRobin' in assign ? 'roundRobin' : 'member'
+                    });
+                } else {
+                    refusal = 'roundRobin' in assign ? 'empty-pool' : 'not-a-member';
+                }
+            }
+            if (!decision) return {
+                outcome: 'none',
+                reason: refusal
+            };
+            if (decision.ownerUid === current) {
+                return {
+                    outcome: 'unchanged',
+                    ownerUid: current
+                };
+            }
+            tx.update(contactRef, {
+                [contactFacetPath(group.groupId, 'ownerUid')]: decision.ownerUid,
+                updatedAt: FieldValue.serverTimestamp()
+            });
+            if (decision.advancePointer) {
+                tx.update(orgRef, {
+                    [CRM_ROUND_ROBIN_LAST_ASSIGNED_PATH]: decision.ownerUid
+                });
+            }
+            /*
+         * A lead somebody already assigned by hand keeps its owner on a
+         * capture — the contact was new, the lead may not have been — and
+         * follows the contact on a deliberate reassignment.
+         */ const leadOwner = String((_ref = leadSnapshot == null ? void 0 : leadSnapshot.get('ownerUid')) != null ? _ref : '');
+            const leadMirrored = Boolean((leadSnapshot == null ? void 0 : leadSnapshot.exists) && (policy.kind === 'reassign' || !leadOwner));
+            if (leadMirrored && leadRef) {
+                tx.update(leadRef, {
+                    ownerUid: decision.ownerUid,
+                    updatedAt: FieldValue.serverTimestamp()
+                });
+            }
+            return _extends({
+                outcome: 'assigned',
+                ownerUid: decision.ownerUid,
+                by: decision.by
+            }, decision.ruleId ? {
+                ruleId: decision.ruleId
+            } : {}, {
+                leadMirrored,
+                notified: false
+            });
+        });
+        if (verdict.outcome !== 'assigned') return verdict;
+        // The owner is what the Contacts list filters by (AGL-3321).
+        await restampCrmListFieldsAt(contactRef, 'contacts');
+        if (!verdict.leadMirrored && leadRef && policy.kind === 'capture' && LEAD_FILING_SOURCES.has(policy.input.source)) {
+            void mirrorOwnerOntoLeadLater(leadRef, verdict.ownerUid);
+        }
+        const notified = await notifyRecordAssigned({
+            hostId: input.hostId,
+            orgId,
+            ownerUid: verdict.ownerUid,
+            actorUid: input.actorUid,
+            record: verdict.leadMirrored && leadKey ? {
+                kind: 'lead',
+                id: leadKey
+            } : {
+                kind: 'contact',
+                id: input.contactId
+            },
+            who: contactName || input.email
+        });
+        return _extends({}, verdict, {
+            notified
+        });
+    } catch (error) {
+        console.error('assignContactOwner failed', input.hostId, input.contactId, error);
+        return {
+            outcome: 'none',
+            reason: 'failed'
+        };
+    }
+}
+/**
+ * The detached second look for a lead that lands after the contact.
+ *
+ * Bounded, and only ever ADDS an owner: a lead that arrived with one (a
+ * person assigned it in the meantime) is left alone, and a lead that never
+ * arrives costs three reads over six seconds and nothing else. Detached
+ * because the capture must not hold `contactCreated` back for it — an
+ * automation welcoming the contact has nothing to do with the lead's owner
+ * column.
+ */ async function mirrorOwnerOntoLeadLater(leadRef, ownerUid, delaysMs = LEAD_MIRROR_RETRY_MS) {
+    for (const delay of delaysMs){
+        await new Promise((resolve)=>setTimeout(resolve, delay));
+        try {
+            var _lead_get;
+            const lead = await leadRef.get();
+            if (!lead.exists) continue;
+            if (String((_lead_get = lead.get('ownerUid')) != null ? _lead_get : '')) return false;
+            await leadRef.update({
+                ownerUid,
+                updatedAt: FieldValue.serverTimestamp()
+            });
+            return true;
+        } catch (error) {
+            console.error('assignContactOwner lead mirror failed', leadRef.path, error);
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * The capture door's pass: the org's rules in order, then the capturing
+ * site's default owner, on a record that has no owner yet. See the module
+ * comment for the whole of it.
+ */ export function assignOwnerForCapture(input) {
+    return assignOwner({
+        kind: 'capture',
+        input
+    });
+}
+/**
+ * The deliberate assignment — the `assignContactOwner` step, and a person
+ * handing a record to somebody: a member by uid (verified on the roster) or
+ * the next in the round-robin pool, overwriting whoever held it. Naming the
+ * owner the record already has changes nothing and tells nobody.
+ */ export function reassignContactOwner(input) {
+    return assignOwner({
+        kind: 'reassign',
+        input
+    });
+}
+export default assignOwnerForCapture;
+
+//# sourceMappingURL=assign-contact-owner.js.map

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-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-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\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\n        // One read per candidate per attempt; a retried transaction reads\n        // afresh, as it must.\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\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\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","assignOwner","policy","resolved","outcome","reason","firestore","app","orgRef","collection","doc","contactRef","contactId","membersRef","leadKey","email","leadRef","contactName","verdict","runTransaction","tx","orgSnapshot","contactSnapshot","contact","leadSnapshot","Promise","all","get","resolve","exists","org","data","String","group","facet","groupId","current","settings","onRoster","Map","isMember","uid","known","then","snapshot","set","fromPool","pool","memberUids","lastAssignedUid","resolveTarget","target","advancePointer","memberUid","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"],"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;