@aglyn/tenant-data-admin 1.0.0-beta.296 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +7 -7
- package/src/lib/server/dynamic-list-materialize.js +59 -21
- package/src/lib/server/dynamic-list-materialize.js.map +1 -1
- package/src/lib/server/list-members.d.ts +18 -1
- package/src/lib/server/list-members.js +25 -3
- package/src/lib/server/list-members.js.map +1 -1
- package/src/lib/server/vercel-log-drain.d.ts +6 -1
- package/src/lib/server/vercel-log-drain.js.map +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aglyn/tenant-data-admin",
|
|
3
|
-
"version": "1.0.0
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"homepage": "https://aglyn.com",
|
|
6
6
|
"repository": {
|
|
@@ -25,12 +25,12 @@
|
|
|
25
25
|
"./package.json": "./package.json"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@aglyn/aglyn": "1.0.0
|
|
29
|
-
"@aglyn/shared-util-email": "1.0.0
|
|
30
|
-
"@aglyn/shared-util-fbserver": "1.0.0
|
|
31
|
-
"@aglyn/shared-util-first-touch": "1.0.0
|
|
32
|
-
"@aglyn/shared-util-http": "1.0.0
|
|
33
|
-
"@aglyn/shared-util-tools": "1.0.0
|
|
28
|
+
"@aglyn/aglyn": "1.0.0",
|
|
29
|
+
"@aglyn/shared-util-email": "1.0.0",
|
|
30
|
+
"@aglyn/shared-util-fbserver": "1.0.0",
|
|
31
|
+
"@aglyn/shared-util-first-touch": "1.0.0",
|
|
32
|
+
"@aglyn/shared-util-http": "1.0.0",
|
|
33
|
+
"@aglyn/shared-util-tools": "1.0.0",
|
|
34
34
|
"@msgpack/msgpack": "^3.1.3",
|
|
35
35
|
"@swc/helpers": "0.5.23",
|
|
36
36
|
"sharp": "^0.35.5",
|
|
@@ -476,6 +476,7 @@ const millis = (value)=>{
|
|
|
476
476
|
* org-owned contacts read is narrowed to.
|
|
477
477
|
* @param resume a cursor from a previous incomplete run.
|
|
478
478
|
*/ export async function materializeDynamicList(options) {
|
|
479
|
+
var _ref;
|
|
479
480
|
/*
|
|
480
481
|
* The rule cannot refer to the list it materializes — see
|
|
481
482
|
* `dynamicListRuleWithoutListReference` for the oscillation that produces,
|
|
@@ -516,26 +517,6 @@ const millis = (value)=>{
|
|
|
516
517
|
const key = personKey(candidate.email);
|
|
517
518
|
if (key) matches.set(key, candidate);
|
|
518
519
|
}
|
|
519
|
-
let enrolled = 0;
|
|
520
|
-
for (const candidate of matches.values()){
|
|
521
|
-
const result = await enrollListMember(_extends({
|
|
522
|
-
listRef: options.listRef,
|
|
523
|
-
// A group of one, and it costs nothing: the materializer passes NO
|
|
524
|
-
// consent (see below), so the group decides only which site is recorded
|
|
525
|
-
// as having captured the row.
|
|
526
|
-
group: soloConsentGroup(options.hostId),
|
|
527
|
-
email: candidate.email
|
|
528
|
-
}, candidate.name ? {
|
|
529
|
-
name: candidate.name
|
|
530
|
-
} : {}, {
|
|
531
|
-
source: `rule:${candidate.silo}`,
|
|
532
|
-
via: 'rule'
|
|
533
|
-
}));
|
|
534
|
-
// A refusal is not a materialization failure: an unusable address and a
|
|
535
|
-
// person whose row records a refusal are both simply not on this list,
|
|
536
|
-
// and a rule that selected them does not overrule either.
|
|
537
|
-
if (result.enrolled && result.created) enrolled += 1;
|
|
538
|
-
}
|
|
539
520
|
/*
|
|
540
521
|
* Reconciliation is allowed only for a run that saw the WHOLE population:
|
|
541
522
|
* one that started at the beginning AND finished.
|
|
@@ -554,6 +535,58 @@ const millis = (value)=>{
|
|
|
554
535
|
* a wrong count, which is recoverable, and a deleted enrollment destroys
|
|
555
536
|
* the record that says the person asked to be there, which is not.
|
|
556
537
|
*/ const sawWholePopulation = complete && !options.resume;
|
|
538
|
+
/*
|
|
539
|
+
* WHO IS ALREADY HERE, read once (AGL-4121).
|
|
540
|
+
*
|
|
541
|
+
* Enrolling costs three reads and a write per person, and nearly everyone a
|
|
542
|
+
* sweep matches was enrolled by the sweep before it, so an unchanged list
|
|
543
|
+
* used to pay that for its whole membership every hour to rewrite each row
|
|
544
|
+
* as it stood. What is held below lets `enrollListMember` settle those
|
|
545
|
+
* people with no read and no write. It decides nothing itself: a person it
|
|
546
|
+
* does not hold, a manual row the rule is about to take over, a row under a
|
|
547
|
+
* legacy id, all go through the same enrollment they always did.
|
|
548
|
+
*
|
|
549
|
+
* A run that saw everybody is about to read the rule's rows to reconcile, so
|
|
550
|
+
* it reads them here and reuses them. A partial run reconciles nothing and
|
|
551
|
+
* its list may be far longer than this run's matches, so it reads only those
|
|
552
|
+
* matches, one key each.
|
|
553
|
+
*/ const members = options.listRef.collection('members');
|
|
554
|
+
const readRuleRows = ()=>members.where('via', '==', 'rule').get();
|
|
555
|
+
const ruleRowsBefore = sawWholePopulation ? await readRuleRows() : null;
|
|
556
|
+
const heldRows = new Map();
|
|
557
|
+
for (const doc of (_ref = ruleRowsBefore == null ? void 0 : ruleRowsBefore.docs) != null ? _ref : [])heldRows.set(doc.id, doc);
|
|
558
|
+
if (!ruleRowsBefore && matches.size) {
|
|
559
|
+
const rows = await options.listRef.firestore.getAll(...[
|
|
560
|
+
...matches.keys()
|
|
561
|
+
].map((key)=>members.doc(key)));
|
|
562
|
+
for (const row of rows)if (row.exists) heldRows.set(row.id, row);
|
|
563
|
+
}
|
|
564
|
+
let enrolled = 0;
|
|
565
|
+
let wrote = false;
|
|
566
|
+
for (const [key, candidate] of matches){
|
|
567
|
+
const heldRow = heldRows.get(key);
|
|
568
|
+
const result = await enrollListMember(_extends({
|
|
569
|
+
listRef: options.listRef
|
|
570
|
+
}, heldRow ? {
|
|
571
|
+
heldRow
|
|
572
|
+
} : {}, {
|
|
573
|
+
// A group of one, and it costs nothing: the materializer passes NO
|
|
574
|
+
// consent (see below), so the group decides only which site is recorded
|
|
575
|
+
// as having captured the row.
|
|
576
|
+
group: soloConsentGroup(options.hostId),
|
|
577
|
+
email: candidate.email
|
|
578
|
+
}, candidate.name ? {
|
|
579
|
+
name: candidate.name
|
|
580
|
+
} : {}, {
|
|
581
|
+
source: `rule:${candidate.silo}`,
|
|
582
|
+
via: 'rule'
|
|
583
|
+
}));
|
|
584
|
+
// A refusal is not a materialization failure: an unusable address and a
|
|
585
|
+
// person whose row records a refusal are both simply not on this list,
|
|
586
|
+
// and a rule that selected them does not overrule either.
|
|
587
|
+
if (result.enrolled && result.created) enrolled += 1;
|
|
588
|
+
if (result.enrolled && !result.unchanged) wrote = true;
|
|
589
|
+
}
|
|
557
590
|
let removed = 0;
|
|
558
591
|
if (sawWholePopulation) {
|
|
559
592
|
/*
|
|
@@ -570,7 +603,12 @@ const millis = (value)=>{
|
|
|
570
603
|
* This is the one removal in this file and it is a MEMBERSHIP change —
|
|
571
604
|
* the person stopped matching the rule. It is not a capacity decision and
|
|
572
605
|
* there is no count in the condition.
|
|
573
|
-
|
|
606
|
+
*
|
|
607
|
+
* Read again only when the loop above wrote: then time has passed and
|
|
608
|
+
* somebody's hand-enrollment may have taken a row off the rule meanwhile,
|
|
609
|
+
* which this must see before it deletes. A loop that wrote nothing took no
|
|
610
|
+
* time, so the rows above are the read this would have made.
|
|
611
|
+
*/ const existing = ruleRowsBefore && !wrote ? ruleRowsBefore : await readRuleRows();
|
|
574
612
|
for (const doc of existing.docs){
|
|
575
613
|
if (matches.has(doc.id)) continue;
|
|
576
614
|
// A row adopted under a legacy id is keyed by neither `personKey` nor
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dynamic-list-materialize.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 * Materializes a `kind: 'dynamic'` list's rule into its `members`\n * subcollection (`docs/specs/email-overhaul.md` §3b/§3e).\n *\n * A dynamic list does NOT resolve at send time. It stores a rule, a sweep\n * writes the matching people into the same `members` collection a manual list\n * uses, and the send path keeps reading one deterministic collection. Three\n * reasons, all of them things that have already gone wrong here:\n *\n * 1. The send must not run an unbounded scan — that is what produced an\n * arbitrary, unstable 500 of a site's 3,000 leads.\n * 2. The composer needs a cheap count, not a 5,000-document scan per\n * keystroke.\n * 3. \"Who did this campaign go to\" is a support question and a compliance\n * question. A materialized membership answers it; a rule re-evaluated\n * later does not.\n *\n * ## ⛔ A CEILING NEVER REMOVES A PERSON\n *\n * This function has no quota comparison and must never grow one. Capacity in\n * this product is enforced at the REDUCTION, not at the use: a limit that\n * refuses a person or their data leaks, because the person is already there\n * and dropping them is not a refusal, it is deletion. So a rule that matches\n * more people than a plan's audience band, or than a single send's recipient\n * cap, materializes ALL of them. The ceiling that a large audience meets is\n * `performCampaignSend`'s, which refuses the SEND and states the count it\n * found — a refusal the merchant can see, argue with, and act on, where a\n * trimmed membership is silent and unreproducible.\n *\n * What bounds this function is the per-run SCAN budget below, which is a\n * different thing: it bounds how much work one sweep does, and the cursor it\n * returns resumes the same sweep on the next run. Running out of budget\n * postpones enrollments; it never removes anybody, and it never finishes a\n * sweep it did not complete.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport type {\n DocumentReference,\n Query,\n QueryDocumentSnapshot,\n} from 'firebase-admin/firestore'\nimport {\n soloConsentGroup,\n candidateMatchesDynamicListRule,\n dynamicListRuleIsEmpty,\n dynamicListRuleListIds,\n dynamicListRuleWithoutListReference,\n dynamicListRuleNeedsContactFacet,\n dynamicListDimensionsForCrmView,\n dynamicListPlanningRule,\n CRM_COLLECTIONS,\n normalizeCrmViewFilters,\n type DynamicListDimensions,\n dynamicListRuleNeedsEngagement,\n extractEmailFromFields,\n seenOnlyThroughGrant,\n isContactLifecycleStage,\n normalizeContactEmail,\n normalizeDynamicListRule,\n personKey,\n readContainerIds,\n readContactContainerIds,\n readContactFacet,\n type ContactCustomValue,\n type DynamicListCandidate,\n type DynamicListRule,\n type DynamicListSource,\n type ResolvedSegmentFilters,\n} from '@aglyn/aglyn/server'\nimport { consentGroupHoldersInMotion } from '@aglyn/aglyn/app-utils/consent-group-change'\nimport { firebaseAdmin } from './firebase-admin'\nimport { readPersonEngagementByKeys } from './email-delivery-log'\nimport { enrollListMember } from './list-members'\nimport {\n consentGroupForSite,\n getOrgForHost,\n orgDataCollectionForHost,\n scopedToHost,\n} from './organizations'\n\n/**\n * Documents one sweep run may READ across all sources.\n *\n * A bound on work, not on membership. When a run exhausts it the sweep stops\n * where it is, returns `complete: false` with the cursor it reached, and the\n * next run continues — the shape the import-history sweep already uses. The\n * alternative, an unbounded scan of every silo per list per run, is the\n * expensive-read pattern this codebase refuses.\n *\n * ⚠️ Membership reconciliation is SKIPPED on an incomplete run. A partial\n * scan has only seen part of the population, so anybody it did not reach\n * would look like a non-match — and acting on that would delete real members\n * because a budget ran out.\n */\nexport const DYNAMIC_LIST_SCAN_BUDGET = 5_000\n\n/** Documents read per source page. */\nconst PAGE_SIZE = 500\n\n/**\n * ⚠️ THE DATE FIELDS THIS FILE READS, AND WHO WRITES THEM.\n *\n * `createdAfterMs`/`createdBeforeMs` are applied IN MEMORY against\n * `createdAt`, never as a Firestore `orderBy` or `where`. That distinction is\n * the whole safety property: an `orderBy` on a data field drops every document\n * missing it from the QUERY, invisibly, where an in-memory filter still reads\n * the document and merely decides it does not match. The paging order is\n * `__name__`, the one key every document has.\n *\n * The rule's decision for an undated record is to EXCLUDE it, so the writers\n * were checked rather than assumed — a silo with an unstamped writer would\n * quietly shrink every dated rule:\n *\n * - `leads` — `addHostLead` is the single writer and always stamps it.\n * - `siteMembers` — `membership-register.ts` is the only creator; the other\n * member routes read or update an existing document.\n * - `contacts` — `upsertHostContact`'s create path and the v1 API both stamp.\n * - `formSubmissions` — the submit route is the only creator; the v1 API and\n * the inbox reply route read.\n *\n * A new writer of any of those four must stamp `createdAt` or be added here.\n *\n * ## Campaign membership is read the same way — off the paged document\n *\n * `campaignIds` is applied in memory too, and for a second reason beyond the\n * one above: it is an ARRAY, so a Firestore `array-contains-any` could express\n * only the single-campaign case and would need a composite index the moment it\n * met any other filter in the rule. The membership is already on the document\n * this scan has read, on a submission at the top and on a contact inside the\n * reading holder's facet, so matching it costs nothing the page did not\n * already pay.\n */\n\n/** Where a partial sweep stopped, so the next run resumes rather than restarts. */\nexport interface DynamicListCursor {\n /** The source being scanned when the budget ran out. */\n source: DynamicListSource\n /** The last document id read from it. */\n afterId: string\n}\n\nexport interface MaterializeDynamicListResult {\n /** People the rule matched and that are now enrolled. */\n matched: number\n /** Rows created by this run. */\n enrolled: number\n /** Rule-owned rows removed because the person no longer matches. */\n removed: number\n /** False when the scan budget ran out — `cursor` says where to resume. */\n complete: boolean\n cursor: DynamicListCursor | null\n /**\n * True when the rule selects nobody by construction (no sources). Reported\n * rather than silently materializing an empty list, because an empty list\n * reads in the composer exactly like a rule that has not run yet.\n */\n empty: boolean\n}\n\n/** What a read-only pass over the silos found. */\nexport interface DynamicListScanResult {\n /** Matched people, de-duplicated across silos by their person key. */\n candidates: DynamicListCandidate[]\n /** False when the scan budget ran out — `cursor` says where to resume. */\n complete: boolean\n cursor: DynamicListCursor | null\n /**\n * True when the rule selects nobody by construction — no sources, or a\n * `segmentId` naming a segment that no longer exists.\n */\n empty: boolean\n /** Documents read, against the budget. */\n read: number\n}\n\n/**\n * The silo collections, as queries.\n *\n * `contacts` is org-scoped and must go through `scopedToHost` — the Admin SDK\n * does not evaluate rules, so an unfiltered read would let one site's list\n * materialize another site's contacts. The other three are host-owned and\n * carry no `visibleTo` to filter on.\n */\nasync function sourceQuery(\n source: DynamicListSource,\n hostId: string,\n): Promise<Query> {\n const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(hostId)\n if (source === 'contacts') {\n const ref = await orgDataCollectionForHost(hostId, 'contacts')\n return scopedToHost(ref, hostId)\n }\n return hostRef.collection(source)\n}\n\nconst millis = (value: unknown): number | null => {\n if (typeof value === 'number') return Number.isFinite(value) ? value : null\n const toMillis = (value as { toMillis?: unknown } | null)?.toMillis\n if (typeof toMillis === 'function') {\n const parsed = Number(toMillis.call(value))\n return Number.isFinite(parsed) ? parsed : null\n }\n return null\n}\n\n/**\n * The CRM fields a rule may read, out of ONE holder's facet (AGL-2603).\n *\n * The owner, the stage, the company and the custom values are this holder's\n * business records on a shared row. They are read through `readContactFacet`\n * for the group the sweep runs as — never off the top of the document, where\n * a pre-facet row could still carry somebody's fields, and never out of\n * another group's facet. A field the facet does not carry is left ABSENT on\n * the candidate, which the matcher reads as \"does not match\" for the first\n * three and as \"unset\" for a custom clause; a stage the model does not name\n * is dropped for the reason the normalizer drops one from a rule.\n */\nfunction crmFieldsFromFacet(\n data: Record<string, unknown>,\n groupId: string,\n): Pick<\n DynamicListCandidate,\n 'ownerUid' | 'lifecycleStage' | 'companyId' | 'custom' | 'lastEmailEngagementAtMs'\n> {\n const facet = readContactFacet(data, groupId)\n const custom =\n facet.custom && typeof facet.custom === 'object' && !Array.isArray(facet.custom)\n ? (facet.custom as Record<string, ContactCustomValue>)\n : undefined\n // The campaign engagement stamp (AGL-2616), on the same footing as the\n // owner: this holder's fact about the person, read out of this holder's\n // facet, absent when the webhook has never stamped one.\n const engaged = Number(facet.lastEmailEngagementAtMs ?? 0)\n return {\n ...(typeof facet.ownerUid === 'string' && facet.ownerUid\n ? { ownerUid: facet.ownerUid }\n : {}),\n ...(isContactLifecycleStage(facet.lifecycleStage)\n ? { lifecycleStage: facet.lifecycleStage }\n : {}),\n ...(typeof facet.companyId === 'string' && facet.companyId\n ? { companyId: facet.companyId }\n : {}),\n ...(custom ? { custom } : {}),\n ...(Number.isFinite(engaged) && engaged > 0\n ? { lastEmailEngagementAtMs: engaged }\n : {}),\n }\n}\n\n/**\n * Reads one silo document into the shape the rule matcher understands.\n *\n * @param groupId the consent group whose contact facet the campaign membership\n * and the CRM fields are read from, or `null` when the rule names none of\n * them and no group was resolved. A contact row is shared by every site in\n * the org and its membership, its owner, its stage, its company and its\n * custom values all live inside one holder's facet, so there is no\n * expression here that returns another holder's filing.\n */\nfunction toCandidate(\n source: DynamicListSource,\n doc: QueryDocumentSnapshot,\n groupId: string | null,\n): DynamicListCandidate | null {\n const data = doc.data() as Record<string, unknown>\n const email =\n source === 'formSubmissions'\n ? // A form does not guarantee a canonical email field, so this is the\n // same best-effort extraction the submissions route already uses to\n // decide whether a submission produces a contact at all.\n extractEmailFromFields(data['fields'] as Record<string, unknown>)\n : normalizeContactEmail(data['email'])\n if (!email) return null\n const createdAtMs = millis(data['createdAt'])\n return {\n silo: source,\n email,\n // `siteMembers` stores `displayName`; the rest store `name`. Reading only\n // `name` is what left every member campaign's merge tags blank.\n name:\n (typeof data['name'] === 'string' && data['name']) ||\n (typeof data['displayName'] === 'string' && data['displayName']) ||\n undefined,\n createdAtMs,\n ...(source === 'contacts'\n ? {\n tags: (data['tags'] as string[]) ?? [],\n sources: (data['sources'] as DynamicListCandidate['sources']) ?? {},\n ordersCount: Number(data['ordersCount'] ?? 0),\n ltvCents: Number(data['ltvCents'] ?? 0),\n lastPurchaseAtMs: millis(data['lastPurchaseAtMs']),\n // Inside the holder's facet, never the top of the document. A rule\n // with no facet clause resolves no group and reads nothing here,\n // which is what keeps the group lookup an opt-in cost.\n ...(groupId\n ? {\n campaignIds: readContactContainerIds(data, groupId, 'campaign'),\n ...crmFieldsFromFacet(data, groupId),\n }\n : {}),\n }\n : {}),\n ...(source === 'formSubmissions'\n ? {\n formName: String(data['formName'] ?? ''),\n // At the TOP of a submission, because a submission belongs to one\n // site — the same shape every other host resource carries it in.\n campaignIds: readContainerIds(data, 'campaign'),\n }\n : {}),\n }\n}\n\n/*==========================================\n * ENRICHMENT — the two dimensions the scan cannot read off a silo row.\n *\n * Engagement lives on `emailDeliveries/{personKey}` and list membership on\n * `orgs/{orgId}/lists/{listId}/members/{personKey}`. Both describe an ADDRESS\n * rather than a contact, a lead or a submission, so neither is in the\n * document the sweep just paged.\n *\n * Three properties, and each of them is a thing that could otherwise go\n * wrong here:\n *\n * 1. **KEYED reads, never queries.** `getAll` over document references. No\n * `where`, no `orderBy`, so no composite index, nothing that can be\n * truncated by a `limit`, and — the failure this codebase has hit\n * nineteen times — nothing that silently drops a document for missing\n * the field being ordered on.\n * 2. **Opt-in.** A rule with no engagement clause and no list reference\n * pays nothing at all. The cost belongs to the rules that ask for it,\n * not to every sweep.\n * 3. **Charged to the SAME scan budget.** Every enrichment read is counted\n * in `read`, so a rule that asks for engagement fills the budget faster\n * and its sweep simply takes more runs. The budget and the resume cursor\n * keep working exactly as they did; what changes is how much of the\n * budget one page costs.\n *=========================================*/\n\n/** What a rule needs looked up, resolved once per scan rather than per page. */\ninterface EnrichmentPlan {\n engagement: boolean\n /** `listId` → that list's `members` collection. */\n listMembers: Map<string, FirebaseFirestore.CollectionReference>\n}\n\n/**\n * Resolves what a rule needs enriched.\n *\n * A named list that no longer exists resolves to a collection with no\n * documents, which reads as \"nobody is a member\" — the same direction a\n * deleted `segmentId` takes, and the safe one: an `inListIds` naming a\n * deleted list selects nobody rather than everybody, and a `notInListIds`\n * naming one excludes nobody rather than the whole audience.\n */\nasync function planEnrichment(\n rule: DynamicListRule,\n hostId: string,\n): Promise<EnrichmentPlan> {\n const listIds = dynamicListRuleListIds(rule)\n const listMembers = new Map<string, FirebaseFirestore.CollectionReference>()\n if (listIds.length) {\n const lists = await orgDataCollectionForHost(hostId, 'lists')\n for (const listId of listIds) {\n listMembers.set(listId, lists.doc(listId).collection('members'))\n }\n }\n return { engagement: dynamicListRuleNeedsEngagement(rule), listMembers }\n}\n\n/** True when nothing needs looking up, so the page loop can skip the work. */\nfunction planIsEmpty(plan: EnrichmentPlan): boolean {\n return !plan.engagement && plan.listMembers.size === 0\n}\n\n/**\n * Fills the enrichment fields on one page's candidates.\n *\n * Keys are de-duplicated first: two silos can produce the same person on one\n * page, and looking them up twice would spend budget on an answer already in\n * hand.\n *\n * @returns how many documents were read, for the caller's budget.\n */\nasync function enrichCandidates(\n candidates: DynamicListCandidate[],\n plan: EnrichmentPlan,\n): Promise<number> {\n if (!candidates.length || planIsEmpty(plan)) return 0\n const keyed = new Map<string, DynamicListCandidate[]>()\n for (const candidate of candidates) {\n const key = personKey(candidate.email)\n if (!key) continue\n const held = keyed.get(key)\n if (held) held.push(candidate)\n else keyed.set(key, [candidate])\n }\n const keys = [...keyed.keys()]\n if (!keys.length) return 0\n const firestore = firebaseAdmin.app().firestore()\n let read = 0\n\n if (plan.engagement) {\n // The scan's own Firestore handle, passed rather than defaulted: the\n // rollup lives in another module with its own default, and two handles in\n // one sweep is two things a caller has to configure to reach one store.\n const engagement = await readPersonEngagementByKeys(keys, firestore)\n read += keys.length\n for (const [key, rows] of keyed) {\n const found = engagement.get(key)\n for (const candidate of rows) {\n candidate.lastOpenedAtMs = found?.lastOpenedAtMs ?? null\n candidate.lastClickedAtMs = found?.lastClickedAtMs ?? null\n }\n }\n }\n\n if (plan.listMembers.size) {\n // No pre-seeding of `listIds`. A candidate found on no list keeps the\n // field absent, and the matcher reads absent as \"on no list\" — see\n // `candidateMatchesDynamicListRule` for why that direction is the safe\n // one. Writing an empty array first would be a line saying the same thing\n // the matcher already says.\n for (const [listId, members] of plan.listMembers) {\n let snapshots: FirebaseFirestore.DocumentSnapshot[] = []\n try {\n snapshots = await firestore.getAll(\n ...keys.map((key) => members.doc(key)),\n )\n } catch (error) {\n // A failed membership lookup leaves every candidate reading as a\n // non-member of this list. That keeps an `inListIds` rule from\n // enrolling people it could not confirm, and it is the direction a\n // reader can recover from — the next sweep asks again.\n console.error('[dynamic-list] list membership lookup failed', listId, error)\n }\n read += keys.length\n for (const snapshot of snapshots) {\n if (!snapshot?.exists) continue\n for (const candidate of keyed.get(snapshot.id) ?? []) {\n candidate.listIds = [...(candidate.listIds ?? []), listId]\n }\n }\n }\n }\n\n return read\n}\n\n/**\n * WHO A RULE SELECTS, without writing anything.\n *\n * The scan and the enrollment used to be one function, so \"who would this\n * match\" could only be answered by materializing it. That is the wrong shape\n * for two callers that now exist: a merchant asking to see an audience before\n * committing to it, and a fixed list using the filters to FIND people to add.\n * Neither may write memberships as a side effect of a question.\n *\n * One scanner rather than two. Every subtlety here is a place a second\n * implementation would drift — the in-memory date filter (an `orderBy` on a\n * data field would DROP undated documents rather than merely not matching\n * them), the `__name__` paging order, `scopedToHost` on `contacts` and on\n * nothing else, and a deleted `segmentId` narrowing to nobody rather than\n * widening to everybody. `materializeDynamicList` reads this and then enrolls.\n *\n * NOTHING here writes, and nothing here compares a count against a limit.\n */\nexport async function collectDynamicListCandidates(options: {\n hostId: string\n rule: unknown\n resume?: DynamicListCursor | null\n nowMs?: number\n scanBudget?: number\n}): Promise<DynamicListScanResult> {\n const rule: DynamicListRule = normalizeDynamicListRule(options.rule)\n const nowMs = options.nowMs ?? Date.now()\n const budget = options.scanBudget ?? DYNAMIC_LIST_SCAN_BUDGET\n if (dynamicListRuleIsEmpty(rule)) {\n return { candidates: [], complete: true, cursor: null, empty: true, read: 0 }\n }\n\n // A saved segment's filters, resolved ONCE rather than per candidate.\n let segment: ResolvedSegmentFilters | null = null\n if (rule.segmentId) {\n const segments = await orgDataCollectionForHost(\n options.hostId,\n 'contactSegments',\n )\n const snapshot = await segments.doc(rule.segmentId).get()\n // A deleted segment narrows to nothing rather than widening to everybody:\n // a rule whose filter vanished must not start matching the whole org.\n if (!snapshot.exists) {\n return {\n candidates: [],\n complete: true,\n cursor: null,\n empty: true,\n read: 0,\n }\n }\n segment = {\n tags: (snapshot.get('tags') as string[]) ?? [],\n sources: (snapshot.get('sources') as ResolvedSegmentFilters['sources']) ?? [],\n }\n }\n\n /*\n * A saved VIEW's filters, resolved ONCE into this language (AGL-2617).\n *\n * The same two leans the segment takes, for the same reason: a view that\n * was deleted narrows to nothing, and so does one whose clauses this\n * language cannot carry — `dynamicListDimensionsForCrmView` names them\n * rather than dropping them, and dropping one would make the audience\n * wider than the view the merchant picked. The picker offers only views\n * that translate whole, so the second case is a view edited after the\n * rule named it, and a view of another section — a list of companies is\n * not an audience of people — reads the same way.\n */\n let view: DynamicListDimensions | null = null\n if (rule.viewId) {\n const views = await orgDataCollectionForHost(\n options.hostId,\n CRM_COLLECTIONS.views,\n )\n const snapshot = await views.doc(rule.viewId).get()\n const translation =\n snapshot.exists && snapshot.get('section') === 'contacts'\n ? dynamicListDimensionsForCrmView(\n normalizeCrmViewFilters(snapshot.get('filters')),\n )\n : null\n if (!translation || translation.unsupported.length) {\n return {\n candidates: [],\n complete: true,\n cursor: null,\n empty: true,\n read: 0,\n }\n }\n view = translation.dimensions\n }\n\n /*\n * Resolved once for the whole scan: it names collections, and re-resolving\n * the org for every page would be a read per page for an unchanging answer.\n * Planned with the view's dimensions beside the rule's: a view naming an\n * owner needs the facet exactly as a rule naming one does.\n */\n const planning = dynamicListPlanningRule(rule, view)\n const enrichment = await planEnrichment(planning, options.hostId)\n\n /*\n * THE HOLDER whose contact facet a campaign or CRM clause is read from.\n *\n * The same group the writers use — the sites declared to be one sender, or\n * this site alone — because a facet written under one group id and read\n * under another is a membership that silently matches nobody. Resolved once,\n * and only for a rule that names something the facet holds: a campaign, an\n * owner, a stage, a company or a custom field. A rule naming none of them\n * pays no org read at all, which is the shape the engagement and list\n * lookups already take.\n */\n let facetGroupId: string | null = null\n if (dynamicListRuleNeedsContactFacet(planning)) {\n const found = await getOrgForHost(options.hostId).catch(() => null)\n const org = (found?.org as Record<string, unknown> | undefined) ?? null\n /*\n * NOT WHILE THE FACETS MOVE (AGL-3320). A consent group change re-homes\n * this site's facets after its declaration flips, and until it finishes a\n * person's record may still sit under the old key — where this read,\n * keyed by the new group, finds nothing. A rule reads that absence as a\n * non-match, and a non-match is a removal. So the scan reports itself\n * incomplete and reads nothing: the materializer's own rule for a partial\n * view then enrolls nobody new and removes nobody, and the first sweep\n * after the change finishes reads every record where it landed.\n */\n if (consentGroupHoldersInMotion(org, options.hostId)) {\n return {\n candidates: [],\n complete: false,\n cursor: options.resume ?? null,\n empty: false,\n read: 0,\n }\n }\n facetGroupId = (await consentGroupForSite(options.hostId, org)).groupId\n }\n\n /** Matched people, de-duplicated across silos by their person key. */\n const matches = new Map<string, DynamicListCandidate>()\n let read = 0\n let cursor: DynamicListCursor | null = null\n let complete = true\n\n const ordered = rule.sources\n const resumeIndex = options.resume\n ? ordered.indexOf(options.resume.source)\n : -1\n\n scan: for (let index = 0; index < ordered.length; index += 1) {\n const source = ordered[index] as DynamicListSource\n // A resume skips the sources already finished and re-enters the one that\n // was interrupted at the id it stopped on.\n if (resumeIndex >= 0 && index < resumeIndex) continue\n let after = resumeIndex === index ? options.resume?.afterId ?? '' : ''\n const base = await sourceQuery(source, options.hostId)\n for (;;) {\n /*\n * Ordered by document id, and paged with a `startAfter` cursor.\n *\n * `orderBy(FieldPath.documentId())` rather than a data field on\n * purpose: an `orderBy` on a field DROPS every document missing it, and\n * these four collections have writers old enough that no data field is\n * guaranteed on every row. The id is on all of them, so this is a total\n * order that cannot silently omit a person — which is the whole point\n * of the exercise, since the defect being fixed is an unordered\n * `limit()` returning an arbitrary subset.\n */\n let page = base\n .orderBy(firebaseAdmin.firestore.FieldPath.documentId())\n .limit(PAGE_SIZE)\n if (after) page = page.startAfter(after)\n const snapshot = await page.get()\n if (snapshot.empty) break\n /*\n * The page is read into candidates FIRST, then enriched, then matched.\n *\n * A per-document match would mean a per-document enrichment lookup, and\n * the whole reason enrichment is affordable is that one page's people\n * are fetched in one `getAll`. Only candidates are enriched — a\n * document with no usable address is dropped by `toCandidate` before it\n * can cost a lookup.\n */\n const pageCandidates: DynamicListCandidate[] = []\n for (const doc of snapshot.docs) {\n read += 1\n after = doc.id\n // A contact another site SHARED with this one (AGL-3336) is seen\n // here, not held: it is never this site's audience.\n if (source === 'contacts' && seenOnlyThroughGrant(doc.data(), options.hostId)) continue\n const candidate = toCandidate(source, doc, facetGroupId)\n if (candidate) pageCandidates.push(candidate)\n }\n read += await enrichCandidates(pageCandidates, enrichment)\n for (const candidate of pageCandidates) {\n if (\n !candidateMatchesDynamicListRule(candidate, rule, {\n segment,\n view,\n nowMs,\n })\n ) {\n continue\n }\n const key = personKey(candidate.email)\n if (key && !matches.has(key)) matches.set(key, candidate)\n }\n if (read >= budget) {\n complete = false\n cursor = { source, afterId: after }\n break scan\n }\n if (snapshot.size < PAGE_SIZE) break\n }\n }\n\n\n return {\n candidates: [...matches.values()],\n complete,\n cursor,\n empty: false,\n read,\n }\n}\n\n/**\n * Re-evaluates one dynamic list and writes the result into its members.\n *\n * @param listRef `orgs/{orgId}/lists/{listId}` — the caller has proved it\n * exists and that it is `kind: 'dynamic'`.\n * @param hostId the site whose silos the rule draws from, and the scope the\n * org-owned contacts read is narrowed to.\n * @param resume a cursor from a previous incomplete run.\n */\nexport async function materializeDynamicList(options: {\n listRef: DocumentReference\n hostId: string\n rule: unknown\n resume?: DynamicListCursor | null\n nowMs?: number\n /**\n * The scan budget. Passed by NOTHING in production — it exists so the suite\n * can drive a sweep into an exhausted budget and require that it still\n * removes nobody. A guarantee that only holds at the production budget was\n * never that guarantee.\n */\n scanBudget?: number\n}): Promise<MaterializeDynamicListResult> {\n /*\n * The rule cannot refer to the list it materializes — see\n * `dynamicListRuleWithoutListReference` for the oscillation that produces,\n * and note that half of its beats are DELETIONS of rows this sweep created.\n * Stripped here rather than at authoring time because the rule outlives any\n * one form: an API caller, an import and a copied list would each need to\n * remember, and the sweep is the one place all of them arrive.\n */\n const rule = dynamicListRuleWithoutListReference(\n normalizeDynamicListRule(options.rule),\n options.listRef.id,\n )\n const scan = await collectDynamicListCandidates({\n hostId: options.hostId,\n rule,\n ...(options.resume ? { resume: options.resume } : {}),\n ...(options.nowMs !== undefined ? { nowMs: options.nowMs } : {}),\n ...(options.scanBudget !== undefined\n ? { scanBudget: options.scanBudget }\n : {}),\n })\n if (scan.empty) {\n return {\n matched: 0,\n enrolled: 0,\n removed: 0,\n complete: true,\n cursor: null,\n empty: true,\n }\n }\n const { complete, cursor } = scan\n /*\n * Re-keyed by person rather than carried as a Map across the seam.\n *\n * Reconciliation below asks `matches.has(key)` about a stored row's id and\n * about its address, so it needs the same key the scan de-duplicated on —\n * computed by the same function, from the same addresses.\n */\n const matches = new Map<string, DynamicListCandidate>()\n for (const candidate of scan.candidates) {\n const key = personKey(candidate.email)\n if (key) matches.set(key, candidate)\n }\n\n let enrolled = 0\n for (const candidate of matches.values()) {\n const result = await enrollListMember({\n listRef: options.listRef,\n // A group of one, and it costs nothing: the materializer passes NO\n // consent (see below), so the group decides only which site is recorded\n // as having captured the row.\n group: soloConsentGroup(options.hostId),\n email: candidate.email,\n ...(candidate.name ? { name: candidate.name } : {}),\n source: `rule:${candidate.silo}`,\n via: 'rule',\n /*\n * ⛔ NO CONSENT IS PASSED, EVER.\n *\n * Matching a rule is not consenting to anything — the person is here\n * because they bought something, filled in a form or hold an account,\n * and none of those is an opt-in. Stamping a basis from a rule match\n * would let any merchant manufacture consent for their whole contact\n * list by writing a rule that selects it, which is precisely the\n * inference the consent arc refused to make. Their real basis, if they\n * have one, is on their own record and the send-time join reads it\n * there.\n */\n })\n // A refusal is not a materialization failure: an unusable address and a\n // person whose row records a refusal are both simply not on this list,\n // and a rule that selected them does not overrule either.\n if (result.enrolled && result.created) enrolled += 1\n }\n\n /*\n * Reconciliation is allowed only for a run that saw the WHOLE population:\n * one that started at the beginning AND finished.\n *\n * `complete` alone is not enough, and that is the trap. A run that RESUMES\n * from a cursor finishes the tail of the scan and reports `complete: true`\n * having examined only the tail — so its match set is the remainder, and\n * reconciling against it would delete every member found by the earlier\n * runs of the same sweep. That is a quota drop wearing the costume of a\n * membership change: nothing about it looks like a limit, and it removes\n * people for no reason but how the work was chunked.\n *\n * The cost is that a list whose population exceeds one run's scan budget\n * never reconciles, so somebody who stops matching stays enrolled until a\n * sweep fits in one run. That is the right way round: an over-full list is\n * a wrong count, which is recoverable, and a deleted enrollment destroys\n * the record that says the person asked to be there, which is not.\n */\n const sawWholePopulation = complete && !options.resume\n let removed = 0\n if (sawWholePopulation) {\n /*\n * Reconciliation.\n *\n * Only rows this materializer created are eligible (`via === 'rule'`). A\n * row somebody enrolled by hand, or that an automation's `enrollList`\n * step wrote, stays on a dynamic list forever: it was put there by a\n * decision, and a rule that does not happen to select that person is not\n * a decision to remove them. Rows written before `via` existed carry no\n * `via` at all and are therefore never eligible either, which is the\n * conservative direction for a field introduced after the data.\n *\n * This is the one removal in this file and it is a MEMBERSHIP change —\n * the person stopped matching the rule. It is not a capacity decision and\n * there is no count in the condition.\n */\n const existing = await options.listRef\n .collection('members')\n .where('via', '==', 'rule')\n .get()\n for (const doc of existing.docs) {\n if (matches.has(doc.id)) continue\n // A row adopted under a legacy id is keyed by neither `personKey` nor\n // anything this sweep computed, so it is matched by ADDRESS as well\n // before being removed. Getting that wrong un-enrolls a person who\n // still matches the rule.\n const email = normalizeContactEmail(doc.get('email'))\n const key = email ? personKey(email) : null\n if (key && matches.has(key)) continue\n await doc.ref.delete()\n removed += 1\n }\n }\n\n await options.listRef.set(\n {\n kind: 'dynamic',\n // The count the composer reads instead of scanning. Written only by a\n // run that saw everybody, for the same reason reconciliation is: a\n // partial or resumed run measured a fraction, and publishing that as\n // the list's size would under-report the audience in the one place a\n // merchant checks it before sending.\n ...(sawWholePopulation ? { memberCount: matches.size } : {}),\n lastEvaluatedAt: FieldValue.serverTimestamp(),\n ...(cursor ? { evaluationCursor: cursor } : { evaluationCursor: null }),\n },\n { merge: true },\n )\n\n return {\n matched: matches.size,\n enrolled,\n removed,\n complete,\n cursor,\n empty: false,\n }\n}\n"],"names":["FieldValue","soloConsentGroup","candidateMatchesDynamicListRule","dynamicListRuleIsEmpty","dynamicListRuleListIds","dynamicListRuleWithoutListReference","dynamicListRuleNeedsContactFacet","dynamicListDimensionsForCrmView","dynamicListPlanningRule","CRM_COLLECTIONS","normalizeCrmViewFilters","dynamicListRuleNeedsEngagement","extractEmailFromFields","seenOnlyThroughGrant","isContactLifecycleStage","normalizeContactEmail","normalizeDynamicListRule","personKey","readContainerIds","readContactContainerIds","readContactFacet","consentGroupHoldersInMotion","firebaseAdmin","readPersonEngagementByKeys","enrollListMember","consentGroupForSite","getOrgForHost","orgDataCollectionForHost","scopedToHost","DYNAMIC_LIST_SCAN_BUDGET","PAGE_SIZE","sourceQuery","source","hostId","hostRef","app","firestore","collection","doc","ref","millis","value","Number","isFinite","toMillis","parsed","call","crmFieldsFromFacet","data","groupId","facet","custom","Array","isArray","undefined","engaged","lastEmailEngagementAtMs","ownerUid","lifecycleStage","companyId","toCandidate","email","createdAtMs","silo","name","tags","sources","ordersCount","ltvCents","lastPurchaseAtMs","campaignIds","formName","String","planEnrichment","rule","listIds","listMembers","Map","length","lists","listId","set","engagement","planIsEmpty","plan","size","enrichCandidates","candidates","keyed","candidate","key","held","get","push","keys","read","rows","found","lastOpenedAtMs","lastClickedAtMs","members","snapshots","getAll","map","error","console","snapshot","exists","id","collectDynamicListCandidates","options","nowMs","Date","now","budget","scanBudget","complete","cursor","empty","segment","segmentId","segments","view","viewId","views","translation","unsupported","dimensions","planning","enrichment","facetGroupId","catch","org","resume","matches","ordered","resumeIndex","indexOf","scan","index","after","afterId","base","page","orderBy","FieldPath","documentId","limit","startAfter","pageCandidates","docs","has","values","materializeDynamicList","listRef","matched","enrolled","removed","result","group","via","created","sawWholePopulation","existing","where","delete","kind","memberCount","lastEvaluatedAt","serverTimestamp","evaluationCursor","merge"],"mappings":"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"}
|
|
1
|
+
{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/dynamic-list-materialize.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 * Materializes a `kind: 'dynamic'` list's rule into its `members`\n * subcollection (`docs/specs/email-overhaul.md` §3b/§3e).\n *\n * A dynamic list does NOT resolve at send time. It stores a rule, a sweep\n * writes the matching people into the same `members` collection a manual list\n * uses, and the send path keeps reading one deterministic collection. Three\n * reasons, all of them things that have already gone wrong here:\n *\n * 1. The send must not run an unbounded scan — that is what produced an\n * arbitrary, unstable 500 of a site's 3,000 leads.\n * 2. The composer needs a cheap count, not a 5,000-document scan per\n * keystroke.\n * 3. \"Who did this campaign go to\" is a support question and a compliance\n * question. A materialized membership answers it; a rule re-evaluated\n * later does not.\n *\n * ## ⛔ A CEILING NEVER REMOVES A PERSON\n *\n * This function has no quota comparison and must never grow one. Capacity in\n * this product is enforced at the REDUCTION, not at the use: a limit that\n * refuses a person or their data leaks, because the person is already there\n * and dropping them is not a refusal, it is deletion. So a rule that matches\n * more people than a plan's audience band, or than a single send's recipient\n * cap, materializes ALL of them. The ceiling that a large audience meets is\n * `performCampaignSend`'s, which refuses the SEND and states the count it\n * found — a refusal the merchant can see, argue with, and act on, where a\n * trimmed membership is silent and unreproducible.\n *\n * What bounds this function is the per-run SCAN budget below, which is a\n * different thing: it bounds how much work one sweep does, and the cursor it\n * returns resumes the same sweep on the next run. Running out of budget\n * postpones enrollments; it never removes anybody, and it never finishes a\n * sweep it did not complete.\n */\n\nimport { FieldValue } from 'firebase-admin/firestore'\nimport type {\n DocumentReference,\n DocumentSnapshot,\n Query,\n QueryDocumentSnapshot,\n} from 'firebase-admin/firestore'\nimport {\n soloConsentGroup,\n candidateMatchesDynamicListRule,\n dynamicListRuleIsEmpty,\n dynamicListRuleListIds,\n dynamicListRuleWithoutListReference,\n dynamicListRuleNeedsContactFacet,\n dynamicListDimensionsForCrmView,\n dynamicListPlanningRule,\n CRM_COLLECTIONS,\n normalizeCrmViewFilters,\n type DynamicListDimensions,\n dynamicListRuleNeedsEngagement,\n extractEmailFromFields,\n seenOnlyThroughGrant,\n isContactLifecycleStage,\n normalizeContactEmail,\n normalizeDynamicListRule,\n personKey,\n readContainerIds,\n readContactContainerIds,\n readContactFacet,\n type ContactCustomValue,\n type DynamicListCandidate,\n type DynamicListRule,\n type DynamicListSource,\n type ResolvedSegmentFilters,\n} from '@aglyn/aglyn/server'\nimport { consentGroupHoldersInMotion } from '@aglyn/aglyn/app-utils/consent-group-change'\nimport { firebaseAdmin } from './firebase-admin'\nimport { readPersonEngagementByKeys } from './email-delivery-log'\nimport { enrollListMember } from './list-members'\nimport {\n consentGroupForSite,\n getOrgForHost,\n orgDataCollectionForHost,\n scopedToHost,\n} from './organizations'\n\n/**\n * Documents one sweep run may READ across all sources.\n *\n * A bound on work, not on membership. When a run exhausts it the sweep stops\n * where it is, returns `complete: false` with the cursor it reached, and the\n * next run continues — the shape the import-history sweep already uses. The\n * alternative, an unbounded scan of every silo per list per run, is the\n * expensive-read pattern this codebase refuses.\n *\n * ⚠️ Membership reconciliation is SKIPPED on an incomplete run. A partial\n * scan has only seen part of the population, so anybody it did not reach\n * would look like a non-match — and acting on that would delete real members\n * because a budget ran out.\n */\nexport const DYNAMIC_LIST_SCAN_BUDGET = 5_000\n\n/** Documents read per source page. */\nconst PAGE_SIZE = 500\n\n/**\n * ⚠️ THE DATE FIELDS THIS FILE READS, AND WHO WRITES THEM.\n *\n * `createdAfterMs`/`createdBeforeMs` are applied IN MEMORY against\n * `createdAt`, never as a Firestore `orderBy` or `where`. That distinction is\n * the whole safety property: an `orderBy` on a data field drops every document\n * missing it from the QUERY, invisibly, where an in-memory filter still reads\n * the document and merely decides it does not match. The paging order is\n * `__name__`, the one key every document has.\n *\n * The rule's decision for an undated record is to EXCLUDE it, so the writers\n * were checked rather than assumed — a silo with an unstamped writer would\n * quietly shrink every dated rule:\n *\n * - `leads` — `addHostLead` is the single writer and always stamps it.\n * - `siteMembers` — `membership-register.ts` is the only creator; the other\n * member routes read or update an existing document.\n * - `contacts` — `upsertHostContact`'s create path and the v1 API both stamp.\n * - `formSubmissions` — the submit route is the only creator; the v1 API and\n * the inbox reply route read.\n *\n * A new writer of any of those four must stamp `createdAt` or be added here.\n *\n * ## Campaign membership is read the same way — off the paged document\n *\n * `campaignIds` is applied in memory too, and for a second reason beyond the\n * one above: it is an ARRAY, so a Firestore `array-contains-any` could express\n * only the single-campaign case and would need a composite index the moment it\n * met any other filter in the rule. The membership is already on the document\n * this scan has read, on a submission at the top and on a contact inside the\n * reading holder's facet, so matching it costs nothing the page did not\n * already pay.\n */\n\n/** Where a partial sweep stopped, so the next run resumes rather than restarts. */\nexport interface DynamicListCursor {\n /** The source being scanned when the budget ran out. */\n source: DynamicListSource\n /** The last document id read from it. */\n afterId: string\n}\n\nexport interface MaterializeDynamicListResult {\n /** People the rule matched and that are now enrolled. */\n matched: number\n /** Rows created by this run. */\n enrolled: number\n /** Rule-owned rows removed because the person no longer matches. */\n removed: number\n /** False when the scan budget ran out — `cursor` says where to resume. */\n complete: boolean\n cursor: DynamicListCursor | null\n /**\n * True when the rule selects nobody by construction (no sources). Reported\n * rather than silently materializing an empty list, because an empty list\n * reads in the composer exactly like a rule that has not run yet.\n */\n empty: boolean\n}\n\n/** What a read-only pass over the silos found. */\nexport interface DynamicListScanResult {\n /** Matched people, de-duplicated across silos by their person key. */\n candidates: DynamicListCandidate[]\n /** False when the scan budget ran out — `cursor` says where to resume. */\n complete: boolean\n cursor: DynamicListCursor | null\n /**\n * True when the rule selects nobody by construction — no sources, or a\n * `segmentId` naming a segment that no longer exists.\n */\n empty: boolean\n /** Documents read, against the budget. */\n read: number\n}\n\n/**\n * The silo collections, as queries.\n *\n * `contacts` is org-scoped and must go through `scopedToHost` — the Admin SDK\n * does not evaluate rules, so an unfiltered read would let one site's list\n * materialize another site's contacts. The other three are host-owned and\n * carry no `visibleTo` to filter on.\n */\nasync function sourceQuery(\n source: DynamicListSource,\n hostId: string,\n): Promise<Query> {\n const hostRef = firebaseAdmin.app().firestore().collection('hosts').doc(hostId)\n if (source === 'contacts') {\n const ref = await orgDataCollectionForHost(hostId, 'contacts')\n return scopedToHost(ref, hostId)\n }\n return hostRef.collection(source)\n}\n\nconst millis = (value: unknown): number | null => {\n if (typeof value === 'number') return Number.isFinite(value) ? value : null\n const toMillis = (value as { toMillis?: unknown } | null)?.toMillis\n if (typeof toMillis === 'function') {\n const parsed = Number(toMillis.call(value))\n return Number.isFinite(parsed) ? parsed : null\n }\n return null\n}\n\n/**\n * The CRM fields a rule may read, out of ONE holder's facet (AGL-2603).\n *\n * The owner, the stage, the company and the custom values are this holder's\n * business records on a shared row. They are read through `readContactFacet`\n * for the group the sweep runs as — never off the top of the document, where\n * a pre-facet row could still carry somebody's fields, and never out of\n * another group's facet. A field the facet does not carry is left ABSENT on\n * the candidate, which the matcher reads as \"does not match\" for the first\n * three and as \"unset\" for a custom clause; a stage the model does not name\n * is dropped for the reason the normalizer drops one from a rule.\n */\nfunction crmFieldsFromFacet(\n data: Record<string, unknown>,\n groupId: string,\n): Pick<\n DynamicListCandidate,\n 'ownerUid' | 'lifecycleStage' | 'companyId' | 'custom' | 'lastEmailEngagementAtMs'\n> {\n const facet = readContactFacet(data, groupId)\n const custom =\n facet.custom && typeof facet.custom === 'object' && !Array.isArray(facet.custom)\n ? (facet.custom as Record<string, ContactCustomValue>)\n : undefined\n // The campaign engagement stamp (AGL-2616), on the same footing as the\n // owner: this holder's fact about the person, read out of this holder's\n // facet, absent when the webhook has never stamped one.\n const engaged = Number(facet.lastEmailEngagementAtMs ?? 0)\n return {\n ...(typeof facet.ownerUid === 'string' && facet.ownerUid\n ? { ownerUid: facet.ownerUid }\n : {}),\n ...(isContactLifecycleStage(facet.lifecycleStage)\n ? { lifecycleStage: facet.lifecycleStage }\n : {}),\n ...(typeof facet.companyId === 'string' && facet.companyId\n ? { companyId: facet.companyId }\n : {}),\n ...(custom ? { custom } : {}),\n ...(Number.isFinite(engaged) && engaged > 0\n ? { lastEmailEngagementAtMs: engaged }\n : {}),\n }\n}\n\n/**\n * Reads one silo document into the shape the rule matcher understands.\n *\n * @param groupId the consent group whose contact facet the campaign membership\n * and the CRM fields are read from, or `null` when the rule names none of\n * them and no group was resolved. A contact row is shared by every site in\n * the org and its membership, its owner, its stage, its company and its\n * custom values all live inside one holder's facet, so there is no\n * expression here that returns another holder's filing.\n */\nfunction toCandidate(\n source: DynamicListSource,\n doc: QueryDocumentSnapshot,\n groupId: string | null,\n): DynamicListCandidate | null {\n const data = doc.data() as Record<string, unknown>\n const email =\n source === 'formSubmissions'\n ? // A form does not guarantee a canonical email field, so this is the\n // same best-effort extraction the submissions route already uses to\n // decide whether a submission produces a contact at all.\n extractEmailFromFields(data['fields'] as Record<string, unknown>)\n : normalizeContactEmail(data['email'])\n if (!email) return null\n const createdAtMs = millis(data['createdAt'])\n return {\n silo: source,\n email,\n // `siteMembers` stores `displayName`; the rest store `name`. Reading only\n // `name` is what left every member campaign's merge tags blank.\n name:\n (typeof data['name'] === 'string' && data['name']) ||\n (typeof data['displayName'] === 'string' && data['displayName']) ||\n undefined,\n createdAtMs,\n ...(source === 'contacts'\n ? {\n tags: (data['tags'] as string[]) ?? [],\n sources: (data['sources'] as DynamicListCandidate['sources']) ?? {},\n ordersCount: Number(data['ordersCount'] ?? 0),\n ltvCents: Number(data['ltvCents'] ?? 0),\n lastPurchaseAtMs: millis(data['lastPurchaseAtMs']),\n // Inside the holder's facet, never the top of the document. A rule\n // with no facet clause resolves no group and reads nothing here,\n // which is what keeps the group lookup an opt-in cost.\n ...(groupId\n ? {\n campaignIds: readContactContainerIds(data, groupId, 'campaign'),\n ...crmFieldsFromFacet(data, groupId),\n }\n : {}),\n }\n : {}),\n ...(source === 'formSubmissions'\n ? {\n formName: String(data['formName'] ?? ''),\n // At the TOP of a submission, because a submission belongs to one\n // site — the same shape every other host resource carries it in.\n campaignIds: readContainerIds(data, 'campaign'),\n }\n : {}),\n }\n}\n\n/*==========================================\n * ENRICHMENT — the two dimensions the scan cannot read off a silo row.\n *\n * Engagement lives on `emailDeliveries/{personKey}` and list membership on\n * `orgs/{orgId}/lists/{listId}/members/{personKey}`. Both describe an ADDRESS\n * rather than a contact, a lead or a submission, so neither is in the\n * document the sweep just paged.\n *\n * Three properties, and each of them is a thing that could otherwise go\n * wrong here:\n *\n * 1. **KEYED reads, never queries.** `getAll` over document references. No\n * `where`, no `orderBy`, so no composite index, nothing that can be\n * truncated by a `limit`, and — the failure this codebase has hit\n * nineteen times — nothing that silently drops a document for missing\n * the field being ordered on.\n * 2. **Opt-in.** A rule with no engagement clause and no list reference\n * pays nothing at all. The cost belongs to the rules that ask for it,\n * not to every sweep.\n * 3. **Charged to the SAME scan budget.** Every enrichment read is counted\n * in `read`, so a rule that asks for engagement fills the budget faster\n * and its sweep simply takes more runs. The budget and the resume cursor\n * keep working exactly as they did; what changes is how much of the\n * budget one page costs.\n *=========================================*/\n\n/** What a rule needs looked up, resolved once per scan rather than per page. */\ninterface EnrichmentPlan {\n engagement: boolean\n /** `listId` → that list's `members` collection. */\n listMembers: Map<string, FirebaseFirestore.CollectionReference>\n}\n\n/**\n * Resolves what a rule needs enriched.\n *\n * A named list that no longer exists resolves to a collection with no\n * documents, which reads as \"nobody is a member\" — the same direction a\n * deleted `segmentId` takes, and the safe one: an `inListIds` naming a\n * deleted list selects nobody rather than everybody, and a `notInListIds`\n * naming one excludes nobody rather than the whole audience.\n */\nasync function planEnrichment(\n rule: DynamicListRule,\n hostId: string,\n): Promise<EnrichmentPlan> {\n const listIds = dynamicListRuleListIds(rule)\n const listMembers = new Map<string, FirebaseFirestore.CollectionReference>()\n if (listIds.length) {\n const lists = await orgDataCollectionForHost(hostId, 'lists')\n for (const listId of listIds) {\n listMembers.set(listId, lists.doc(listId).collection('members'))\n }\n }\n return { engagement: dynamicListRuleNeedsEngagement(rule), listMembers }\n}\n\n/** True when nothing needs looking up, so the page loop can skip the work. */\nfunction planIsEmpty(plan: EnrichmentPlan): boolean {\n return !plan.engagement && plan.listMembers.size === 0\n}\n\n/**\n * Fills the enrichment fields on one page's candidates.\n *\n * Keys are de-duplicated first: two silos can produce the same person on one\n * page, and looking them up twice would spend budget on an answer already in\n * hand.\n *\n * @returns how many documents were read, for the caller's budget.\n */\nasync function enrichCandidates(\n candidates: DynamicListCandidate[],\n plan: EnrichmentPlan,\n): Promise<number> {\n if (!candidates.length || planIsEmpty(plan)) return 0\n const keyed = new Map<string, DynamicListCandidate[]>()\n for (const candidate of candidates) {\n const key = personKey(candidate.email)\n if (!key) continue\n const held = keyed.get(key)\n if (held) held.push(candidate)\n else keyed.set(key, [candidate])\n }\n const keys = [...keyed.keys()]\n if (!keys.length) return 0\n const firestore = firebaseAdmin.app().firestore()\n let read = 0\n\n if (plan.engagement) {\n // The scan's own Firestore handle, passed rather than defaulted: the\n // rollup lives in another module with its own default, and two handles in\n // one sweep is two things a caller has to configure to reach one store.\n const engagement = await readPersonEngagementByKeys(keys, firestore)\n read += keys.length\n for (const [key, rows] of keyed) {\n const found = engagement.get(key)\n for (const candidate of rows) {\n candidate.lastOpenedAtMs = found?.lastOpenedAtMs ?? null\n candidate.lastClickedAtMs = found?.lastClickedAtMs ?? null\n }\n }\n }\n\n if (plan.listMembers.size) {\n // No pre-seeding of `listIds`. A candidate found on no list keeps the\n // field absent, and the matcher reads absent as \"on no list\" — see\n // `candidateMatchesDynamicListRule` for why that direction is the safe\n // one. Writing an empty array first would be a line saying the same thing\n // the matcher already says.\n for (const [listId, members] of plan.listMembers) {\n let snapshots: FirebaseFirestore.DocumentSnapshot[] = []\n try {\n snapshots = await firestore.getAll(\n ...keys.map((key) => members.doc(key)),\n )\n } catch (error) {\n // A failed membership lookup leaves every candidate reading as a\n // non-member of this list. That keeps an `inListIds` rule from\n // enrolling people it could not confirm, and it is the direction a\n // reader can recover from — the next sweep asks again.\n console.error('[dynamic-list] list membership lookup failed', listId, error)\n }\n read += keys.length\n for (const snapshot of snapshots) {\n if (!snapshot?.exists) continue\n for (const candidate of keyed.get(snapshot.id) ?? []) {\n candidate.listIds = [...(candidate.listIds ?? []), listId]\n }\n }\n }\n }\n\n return read\n}\n\n/**\n * WHO A RULE SELECTS, without writing anything.\n *\n * The scan and the enrollment used to be one function, so \"who would this\n * match\" could only be answered by materializing it. That is the wrong shape\n * for two callers that now exist: a merchant asking to see an audience before\n * committing to it, and a fixed list using the filters to FIND people to add.\n * Neither may write memberships as a side effect of a question.\n *\n * One scanner rather than two. Every subtlety here is a place a second\n * implementation would drift — the in-memory date filter (an `orderBy` on a\n * data field would DROP undated documents rather than merely not matching\n * them), the `__name__` paging order, `scopedToHost` on `contacts` and on\n * nothing else, and a deleted `segmentId` narrowing to nobody rather than\n * widening to everybody. `materializeDynamicList` reads this and then enrolls.\n *\n * NOTHING here writes, and nothing here compares a count against a limit.\n */\nexport async function collectDynamicListCandidates(options: {\n hostId: string\n rule: unknown\n resume?: DynamicListCursor | null\n nowMs?: number\n scanBudget?: number\n}): Promise<DynamicListScanResult> {\n const rule: DynamicListRule = normalizeDynamicListRule(options.rule)\n const nowMs = options.nowMs ?? Date.now()\n const budget = options.scanBudget ?? DYNAMIC_LIST_SCAN_BUDGET\n if (dynamicListRuleIsEmpty(rule)) {\n return { candidates: [], complete: true, cursor: null, empty: true, read: 0 }\n }\n\n // A saved segment's filters, resolved ONCE rather than per candidate.\n let segment: ResolvedSegmentFilters | null = null\n if (rule.segmentId) {\n const segments = await orgDataCollectionForHost(\n options.hostId,\n 'contactSegments',\n )\n const snapshot = await segments.doc(rule.segmentId).get()\n // A deleted segment narrows to nothing rather than widening to everybody:\n // a rule whose filter vanished must not start matching the whole org.\n if (!snapshot.exists) {\n return {\n candidates: [],\n complete: true,\n cursor: null,\n empty: true,\n read: 0,\n }\n }\n segment = {\n tags: (snapshot.get('tags') as string[]) ?? [],\n sources: (snapshot.get('sources') as ResolvedSegmentFilters['sources']) ?? [],\n }\n }\n\n /*\n * A saved VIEW's filters, resolved ONCE into this language (AGL-2617).\n *\n * The same two leans the segment takes, for the same reason: a view that\n * was deleted narrows to nothing, and so does one whose clauses this\n * language cannot carry — `dynamicListDimensionsForCrmView` names them\n * rather than dropping them, and dropping one would make the audience\n * wider than the view the merchant picked. The picker offers only views\n * that translate whole, so the second case is a view edited after the\n * rule named it, and a view of another section — a list of companies is\n * not an audience of people — reads the same way.\n */\n let view: DynamicListDimensions | null = null\n if (rule.viewId) {\n const views = await orgDataCollectionForHost(\n options.hostId,\n CRM_COLLECTIONS.views,\n )\n const snapshot = await views.doc(rule.viewId).get()\n const translation =\n snapshot.exists && snapshot.get('section') === 'contacts'\n ? dynamicListDimensionsForCrmView(\n normalizeCrmViewFilters(snapshot.get('filters')),\n )\n : null\n if (!translation || translation.unsupported.length) {\n return {\n candidates: [],\n complete: true,\n cursor: null,\n empty: true,\n read: 0,\n }\n }\n view = translation.dimensions\n }\n\n /*\n * Resolved once for the whole scan: it names collections, and re-resolving\n * the org for every page would be a read per page for an unchanging answer.\n * Planned with the view's dimensions beside the rule's: a view naming an\n * owner needs the facet exactly as a rule naming one does.\n */\n const planning = dynamicListPlanningRule(rule, view)\n const enrichment = await planEnrichment(planning, options.hostId)\n\n /*\n * THE HOLDER whose contact facet a campaign or CRM clause is read from.\n *\n * The same group the writers use — the sites declared to be one sender, or\n * this site alone — because a facet written under one group id and read\n * under another is a membership that silently matches nobody. Resolved once,\n * and only for a rule that names something the facet holds: a campaign, an\n * owner, a stage, a company or a custom field. A rule naming none of them\n * pays no org read at all, which is the shape the engagement and list\n * lookups already take.\n */\n let facetGroupId: string | null = null\n if (dynamicListRuleNeedsContactFacet(planning)) {\n const found = await getOrgForHost(options.hostId).catch(() => null)\n const org = (found?.org as Record<string, unknown> | undefined) ?? null\n /*\n * NOT WHILE THE FACETS MOVE (AGL-3320). A consent group change re-homes\n * this site's facets after its declaration flips, and until it finishes a\n * person's record may still sit under the old key — where this read,\n * keyed by the new group, finds nothing. A rule reads that absence as a\n * non-match, and a non-match is a removal. So the scan reports itself\n * incomplete and reads nothing: the materializer's own rule for a partial\n * view then enrolls nobody new and removes nobody, and the first sweep\n * after the change finishes reads every record where it landed.\n */\n if (consentGroupHoldersInMotion(org, options.hostId)) {\n return {\n candidates: [],\n complete: false,\n cursor: options.resume ?? null,\n empty: false,\n read: 0,\n }\n }\n facetGroupId = (await consentGroupForSite(options.hostId, org)).groupId\n }\n\n /** Matched people, de-duplicated across silos by their person key. */\n const matches = new Map<string, DynamicListCandidate>()\n let read = 0\n let cursor: DynamicListCursor | null = null\n let complete = true\n\n const ordered = rule.sources\n const resumeIndex = options.resume\n ? ordered.indexOf(options.resume.source)\n : -1\n\n scan: for (let index = 0; index < ordered.length; index += 1) {\n const source = ordered[index] as DynamicListSource\n // A resume skips the sources already finished and re-enters the one that\n // was interrupted at the id it stopped on.\n if (resumeIndex >= 0 && index < resumeIndex) continue\n let after = resumeIndex === index ? options.resume?.afterId ?? '' : ''\n const base = await sourceQuery(source, options.hostId)\n for (;;) {\n /*\n * Ordered by document id, and paged with a `startAfter` cursor.\n *\n * `orderBy(FieldPath.documentId())` rather than a data field on\n * purpose: an `orderBy` on a field DROPS every document missing it, and\n * these four collections have writers old enough that no data field is\n * guaranteed on every row. The id is on all of them, so this is a total\n * order that cannot silently omit a person — which is the whole point\n * of the exercise, since the defect being fixed is an unordered\n * `limit()` returning an arbitrary subset.\n */\n let page = base\n .orderBy(firebaseAdmin.firestore.FieldPath.documentId())\n .limit(PAGE_SIZE)\n if (after) page = page.startAfter(after)\n const snapshot = await page.get()\n if (snapshot.empty) break\n /*\n * The page is read into candidates FIRST, then enriched, then matched.\n *\n * A per-document match would mean a per-document enrichment lookup, and\n * the whole reason enrichment is affordable is that one page's people\n * are fetched in one `getAll`. Only candidates are enriched — a\n * document with no usable address is dropped by `toCandidate` before it\n * can cost a lookup.\n */\n const pageCandidates: DynamicListCandidate[] = []\n for (const doc of snapshot.docs) {\n read += 1\n after = doc.id\n // A contact another site SHARED with this one (AGL-3336) is seen\n // here, not held: it is never this site's audience.\n if (source === 'contacts' && seenOnlyThroughGrant(doc.data(), options.hostId)) continue\n const candidate = toCandidate(source, doc, facetGroupId)\n if (candidate) pageCandidates.push(candidate)\n }\n read += await enrichCandidates(pageCandidates, enrichment)\n for (const candidate of pageCandidates) {\n if (\n !candidateMatchesDynamicListRule(candidate, rule, {\n segment,\n view,\n nowMs,\n })\n ) {\n continue\n }\n const key = personKey(candidate.email)\n if (key && !matches.has(key)) matches.set(key, candidate)\n }\n if (read >= budget) {\n complete = false\n cursor = { source, afterId: after }\n break scan\n }\n if (snapshot.size < PAGE_SIZE) break\n }\n }\n\n\n return {\n candidates: [...matches.values()],\n complete,\n cursor,\n empty: false,\n read,\n }\n}\n\n/**\n * Re-evaluates one dynamic list and writes the result into its members.\n *\n * @param listRef `orgs/{orgId}/lists/{listId}` — the caller has proved it\n * exists and that it is `kind: 'dynamic'`.\n * @param hostId the site whose silos the rule draws from, and the scope the\n * org-owned contacts read is narrowed to.\n * @param resume a cursor from a previous incomplete run.\n */\nexport async function materializeDynamicList(options: {\n listRef: DocumentReference\n hostId: string\n rule: unknown\n resume?: DynamicListCursor | null\n nowMs?: number\n /**\n * The scan budget. Passed by NOTHING in production — it exists so the suite\n * can drive a sweep into an exhausted budget and require that it still\n * removes nobody. A guarantee that only holds at the production budget was\n * never that guarantee.\n */\n scanBudget?: number\n}): Promise<MaterializeDynamicListResult> {\n /*\n * The rule cannot refer to the list it materializes — see\n * `dynamicListRuleWithoutListReference` for the oscillation that produces,\n * and note that half of its beats are DELETIONS of rows this sweep created.\n * Stripped here rather than at authoring time because the rule outlives any\n * one form: an API caller, an import and a copied list would each need to\n * remember, and the sweep is the one place all of them arrive.\n */\n const rule = dynamicListRuleWithoutListReference(\n normalizeDynamicListRule(options.rule),\n options.listRef.id,\n )\n const scan = await collectDynamicListCandidates({\n hostId: options.hostId,\n rule,\n ...(options.resume ? { resume: options.resume } : {}),\n ...(options.nowMs !== undefined ? { nowMs: options.nowMs } : {}),\n ...(options.scanBudget !== undefined\n ? { scanBudget: options.scanBudget }\n : {}),\n })\n if (scan.empty) {\n return {\n matched: 0,\n enrolled: 0,\n removed: 0,\n complete: true,\n cursor: null,\n empty: true,\n }\n }\n const { complete, cursor } = scan\n /*\n * Re-keyed by person rather than carried as a Map across the seam.\n *\n * Reconciliation below asks `matches.has(key)` about a stored row's id and\n * about its address, so it needs the same key the scan de-duplicated on —\n * computed by the same function, from the same addresses.\n */\n const matches = new Map<string, DynamicListCandidate>()\n for (const candidate of scan.candidates) {\n const key = personKey(candidate.email)\n if (key) matches.set(key, candidate)\n }\n\n /*\n * Reconciliation is allowed only for a run that saw the WHOLE population:\n * one that started at the beginning AND finished.\n *\n * `complete` alone is not enough, and that is the trap. A run that RESUMES\n * from a cursor finishes the tail of the scan and reports `complete: true`\n * having examined only the tail — so its match set is the remainder, and\n * reconciling against it would delete every member found by the earlier\n * runs of the same sweep. That is a quota drop wearing the costume of a\n * membership change: nothing about it looks like a limit, and it removes\n * people for no reason but how the work was chunked.\n *\n * The cost is that a list whose population exceeds one run's scan budget\n * never reconciles, so somebody who stops matching stays enrolled until a\n * sweep fits in one run. That is the right way round: an over-full list is\n * a wrong count, which is recoverable, and a deleted enrollment destroys\n * the record that says the person asked to be there, which is not.\n */\n const sawWholePopulation = complete && !options.resume\n\n /*\n * WHO IS ALREADY HERE, read once (AGL-4121).\n *\n * Enrolling costs three reads and a write per person, and nearly everyone a\n * sweep matches was enrolled by the sweep before it, so an unchanged list\n * used to pay that for its whole membership every hour to rewrite each row\n * as it stood. What is held below lets `enrollListMember` settle those\n * people with no read and no write. It decides nothing itself: a person it\n * does not hold, a manual row the rule is about to take over, a row under a\n * legacy id, all go through the same enrollment they always did.\n *\n * A run that saw everybody is about to read the rule's rows to reconcile, so\n * it reads them here and reuses them. A partial run reconciles nothing and\n * its list may be far longer than this run's matches, so it reads only those\n * matches, one key each.\n */\n const members = options.listRef.collection('members')\n const readRuleRows = () => members.where('via', '==', 'rule').get()\n const ruleRowsBefore = sawWholePopulation ? await readRuleRows() : null\n const heldRows = new Map<string, DocumentSnapshot>()\n for (const doc of ruleRowsBefore?.docs ?? []) heldRows.set(doc.id, doc)\n if (!ruleRowsBefore && matches.size) {\n const rows = await options.listRef.firestore.getAll(\n ...[...matches.keys()].map((key) => members.doc(key)),\n )\n for (const row of rows) if (row.exists) heldRows.set(row.id, row)\n }\n\n let enrolled = 0\n let wrote = false\n for (const [key, candidate] of matches) {\n const heldRow = heldRows.get(key)\n const result = await enrollListMember({\n listRef: options.listRef,\n ...(heldRow ? { heldRow } : {}),\n // A group of one, and it costs nothing: the materializer passes NO\n // consent (see below), so the group decides only which site is recorded\n // as having captured the row.\n group: soloConsentGroup(options.hostId),\n email: candidate.email,\n ...(candidate.name ? { name: candidate.name } : {}),\n source: `rule:${candidate.silo}`,\n via: 'rule',\n /*\n * ⛔ NO CONSENT IS PASSED, EVER.\n *\n * Matching a rule is not consenting to anything — the person is here\n * because they bought something, filled in a form or hold an account,\n * and none of those is an opt-in. Stamping a basis from a rule match\n * would let any merchant manufacture consent for their whole contact\n * list by writing a rule that selects it, which is precisely the\n * inference the consent arc refused to make. Their real basis, if they\n * have one, is on their own record and the send-time join reads it\n * there.\n */\n })\n // A refusal is not a materialization failure: an unusable address and a\n // person whose row records a refusal are both simply not on this list,\n // and a rule that selected them does not overrule either.\n if (result.enrolled && result.created) enrolled += 1\n if (result.enrolled && !result.unchanged) wrote = true\n }\n\n let removed = 0\n if (sawWholePopulation) {\n /*\n * Reconciliation.\n *\n * Only rows this materializer created are eligible (`via === 'rule'`). A\n * row somebody enrolled by hand, or that an automation's `enrollList`\n * step wrote, stays on a dynamic list forever: it was put there by a\n * decision, and a rule that does not happen to select that person is not\n * a decision to remove them. Rows written before `via` existed carry no\n * `via` at all and are therefore never eligible either, which is the\n * conservative direction for a field introduced after the data.\n *\n * This is the one removal in this file and it is a MEMBERSHIP change —\n * the person stopped matching the rule. It is not a capacity decision and\n * there is no count in the condition.\n *\n * Read again only when the loop above wrote: then time has passed and\n * somebody's hand-enrollment may have taken a row off the rule meanwhile,\n * which this must see before it deletes. A loop that wrote nothing took no\n * time, so the rows above are the read this would have made.\n */\n const existing =\n ruleRowsBefore && !wrote ? ruleRowsBefore : await readRuleRows()\n for (const doc of existing.docs) {\n if (matches.has(doc.id)) continue\n // A row adopted under a legacy id is keyed by neither `personKey` nor\n // anything this sweep computed, so it is matched by ADDRESS as well\n // before being removed. Getting that wrong un-enrolls a person who\n // still matches the rule.\n const email = normalizeContactEmail(doc.get('email'))\n const key = email ? personKey(email) : null\n if (key && matches.has(key)) continue\n await doc.ref.delete()\n removed += 1\n }\n }\n\n await options.listRef.set(\n {\n kind: 'dynamic',\n // The count the composer reads instead of scanning. Written only by a\n // run that saw everybody, for the same reason reconciliation is: a\n // partial or resumed run measured a fraction, and publishing that as\n // the list's size would under-report the audience in the one place a\n // merchant checks it before sending.\n ...(sawWholePopulation ? { memberCount: matches.size } : {}),\n lastEvaluatedAt: FieldValue.serverTimestamp(),\n ...(cursor ? { evaluationCursor: cursor } : { evaluationCursor: null }),\n },\n { merge: true },\n )\n\n return {\n matched: matches.size,\n enrolled,\n removed,\n complete,\n cursor,\n empty: false,\n }\n}\n"],"names":["FieldValue","soloConsentGroup","candidateMatchesDynamicListRule","dynamicListRuleIsEmpty","dynamicListRuleListIds","dynamicListRuleWithoutListReference","dynamicListRuleNeedsContactFacet","dynamicListDimensionsForCrmView","dynamicListPlanningRule","CRM_COLLECTIONS","normalizeCrmViewFilters","dynamicListRuleNeedsEngagement","extractEmailFromFields","seenOnlyThroughGrant","isContactLifecycleStage","normalizeContactEmail","normalizeDynamicListRule","personKey","readContainerIds","readContactContainerIds","readContactFacet","consentGroupHoldersInMotion","firebaseAdmin","readPersonEngagementByKeys","enrollListMember","consentGroupForSite","getOrgForHost","orgDataCollectionForHost","scopedToHost","DYNAMIC_LIST_SCAN_BUDGET","PAGE_SIZE","sourceQuery","source","hostId","hostRef","app","firestore","collection","doc","ref","millis","value","Number","isFinite","toMillis","parsed","call","crmFieldsFromFacet","data","groupId","facet","custom","Array","isArray","undefined","engaged","lastEmailEngagementAtMs","ownerUid","lifecycleStage","companyId","toCandidate","email","createdAtMs","silo","name","tags","sources","ordersCount","ltvCents","lastPurchaseAtMs","campaignIds","formName","String","planEnrichment","rule","listIds","listMembers","Map","length","lists","listId","set","engagement","planIsEmpty","plan","size","enrichCandidates","candidates","keyed","candidate","key","held","get","push","keys","read","rows","found","lastOpenedAtMs","lastClickedAtMs","members","snapshots","getAll","map","error","console","snapshot","exists","id","collectDynamicListCandidates","options","nowMs","Date","now","budget","scanBudget","complete","cursor","empty","segment","segmentId","segments","view","viewId","views","translation","unsupported","dimensions","planning","enrichment","facetGroupId","catch","org","resume","matches","ordered","resumeIndex","indexOf","scan","index","after","afterId","base","page","orderBy","FieldPath","documentId","limit","startAfter","pageCandidates","docs","has","values","materializeDynamicList","listRef","matched","enrolled","removed","sawWholePopulation","readRuleRows","where","ruleRowsBefore","heldRows","row","wrote","heldRow","result","group","via","created","unchanged","existing","delete","kind","memberCount","lastEvaluatedAt","serverTimestamp","evaluationCursor","merge"],"mappings":"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"}
|
|
@@ -35,7 +35,7 @@
|
|
|
35
35
|
* Enrolling goes through this function so that the id has one definition and
|
|
36
36
|
* no caller is offered the chance to derive its own.
|
|
37
37
|
*/
|
|
38
|
-
import type { DocumentReference } from 'firebase-admin/firestore';
|
|
38
|
+
import type { DocumentReference, DocumentSnapshot } from 'firebase-admin/firestore';
|
|
39
39
|
import { type ConsentGroup } from '@aglyn/aglyn/server';
|
|
40
40
|
/**
|
|
41
41
|
* What a list's membership table searches a member by (AGL-3321): the word
|
|
@@ -175,6 +175,18 @@ export interface EnrollListMemberInput {
|
|
|
175
175
|
* person somebody added by hand does not.
|
|
176
176
|
*/
|
|
177
177
|
via?: 'manual' | 'rule';
|
|
178
|
+
/**
|
|
179
|
+
* This person's row at the canonical id, for a caller that has just read
|
|
180
|
+
* the list and is enrolling everyone on it (AGL-4121).
|
|
181
|
+
*
|
|
182
|
+
* The canonical row is the one the lookup below would have settled on,
|
|
183
|
+
* legacy rows or none, so a held row that exists answers the lookup without
|
|
184
|
+
* its `getAll`. Holding it is also the caller saying this is a re-enrollment
|
|
185
|
+
* sweep: a write that would leave the row exactly as it is goes unsent, and
|
|
186
|
+
* the result says `unchanged`. Everything else about the enrollment, a
|
|
187
|
+
* recorded refusal above all, is decided here as it is for every caller.
|
|
188
|
+
*/
|
|
189
|
+
heldRow?: DocumentSnapshot;
|
|
178
190
|
}
|
|
179
191
|
export interface EnrolledListMember {
|
|
180
192
|
/** The document actually written — a legacy id when one was adopted. */
|
|
@@ -183,6 +195,8 @@ export interface EnrolledListMember {
|
|
|
183
195
|
adopted: boolean;
|
|
184
196
|
/** False when the row already existed under some id. */
|
|
185
197
|
created: boolean;
|
|
198
|
+
/** True when a {@link EnrollListMemberInput.heldRow} needed no write at all. */
|
|
199
|
+
unchanged?: true;
|
|
186
200
|
}
|
|
187
201
|
/** Why nothing was written. */
|
|
188
202
|
export type EnrollListMemberRefusal =
|
|
@@ -223,6 +237,9 @@ export type EnrollListMemberResult = ({
|
|
|
223
237
|
*
|
|
224
238
|
* The cost is one `getAll` of three refs, on a human-triggered signup, in
|
|
225
239
|
* place of the blind `set` this replaced. It is one round trip, not three.
|
|
240
|
+
* The dynamic-list sweep is not human-triggered and hands in what it read
|
|
241
|
+
* instead (`heldRow`), or that one round trip is three reads and a write for
|
|
242
|
+
* every member of every list on every sweep.
|
|
226
243
|
*
|
|
227
244
|
* `addedAt` is stamped only when the document is created, so re-enrolling
|
|
228
245
|
* keeps the date the person actually joined — the same "earliest wins" collapse
|
|
@@ -39,6 +39,7 @@ import { normalizeContactEmail, personKey, CAPTURED_BY_HOST_FIELD, MARKETING_CON
|
|
|
39
39
|
import { consentGroupForGrant } from "@aglyn/aglyn/app-utils/consent-groups";
|
|
40
40
|
import { nameSearchTokens } from "@aglyn/aglyn/app-utils/name-search";
|
|
41
41
|
import { createHash, createHmac } from "node:crypto";
|
|
42
|
+
import { isDeepStrictEqual } from "node:util";
|
|
42
43
|
import { emailSearchTokens } from "./email-suppression.js";
|
|
43
44
|
import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
|
|
44
45
|
/**
|
|
@@ -108,6 +109,9 @@ import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
|
|
|
108
109
|
*
|
|
109
110
|
* The cost is one `getAll` of three refs, on a human-triggered signup, in
|
|
110
111
|
* place of the blind `set` this replaced. It is one round trip, not three.
|
|
112
|
+
* The dynamic-list sweep is not human-triggered and hands in what it read
|
|
113
|
+
* instead (`heldRow`), or that one round trip is three reads and a write for
|
|
114
|
+
* every member of every list on every sweep.
|
|
111
115
|
*
|
|
112
116
|
* `addedAt` is stamped only when the document is created, so re-enrolling
|
|
113
117
|
* keeps the date the person actually joined — the same "earliest wins" collapse
|
|
@@ -128,6 +132,7 @@ import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
|
|
|
128
132
|
* consent join reads the row this function writes either way.
|
|
129
133
|
*/ export async function enrollListMember(input) {
|
|
130
134
|
var _ref, _input_consent;
|
|
135
|
+
var _input_heldRow;
|
|
131
136
|
const email = normalizeContactEmail(input.email);
|
|
132
137
|
if (!email) return {
|
|
133
138
|
enrolled: false,
|
|
@@ -144,7 +149,9 @@ import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
|
|
|
144
149
|
// the same normalized address does — must not be fetched twice: `getAll`
|
|
145
150
|
// rejects duplicate references.
|
|
146
151
|
.filter((id)=>id !== key).map((id)=>members.doc(id));
|
|
147
|
-
const snapshots =
|
|
152
|
+
const snapshots = ((_input_heldRow = input.heldRow) == null ? void 0 : _input_heldRow.exists) ? [
|
|
153
|
+
input.heldRow
|
|
154
|
+
] : await input.listRef.firestore.getAll(canonicalRef, ...legacyRefs);
|
|
148
155
|
const existing = snapshots.find((snapshot)=>snapshot.exists);
|
|
149
156
|
const target = (_ref = existing == null ? void 0 : existing.ref) != null ? _ref : canonicalRef;
|
|
150
157
|
if (existing && readMarketingBasis(existing.data(), input.group).basis === 'declined') {
|
|
@@ -171,7 +178,7 @@ import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
|
|
|
171
178
|
* it already carries — because the search tokens are the address's and
|
|
172
179
|
* that name's, and a re-enrollment without a name keeps the stored one.
|
|
173
180
|
*/ const name = input.name || (existing == null ? void 0 : existing.get('name')) || null;
|
|
174
|
-
|
|
181
|
+
const fields = _extends({
|
|
175
182
|
email
|
|
176
183
|
}, input.name ? {
|
|
177
184
|
name: input.name
|
|
@@ -192,7 +199,22 @@ import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
|
|
|
192
199
|
[CAPTURED_BY_HOST_FIELD]: [
|
|
193
200
|
input.group.hostId
|
|
194
201
|
]
|
|
195
|
-
})
|
|
202
|
+
});
|
|
203
|
+
/*
|
|
204
|
+
* Compared against what this write would actually send, field by field,
|
|
205
|
+
* rather than against a list of what a sweep tends to change: a field added
|
|
206
|
+
* to the write above is covered here the day it is added, and any doubt
|
|
207
|
+
* (a Timestamp, a nested basis) reads as a difference and writes.
|
|
208
|
+
*/ if (input.heldRow && existing && Object.entries(fields).every(([field, value])=>isDeepStrictEqual(existing.get(field), value))) {
|
|
209
|
+
return {
|
|
210
|
+
enrolled: true,
|
|
211
|
+
memberId: target.id,
|
|
212
|
+
adopted: target.id !== key,
|
|
213
|
+
created: false,
|
|
214
|
+
unchanged: true
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
await target.set(fields, {
|
|
196
218
|
merge: true
|
|
197
219
|
});
|
|
198
220
|
/*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/list-members.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 only writer of `orgs/{orgId}/lists/{listId}/members` (AGL-2499).\n *\n * Two enrollment routes reach this collection — the commerce newsletter\n * handler and the workflow `enrollList` step — and they used to derive the\n * document id two incompatible ways: a full `sha256(email)` on one side, a\n * `hmac('aglyn-list-member', email)` truncated to 20 hex on the other. The\n * same person subscribing by both routes became two members of one list.\n *\n * The id is now `personKey` on both, which is the derivation both\n * `docs/specs/email-overhaul.md` §3d and `docs/specs/reusable-forms.md` §4\n * specify, and it normalizes before hashing so casing cannot fork it either.\n *\n * ## Why a helper and not two corrected call sites\n *\n * Two call sites that merely agree today are what produced the split: nothing\n * about either one said the other existed. A third route — the reusable-forms\n * capture path is already specified — would have been written the same way.\n * Enrolling goes through this function so that the id has one definition and\n * no caller is offered the chance to derive its own.\n */\n\nimport type { DocumentReference } from 'firebase-admin/firestore'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n normalizeContactEmail,\n personKey,\n CAPTURED_BY_HOST_FIELD,\n MARKETING_CONSENT_BASIS_FIELD,\n MARKETING_CONSENT_BY_HOST_FIELD,\n MARKETING_CONSENT_FIELD,\n marketingConsentFieldsForGroup,\n readMarketingBasis,\n type ConsentGroup,\n} from '@aglyn/aglyn/server'\nimport { consentGroupForGrant } from '@aglyn/aglyn/app-utils/consent-groups'\nimport { nameSearchTokens } from '@aglyn/aglyn/app-utils/name-search'\nimport { createHash, createHmac } from 'node:crypto'\nimport { emailSearchTokens } from './email-suppression'\nimport { scheduleCapturedEmailCheck } from './capture-email-check'\n\n/**\n * What a list's membership table searches a member by (AGL-3321): the word\n * prefixes of their name and of their address (`emailSearchTokens`), one\n * array, so one `array-contains` finds \"dana\" in either.\n *\n * Mirrored by `tools/scripts/backfill-email-list-filters.mjs`, which stamps\n * the rows written before the field; the two are held to the same fixtures\n * (`tools/scripts/lib/email-search-tokens.fixtures.json`, which the\n * script-side twin in `tools/scripts/lib/email-search-tokens.mjs` answers too).\n */\nexport function listMemberSearchTokens(\n email: string | null | undefined,\n name: string | null | undefined,\n): string[] {\n return [...new Set([...emailSearchTokens(email), ...nameSearchTokens(name)])]\n}\n\n/**\n * The two ids this collection was written under before `personKey`.\n *\n * Read-only, and never written for a new row: they exist so an address\n * already enrolled under a legacy id is *found* rather than duplicated. See\n * `enrollListMember` for why that lookup is the migration.\n *\n * Both take the normalized address, which is what the two original call sites\n * happened to pass — each lowercased at its own entry point before hashing, so\n * every row already on the collection was keyed from a lowercased address even\n * though neither derivation enforced it.\n */\nfunction legacyListMemberIds(normalizedEmail: string): string[] {\n return [\n createHash('sha256').update(normalizedEmail).digest('hex'),\n createHmac('sha256', 'aglyn-list-member')\n .update(normalizedEmail)\n .digest('hex')\n .slice(0, 20),\n ]\n}\n\n/**\n * Every document id one address may be filed under on a list's `members`:\n * the canonical key first, then the two ids earlier writers minted. A\n * reader that must find the person wherever they were enrolled — the\n * erasure sweep (AGL-2623) — asks for all of them with one `getAll`, the\n * same set `enrollListMember` reads before it writes, so a member enrolled\n * under an old id is neither missed nor duplicated.\n */\nexport function listMemberDocIds(email: unknown): string[] {\n const normalized = normalizeContactEmail(email)\n if (!normalized) return []\n const key = personKey(normalized)\n if (!key) return []\n return [key, ...legacyListMemberIds(normalized).filter((id) => id !== key)]\n}\n\n/**\n * What makes an enrollment mailable, and who is answerable for it.\n *\n * Two values and no third. They are not interchangeable and the difference is\n * the whole reason the basis is stored rather than implied:\n *\n * - `contact-opt-in` — the person ticked a box. The enrollment carries a\n * decision they made, and `atMs` is when THEY made it, not when the row was\n * written. Nobody is answerable because nobody asserted anything.\n * - `operator-attested` — a console account stated that they have this\n * person's permission. That statement is itself the basis, so it is only\n * worth storing with the account that made it and the moment they did.\n *\n * Rendering the second as though it were the first is what a support or\n * compliance question cannot recover from, which is why the basis rides\n * beside `marketingConsent` on every row that has one.\n */\nexport type ListMemberConsentBasis = 'contact-opt-in' | 'operator-attested'\n\n/** A basis, with the attribution that makes it answerable. */\nexport interface ListMemberConsent {\n basis: ListMemberConsentBasis\n /**\n * When the basis was recorded.\n *\n * For a pass-through this is the ORIGINAL opt-in moment carried over from\n * the person's own record, because the question a consent record answers is\n * when the person said yes — not when somebody copied their answer onto a\n * list.\n */\n atMs: number\n /** The console account that attested. Meaningless for a pass-through. */\n byUid?: string | null\n /**\n * Why, in the operator's own terms, for whoever audits this later.\n *\n * Written for an attestation and ignored for a pass-through, which needs no\n * explanation beyond the person's own record. An import fills it from what\n * the FILE declared — the opt-in source and date the merchant supplied per\n * row — because \"a declared basis per address, not one checkbox over the\n * file\" is only worth asking for if the declaration survives onto the row\n * it was made about.\n */\n reason?: string\n}\n\nexport interface EnrollListMemberInput {\n /** `orgs/{orgId}/lists/{listId}` — the caller has already proved it exists. */\n listRef: DocumentReference\n /**\n * The consent group the enrollment is being made IN THE NAME OF.\n *\n * Lists live on the org and every site in it can mail one, so a membership\n * carries a basis that no path could attribute to a controller. A GROUP\n * rather than a site, because a business running three sites under one name\n * legitimately enrolls somebody into all three at once — and an agency's\n * client, which declared no group, gets exactly itself.\n *\n * Required and undefaulted: a caller that has not resolved a group has not\n * decided who this person agreed to hear from.\n */\n group: ConsentGroup\n email: string\n name?: string\n /** Free-form provenance: `'newsletter'`, `'action:{actionId}'`. */\n source: string\n /**\n * Explicit marketing opt-in, with a consent timestamp — the same shape\n * `upsertHostContact` and `addHostLead` already carry.\n *\n * A list membership had NO consent field of any kind, so `audience: 'list'`\n * had nothing for the send-time join to read\n * (`docs/specs/email-overhaul.md` §1d/§3f). This is the field that closes\n * it, and it is the caller's captured checkbox: enrolling is an act, and\n * `false`/omitted therefore writes nothing rather than a basis.\n */\n marketingConsent?: boolean\n /**\n * The basis in full, for a caller that knows more than \"a box was ticked\".\n *\n * `marketingConsent: true` is the shorthand a capture surface uses: it means\n * `contact-opt-in`, recorded now, asserted by nobody. Anything else — a\n * pass-through carrying the person's ORIGINAL opt-in date, or an\n * attestation carrying the account that made it — has to say so, and this\n * is where it says it. The two inputs are normalized to one value before\n * anything is written, so there is a single writer of the consent fields.\n */\n consent?: ListMemberConsent\n /**\n * The person's own grants, as `grantEntriesAsRecorded` read them off their\n * record — what a PASS-THROUGH carries (AGL-3320).\n *\n * A `contact-opt-in` consent with these writes exactly these sites, with\n * each grant's own moment and the disclosure it was given under: an opt-in\n * given to one site before the group existed stays that site's on the list,\n * and one given under the group's sentence reaches the sites it named.\n * Re-recording the pass-through over {@link group} instead would widen the\n * first to every site the group names today.\n */\n grantEntries?: Readonly<Record<string, Readonly<Record<string, unknown>>>>\n /**\n * The `consentGroupDisclosureKey` a capture surface rendered beside its\n * checkbox, for a {@link marketingConsent} captured just now. The grant\n * pools across {@link group} only when it is the group's current key.\n *\n * Every other basis without {@link grantEntries} — an attestation, a\n * capture that rendered no disclosure — is recorded for the enrolling site\n * alone: an operator's word about one site's list is not a disclosure\n * anybody read about the rest.\n */\n disclosedConsentGroup?: string | null\n /**\n * How the person got here: enrolled by hand or by an automation\n * (`'manual'`), or selected by a dynamic list's rule (`'rule'`).\n *\n * The materializer needs to tell its own rows apart from a manual one on\n * the same list, because a person who stops matching the rule leaves and a\n * person somebody added by hand does not.\n */\n via?: 'manual' | 'rule'\n}\n\nexport interface EnrolledListMember {\n /** The document actually written — a legacy id when one was adopted. */\n memberId: string\n /** True when an existing legacy-keyed row was written instead of a new one. */\n adopted: boolean\n /** False when the row already existed under some id. */\n created: boolean\n}\n\n/** Why nothing was written. */\nexport type EnrollListMemberRefusal =\n /** Not an address this collection can key. Nothing to write, nothing to fix. */\n | 'unusable-address'\n /**\n * The person's membership records a REFUSAL. Not overridable by any caller\n * and not reported as a failure to fix, because the fix would be to ignore\n * it.\n */\n | 'declined'\n\n/**\n * Enrolled, or refused and why.\n *\n * A union rather than `EnrolledListMember | null`, because the two refusals\n * are not the same event and a caller that cannot tell them apart is a caller\n * that reports a person's recorded refusal as a malformed address.\n */\nexport type EnrollListMemberResult =\n | ({ enrolled: true } & EnrolledListMember)\n | { enrolled: false; refusal: EnrollListMemberRefusal }\n\n/**\n * Enrolls one address into a list, at one document per person.\n *\n * ## The legacy lookup is the migration\n *\n * Changing the derivation without one would strand every row written under the\n * old ids: the next enrollment of an address already on the list would key a\n * *new* document beside the old one, so a defect that produced duplicates only\n * when two routes met would start producing them on a single route. Rather\n * than rewrite those ids — a bulk operation that has to delete the row it\n * replaces, and deleting an enrollment destroys the consent record that says\n * the person asked to be there — the write resolves the person's existing\n * document and keeps using it.\n *\n * The cost is one `getAll` of three refs, on a human-triggered signup, in\n * place of the blind `set` this replaced. It is one round trip, not three.\n *\n * `addedAt` is stamped only when the document is created, so re-enrolling\n * keeps the date the person actually joined — the same \"earliest wins\" collapse\n * `docs/specs/email-overhaul.md` §3d asks a backfill to preserve.\n *\n * ## A recorded refusal stops every route through this function\n *\n * This is the only writer of the collection, so the refusal check belongs\n * here and not at the four call sites: a guard on the button that adds\n * somebody by hand leaves the newsletter handler, the workflow `enrollList`\n * step and the dynamic-list materializer free to put the same person back.\n * The membership snapshot is already in hand from the id resolution above, so\n * the check costs no read.\n *\n * It answers the question about the LIST ROW. A refusal recorded on the\n * person's CRM record is a different document this function does not fetch —\n * a caller that can see one is expected to consult it, and the send-time\n * consent join reads the row this function writes either way.\n */\nexport async function enrollListMember(\n input: EnrollListMemberInput,\n): Promise<EnrollListMemberResult> {\n const email = normalizeContactEmail(input.email)\n if (!email) return { enrolled: false, refusal: 'unusable-address' }\n const key = personKey(email)\n if (!key) return { enrolled: false, refusal: 'unusable-address' }\n\n const members = input.listRef.collection('members')\n const canonicalRef = members.doc(key)\n const legacyRefs = legacyListMemberIds(email)\n // A legacy derivation that happens to agree with `personKey` — `sha256` of\n // the same normalized address does — must not be fetched twice: `getAll`\n // rejects duplicate references.\n .filter((id) => id !== key)\n .map((id) => members.doc(id))\n\n const snapshots = await input.listRef.firestore.getAll(\n canonicalRef,\n ...legacyRefs,\n )\n const existing = snapshots.find((snapshot) => snapshot.exists)\n const target = existing?.ref ?? canonicalRef\n\n if (\n existing &&\n readMarketingBasis(existing.data() as Record<string, unknown>, input.group)\n .basis === 'declined'\n ) {\n return { enrolled: false, refusal: 'declined' }\n }\n\n /*\n * ONE value from the two ways a caller may state a basis.\n *\n * `marketingConsent: true` is a capture surface saying \"a box was ticked\n * just now\", which is `contact-opt-in` recorded at this moment with nobody\n * asserting it. Normalizing here rather than branching at the write is what\n * keeps the consent fields to a single writer — two branches stamping\n * overlapping subsets of them is how a row comes to carry a basis with no\n * timestamp, or a timestamp with no basis.\n */\n const consent: ListMemberConsent | null =\n input.consent ??\n (input.marketingConsent\n ? { basis: 'contact-opt-in', atMs: Date.now() }\n : null)\n\n /*\n * The name the row will hold after this write — the caller's, else the one\n * it already carries — because the search tokens are the address's and\n * that name's, and a re-enrollment without a name keeps the stored one.\n */\n const name = input.name || (existing?.get('name') as string | undefined) || null\n await target.set(\n {\n email,\n /*\n * `name` and `addedAt` are on EVERY row, because the members table\n * orders its query by them (AGL-3680) and `orderBy` drops a document\n * that lacks the field: the caller's name, else the stored one, else\n * `null`. A caller that says nothing never clears a stored name.\n */\n ...(input.name\n ? { name: input.name }\n : existing?.get('name') !== undefined\n ? {}\n : { name: null }),\n searchTokens: listMemberSearchTokens(email, name),\n source: input.source,\n /*\n * `via` is on every row, so the table's How filter can ask for it\n * (AGL-3321): the caller's, else `manual` on a row that has none — what\n * an absent `via` has always meant. A caller that says nothing never\n * moves a stored one.\n */\n ...(input.via\n ? { via: input.via }\n : existing?.get('via')\n ? {}\n : { via: 'manual' }),\n /*\n * Written only when the caller has a basis, and never unwritten.\n *\n * A merge that stamped `marketingConsent: false` on the omitted case\n * would erase a basis this person gave on an earlier enrollment, and a\n * withdrawn consent is not the same event as a re-enrollment that\n * happened to carry no checkbox. Withdrawal has its own path — the\n * unsubscribe link and the suppression list.\n *\n * `marketingConsentAtMs` moves with each fresh basis on purpose: the\n * question a consent record answers is when the person last said yes.\n *\n * The `marketingConsent` family rather than the `consent*` names\n * `docs/specs/email-overhaul.md` §3d sketched: `readMarketingBasis` is\n * the shipped reader and it reads these, so a second vocabulary here\n * would be a basis the send-time join cannot see. The two new fields\n * are attribution ON that field — they say why the person is mailable,\n * never whether — so nothing about the send decision moves into them.\n *\n * Written UNDER the enrolling GROUP, through the one writer helper. A\n * list lives on the org and every site in it can mail one, so a basis\n * written at the top of this row would enroll a person into one\n * client's newsletter and make them mailable by all of them. A group of\n * one — the default — is that client and nobody else.\n *\n * `marketingConsentByUid` is written on EVERY basis, `null` for a\n * pass-through. Leaving it absent would let a real opt-in that\n * supersedes an earlier attestation inherit the attesting account, and\n * a row reading \"this account vouched for them\" when the person ticked\n * a box themselves is a false attribution in the one direction a\n * compliance answer cannot afford.\n *\n * `marketingConsentReason` follows the same rule for the same reason:\n * always written, `''` for a pass-through, so a later real opt-in\n * cannot inherit the sentence an earlier import wrote about where the\n * merchant said the address came from.\n *\n * WHICH sites the basis covers is `membershipConsentFields`' to say,\n * and it never re-derives a grant from the group as it stands now.\n */\n ...(consent ? membershipConsentFields(input, consent) : {}),\n ...(existing\n ? // A legacy row that predates `addedAt` joined when it was created:\n // its document's create time, the date it has always meant.\n existing.get('addedAt') === undefined && existing.createTime\n ? { addedAt: existing.createTime }\n : {}\n : {\n addedAt: FieldValue.serverTimestamp(),\n [CAPTURED_BY_HOST_FIELD]: [input.group.hostId],\n }),\n },\n { merge: true },\n )\n\n /*\n * A person NEW to the list has their address's domain checked after the\n * response (AGL-3328), so the CRM record they are reads \"Would bounce\"\n * when it takes no mail. The list's owner names whose records those are:\n * an organization's list its own, a site's list the site's organization.\n */\n if (!existing) {\n const owner = input.listRef.parent?.parent\n const ownerKind = owner?.parent?.id\n scheduleCapturedEmailCheck({\n orgId: ownerKind === 'orgs' ? owner?.id : null,\n hostId: ownerKind === 'hosts' ? owner?.id : input.group?.hostId,\n email,\n })\n }\n\n return {\n enrolled: true,\n memberId: target.id,\n adopted: target.id !== key,\n created: !existing,\n }\n}\n\n/**\n * The consent fields one enrollment writes: the basis, its attribution, and\n * the sites it covers (AGL-3320).\n *\n * Three ways in, and the sites follow from which one it is:\n *\n * - a PASS-THROUGH with the person's {@link EnrollListMemberInput.grantEntries}\n * writes those sites and no others, each grant with its own moment and\n * the disclosure it was given under;\n * - a capture's checkbox pools over the group only when its surface sent\n * back the group's current disclosure key — `consentGroupForGrant`;\n * - everything else, an attestation among them, is the enrolling site's\n * alone.\n *\n * The attribution is the membership's own on every entry, the pass-through's\n * included, for the reason the write explains: an entry that kept an earlier\n * attestation's account under a person's own opt-in would be a false claim\n * about who vouched for them.\n */\nfunction membershipConsentFields(\n input: EnrollListMemberInput,\n consent: ListMemberConsent,\n): Record<string, unknown> {\n const attribution = {\n [MARKETING_CONSENT_BASIS_FIELD]: consent.basis,\n marketingConsentByUid: consent.byUid ?? null,\n marketingConsentReason: consent.reason ?? '',\n }\n const carried =\n consent.basis === 'contact-opt-in'\n ? Object.entries(input.grantEntries ?? {})\n : []\n if (carried.length) {\n return {\n [MARKETING_CONSENT_BY_HOST_FIELD]: Object.fromEntries(\n carried.map(([hostId, entry]) => [\n hostId,\n {\n ...entry,\n [MARKETING_CONSENT_FIELD]: true,\n // The grant's own moment; the pass-through's only when the\n // person's record never stamped one, as the basis itself falls\n // back to now.\n marketingConsentAtMs: entry['marketingConsentAtMs'] ?? consent.atMs,\n ...attribution,\n },\n ]),\n ),\n }\n }\n return marketingConsentFieldsForGroup(\n consentGroupForGrant(input.group, input.disclosedConsentGroup),\n consent.atMs,\n attribution,\n )\n}\n"],"names":["FieldValue","normalizeContactEmail","personKey","CAPTURED_BY_HOST_FIELD","MARKETING_CONSENT_BASIS_FIELD","MARKETING_CONSENT_BY_HOST_FIELD","MARKETING_CONSENT_FIELD","marketingConsentFieldsForGroup","readMarketingBasis","consentGroupForGrant","nameSearchTokens","createHash","createHmac","emailSearchTokens","scheduleCapturedEmailCheck","listMemberSearchTokens","email","name","Set","legacyListMemberIds","normalizedEmail","update","digest","slice","listMemberDocIds","normalized","key","filter","id","enrollListMember","input","enrolled","refusal","members","listRef","collection","canonicalRef","doc","legacyRefs","map","snapshots","firestore","getAll","existing","find","snapshot","exists","target","ref","data","group","basis","consent","marketingConsent","atMs","Date","now","get","set","undefined","searchTokens","source","via","membershipConsentFields","createTime","addedAt","serverTimestamp","hostId","merge","owner","parent","ownerKind","orgId","memberId","adopted","created","attribution","marketingConsentByUid","byUid","marketingConsentReason","reason","carried","Object","entries","grantEntries","length","fromEntries","entry","marketingConsentAtMs","disclosedConsentGroup"],"mappings":"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"}
|
|
1
|
+
{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/list-members.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 only writer of `orgs/{orgId}/lists/{listId}/members` (AGL-2499).\n *\n * Two enrollment routes reach this collection — the commerce newsletter\n * handler and the workflow `enrollList` step — and they used to derive the\n * document id two incompatible ways: a full `sha256(email)` on one side, a\n * `hmac('aglyn-list-member', email)` truncated to 20 hex on the other. The\n * same person subscribing by both routes became two members of one list.\n *\n * The id is now `personKey` on both, which is the derivation both\n * `docs/specs/email-overhaul.md` §3d and `docs/specs/reusable-forms.md` §4\n * specify, and it normalizes before hashing so casing cannot fork it either.\n *\n * ## Why a helper and not two corrected call sites\n *\n * Two call sites that merely agree today are what produced the split: nothing\n * about either one said the other existed. A third route — the reusable-forms\n * capture path is already specified — would have been written the same way.\n * Enrolling goes through this function so that the id has one definition and\n * no caller is offered the chance to derive its own.\n */\n\nimport type { DocumentReference, DocumentSnapshot } from 'firebase-admin/firestore'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n normalizeContactEmail,\n personKey,\n CAPTURED_BY_HOST_FIELD,\n MARKETING_CONSENT_BASIS_FIELD,\n MARKETING_CONSENT_BY_HOST_FIELD,\n MARKETING_CONSENT_FIELD,\n marketingConsentFieldsForGroup,\n readMarketingBasis,\n type ConsentGroup,\n} from '@aglyn/aglyn/server'\nimport { consentGroupForGrant } from '@aglyn/aglyn/app-utils/consent-groups'\nimport { nameSearchTokens } from '@aglyn/aglyn/app-utils/name-search'\nimport { createHash, createHmac } from 'node:crypto'\nimport { isDeepStrictEqual } from 'node:util'\nimport { emailSearchTokens } from './email-suppression'\nimport { scheduleCapturedEmailCheck } from './capture-email-check'\n\n/**\n * What a list's membership table searches a member by (AGL-3321): the word\n * prefixes of their name and of their address (`emailSearchTokens`), one\n * array, so one `array-contains` finds \"dana\" in either.\n *\n * Mirrored by `tools/scripts/backfill-email-list-filters.mjs`, which stamps\n * the rows written before the field; the two are held to the same fixtures\n * (`tools/scripts/lib/email-search-tokens.fixtures.json`, which the\n * script-side twin in `tools/scripts/lib/email-search-tokens.mjs` answers too).\n */\nexport function listMemberSearchTokens(\n email: string | null | undefined,\n name: string | null | undefined,\n): string[] {\n return [...new Set([...emailSearchTokens(email), ...nameSearchTokens(name)])]\n}\n\n/**\n * The two ids this collection was written under before `personKey`.\n *\n * Read-only, and never written for a new row: they exist so an address\n * already enrolled under a legacy id is *found* rather than duplicated. See\n * `enrollListMember` for why that lookup is the migration.\n *\n * Both take the normalized address, which is what the two original call sites\n * happened to pass — each lowercased at its own entry point before hashing, so\n * every row already on the collection was keyed from a lowercased address even\n * though neither derivation enforced it.\n */\nfunction legacyListMemberIds(normalizedEmail: string): string[] {\n return [\n createHash('sha256').update(normalizedEmail).digest('hex'),\n createHmac('sha256', 'aglyn-list-member')\n .update(normalizedEmail)\n .digest('hex')\n .slice(0, 20),\n ]\n}\n\n/**\n * Every document id one address may be filed under on a list's `members`:\n * the canonical key first, then the two ids earlier writers minted. A\n * reader that must find the person wherever they were enrolled — the\n * erasure sweep (AGL-2623) — asks for all of them with one `getAll`, the\n * same set `enrollListMember` reads before it writes, so a member enrolled\n * under an old id is neither missed nor duplicated.\n */\nexport function listMemberDocIds(email: unknown): string[] {\n const normalized = normalizeContactEmail(email)\n if (!normalized) return []\n const key = personKey(normalized)\n if (!key) return []\n return [key, ...legacyListMemberIds(normalized).filter((id) => id !== key)]\n}\n\n/**\n * What makes an enrollment mailable, and who is answerable for it.\n *\n * Two values and no third. They are not interchangeable and the difference is\n * the whole reason the basis is stored rather than implied:\n *\n * - `contact-opt-in` — the person ticked a box. The enrollment carries a\n * decision they made, and `atMs` is when THEY made it, not when the row was\n * written. Nobody is answerable because nobody asserted anything.\n * - `operator-attested` — a console account stated that they have this\n * person's permission. That statement is itself the basis, so it is only\n * worth storing with the account that made it and the moment they did.\n *\n * Rendering the second as though it were the first is what a support or\n * compliance question cannot recover from, which is why the basis rides\n * beside `marketingConsent` on every row that has one.\n */\nexport type ListMemberConsentBasis = 'contact-opt-in' | 'operator-attested'\n\n/** A basis, with the attribution that makes it answerable. */\nexport interface ListMemberConsent {\n basis: ListMemberConsentBasis\n /**\n * When the basis was recorded.\n *\n * For a pass-through this is the ORIGINAL opt-in moment carried over from\n * the person's own record, because the question a consent record answers is\n * when the person said yes — not when somebody copied their answer onto a\n * list.\n */\n atMs: number\n /** The console account that attested. Meaningless for a pass-through. */\n byUid?: string | null\n /**\n * Why, in the operator's own terms, for whoever audits this later.\n *\n * Written for an attestation and ignored for a pass-through, which needs no\n * explanation beyond the person's own record. An import fills it from what\n * the FILE declared — the opt-in source and date the merchant supplied per\n * row — because \"a declared basis per address, not one checkbox over the\n * file\" is only worth asking for if the declaration survives onto the row\n * it was made about.\n */\n reason?: string\n}\n\nexport interface EnrollListMemberInput {\n /** `orgs/{orgId}/lists/{listId}` — the caller has already proved it exists. */\n listRef: DocumentReference\n /**\n * The consent group the enrollment is being made IN THE NAME OF.\n *\n * Lists live on the org and every site in it can mail one, so a membership\n * carries a basis that no path could attribute to a controller. A GROUP\n * rather than a site, because a business running three sites under one name\n * legitimately enrolls somebody into all three at once — and an agency's\n * client, which declared no group, gets exactly itself.\n *\n * Required and undefaulted: a caller that has not resolved a group has not\n * decided who this person agreed to hear from.\n */\n group: ConsentGroup\n email: string\n name?: string\n /** Free-form provenance: `'newsletter'`, `'action:{actionId}'`. */\n source: string\n /**\n * Explicit marketing opt-in, with a consent timestamp — the same shape\n * `upsertHostContact` and `addHostLead` already carry.\n *\n * A list membership had NO consent field of any kind, so `audience: 'list'`\n * had nothing for the send-time join to read\n * (`docs/specs/email-overhaul.md` §1d/§3f). This is the field that closes\n * it, and it is the caller's captured checkbox: enrolling is an act, and\n * `false`/omitted therefore writes nothing rather than a basis.\n */\n marketingConsent?: boolean\n /**\n * The basis in full, for a caller that knows more than \"a box was ticked\".\n *\n * `marketingConsent: true` is the shorthand a capture surface uses: it means\n * `contact-opt-in`, recorded now, asserted by nobody. Anything else — a\n * pass-through carrying the person's ORIGINAL opt-in date, or an\n * attestation carrying the account that made it — has to say so, and this\n * is where it says it. The two inputs are normalized to one value before\n * anything is written, so there is a single writer of the consent fields.\n */\n consent?: ListMemberConsent\n /**\n * The person's own grants, as `grantEntriesAsRecorded` read them off their\n * record — what a PASS-THROUGH carries (AGL-3320).\n *\n * A `contact-opt-in` consent with these writes exactly these sites, with\n * each grant's own moment and the disclosure it was given under: an opt-in\n * given to one site before the group existed stays that site's on the list,\n * and one given under the group's sentence reaches the sites it named.\n * Re-recording the pass-through over {@link group} instead would widen the\n * first to every site the group names today.\n */\n grantEntries?: Readonly<Record<string, Readonly<Record<string, unknown>>>>\n /**\n * The `consentGroupDisclosureKey` a capture surface rendered beside its\n * checkbox, for a {@link marketingConsent} captured just now. The grant\n * pools across {@link group} only when it is the group's current key.\n *\n * Every other basis without {@link grantEntries} — an attestation, a\n * capture that rendered no disclosure — is recorded for the enrolling site\n * alone: an operator's word about one site's list is not a disclosure\n * anybody read about the rest.\n */\n disclosedConsentGroup?: string | null\n /**\n * How the person got here: enrolled by hand or by an automation\n * (`'manual'`), or selected by a dynamic list's rule (`'rule'`).\n *\n * The materializer needs to tell its own rows apart from a manual one on\n * the same list, because a person who stops matching the rule leaves and a\n * person somebody added by hand does not.\n */\n via?: 'manual' | 'rule'\n /**\n * This person's row at the canonical id, for a caller that has just read\n * the list and is enrolling everyone on it (AGL-4121).\n *\n * The canonical row is the one the lookup below would have settled on,\n * legacy rows or none, so a held row that exists answers the lookup without\n * its `getAll`. Holding it is also the caller saying this is a re-enrollment\n * sweep: a write that would leave the row exactly as it is goes unsent, and\n * the result says `unchanged`. Everything else about the enrollment, a\n * recorded refusal above all, is decided here as it is for every caller.\n */\n heldRow?: DocumentSnapshot\n}\n\nexport interface EnrolledListMember {\n /** The document actually written — a legacy id when one was adopted. */\n memberId: string\n /** True when an existing legacy-keyed row was written instead of a new one. */\n adopted: boolean\n /** False when the row already existed under some id. */\n created: boolean\n /** True when a {@link EnrollListMemberInput.heldRow} needed no write at all. */\n unchanged?: true\n}\n\n/** Why nothing was written. */\nexport type EnrollListMemberRefusal =\n /** Not an address this collection can key. Nothing to write, nothing to fix. */\n | 'unusable-address'\n /**\n * The person's membership records a REFUSAL. Not overridable by any caller\n * and not reported as a failure to fix, because the fix would be to ignore\n * it.\n */\n | 'declined'\n\n/**\n * Enrolled, or refused and why.\n *\n * A union rather than `EnrolledListMember | null`, because the two refusals\n * are not the same event and a caller that cannot tell them apart is a caller\n * that reports a person's recorded refusal as a malformed address.\n */\nexport type EnrollListMemberResult =\n | ({ enrolled: true } & EnrolledListMember)\n | { enrolled: false; refusal: EnrollListMemberRefusal }\n\n/**\n * Enrolls one address into a list, at one document per person.\n *\n * ## The legacy lookup is the migration\n *\n * Changing the derivation without one would strand every row written under the\n * old ids: the next enrollment of an address already on the list would key a\n * *new* document beside the old one, so a defect that produced duplicates only\n * when two routes met would start producing them on a single route. Rather\n * than rewrite those ids — a bulk operation that has to delete the row it\n * replaces, and deleting an enrollment destroys the consent record that says\n * the person asked to be there — the write resolves the person's existing\n * document and keeps using it.\n *\n * The cost is one `getAll` of three refs, on a human-triggered signup, in\n * place of the blind `set` this replaced. It is one round trip, not three.\n * The dynamic-list sweep is not human-triggered and hands in what it read\n * instead (`heldRow`), or that one round trip is three reads and a write for\n * every member of every list on every sweep.\n *\n * `addedAt` is stamped only when the document is created, so re-enrolling\n * keeps the date the person actually joined — the same \"earliest wins\" collapse\n * `docs/specs/email-overhaul.md` §3d asks a backfill to preserve.\n *\n * ## A recorded refusal stops every route through this function\n *\n * This is the only writer of the collection, so the refusal check belongs\n * here and not at the four call sites: a guard on the button that adds\n * somebody by hand leaves the newsletter handler, the workflow `enrollList`\n * step and the dynamic-list materializer free to put the same person back.\n * The membership snapshot is already in hand from the id resolution above, so\n * the check costs no read.\n *\n * It answers the question about the LIST ROW. A refusal recorded on the\n * person's CRM record is a different document this function does not fetch —\n * a caller that can see one is expected to consult it, and the send-time\n * consent join reads the row this function writes either way.\n */\nexport async function enrollListMember(\n input: EnrollListMemberInput,\n): Promise<EnrollListMemberResult> {\n const email = normalizeContactEmail(input.email)\n if (!email) return { enrolled: false, refusal: 'unusable-address' }\n const key = personKey(email)\n if (!key) return { enrolled: false, refusal: 'unusable-address' }\n\n const members = input.listRef.collection('members')\n const canonicalRef = members.doc(key)\n const legacyRefs = legacyListMemberIds(email)\n // A legacy derivation that happens to agree with `personKey` — `sha256` of\n // the same normalized address does — must not be fetched twice: `getAll`\n // rejects duplicate references.\n .filter((id) => id !== key)\n .map((id) => members.doc(id))\n\n const snapshots = input.heldRow?.exists\n ? [input.heldRow]\n : await input.listRef.firestore.getAll(canonicalRef, ...legacyRefs)\n const existing = snapshots.find((snapshot) => snapshot.exists)\n const target = existing?.ref ?? canonicalRef\n\n if (\n existing &&\n readMarketingBasis(existing.data() as Record<string, unknown>, input.group)\n .basis === 'declined'\n ) {\n return { enrolled: false, refusal: 'declined' }\n }\n\n /*\n * ONE value from the two ways a caller may state a basis.\n *\n * `marketingConsent: true` is a capture surface saying \"a box was ticked\n * just now\", which is `contact-opt-in` recorded at this moment with nobody\n * asserting it. Normalizing here rather than branching at the write is what\n * keeps the consent fields to a single writer — two branches stamping\n * overlapping subsets of them is how a row comes to carry a basis with no\n * timestamp, or a timestamp with no basis.\n */\n const consent: ListMemberConsent | null =\n input.consent ??\n (input.marketingConsent\n ? { basis: 'contact-opt-in', atMs: Date.now() }\n : null)\n\n /*\n * The name the row will hold after this write — the caller's, else the one\n * it already carries — because the search tokens are the address's and\n * that name's, and a re-enrollment without a name keeps the stored one.\n */\n const name = input.name || (existing?.get('name') as string | undefined) || null\n const fields: Record<string, unknown> = {\n email,\n /*\n * `name` and `addedAt` are on EVERY row, because the members table\n * orders its query by them (AGL-3680) and `orderBy` drops a document\n * that lacks the field: the caller's name, else the stored one, else\n * `null`. A caller that says nothing never clears a stored name.\n */\n ...(input.name\n ? { name: input.name }\n : existing?.get('name') !== undefined\n ? {}\n : { name: null }),\n searchTokens: listMemberSearchTokens(email, name),\n source: input.source,\n /*\n * `via` is on every row, so the table's How filter can ask for it\n * (AGL-3321): the caller's, else `manual` on a row that has none — what\n * an absent `via` has always meant. A caller that says nothing never\n * moves a stored one.\n */\n ...(input.via\n ? { via: input.via }\n : existing?.get('via')\n ? {}\n : { via: 'manual' }),\n /*\n * Written only when the caller has a basis, and never unwritten.\n *\n * A merge that stamped `marketingConsent: false` on the omitted case\n * would erase a basis this person gave on an earlier enrollment, and a\n * withdrawn consent is not the same event as a re-enrollment that\n * happened to carry no checkbox. Withdrawal has its own path — the\n * unsubscribe link and the suppression list.\n *\n * `marketingConsentAtMs` moves with each fresh basis on purpose: the\n * question a consent record answers is when the person last said yes.\n *\n * The `marketingConsent` family rather than the `consent*` names\n * `docs/specs/email-overhaul.md` §3d sketched: `readMarketingBasis` is\n * the shipped reader and it reads these, so a second vocabulary here\n * would be a basis the send-time join cannot see. The two new fields\n * are attribution ON that field — they say why the person is mailable,\n * never whether — so nothing about the send decision moves into them.\n *\n * Written UNDER the enrolling GROUP, through the one writer helper. A\n * list lives on the org and every site in it can mail one, so a basis\n * written at the top of this row would enroll a person into one\n * client's newsletter and make them mailable by all of them. A group of\n * one — the default — is that client and nobody else.\n *\n * `marketingConsentByUid` is written on EVERY basis, `null` for a\n * pass-through. Leaving it absent would let a real opt-in that\n * supersedes an earlier attestation inherit the attesting account, and\n * a row reading \"this account vouched for them\" when the person ticked\n * a box themselves is a false attribution in the one direction a\n * compliance answer cannot afford.\n *\n * `marketingConsentReason` follows the same rule for the same reason:\n * always written, `''` for a pass-through, so a later real opt-in\n * cannot inherit the sentence an earlier import wrote about where the\n * merchant said the address came from.\n *\n * WHICH sites the basis covers is `membershipConsentFields`' to say,\n * and it never re-derives a grant from the group as it stands now.\n */\n ...(consent ? membershipConsentFields(input, consent) : {}),\n ...(existing\n ? // A legacy row that predates `addedAt` joined when it was created:\n // its document's create time, the date it has always meant.\n existing.get('addedAt') === undefined && existing.createTime\n ? { addedAt: existing.createTime }\n : {}\n : {\n addedAt: FieldValue.serverTimestamp(),\n [CAPTURED_BY_HOST_FIELD]: [input.group.hostId],\n }),\n }\n\n /*\n * Compared against what this write would actually send, field by field,\n * rather than against a list of what a sweep tends to change: a field added\n * to the write above is covered here the day it is added, and any doubt\n * (a Timestamp, a nested basis) reads as a difference and writes.\n */\n if (\n input.heldRow &&\n existing &&\n Object.entries(fields).every(([field, value]) =>\n isDeepStrictEqual(existing.get(field), value),\n )\n ) {\n return {\n enrolled: true,\n memberId: target.id,\n adopted: target.id !== key,\n created: false,\n unchanged: true,\n }\n }\n\n await target.set(fields, { merge: true })\n\n /*\n * A person NEW to the list has their address's domain checked after the\n * response (AGL-3328), so the CRM record they are reads \"Would bounce\"\n * when it takes no mail. The list's owner names whose records those are:\n * an organization's list its own, a site's list the site's organization.\n */\n if (!existing) {\n const owner = input.listRef.parent?.parent\n const ownerKind = owner?.parent?.id\n scheduleCapturedEmailCheck({\n orgId: ownerKind === 'orgs' ? owner?.id : null,\n hostId: ownerKind === 'hosts' ? owner?.id : input.group?.hostId,\n email,\n })\n }\n\n return {\n enrolled: true,\n memberId: target.id,\n adopted: target.id !== key,\n created: !existing,\n }\n}\n\n/**\n * The consent fields one enrollment writes: the basis, its attribution, and\n * the sites it covers (AGL-3320).\n *\n * Three ways in, and the sites follow from which one it is:\n *\n * - a PASS-THROUGH with the person's {@link EnrollListMemberInput.grantEntries}\n * writes those sites and no others, each grant with its own moment and\n * the disclosure it was given under;\n * - a capture's checkbox pools over the group only when its surface sent\n * back the group's current disclosure key — `consentGroupForGrant`;\n * - everything else, an attestation among them, is the enrolling site's\n * alone.\n *\n * The attribution is the membership's own on every entry, the pass-through's\n * included, for the reason the write explains: an entry that kept an earlier\n * attestation's account under a person's own opt-in would be a false claim\n * about who vouched for them.\n */\nfunction membershipConsentFields(\n input: EnrollListMemberInput,\n consent: ListMemberConsent,\n): Record<string, unknown> {\n const attribution = {\n [MARKETING_CONSENT_BASIS_FIELD]: consent.basis,\n marketingConsentByUid: consent.byUid ?? null,\n marketingConsentReason: consent.reason ?? '',\n }\n const carried =\n consent.basis === 'contact-opt-in'\n ? Object.entries(input.grantEntries ?? {})\n : []\n if (carried.length) {\n return {\n [MARKETING_CONSENT_BY_HOST_FIELD]: Object.fromEntries(\n carried.map(([hostId, entry]) => [\n hostId,\n {\n ...entry,\n [MARKETING_CONSENT_FIELD]: true,\n // The grant's own moment; the pass-through's only when the\n // person's record never stamped one, as the basis itself falls\n // back to now.\n marketingConsentAtMs: entry['marketingConsentAtMs'] ?? consent.atMs,\n ...attribution,\n },\n ]),\n ),\n }\n }\n return marketingConsentFieldsForGroup(\n consentGroupForGrant(input.group, input.disclosedConsentGroup),\n consent.atMs,\n attribution,\n )\n}\n"],"names":["FieldValue","normalizeContactEmail","personKey","CAPTURED_BY_HOST_FIELD","MARKETING_CONSENT_BASIS_FIELD","MARKETING_CONSENT_BY_HOST_FIELD","MARKETING_CONSENT_FIELD","marketingConsentFieldsForGroup","readMarketingBasis","consentGroupForGrant","nameSearchTokens","createHash","createHmac","isDeepStrictEqual","emailSearchTokens","scheduleCapturedEmailCheck","listMemberSearchTokens","email","name","Set","legacyListMemberIds","normalizedEmail","update","digest","slice","listMemberDocIds","normalized","key","filter","id","enrollListMember","input","enrolled","refusal","members","listRef","collection","canonicalRef","doc","legacyRefs","map","snapshots","heldRow","exists","firestore","getAll","existing","find","snapshot","target","ref","data","group","basis","consent","marketingConsent","atMs","Date","now","get","fields","undefined","searchTokens","source","via","membershipConsentFields","createTime","addedAt","serverTimestamp","hostId","Object","entries","every","field","value","memberId","adopted","created","unchanged","set","merge","owner","parent","ownerKind","orgId","attribution","marketingConsentByUid","byUid","marketingConsentReason","reason","carried","grantEntries","length","fromEntries","entry","marketingConsentAtMs","disclosedConsentGroup"],"mappings":"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"}
|
|
@@ -230,7 +230,12 @@ export interface DrainIngestResult {
|
|
|
230
230
|
* `{rate: 0}` rule with no path prefix — literally "drop everything" — changed
|
|
231
231
|
* delivery volume from 31 to 32 per five minutes. The whole `schemas.log`
|
|
232
232
|
* filter block is accepted by the API, echoed back on `GET`, and never
|
|
233
|
-
* applied. Separation is
|
|
233
|
+
* applied. Separation is what stops the loop.
|
|
234
|
+
*
|
|
235
|
+
* The drain's newer top-level OData `filter` IS applied, and is what keeps the
|
|
236
|
+
* delivery volume down (AGL-4121). It cannot replace the gate here: Vercel's
|
|
237
|
+
* `log/statusCode` reads only `proxy.statusCode`, so the drains drop what is
|
|
238
|
+
* proven healthy and this module still decides what is a server error.
|
|
234
239
|
*
|
|
235
240
|
* The default keeps every existing caller on the Firebase admin credential.
|
|
236
241
|
* A receiver hosted off Vercel (Cloud Run in `aglyn-main`) passes its own
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/vercel-log-drain.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 Vercel log-drain receiver (AGL-1921, third and last arm).\n *\n * ## Why this arm exists at all\n *\n * The two arms already shipped both start from OUR code running. The\n * `onRequestError` hook (`reportServerError`) sees a render or route handler\n * throw; `/api/health/server-errors` grades the markers that hook writes.\n * Neither can see:\n *\n * - an error that kills the process before the hook runs,\n * - a platform-level 5xx that never reaches our code at all — a function\n * timeout, an OOM kill, a cold-start 502,\n * - anything thrown in the edge runtime.\n *\n * A log drain sees all three, because Vercel emits the request log whether or\n * not our code got far enough to have an opinion. That is why this is the arm\n * that closes the issue rather than a fourth partial view.\n *\n * ## The shape of the risk, and what each rule below buys\n *\n * A drain streams EVERY request log for both projects. The account's whole\n * monitoring budget is about $20/month, so the dangerous failure mode here is\n * not missing an error — it is faithfully forwarding a million healthy 200s\n * into Cloud Logging and getting a bill for it. Hence, in order:\n *\n * 1. **Signature first, fail closed.** HMAC-SHA1 of the RAW body keyed by the\n * drain secret, timing-safe compared. Unsigned means unwritten, always.\n * 2. **Filter before writing.** `isServerErrorEntry` is the cost gate: an\n * entry that is not a server error costs one predicate and zero writes.\n * 3. **Never our own route.** See `RECEIVER_ROUTE_PATH`.\n * 4. **Never a deliberate 5xx.** A 503 is how the lockdown notice and every\n * health contract SAY something, and forwarding a verdict as a fault makes\n * the stream unreadable: measured over the 48 hours to 2026-09-09, 229 of\n * the 251 entries in this log were `/api/health/*` reporting degraded and\n * 22 were the only real outage in the window. See `isLockdownNoticeEntry`\n * and `isHealthContractEntry` (AGL-2709).\n * 5. **A per-instance budget per window**, with suppression REPORTED. A\n * monitoring path that hides its own lossiness is the bug shape this repo\n * keeps rediscovering.\n *\n * ## Where it writes, and why not next door\n *\n * `vercel-runtime`, DELIBERATELY NOT `server-errors`. That log is the\n * `onRequestError` hook's, and the alert policy\n * `projects/aglyn-main/alertPolicies/11610705614308437855` keys on it. A 500\n * our code threw is seen by BOTH arms, so merging the streams would count one\n * incident twice and make triage start by asking which arm saw it. The same\n * separation `client-errors` and `server-errors` already keep, for the same\n * reason.\n *\n * The entries carry a real `httpRequest.status`, which is what makes the\n * policy AGL-1921 originally specified — a log filter on logName matching\n * \"vercel\" and httpRequest.status at or above 500 — expressible without a\n * log-based metric on a jsonPayload field first.\n */\n\n/**\n * LAZY, and that is load-bearing rather than stylistic (AGL-1921, 2026-08-26).\n *\n * `client-error-report` reaches `firebase-admin`. A static import here would\n * pull the whole SDK into anything that bundles this module — including the\n * Cloud Run receiver, whose entire reason for existing is to run this gate\n * OFF Vercel with nothing but `node:crypto` and a metadata-server token. That\n * receiver always supplies its own {@link DrainIngestOptions.target}, so this\n * path is never reached there and the SDK is never resolved.\n *\n * Called through `defaultLoggingTarget` below, never at module scope.\n */\nasync function defaultLoggingTarget(): Promise<{\n token: string\n projectId: string\n} | null> {\n const { beaconLoggingTarget } = await import('./client-error-report')\n return beaconLoggingTarget()\n}\n\n/**\n * The log id the drain writes to. Contains \"vercel\" on purpose: the alert\n * policy `projects/aglyn-main/alertPolicies/14031689508473384486` matches\n * `logName=~\"vercel\"`, so the name is load-bearing. Renaming this log without\n * repointing that policy silences the platform-5xx arm.\n */\nexport const VERCEL_RUNTIME_LOG_ID = 'vercel-runtime'\n\n/** The env var holding the drain's signature secret. Fails closed if unset. */\nexport const DRAIN_SECRET_ENV = 'VERCEL_LOG_DRAIN_SECRET'\n\n/**\n * The receiver's own path — the FEEDBACK-LOOP GUARD (requirement 5).\n *\n * ⚠️ HISTORICAL, AND KEPT AS DEFENCE IN DEPTH (2026-08-26). The receiver USED\n * to run on `aglyn-console`, whose logs the console drain collects, and the\n * two cuts below were the answer to one receiver 500 draining back in.\n *\n * They were not enough, and the reason is worth stating plainly because the\n * docstring that used to live here got it wrong: **both cuts are about the\n * WRITE, and the cost was the DELIVERY.** Nothing inside a receiver can\n * decline to be requested, and every delivery POST is itself a request that\n * produces a log the same drain then delivers. Measured at 695K invocations\n * in nine hours. Vercel's drain `sampling` rules are not a fix either — a\n * single `{rate: 0}` rule with no path prefix moved delivery volume from 31\n * to 32 per five minutes, i.e. the whole `schemas.log` filter block is stored\n * and never applied.\n *\n * The receiver now lives OFF Vercel, at `cloud/log-drain` on Cloud Run, which\n * no drain watches — so the loop is structurally impossible rather than\n * filtered against. These cuts stay because they cost nothing and they are\n * the backstop if anyone ever mounts this gate on a Vercel route again.\n *\n * Two structural cuts, not one:\n *\n * a. Every entry whose path is this route is dropped before the 5xx filter —\n * so even the receiver's OWN 500s can never be forwarded, by anything, at\n * any budget. It is not \"we try not to error\"; it is that its errors are\n * unforwardable.\n * b. Every line this module logs about itself is `console.warn`, i.e. Vercel\n * `level: \"warning\"`, and the filter forwards only 5xx and `fatal`. A\n * suppression summary drained back in is therefore dropped a second time,\n * on a different property, by a different rule.\n *\n * Matched as a PREFIX so `/api/log-drain`, a future `/api/log-drain/test` and\n * the query-bearing `proxy.path` form all fall on the same side of it.\n */\nexport const RECEIVER_ROUTE_PATH = '/api/log-drain'\n\n/**\n * The lockdown notice route — a route whose 503 is the FEATURE, not a fault.\n *\n * `apps/tenant/app/api/locked/route.ts` answers every request with a real 503\n * carrying `Retry-After`, and the middleware rewrites every path of a locked\n * or bandwidth-capped host to it. That status is deliberate: a takedown\n * notice answering 200 would tell crawlers and uptime checks the site is\n * fine, which is the whole reason the notice is a route handler rather than a\n * page.\n *\n * Forwarded, it is indistinguishable from an outage. One suspended host being\n * crawled emits a 5xx per request, forever, into the arm whose only consumer\n * is an alert policy — so the policy fires on a working feature and the next\n * real incident arrives in a stream that is already red.\n *\n * Matched EXACTLY, not as a prefix: the notice is one path, and a future\n * `/api/locked/*` would be a different route with no such guarantee about its\n * status.\n */\nexport const LOCKDOWN_NOTICE_ROUTE_PATH = '/api/locked'\n\n/**\n * Per-instance write budget, mirroring `reportServerError`'s (same file\n * neighbourhood, same rationale): the failure being watched is a SPIKE, and a\n * spike is when an unbounded forwarder turns one incident into a second one\n * denominated in dollars. 60 entries a minute per instance is far more than\n * any threshold policy needs to cross — the shape of the spike survives; the\n * bill does not follow it.\n */\nconst DRAIN_BUDGET_PER_WINDOW = 60\nconst DRAIN_WINDOW_MS = 60_000\nlet drainWindowStartedAt = 0\nlet drainWritten = 0\nlet drainSuppressed = 0\n\nconst MAX_MESSAGE = 1_024\nconst WRITE_TIMEOUT_MS = 4_000\n\n/** Reset the budget counters. Test seam only — never called in production. */\nexport function resetDrainBudgetForTests(): void {\n drainWindowStartedAt = 0\n drainWritten = 0\n drainSuppressed = 0\n}\n\n/**\n * One log entry as a Vercel drain delivers it. Only the fields this receiver\n * reads are named; the wire object carries many more (client IP, user agent,\n * referer, the query-bearing `proxy.path`) which are deliberately NOT in this\n * type, because a field that has no name here cannot be forwarded by accident.\n */\nexport interface VercelDrainEntry {\n id?: string\n deploymentId?: string\n projectId?: string\n projectName?: string\n source?: string\n host?: string\n timestamp?: number\n level?: string\n type?: string\n message?: string\n path?: string\n entrypoint?: string\n requestId?: string\n statusCode?: number\n environment?: string\n executionRegion?: string\n proxy?: {\n method?: string\n statusCode?: number\n path?: string\n pathType?: string\n }\n}\n\nfunction clampString(value: unknown, max: number): string {\n return typeof value === 'string' ? value.slice(0, max) : ''\n}\n\n/**\n * The entries in one delivery, in either format Vercel will send.\n *\n * `json` delivers an array (and, per the reference's own example, sometimes a\n * newline-separated sequence of objects); `ndjson` delivers one object per\n * line. Parsing both means the drain's `deliveryFormat` can be changed in the\n * dashboard without a deploy, and a malformed line is skipped rather than\n * failing the whole delivery — Vercel disables a drain that errors too often,\n * so a receiver that 500s on one bad line silences itself.\n */\nexport function parseDrainPayload(rawBody: string): VercelDrainEntry[] {\n const body = rawBody.trim()\n if (!body) return []\n try {\n const parsed: unknown = JSON.parse(body)\n if (Array.isArray(parsed)) {\n return parsed.filter(\n (entry): entry is VercelDrainEntry =>\n Boolean(entry) && typeof entry === 'object',\n )\n }\n if (parsed && typeof parsed === 'object')\n return [parsed as VercelDrainEntry]\n } catch {\n // Not a single JSON document — fall through to line-by-line.\n }\n const entries: VercelDrainEntry[] = []\n for (const line of body.split('\\n')) {\n const trimmed = line.trim()\n if (!trimmed) continue\n try {\n const parsed: unknown = JSON.parse(trimmed)\n if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n entries.push(parsed as VercelDrainEntry)\n }\n } catch {\n // One unreadable line never fails a delivery.\n }\n }\n return entries\n}\n\n/** Does this entry describe the receiver's own route? See RECEIVER_ROUTE_PATH. */\nexport function isReceiverEntry(entry: VercelDrainEntry): boolean {\n const paths = [entry.path, entry.proxy?.path]\n return paths.some((path) => {\n if (typeof path !== 'string') return false\n // `proxy.path` carries the query string; compare the path part only.\n const [pathname] = path.split('?')\n return (\n pathname === RECEIVER_ROUTE_PATH ||\n pathname.startsWith(`${RECEIVER_ROUTE_PATH}/`)\n )\n })\n}\n\n/**\n * Is this the lockdown notice serving its deliberate 503? See\n * {@link LOCKDOWN_NOTICE_ROUTE_PATH}.\n *\n * Narrow on purpose — the route being exempt must not make the route\n * unwatchable. Only a clean 503 is excused: a 500 the handler threw, the\n * `statusCode -1` of a crashed lambda, and a `fatal` line all still forward,\n * because those say the notice itself is broken and a locked host is then\n * serving nothing at all.\n */\nexport function isLockdownNoticeEntry(entry: VercelDrainEntry): boolean {\n if (entry.level === 'fatal' || entry.type === 'fatal') return false\n const statuses = [entry.statusCode, entry.proxy?.statusCode].filter(\n (status): status is number => typeof status === 'number',\n )\n if (!statuses.length || statuses.some((status) => status !== 503))\n return false\n return [entry.path, entry.proxy?.path].some((path) => {\n if (typeof path !== 'string') return false\n // `proxy.path` carries the query string; compare the path part only.\n const [pathname] = path.split('?')\n return pathname === LOCKDOWN_NOTICE_ROUTE_PATH\n })\n}\n\n/**\n * The health contract's routes, whose 503 is a VERDICT and not a fault.\n *\n * Prefix, not an exact path: every endpoint under it speaks the same contract\n * — `healthHttpStatus` answers 200 while a check reports ok and 503 the moment\n * it reports degraded — so `/api/health`, `/api/health/crons` and\n * `/api/health/render/site` are all the same case.\n */\nexport const HEALTH_ROUTE_PREFIX = '/api/health'\n\n/**\n * Is this a health endpoint answering 503 because it is doing its job?\n * (AGL-2709)\n *\n * ⚠️ THE STREAM WAS 91% THIS. Measured over the 48 hours to 2026-09-09, the\n * drain forwarded 251 entries into `vercel-runtime`. **229 were `/api/health/*`\n * answering 503** — `crons` 113, `funnel` 73, `server-errors` 18 — and 22 were\n * the AGL-2708 outage, the only real server errors in the window. The policy\n * on that log (`logName=~\"vercel\" AND severity>=ERROR`, one notification an\n * hour) therefore mails about a working health check for as long as any\n * subsystem is degraded: `/api/health/crons` was CORRECTLY reporting a broken\n * job for six hours on 2026-09-07, which is six hours of \"server errors\" mail\n * arriving in the same inbox that then had to notice 04:02 on 2026-09-09.\n *\n * Excusing it removes a DUPLICATE, not a signal, and the reason is structural\n * rather than a judgement call: every `/api/health/*` route both apps ship has\n * a monitor reading it, and `evaluateSubsystemReaders` fails the build if one\n * ever does not. The 503 is already on the uptime probe's board, in an\n * UptimeRobot monitor and on `docs.aglyn.com/status`, said in a body that\n * names WHICH check failed — which the drain entry never could.\n *\n * Narrow in exactly the same three ways as {@link isLockdownNoticeEntry}, and\n * each one is load-bearing:\n *\n * - a clean 503 only. A 500 the handler threw means the health route itself\n * is broken, and a check that cannot answer must never look calm;\n * - never a `fatal` line, which is process death rather than a verdict;\n * - never `statusCode -1`, the crashed-lambda sentinel, which is not 503 and\n * so fails the status test above.\n */\nexport function isHealthContractEntry(entry: VercelDrainEntry): boolean {\n if (entry.level === 'fatal' || entry.type === 'fatal') return false\n const statuses = [entry.statusCode, entry.proxy?.statusCode].filter(\n (status): status is number => typeof status === 'number',\n )\n if (!statuses.length || statuses.some((status) => status !== 503))\n return false\n return [entry.path, entry.proxy?.path].some((path) => {\n if (typeof path !== 'string') return false\n // `proxy.path` carries the query string; compare the path part only.\n const [pathname] = path.split('?')\n return (\n pathname === HEALTH_ROUTE_PREFIX ||\n pathname.startsWith(`${HEALTH_ROUTE_PREFIX}/`)\n )\n })\n}\n\n/**\n * THE COST GATE (requirement 3). Everything false here is dropped unwritten.\n *\n * What counts as a server error:\n *\n * - `statusCode >= 500` or `proxy.statusCode >= 500` — the platform 5xx this\n * whole arm exists for, including the ones our code never saw.\n * - `statusCode === -1` — documented as \"no response returned and the lambda\n * crashed\". The OOM/hard-crash case, and the single most important entry\n * shape the `onRequestError` hook is structurally unable to produce.\n * - `level === 'fatal'` or `type === 'fatal'` — the edge-runtime and\n * process-death shape, which may carry no status at all.\n *\n * What deliberately does NOT count:\n *\n * - `level === 'error'`. That is any `console.error`, including the fail-soft\n * warn/error lines the beacons themselves write, and forwarding it would\n * mean paying per line for a stream the `onRequestError` hook already\n * covers properly. If an errored request matters, it has a status.\n * - `proxy.statusCode === -1`. Same sentinel, opposite meaning: on the proxy\n * object it documents a BACKGROUND REVALIDATION, which is a healthy ISR\n * refresh. Reading it as a crash would forward a steady trickle of normal\n * traffic forever — the exact bill this gate exists to prevent.\n */\nexport function isServerErrorEntry(entry: VercelDrainEntry): boolean {\n if (typeof entry.statusCode === 'number') {\n if (entry.statusCode >= 500) return true\n if (entry.statusCode === -1) return true\n }\n const proxyStatus = entry.proxy?.statusCode\n if (typeof proxyStatus === 'number' && proxyStatus >= 500) return true\n if (entry.level === 'fatal' || entry.type === 'fatal') return true\n return false\n}\n\n/**\n * Everything above, in the order the cost argument requires.\n * Exported so the tests can assert the gate without a transport.\n */\nexport function selectForwardableEntries(\n entries: readonly VercelDrainEntry[],\n): VercelDrainEntry[] {\n return entries.filter(\n (entry) =>\n !isReceiverEntry(entry) &&\n !isLockdownNoticeEntry(entry) &&\n !isHealthContractEntry(entry) &&\n isServerErrorEntry(entry),\n )\n}\n\n/**\n * One Cloud Logging entry, carrying ONLY fields that are already inside the\n * envelope the shipped beacons send (requirement 8).\n *\n * Explicitly absent, and each for a reason:\n * `proxy.path` (query string — the AGL-1538 boundary is origin+pathname and\n * this is the same boundary), `proxy.clientIp` and `proxy.userAgent` and\n * `proxy.referer` (visitor identity; also why Vercel's own IP-visibility\n * toggle exists), request or response bodies (never delivered, never wanted).\n * `path` IS forwarded because Vercel documents it as the function or dynamic\n * path — the route PATTERN, which is what you group and alert on anyway, and\n * exactly what `reportServerError` already sends as `route`.\n */\nfunction toLogEntry(entry: VercelDrainEntry): Record<string, unknown> {\n const status =\n typeof entry.statusCode === 'number' && entry.statusCode >= 0\n ? entry.statusCode\n : typeof entry.proxy?.statusCode === 'number' &&\n entry.proxy.statusCode >= 0\n ? entry.proxy.statusCode\n : undefined\n return {\n severity: 'ERROR',\n // The structured field the AGL-1921 policy matches on. A jsonPayload key\n // would need a log-based metric first; this one is queryable as shipped.\n httpRequest: {\n requestMethod: clampString(entry.proxy?.method, 16) || undefined,\n status,\n },\n jsonPayload: {\n // No ReportedErrorEvent `@type`: these are NOT ingested into Error\n // Reporting. A function timeout has no stack, would group as one giant\n // bucket, and would drown the real grouped errors the hook reports.\n source: clampString(entry.source, 32) || undefined,\n level: clampString(entry.level, 16) || undefined,\n type: clampString(entry.type, 32) || undefined,\n route: clampString(entry.path, 512) || undefined,\n entrypoint: clampString(entry.entrypoint, 256) || undefined,\n host: clampString(entry.host, 256) || undefined,\n environment: clampString(entry.environment, 32) || undefined,\n region: clampString(entry.executionRegion, 32) || undefined,\n project: clampString(entry.projectName, 64) || undefined,\n projectId: clampString(entry.projectId, 64) || undefined,\n deploymentId: clampString(entry.deploymentId, 64) || undefined,\n requestId: clampString(entry.requestId, 64) || undefined,\n logId: clampString(entry.id, 64) || undefined,\n statusCode:\n typeof entry.statusCode === 'number' ? entry.statusCode : undefined,\n proxyStatusCode:\n typeof entry.proxy?.statusCode === 'number'\n ? entry.proxy.statusCode\n : undefined,\n // Clamped like the beacon's own message. This is where \"Task timed out\n // after 10.01 seconds\" lives, which is the whole triage value of the\n // platform-5xx case.\n message: clampString(entry.message, MAX_MESSAGE) || undefined,\n },\n }\n}\n\n/** What one delivery did, for the response body, the tests and the caller. */\nexport interface DrainIngestResult {\n /** Entries in the delivery. */\n received: number\n /** Entries that passed the receiver-path and 5xx gates. */\n matched: number\n /** Entries actually written to Cloud Logging. */\n forwarded: number\n /** Entries dropped by the per-window budget — REPORTED, never silent. */\n suppressed: number\n /** Set when nothing could be written at all; a stable code, never a message. */\n code?: 'no-credential' | 'transport' | `http-${number}`\n}\n\n/**\n * Where the write goes, and under whose credential.\n *\n * Injectable because the receiver has to be able to run somewhere that is NOT\n * a Vercel project this drain watches — a delivery POST is a request to\n * whatever hosts it, and a request produces a log the same drain then\n * delivers, which is the AGL-1921 feedback loop. Vercel's drain `sampling`\n * rules look like the answer and are NOT: measured 2026-08-26, a single\n * `{rate: 0}` rule with no path prefix — literally \"drop everything\" — changed\n * delivery volume from 31 to 32 per five minutes. The whole `schemas.log`\n * filter block is accepted by the API, echoed back on `GET`, and never\n * applied. Separation is the only control that works.\n *\n * The default keeps every existing caller on the Firebase admin credential.\n * A receiver hosted off Vercel (Cloud Run in `aglyn-main`) passes its own\n * resolver instead and never imports `firebase-admin` at all, which is what\n * lets this module be bundled for it without dragging the SDK along.\n */\nexport interface DrainIngestOptions {\n /**\n * Resolve the Cloud Logging bearer token and project. Returning `null`\n * means \"no credential\" and the delivery is dropped, reported, and answered\n * 200 — never an error, because Vercel disables a drain whose endpoint\n * fails often enough.\n */\n target?: () => Promise<{ token: string; projectId: string } | null>\n}\n\n/**\n * Ingest ONE verified delivery: filter, budget, then a single batched write.\n *\n * Never throws. Vercel disables a drain whose endpoint fails often enough, so\n * a receiver that propagated a Logging outage would end by turning itself off\n * during the incident it exists to report.\n */\nexport async function ingestDrainDelivery(\n entries: readonly VercelDrainEntry[],\n options?: DrainIngestOptions,\n): Promise<DrainIngestResult> {\n const received = entries.length\n const matched = selectForwardableEntries(entries)\n const result: DrainIngestResult = {\n received,\n matched: matched.length,\n forwarded: 0,\n suppressed: 0,\n }\n if (!matched.length) return result\n\n const now = Date.now()\n if (now - drainWindowStartedAt >= DRAIN_WINDOW_MS) {\n if (drainSuppressed > 0) {\n // ⚠️ The lossiness is REPORTED. `level: \"warning\"`, so guard (b) in\n // RECEIVER_ROUTE_PATH keeps this line from ever draining back in.\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n suppressed: drainSuppressed,\n written: drainWritten,\n windowMs: DRAIN_WINDOW_MS,\n }),\n )\n }\n drainWindowStartedAt = now\n drainWritten = 0\n drainSuppressed = 0\n }\n\n const room = Math.max(0, DRAIN_BUDGET_PER_WINDOW - drainWritten)\n const writable = matched.slice(0, room)\n const suppressed = matched.length - writable.length\n if (suppressed > 0) drainSuppressed += suppressed\n result.suppressed = suppressed\n if (!writable.length) return result\n\n const target = await (options?.target ?? defaultLoggingTarget)()\n if (!target) {\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n drop: writable.length,\n reason: 'no-credential',\n }),\n )\n result.code = 'no-credential'\n return result\n }\n\n try {\n const response = await fetch(\n 'https://logging.googleapis.com/v2/entries:write',\n {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${target.token}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n logName: `projects/${target.projectId}/logs/${VERCEL_RUNTIME_LOG_ID}`,\n resource: { type: 'global' },\n entries: writable.map(toLogEntry),\n }),\n signal: AbortSignal.timeout(WRITE_TIMEOUT_MS),\n },\n )\n if (!response.ok) {\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n status: response.status,\n drop: writable.length,\n }),\n )\n result.code = `http-${response.status}`\n return result\n }\n drainWritten += writable.length\n result.forwarded = writable.length\n return result\n } catch (error) {\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n transport: String(error).slice(0, 200),\n }),\n )\n result.code = 'transport'\n return result\n }\n}\n"],"names":["defaultLoggingTarget","beaconLoggingTarget","VERCEL_RUNTIME_LOG_ID","DRAIN_SECRET_ENV","RECEIVER_ROUTE_PATH","LOCKDOWN_NOTICE_ROUTE_PATH","DRAIN_BUDGET_PER_WINDOW","DRAIN_WINDOW_MS","drainWindowStartedAt","drainWritten","drainSuppressed","MAX_MESSAGE","WRITE_TIMEOUT_MS","resetDrainBudgetForTests","clampString","value","max","slice","parseDrainPayload","rawBody","body","trim","parsed","JSON","parse","Array","isArray","filter","entry","Boolean","entries","line","split","trimmed","push","isReceiverEntry","paths","path","proxy","some","pathname","startsWith","isLockdownNoticeEntry","level","type","statuses","statusCode","status","length","HEALTH_ROUTE_PREFIX","isHealthContractEntry","isServerErrorEntry","proxyStatus","selectForwardableEntries","toLogEntry","undefined","severity","httpRequest","requestMethod","method","jsonPayload","source","route","entrypoint","host","environment","region","executionRegion","project","projectName","projectId","deploymentId","requestId","logId","id","proxyStatusCode","message","ingestDrainDelivery","options","received","matched","result","forwarded","suppressed","now","Date","console","warn","stringify","tag","written","windowMs","room","Math","writable","target","drop","reason","code","response","fetch","headers","Authorization","token","logName","resource","map","signal","AbortSignal","timeout","ok","error","transport","String"],"mappings":"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"}
|
|
1
|
+
{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/vercel-log-drain.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 Vercel log-drain receiver (AGL-1921, third and last arm).\n *\n * ## Why this arm exists at all\n *\n * The two arms already shipped both start from OUR code running. The\n * `onRequestError` hook (`reportServerError`) sees a render or route handler\n * throw; `/api/health/server-errors` grades the markers that hook writes.\n * Neither can see:\n *\n * - an error that kills the process before the hook runs,\n * - a platform-level 5xx that never reaches our code at all — a function\n * timeout, an OOM kill, a cold-start 502,\n * - anything thrown in the edge runtime.\n *\n * A log drain sees all three, because Vercel emits the request log whether or\n * not our code got far enough to have an opinion. That is why this is the arm\n * that closes the issue rather than a fourth partial view.\n *\n * ## The shape of the risk, and what each rule below buys\n *\n * A drain streams EVERY request log for both projects. The account's whole\n * monitoring budget is about $20/month, so the dangerous failure mode here is\n * not missing an error — it is faithfully forwarding a million healthy 200s\n * into Cloud Logging and getting a bill for it. Hence, in order:\n *\n * 1. **Signature first, fail closed.** HMAC-SHA1 of the RAW body keyed by the\n * drain secret, timing-safe compared. Unsigned means unwritten, always.\n * 2. **Filter before writing.** `isServerErrorEntry` is the cost gate: an\n * entry that is not a server error costs one predicate and zero writes.\n * 3. **Never our own route.** See `RECEIVER_ROUTE_PATH`.\n * 4. **Never a deliberate 5xx.** A 503 is how the lockdown notice and every\n * health contract SAY something, and forwarding a verdict as a fault makes\n * the stream unreadable: measured over the 48 hours to 2026-09-09, 229 of\n * the 251 entries in this log were `/api/health/*` reporting degraded and\n * 22 were the only real outage in the window. See `isLockdownNoticeEntry`\n * and `isHealthContractEntry` (AGL-2709).\n * 5. **A per-instance budget per window**, with suppression REPORTED. A\n * monitoring path that hides its own lossiness is the bug shape this repo\n * keeps rediscovering.\n *\n * ## Where it writes, and why not next door\n *\n * `vercel-runtime`, DELIBERATELY NOT `server-errors`. That log is the\n * `onRequestError` hook's, and the alert policy\n * `projects/aglyn-main/alertPolicies/11610705614308437855` keys on it. A 500\n * our code threw is seen by BOTH arms, so merging the streams would count one\n * incident twice and make triage start by asking which arm saw it. The same\n * separation `client-errors` and `server-errors` already keep, for the same\n * reason.\n *\n * The entries carry a real `httpRequest.status`, which is what makes the\n * policy AGL-1921 originally specified — a log filter on logName matching\n * \"vercel\" and httpRequest.status at or above 500 — expressible without a\n * log-based metric on a jsonPayload field first.\n */\n\n/**\n * LAZY, and that is load-bearing rather than stylistic (AGL-1921, 2026-08-26).\n *\n * `client-error-report` reaches `firebase-admin`. A static import here would\n * pull the whole SDK into anything that bundles this module — including the\n * Cloud Run receiver, whose entire reason for existing is to run this gate\n * OFF Vercel with nothing but `node:crypto` and a metadata-server token. That\n * receiver always supplies its own {@link DrainIngestOptions.target}, so this\n * path is never reached there and the SDK is never resolved.\n *\n * Called through `defaultLoggingTarget` below, never at module scope.\n */\nasync function defaultLoggingTarget(): Promise<{\n token: string\n projectId: string\n} | null> {\n const { beaconLoggingTarget } = await import('./client-error-report')\n return beaconLoggingTarget()\n}\n\n/**\n * The log id the drain writes to. Contains \"vercel\" on purpose: the alert\n * policy `projects/aglyn-main/alertPolicies/14031689508473384486` matches\n * `logName=~\"vercel\"`, so the name is load-bearing. Renaming this log without\n * repointing that policy silences the platform-5xx arm.\n */\nexport const VERCEL_RUNTIME_LOG_ID = 'vercel-runtime'\n\n/** The env var holding the drain's signature secret. Fails closed if unset. */\nexport const DRAIN_SECRET_ENV = 'VERCEL_LOG_DRAIN_SECRET'\n\n/**\n * The receiver's own path — the FEEDBACK-LOOP GUARD (requirement 5).\n *\n * ⚠️ HISTORICAL, AND KEPT AS DEFENCE IN DEPTH (2026-08-26). The receiver USED\n * to run on `aglyn-console`, whose logs the console drain collects, and the\n * two cuts below were the answer to one receiver 500 draining back in.\n *\n * They were not enough, and the reason is worth stating plainly because the\n * docstring that used to live here got it wrong: **both cuts are about the\n * WRITE, and the cost was the DELIVERY.** Nothing inside a receiver can\n * decline to be requested, and every delivery POST is itself a request that\n * produces a log the same drain then delivers. Measured at 695K invocations\n * in nine hours. Vercel's drain `sampling` rules are not a fix either — a\n * single `{rate: 0}` rule with no path prefix moved delivery volume from 31\n * to 32 per five minutes, i.e. the whole `schemas.log` filter block is stored\n * and never applied.\n *\n * The receiver now lives OFF Vercel, at `cloud/log-drain` on Cloud Run, which\n * no drain watches — so the loop is structurally impossible rather than\n * filtered against. These cuts stay because they cost nothing and they are\n * the backstop if anyone ever mounts this gate on a Vercel route again.\n *\n * Two structural cuts, not one:\n *\n * a. Every entry whose path is this route is dropped before the 5xx filter —\n * so even the receiver's OWN 500s can never be forwarded, by anything, at\n * any budget. It is not \"we try not to error\"; it is that its errors are\n * unforwardable.\n * b. Every line this module logs about itself is `console.warn`, i.e. Vercel\n * `level: \"warning\"`, and the filter forwards only 5xx and `fatal`. A\n * suppression summary drained back in is therefore dropped a second time,\n * on a different property, by a different rule.\n *\n * Matched as a PREFIX so `/api/log-drain`, a future `/api/log-drain/test` and\n * the query-bearing `proxy.path` form all fall on the same side of it.\n */\nexport const RECEIVER_ROUTE_PATH = '/api/log-drain'\n\n/**\n * The lockdown notice route — a route whose 503 is the FEATURE, not a fault.\n *\n * `apps/tenant/app/api/locked/route.ts` answers every request with a real 503\n * carrying `Retry-After`, and the middleware rewrites every path of a locked\n * or bandwidth-capped host to it. That status is deliberate: a takedown\n * notice answering 200 would tell crawlers and uptime checks the site is\n * fine, which is the whole reason the notice is a route handler rather than a\n * page.\n *\n * Forwarded, it is indistinguishable from an outage. One suspended host being\n * crawled emits a 5xx per request, forever, into the arm whose only consumer\n * is an alert policy — so the policy fires on a working feature and the next\n * real incident arrives in a stream that is already red.\n *\n * Matched EXACTLY, not as a prefix: the notice is one path, and a future\n * `/api/locked/*` would be a different route with no such guarantee about its\n * status.\n */\nexport const LOCKDOWN_NOTICE_ROUTE_PATH = '/api/locked'\n\n/**\n * Per-instance write budget, mirroring `reportServerError`'s (same file\n * neighbourhood, same rationale): the failure being watched is a SPIKE, and a\n * spike is when an unbounded forwarder turns one incident into a second one\n * denominated in dollars. 60 entries a minute per instance is far more than\n * any threshold policy needs to cross — the shape of the spike survives; the\n * bill does not follow it.\n */\nconst DRAIN_BUDGET_PER_WINDOW = 60\nconst DRAIN_WINDOW_MS = 60_000\nlet drainWindowStartedAt = 0\nlet drainWritten = 0\nlet drainSuppressed = 0\n\nconst MAX_MESSAGE = 1_024\nconst WRITE_TIMEOUT_MS = 4_000\n\n/** Reset the budget counters. Test seam only — never called in production. */\nexport function resetDrainBudgetForTests(): void {\n drainWindowStartedAt = 0\n drainWritten = 0\n drainSuppressed = 0\n}\n\n/**\n * One log entry as a Vercel drain delivers it. Only the fields this receiver\n * reads are named; the wire object carries many more (client IP, user agent,\n * referer, the query-bearing `proxy.path`) which are deliberately NOT in this\n * type, because a field that has no name here cannot be forwarded by accident.\n */\nexport interface VercelDrainEntry {\n id?: string\n deploymentId?: string\n projectId?: string\n projectName?: string\n source?: string\n host?: string\n timestamp?: number\n level?: string\n type?: string\n message?: string\n path?: string\n entrypoint?: string\n requestId?: string\n statusCode?: number\n environment?: string\n executionRegion?: string\n proxy?: {\n method?: string\n statusCode?: number\n path?: string\n pathType?: string\n }\n}\n\nfunction clampString(value: unknown, max: number): string {\n return typeof value === 'string' ? value.slice(0, max) : ''\n}\n\n/**\n * The entries in one delivery, in either format Vercel will send.\n *\n * `json` delivers an array (and, per the reference's own example, sometimes a\n * newline-separated sequence of objects); `ndjson` delivers one object per\n * line. Parsing both means the drain's `deliveryFormat` can be changed in the\n * dashboard without a deploy, and a malformed line is skipped rather than\n * failing the whole delivery — Vercel disables a drain that errors too often,\n * so a receiver that 500s on one bad line silences itself.\n */\nexport function parseDrainPayload(rawBody: string): VercelDrainEntry[] {\n const body = rawBody.trim()\n if (!body) return []\n try {\n const parsed: unknown = JSON.parse(body)\n if (Array.isArray(parsed)) {\n return parsed.filter(\n (entry): entry is VercelDrainEntry =>\n Boolean(entry) && typeof entry === 'object',\n )\n }\n if (parsed && typeof parsed === 'object')\n return [parsed as VercelDrainEntry]\n } catch {\n // Not a single JSON document — fall through to line-by-line.\n }\n const entries: VercelDrainEntry[] = []\n for (const line of body.split('\\n')) {\n const trimmed = line.trim()\n if (!trimmed) continue\n try {\n const parsed: unknown = JSON.parse(trimmed)\n if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n entries.push(parsed as VercelDrainEntry)\n }\n } catch {\n // One unreadable line never fails a delivery.\n }\n }\n return entries\n}\n\n/** Does this entry describe the receiver's own route? See RECEIVER_ROUTE_PATH. */\nexport function isReceiverEntry(entry: VercelDrainEntry): boolean {\n const paths = [entry.path, entry.proxy?.path]\n return paths.some((path) => {\n if (typeof path !== 'string') return false\n // `proxy.path` carries the query string; compare the path part only.\n const [pathname] = path.split('?')\n return (\n pathname === RECEIVER_ROUTE_PATH ||\n pathname.startsWith(`${RECEIVER_ROUTE_PATH}/`)\n )\n })\n}\n\n/**\n * Is this the lockdown notice serving its deliberate 503? See\n * {@link LOCKDOWN_NOTICE_ROUTE_PATH}.\n *\n * Narrow on purpose — the route being exempt must not make the route\n * unwatchable. Only a clean 503 is excused: a 500 the handler threw, the\n * `statusCode -1` of a crashed lambda, and a `fatal` line all still forward,\n * because those say the notice itself is broken and a locked host is then\n * serving nothing at all.\n */\nexport function isLockdownNoticeEntry(entry: VercelDrainEntry): boolean {\n if (entry.level === 'fatal' || entry.type === 'fatal') return false\n const statuses = [entry.statusCode, entry.proxy?.statusCode].filter(\n (status): status is number => typeof status === 'number',\n )\n if (!statuses.length || statuses.some((status) => status !== 503))\n return false\n return [entry.path, entry.proxy?.path].some((path) => {\n if (typeof path !== 'string') return false\n // `proxy.path` carries the query string; compare the path part only.\n const [pathname] = path.split('?')\n return pathname === LOCKDOWN_NOTICE_ROUTE_PATH\n })\n}\n\n/**\n * The health contract's routes, whose 503 is a VERDICT and not a fault.\n *\n * Prefix, not an exact path: every endpoint under it speaks the same contract\n * — `healthHttpStatus` answers 200 while a check reports ok and 503 the moment\n * it reports degraded — so `/api/health`, `/api/health/crons` and\n * `/api/health/render/site` are all the same case.\n */\nexport const HEALTH_ROUTE_PREFIX = '/api/health'\n\n/**\n * Is this a health endpoint answering 503 because it is doing its job?\n * (AGL-2709)\n *\n * ⚠️ THE STREAM WAS 91% THIS. Measured over the 48 hours to 2026-09-09, the\n * drain forwarded 251 entries into `vercel-runtime`. **229 were `/api/health/*`\n * answering 503** — `crons` 113, `funnel` 73, `server-errors` 18 — and 22 were\n * the AGL-2708 outage, the only real server errors in the window. The policy\n * on that log (`logName=~\"vercel\" AND severity>=ERROR`, one notification an\n * hour) therefore mails about a working health check for as long as any\n * subsystem is degraded: `/api/health/crons` was CORRECTLY reporting a broken\n * job for six hours on 2026-09-07, which is six hours of \"server errors\" mail\n * arriving in the same inbox that then had to notice 04:02 on 2026-09-09.\n *\n * Excusing it removes a DUPLICATE, not a signal, and the reason is structural\n * rather than a judgement call: every `/api/health/*` route both apps ship has\n * a monitor reading it, and `evaluateSubsystemReaders` fails the build if one\n * ever does not. The 503 is already on the uptime probe's board, in an\n * UptimeRobot monitor and on `docs.aglyn.com/status`, said in a body that\n * names WHICH check failed — which the drain entry never could.\n *\n * Narrow in exactly the same three ways as {@link isLockdownNoticeEntry}, and\n * each one is load-bearing:\n *\n * - a clean 503 only. A 500 the handler threw means the health route itself\n * is broken, and a check that cannot answer must never look calm;\n * - never a `fatal` line, which is process death rather than a verdict;\n * - never `statusCode -1`, the crashed-lambda sentinel, which is not 503 and\n * so fails the status test above.\n */\nexport function isHealthContractEntry(entry: VercelDrainEntry): boolean {\n if (entry.level === 'fatal' || entry.type === 'fatal') return false\n const statuses = [entry.statusCode, entry.proxy?.statusCode].filter(\n (status): status is number => typeof status === 'number',\n )\n if (!statuses.length || statuses.some((status) => status !== 503))\n return false\n return [entry.path, entry.proxy?.path].some((path) => {\n if (typeof path !== 'string') return false\n // `proxy.path` carries the query string; compare the path part only.\n const [pathname] = path.split('?')\n return (\n pathname === HEALTH_ROUTE_PREFIX ||\n pathname.startsWith(`${HEALTH_ROUTE_PREFIX}/`)\n )\n })\n}\n\n/**\n * THE COST GATE (requirement 3). Everything false here is dropped unwritten.\n *\n * What counts as a server error:\n *\n * - `statusCode >= 500` or `proxy.statusCode >= 500` — the platform 5xx this\n * whole arm exists for, including the ones our code never saw.\n * - `statusCode === -1` — documented as \"no response returned and the lambda\n * crashed\". The OOM/hard-crash case, and the single most important entry\n * shape the `onRequestError` hook is structurally unable to produce.\n * - `level === 'fatal'` or `type === 'fatal'` — the edge-runtime and\n * process-death shape, which may carry no status at all.\n *\n * What deliberately does NOT count:\n *\n * - `level === 'error'`. That is any `console.error`, including the fail-soft\n * warn/error lines the beacons themselves write, and forwarding it would\n * mean paying per line for a stream the `onRequestError` hook already\n * covers properly. If an errored request matters, it has a status.\n * - `proxy.statusCode === -1`. Same sentinel, opposite meaning: on the proxy\n * object it documents a BACKGROUND REVALIDATION, which is a healthy ISR\n * refresh. Reading it as a crash would forward a steady trickle of normal\n * traffic forever — the exact bill this gate exists to prevent.\n */\nexport function isServerErrorEntry(entry: VercelDrainEntry): boolean {\n if (typeof entry.statusCode === 'number') {\n if (entry.statusCode >= 500) return true\n if (entry.statusCode === -1) return true\n }\n const proxyStatus = entry.proxy?.statusCode\n if (typeof proxyStatus === 'number' && proxyStatus >= 500) return true\n if (entry.level === 'fatal' || entry.type === 'fatal') return true\n return false\n}\n\n/**\n * Everything above, in the order the cost argument requires.\n * Exported so the tests can assert the gate without a transport.\n */\nexport function selectForwardableEntries(\n entries: readonly VercelDrainEntry[],\n): VercelDrainEntry[] {\n return entries.filter(\n (entry) =>\n !isReceiverEntry(entry) &&\n !isLockdownNoticeEntry(entry) &&\n !isHealthContractEntry(entry) &&\n isServerErrorEntry(entry),\n )\n}\n\n/**\n * One Cloud Logging entry, carrying ONLY fields that are already inside the\n * envelope the shipped beacons send (requirement 8).\n *\n * Explicitly absent, and each for a reason:\n * `proxy.path` (query string — the AGL-1538 boundary is origin+pathname and\n * this is the same boundary), `proxy.clientIp` and `proxy.userAgent` and\n * `proxy.referer` (visitor identity; also why Vercel's own IP-visibility\n * toggle exists), request or response bodies (never delivered, never wanted).\n * `path` IS forwarded because Vercel documents it as the function or dynamic\n * path — the route PATTERN, which is what you group and alert on anyway, and\n * exactly what `reportServerError` already sends as `route`.\n */\nfunction toLogEntry(entry: VercelDrainEntry): Record<string, unknown> {\n const status =\n typeof entry.statusCode === 'number' && entry.statusCode >= 0\n ? entry.statusCode\n : typeof entry.proxy?.statusCode === 'number' &&\n entry.proxy.statusCode >= 0\n ? entry.proxy.statusCode\n : undefined\n return {\n severity: 'ERROR',\n // The structured field the AGL-1921 policy matches on. A jsonPayload key\n // would need a log-based metric first; this one is queryable as shipped.\n httpRequest: {\n requestMethod: clampString(entry.proxy?.method, 16) || undefined,\n status,\n },\n jsonPayload: {\n // No ReportedErrorEvent `@type`: these are NOT ingested into Error\n // Reporting. A function timeout has no stack, would group as one giant\n // bucket, and would drown the real grouped errors the hook reports.\n source: clampString(entry.source, 32) || undefined,\n level: clampString(entry.level, 16) || undefined,\n type: clampString(entry.type, 32) || undefined,\n route: clampString(entry.path, 512) || undefined,\n entrypoint: clampString(entry.entrypoint, 256) || undefined,\n host: clampString(entry.host, 256) || undefined,\n environment: clampString(entry.environment, 32) || undefined,\n region: clampString(entry.executionRegion, 32) || undefined,\n project: clampString(entry.projectName, 64) || undefined,\n projectId: clampString(entry.projectId, 64) || undefined,\n deploymentId: clampString(entry.deploymentId, 64) || undefined,\n requestId: clampString(entry.requestId, 64) || undefined,\n logId: clampString(entry.id, 64) || undefined,\n statusCode:\n typeof entry.statusCode === 'number' ? entry.statusCode : undefined,\n proxyStatusCode:\n typeof entry.proxy?.statusCode === 'number'\n ? entry.proxy.statusCode\n : undefined,\n // Clamped like the beacon's own message. This is where \"Task timed out\n // after 10.01 seconds\" lives, which is the whole triage value of the\n // platform-5xx case.\n message: clampString(entry.message, MAX_MESSAGE) || undefined,\n },\n }\n}\n\n/** What one delivery did, for the response body, the tests and the caller. */\nexport interface DrainIngestResult {\n /** Entries in the delivery. */\n received: number\n /** Entries that passed the receiver-path and 5xx gates. */\n matched: number\n /** Entries actually written to Cloud Logging. */\n forwarded: number\n /** Entries dropped by the per-window budget — REPORTED, never silent. */\n suppressed: number\n /** Set when nothing could be written at all; a stable code, never a message. */\n code?: 'no-credential' | 'transport' | `http-${number}`\n}\n\n/**\n * Where the write goes, and under whose credential.\n *\n * Injectable because the receiver has to be able to run somewhere that is NOT\n * a Vercel project this drain watches — a delivery POST is a request to\n * whatever hosts it, and a request produces a log the same drain then\n * delivers, which is the AGL-1921 feedback loop. Vercel's drain `sampling`\n * rules look like the answer and are NOT: measured 2026-08-26, a single\n * `{rate: 0}` rule with no path prefix — literally \"drop everything\" — changed\n * delivery volume from 31 to 32 per five minutes. The whole `schemas.log`\n * filter block is accepted by the API, echoed back on `GET`, and never\n * applied. Separation is what stops the loop.\n *\n * The drain's newer top-level OData `filter` IS applied, and is what keeps the\n * delivery volume down (AGL-4121). It cannot replace the gate here: Vercel's\n * `log/statusCode` reads only `proxy.statusCode`, so the drains drop what is\n * proven healthy and this module still decides what is a server error.\n *\n * The default keeps every existing caller on the Firebase admin credential.\n * A receiver hosted off Vercel (Cloud Run in `aglyn-main`) passes its own\n * resolver instead and never imports `firebase-admin` at all, which is what\n * lets this module be bundled for it without dragging the SDK along.\n */\nexport interface DrainIngestOptions {\n /**\n * Resolve the Cloud Logging bearer token and project. Returning `null`\n * means \"no credential\" and the delivery is dropped, reported, and answered\n * 200 — never an error, because Vercel disables a drain whose endpoint\n * fails often enough.\n */\n target?: () => Promise<{ token: string; projectId: string } | null>\n}\n\n/**\n * Ingest ONE verified delivery: filter, budget, then a single batched write.\n *\n * Never throws. Vercel disables a drain whose endpoint fails often enough, so\n * a receiver that propagated a Logging outage would end by turning itself off\n * during the incident it exists to report.\n */\nexport async function ingestDrainDelivery(\n entries: readonly VercelDrainEntry[],\n options?: DrainIngestOptions,\n): Promise<DrainIngestResult> {\n const received = entries.length\n const matched = selectForwardableEntries(entries)\n const result: DrainIngestResult = {\n received,\n matched: matched.length,\n forwarded: 0,\n suppressed: 0,\n }\n if (!matched.length) return result\n\n const now = Date.now()\n if (now - drainWindowStartedAt >= DRAIN_WINDOW_MS) {\n if (drainSuppressed > 0) {\n // ⚠️ The lossiness is REPORTED. `level: \"warning\"`, so guard (b) in\n // RECEIVER_ROUTE_PATH keeps this line from ever draining back in.\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n suppressed: drainSuppressed,\n written: drainWritten,\n windowMs: DRAIN_WINDOW_MS,\n }),\n )\n }\n drainWindowStartedAt = now\n drainWritten = 0\n drainSuppressed = 0\n }\n\n const room = Math.max(0, DRAIN_BUDGET_PER_WINDOW - drainWritten)\n const writable = matched.slice(0, room)\n const suppressed = matched.length - writable.length\n if (suppressed > 0) drainSuppressed += suppressed\n result.suppressed = suppressed\n if (!writable.length) return result\n\n const target = await (options?.target ?? defaultLoggingTarget)()\n if (!target) {\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n drop: writable.length,\n reason: 'no-credential',\n }),\n )\n result.code = 'no-credential'\n return result\n }\n\n try {\n const response = await fetch(\n 'https://logging.googleapis.com/v2/entries:write',\n {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${target.token}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n logName: `projects/${target.projectId}/logs/${VERCEL_RUNTIME_LOG_ID}`,\n resource: { type: 'global' },\n entries: writable.map(toLogEntry),\n }),\n signal: AbortSignal.timeout(WRITE_TIMEOUT_MS),\n },\n )\n if (!response.ok) {\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n status: response.status,\n drop: writable.length,\n }),\n )\n result.code = `http-${response.status}`\n return result\n }\n drainWritten += writable.length\n result.forwarded = writable.length\n return result\n } catch (error) {\n console.warn(\n JSON.stringify({\n tag: 'AGL-1921:vercel-log-drain',\n transport: String(error).slice(0, 200),\n }),\n )\n result.code = 'transport'\n return result\n }\n}\n"],"names":["defaultLoggingTarget","beaconLoggingTarget","VERCEL_RUNTIME_LOG_ID","DRAIN_SECRET_ENV","RECEIVER_ROUTE_PATH","LOCKDOWN_NOTICE_ROUTE_PATH","DRAIN_BUDGET_PER_WINDOW","DRAIN_WINDOW_MS","drainWindowStartedAt","drainWritten","drainSuppressed","MAX_MESSAGE","WRITE_TIMEOUT_MS","resetDrainBudgetForTests","clampString","value","max","slice","parseDrainPayload","rawBody","body","trim","parsed","JSON","parse","Array","isArray","filter","entry","Boolean","entries","line","split","trimmed","push","isReceiverEntry","paths","path","proxy","some","pathname","startsWith","isLockdownNoticeEntry","level","type","statuses","statusCode","status","length","HEALTH_ROUTE_PREFIX","isHealthContractEntry","isServerErrorEntry","proxyStatus","selectForwardableEntries","toLogEntry","undefined","severity","httpRequest","requestMethod","method","jsonPayload","source","route","entrypoint","host","environment","region","executionRegion","project","projectName","projectId","deploymentId","requestId","logId","id","proxyStatusCode","message","ingestDrainDelivery","options","received","matched","result","forwarded","suppressed","now","Date","console","warn","stringify","tag","written","windowMs","room","Math","writable","target","drop","reason","code","response","fetch","headers","Authorization","token","logName","resource","map","signal","AbortSignal","timeout","ok","error","transport","String"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDC,GAED;;;;;;;;;;;CAWC,GACD,eAAeA;IAIb,MAAM,EAAEC,mBAAmB,EAAE,GAAG,MAAM,MAAM,CAAC;IAC7C,OAAOA;AACT;AAEA;;;;;CAKC,GACD,OAAO,MAAMC,wBAAwB,iBAAgB;AAErD,6EAA6E,GAC7E,OAAO,MAAMC,mBAAmB,0BAAyB;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCC,GACD,OAAO,MAAMC,sBAAsB,iBAAgB;AAEnD;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,MAAMC,6BAA6B,cAAa;AAEvD;;;;;;;CAOC,GACD,MAAMC,0BAA0B;AAChC,MAAMC,kBAAkB;AACxB,IAAIC,uBAAuB;AAC3B,IAAIC,eAAe;AACnB,IAAIC,kBAAkB;AAEtB,MAAMC,cAAc;AACpB,MAAMC,mBAAmB;AAEzB,4EAA4E,GAC5E,OAAO,SAASC;IACdL,uBAAuB;IACvBC,eAAe;IACfC,kBAAkB;AACpB;AAiCA,SAASI,YAAYC,KAAc,EAAEC,GAAW;IAC9C,OAAO,OAAOD,UAAU,WAAWA,MAAME,KAAK,CAAC,GAAGD,OAAO;AAC3D;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASE,kBAAkBC,OAAe;IAC/C,MAAMC,OAAOD,QAAQE,IAAI;IACzB,IAAI,CAACD,MAAM,OAAO,EAAE;IACpB,IAAI;QACF,MAAME,SAAkBC,KAAKC,KAAK,CAACJ;QACnC,IAAIK,MAAMC,OAAO,CAACJ,SAAS;YACzB,OAAOA,OAAOK,MAAM,CAClB,CAACC,QACCC,QAAQD,UAAU,OAAOA,UAAU;QAEzC;QACA,IAAIN,UAAU,OAAOA,WAAW,UAC9B,OAAO;YAACA;SAA2B;IACvC,EAAE,eAAM;IACN,6DAA6D;IAC/D;IACA,MAAMQ,UAA8B,EAAE;IACtC,KAAK,MAAMC,QAAQX,KAAKY,KAAK,CAAC,MAAO;QACnC,MAAMC,UAAUF,KAAKV,IAAI;QACzB,IAAI,CAACY,SAAS;QACd,IAAI;YACF,MAAMX,SAAkBC,KAAKC,KAAK,CAACS;YACnC,IAAIX,UAAU,OAAOA,WAAW,YAAY,CAACG,MAAMC,OAAO,CAACJ,SAAS;gBAClEQ,QAAQI,IAAI,CAACZ;YACf;QACF,EAAE,eAAM;QACN,8CAA8C;QAChD;IACF;IACA,OAAOQ;AACT;AAEA,gFAAgF,GAChF,OAAO,SAASK,gBAAgBP,KAAuB;QAC1BA;IAA3B,MAAMQ,QAAQ;QAACR,MAAMS,IAAI;SAAET,eAAAA,MAAMU,KAAK,qBAAXV,aAAaS,IAAI;KAAC;IAC7C,OAAOD,MAAMG,IAAI,CAAC,CAACF;QACjB,IAAI,OAAOA,SAAS,UAAU,OAAO;QACrC,qEAAqE;QACrE,MAAM,CAACG,SAAS,GAAGH,KAAKL,KAAK,CAAC;QAC9B,OACEQ,aAAapC,uBACboC,SAASC,UAAU,CAAC,GAAGrC,oBAAoB,CAAC,CAAC;IAEjD;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASsC,sBAAsBd,KAAuB;QAEvBA,cAKhBA;IANpB,IAAIA,MAAMe,KAAK,KAAK,WAAWf,MAAMgB,IAAI,KAAK,SAAS,OAAO;IAC9D,MAAMC,WAAW;QAACjB,MAAMkB,UAAU;SAAElB,eAAAA,MAAMU,KAAK,qBAAXV,aAAakB,UAAU;KAAC,CAACnB,MAAM,CACjE,CAACoB,SAA6B,OAAOA,WAAW;IAElD,IAAI,CAACF,SAASG,MAAM,IAAIH,SAASN,IAAI,CAAC,CAACQ,SAAWA,WAAW,MAC3D,OAAO;IACT,OAAO;QAACnB,MAAMS,IAAI;SAAET,gBAAAA,MAAMU,KAAK,qBAAXV,cAAaS,IAAI;KAAC,CAACE,IAAI,CAAC,CAACF;QAC3C,IAAI,OAAOA,SAAS,UAAU,OAAO;QACrC,qEAAqE;QACrE,MAAM,CAACG,SAAS,GAAGH,KAAKL,KAAK,CAAC;QAC9B,OAAOQ,aAAanC;IACtB;AACF;AAEA;;;;;;;CAOC,GACD,OAAO,MAAM4C,sBAAsB,cAAa;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD,OAAO,SAASC,sBAAsBtB,KAAuB;QAEvBA,cAKhBA;IANpB,IAAIA,MAAMe,KAAK,KAAK,WAAWf,MAAMgB,IAAI,KAAK,SAAS,OAAO;IAC9D,MAAMC,WAAW;QAACjB,MAAMkB,UAAU;SAAElB,eAAAA,MAAMU,KAAK,qBAAXV,aAAakB,UAAU;KAAC,CAACnB,MAAM,CACjE,CAACoB,SAA6B,OAAOA,WAAW;IAElD,IAAI,CAACF,SAASG,MAAM,IAAIH,SAASN,IAAI,CAAC,CAACQ,SAAWA,WAAW,MAC3D,OAAO;IACT,OAAO;QAACnB,MAAMS,IAAI;SAAET,gBAAAA,MAAMU,KAAK,qBAAXV,cAAaS,IAAI;KAAC,CAACE,IAAI,CAAC,CAACF;QAC3C,IAAI,OAAOA,SAAS,UAAU,OAAO;QACrC,qEAAqE;QACrE,MAAM,CAACG,SAAS,GAAGH,KAAKL,KAAK,CAAC;QAC9B,OACEQ,aAAaS,uBACbT,SAASC,UAAU,CAAC,GAAGQ,oBAAoB,CAAC,CAAC;IAEjD;AACF;AAEA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,SAASE,mBAAmBvB,KAAuB;QAKpCA;IAJpB,IAAI,OAAOA,MAAMkB,UAAU,KAAK,UAAU;QACxC,IAAIlB,MAAMkB,UAAU,IAAI,KAAK,OAAO;QACpC,IAAIlB,MAAMkB,UAAU,KAAK,CAAC,GAAG,OAAO;IACtC;IACA,MAAMM,eAAcxB,eAAAA,MAAMU,KAAK,qBAAXV,aAAakB,UAAU;IAC3C,IAAI,OAAOM,gBAAgB,YAAYA,eAAe,KAAK,OAAO;IAClE,IAAIxB,MAAMe,KAAK,KAAK,WAAWf,MAAMgB,IAAI,KAAK,SAAS,OAAO;IAC9D,OAAO;AACT;AAEA;;;CAGC,GACD,OAAO,SAASS,yBACdvB,OAAoC;IAEpC,OAAOA,QAAQH,MAAM,CACnB,CAACC,QACC,CAACO,gBAAgBP,UACjB,CAACc,sBAAsBd,UACvB,CAACsB,sBAAsBtB,UACvBuB,mBAAmBvB;AAEzB;AAEA;;;;;;;;;;;;CAYC,GACD,SAAS0B,WAAW1B,KAAuB;QAI5BA,cASkBA,eAuBlBA;IAnCb,MAAMmB,SACJ,OAAOnB,MAAMkB,UAAU,KAAK,YAAYlB,MAAMkB,UAAU,IAAI,IACxDlB,MAAMkB,UAAU,GAChB,SAAOlB,eAAAA,MAAMU,KAAK,qBAAXV,aAAakB,UAAU,MAAK,YACjClB,MAAMU,KAAK,CAACQ,UAAU,IAAI,IAC1BlB,MAAMU,KAAK,CAACQ,UAAU,GACtBS;IACR,OAAO;QACLC,UAAU;QACV,yEAAyE;QACzE,yEAAyE;QACzEC,aAAa;YACXC,eAAe5C,aAAYc,gBAAAA,MAAMU,KAAK,qBAAXV,cAAa+B,MAAM,EAAE,OAAOJ;YACvDR;QACF;QACAa,aAAa;YACX,mEAAmE;YACnE,uEAAuE;YACvE,oEAAoE;YACpEC,QAAQ/C,YAAYc,MAAMiC,MAAM,EAAE,OAAON;YACzCZ,OAAO7B,YAAYc,MAAMe,KAAK,EAAE,OAAOY;YACvCX,MAAM9B,YAAYc,MAAMgB,IAAI,EAAE,OAAOW;YACrCO,OAAOhD,YAAYc,MAAMS,IAAI,EAAE,QAAQkB;YACvCQ,YAAYjD,YAAYc,MAAMmC,UAAU,EAAE,QAAQR;YAClDS,MAAMlD,YAAYc,MAAMoC,IAAI,EAAE,QAAQT;YACtCU,aAAanD,YAAYc,MAAMqC,WAAW,EAAE,OAAOV;YACnDW,QAAQpD,YAAYc,MAAMuC,eAAe,EAAE,OAAOZ;YAClDa,SAAStD,YAAYc,MAAMyC,WAAW,EAAE,OAAOd;YAC/Ce,WAAWxD,YAAYc,MAAM0C,SAAS,EAAE,OAAOf;YAC/CgB,cAAczD,YAAYc,MAAM2C,YAAY,EAAE,OAAOhB;YACrDiB,WAAW1D,YAAYc,MAAM4C,SAAS,EAAE,OAAOjB;YAC/CkB,OAAO3D,YAAYc,MAAM8C,EAAE,EAAE,OAAOnB;YACpCT,YACE,OAAOlB,MAAMkB,UAAU,KAAK,WAAWlB,MAAMkB,UAAU,GAAGS;YAC5DoB,iBACE,SAAO/C,gBAAAA,MAAMU,KAAK,qBAAXV,cAAakB,UAAU,MAAK,WAC/BlB,MAAMU,KAAK,CAACQ,UAAU,GACtBS;YACN,uEAAuE;YACvE,qEAAqE;YACrE,qBAAqB;YACrBqB,SAAS9D,YAAYc,MAAMgD,OAAO,EAAEjE,gBAAgB4C;QACtD;IACF;AACF;AAiDA;;;;;;CAMC,GACD,OAAO,eAAesB,oBACpB/C,OAAoC,EACpCgD,OAA4B;;IAE5B,MAAMC,WAAWjD,QAAQkB,MAAM;IAC/B,MAAMgC,UAAU3B,yBAAyBvB;IACzC,MAAMmD,SAA4B;QAChCF;QACAC,SAASA,QAAQhC,MAAM;QACvBkC,WAAW;QACXC,YAAY;IACd;IACA,IAAI,CAACH,QAAQhC,MAAM,EAAE,OAAOiC;IAE5B,MAAMG,MAAMC,KAAKD,GAAG;IACpB,IAAIA,MAAM5E,wBAAwBD,iBAAiB;QACjD,IAAIG,kBAAkB,GAAG;YACvB,oEAAoE;YACpE,kEAAkE;YAClE4E,QAAQC,IAAI,CACVhE,KAAKiE,SAAS,CAAC;gBACbC,KAAK;gBACLN,YAAYzE;gBACZgF,SAASjF;gBACTkF,UAAUpF;YACZ;QAEJ;QACAC,uBAAuB4E;QACvB3E,eAAe;QACfC,kBAAkB;IACpB;IAEA,MAAMkF,OAAOC,KAAK7E,GAAG,CAAC,GAAGV,0BAA0BG;IACnD,MAAMqF,WAAWd,QAAQ/D,KAAK,CAAC,GAAG2E;IAClC,MAAMT,aAAaH,QAAQhC,MAAM,GAAG8C,SAAS9C,MAAM;IACnD,IAAImC,aAAa,GAAGzE,mBAAmByE;IACvCF,OAAOE,UAAU,GAAGA;IACpB,IAAI,CAACW,SAAS9C,MAAM,EAAE,OAAOiC;IAE7B,MAAMc,SAAS,MAAM,SAACjB,2BAAAA,QAASiB,MAAM,mBAAI/F;IACzC,IAAI,CAAC+F,QAAQ;QACXT,QAAQC,IAAI,CACVhE,KAAKiE,SAAS,CAAC;YACbC,KAAK;YACLO,MAAMF,SAAS9C,MAAM;YACrBiD,QAAQ;QACV;QAEFhB,OAAOiB,IAAI,GAAG;QACd,OAAOjB;IACT;IAEA,IAAI;QACF,MAAMkB,WAAW,MAAMC,MACrB,mDACA;YACEzC,QAAQ;YACR0C,SAAS;gBACPC,eAAe,CAAC,OAAO,EAAEP,OAAOQ,KAAK,EAAE;gBACvC,gBAAgB;YAClB;YACAnF,MAAMG,KAAKiE,SAAS,CAAC;gBACnBgB,SAAS,CAAC,SAAS,EAAET,OAAOzB,SAAS,CAAC,MAAM,EAAEpE,uBAAuB;gBACrEuG,UAAU;oBAAE7D,MAAM;gBAAS;gBAC3Bd,SAASgE,SAASY,GAAG,CAACpD;YACxB;YACAqD,QAAQC,YAAYC,OAAO,CAACjG;QAC9B;QAEF,IAAI,CAACuF,SAASW,EAAE,EAAE;YAChBxB,QAAQC,IAAI,CACVhE,KAAKiE,SAAS,CAAC;gBACbC,KAAK;gBACL1C,QAAQoD,SAASpD,MAAM;gBACvBiD,MAAMF,SAAS9C,MAAM;YACvB;YAEFiC,OAAOiB,IAAI,GAAG,CAAC,KAAK,EAAEC,SAASpD,MAAM,EAAE;YACvC,OAAOkC;QACT;QACAxE,gBAAgBqF,SAAS9C,MAAM;QAC/BiC,OAAOC,SAAS,GAAGY,SAAS9C,MAAM;QAClC,OAAOiC;IACT,EAAE,OAAO8B,OAAO;QACdzB,QAAQC,IAAI,CACVhE,KAAKiE,SAAS,CAAC;YACbC,KAAK;YACLuB,WAAWC,OAAOF,OAAO9F,KAAK,CAAC,GAAG;QACpC;QAEFgE,OAAOiB,IAAI,GAAG;QACd,OAAOjB;IACT;AACF"}
|