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

package/src/lib/server/host-visitor-records.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The durable half of the visitor-record ceilings (AGL-1529) — the lead
+ * writer that enforces `LEADS_MAX_PER_HOST`, and the bookkeeping that makes a
+ * trip of EITHER ceiling something a site's owner can see.
+ *
+ * The policy is pure and lives in `@aglyn/aglyn/server`
+ * (`visitor-record-ceiling.ts`); this is the part that needs Firestore. Same
+ * split as `visitorWriteRateLimitRefusal`, and for the same reason.
+ */
+import { type VisitorRecordKind } from '@aglyn/aglyn/server';
+import { type ResolvedCampaignTouch } from './campaign-conversion-attribution';
+/**
+ * Make a tripped ceiling OBSERVABLE rather than a silent drop — the * standing rule that a control which is not visible in the console does not
+ * count as shipped.
+ *
+ * Two audiences, one call, in exactly `recordAbuseCeilingTrip`'s shape
+ * (`apps/tenant/app/api/forms/submit/route.ts`, AGL-1655):
+ *
+ *  - A durable per-month refusal count at
+ *    `hosts/{id}/counters/{siteMembers|leads}Refused`. Counters are excluded
+ *    from every client write in `cloud/firebase-firestore.rules` (AGL-1367),
+ *    so the record cannot be edited away by the site it describes, and host
+ *    admins can already READ it — which is what lets the inbox console page
+ *    render it with no rules change.
+ *  - One in-app notification to the site's managers, on the FIRST refusal of
+ *    the month only. A notification per refused bot request would be the
+ *    flood again, delivered.
+ *
+ * The counter is month-keyed even though the CEILING is a total, because the
+ * two facts are different: the ceiling is "how many records exist" and this is
+ * "how many were turned away recently". Only the second is worth a notice.
+ *
+ * Best-effort throughout: bookkeeping that failed must never turn a contained
+ * refusal into a 500, because a 500 is an invitation to retry.
+ */
+export declare function recordVisitorRecordCeilingTrip(options: {
+    hostRef: FirebaseFirestore.DocumentReference;
+    hostId: string;
+    kind: VisitorRecordKind;
+    ceiling: number;
+    monthKey?: string;
+}): Promise<void>;
+/** What a caller wants stored on the lead. `createdAt` is stamped here. */
+export interface HostLeadInput {
+    email: string;
+    /** The name the person typed, when they typed one (AGL-2303). */
+    name?: string;
+    /** `signup`, `booking`, `form:{formId}` — the surface that produced it. */
+    source: string;
+    /**
+     * Explicit marketing opt-in, with a consent timestamp — the same shape
+     * `upsertHostContact` already carries (AGL-301). Omitted or `false` writes
+     * nothing: a lead is a side effect of an action the visitor DID take
+     * (sign up, book), which is not by itself consent to be emailed
+     * marketing, so this is only set when the caller captured an explicit
+     * checkbox.
+     */
+    marketingConsent?: boolean;
+}
+/**
+ * Record one lead at `hosts/{hostId}/leads/{personKey}`, bounded by
+ * `LEADS_MAX_PER_HOST` (AGL-1529).
+ *
+ * ## One person is one document
+ *
+ * `docs/specs/reusable-forms.md` §4b. This used to be `tx.create(ref.doc())`
+ * — an auto-id per capture event — so one returning customer who signed up
+ * and booked twice was three "leads". The Members & leads tab presented a
+ * list of events as a list of people, and the only thing holding two rows for
+ * one person together was string equality on the address at render time.
+ *
+ * The events are not lost, they are just no longer the record: `sources`
+ * carries every surface that produced a capture, `submissionCount` counts
+ * them, and `firstSeenAtMs`/`lastSeenAtMs` bracket them. The submissions, the
+ * bookings and the member document are still there and still one row each.
+ *
+ * The id is {@link personKey} — `sha256(normalizeContactEmail(email))`, the
+ * SAME derivation a list membership's `memberKey` uses, imported rather than
+ * restated. Two specs named this function and the rule both stated is that
+ * whichever ships second imports the first's helper: a second copy is how
+ * `emailSuppressionKey` and `suppressionId` came to disagree.
+ *
+ * ## Why every lead writer goes through here
+ *
+ * There are three lead writes in the repo — the sign-up handler and the two
+ * bookings paths — and all three were `hostRef.collection('leads').add(…)`
+ * with a `.catch()` on the end. A cap enforced at two of three call sites is
+ * not a cap, and the fourth writer somebody adds next month would not have
+ * one either. One function is the only shape that survives that.
+ *
+ * ## The count is evaluated INSIDE the transaction that writes
+ *
+ * A create-time quota can be laundered by WHEN it is evaluated, not by the
+ * counting rule (AGL-2231/2265/2266). Read-then-decide-then-`add()` lets N
+ * concurrent visitors each read the same pre-count, each find room, and each
+ * land — and nothing re-counts afterwards, so the extra rows are permanent.
+ * `Transaction.get(AggregateQuery)` serialises the count against a concurrent
+ * create into the same collection: the loser retries, re-reads the higher
+ * count, and is refused. The count is of LIVE documents, so triaging leads in
+ * the inbox frees the slots.
+ *
+ * ## Refusing a lead never fails the visitor's action
+ *
+ * A lead is a SIDE EFFECT — of a sign-up, or of a booking. The visitor did
+ * not ask for it and cannot see it, so refusing one must not refuse the thing
+ * they did ask for. This returns a boolean and never throws; the trip is
+ * recorded and the caller carries on. That is the honest split, and it is why
+ * `SITE_MEMBERS_MAX_PER_HOST` (which governs an action a visitor DID take) is
+ * enforced with a 429 in the sign-up handler and this is not.
+ */
+export declare function addHostLead(options: {
+    hostRef: FirebaseFirestore.DocumentReference;
+    hostId: string;
+    lead: HostLeadInput;
+    /**
+     * The ceiling to compare against. Defaults to `LEADS_MAX_PER_HOST` and is
+     * passed by NOTHING in production — it exists so the suite can re-drive the
+     * same count against a ceiling one higher and require the write to succeed.
+     * A refusal that survives its own ceiling being raised was never that
+     * ceiling's refusal, and there is exactly ONE comparison below, so knifing
+     * it cannot be absorbed by a fallback branch.
+     */
+    ceiling?: number;
+    /**
+     * The campaign this person came from, already resolved by the door.
+     *
+     * Resolved rather than raw, and passed rather than looked up, because one
+     * visitor action reaches several writers: a form submission that creates a
+     * submission, a contact AND a lead must pay for the touch lookup once. A
+     * door that hands none — every order path, every import — attributes
+     * nothing, which is how a lead that no campaign caused stays uncredited.
+     */
+    touch?: ResolvedCampaignTouch | null;
+}): Promise<boolean>;

