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

package/src/lib/server/contact-email-engagement.js

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * THE CONTACT'S OWN ENGAGEMENT STAMP (AGL-2616):
+ * `facets.{groupId}.lastEmailEngagementAtMs` on `orgs/{orgId}/contacts`.
+ *
+ * ## What it answers
+ *
+ * "When did this person last read one of OUR campaigns?" — on the record
+ * page as "Last engaged", as a column on the list, and as the audience rule
+ * `engagedWithinDays`. The per-person rollup on `emailDeliveries/{key}`
+ * already answers "when did this address last read anything from anybody",
+ * which is the right question for a sunset that refuses to mail cold
+ * addresses and the wrong one for a re-engagement audience: it moves when
+ * the person opens a receipt, an invite, or a sibling business's newsletter
+ * on the same shared row. This stamp moves only when they open or click a
+ * campaign this holder's own sites sent.
+ *
+ * ## What one webhook event costs
+ *
+ * The same bound the rollup keeps: only an event that is the FIRST of its
+ * type for its message reaches here, which `recordEmailDeliveryEvent`'s
+ * transaction already decided. A reader opening one newsletter six times is
+ * one transaction, and a replayed event finds its type already recorded and
+ * contributes nothing. Inside that bound the cost per person is one org
+ * resolution and one group resolution per batch, then one keyed query and
+ * at most one update per person.
+ *
+ * ## Forward-only, in a transaction
+ *
+ * Provider events are unordered and at-least-once, so an old instant
+ * arriving late must not overwrite a fresh stamp — the same reasoning
+ * `recordPersonEngagement` gives. The query for the contact rides inside
+ * the transaction so the compare-and-write is atomic against a second event
+ * for the same person landing in another instance.
+ *
+ * ## Only a contact this site may see, and only this holder's facet
+ *
+ * The contact row is shared by every site in the org. The stamp is written
+ * under the sending site's consent group, never at the top of the document,
+ * and only onto a row whose `visibleTo` admits the site — a person another
+ * holder captured and this site never met is not this site's contact, and a
+ * write onto their row would mint a facet for a holder that does not hold
+ * them. `updatedAt` is left alone: an open is something the person did, not
+ * an edit the team made, and a list sorted on recency must not reshuffle on
+ * every mailbox prefetch.
+ *
+ * ## Never throws
+ *
+ * Best-effort for the reason everything on the webhook path is: a stamp that
+ * failed loses a fact a page can live without, and a stamp that threw would
+ * lose the provider's acknowledgement and teach it to retry the whole event.
+ */ import { contactFacetPath, normalizeContactEmail, readContactFacet, visibleToHost } from "@aglyn/aglyn/server";
+import { findContactByEmail } from "./contact-email-index.js";
+import { firebaseAdmin } from "./firebase-admin.js";
+import { consentGroupForSite, orgDataCollectionForHost } from "./organizations.js";
+/** The facet field the stamp lives under. */ export const CONTACT_EMAIL_ENGAGEMENT_FIELD = 'lastEmailEngagementAtMs';
+/** The event types that count as a person engaging with a campaign. */ const ENGAGEMENT_TYPES = new Set([
+    'opened',
+    'clicked'
+]);
+/**
+ * Stamps the sending site's contact facet for every person these outcomes
+ * say engaged for the first time with a message.
+ *
+ * @param hostId the site the campaign went out from — the `hostId` tag the
+ *   send stamped, which is the only tenant identity a delivery event carries.
+ * @returns how many contact documents were written.
+ */ export async function recordContactEmailEngagement(args) {
+    var _args_hostId, _args_firestore;
+    const hostId = String((_args_hostId = args.hostId) != null ? _args_hostId : '');
+    if (!hostId) return 0;
+    /** Address → the newest engagement instant in this batch. */ const byEmail = new Map();
+    for (const outcome of args.outcomes){
+        var _byEmail_get;
+        if (!outcome.firstOfType) continue;
+        if (!ENGAGEMENT_TYPES.has(outcome.type)) continue;
+        const email = normalizeContactEmail(outcome.to);
+        const at = Number(outcome.at);
+        if (!email || !Number.isFinite(at) || at <= 0) continue;
+        byEmail.set(email, Math.max((_byEmail_get = byEmail.get(email)) != null ? _byEmail_get : 0, at));
+    }
+    if (!byEmail.size) return 0;
+    let contactsRef;
+    let groupId;
+    try {
+        contactsRef = await orgDataCollectionForHost(hostId, 'contacts');
+        groupId = (await consentGroupForSite(hostId)).groupId;
+    } catch (error) {
+        console.error('[contact-email-engagement] site could not be resolved', hostId, error);
+        return 0;
+    }
+    const db = (_args_firestore = args.firestore) != null ? _args_firestore : firebaseAdmin.app().firestore();
+    const field = contactFacetPath(groupId, CONTACT_EMAIL_ENGAGEMENT_FIELD);
+    let written = 0;
+    for (const [email, at] of byEmail){
+        try {
+            await db.runTransaction(async (transaction)=>{
+                var _snapshot_data, _readContactFacet_CONTACT_EMAIL_ENGAGEMENT_FIELD;
+                /*
+         * The same unscoped lookup the capture door makes — one human is one
+         * row whichever site met them, and through the address index
+         * (AGL-2633) the row is found under an address a merge folded into
+         * it too — followed by the scope check the capture door's
+         * `visibleTo` write is the source of. Read THROUGH the transaction:
+         * the stamp below is a compare-and-set against the instant this
+         * read saw.
+         */ const snapshot = await findContactByEmail(contactsRef, email, {
+                    transaction
+                });
+                if (!snapshot) return;
+                const data = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+                if (!visibleToHost(data['visibleTo'], hostId)) {
+                    return;
+                }
+                const stored = Number((_readContactFacet_CONTACT_EMAIL_ENGAGEMENT_FIELD = readContactFacet(data, groupId)[CONTACT_EMAIL_ENGAGEMENT_FIELD]) != null ? _readContactFacet_CONTACT_EMAIL_ENGAGEMENT_FIELD : 0);
+                // Nothing moved forward, so nothing is written — the out-of-order
+                // and the replayed event are the ordinary cases this skips.
+                if (Number.isFinite(stored) && stored >= at) return;
+                transaction.update(snapshot.ref, {
+                    [field]: at
+                });
+                written += 1;
+            });
+        } catch (error) {
+            console.error('[contact-email-engagement] stamp failed', hostId, error);
+        }
+    }
+    return written;
+}
+
+//# sourceMappingURL=contact-email-engagement.js.map

