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

package/src/lib/server/list-members.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @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 only writer of `orgs/{orgId}/lists/{listId}/members` (AGL-2499).
+ *
+ * Two enrollment routes reach this collection — the commerce newsletter
+ * handler and the workflow `enrollList` step — and they used to derive the
+ * document id two incompatible ways: a full `sha256(email)` on one side, a
+ * `hmac('aglyn-list-member', email)` truncated to 20 hex on the other. The
+ * same person subscribing by both routes became two members of one list.
+ *
+ * The id is now `personKey` on both, which is the derivation both
+ * `docs/specs/email-overhaul.md` §3d and `docs/specs/reusable-forms.md` §4
+ * specify, and it normalizes before hashing so casing cannot fork it either.
+ *
+ * ## Why a helper and not two corrected call sites
+ *
+ * Two call sites that merely agree today are what produced the split: nothing
+ * about either one said the other existed. A third route — the reusable-forms
+ * capture path is already specified — would have been written the same way.
+ * Enrolling goes through this function so that the id has one definition and
+ * no caller is offered the chance to derive its own.
+ */
+import type { DocumentReference } from 'firebase-admin/firestore';
+import { type ConsentGroup } from '@aglyn/aglyn/server';
+/**
+ * Every document id one address may be filed under on a list's `members`:
+ * the canonical key first, then the two ids earlier writers minted. A
+ * reader that must find the person wherever they were enrolled — the
+ * erasure sweep (AGL-2623) — asks for all of them with one `getAll`, the
+ * same set `enrollListMember` reads before it writes, so a member enrolled
+ * under an old id is neither missed nor duplicated.
+ */
+export declare function listMemberDocIds(email: unknown): string[];
+/**
+ * What makes an enrollment mailable, and who is answerable for it.
+ *
+ * Two values and no third. They are not interchangeable and the difference is
+ * the whole reason the basis is stored rather than implied:
+ *
+ * - `contact-opt-in` — the person ticked a box. The enrollment carries a
+ *   decision they made, and `atMs` is when THEY made it, not when the row was
+ *   written. Nobody is answerable because nobody asserted anything.
+ * - `operator-attested` — a console account stated that they have this
+ *   person's permission. That statement is itself the basis, so it is only
+ *   worth storing with the account that made it and the moment they did.
+ *
+ * Rendering the second as though it were the first is what a support or
+ * compliance question cannot recover from, which is why the basis rides
+ * beside `marketingConsent` on every row that has one.
+ */
+export type ListMemberConsentBasis = 'contact-opt-in' | 'operator-attested';
+/** A basis, with the attribution that makes it answerable. */
+export interface ListMemberConsent {
+    basis: ListMemberConsentBasis;
+    /**
+     * When the basis was recorded.
+     *
+     * For a pass-through this is the ORIGINAL opt-in moment carried over from
+     * the person's own record, because the question a consent record answers is
+     * when the person said yes — not when somebody copied their answer onto a
+     * list.
+     */
+    atMs: number;
+    /** The console account that attested. Meaningless for a pass-through. */
+    byUid?: string | null;
+    /**
+     * Why, in the operator's own terms, for whoever audits this later.
+     *
+     * Written for an attestation and ignored for a pass-through, which needs no
+     * explanation beyond the person's own record. An import fills it from what
+     * the FILE declared — the opt-in source and date the merchant supplied per
+     * row — because "a declared basis per address, not one checkbox over the
+     * file" is only worth asking for if the declaration survives onto the row
+     * it was made about.
+     */
+    reason?: string;
+}
+export interface EnrollListMemberInput {
+    /** `orgs/{orgId}/lists/{listId}` — the caller has already proved it exists. */
+    listRef: DocumentReference;
+    /**
+     * The consent group the enrollment is being made IN THE NAME OF.
+     *
+     * Lists live on the org and every site in it can mail one, so a membership
+     * carries a basis that no path could attribute to a controller. A GROUP
+     * rather than a site, because a business running three sites under one name
+     * legitimately enrolls somebody into all three at once — and an agency's
+     * client, which declared no group, gets exactly itself.
+     *
+     * Required and undefaulted: a caller that has not resolved a group has not
+     * decided who this person agreed to hear from.
+     */
+    group: ConsentGroup;
+    email: string;
+    name?: string;
+    /** Free-form provenance: `'newsletter'`, `'action:{actionId}'`. */
+    source: string;
+    /**
+     * Explicit marketing opt-in, with a consent timestamp — the same shape
+     * `upsertHostContact` and `addHostLead` already carry.
+     *
+     * A list membership had NO consent field of any kind, so `audience: 'list'`
+     * had nothing for the send-time join to read
+     * (`docs/specs/email-overhaul.md` §1d/§3f). This is the field that closes
+     * it, and it is the caller's captured checkbox: enrolling is an act, and
+     * `false`/omitted therefore writes nothing rather than a basis.
+     */
+    marketingConsent?: boolean;
+    /**
+     * The basis in full, for a caller that knows more than "a box was ticked".
+     *
+     * `marketingConsent: true` is the shorthand a capture surface uses: it means
+     * `contact-opt-in`, recorded now, asserted by nobody. Anything else — a
+     * pass-through carrying the person's ORIGINAL opt-in date, or an
+     * attestation carrying the account that made it — has to say so, and this
+     * is where it says it. The two inputs are normalized to one value before
+     * anything is written, so there is a single writer of the consent fields.
+     */
+    consent?: ListMemberConsent;
+    /**
+     * How the person got here: enrolled by hand or by an automation
+     * (`'manual'`), or selected by a dynamic list's rule (`'rule'`).
+     *
+     * The materializer needs to tell its own rows apart from a manual one on
+     * the same list, because a person who stops matching the rule leaves and a
+     * person somebody added by hand does not.
+     */
+    via?: 'manual' | 'rule';
+}
+export interface EnrolledListMember {
+    /** The document actually written — a legacy id when one was adopted. */
+    memberId: string;
+    /** True when an existing legacy-keyed row was written instead of a new one. */
+    adopted: boolean;
+    /** False when the row already existed under some id. */
+    created: boolean;
+}
+/** Why nothing was written. */
+export type EnrollListMemberRefusal = 
+/** Not an address this collection can key. Nothing to write, nothing to fix. */
+'unusable-address'
+/**
+ * The person's membership records a REFUSAL. Not overridable by any caller
+ * and not reported as a failure to fix, because the fix would be to ignore
+ * it.
+ */
+ | 'declined';
+/**
+ * Enrolled, or refused and why.
+ *
+ * A union rather than `EnrolledListMember | null`, because the two refusals
+ * are not the same event and a caller that cannot tell them apart is a caller
+ * that reports a person's recorded refusal as a malformed address.
+ */
+export type EnrollListMemberResult = ({
+    enrolled: true;
+} & EnrolledListMember) | {
+    enrolled: false;
+    refusal: EnrollListMemberRefusal;
+};
+/**
+ * Enrolls one address into a list, at one document per person.
+ *
+ * ## The legacy lookup is the migration
+ *
+ * Changing the derivation without one would strand every row written under the
+ * old ids: the next enrollment of an address already on the list would key a
+ * *new* document beside the old one, so a defect that produced duplicates only
+ * when two routes met would start producing them on a single route. Rather
+ * than rewrite those ids — a bulk operation that has to delete the row it
+ * replaces, and deleting an enrollment destroys the consent record that says
+ * the person asked to be there — the write resolves the person's existing
+ * document and keeps using it.
+ *
+ * The cost is one `getAll` of three refs, on a human-triggered signup, in
+ * place of the blind `set` this replaced. It is one round trip, not three.
+ *
+ * `addedAt` is stamped only when the document is created, so re-enrolling
+ * keeps the date the person actually joined — the same "earliest wins" collapse
+ * `docs/specs/email-overhaul.md` §3d asks a backfill to preserve.
+ *
+ * ## A recorded refusal stops every route through this function
+ *
+ * This is the only writer of the collection, so the refusal check belongs
+ * here and not at the four call sites: a guard on the button that adds
+ * somebody by hand leaves the newsletter handler, the workflow `enrollList`
+ * step and the dynamic-list materializer free to put the same person back.
+ * The membership snapshot is already in hand from the id resolution above, so
+ * the check costs no read.
+ *
+ * It answers the question about the LIST ROW. A refusal recorded on the
+ * person's CRM record is a different document this function does not fetch —
+ * a caller that can see one is expected to consult it, and the send-time
+ * consent join reads the row this function writes either way.
+ */
+export declare function enrollListMember(input: EnrollListMemberInput): Promise<EnrollListMemberResult>;

