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

package/src/lib/server/person-records.js

@@ -0,0 +1,317 @@
+/**
+ * @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 { containerMembershipField, contactContainerFieldPath, normalizeContainerIds } from "@aglyn/aglyn/app-utils/container-membership";
+import { normalizeContactEmail } from "@aglyn/aglyn/app-utils/contacts";
+import { CRM_COLLECTIONS, crmLeadStatus, crmViewIsListed, isCrmLeadOpen, normalizeCrmViewFilters } from "@aglyn/aglyn/app-utils/crm";
+import { dynamicListDimensionsForCrmView } from "@aglyn/aglyn/app-utils/dynamic-list-rule";
+import { personKey } from "@aglyn/aglyn/app-utils/person-key";
+import { scopeTokensForHost, seenOnlyThroughGrant, visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { consentGroupForSite, firebaseAdmin, resolveOrgIdForHost } from "@aglyn/tenant-data-admin";
+// The leaves, not the barrel: this plugin's specs substitute the barrel
+// wholesale, and the lookup and the restamp must reach the real logic.
+import { findContactByEmail } from "@aglyn/tenant-data-admin/server/contact-email-index";
+import { restampCrmListFieldsAt } from "@aglyn/tenant-data-admin/server/crm-records";
+import { collectDynamicListCandidates } from "@aglyn/tenant-data-admin/server/dynamic-list-materialize";
+import { FieldValue } from "firebase-admin/firestore";
+import { recordPersonRefund } from "./person-refund.js";
+/** The person kinds, as `plugin-record-routes` addresses them. */ export const CRM_PERSON_KINDS = {
+    contact: 'contact',
+    lead: 'lead'
+};
+/** The collection each person kind is stored in, under the organization. */ const STORED_IN = {
+    [CRM_PERSON_KINDS.contact]: 'contacts',
+    [CRM_PERSON_KINDS.lead]: 'leads'
+};
+/** `getAll` takes this many references per call. */ const GET_ALL_CHUNK = 300;
+/**
+ * The most leads a saved Leads view is taken from: the site's most recently
+ * seen, the Leads list's own window (AGL-3234).
+ */ export const CRM_LEADS_VIEW_WINDOW = 200;
+export function defaultCrmPersonRecordsDeps() {
+    return {
+        firestore: ()=>firebaseAdmin.app().firestore(),
+        orgIdForHost: async (hostId)=>{
+            var _ref;
+            return (_ref = await resolveOrgIdForHost(hostId)) != null ? _ref : null;
+        },
+        groupIdForHost: async (hostId)=>(await consentGroupForSite(hostId)).groupId,
+        contactViewEmails: async ({ hostId, viewId })=>{
+            const scan = await collectDynamicListCandidates({
+                hostId,
+                rule: {
+                    sources: [
+                        'contacts'
+                    ],
+                    viewId
+                }
+            });
+            return {
+                emails: scan.candidates.map((candidate)=>candidate.email),
+                complete: scan.complete
+            };
+        }
+    };
+}
+function personOf(kind, snapshot) {
+    var _snapshot_data;
+    const data = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+    return {
+        kind,
+        id: snapshot.id,
+        email: normalizeContactEmail(data['email']),
+        data
+    };
+}
+/**
+ * The organization a request names, or the one its site belongs to. A site
+ * with no organization THROWS, as the org-data lookup every caller used to
+ * make threw: each caller has already decided which way a failed read falls.
+ */ async function orgOf(deps, request) {
+    var _request_orgId, _request_hostId;
+    const named = String((_request_orgId = request.orgId) != null ? _request_orgId : '').trim();
+    if (named) return named;
+    const hostId = String((_request_hostId = request.hostId) != null ? _request_hostId : '').trim();
+    const resolved = hostId ? await deps.orgIdForHost(hostId) : null;
+    if (!resolved) throw new Error(`[crm] no organization to find a person in for host ${hostId || '(none)'}`);
+    return resolved;
+}
+export function createCrmPersonRecords(deps) {
+    return {
+        /**
+     * The contact first, through the org's address index (AGL-2633) so an
+     * address a merge folded into another record still names the person who
+     * now holds it; then, for a caller that asked for any kind, the lead the
+     * address is keyed as. Narrowed to the site when asked, on the document
+     * the address names: a record the site cannot see is `null`.
+     */ async find (request) {
+            var _request_hostId;
+            const email = normalizeContactEmail(request.email);
+            if (!email) return null;
+            const orgId = await orgOf(deps, request);
+            const org = deps.firestore().collection('orgs').doc(orgId);
+            const hostId = String((_request_hostId = request.hostId) != null ? _request_hostId : '').trim();
+            const narrowTo = request.onlyVisibleToSite && hostId ? hostId : null;
+            const contact = await findContactByEmail(org.collection(STORED_IN[CRM_PERSON_KINDS.contact]), email, narrowTo ? {
+                hostId: narrowTo
+            } : {});
+            if (contact) return personOf(CRM_PERSON_KINDS.contact, contact);
+            if (!request.anyKind) return null;
+            const key = personKey(email);
+            if (!key) return null;
+            const lead = await org.collection(STORED_IN[CRM_PERSON_KINDS.lead]).doc(key).get();
+            if (!lead.exists) return null;
+            if (narrowTo && !visibleToHost(lead.get('visibleTo'), narrowTo)) {
+                return null;
+            }
+            return personOf(CRM_PERSON_KINDS.lead, lead);
+        },
+        /** Every record named, read at once; a kind the CRM does not keep is `null`. */ async read (request) {
+            const firestore = deps.firestore();
+            const org = firestore.collection('orgs').doc(request.orgId);
+            const refs = request.records.map((record)=>{
+                var _record_id;
+                const collection = STORED_IN[record.kind];
+                const id = String((_record_id = record.id) != null ? _record_id : '').trim();
+                return collection && id ? org.collection(collection).doc(id) : null;
+            });
+            const wanted = refs.filter((ref)=>ref !== null);
+            const snapshots = [];
+            for(let start = 0; start < wanted.length; start += GET_ALL_CHUNK){
+                snapshots.push(...await firestore.getAll(...wanted.slice(start, start + GET_ALL_CHUNK)));
+            }
+            let at = 0;
+            return request.records.map((record, index)=>{
+                if (!refs[index]) return null;
+                const snapshot = snapshots[at++];
+                return (snapshot == null ? void 0 : snapshot.exists) ? personOf(record.kind, snapshot) : null;
+            });
+        },
+        /**
+     * Files the person under the containers as the site holds them: on a
+     * contact, inside the site's consent-group facet — which campaigns a
+     * merchant filed somebody under is that merchant's record, and written at
+     * the top it would be readable by every site of an agency's account; on a
+     * lead, in the lead's own membership field, whose list fields are then
+     * restamped so the Leads list's filter finds it (AGL-3321).
+     *
+     * `update`, never a merge-set: a dotted path in `set` is a literal field
+     * name, and the record must exist. A record the site cannot see is not
+     * filed.
+     */ async fileUnder (request) {
+            var _request_record_id;
+            const ids = normalizeContainerIds(request.ids);
+            const collection = STORED_IN[request.record.kind];
+            const id = String((_request_record_id = request.record.id) != null ? _request_record_id : '').trim();
+            if (!ids.length || !collection || !id) return {
+                filed: false
+            };
+            const orgId = await orgOf(deps, request);
+            const ref = deps.firestore().collection('orgs').doc(orgId).collection(collection).doc(id);
+            const snapshot = await ref.get();
+            if (!snapshot.exists) return {
+                filed: false
+            };
+            if (!visibleToHost(snapshot.get('visibleTo'), request.hostId)) {
+                return {
+                    filed: false
+                };
+            }
+            if (request.record.kind === CRM_PERSON_KINDS.lead) {
+                await ref.update({
+                    [containerMembershipField(request.containerKind)]: FieldValue.arrayUnion(...ids),
+                    updatedAt: FieldValue.serverTimestamp()
+                });
+                await restampCrmListFieldsAt(ref, 'leads');
+                return {
+                    filed: true
+                };
+            }
+            const groupId = await deps.groupIdForHost(request.hostId);
+            await ref.update({
+                [contactContainerFieldPath(groupId, request.containerKind)]: FieldValue.arrayUnion(...ids),
+                updatedAt: FieldValue.serverTimestamp()
+            });
+            return {
+                filed: true
+            };
+        },
+        recordRefund: (request)=>recordPersonRefund(request),
+        /**
+     * The people a saved view selects for a site (AGL-3234). A colleague's
+     * private view is theirs: not listed for this member, so it does not
+     * exist for them here either.
+     *
+     * A Leads view takes the site's most recently seen leads —
+     * {@link CRM_LEADS_VIEW_WINDOW}, the Leads list's own window — narrowed by
+     * the view's status clause the way the list narrows it: open leads when
+     * the view names no status, one status when it does, everything for
+     * `all`. Held, not merely seen: a lead another site only SHARED with this
+     * one (AGL-3336) is not this site's to take.
+     *
+     * A Contacts view is read the way the dynamic-list sweep reads one, and
+     * each address it selects is resolved to the contact the site may see. A
+     * view filtering on something that reading cannot apply is refused whole:
+     * dropping the filter would select more people than the view shows.
+     */ async peopleInView (request) {
+            var _view_data, _data_ownerUid;
+            const firestore = deps.firestore();
+            const org = firestore.collection('orgs').doc(request.orgId);
+            const view = await org.collection(CRM_COLLECTIONS.views).doc(request.viewId).get();
+            const data = view.exists ? (_view_data = view.data()) != null ? _view_data : {} : null;
+            if (!data || !crmViewIsListed({
+                shared: data['shared'] === true,
+                ownerUid: String((_data_ownerUid = data['ownerUid']) != null ? _data_ownerUid : '')
+            }, request.viewerUid)) {
+                return {
+                    ok: false,
+                    reason: 'not-found'
+                };
+            }
+            const filters = normalizeCrmViewFilters(data['filters']);
+            if (data['section'] === 'leads') {
+                var _ref;
+                const statusClause = filters.find((clause)=>clause.field === 'status' && clause.op === 'equals');
+                const wanted = String((_ref = statusClause == null ? void 0 : statusClause.value) != null ? _ref : 'open');
+                // Narrowed to what the site may see before it is ordered (AGL-3275):
+                // the collection is org-wide, and an agency's sequence must not be
+                // offered another client's people.
+                const window = await org.collection(STORED_IN[CRM_PERSON_KINDS.lead]).where('visibleTo', 'array-contains-any', scopeTokensForHost(request.hostId)).orderBy('lastSeenAtMs', 'desc').limit(CRM_LEADS_VIEW_WINDOW + 1).get();
+                const matching = window.docs.slice(0, CRM_LEADS_VIEW_WINDOW).filter((doc)=>{
+                    var _doc_data;
+                    const lead = (_doc_data = doc.data()) != null ? _doc_data : {};
+                    if (seenOnlyThroughGrant(lead, request.hostId)) return false;
+                    if (wanted === 'all') return true;
+                    if (wanted === 'open') return isCrmLeadOpen(lead) && !lead['convertedContactId'];
+                    return crmLeadStatus(lead) === wanted;
+                });
+                return {
+                    ok: true,
+                    people: matching.slice(0, request.limit).map((doc)=>({
+                            kind: CRM_PERSON_KINDS.lead,
+                            id: doc.id
+                        })),
+                    total: matching.length,
+                    truncated: matching.length > request.limit || window.docs.length > CRM_LEADS_VIEW_WINDOW
+                };
+            }
+            if (data['section'] !== 'contacts') return {
+                ok: false,
+                reason: 'not-people'
+            };
+            const { unsupported } = dynamicListDimensionsForCrmView(filters);
+            if (unsupported.length) {
+                return {
+                    ok: false,
+                    reason: 'unsupported',
+                    unsupported: unsupported.map((clause)=>clause.label || clause.field)
+                };
+            }
+            const { emails, complete } = await deps.contactViewEmails({
+                hostId: request.hostId,
+                viewId: request.viewId
+            });
+            const ordered = [
+                ...new Set(emails)
+            ].sort();
+            const contacts = org.collection(STORED_IN[CRM_PERSON_KINDS.contact]);
+            const found = await Promise.all(ordered.slice(0, request.limit).map((email)=>findContactByEmail(contacts, email, {
+                    hostId: request.hostId
+                })));
+            const ids = [
+                ...new Set(found.filter((snapshot)=>snapshot).map((snapshot)=>String(snapshot == null ? void 0 : snapshot.id)))
+            ];
+            return {
+                ok: true,
+                people: ids.map((id)=>({
+                        kind: CRM_PERSON_KINDS.contact,
+                        id
+                    })),
+                total: ordered.length,
+                truncated: ordered.length > request.limit || !complete
+            };
+        },
+        /**
+     * Whether each person has ever written in: an inbound email on their
+     * timeline, filed on the contact, or on the lead while they were one
+     * (AGL-3234). One keyed query each; a failed one is unknown.
+     */ async wroteIn (request) {
+            const activities = deps.firestore().collection('orgs').doc(request.orgId).collection(CRM_COLLECTIONS.activities);
+            return Promise.all(request.records.map(async (record)=>{
+                var _record_id;
+                const field = record.kind === CRM_PERSON_KINDS.contact ? 'contactId' : record.kind === CRM_PERSON_KINDS.lead ? 'leadId' : null;
+                const id = String((_record_id = record.id) != null ? _record_id : '').trim();
+                if (!field || !id) return null;
+                try {
+                    const snapshot = await activities.where(field, '==', id).where('direction', '==', 'inbound').limit(1).get();
+                    return !snapshot.empty;
+                } catch (error) {
+                    console.error('[crm] inbound email lookup failed; reading as unknown', error);
+                    return null;
+                }
+            }));
+        }
+    };
+}
+/** The service as the CRM registers it, its storage the admin app's. */ export const crmPersonRecords = {
+    find: (request)=>createCrmPersonRecords(defaultCrmPersonRecordsDeps()).find(request),
+    read: (request)=>createCrmPersonRecords(defaultCrmPersonRecordsDeps()).read(request),
+    fileUnder: (request)=>createCrmPersonRecords(defaultCrmPersonRecordsDeps()).fileUnder(request),
+    recordRefund: (request)=>recordPersonRefund(request),
+    peopleInView: (request)=>createCrmPersonRecords(defaultCrmPersonRecordsDeps()).peopleInView(request),
+    wroteIn: (request)=>createCrmPersonRecords(defaultCrmPersonRecordsDeps()).wroteIn(request)
+};
+
+//# sourceMappingURL=person-records.js.map