package/src/lib/server/contact-email-engagement.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/contact-email-engagement.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\n/**\n * THE CONTACT'S OWN ENGAGEMENT STAMP (AGL-2616):\n * `facets.{groupId}.lastEmailEngagementAtMs` on `orgs/{orgId}/contacts`.\n *\n * ## What it answers\n *\n * \"When did this person last read one of OUR campaigns?\" — on the record\n * page as \"Last engaged\", as a column on the list, and as the audience rule\n * `engagedWithinDays`. The per-person rollup on `emailDeliveries/{key}`\n * already answers \"when did this address last read anything from anybody\",\n * which is the right question for a sunset that refuses to mail cold\n * addresses and the wrong one for a re-engagement audience: it moves when\n * the person opens a receipt, an invite, or a sibling business's newsletter\n * on the same shared row. This stamp moves only when they open or click a\n * campaign this holder's own sites sent.\n *\n * ## What one webhook event costs\n *\n * The same bound the rollup keeps: only an event that is the FIRST of its\n * type for its message reaches here, which `recordEmailDeliveryEvent`'s\n * transaction already decided. A reader opening one newsletter six times is\n * one transaction, and a replayed event finds its type already recorded and\n * contributes nothing. Inside that bound the cost per person is one org\n * resolution and one group resolution per batch, then one keyed query and\n * at most one update per person.\n *\n * ## Forward-only, in a transaction\n *\n * Provider events are unordered and at-least-once, so an old instant\n * arriving late must not overwrite a fresh stamp — the same reasoning\n * `recordPersonEngagement` gives. The query for the contact rides inside\n * the transaction so the compare-and-write is atomic against a second event\n * for the same person landing in another instance.\n *\n * ## Only a contact this site may see, and only this holder's facet\n *\n * The contact row is shared by every site in the org. The stamp is written\n * under the sending site's consent group, never at the top of the document,\n * and only onto a row whose `visibleTo` admits the site — a person another\n * holder captured and this site never met is not this site's contact, and a\n * write onto their row would mint a facet for a holder that does not hold\n * them. `updatedAt` is left alone: an open is something the person did, not\n * an edit the team made, and a list sorted on recency must not reshuffle on\n * every mailbox prefetch.\n *\n * ## Never throws\n *\n * Best-effort for the reason everything on the webhook path is: a stamp that\n * failed loses a fact a page can live without, and a stamp that threw would\n * lose the provider's acknowledgement and teach it to retry the whole event.\n */\n\nimport {\n  contactFacetPath,\n  normalizeContactEmail,\n  readContactFacet,\n  visibleToHost,\n} from '@aglyn/aglyn/server'\nimport { findContactByEmail } from './contact-email-index'\nimport type { EmailDeliveryEventOutcome } from './email-delivery-log'\nimport { firebaseAdmin } from './firebase-admin'\nimport { consentGroupForSite, orgDataCollectionForHost } from './organizations'\n\n/** The facet field the stamp lives under. */\nexport const CONTACT_EMAIL_ENGAGEMENT_FIELD = 'lastEmailEngagementAtMs'\n\n/** The event types that count as a person engaging with a campaign. */\nconst ENGAGEMENT_TYPES: ReadonlySet<EmailDeliveryEventOutcome['type']> = new Set([\n  'opened',\n  'clicked',\n])\n\n/**\n * Stamps the sending site's contact facet for every person these outcomes\n * say engaged for the first time with a message.\n *\n * @param hostId the site the campaign went out from — the `hostId` tag the\n *   send stamped, which is the only tenant identity a delivery event carries.\n * @returns how many contact documents were written.\n */\nexport async function recordContactEmailEngagement(args: {\n  hostId: string\n  outcomes: readonly EmailDeliveryEventOutcome[]\n  firestore?: any\n}): Promise<number> {\n  const hostId = String(args.hostId ?? '')\n  if (!hostId) return 0\n\n  /** Address → the newest engagement instant in this batch. */\n  const byEmail = new Map<string, number>()\n  for (const outcome of args.outcomes) {\n    if (!outcome.firstOfType) continue\n    if (!ENGAGEMENT_TYPES.has(outcome.type)) continue\n    const email = normalizeContactEmail(outcome.to)\n    const at = Number(outcome.at)\n    if (!email || !Number.isFinite(at) || at <= 0) continue\n    byEmail.set(email, Math.max(byEmail.get(email) ?? 0, at))\n  }\n  if (!byEmail.size) return 0\n\n  let contactsRef: FirebaseFirestore.CollectionReference\n  let groupId: string\n  try {\n    contactsRef = await orgDataCollectionForHost(hostId, 'contacts')\n    groupId = (await consentGroupForSite(hostId)).groupId\n  } catch (error) {\n    console.error('[contact-email-engagement] site could not be resolved', hostId, error)\n    return 0\n  }\n\n  const db = args.firestore ?? firebaseAdmin.app().firestore()\n  const field = contactFacetPath(groupId, CONTACT_EMAIL_ENGAGEMENT_FIELD)\n  let written = 0\n  for (const [email, at] of byEmail) {\n    try {\n      await db.runTransaction(async (transaction: any) => {\n        /*\n         * The same unscoped lookup the capture door makes — one human is one\n         * row whichever site met them, and through the address index\n         * (AGL-2633) the row is found under an address a merge folded into\n         * it too — followed by the scope check the capture door's\n         * `visibleTo` write is the source of. Read THROUGH the transaction:\n         * the stamp below is a compare-and-set against the instant this\n         * read saw.\n         */\n        const snapshot = await findContactByEmail(contactsRef, email, { transaction })\n        if (!snapshot) return\n        const data = (snapshot.data() ?? {}) as Record<string, unknown>\n        if (!visibleToHost(data['visibleTo'] as string[] | undefined, hostId)) {\n          return\n        }\n        const stored = Number(\n          readContactFacet(data, groupId)[CONTACT_EMAIL_ENGAGEMENT_FIELD] ?? 0,\n        )\n        // Nothing moved forward, so nothing is written — the out-of-order\n        // and the replayed event are the ordinary cases this skips.\n        if (Number.isFinite(stored) && stored >= at) return\n        transaction.update(snapshot.ref, { [field]: at })\n        written += 1\n      })\n    } catch (error) {\n      console.error('[contact-email-engagement] stamp failed', hostId, error)\n    }\n  }\n  return written\n}\n"],"names":["contactFacetPath","normalizeContactEmail","readContactFacet","visibleToHost","findContactByEmail","firebaseAdmin","consentGroupForSite","orgDataCollectionForHost","CONTACT_EMAIL_ENGAGEMENT_FIELD","ENGAGEMENT_TYPES","Set","recordContactEmailEngagement","args","hostId","String","byEmail","Map","outcome","outcomes","firstOfType","has","type","email","to","at","Number","isFinite","set","Math","max","get","size","contactsRef","groupId","error","console","db","firestore","app","field","written","runTransaction","transaction","snapshot","data","stored","update","ref"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDC,GAED,SACEA,gBAAgB,EAChBC,qBAAqB,EACrBC,gBAAgB,EAChBC,aAAa,QACR,sBAAqB;AAC5B,SAASC,kBAAkB,QAAQ,2BAAuB;AAE1D,SAASC,aAAa,QAAQ,sBAAkB;AAChD,SAASC,mBAAmB,EAAEC,wBAAwB,QAAQ,qBAAiB;AAE/E,2CAA2C,GAC3C,OAAO,MAAMC,iCAAiC,0BAAyB;AAEvE,qEAAqE,GACrE,MAAMC,mBAAmE,IAAIC,IAAI;IAC/E;IACA;CACD;AAED;;;;;;;CAOC,GACD,OAAO,eAAeC,6BAA6BC,IAIlD;QACuBA,cAyBXA;IAzBX,MAAMC,SAASC,QAAOF,eAAAA,KAAKC,MAAM,YAAXD,eAAe;IACrC,IAAI,CAACC,QAAQ,OAAO;IAEpB,2DAA2D,GAC3D,MAAME,UAAU,IAAIC;IACpB,KAAK,MAAMC,WAAWL,KAAKM,QAAQ,CAAE;YAMPH;QAL5B,IAAI,CAACE,QAAQE,WAAW,EAAE;QAC1B,IAAI,CAACV,iBAAiBW,GAAG,CAACH,QAAQI,IAAI,GAAG;QACzC,MAAMC,QAAQrB,sBAAsBgB,QAAQM,EAAE;QAC9C,MAAMC,KAAKC,OAAOR,QAAQO,EAAE;QAC5B,IAAI,CAACF,SAAS,CAACG,OAAOC,QAAQ,CAACF,OAAOA,MAAM,GAAG;QAC/CT,QAAQY,GAAG,CAACL,OAAOM,KAAKC,GAAG,EAACd,eAAAA,QAAQe,GAAG,CAACR,kBAAZP,eAAsB,GAAGS;IACvD;IACA,IAAI,CAACT,QAAQgB,IAAI,EAAE,OAAO;IAE1B,IAAIC;IACJ,IAAIC;IACJ,IAAI;QACFD,cAAc,MAAMzB,yBAAyBM,QAAQ;QACrDoB,UAAU,AAAC,CAAA,MAAM3B,oBAAoBO,OAAM,EAAGoB,OAAO;IACvD,EAAE,OAAOC,OAAO;QACdC,QAAQD,KAAK,CAAC,yDAAyDrB,QAAQqB;QAC/E,OAAO;IACT;IAEA,MAAME,MAAKxB,kBAAAA,KAAKyB,SAAS,YAAdzB,kBAAkBP,cAAciC,GAAG,GAAGD,SAAS;IAC1D,MAAME,QAAQvC,iBAAiBiC,SAASzB;IACxC,IAAIgC,UAAU;IACd,KAAK,MAAM,CAAClB,OAAOE,GAAG,IAAIT,QAAS;QACjC,IAAI;YACF,MAAMqB,GAAGK,cAAc,CAAC,OAAOC;oBAYfC,gBAKZzC;gBAhBF;;;;;;;;SAQC,GACD,MAAMyC,WAAW,MAAMvC,mBAAmB4B,aAAaV,OAAO;oBAAEoB;gBAAY;gBAC5E,IAAI,CAACC,UAAU;gBACf,MAAMC,QAAQD,iBAAAA,SAASC,IAAI,cAAbD,iBAAmB,CAAC;gBAClC,IAAI,CAACxC,cAAcyC,IAAI,CAAC,YAAY,EAA0B/B,SAAS;oBACrE;gBACF;gBACA,MAAMgC,SAASpB,QACbvB,mDAAAA,iBAAiB0C,MAAMX,QAAQ,CAACzB,+BAA+B,YAA/DN,mDAAmE;gBAErE,kEAAkE;gBAClE,4DAA4D;gBAC5D,IAAIuB,OAAOC,QAAQ,CAACmB,WAAWA,UAAUrB,IAAI;gBAC7CkB,YAAYI,MAAM,CAACH,SAASI,GAAG,EAAE;oBAAE,CAACR,MAAM,EAAEf;gBAAG;gBAC/CgB,WAAW;YACb;QACF,EAAE,OAAON,OAAO;YACdC,QAAQD,KAAK,CAAC,2CAA2CrB,QAAQqB;QACnE;IACF;IACA,OAAOM;AACT"}

package/src/lib/server/contact-email-index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @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.
+ */
+/** One entry: the address as stored, and the contact it resolves to. */
+export interface ContactEmailIndexEntry {
+    email: string;
+    contactId: string;
+}
+/**
+ * The org's index collection, beside its contacts one — or `null` when the
+ * handle has no parent, which is a fixture's contacts reference and never
+ * a real org subcollection. `null` means "no index": the caller falls back
+ * to the query and writes nothing.
+ */
+export declare function emailIndexBeside(contactsRef: FirebaseFirestore.CollectionReference): FirebaseFirestore.CollectionReference | null;
+/**
+ * Point every address in `emails` at `contactId`. Never rejects: an entry
+ * that could not be written is one the next lookup writes again.
+ */
+export declare function writeContactEmailIndex(index: FirebaseFirestore.CollectionReference | null, contactId: string, emails: readonly string[]): Promise<void>;
+/** How one door reads differently from the capture; see the module notes. */
+export interface FindContactByEmailOptions {
+    /**
+     * Answer only a contact THIS site may see. A document the address names
+     * but the site cannot read is `null` — the same answer the scoped
+     * `email ==` query gave, since one address names one document.
+     */
+    hostId?: string;
+    /**
+     * Read through this transaction. Every read — the index entry, the
+     * contact it names, the fallback query — goes through it; the lazy index
+     * write does not, so the caller may still read after this returns.
+     */
+    transaction?: FirebaseFirestore.Transaction;
+}
+/**
+ * The contact an address belongs to, as a document snapshot — or `null`.
+ *
+ * The index first, then the per-document query it summarizes. A query hit
+ * writes the entry the index lacked, so the read that paid for the miss is
+ * the last one that has to.
+ */
+export declare function findContactByEmail(contactsRef: FirebaseFirestore.CollectionReference, email: unknown, options?: FindContactByEmailOptions): Promise<FirebaseFirestore.DocumentSnapshot | null>;

package/src/lib/server/contact-email-index.js

@@ -0,0 +1,158 @@
+/**
+ * @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.
+ */ /**
+ * THE ADDRESS INDEX (AGL-2625): `orgs/{orgId}/emailIndex/{personKey}`.
+ *
+ * `upsertHostContact` finds a person by `where('email', '==', …)` on the
+ * contacts collection, and that query answers one document per address by
+ * construction — which is exactly what stops a merged record's address from
+ * ever finding the survivor. The survivor's `email` is the identity that
+ * stayed; the merged address is in its `alternateEmails`, and Firestore
+ * cannot answer "the document whose primary OR alternate address is X" as
+ * one indexed query. So the address is indexed on its own: one document per
+ * address, naming the contact it belongs to.
+ *
+ * ## Consulted first, never trusted alone
+ *
+ * The lookup reads the index entry and then the contact it names, and
+ * takes the contact only if it still exists. A stale entry — a contact
+ * detached and deleted after its entry was written — falls through to the
+ * query, which is the truth the index only summarizes.
+ *
+ * ## Written lazily, never backfilled
+ *
+ * An entry is written when a capture CREATES a contact, and when a lookup
+ * finds one through the query rather than the index — so every existing
+ * contact gains an entry on its next write, and no job has to walk the
+ * collection. A merge writes one entry per address the survivor answers to.
+ *
+ * ## Never in the way of a capture
+ *
+ * Every read and write here is wrapped: a form submission or an order must
+ * succeed whatever the index did, exactly as the capture itself swallows
+ * its own failures. An index that cannot be reached is a miss, and a miss
+ * is the query.
+ *
+ * ## One lookup for every door (AGL-2633)
+ *
+ * The capture door was the first reader; every other place that finds a
+ * person by address — an automation step, the flow-email consent gate, the
+ * delivery webhook's engagement stamp, the Inbox add-to-list check, a
+ * refund, a campaign's proof and consent reads, the REST create and
+ * `?email=` list — resolves through this same function, so a merged
+ * record's alternate address answers the same person everywhere. Two of
+ * those doors read differently from the capture, and the options carry it:
+ *
+ * - **`hostId`** narrows the answer to what ONE site may see. The index is
+ *   org-wide, so the lookup is too; the scope check is applied to the
+ *   document it names, in memory, which answers exactly what the scoped
+ *   `email ==` query used to — one document per address, so a contact the
+ *   site cannot see is `null` rather than a reason to look further.
+ * - **`transaction`** routes every read through the caller's transaction,
+ *   for a door that updates the contact it finds inside one. The lazy index
+ *   write stays OUTSIDE the transaction, deliberately: a queued write would
+ *   forbid the caller any later read, and the entry is a cache fill that
+ *   never has to be atomic with anything. It is idempotent, so a retried
+ *   transaction body writing it twice is harmless.
+ *
+ * Imported by module path rather than through the `@aglyn/aglyn/server`
+ * barrel, for the reason `upsert-contact.ts` gives: the door's specs
+ * substitute a fixture barrel, and a helper that reached the normalizer only
+ * through it would find `undefined` there. Callers outside this library
+ * import THIS module by its leaf path for the mirror-image reason: most of
+ * their specs substitute the `@aglyn/tenant-data-admin` barrel wholesale.
+ */ import { CONTACT_EMAIL_INDEX_COLLECTION, normalizeContactEmail } from "@aglyn/aglyn/app-utils/contacts";
+import { personKey } from "@aglyn/aglyn/app-utils/person-key";
+import { visibleToHost } from "@aglyn/aglyn/app-utils/scope-tokens";
+import { FieldValue } from "firebase-admin/firestore";
+/**
+ * The org's index collection, beside its contacts one — or `null` when the
+ * handle has no parent, which is a fixture's contacts reference and never
+ * a real org subcollection. `null` means "no index": the caller falls back
+ * to the query and writes nothing.
+ */ export function emailIndexBeside(contactsRef) {
+    try {
+        const parent = contactsRef.parent;
+        return parent ? parent.collection(CONTACT_EMAIL_INDEX_COLLECTION) : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * Point every address in `emails` at `contactId`. Never rejects: an entry
+ * that could not be written is one the next lookup writes again.
+ */ export async function writeContactEmailIndex(index, contactId, emails) {
+    if (!index || !contactId) return;
+    await Promise.all(emails.map(async (raw)=>{
+        const email = normalizeContactEmail(raw);
+        const key = email ? personKey(email) : null;
+        if (!email || !key) return;
+        const entry = {
+            email,
+            contactId,
+            updatedAt: FieldValue.serverTimestamp()
+        };
+        await index.doc(key).set(entry, {
+            merge: true
+        });
+    })).catch((error)=>{
+        console.error('[contact-email-index] write failed', contactId, error);
+    });
+}
+/**
+ * The contact an address belongs to, as a document snapshot — or `null`.
+ *
+ * The index first, then the per-document query it summarizes. A query hit
+ * writes the entry the index lacked, so the read that paid for the miss is
+ * the last one that has to.
+ */ export async function findContactByEmail(contactsRef, email, options = {}) {
+    const normalized = normalizeContactEmail(email);
+    if (!normalized) return null;
+    const { hostId, transaction } = options;
+    const readDoc = (ref)=>transaction ? transaction.get(ref) : ref.get();
+    const readQuery = (query)=>transaction ? transaction.get(query) : query.get();
+    const index = emailIndexBeside(contactsRef);
+    const key = index ? personKey(normalized) : null;
+    let hit = null;
+    if (index && key) {
+        try {
+            var _entry_get;
+            const entry = await readDoc(index.doc(key));
+            const contactId = entry.exists ? String((_entry_get = entry.get('contactId')) != null ? _entry_get : '') : '';
+            if (contactId) {
+                const contact = await readDoc(contactsRef.doc(contactId));
+                if (contact.exists) hit = contact;
+            }
+        } catch (error) {
+            console.error('[contact-email-index] lookup failed', error);
+        }
+    }
+    if (!hit) {
+        var _found_docs_;
+        const found = await readQuery(contactsRef.where('email', '==', normalized).limit(1));
+        hit = (_found_docs_ = found.docs[0]) != null ? _found_docs_ : null;
+        if (!hit) return null;
+        await writeContactEmailIndex(index, hit.id, [
+            normalized
+        ]);
+    }
+    if (hostId && !visibleToHost(hit.get('visibleTo'), hostId)) {
+        return null;
+    }
+    return hit;
+}
+
+//# sourceMappingURL=contact-email-index.js.map

package/src/lib/server/contact-email-index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/contact-email-index.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\n/**\n * THE ADDRESS INDEX (AGL-2625): `orgs/{orgId}/emailIndex/{personKey}`.\n *\n * `upsertHostContact` finds a person by `where('email', '==', …)` on the\n * contacts collection, and that query answers one document per address by\n * construction — which is exactly what stops a merged record's address from\n * ever finding the survivor. The survivor's `email` is the identity that\n * stayed; the merged address is in its `alternateEmails`, and Firestore\n * cannot answer \"the document whose primary OR alternate address is X\" as\n * one indexed query. So the address is indexed on its own: one document per\n * address, naming the contact it belongs to.\n *\n * ## Consulted first, never trusted alone\n *\n * The lookup reads the index entry and then the contact it names, and\n * takes the contact only if it still exists. A stale entry — a contact\n * detached and deleted after its entry was written — falls through to the\n * query, which is the truth the index only summarizes.\n *\n * ## Written lazily, never backfilled\n *\n * An entry is written when a capture CREATES a contact, and when a lookup\n * finds one through the query rather than the index — so every existing\n * contact gains an entry on its next write, and no job has to walk the\n * collection. A merge writes one entry per address the survivor answers to.\n *\n * ## Never in the way of a capture\n *\n * Every read and write here is wrapped: a form submission or an order must\n * succeed whatever the index did, exactly as the capture itself swallows\n * its own failures. An index that cannot be reached is a miss, and a miss\n * is the query.\n *\n * ## One lookup for every door (AGL-2633)\n *\n * The capture door was the first reader; every other place that finds a\n * person by address — an automation step, the flow-email consent gate, the\n * delivery webhook's engagement stamp, the Inbox add-to-list check, a\n * refund, a campaign's proof and consent reads, the REST create and\n * `?email=` list — resolves through this same function, so a merged\n * record's alternate address answers the same person everywhere. Two of\n * those doors read differently from the capture, and the options carry it:\n *\n * - **`hostId`** narrows the answer to what ONE site may see. The index is\n *   org-wide, so the lookup is too; the scope check is applied to the\n *   document it names, in memory, which answers exactly what the scoped\n *   `email ==` query used to — one document per address, so a contact the\n *   site cannot see is `null` rather than a reason to look further.\n * - **`transaction`** routes every read through the caller's transaction,\n *   for a door that updates the contact it finds inside one. The lazy index\n *   write stays OUTSIDE the transaction, deliberately: a queued write would\n *   forbid the caller any later read, and the entry is a cache fill that\n *   never has to be atomic with anything. It is idempotent, so a retried\n *   transaction body writing it twice is harmless.\n *\n * Imported by module path rather than through the `@aglyn/aglyn/server`\n * barrel, for the reason `upsert-contact.ts` gives: the door's specs\n * substitute a fixture barrel, and a helper that reached the normalizer only\n * through it would find `undefined` there. Callers outside this library\n * import THIS module by its leaf path for the mirror-image reason: most of\n * their specs substitute the `@aglyn/tenant-data-admin` barrel wholesale.\n */\n\nimport {\n  CONTACT_EMAIL_INDEX_COLLECTION,\n  normalizeContactEmail,\n} from '@aglyn/aglyn/app-utils/contacts'\nimport { personKey } from '@aglyn/aglyn/app-utils/person-key'\nimport { visibleToHost } from '@aglyn/aglyn/app-utils/scope-tokens'\nimport { FieldValue } from 'firebase-admin/firestore'\n\n/** One entry: the address as stored, and the contact it resolves to. */\nexport interface ContactEmailIndexEntry {\n  email: string\n  contactId: string\n}\n\n/**\n * The org's index collection, beside its contacts one — or `null` when the\n * handle has no parent, which is a fixture's contacts reference and never\n * a real org subcollection. `null` means \"no index\": the caller falls back\n * to the query and writes nothing.\n */\nexport function emailIndexBeside(\n  contactsRef: FirebaseFirestore.CollectionReference,\n): FirebaseFirestore.CollectionReference | null {\n  try {\n    const parent = contactsRef.parent\n    return parent ? parent.collection(CONTACT_EMAIL_INDEX_COLLECTION) : null\n  } catch {\n    return null\n  }\n}\n\n/**\n * Point every address in `emails` at `contactId`. Never rejects: an entry\n * that could not be written is one the next lookup writes again.\n */\nexport async function writeContactEmailIndex(\n  index: FirebaseFirestore.CollectionReference | null,\n  contactId: string,\n  emails: readonly string[],\n): Promise<void> {\n  if (!index || !contactId) return\n  await Promise.all(\n    emails.map(async (raw) => {\n      const email = normalizeContactEmail(raw)\n      const key = email ? personKey(email) : null\n      if (!email || !key) return\n      const entry: ContactEmailIndexEntry & { updatedAt: unknown } = {\n        email,\n        contactId,\n        updatedAt: FieldValue.serverTimestamp(),\n      }\n      await index.doc(key).set(entry, { merge: true })\n    }),\n  ).catch((error: unknown) => {\n    console.error('[contact-email-index] write failed', contactId, error)\n  })\n}\n\n/** How one door reads differently from the capture; see the module notes. */\nexport interface FindContactByEmailOptions {\n  /**\n   * Answer only a contact THIS site may see. A document the address names\n   * but the site cannot read is `null` — the same answer the scoped\n   * `email ==` query gave, since one address names one document.\n   */\n  hostId?: string\n  /**\n   * Read through this transaction. Every read — the index entry, the\n   * contact it names, the fallback query — goes through it; the lazy index\n   * write does not, so the caller may still read after this returns.\n   */\n  transaction?: FirebaseFirestore.Transaction\n}\n\n/**\n * The contact an address belongs to, as a document snapshot — or `null`.\n *\n * The index first, then the per-document query it summarizes. A query hit\n * writes the entry the index lacked, so the read that paid for the miss is\n * the last one that has to.\n */\nexport async function findContactByEmail(\n  contactsRef: FirebaseFirestore.CollectionReference,\n  email: unknown,\n  options: FindContactByEmailOptions = {},\n): Promise<FirebaseFirestore.DocumentSnapshot | null> {\n  const normalized = normalizeContactEmail(email)\n  if (!normalized) return null\n  const { hostId, transaction } = options\n  const readDoc = (ref: FirebaseFirestore.DocumentReference) =>\n    transaction ? transaction.get(ref) : ref.get()\n  const readQuery = (query: FirebaseFirestore.Query) =>\n    transaction ? transaction.get(query) : query.get()\n\n  const index = emailIndexBeside(contactsRef)\n  const key = index ? personKey(normalized) : null\n  let hit: FirebaseFirestore.DocumentSnapshot | null = null\n  if (index && key) {\n    try {\n      const entry = await readDoc(index.doc(key))\n      const contactId = entry.exists ? String(entry.get('contactId') ?? '') : ''\n      if (contactId) {\n        const contact = await readDoc(contactsRef.doc(contactId))\n        if (contact.exists) hit = contact\n      }\n    } catch (error) {\n      console.error('[contact-email-index] lookup failed', error)\n    }\n  }\n  if (!hit) {\n    const found = await readQuery(\n      contactsRef.where('email', '==', normalized).limit(1),\n    )\n    hit = found.docs[0] ?? null\n    if (!hit) return null\n    await writeContactEmailIndex(index, hit.id, [normalized])\n  }\n  if (hostId && !visibleToHost(hit.get('visibleTo') as string[] | undefined, hostId)) {\n    return null\n  }\n  return hit\n}\n"],"names":["CONTACT_EMAIL_INDEX_COLLECTION","normalizeContactEmail","personKey","visibleToHost","FieldValue","emailIndexBeside","contactsRef","parent","collection","writeContactEmailIndex","index","contactId","emails","Promise","all","map","raw","email","key","entry","updatedAt","serverTimestamp","doc","set","merge","catch","error","console","findContactByEmail","options","normalized","hostId","transaction","readDoc","ref","get","readQuery","query","hit","exists","String","contact","found","where","limit","docs","id"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6DC,GAED,SACEA,8BAA8B,EAC9BC,qBAAqB,QAChB,kCAAiC;AACxC,SAASC,SAAS,QAAQ,oCAAmC;AAC7D,SAASC,aAAa,QAAQ,sCAAqC;AACnE,SAASC,UAAU,QAAQ,2BAA0B;AAQrD;;;;;CAKC,GACD,OAAO,SAASC,iBACdC,WAAkD;IAElD,IAAI;QACF,MAAMC,SAASD,YAAYC,MAAM;QACjC,OAAOA,SAASA,OAAOC,UAAU,CAACR,kCAAkC;IACtE,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;CAGC,GACD,OAAO,eAAeS,uBACpBC,KAAmD,EACnDC,SAAiB,EACjBC,MAAyB;IAEzB,IAAI,CAACF,SAAS,CAACC,WAAW;IAC1B,MAAME,QAAQC,GAAG,CACfF,OAAOG,GAAG,CAAC,OAAOC;QAChB,MAAMC,QAAQhB,sBAAsBe;QACpC,MAAME,MAAMD,QAAQf,UAAUe,SAAS;QACvC,IAAI,CAACA,SAAS,CAACC,KAAK;QACpB,MAAMC,QAAyD;YAC7DF;YACAN;YACAS,WAAWhB,WAAWiB,eAAe;QACvC;QACA,MAAMX,MAAMY,GAAG,CAACJ,KAAKK,GAAG,CAACJ,OAAO;YAAEK,OAAO;QAAK;IAChD,IACAC,KAAK,CAAC,CAACC;QACPC,QAAQD,KAAK,CAAC,sCAAsCf,WAAWe;IACjE;AACF;AAkBA;;;;;;CAMC,GACD,OAAO,eAAeE,mBACpBtB,WAAkD,EAClDW,KAAc,EACdY,UAAqC,CAAC,CAAC;IAEvC,MAAMC,aAAa7B,sBAAsBgB;IACzC,IAAI,CAACa,YAAY,OAAO;IACxB,MAAM,EAAEC,MAAM,EAAEC,WAAW,EAAE,GAAGH;IAChC,MAAMI,UAAU,CAACC,MACfF,cAAcA,YAAYG,GAAG,CAACD,OAAOA,IAAIC,GAAG;IAC9C,MAAMC,YAAY,CAACC,QACjBL,cAAcA,YAAYG,GAAG,CAACE,SAASA,MAAMF,GAAG;IAElD,MAAMzB,QAAQL,iBAAiBC;IAC/B,MAAMY,MAAMR,QAAQR,UAAU4B,cAAc;IAC5C,IAAIQ,MAAiD;IACrD,IAAI5B,SAASQ,KAAK;QAChB,IAAI;gBAEsCC;YADxC,MAAMA,QAAQ,MAAMc,QAAQvB,MAAMY,GAAG,CAACJ;YACtC,MAAMP,YAAYQ,MAAMoB,MAAM,GAAGC,QAAOrB,aAAAA,MAAMgB,GAAG,CAAC,wBAAVhB,aAA0B,MAAM;YACxE,IAAIR,WAAW;gBACb,MAAM8B,UAAU,MAAMR,QAAQ3B,YAAYgB,GAAG,CAACX;gBAC9C,IAAI8B,QAAQF,MAAM,EAAED,MAAMG;YAC5B;QACF,EAAE,OAAOf,OAAO;YACdC,QAAQD,KAAK,CAAC,uCAAuCA;QACvD;IACF;IACA,IAAI,CAACY,KAAK;YAIFI;QAHN,MAAMA,QAAQ,MAAMN,UAClB9B,YAAYqC,KAAK,CAAC,SAAS,MAAMb,YAAYc,KAAK,CAAC;QAErDN,OAAMI,eAAAA,MAAMG,IAAI,CAAC,EAAE,YAAbH,eAAiB;QACvB,IAAI,CAACJ,KAAK,OAAO;QACjB,MAAM7B,uBAAuBC,OAAO4B,IAAIQ,EAAE,EAAE;YAAChB;SAAW;IAC1D;IACA,IAAIC,UAAU,CAAC5B,cAAcmC,IAAIH,GAAG,CAAC,cAAsCJ,SAAS;QAClF,OAAO;IACT;IACA,OAAOO;AACT"}

package/src/lib/server/contact-lifecycle-floor.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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.
+ */
+/**
+ * A person's lifecycle stage, FLOORED at what just happened to them
+ * (AGL-2641).
+ *
+ * The capture doors floor a stage inside `upsertHostContact`: an order
+ * names `customer` as its `initialLifecycleStage`, and the door fills an
+ * empty stage or advances an earlier one and never moves anybody back. A
+ * won deal is the same fact as a purchase — the business has decided this
+ * person bought — but it arrives at a record that already exists, through a
+ * writer that is not a capture door: the deal-stage route and the REST
+ * deals resource. This is the door's rule for them, over a contact document
+ * they already hold a reference to.
+ *
+ * The write goes into ONE holder's facet, because a stage is one business's
+ * reading of a person and the row is shared by every site in the org. The
+ * holder is the site the deal was made on, resolved to its consent group
+ * the way every other facet writer resolves it; a deal that names no site
+ * falls back to the site that captured the person, which is the one
+ * holder a contact always has. A contact that names none either is left
+ * alone and the caller told, rather than written into a facet nobody reads.
+ *
+ * The write is skipped when it would change nothing — a customer stays a
+ * customer, an evangelist stays an evangelist, `other` is never overwritten
+ * — so a caller can announce `contactStageChanged` exactly when `advanced`
+ * says the stage moved, and an automation listening for the change never
+ * hears one that did not happen.
+ */
+import { type ContactLifecycleStage } from '@aglyn/aglyn/server';
+export type ContactLifecycleFloor = {
+    /** The stage was raised to the floor. */
+    outcome: 'advanced';
+    contactId: string;
+    /** The address on the row, for the event a caller announces. */
+    email: string;
+    /** The site whose facet was written. */
+    hostId: string;
+    groupId: string;
+    /** The stage before the write, or `''` for a person who had none. */
+    previousStage: ContactLifecycleStage | '';
+    lifecycleStage: ContactLifecycleStage;
+} | {
+    /** The person already held the floor or a later stage; nothing was written. */
+    outcome: 'held';
+    contactId: string;
+    email: string;
+    hostId: string;
+    groupId: string;
+    lifecycleStage: ContactLifecycleStage;
+} | {
+    /** No such contact. */
+    outcome: 'missing';
+    contactId: string;
+} | {
+    /** Neither the caller nor the contact names a site, so there is no facet to write. */
+    outcome: 'unheld';
+    contactId: string;
+};
+export interface ContactLifecycleFloorOptions {
+    contactRef: FirebaseFirestore.DocumentReference;
+    /**
+     * The org the contact belongs to, for the consent groups — the same
+     * document every facet writer resolves the holder through.
+     */
+    org: Record<string, unknown> | null | undefined;
+    /**
+     * The site the act happened on, whose facet takes the stage. `null` for a
+     * record no site captured; the contact's own capturing site is used then.
+     */
+    hostId: string | null | undefined;
+    /** The EARLIEST stage that describes what happened — see `advanceContactLifecycleStage`. */
+    floor: ContactLifecycleStage;
+}
+export declare function floorContactLifecycleStage(options: ContactLifecycleFloorOptions): Promise<ContactLifecycleFloor>;

package/src/lib/server/contact-lifecycle-floor.js

@@ -0,0 +1,88 @@
+/**
+ * @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.
+ */ /**
+ * A person's lifecycle stage, FLOORED at what just happened to them
+ * (AGL-2641).
+ *
+ * The capture doors floor a stage inside `upsertHostContact`: an order
+ * names `customer` as its `initialLifecycleStage`, and the door fills an
+ * empty stage or advances an earlier one and never moves anybody back. A
+ * won deal is the same fact as a purchase — the business has decided this
+ * person bought — but it arrives at a record that already exists, through a
+ * writer that is not a capture door: the deal-stage route and the REST
+ * deals resource. This is the door's rule for them, over a contact document
+ * they already hold a reference to.
+ *
+ * The write goes into ONE holder's facet, because a stage is one business's
+ * reading of a person and the row is shared by every site in the org. The
+ * holder is the site the deal was made on, resolved to its consent group
+ * the way every other facet writer resolves it; a deal that names no site
+ * falls back to the site that captured the person, which is the one
+ * holder a contact always has. A contact that names none either is left
+ * alone and the caller told, rather than written into a facet nobody reads.
+ *
+ * The write is skipped when it would change nothing — a customer stays a
+ * customer, an evangelist stays an evangelist, `other` is never overwritten
+ * — so a caller can announce `contactStageChanged` exactly when `advanced`
+ * says the stage moved, and an automation listening for the change never
+ * hears one that did not happen.
+ */ import { consentGroupForHost, advanceContactLifecycleStage, contactFacetPath, isContactLifecycleStage, readContactFacet } from "@aglyn/aglyn/server";
+import { FieldValue } from "firebase-admin/firestore";
+export async function floorContactLifecycleStage(options) {
+    var _snapshot_data, _options_hostId, _data_hostId, _advanceContactLifecycleStage, _data_email;
+    const { contactRef, org, floor } = options;
+    const snapshot = await contactRef.get();
+    if (!snapshot.exists) return {
+        outcome: 'missing',
+        contactId: contactRef.id
+    };
+    const data = (_snapshot_data = snapshot.data()) != null ? _snapshot_data : {};
+    const hostId = String((_options_hostId = options.hostId) != null ? _options_hostId : '').trim() || String((_data_hostId = data['hostId']) != null ? _data_hostId : '').trim();
+    if (!hostId) return {
+        outcome: 'unheld',
+        contactId: snapshot.id
+    };
+    const { groupId } = consentGroupForHost(org != null ? org : null, hostId);
+    const facet = readContactFacet(data, groupId);
+    const held = isContactLifecycleStage(facet.lifecycleStage) ? facet.lifecycleStage : undefined;
+    const lifecycleStage = (_advanceContactLifecycleStage = advanceContactLifecycleStage(held, floor)) != null ? _advanceContactLifecycleStage : floor;
+    const email = String((_data_email = data['email']) != null ? _data_email : '');
+    if (lifecycleStage === held) {
+        return {
+            outcome: 'held',
+            contactId: snapshot.id,
+            email,
+            hostId,
+            groupId,
+            lifecycleStage
+        };
+    }
+    await snapshot.ref.update({
+        [contactFacetPath(groupId, 'lifecycleStage')]: lifecycleStage,
+        updatedAt: FieldValue.serverTimestamp()
+    });
+    return {
+        outcome: 'advanced',
+        contactId: snapshot.id,
+        email,
+        hostId,
+        groupId,
+        previousStage: held != null ? held : '',
+        lifecycleStage
+    };
+}
+
+//# sourceMappingURL=contact-lifecycle-floor.js.map

package/src/lib/server/contact-lifecycle-floor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/contact-lifecycle-floor.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\n/**\n * A person's lifecycle stage, FLOORED at what just happened to them\n * (AGL-2641).\n *\n * The capture doors floor a stage inside `upsertHostContact`: an order\n * names `customer` as its `initialLifecycleStage`, and the door fills an\n * empty stage or advances an earlier one and never moves anybody back. A\n * won deal is the same fact as a purchase — the business has decided this\n * person bought — but it arrives at a record that already exists, through a\n * writer that is not a capture door: the deal-stage route and the REST\n * deals resource. This is the door's rule for them, over a contact document\n * they already hold a reference to.\n *\n * The write goes into ONE holder's facet, because a stage is one business's\n * reading of a person and the row is shared by every site in the org. The\n * holder is the site the deal was made on, resolved to its consent group\n * the way every other facet writer resolves it; a deal that names no site\n * falls back to the site that captured the person, which is the one\n * holder a contact always has. A contact that names none either is left\n * alone and the caller told, rather than written into a facet nobody reads.\n *\n * The write is skipped when it would change nothing — a customer stays a\n * customer, an evangelist stays an evangelist, `other` is never overwritten\n * — so a caller can announce `contactStageChanged` exactly when `advanced`\n * says the stage moved, and an automation listening for the change never\n * hears one that did not happen.\n */\n\nimport {\n  consentGroupForHost,\n  advanceContactLifecycleStage,\n  contactFacetPath,\n  type ContactLifecycleStage,\n  isContactLifecycleStage,\n  readContactFacet,\n} from '@aglyn/aglyn/server'\nimport { FieldValue } from 'firebase-admin/firestore'\n\nexport type ContactLifecycleFloor =\n  | {\n      /** The stage was raised to the floor. */\n      outcome: 'advanced'\n      contactId: string\n      /** The address on the row, for the event a caller announces. */\n      email: string\n      /** The site whose facet was written. */\n      hostId: string\n      groupId: string\n      /** The stage before the write, or `''` for a person who had none. */\n      previousStage: ContactLifecycleStage | ''\n      lifecycleStage: ContactLifecycleStage\n    }\n  | {\n      /** The person already held the floor or a later stage; nothing was written. */\n      outcome: 'held'\n      contactId: string\n      email: string\n      hostId: string\n      groupId: string\n      lifecycleStage: ContactLifecycleStage\n    }\n  | {\n      /** No such contact. */\n      outcome: 'missing'\n      contactId: string\n    }\n  | {\n      /** Neither the caller nor the contact names a site, so there is no facet to write. */\n      outcome: 'unheld'\n      contactId: string\n    }\n\nexport interface ContactLifecycleFloorOptions {\n  contactRef: FirebaseFirestore.DocumentReference\n  /**\n   * The org the contact belongs to, for the consent groups — the same\n   * document every facet writer resolves the holder through.\n   */\n  org: Record<string, unknown> | null | undefined\n  /**\n   * The site the act happened on, whose facet takes the stage. `null` for a\n   * record no site captured; the contact's own capturing site is used then.\n   */\n  hostId: string | null | undefined\n  /** The EARLIEST stage that describes what happened — see `advanceContactLifecycleStage`. */\n  floor: ContactLifecycleStage\n}\n\nexport async function floorContactLifecycleStage(\n  options: ContactLifecycleFloorOptions,\n): Promise<ContactLifecycleFloor> {\n  const { contactRef, org, floor } = options\n  const snapshot = await contactRef.get()\n  if (!snapshot.exists) return { outcome: 'missing', contactId: contactRef.id }\n  const data = (snapshot.data() ?? {}) as Record<string, unknown>\n  const hostId = String(options.hostId ?? '').trim() || String(data['hostId'] ?? '').trim()\n  if (!hostId) return { outcome: 'unheld', contactId: snapshot.id }\n\n  const { groupId } = consentGroupForHost(org ?? null, hostId)\n  const facet = readContactFacet(data, groupId)\n  const held = isContactLifecycleStage(facet.lifecycleStage)\n    ? facet.lifecycleStage\n    : undefined\n  const lifecycleStage = advanceContactLifecycleStage(held, floor) ?? floor\n  const email = String(data['email'] ?? '')\n  if (lifecycleStage === held) {\n    return { outcome: 'held', contactId: snapshot.id, email, hostId, groupId, lifecycleStage }\n  }\n  await snapshot.ref.update({\n    [contactFacetPath(groupId, 'lifecycleStage')]: lifecycleStage,\n    updatedAt: FieldValue.serverTimestamp(),\n  })\n  return {\n    outcome: 'advanced',\n    contactId: snapshot.id,\n    email,\n    hostId,\n    groupId,\n    previousStage: held ?? '',\n    lifecycleStage,\n  }\n}\n"],"names":["consentGroupForHost","advanceContactLifecycleStage","contactFacetPath","isContactLifecycleStage","readContactFacet","FieldValue","floorContactLifecycleStage","options","snapshot","data","contactRef","org","floor","get","exists","outcome","contactId","id","hostId","String","trim","groupId","facet","held","lifecycleStage","undefined","email","ref","update","updatedAt","serverTimestamp","previousStage"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GAED,SACEA,mBAAmB,EACnBC,4BAA4B,EAC5BC,gBAAgB,EAEhBC,uBAAuB,EACvBC,gBAAgB,QACX,sBAAqB;AAC5B,SAASC,UAAU,QAAQ,2BAA0B;AAoDrD,OAAO,eAAeC,2BACpBC,OAAqC;QAKvBC,gBACQD,iBAAuCE,cAQtCR,+BACFQ;IAbrB,MAAM,EAAEC,UAAU,EAAEC,GAAG,EAAEC,KAAK,EAAE,GAAGL;IACnC,MAAMC,WAAW,MAAME,WAAWG,GAAG;IACrC,IAAI,CAACL,SAASM,MAAM,EAAE,OAAO;QAAEC,SAAS;QAAWC,WAAWN,WAAWO,EAAE;IAAC;IAC5E,MAAMR,QAAQD,iBAAAA,SAASC,IAAI,cAAbD,iBAAmB,CAAC;IAClC,MAAMU,SAASC,QAAOZ,kBAAAA,QAAQW,MAAM,YAAdX,kBAAkB,IAAIa,IAAI,MAAMD,QAAOV,eAAAA,IAAI,CAAC,SAAS,YAAdA,eAAkB,IAAIW,IAAI;IACvF,IAAI,CAACF,QAAQ,OAAO;QAAEH,SAAS;QAAUC,WAAWR,SAASS,EAAE;IAAC;IAEhE,MAAM,EAAEI,OAAO,EAAE,GAAGrB,oBAAoBW,cAAAA,MAAO,MAAMO;IACrD,MAAMI,QAAQlB,iBAAiBK,MAAMY;IACrC,MAAME,OAAOpB,wBAAwBmB,MAAME,cAAc,IACrDF,MAAME,cAAc,GACpBC;IACJ,MAAMD,kBAAiBvB,gCAAAA,6BAA6BsB,MAAMX,kBAAnCX,gCAA6CW;IACpE,MAAMc,QAAQP,QAAOV,cAAAA,IAAI,CAAC,QAAQ,YAAbA,cAAiB;IACtC,IAAIe,mBAAmBD,MAAM;QAC3B,OAAO;YAAER,SAAS;YAAQC,WAAWR,SAASS,EAAE;YAAES;YAAOR;YAAQG;YAASG;QAAe;IAC3F;IACA,MAAMhB,SAASmB,GAAG,CAACC,MAAM,CAAC;QACxB,CAAC1B,iBAAiBmB,SAAS,kBAAkB,EAAEG;QAC/CK,WAAWxB,WAAWyB,eAAe;IACvC;IACA,OAAO;QACLf,SAAS;QACTC,WAAWR,SAASS,EAAE;QACtBS;QACAR;QACAG;QACAU,aAAa,EAAER,eAAAA,OAAQ;QACvBC;IACF;AACF"}