package/src/lib/server/host-visitor-records.js

@@ -0,0 +1,262 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The durable half of the visitor-record ceilings (AGL-1529) — the lead
+ * writer that enforces `LEADS_MAX_PER_HOST`, and the bookkeeping that makes a
+ * trip of EITHER ceiling something a site's owner can see.
+ *
+ * The policy is pure and lives in `@aglyn/aglyn/server`
+ * (`visitor-record-ceiling.ts`); this is the part that needs Firestore. Same
+ * split as `visitorWriteRateLimitRefusal`, and for the same reason.
+ */ import { CAPTURED_BY_HOST_FIELD, checkVisitorRecordCeiling, LEADS_MAX_PER_HOST, marketingConsentFieldsForGroup, personKey, readMarketingBasis, soloConsentGroup, submissionMonthKey, visitorRecordRefusedCounterId } from "@aglyn/aglyn/server";
+import { FieldValue } from "firebase-admin/firestore";
+import { attributeCampaignConversion } from "./campaign-conversion-attribution.js";
+import { notifyHostManagers } from "./notifications.js";
+/**
+ * Make a tripped ceiling OBSERVABLE rather than a silent drop — the * standing rule that a control which is not visible in the console does not
+ * count as shipped.
+ *
+ * Two audiences, one call, in exactly `recordAbuseCeilingTrip`'s shape
+ * (`apps/tenant/app/api/forms/submit/route.ts`, AGL-1655):
+ *
+ *  - A durable per-month refusal count at
+ *    `hosts/{id}/counters/{siteMembers|leads}Refused`. Counters are excluded
+ *    from every client write in `cloud/firebase-firestore.rules` (AGL-1367),
+ *    so the record cannot be edited away by the site it describes, and host
+ *    admins can already READ it — which is what lets the inbox console page
+ *    render it with no rules change.
+ *  - One in-app notification to the site's managers, on the FIRST refusal of
+ *    the month only. A notification per refused bot request would be the
+ *    flood again, delivered.
+ *
+ * The counter is month-keyed even though the CEILING is a total, because the
+ * two facts are different: the ceiling is "how many records exist" and this is
+ * "how many were turned away recently". Only the second is worth a notice.
+ *
+ * Best-effort throughout: bookkeeping that failed must never turn a contained
+ * refusal into a 500, because a 500 is an invitation to retry.
+ */ export async function recordVisitorRecordCeilingTrip(options) {
+    var _options_monthKey;
+    const { hostRef, hostId, kind, ceiling } = options;
+    const monthKey = (_options_monthKey = options.monthKey) != null ? _options_monthKey : submissionMonthKey();
+    try {
+        var _refusedSnapshot_get;
+        const refusedRef = hostRef.collection('counters').doc(visitorRecordRefusedCounterId(kind));
+        const refusedSnapshot = await refusedRef.get();
+        const alreadyRefused = Number((_refusedSnapshot_get = refusedSnapshot.get(monthKey)) != null ? _refusedSnapshot_get : 0);
+        await refusedRef.set({
+            [monthKey]: FieldValue.increment(1),
+            // Explicit values only — Firestore rejects `undefined`.
+            ceiling,
+            lastRefusedAtMs: Date.now()
+        }, {
+            merge: true
+        });
+        if (alreadyRefused === 0) {
+            const leads = kind === 'leads';
+            await notifyHostManagers(hostId, {
+                type: 'system.visitorRecordsPaused',
+                title: leads ? 'Lead capture paused — this site is at the platform limit' : 'Sign-ups paused — this site is at the platform limit',
+                body: `This site holds ${ceiling.toLocaleString()} ` + `${leads ? 'leads' : 'member accounts'}, which is the platform ` + `safety limit, so further ${leads ? 'leads' : 'sign-ups'} are ` + 'being refused. This is not part of your plan — every plan ' + `includes unlimited ${leads ? 'leads' : 'member accounts'}. ` + `Remove some ${leads ? 'leads' : 'members'}, or contact support ` + 'if this is real traffic.',
+                link: `/${hostId}/inbox`
+            });
+        }
+    } catch (error) {
+        console.error('visitor record ceiling bookkeeping failed', error);
+    }
+}
+/**
+ * Record one lead at `hosts/{hostId}/leads/{personKey}`, bounded by
+ * `LEADS_MAX_PER_HOST` (AGL-1529).
+ *
+ * ## One person is one document
+ *
+ * `docs/specs/reusable-forms.md` §4b. This used to be `tx.create(ref.doc())`
+ * — an auto-id per capture event — so one returning customer who signed up
+ * and booked twice was three "leads". The Members & leads tab presented a
+ * list of events as a list of people, and the only thing holding two rows for
+ * one person together was string equality on the address at render time.
+ *
+ * The events are not lost, they are just no longer the record: `sources`
+ * carries every surface that produced a capture, `submissionCount` counts
+ * them, and `firstSeenAtMs`/`lastSeenAtMs` bracket them. The submissions, the
+ * bookings and the member document are still there and still one row each.
+ *
+ * The id is {@link personKey} — `sha256(normalizeContactEmail(email))`, the
+ * SAME derivation a list membership's `memberKey` uses, imported rather than
+ * restated. Two specs named this function and the rule both stated is that
+ * whichever ships second imports the first's helper: a second copy is how
+ * `emailSuppressionKey` and `suppressionId` came to disagree.
+ *
+ * ## Why every lead writer goes through here
+ *
+ * There are three lead writes in the repo — the sign-up handler and the two
+ * bookings paths — and all three were `hostRef.collection('leads').add(…)`
+ * with a `.catch()` on the end. A cap enforced at two of three call sites is
+ * not a cap, and the fourth writer somebody adds next month would not have
+ * one either. One function is the only shape that survives that.
+ *
+ * ## The count is evaluated INSIDE the transaction that writes
+ *
+ * A create-time quota can be laundered by WHEN it is evaluated, not by the
+ * counting rule (AGL-2231/2265/2266). Read-then-decide-then-`add()` lets N
+ * concurrent visitors each read the same pre-count, each find room, and each
+ * land — and nothing re-counts afterwards, so the extra rows are permanent.
+ * `Transaction.get(AggregateQuery)` serialises the count against a concurrent
+ * create into the same collection: the loser retries, re-reads the higher
+ * count, and is refused. The count is of LIVE documents, so triaging leads in
+ * the inbox frees the slots.
+ *
+ * ## Refusing a lead never fails the visitor's action
+ *
+ * A lead is a SIDE EFFECT — of a sign-up, or of a booking. The visitor did
+ * not ask for it and cannot see it, so refusing one must not refuse the thing
+ * they did ask for. This returns a boolean and never throws; the trip is
+ * recorded and the caller carries on. That is the honest split, and it is why
+ * `SITE_MEMBERS_MAX_PER_HOST` (which governs an action a visitor DID take) is
+ * enforced with a 429 in the sign-up handler and this is not.
+ */ export async function addHostLead(options) {
+    var _options_ceiling;
+    const { hostRef, hostId, lead } = options;
+    const maxPerHost = (_options_ceiling = options.ceiling) != null ? _options_ceiling : LEADS_MAX_PER_HOST;
+    try {
+        const leadsRef = hostRef.collection('leads');
+        const firestore = hostRef.firestore;
+        /*
+     * `null` for anything that is not a usable address — a lead captured
+     * against a malformed one keeps an auto-id and stays its own row. Keying
+     * several unusable addresses under one guessed id would merge two
+     * different people, which is worse than two rows for one.
+     */ const key = personKey(lead.email);
+        const leadRef = key ? leadsRef.doc(key) : leadsRef.doc();
+        const now = Date.now();
+        const seen = _extends({
+            // `arrayUnion`, so a person who books twice has `['booking']` and one
+            // who signed up and then submitted a form has both. Bounded by the
+            // number of surfaces, not by the number of captures.
+            sources: FieldValue.arrayUnion(lead.source),
+            lastSeenAtMs: now,
+            submissionCount: FieldValue.increment(1)
+        }, lead.name ? {
+            name: lead.name
+        } : {});
+        let created = false;
+        const refused = await firestore.runTransaction(async (tx)=>{
+            var _existing_data;
+            // Reset per attempt: a contended transaction re-runs its body, and a
+            // flag left standing from an aborted attempt would credit a campaign
+            // with a person who turned out to exist already.
+            created = false;
+            // ALL READS BEFORE THE WRITE, which Firestore requires.
+            const existing = await tx.get(leadRef);
+            /*
+       * ⛔ THE CEILING GATES A NEW PERSON, NEVER AN EXISTING ONE.
+       *
+       * A returning visitor's capture is an UPDATE — it does not grow the
+       * collection, so refusing it buys no capacity and costs the customer
+       * the source and the timestamp they would have learned. That is the
+       * enforcement-at-use shape the capacity rule exists to forbid: a limit
+       * must refuse the addition, never a person already recorded or the
+       * data attached to them.
+       *
+       * It also means the count is only paid on a genuinely new person,
+       * which is the case that can move it.
+       */ if (!existing.exists) {
+                const used = (await tx.get(leadsRef.count())).data().count;
+                if (checkVisitorRecordCeiling(used, maxPerHost).exceeded) return true;
+            }
+            /*
+       * Consent is carried forward and never cleared.
+       *
+       * A basis is written only when this capture carried an explicit
+       * opt-in, so a later booking by someone who did not tick the box
+       * leaves an earlier grant standing — absent-or-granted, the shape
+       * every other writer uses. The TIMESTAMP is carried over rather than
+       * restamped, for the reason given at the read below.
+       */ /*
+       * The EARLIEST grant is the one that happened, so a later capture
+       * carrying the same checkbox keeps the original date rather than
+       * restamping when this person opted in. Read back through the shared
+       * reader so "already consented" means the same thing here as it does
+       * at send time.
+       */ /*
+       * THE GROUP OF ONE, and deliberately so on this silo.
+       *
+       * `hosts/{hostId}/leads` is private by path — no sibling site can sweep
+       * it, declared group or not — so pooling a lead's basis would record a
+       * disclosure that reaches nothing. The contact written by the same
+       * capture door IS org-shared and IS pooled, which is where a declared
+       * group's disclosure is honored.
+       */ const group = soloConsentGroup(hostId);
+            const prior = readMarketingBasis((_existing_data = existing.data()) != null ? _existing_data : null, group);
+            const consentAtMs = prior.basis === 'granted' && prior.basisAtMs !== null ? prior.basisAtMs : now;
+            created = !existing.exists;
+            tx.set(leadRef, _extends({
+                email: lead.email
+            }, seen, existing.exists ? {} : {
+                firstSeenAtMs: now,
+                createdAt: FieldValue.serverTimestamp(),
+                [CAPTURED_BY_HOST_FIELD]: [
+                    hostId
+                ]
+            }, lead.marketingConsent ? marketingConsentFieldsForGroup(group, consentAtMs) : {}), {
+                merge: true
+            });
+            return false;
+        });
+        if (refused) {
+            await recordVisitorRecordCeilingTrip({
+                hostRef,
+                hostId,
+                kind: 'leads',
+                ceiling: maxPerHost
+            });
+            return false;
+        }
+        /*
+     * ATTRIBUTED ON CREATION ONLY.
+     *
+     * A returning visitor's capture is an update — the campaign did not
+     * produce a lead, it produced another visit by a person the site already
+     * held — and crediting it would let whichever campaign ran most recently
+     * re-earn every lead on the list. `created` is set inside the transaction
+     * that decides it, so the attribution and the write agree about whether
+     * this person is new.
+     *
+     * Awaited rather than fired off: `addHostLead` already returns only after
+     * its own write, and a caller that `void`s it (every one of them) is
+     * unaffected. Never throws, so a failure here cannot cost the lead.
+     */ if (created && options.touch) {
+            await attributeCampaignConversion({
+                hostId,
+                kind: 'lead',
+                refId: leadRef.id,
+                touch: options.touch,
+                convertedAtMs: now
+            });
+        }
+        return true;
+    } catch (error) {
+        // Same posture the three original call sites had (`.catch(() => undefined)`
+        // / `.catch(console.error)`): a lead that failed to store must not fail
+        // the sign-up or the booking that produced it.
+        console.error('lead write failed', error);
+        return false;
+    }
+}
+
+//# sourceMappingURL=host-visitor-records.js.map