package/src/lib/server/person-records.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/crm/src/lib/server/person-records.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  containerMembershipField,\n  contactContainerFieldPath,\n  normalizeContainerIds,\n} from '@aglyn/aglyn/app-utils/container-membership'\nimport { normalizeContactEmail } from '@aglyn/aglyn/app-utils/contacts'\nimport {\n  CRM_COLLECTIONS,\n  crmLeadStatus,\n  crmViewIsListed,\n  isCrmLeadOpen,\n  normalizeCrmViewFilters,\n} from '@aglyn/aglyn/app-utils/crm'\nimport { dynamicListDimensionsForCrmView } from '@aglyn/aglyn/app-utils/dynamic-list-rule'\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport {\n  scopeTokensForHost,\n  seenOnlyThroughGrant,\n  visibleToHost,\n} from '@aglyn/aglyn/app-utils/scope-tokens'\nimport type {\n  PluginPersonFileRequest,\n  PluginPersonFindRequest,\n  PluginPersonReadRequest,\n  PluginPersonRecord,\n  PluginPersonRecordRef,\n  PluginPersonRecords,\n  PluginPersonViewPeople,\n  PluginPersonViewRequest,\n  PluginPersonWroteInRequest,\n} from '@aglyn/aglyn/plugin-manager/plugin-person-records'\nimport {\n  consentGroupForSite,\n  firebaseAdmin,\n  resolveOrgIdForHost,\n} from '@aglyn/tenant-data-admin'\n// The leaves, not the barrel: this plugin's specs substitute the barrel\n// wholesale, and the lookup and the restamp must reach the real logic.\nimport { findContactByEmail } from '@aglyn/tenant-data-admin/server/contact-email-index'\nimport { restampCrmListFieldsAt } from '@aglyn/tenant-data-admin/server/crm-records'\nimport { collectDynamicListCandidates } from '@aglyn/tenant-data-admin/server/dynamic-list-materialize'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport { recordPersonRefund } from './person-refund'\n\n/**\n * THE CRM AS THE PLUGIN THAT KEEPS PEOPLE, asked by the plugins that do not\n * (AGL-3080) — the CRM's side of `plugin-person-records`.\n *\n * Two kinds of record are a person here, in the words `plugin-record-routes`\n * addresses them by: a `contact`, the person once they are known, filed at\n * `orgs/{orgId}/contacts/{id}`; and a `lead`, the person before anybody has\n * qualified them, at `orgs/{orgId}/leads/{personKey}` (AGL-3275). One person\n * is one record (AGL-3232), so a lookup by address answers the contact when\n * there is one and the lead only for a caller that asked for any kind.\n *\n * The record's `data` is the stored document. Beside the fields the platform\n * defines (`marketingConsent…`, `emailState`, `visibleTo`), a contact keeps\n * what each consent group knows of the person in `facets.{groupId}` — the\n * sources, stage, owner, company, address and tags — and a lead keeps the\n * same facts at its top level.\n */\n\ntype Firestore = FirebaseFirestore.Firestore\n\n/** The person kinds, as `plugin-record-routes` addresses them. */\nexport const CRM_PERSON_KINDS = { contact: 'contact', lead: 'lead' } as const\n\n/** The collection each person kind is stored in, under the organization. */\nconst STORED_IN: Readonly<Record<string, string>> = {\n  [CRM_PERSON_KINDS.contact]: 'contacts',\n  [CRM_PERSON_KINDS.lead]: 'leads',\n}\n\n/** `getAll` takes this many references per call. */\nconst GET_ALL_CHUNK = 300\n\n/**\n * The most leads a saved Leads view is taken from: the site's most recently\n * seen, the Leads list's own window (AGL-3234).\n */\nexport const CRM_LEADS_VIEW_WINDOW = 200\n\nexport interface CrmPersonRecordsDeps {\n  firestore(): Firestore\n  /** The organization a site belongs to, or `null` for one with none. */\n  orgIdForHost(hostId: string): Promise<string | null>\n  /** The consent group a site files its facet under. */\n  groupIdForHost(hostId: string): Promise<string>\n  /**\n   * The addresses a saved Contacts view selects among one site's contacts,\n   * read the way the dynamic-list sweep reads one, and whether the read\n   * reached the whole view before its budget.\n   */\n  contactViewEmails(input: { hostId: string; viewId: string }): Promise<{ emails: string[]; complete: boolean }>\n}\n\nexport function defaultCrmPersonRecordsDeps(): CrmPersonRecordsDeps {\n  return {\n    firestore: () => firebaseAdmin.app().firestore(),\n    orgIdForHost: async (hostId) => (await resolveOrgIdForHost(hostId)) ?? null,\n    groupIdForHost: async (hostId) => (await consentGroupForSite(hostId)).groupId,\n    contactViewEmails: async ({ hostId, viewId }) => {\n      const scan = await collectDynamicListCandidates({\n        hostId,\n        rule: { sources: ['contacts'], viewId },\n      })\n      return { emails: scan.candidates.map((candidate) => candidate.email), complete: scan.complete }\n    },\n  }\n}\n\nfunction personOf(kind: string, snapshot: FirebaseFirestore.DocumentSnapshot): PluginPersonRecord {\n  const data = (snapshot.data() ?? {}) as Record<string, unknown>\n  return { kind, id: snapshot.id, email: normalizeContactEmail(data['email']), data }\n}\n\n/**\n * The organization a request names, or the one its site belongs to. A site\n * with no organization THROWS, as the org-data lookup every caller used to\n * make threw: each caller has already decided which way a failed read falls.\n */\nasync function orgOf(\n  deps: CrmPersonRecordsDeps,\n  request: { orgId?: string | null; hostId?: string | null },\n): Promise<string> {\n  const named = String(request.orgId ?? '').trim()\n  if (named) return named\n  const hostId = String(request.hostId ?? '').trim()\n  const resolved = hostId ? await deps.orgIdForHost(hostId) : null\n  if (!resolved) throw new Error(`[crm] no organization to find a person in for host ${hostId || '(none)'}`)\n  return resolved\n}\n\nexport function createCrmPersonRecords(deps: CrmPersonRecordsDeps): PluginPersonRecords {\n  return {\n    /**\n     * The contact first, through the org's address index (AGL-2633) so an\n     * address a merge folded into another record still names the person who\n     * now holds it; then, for a caller that asked for any kind, the lead the\n     * address is keyed as. Narrowed to the site when asked, on the document\n     * the address names: a record the site cannot see is `null`.\n     */\n    async find(request: PluginPersonFindRequest) {\n      const email = normalizeContactEmail(request.email)\n      if (!email) return null\n      const orgId = await orgOf(deps, request)\n      const org = deps.firestore().collection('orgs').doc(orgId)\n      const hostId = String(request.hostId ?? '').trim()\n      const narrowTo = request.onlyVisibleToSite && hostId ? hostId : null\n      const contact = await findContactByEmail(\n        org.collection(STORED_IN[CRM_PERSON_KINDS.contact]),\n        email,\n        narrowTo ? { hostId: narrowTo } : {},\n      )\n      if (contact) return personOf(CRM_PERSON_KINDS.contact, contact)\n      if (!request.anyKind) return null\n      const key = personKey(email)\n      if (!key) return null\n      const lead = await org.collection(STORED_IN[CRM_PERSON_KINDS.lead]).doc(key).get()\n      if (!lead.exists) return null\n      if (narrowTo && !visibleToHost(lead.get('visibleTo') as string[] | undefined, narrowTo)) {\n        return null\n      }\n      return personOf(CRM_PERSON_KINDS.lead, lead)\n    },\n\n    /** Every record named, read at once; a kind the CRM does not keep is `null`. */\n    async read(request: PluginPersonReadRequest) {\n      const firestore = deps.firestore()\n      const org = firestore.collection('orgs').doc(request.orgId)\n      const refs = request.records.map((record) => {\n        const collection = STORED_IN[record.kind]\n        const id = String(record.id ?? '').trim()\n        return collection && id ? org.collection(collection).doc(id) : null\n      })\n      const wanted = refs.filter((ref): ref is FirebaseFirestore.DocumentReference => ref !== null)\n      const snapshots: FirebaseFirestore.DocumentSnapshot[] = []\n      for (let start = 0; start < wanted.length; start += GET_ALL_CHUNK) {\n        snapshots.push(...(await firestore.getAll(...wanted.slice(start, start + GET_ALL_CHUNK))))\n      }\n      let at = 0\n      return request.records.map((record, index) => {\n        if (!refs[index]) return null\n        const snapshot = snapshots[at++]\n        return snapshot?.exists ? personOf(record.kind, snapshot) : null\n      })\n    },\n\n    /**\n     * Files the person under the containers as the site holds them: on a\n     * contact, inside the site's consent-group facet — which campaigns a\n     * merchant filed somebody under is that merchant's record, and written at\n     * the top it would be readable by every site of an agency's account; on a\n     * lead, in the lead's own membership field, whose list fields are then\n     * restamped so the Leads list's filter finds it (AGL-3321).\n     *\n     * `update`, never a merge-set: a dotted path in `set` is a literal field\n     * name, and the record must exist. A record the site cannot see is not\n     * filed.\n     */\n    async fileUnder(request: PluginPersonFileRequest) {\n      const ids = normalizeContainerIds(request.ids)\n      const collection = STORED_IN[request.record.kind]\n      const id = String(request.record.id ?? '').trim()\n      if (!ids.length || !collection || !id) return { filed: false }\n      const orgId = await orgOf(deps, request)\n      const ref = deps.firestore().collection('orgs').doc(orgId).collection(collection).doc(id)\n      const snapshot = await ref.get()\n      if (!snapshot.exists) return { filed: false }\n      if (!visibleToHost(snapshot.get('visibleTo') as string[] | undefined, request.hostId)) {\n        return { filed: false }\n      }\n      if (request.record.kind === CRM_PERSON_KINDS.lead) {\n        await ref.update({\n          [containerMembershipField(request.containerKind)]: FieldValue.arrayUnion(...ids),\n          updatedAt: FieldValue.serverTimestamp(),\n        })\n        await restampCrmListFieldsAt(ref, 'leads')\n        return { filed: true }\n      }\n      const groupId = await deps.groupIdForHost(request.hostId)\n      await ref.update({\n        [contactContainerFieldPath(groupId, request.containerKind)]: FieldValue.arrayUnion(...ids),\n        updatedAt: FieldValue.serverTimestamp(),\n      })\n      return { filed: true }\n    },\n\n    recordRefund: (request) => recordPersonRefund(request),\n\n    /**\n     * The people a saved view selects for a site (AGL-3234). A colleague's\n     * private view is theirs: not listed for this member, so it does not\n     * exist for them here either.\n     *\n     * A Leads view takes the site's most recently seen leads —\n     * {@link CRM_LEADS_VIEW_WINDOW}, the Leads list's own window — narrowed by\n     * the view's status clause the way the list narrows it: open leads when\n     * the view names no status, one status when it does, everything for\n     * `all`. Held, not merely seen: a lead another site only SHARED with this\n     * one (AGL-3336) is not this site's to take.\n     *\n     * A Contacts view is read the way the dynamic-list sweep reads one, and\n     * each address it selects is resolved to the contact the site may see. A\n     * view filtering on something that reading cannot apply is refused whole:\n     * dropping the filter would select more people than the view shows.\n     */\n    async peopleInView(request: PluginPersonViewRequest): Promise<PluginPersonViewPeople> {\n      const firestore = deps.firestore()\n      const org = firestore.collection('orgs').doc(request.orgId)\n      const view = await org.collection(CRM_COLLECTIONS.views).doc(request.viewId).get()\n      const data = view.exists ? ((view.data() ?? {}) as Record<string, unknown>) : null\n      if (\n        !data ||\n        !crmViewIsListed(\n          { shared: data['shared'] === true, ownerUid: String(data['ownerUid'] ?? '') },\n          request.viewerUid,\n        )\n      ) {\n        return { ok: false, reason: 'not-found' }\n      }\n      const filters = normalizeCrmViewFilters(data['filters'])\n      if (data['section'] === 'leads') {\n        const statusClause = filters.find((clause) => clause.field === 'status' && clause.op === 'equals')\n        const wanted = String(statusClause?.value ?? 'open')\n        // Narrowed to what the site may see before it is ordered (AGL-3275):\n        // the collection is org-wide, and an agency's sequence must not be\n        // offered another client's people.\n        const window = await org\n          .collection(STORED_IN[CRM_PERSON_KINDS.lead])\n          .where('visibleTo', 'array-contains-any', scopeTokensForHost(request.hostId))\n          .orderBy('lastSeenAtMs', 'desc')\n          .limit(CRM_LEADS_VIEW_WINDOW + 1)\n          .get()\n        const matching = window.docs.slice(0, CRM_LEADS_VIEW_WINDOW).filter((doc) => {\n          const lead = (doc.data() ?? {}) as Record<string, unknown>\n          if (seenOnlyThroughGrant(lead, request.hostId)) return false\n          if (wanted === 'all') return true\n          if (wanted === 'open') return isCrmLeadOpen(lead as never) && !lead['convertedContactId']\n          return crmLeadStatus(lead as never) === wanted\n        })\n        return {\n          ok: true,\n          people: matching.slice(0, request.limit).map((doc) => ({ kind: CRM_PERSON_KINDS.lead, id: doc.id })),\n          total: matching.length,\n          truncated: matching.length > request.limit || window.docs.length > CRM_LEADS_VIEW_WINDOW,\n        }\n      }\n      if (data['section'] !== 'contacts') return { ok: false, reason: 'not-people' }\n      const { unsupported } = dynamicListDimensionsForCrmView(filters)\n      if (unsupported.length) {\n        return {\n          ok: false,\n          reason: 'unsupported',\n          unsupported: unsupported.map((clause) => clause.label || clause.field),\n        }\n      }\n      const { emails, complete } = await deps.contactViewEmails({\n        hostId: request.hostId,\n        viewId: request.viewId,\n      })\n      const ordered = [...new Set(emails)].sort()\n      const contacts = org.collection(STORED_IN[CRM_PERSON_KINDS.contact])\n      const found = await Promise.all(\n        ordered\n          .slice(0, request.limit)\n          .map((email) => findContactByEmail(contacts, email, { hostId: request.hostId })),\n      )\n      const ids = [...new Set(found.filter((snapshot) => snapshot).map((snapshot) => String(snapshot?.id)))]\n      return {\n        ok: true,\n        people: ids.map((id): PluginPersonRecordRef => ({ kind: CRM_PERSON_KINDS.contact, id })),\n        total: ordered.length,\n        truncated: ordered.length > request.limit || !complete,\n      }\n    },\n\n    /**\n     * Whether each person has ever written in: an inbound email on their\n     * timeline, filed on the contact, or on the lead while they were one\n     * (AGL-3234). One keyed query each; a failed one is unknown.\n     */\n    async wroteIn(request: PluginPersonWroteInRequest) {\n      const activities = deps\n        .firestore()\n        .collection('orgs')\n        .doc(request.orgId)\n        .collection(CRM_COLLECTIONS.activities)\n      return Promise.all(\n        request.records.map(async (record) => {\n          const field =\n            record.kind === CRM_PERSON_KINDS.contact\n              ? 'contactId'\n              : record.kind === CRM_PERSON_KINDS.lead\n                ? 'leadId'\n                : null\n          const id = String(record.id ?? '').trim()\n          if (!field || !id) return null\n          try {\n            const snapshot = await activities\n              .where(field, '==', id)\n              .where('direction', '==', 'inbound')\n              .limit(1)\n              .get()\n            return !snapshot.empty\n          } catch (error) {\n            console.error('[crm] inbound email lookup failed; reading as unknown', error)\n            return null\n          }\n        }),\n      )\n    },\n  }\n}\n\n/** The service as the CRM registers it, its storage the admin app's. */\nexport const crmPersonRecords: Required<PluginPersonRecords> = {\n  find: (request) => createCrmPersonRecords(defaultCrmPersonRecordsDeps()).find(request),\n  read: (request) => createCrmPersonRecords(defaultCrmPersonRecordsDeps()).read(request),\n  fileUnder: (request) => createCrmPersonRecords(defaultCrmPersonRecordsDeps()).fileUnder!(request),\n  recordRefund: (request) => recordPersonRefund(request),\n  peopleInView: (request) => createCrmPersonRecords(defaultCrmPersonRecordsDeps()).peopleInView!(request),\n  wroteIn: (request) => createCrmPersonRecords(defaultCrmPersonRecordsDeps()).wroteIn!(request),\n}\n"],"names":["containerMembershipField","contactContainerFieldPath","normalizeContainerIds","normalizeContactEmail","CRM_COLLECTIONS","crmLeadStatus","crmViewIsListed","isCrmLeadOpen","normalizeCrmViewFilters","dynamicListDimensionsForCrmView","personKey","scopeTokensForHost","seenOnlyThroughGrant","visibleToHost","consentGroupForSite","firebaseAdmin","resolveOrgIdForHost","findContactByEmail","restampCrmListFieldsAt","collectDynamicListCandidates","FieldValue","recordPersonRefund","CRM_PERSON_KINDS","contact","lead","STORED_IN","GET_ALL_CHUNK","CRM_LEADS_VIEW_WINDOW","defaultCrmPersonRecordsDeps","firestore","app","orgIdForHost","hostId","groupIdForHost","groupId","contactViewEmails","viewId","scan","rule","sources","emails","candidates","map","candidate","email","complete","personOf","kind","snapshot","data","id","orgOf","deps","request","named","String","orgId","trim","resolved","Error","createCrmPersonRecords","find","org","collection","doc","narrowTo","onlyVisibleToSite","anyKind","key","get","exists","read","refs","records","record","wanted","filter","ref","snapshots","start","length","push","getAll","slice","at","index","fileUnder","ids","filed","update","containerKind","arrayUnion","updatedAt","serverTimestamp","recordRefund","peopleInView","view","views","shared","ownerUid","viewerUid","ok","reason","filters","statusClause","clause","field","op","value","window","where","orderBy","limit","matching","docs","people","total","truncated","unsupported","label","ordered","Set","sort","contacts","found","Promise","all","wroteIn","activities","empty","error","console","crmPersonRecords"],"mappings":"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"}