package/src/lib/server/list-members.js

@@ -0,0 +1,176 @@
+/**
+ * @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 only writer of `orgs/{orgId}/lists/{listId}/members` (AGL-2499).
+ *
+ * Two enrollment routes reach this collection — the commerce newsletter
+ * handler and the workflow `enrollList` step — and they used to derive the
+ * document id two incompatible ways: a full `sha256(email)` on one side, a
+ * `hmac('aglyn-list-member', email)` truncated to 20 hex on the other. The
+ * same person subscribing by both routes became two members of one list.
+ *
+ * The id is now `personKey` on both, which is the derivation both
+ * `docs/specs/email-overhaul.md` §3d and `docs/specs/reusable-forms.md` §4
+ * specify, and it normalizes before hashing so casing cannot fork it either.
+ *
+ * ## Why a helper and not two corrected call sites
+ *
+ * Two call sites that merely agree today are what produced the split: nothing
+ * about either one said the other existed. A third route — the reusable-forms
+ * capture path is already specified — would have been written the same way.
+ * Enrolling goes through this function so that the id has one definition and
+ * no caller is offered the chance to derive its own.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { FieldValue } from "firebase-admin/firestore";
+import { normalizeContactEmail, personKey, CAPTURED_BY_HOST_FIELD, marketingConsentFieldsForGroup, readMarketingBasis } from "@aglyn/aglyn/server";
+import { createHash, createHmac } from "node:crypto";
+/**
+ * The two ids this collection was written under before `personKey`.
+ *
+ * Read-only, and never written for a new row: they exist so an address
+ * already enrolled under a legacy id is *found* rather than duplicated. See
+ * `enrollListMember` for why that lookup is the migration.
+ *
+ * Both take the normalized address, which is what the two original call sites
+ * happened to pass — each lowercased at its own entry point before hashing, so
+ * every row already on the collection was keyed from a lowercased address even
+ * though neither derivation enforced it.
+ */ function legacyListMemberIds(normalizedEmail) {
+    return [
+        createHash('sha256').update(normalizedEmail).digest('hex'),
+        createHmac('sha256', 'aglyn-list-member').update(normalizedEmail).digest('hex').slice(0, 20)
+    ];
+}
+/**
+ * Every document id one address may be filed under on a list's `members`:
+ * the canonical key first, then the two ids earlier writers minted. A
+ * reader that must find the person wherever they were enrolled — the
+ * erasure sweep (AGL-2623) — asks for all of them with one `getAll`, the
+ * same set `enrollListMember` reads before it writes, so a member enrolled
+ * under an old id is neither missed nor duplicated.
+ */ export function listMemberDocIds(email) {
+    const normalized = normalizeContactEmail(email);
+    if (!normalized) return [];
+    const key = personKey(normalized);
+    if (!key) return [];
+    return [
+        key,
+        ...legacyListMemberIds(normalized).filter((id)=>id !== key)
+    ];
+}
+/**
+ * Enrolls one address into a list, at one document per person.
+ *
+ * ## The legacy lookup is the migration
+ *
+ * Changing the derivation without one would strand every row written under the
+ * old ids: the next enrollment of an address already on the list would key a
+ * *new* document beside the old one, so a defect that produced duplicates only
+ * when two routes met would start producing them on a single route. Rather
+ * than rewrite those ids — a bulk operation that has to delete the row it
+ * replaces, and deleting an enrollment destroys the consent record that says
+ * the person asked to be there — the write resolves the person's existing
+ * document and keeps using it.
+ *
+ * The cost is one `getAll` of three refs, on a human-triggered signup, in
+ * place of the blind `set` this replaced. It is one round trip, not three.
+ *
+ * `addedAt` is stamped only when the document is created, so re-enrolling
+ * keeps the date the person actually joined — the same "earliest wins" collapse
+ * `docs/specs/email-overhaul.md` §3d asks a backfill to preserve.
+ *
+ * ## A recorded refusal stops every route through this function
+ *
+ * This is the only writer of the collection, so the refusal check belongs
+ * here and not at the four call sites: a guard on the button that adds
+ * somebody by hand leaves the newsletter handler, the workflow `enrollList`
+ * step and the dynamic-list materializer free to put the same person back.
+ * The membership snapshot is already in hand from the id resolution above, so
+ * the check costs no read.
+ *
+ * It answers the question about the LIST ROW. A refusal recorded on the
+ * person's CRM record is a different document this function does not fetch —
+ * a caller that can see one is expected to consult it, and the send-time
+ * consent join reads the row this function writes either way.
+ */ export async function enrollListMember(input) {
+    var _ref, _input_consent, _consent_byUid, _consent_reason;
+    const email = normalizeContactEmail(input.email);
+    if (!email) return {
+        enrolled: false,
+        refusal: 'unusable-address'
+    };
+    const key = personKey(email);
+    if (!key) return {
+        enrolled: false,
+        refusal: 'unusable-address'
+    };
+    const members = input.listRef.collection('members');
+    const canonicalRef = members.doc(key);
+    const legacyRefs = legacyListMemberIds(email)// A legacy derivation that happens to agree with `personKey` — `sha256` of
+    // the same normalized address does — must not be fetched twice: `getAll`
+    // rejects duplicate references.
+    .filter((id)=>id !== key).map((id)=>members.doc(id));
+    const snapshots = await input.listRef.firestore.getAll(canonicalRef, ...legacyRefs);
+    const existing = snapshots.find((snapshot)=>snapshot.exists);
+    const target = (_ref = existing == null ? void 0 : existing.ref) != null ? _ref : canonicalRef;
+    if (existing && readMarketingBasis(existing.data(), input.group).basis === 'declined') {
+        return {
+            enrolled: false,
+            refusal: 'declined'
+        };
+    }
+    /*
+   * ONE value from the two ways a caller may state a basis.
+   *
+   * `marketingConsent: true` is a capture surface saying "a box was ticked
+   * just now", which is `contact-opt-in` recorded at this moment with nobody
+   * asserting it. Normalizing here rather than branching at the write is what
+   * keeps the consent fields to a single writer — two branches stamping
+   * overlapping subsets of them is how a row comes to carry a basis with no
+   * timestamp, or a timestamp with no basis.
+   */ const consent = (_input_consent = input.consent) != null ? _input_consent : input.marketingConsent ? {
+        basis: 'contact-opt-in',
+        atMs: Date.now()
+    } : null;
+    await target.set(_extends({
+        email
+    }, input.name ? {
+        name: input.name
+    } : {}, {
+        source: input.source
+    }, input.via ? {
+        via: input.via
+    } : {}, consent ? marketingConsentFieldsForGroup(input.group, consent.atMs, {
+        marketingConsentBasis: consent.basis,
+        marketingConsentByUid: (_consent_byUid = consent.byUid) != null ? _consent_byUid : null,
+        marketingConsentReason: (_consent_reason = consent.reason) != null ? _consent_reason : ''
+    }) : {}, existing ? {} : {
+        addedAt: FieldValue.serverTimestamp(),
+        [CAPTURED_BY_HOST_FIELD]: [
+            input.group.hostId
+        ]
+    }), {
+        merge: true
+    });
+    return {
+        enrolled: true,
+        memberId: target.id,
+        adopted: target.id !== key,
+        created: !existing
+    };
+}
+
+//# sourceMappingURL=list-members.js.map