package/src/lib/server/host-visitor-records.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/host-visitor-records.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * The durable half of the visitor-record ceilings (AGL-1529) — the lead\n * writer that enforces `LEADS_MAX_PER_HOST`, and the bookkeeping that makes a\n * trip of EITHER ceiling something a site's owner can see.\n *\n * The policy is pure and lives in `@aglyn/aglyn/server`\n * (`visitor-record-ceiling.ts`); this is the part that needs Firestore. Same\n * split as `visitorWriteRateLimitRefusal`, and for the same reason.\n */\n\nimport {\n  CAPTURED_BY_HOST_FIELD,\n  checkVisitorRecordCeiling,\n  LEADS_MAX_PER_HOST,\n  marketingConsentFieldsForGroup,\n  personKey,\n  readMarketingBasis,\n  soloConsentGroup,\n  submissionMonthKey,\n  visitorRecordRefusedCounterId,\n  type VisitorRecordKind,\n} from '@aglyn/aglyn/server'\nimport { FieldValue } from 'firebase-admin/firestore'\nimport {\n  attributeCampaignConversion,\n  type ResolvedCampaignTouch,\n} from './campaign-conversion-attribution'\nimport { notifyHostManagers } from './notifications'\n\n/**\n * Make a tripped ceiling OBSERVABLE rather than a silent drop — the * standing rule that a control which is not visible in the console does not\n * count as shipped.\n *\n * Two audiences, one call, in exactly `recordAbuseCeilingTrip`'s shape\n * (`apps/tenant/app/api/forms/submit/route.ts`, AGL-1655):\n *\n *  - A durable per-month refusal count at\n *    `hosts/{id}/counters/{siteMembers|leads}Refused`. Counters are excluded\n *    from every client write in `cloud/firebase-firestore.rules` (AGL-1367),\n *    so the record cannot be edited away by the site it describes, and host\n *    admins can already READ it — which is what lets the inbox console page\n *    render it with no rules change.\n *  - One in-app notification to the site's managers, on the FIRST refusal of\n *    the month only. A notification per refused bot request would be the\n *    flood again, delivered.\n *\n * The counter is month-keyed even though the CEILING is a total, because the\n * two facts are different: the ceiling is \"how many records exist\" and this is\n * \"how many were turned away recently\". Only the second is worth a notice.\n *\n * Best-effort throughout: bookkeeping that failed must never turn a contained\n * refusal into a 500, because a 500 is an invitation to retry.\n */\nexport async function recordVisitorRecordCeilingTrip(options: {\n  hostRef: FirebaseFirestore.DocumentReference\n  hostId: string\n  kind: VisitorRecordKind\n  ceiling: number\n  monthKey?: string\n}): Promise<void> {\n  const { hostRef, hostId, kind, ceiling } = options\n  const monthKey = options.monthKey ?? submissionMonthKey()\n  try {\n    const refusedRef = hostRef\n      .collection('counters')\n      .doc(visitorRecordRefusedCounterId(kind))\n    const refusedSnapshot = await refusedRef.get()\n    const alreadyRefused = Number(refusedSnapshot.get(monthKey) ?? 0)\n    await refusedRef.set(\n      {\n        [monthKey]: FieldValue.increment(1),\n        // Explicit values only — Firestore rejects `undefined`.\n        ceiling,\n        lastRefusedAtMs: Date.now(),\n      },\n      { merge: true },\n    )\n    if (alreadyRefused === 0) {\n      const leads = kind === 'leads'\n      await notifyHostManagers(hostId, {\n        type: 'system.visitorRecordsPaused',\n        title: leads\n          ? 'Lead capture paused — this site is at the platform limit'\n          : 'Sign-ups paused — this site is at the platform limit',\n        body:\n          `This site holds ${ceiling.toLocaleString()} ` +\n          `${leads ? 'leads' : 'member accounts'}, which is the platform ` +\n          `safety limit, so further ${leads ? 'leads' : 'sign-ups'} are ` +\n          'being refused. This is not part of your plan — every plan ' +\n          `includes unlimited ${leads ? 'leads' : 'member accounts'}. ` +\n          `Remove some ${leads ? 'leads' : 'members'}, or contact support ` +\n          'if this is real traffic.',\n        link: `/${hostId}/inbox`,\n      })\n    }\n  } catch (error) {\n    console.error('visitor record ceiling bookkeeping failed', error)\n  }\n}\n\n/** What a caller wants stored on the lead. `createdAt` is stamped here. */\nexport interface HostLeadInput {\n  email: string\n  /** The name the person typed, when they typed one (AGL-2303). */\n  name?: string\n  /** `signup`, `booking`, `form:{formId}` — the surface that produced it. */\n  source: string\n  /**\n   * Explicit marketing opt-in, with a consent timestamp — the same shape\n   * `upsertHostContact` already carries (AGL-301). Omitted or `false` writes\n   * nothing: a lead is a side effect of an action the visitor DID take\n   * (sign up, book), which is not by itself consent to be emailed\n   * marketing, so this is only set when the caller captured an explicit\n   * checkbox.\n   */\n  marketingConsent?: boolean\n}\n\n/**\n * Record one lead at `hosts/{hostId}/leads/{personKey}`, bounded by\n * `LEADS_MAX_PER_HOST` (AGL-1529).\n *\n * ## One person is one document\n *\n * `docs/specs/reusable-forms.md` §4b. This used to be `tx.create(ref.doc())`\n * — an auto-id per capture event — so one returning customer who signed up\n * and booked twice was three \"leads\". The Members & leads tab presented a\n * list of events as a list of people, and the only thing holding two rows for\n * one person together was string equality on the address at render time.\n *\n * The events are not lost, they are just no longer the record: `sources`\n * carries every surface that produced a capture, `submissionCount` counts\n * them, and `firstSeenAtMs`/`lastSeenAtMs` bracket them. The submissions, the\n * bookings and the member document are still there and still one row each.\n *\n * The id is {@link personKey} — `sha256(normalizeContactEmail(email))`, the\n * SAME derivation a list membership's `memberKey` uses, imported rather than\n * restated. Two specs named this function and the rule both stated is that\n * whichever ships second imports the first's helper: a second copy is how\n * `emailSuppressionKey` and `suppressionId` came to disagree.\n *\n * ## Why every lead writer goes through here\n *\n * There are three lead writes in the repo — the sign-up handler and the two\n * bookings paths — and all three were `hostRef.collection('leads').add(…)`\n * with a `.catch()` on the end. A cap enforced at two of three call sites is\n * not a cap, and the fourth writer somebody adds next month would not have\n * one either. One function is the only shape that survives that.\n *\n * ## The count is evaluated INSIDE the transaction that writes\n *\n * A create-time quota can be laundered by WHEN it is evaluated, not by the\n * counting rule (AGL-2231/2265/2266). Read-then-decide-then-`add()` lets N\n * concurrent visitors each read the same pre-count, each find room, and each\n * land — and nothing re-counts afterwards, so the extra rows are permanent.\n * `Transaction.get(AggregateQuery)` serialises the count against a concurrent\n * create into the same collection: the loser retries, re-reads the higher\n * count, and is refused. The count is of LIVE documents, so triaging leads in\n * the inbox frees the slots.\n *\n * ## Refusing a lead never fails the visitor's action\n *\n * A lead is a SIDE EFFECT — of a sign-up, or of a booking. The visitor did\n * not ask for it and cannot see it, so refusing one must not refuse the thing\n * they did ask for. This returns a boolean and never throws; the trip is\n * recorded and the caller carries on. That is the honest split, and it is why\n * `SITE_MEMBERS_MAX_PER_HOST` (which governs an action a visitor DID take) is\n * enforced with a 429 in the sign-up handler and this is not.\n */\nexport async function addHostLead(options: {\n  hostRef: FirebaseFirestore.DocumentReference\n  hostId: string\n  lead: HostLeadInput\n  /**\n   * The ceiling to compare against. Defaults to `LEADS_MAX_PER_HOST` and is\n   * passed by NOTHING in production — it exists so the suite can re-drive the\n   * same count against a ceiling one higher and require the write to succeed.\n   * A refusal that survives its own ceiling being raised was never that\n   * ceiling's refusal, and there is exactly ONE comparison below, so knifing\n   * it cannot be absorbed by a fallback branch.\n   */\n  ceiling?: number\n  /**\n   * The campaign this person came from, already resolved by the door.\n   *\n   * Resolved rather than raw, and passed rather than looked up, because one\n   * visitor action reaches several writers: a form submission that creates a\n   * submission, a contact AND a lead must pay for the touch lookup once. A\n   * door that hands none — every order path, every import — attributes\n   * nothing, which is how a lead that no campaign caused stays uncredited.\n   */\n  touch?: ResolvedCampaignTouch | null\n}): Promise<boolean> {\n  const { hostRef, hostId, lead } = options\n  const maxPerHost = options.ceiling ?? LEADS_MAX_PER_HOST\n  try {\n    const leadsRef = hostRef.collection('leads')\n    const firestore = hostRef.firestore\n    /*\n     * `null` for anything that is not a usable address — a lead captured\n     * against a malformed one keeps an auto-id and stays its own row. Keying\n     * several unusable addresses under one guessed id would merge two\n     * different people, which is worse than two rows for one.\n     */\n    const key = personKey(lead.email)\n    const leadRef = key ? leadsRef.doc(key) : leadsRef.doc()\n    const now = Date.now()\n    const seen = {\n      // `arrayUnion`, so a person who books twice has `['booking']` and one\n      // who signed up and then submitted a form has both. Bounded by the\n      // number of surfaces, not by the number of captures.\n      sources: FieldValue.arrayUnion(lead.source),\n      lastSeenAtMs: now,\n      submissionCount: FieldValue.increment(1),\n      ...(lead.name ? { name: lead.name } : {}),\n    }\n    let created = false\n    const refused = await firestore.runTransaction(async (tx) => {\n      // Reset per attempt: a contended transaction re-runs its body, and a\n      // flag left standing from an aborted attempt would credit a campaign\n      // with a person who turned out to exist already.\n      created = false\n      // ALL READS BEFORE THE WRITE, which Firestore requires.\n      const existing = await tx.get(leadRef)\n      /*\n       * ⛔ THE CEILING GATES A NEW PERSON, NEVER AN EXISTING ONE.\n       *\n       * A returning visitor's capture is an UPDATE — it does not grow the\n       * collection, so refusing it buys no capacity and costs the customer\n       * the source and the timestamp they would have learned. That is the\n       * enforcement-at-use shape the capacity rule exists to forbid: a limit\n       * must refuse the addition, never a person already recorded or the\n       * data attached to them.\n       *\n       * It also means the count is only paid on a genuinely new person,\n       * which is the case that can move it.\n       */\n      if (!existing.exists) {\n        const used = (await tx.get(leadsRef.count())).data().count\n        if (checkVisitorRecordCeiling(used, maxPerHost).exceeded) return true\n      }\n      /*\n       * Consent is carried forward and never cleared.\n       *\n       * A basis is written only when this capture carried an explicit\n       * opt-in, so a later booking by someone who did not tick the box\n       * leaves an earlier grant standing — absent-or-granted, the shape\n       * every other writer uses. The TIMESTAMP is carried over rather than\n       * restamped, for the reason given at the read below.\n       */\n      /*\n       * The EARLIEST grant is the one that happened, so a later capture\n       * carrying the same checkbox keeps the original date rather than\n       * restamping when this person opted in. Read back through the shared\n       * reader so \"already consented\" means the same thing here as it does\n       * at send time.\n       */\n      /*\n       * THE GROUP OF ONE, and deliberately so on this silo.\n       *\n       * `hosts/{hostId}/leads` is private by path — no sibling site can sweep\n       * it, declared group or not — so pooling a lead's basis would record a\n       * disclosure that reaches nothing. The contact written by the same\n       * capture door IS org-shared and IS pooled, which is where a declared\n       * group's disclosure is honored.\n       */\n      const group = soloConsentGroup(hostId)\n      const prior = readMarketingBasis(existing.data() ?? null, group)\n      const consentAtMs =\n        prior.basis === 'granted' && prior.basisAtMs !== null\n          ? prior.basisAtMs\n          : now\n      created = !existing.exists\n      tx.set(\n        leadRef,\n        {\n          email: lead.email,\n          ...seen,\n          ...(existing.exists\n            ? {}\n            : {\n                firstSeenAtMs: now,\n                createdAt: FieldValue.serverTimestamp(),\n                [CAPTURED_BY_HOST_FIELD]: [hostId],\n              }),\n          /*\n           * Recorded under THIS host even though the collection already sits\n           * under it.\n           *\n           * A lead cannot be swept by another site — `hosts/{hostId}/leads`\n           * is private by path — so the host key adds no enforcement here.\n           * It is written anyway because {@link readMarketingBasis} is one\n           * function over four silos, and a silo whose basis lived somewhere\n           * else would need the reader to know which collection it was\n           * handed. A reader that has to be told the shape is a reader that\n           * can be told the wrong one.\n           */\n          ...(lead.marketingConsent\n            ? marketingConsentFieldsForGroup(group, consentAtMs)\n            : {}),\n        },\n        { merge: true },\n      )\n      return false\n    })\n    if (refused) {\n      await recordVisitorRecordCeilingTrip({\n        hostRef,\n        hostId,\n        kind: 'leads',\n        ceiling: maxPerHost,\n      })\n      return false\n    }\n    /*\n     * ATTRIBUTED ON CREATION ONLY.\n     *\n     * A returning visitor's capture is an update — the campaign did not\n     * produce a lead, it produced another visit by a person the site already\n     * held — and crediting it would let whichever campaign ran most recently\n     * re-earn every lead on the list. `created` is set inside the transaction\n     * that decides it, so the attribution and the write agree about whether\n     * this person is new.\n     *\n     * Awaited rather than fired off: `addHostLead` already returns only after\n     * its own write, and a caller that `void`s it (every one of them) is\n     * unaffected. Never throws, so a failure here cannot cost the lead.\n     */\n    if (created && options.touch) {\n      await attributeCampaignConversion({\n        hostId,\n        kind: 'lead',\n        refId: leadRef.id,\n        touch: options.touch,\n        convertedAtMs: now,\n      })\n    }\n    return true\n  } catch (error) {\n    // Same posture the three original call sites had (`.catch(() => undefined)`\n    // / `.catch(console.error)`): a lead that failed to store must not fail\n    // the sign-up or the booking that produced it.\n    console.error('lead write failed', error)\n    return false\n  }\n}\n"],"names":["CAPTURED_BY_HOST_FIELD","checkVisitorRecordCeiling","LEADS_MAX_PER_HOST","marketingConsentFieldsForGroup","personKey","readMarketingBasis","soloConsentGroup","submissionMonthKey","visitorRecordRefusedCounterId","FieldValue","attributeCampaignConversion","notifyHostManagers","recordVisitorRecordCeilingTrip","options","hostRef","hostId","kind","ceiling","monthKey","refusedSnapshot","refusedRef","collection","doc","get","alreadyRefused","Number","set","increment","lastRefusedAtMs","Date","now","merge","leads","type","title","body","toLocaleString","link","error","console","addHostLead","lead","maxPerHost","leadsRef","firestore","key","email","leadRef","seen","sources","arrayUnion","source","lastSeenAtMs","submissionCount","name","created","refused","runTransaction","tx","existing","exists","used","count","data","exceeded","group","prior","consentAtMs","basis","basisAtMs","firstSeenAtMs","createdAt","serverTimestamp","marketingConsent","touch","refId","id","convertedAtMs"],"mappings":"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"}

package/src/lib/server/id-token-refusal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Whether a throw from verifying an ID token (or a session cookie) says the
+ * credential was refused. `true` answers 401; `false` is a failure to check
+ * and must keep the caller's 5xx.
+ */
+export declare function isRefusedIdToken(error: unknown): boolean;
+/**
+ * The 401 a refused credential earns, or `null` for anything else so the
+ * caller's own 500 stands (AGL-1993). Byte-identical to the body a missing
+ * Authorization header already gets, and it never says WHICH code matched.
+ */
+export declare function invalidIdTokenResponse(error: unknown): Response | null;

package/src/lib/server/id-token-refusal.js

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /*==========================================
+ * "THIS TOKEN IS NOT VALID" vs "SOMETHING BROKE WHILE CHECKING IT"
+ * (AGL-1993, AGL-2852).
+ *
+ * `verifyIdToken` throws for both. A handler that answers every throw with a
+ * 401 tells the caller their credential is bad during an outage that has
+ * nothing to do with it, and nothing pages; one that answers every throw with
+ * a 500 records an expired tab as Aglyn failing. This says which one a throw
+ * is, so a refusal can answer 401 and anything else keeps a 5xx.
+ *
+ * ## The direction of the default, which is the whole design
+ *
+ * Unrecognized → `false` → the caller's 5xx. NOT 401. A wrong 500 makes
+ * noise; a wrong 401 hides an outage. Only codes POSITIVELY known to mean the
+ * credential is bad answer `true`, and `strictNullChecks` is off repo-wide, so
+ * an error with no `code` folds to falsy and lands on the `false` default.
+ *
+ * ## `auth/argument-error` is NOT purely a client fault
+ *
+ * firebase-admin maps a bad signature, a malformed JWT, a wrong audience or
+ * issuer and an unknown `kid` to `auth/argument-error` — and falls through to
+ * the same code for `KEY_FETCH_ERROR`, its own Google public-key endpoint
+ * being unreachable (`lib/utils/jwt.js` in firebase-admin 14.2.0 builds that
+ * message as `'Error fetching public keys for Google certs: …'`). By code
+ * alone a certificate outage is a forged token, so the message is read too.
+ *
+ * ## Why a module of its own
+ *
+ * Specs replace `@aglyn/tenant-data-admin` with hand-built `jest.mock`
+ * factories — 178 in the console alone — and a factory that does not list a
+ * symbol makes it `undefined` rather than failing loudly. This file is its
+ * own entry point, `@aglyn/tenant-data-admin/server/id-token-refusal`, which
+ * no factory replaces, so the console's `invalidIdTokenResponse` and every
+ * plugin handler that verifies a token classify through the same real code.
+ * It imports nothing, and must keep importing nothing, for the same reason.
+ *
+ * ## What callers must NOT do with this
+ *
+ * Say which code matched. A refusal's body is the one a missing
+ * Authorization header already gets; telling "expired" from "revoked" from
+ * "no such user" answers questions about accounts for anyone who can send a
+ * request.
+ *==========================================*/ /**
+ * Codes that mean the CREDENTIAL is bad. Anything absent from this set is an
+ * infrastructure failure and keeps its 5xx.
+ */ const INVALID_CREDENTIAL_CODES = new Set([
+    // The JWT itself did not check out: bad signature, malformed, wrong
+    // audience or issuer, unknown `kid`, absent or oversized `sub`.
+    'auth/argument-error',
+    'auth/id-token-expired',
+    'auth/session-cookie-expired',
+    // Revoked or locked out. `assertIdTokenNotRevoked` (AGL-1881) raises these
+    // two with codes matching the SDK's, so both arms agree.
+    'auth/id-token-revoked',
+    'auth/session-cookie-revoked',
+    'auth/user-disabled',
+    // The account behind a well-formed token is gone. Fail-closed, and it is a
+    // statement about the credential, not about our health.
+    'auth/user-not-found',
+    // A token minted in a different GCIP tenant than the pool verifying it.
+    'auth/mismatching-tenant-id'
+]);
+/**
+ * firebase-admin reports its own public-key fetch failing as
+ * `auth/argument-error`. That is an OUTAGE, not a bad token.
+ */ const KEY_FETCH_FAILURE = /error fetching public keys/i;
+/**
+ * Whether a throw from verifying an ID token (or a session cookie) says the
+ * credential was refused. `true` answers 401; `false` is a failure to check
+ * and must keep the caller's 5xx.
+ */ export function isRefusedIdToken(error) {
+    const code = error == null ? void 0 : error.code;
+    if (typeof code !== 'string') return false;
+    if (!INVALID_CREDENTIAL_CODES.has(code)) return false;
+    if (code === 'auth/argument-error') {
+        const message = error.message;
+        if (typeof message === 'string' && KEY_FETCH_FAILURE.test(message)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The 401 a refused credential earns, or `null` for anything else so the
+ * caller's own 500 stands (AGL-1993). Byte-identical to the body a missing
+ * Authorization header already gets, and it never says WHICH code matched.
+ */ export function invalidIdTokenResponse(error) {
+    if (!isRefusedIdToken(error)) return null;
+    return Response.json({
+        error: 'Unauthenticated'
+    }, {
+        status: 401
+    });
+}
+
+//# sourceMappingURL=id-token-refusal.js.map

package/src/lib/server/id-token-refusal.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/id-token-refusal.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 * \"THIS TOKEN IS NOT VALID\" vs \"SOMETHING BROKE WHILE CHECKING IT\"\n * (AGL-1993, AGL-2852).\n *\n * `verifyIdToken` throws for both. A handler that answers every throw with a\n * 401 tells the caller their credential is bad during an outage that has\n * nothing to do with it, and nothing pages; one that answers every throw with\n * a 500 records an expired tab as Aglyn failing. This says which one a throw\n * is, so a refusal can answer 401 and anything else keeps a 5xx.\n *\n * ## The direction of the default, which is the whole design\n *\n * Unrecognized → `false` → the caller's 5xx. NOT 401. A wrong 500 makes\n * noise; a wrong 401 hides an outage. Only codes POSITIVELY known to mean the\n * credential is bad answer `true`, and `strictNullChecks` is off repo-wide, so\n * an error with no `code` folds to falsy and lands on the `false` default.\n *\n * ## `auth/argument-error` is NOT purely a client fault\n *\n * firebase-admin maps a bad signature, a malformed JWT, a wrong audience or\n * issuer and an unknown `kid` to `auth/argument-error` — and falls through to\n * the same code for `KEY_FETCH_ERROR`, its own Google public-key endpoint\n * being unreachable (`lib/utils/jwt.js` in firebase-admin 14.2.0 builds that\n * message as `'Error fetching public keys for Google certs: …'`). By code\n * alone a certificate outage is a forged token, so the message is read too.\n *\n * ## Why a module of its own\n *\n * Specs replace `@aglyn/tenant-data-admin` with hand-built `jest.mock`\n * factories — 178 in the console alone — and a factory that does not list a\n * symbol makes it `undefined` rather than failing loudly. This file is its\n * own entry point, `@aglyn/tenant-data-admin/server/id-token-refusal`, which\n * no factory replaces, so the console's `invalidIdTokenResponse` and every\n * plugin handler that verifies a token classify through the same real code.\n * It imports nothing, and must keep importing nothing, for the same reason.\n *\n * ## What callers must NOT do with this\n *\n * Say which code matched. A refusal's body is the one a missing\n * Authorization header already gets; telling \"expired\" from \"revoked\" from\n * \"no such user\" answers questions about accounts for anyone who can send a\n * request.\n *==========================================*/\n\n/**\n * Codes that mean the CREDENTIAL is bad. Anything absent from this set is an\n * infrastructure failure and keeps its 5xx.\n */\nconst INVALID_CREDENTIAL_CODES: ReadonlySet<string> = new Set([\n  // The JWT itself did not check out: bad signature, malformed, wrong\n  // audience or issuer, unknown `kid`, absent or oversized `sub`.\n  'auth/argument-error',\n  'auth/id-token-expired',\n  'auth/session-cookie-expired',\n  // Revoked or locked out. `assertIdTokenNotRevoked` (AGL-1881) raises these\n  // two with codes matching the SDK's, so both arms agree.\n  'auth/id-token-revoked',\n  'auth/session-cookie-revoked',\n  'auth/user-disabled',\n  // The account behind a well-formed token is gone. Fail-closed, and it is a\n  // statement about the credential, not about our health.\n  'auth/user-not-found',\n  // A token minted in a different GCIP tenant than the pool verifying it.\n  'auth/mismatching-tenant-id',\n])\n\n/**\n * firebase-admin reports its own public-key fetch failing as\n * `auth/argument-error`. That is an OUTAGE, not a bad token.\n */\nconst KEY_FETCH_FAILURE = /error fetching public keys/i\n\n/**\n * Whether a throw from verifying an ID token (or a session cookie) says the\n * credential was refused. `true` answers 401; `false` is a failure to check\n * and must keep the caller's 5xx.\n */\nexport function isRefusedIdToken(error: unknown): boolean {\n  const code = (error as { code?: unknown } | null | undefined)?.code\n  if (typeof code !== 'string') return false\n  if (!INVALID_CREDENTIAL_CODES.has(code)) return false\n  if (code === 'auth/argument-error') {\n    const message = (error as { message?: unknown }).message\n    if (typeof message === 'string' && KEY_FETCH_FAILURE.test(message)) {\n      return false\n    }\n  }\n  return true\n}\n\n/**\n * The 401 a refused credential earns, or `null` for anything else so the\n * caller's own 500 stands (AGL-1993). Byte-identical to the body a missing\n * Authorization header already gets, and it never says WHICH code matched.\n */\nexport function invalidIdTokenResponse(error: unknown): Response | null {\n  if (!isRefusedIdToken(error)) return null\n  return Response.json({ error: 'Unauthenticated' }, { status: 401 })\n}\n"],"names":["INVALID_CREDENTIAL_CODES","Set","KEY_FETCH_FAILURE","isRefusedIdToken","error","code","has","message","test","invalidIdTokenResponse","Response","json","status"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4CA0C4C,GAE5C;;;CAGC,GACD,MAAMA,2BAAgD,IAAIC,IAAI;IAC5D,oEAAoE;IACpE,gEAAgE;IAChE;IACA;IACA;IACA,2EAA2E;IAC3E,yDAAyD;IACzD;IACA;IACA;IACA,2EAA2E;IAC3E,wDAAwD;IACxD;IACA,wEAAwE;IACxE;CACD;AAED;;;CAGC,GACD,MAAMC,oBAAoB;AAE1B;;;;CAIC,GACD,OAAO,SAASC,iBAAiBC,KAAc;IAC7C,MAAMC,OAAQD,yBAAD,AAACA,MAAiDC,IAAI;IACnE,IAAI,OAAOA,SAAS,UAAU,OAAO;IACrC,IAAI,CAACL,yBAAyBM,GAAG,CAACD,OAAO,OAAO;IAChD,IAAIA,SAAS,uBAAuB;QAClC,MAAME,UAAU,AAACH,MAAgCG,OAAO;QACxD,IAAI,OAAOA,YAAY,YAAYL,kBAAkBM,IAAI,CAACD,UAAU;YAClE,OAAO;QACT;IACF;IACA,OAAO;AACT;AAEA;;;;CAIC,GACD,OAAO,SAASE,uBAAuBL,KAAc;IACnD,IAAI,CAACD,iBAAiBC,QAAQ,OAAO;IACrC,OAAOM,SAASC,IAAI,CAAC;QAAEP,OAAO;IAAkB,GAAG;QAAEQ,QAAQ;IAAI;AACnE"}