package/src/lib/server/person-refund.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @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 { PluginPersonRefundOutcome, PluginPersonRefundRequest } from '@aglyn/aglyn/plugin-manager/plugin-person-records';
+/**
+ * Money going BACK to a customer, recorded on their contact (AGL-1754).
+ *
+ * The CRM's answer to `plugin-person-records`' `recordRefund` (AGL-3080):
+ * commerce reports a refund or a lost dispute through the seam, and what it
+ * does to the person is decided here, by the plugin that keeps them. It used
+ * to be commerce's own module, writing these fields onto the CRM's contacts.
+ *
+ * `upsertHostContact` accumulates `ltvCents` and nothing anywhere decremented
+ * it, so a customer who bought $500 and returned all of it read identically to
+ * one who bought $500 and kept it — and the first surface built on the field
+ * (RFM segmentation, a lifetime-value column, a best-customers list) would have
+ * ranked a serial returner among the merchant's best customers.
+ *
+ * WHAT THIS WRITES, AND WHY IT IS NOT A DECREMENT
+ *
+ * `ltvCents` is left exactly as it is and the reversal is recorded BESIDE it:
+ *
+ * | field | meaning |
+ * | -- | -- |
+ * | `ltvCents` | gross money handed over, unchanged (AGL-1748) |
+ * | `refundedCents` | gross money handed back |
+ * | `ordersCount` | orders placed, unchanged |
+ * | `refundedOrdersCount` | of those, how many ended fully reversed |
+ * | `lastRefundAtMs` | when money last went back |
+ *
+ * This is the shape AGL-1747 chose two days earlier for the same question on
+ * the orders CSV — `amountUsd` stayed gross under its existing name and
+ * `refundedUsd`/`netUsd` were appended — and it is the shape AGL-1748 named
+ * when it recorded the gross semantics in `upsert-contact.ts`. Netting in
+ * place would make a stored number mean one thing for rows written before this
+ * commit and another for rows written after, with nothing on the document to
+ * tell the two apart. Two fields cost one number's worth of storage and keep
+ * both facts, and a reader that wants the net has `ltvCents - refundedCents`.
+ *
+ * It also answers "can it go negative?" by moving the question off storage.
+ * Both figures are monotonic counters of money that actually moved in one
+ * direction, so neither can go negative. The DERIVED net can, for exactly one
+ * reason: an order placed before AGL-1748 taught POS, drafts, reservations and
+ * bookings to pass `purchaseCents` at all, whose sale was never added and whose
+ * refund is subtracted here. That is a true statement about the data, and
+ * clamping it away at write time would erase the only evidence that a purchase
+ * is missing. AGL-1753 is the backfill that reconciles it, by SETTING both
+ * fields from the orders — which already carry `refundedCents`, so whatever a
+ * reader decides here costs the rebuild nothing. A merchant-facing reader
+ * should show gross and refunded, and clamp only the net it ranks on.
+ *
+ * `ordersCount` is deliberately NOT decremented. A fully refunded order still
+ * happened, and a decrement cannot be undone by a reader that would rather
+ * count it — while `refundedOrdersCount` beside it lets RFM's frequency term
+ * net the two, or not, at the point of display. Same argument as the amount,
+ * one field along.
+ *
+ * WHEN THE CONTACT IS MISSING, THIS REFUSES — and records the refusal.
+ *
+ * Refusing is right on AGL-1732's test, "does refusing discard money or work
+ * that already happened?", because it does not: the refund is durable on the
+ * order (`refundedCents`, the timeline entry, Stripe), and the contact is a
+ * derived aggregate that AGL-1753's rebuild reads back out of those same
+ * orders. Creating one here would be worse three ways — creation is audience
+ * BAND gated, so it hard-bands a Free org (raising the AGL-891 dropped-contacts
+ * alert for a record the merchant never had) or meters onto a paid invoice; the
+ * contact it created would hold a refund and no purchase, which is the negative
+ * lifetime value above with nothing to reconcile it against; and it is the
+ * phantom-document shape the `updateExisting` sweep spent yesterday closing.
+ *
+ * So the write is an `update()`, never `set(…, { merge: true })` — the contact
+ * may have been deleted between the query and the write, and a merge-set would
+ * resurrect it as a document holding nothing but a refund. Every refusal
+ * increments `hosts/{hostId}/counters/contactRefundsUnmatched`, the counter
+ * shape `contactsDropped` already uses, so a refund that reached no contact is
+ * countable rather than silent.
+ *
+ * CHARGEBACKS (AGL-1554) are a separate decision and are NOT handled here.
+ * This takes `kind` so the handler that eventually answers
+ * `charge.dispute.closed` can record a lost dispute through the same writer
+ * with the same fields: money reversed is money reversed, whichever door it
+ * left by, and only the wording of the timeline entry differs.
+ */
+export declare function recordPersonRefund(request: PluginPersonRefundRequest): Promise<PluginPersonRefundOutcome>;