package/src/lib/server/list-members.js.map

@@ -0,0 +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  marketingConsentFieldsForGroup,\n  readMarketingBasis,\n  type ConsentGroup,\n} from '@aglyn/aglyn/server'\nimport { createHash, createHmac } from 'node:crypto'\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   * 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  await target.set(\n    {\n      email,\n      ...(input.name ? { name: input.name } : {}),\n      source: input.source,\n      ...(input.via ? { via: input.via } : {}),\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      ...(consent\n        ? marketingConsentFieldsForGroup(input.group, consent.atMs, {\n            marketingConsentBasis: consent.basis,\n            marketingConsentByUid: consent.byUid ?? null,\n            marketingConsentReason: consent.reason ?? '',\n          })\n        : {}),\n      ...(existing\n        ? {}\n        : {\n            addedAt: FieldValue.serverTimestamp(),\n            [CAPTURED_BY_HOST_FIELD]: [input.group.hostId],\n          }),\n    },\n    { merge: true },\n  )\n\n  return {\n    enrolled: true,\n    memberId: target.id,\n    adopted: target.id !== key,\n    created: !existing,\n  }\n}\n"],"names":["FieldValue","normalizeContactEmail","personKey","CAPTURED_BY_HOST_FIELD","marketingConsentFieldsForGroup","readMarketingBasis","createHash","createHmac","legacyListMemberIds","normalizedEmail","update","digest","slice","listMemberDocIds","email","normalized","key","filter","id","enrollListMember","input","consent","enrolled","refusal","members","listRef","collection","canonicalRef","doc","legacyRefs","map","snapshots","firestore","getAll","existing","find","snapshot","exists","target","ref","data","group","basis","marketingConsent","atMs","Date","now","set","name","source","via","marketingConsentBasis","marketingConsentByUid","byUid","marketingConsentReason","reason","addedAt","serverTimestamp","hostId","merge","memberId","adopted","created"],"mappings":"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"}

package/src/lib/server/live-page-usage.d.ts

@@ -0,0 +1,202 @@
+/**
+ * @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.
+ */
+/**
+ * Which live pages a change reaches, for a site's screens, layouts and
+ * components.
+ *
+ * The corpus read and the two closures over it, held here rather than in the
+ * console because the console is no longer the only side that needs them. A
+ * dataset record is written from the tenant as well — a form submission, an
+ * automation step — and those writes make the same pages stale as a console
+ * edit does. Two implementations of "which screens render this" is the shape
+ * that put AGL-1223 in the tree: one reader handled a node tree's second
+ * storage form and the other did not, so half the corpus answered "used
+ * nowhere" and a publish dropped no cache.
+ *
+ * Nothing here is dataset-specific, and nothing is console-specific. The
+ * console's `scan-artifact-usage` re-exports these and keeps the parts that
+ * are about the console's own "what would I break" copy.
+ */
+import { type ReusableComponentProp } from '@aglyn/aglyn/server';
+/** A screen/layout/component reduced to what a usage scan needs. */
+export interface UsageCandidate {
+    id: string;
+    displayName?: string;
+    /** Legacy field some older documents used instead of `displayName`. */
+    name?: string;
+    deletedAt?: unknown;
+    /**
+     * Node tree to search. For screens and layouts this is the PUBLISHED
+     * version's nodes (what visitors see); for components it is the definition
+     * tree off the component document, which is what the runtime reads.
+     */
+    nodes?: Record<string, any> | null;
+    /** Published version, carried through so the caller can deep-link. */
+    versionId?: string;
+    /** Screens only: the layout they render inside. */
+    layoutId?: string;
+    /** Screens only: the screen they nest under, which is part of their path. */
+    parentId?: string;
+    /**
+     * Components only: the properties the definition declares (AGL-1247). A
+     * Link property's default renders as a link wherever an instance leaves the
+     * property unset, and it is stored here, not in `nodes` (AGL-2846).
+     */
+    props?: ReadonlyArray<ReusableComponentProp | null | undefined> | null;
+}
+/** One document that depends on the artifact a scan was asked about. */
+export interface UsageDependent {
+    type: 'screen' | 'layout' | 'component' | 'collection';
+    id: string;
+    name: string;
+    via: Array<'id' | 'name'>;
+    versionId?: string;
+    /**
+     * HOW the dependent references the artifact — screens and collection
+     * listings (AGL-703, AGL-2806).
+     *
+     * A component or a layout has exactly one kind of dependent and the noun
+     * says everything: an instance, or a binding. A screen has three, and they
+     * break in three different ways — a link goes dead, a child moves, a
+     * collection loses the page it renders through. Copy that could not tell
+     * them apart would have to describe the worst case every time. A collection
+     * listing's dependents are all links, and say so.
+     */
+    relation?: 'link' | 'child' | 'template';
+}
+/** The three corpora every closure below walks. */
+export interface UsageSources {
+    screens: UsageCandidate[];
+    layouts: UsageCandidate[];
+    components: UsageCandidate[];
+}
+/** `displayName`, falling back to a legacy `name`, then the raw id. */
+export declare function usageCandidateLabel(candidate: UsageCandidate): string;
+/** A soft-deleted document renders nothing, so it depends on nothing. */
+export declare const isLiveUsageCandidate: (candidate: UsageCandidate) => boolean;
+/**
+ * Everything that references a reusable component (AGL-703).
+ *
+ * Three places, because the renderer expands instances in three places:
+ * published screen versions, published layout versions, and OTHER component
+ * definitions — `composeReusableComponentNodes` grafts nested instances, so
+ * a component used only inside another component is genuinely used. Omitting
+ * that third scan would report "used nowhere" for it and invite a confident
+ * deletion, which is worse than showing nothing at all.
+ */
+export declare function scanComponentUsage(componentId: string, sources: UsageSources): UsageDependent[];
+/**
+ * Everything rendering inside a layout (AGL-703).
+ *
+ * Two kinds of dependent, both expressed by the same `layoutId` pointer:
+ *
+ * - **screens**, which name the layout they render inside;
+ * - **other layouts**, since a layout can itself sit inside one. A nested
+ *   layout is a real dependent — deleting its parent unwraps every screen
+ *   underneath it — so leaving layouts out would report a parent layout as
+ *   used only by the screens that name it directly, and none of the ones
+ *   that reach it through a child.
+ *
+ * A layout never counts as its own dependent; `canNestLayout` refuses that,
+ * and this refuses to report it even if stored data holds one.
+ */
+export declare function scanLayoutUsage(layoutId: string, screens: UsageCandidate[], layouts?: UsageCandidate[]): UsageDependent[];
+/**
+ * Every live screen rendered inside `layoutId`, at ANY nesting depth
+ * (AGL-1150).
+ *
+ * `scanLayoutUsage` answers one level. Layouts nest — a screen points at a
+ * layout, which can point at a parent layout, and `compose-screen-nodes` walks
+ * that whole chain when composing a page. So publishing a layout changes every
+ * screen below it, not just the ones bound to it directly, and a cache drop
+ * that only handles the direct level leaves the rest showing stale chrome for
+ * the full revalidate window.
+ *
+ * Pure, and separate from the Firestore read, so the nesting behaviour is
+ * testable without a database.
+ *
+ * Cycle-safe. `canNestLayout` refuses to create a cycle, but a document written
+ * straight to Firestore is not bound by that, and a cycle here would hang a
+ * publish request rather than surface anything.
+ */
+export declare function screenIdsUsingLayoutDeep(layoutId: string, screens: UsageCandidate[], layouts?: UsageCandidate[]): string[];
+/**
+ * Every live screen whose rendered output contains `componentId`, however
+ * indirectly (AGL-1161).
+ *
+ * `scanComponentUsage` answers one level and returns three kinds of dependent.
+ * Only one of them is a screen, and the other two both reach screens by routes
+ * a single-level scan cannot see:
+ *
+ * - a **component** dependent nests the target inside itself, and that outer
+ *   component may itself only be used inside a third — so component→component
+ *   edges have to be followed to a fixed point;
+ * - a **layout** dependent puts the component in page chrome, which every
+ *   screen under that layout renders. Layouts nest, so that is
+ *   `screenIdsUsingLayoutDeep`, not a direct `layoutId` match.
+ *
+ * Miss either and a publish reports success while some pages keep serving the
+ * old component for the full revalidate window — the failure this whole arc
+ * exists to remove, and the one that is hardest to notice because the pages
+ * that ARE dropped update instantly.
+ *
+ * Pure, and separate from the Firestore read, so the closure is testable
+ * without a database — the same split `screenIdsUsingLayoutDeep` uses.
+ *
+ * Cycle-safe. `composeReusableComponentNodes` would not survive a cycle, but a
+ * document written straight to Firestore is not bound by what the editor
+ * allows, and a cycle here would hang a publish rather than surface anything.
+ */
+export declare function screenIdsUsingComponentDeep(componentId: string, sources: UsageSources): string[];
+export interface UsageCandidateRead {
+    candidates: UsageCandidate[];
+    /**
+     * The collection held more documents than `limit` allowed, so the scan below
+     * it is INCOMPLETE.
+     *
+     * Returned rather than logged, because the two callers owe the user
+     * different things: an advisory "what would I break" can show a partial
+     * answer and say so, while a cache drop that silently scans a prefix reports
+     * a successful publish and leaves real pages stale.
+     */
+    truncated: boolean;
+}
+/**
+ * One collection's documents, with published nodes attached when the scan
+ * needs to search them.
+ *
+ * `limit` is a real bound, not a guess: it is fetched with one extra document
+ * so exceeding it is DETECTED rather than assumed away. A caller that ignores
+ * `truncated` is choosing to be wrong quietly.
+ */
+export declare function readUsageCandidates(hostRef: FirebaseFirestore.DocumentReference, collectionName: 'screens' | 'layouts' | 'components', options: {
+    withNodes: boolean;
+    limit: number;
+}): Promise<UsageCandidateRead>;
+/**
+ * Every screen, layout and component of a site, with their node trees — the
+ * corpus every tree-searching closure above walks.
+ *
+ * Each collection ONCE, in memory: a query per level would multiply round
+ * trips by the nesting depth of the graph. Shared so two scans cannot read
+ * different corpora under different bounds, and a change to one cannot quietly
+ * narrow the other.
+ */
+export declare function readUsageSources(hostRef: FirebaseFirestore.DocumentReference, limit: number): Promise<{
+    candidates: UsageSources;
+    truncated: boolean;
+}>;