@aglyn/tenant-data-admin 1.0.0-beta.202 → 1.0.0-beta.204

package/src/lib/server/held-page-subject.js

@@ -0,0 +1,206 @@
+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.
+ */ /*==========================================
+ * WHICH PAGE WAS HELD, AND WHERE IT LIVES (AGL-3374).
+ *
+ * `describeHeldPage` turns the screen id the page review holds into a
+ * {@link HeldPageSubject} (`@aglyn/shared-util-email/held-page`): the page's
+ * kind, name and route, the entry it was showing, the layout or component
+ * the flagged content came from, and what visitors see meanwhile.
+ *
+ * Run once per review row, never per render: the page review calls it only
+ * when it files a row that does not describe its page yet, so the reads it
+ * may make — the screen document, the collection that designates a
+ * template, the site's usage corpus when a layout or component is the
+ * source — are paid once for a page that was flagged, and never for a clean
+ * one.
+ *
+ * The composer knows most of this already and hands it over as a
+ * {@link HostedPageContext}; the reads here are the fallback for a caller
+ * that does not, and for a page kind the caller cannot see (a layout's
+ * content is only a layout's to the one who composed it).
+ *=========================================*/ import { TENANT_APEX } from "@aglyn/aglyn/app-utils/host-naming";
+import { screenHostedPage } from "@aglyn/shared-util-email/hosted-page-screen";
+import firebaseAdmin from "./firebase-admin.js";
+import { readUsageSources, screenIdsUsingComponentDeep, screenIdsUsingLayoutDeep } from "./live-page-usage.js";
+import { canonicalJson } from "./outbound-send-review.js";
+/** The site's public origin, or null when it has no address yet. */ export function hostOrigin(host) {
+    const subdomain = typeof (host == null ? void 0 : host['subdomain']) === 'string' ? host['subdomain'] : '';
+    const cname = typeof (host == null ? void 0 : host['cname']) === 'string' ? host['cname'] : '';
+    if (cname) return `https://${cname}`;
+    if (subdomain) return `https://${subdomain}.${TENANT_APEX}`;
+    return null;
+}
+/**
+ * A screen's route from the host routing map: `/about`, `/` for the index.
+ * Null when the map does not route it — a template, an error screen, an
+ * unpublished page. Never the site root for a page the map does not name:
+ * that was the row that called a video template "https://aglyn.com/".
+ */ export function routedScreenPath(host, screenId) {
+    var _ref;
+    const screens = (_ref = host == null ? void 0 : host['screens']) != null ? _ref : {};
+    const raw = screens[screenId];
+    if (typeof raw !== 'string') return null;
+    const clean = raw.replace(/^\/+|\/+$/g, '');
+    return clean === 'index' || clean === '' ? '/' : `/${clean}`;
+}
+function text(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+function hostRef(hostId) {
+    return firebaseAdmin.app().firestore().collection('hosts').doc(hostId);
+}
+/**
+ * The collection route a template screen renders, by the three fields a
+ * collection designates one with (the runtime's own resolution: list through
+ * `listScreenId`, entry through `entryScreenId` then the legacy
+ * `templateScreenId`). Null when no collection names it.
+ */ async function collectionTemplateOf(hostId, screenId) {
+    const collections = hostRef(hostId).collection('collections');
+    for (const [field, role] of [
+        [
+            'entryScreenId',
+            'entry'
+        ],
+        [
+            'templateScreenId',
+            'entry'
+        ],
+        [
+            'listScreenId',
+            'list'
+        ]
+    ]){
+        const found = await collections.where(field, '==', screenId).limit(1).get();
+        const doc = found.docs[0];
+        const slug = text(doc == null ? void 0 : doc.get('slug'));
+        if (doc && slug) return {
+            role,
+            slug,
+            name: text(doc.get('displayName'))
+        };
+    }
+    return null;
+}
+function signalKeys(signals) {
+    return new Set(signals.map((signal)=>canonicalJson(signal)));
+}
+/**
+ * Which part of the page carries the flagged content. The page's own nodes
+ * first — when they carry any of it, the page is the source and nothing else
+ * is named; otherwise the first layout, then the first component, that does.
+ */ export function attributeHeldSignals(parts, signals, identity) {
+    var _ref, _parts_find;
+    const held = signalKeys(signals);
+    const carries = (part)=>screenHostedPage(_extends({
+            nodes: part.nodes
+        }, identity)).signals.some((signal)=>held.has(canonicalJson(signal)));
+    const own = parts.filter((part)=>part.type === 'screen');
+    if (own.some(carries)) return null;
+    return (_ref = (_parts_find = parts.find((part)=>part.type === 'layout' && carries(part))) != null ? _parts_find : parts.find((part)=>part.type === 'component' && carries(part))) != null ? _ref : null;
+}
+/** How many live pages render a layout or component, or null past the corpus bound. */ async function pagesUsing(hostId, part) {
+    try {
+        const { candidates, truncated } = await readUsageSources(hostRef(hostId), 500);
+        if (truncated) return null;
+        const ids = part.type === 'layout' ? screenIdsUsingLayoutDeep(part.id, candidates.screens, candidates.layouts) : screenIdsUsingComponentDeep(part.id, candidates);
+        return ids.length;
+    } catch (unused) {
+        return null;
+    }
+}
+async function sourceOf(hostId, part) {
+    let name = text(part.name);
+    if (!name) {
+        var _text;
+        const doc = await hostRef(hostId).collection(part.type === 'layout' ? 'layouts' : 'components').doc(part.id).get().catch(()=>null);
+        name = (_text = text(doc == null ? void 0 : doc.get('displayName'))) != null ? _text : text(doc == null ? void 0 : doc.get('name'));
+    }
+    return {
+        type: part.type === 'layout' ? 'layout' : 'component',
+        id: part.id,
+        name,
+        pagesUsing: await pagesUsing(hostId, part)
+    };
+}
+/**
+ * Describe the reviewed page. Best effort throughout: a read that fails
+ * leaves its field empty, and the subject still names what it can — it is a
+ * label on a decision already made, never a reason to change it.
+ */ export async function describeHeldPage(input) {
+    var _input_page, _page_screen, _text;
+    const page = (_input_page = input.page) != null ? _input_page : {};
+    let screen = (_page_screen = page.screen) != null ? _page_screen : null;
+    if (!screen) {
+        screen = await hostRef(input.hostId).collection('screens').doc(input.screenId).get().then((doc)=>{
+            var _doc_data;
+            return doc.exists ? (_doc_data = doc.data()) != null ? _doc_data : null : null;
+        }).catch(()=>null);
+    }
+    const name = (_text = text(screen == null ? void 0 : screen.displayName)) != null ? _text : text(screen == null ? void 0 : screen.name);
+    const origin = hostOrigin(input.host);
+    const routed = routedScreenPath(input.host, input.screenId);
+    let kind = 'screen';
+    let route = routed;
+    let collectionName = null;
+    let entryPath = null;
+    let fallback = 'not-found';
+    if (page.template) {
+        var _page_template_fallback;
+        kind = page.template.role === 'list' ? 'list-template' : 'entry-template';
+        route = page.template.route;
+        collectionName = text(page.template.collectionName);
+        entryPath = text(page.template.entryPath);
+        fallback = (_page_template_fallback = page.template.fallback) != null ? _page_template_fallback : 'not-found';
+    } else if (!page.variant && !routed) {
+        // Not routed and not handed over: a template the caller did not
+        // describe, or an error screen.
+        const template = await collectionTemplateOf(input.hostId, input.screenId).catch(()=>null);
+        if (template) {
+            kind = template.role === 'list' ? 'list-template' : 'entry-template';
+            route = template.role === 'list' ? `/${template.slug}` : `/${template.slug}/:slug`;
+            collectionName = template.name;
+            fallback = 'built-in-design';
+        } else if ((screen == null ? void 0 : screen.kind) === 'error') {
+            kind = 'error-screen';
+        }
+    }
+    if (page.variant) kind = 'variant';
+    let source = null;
+    if (page.parts) {
+        const parts = await page.parts().catch(()=>[]);
+        const part = attributeHeldSignals(parts, input.signals, input.identity);
+        if (part) source = await sourceOf(input.hostId, part);
+    }
+    const visitorView = input.live ? 'live' : kind === 'variant' ? 'published-version' : input.previousVersionId && input.previousVersionId !== input.versionId ? 'previous-version' : kind === 'list-template' || kind === 'entry-template' ? fallback : 'not-found';
+    const addressable = kind === 'screen' || kind === 'list-template' || kind === 'variant';
+    return {
+        kind,
+        screenId: input.screenId,
+        versionId: input.versionId,
+        name,
+        route,
+        url: origin && route && addressable ? `${origin}${route === '/' ? '/' : route}` : null,
+        entryUrl: origin && entryPath ? `${origin}${entryPath}` : null,
+        collectionName,
+        variantName: page.variant ? text(page.variant.name) : null,
+        source,
+        visitorView
+    };
+}
+
+//# sourceMappingURL=held-page-subject.js.map

package/src/lib/server/held-page-subject.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/held-page-subject.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 * WHICH PAGE WAS HELD, AND WHERE IT LIVES (AGL-3374).\n *\n * `describeHeldPage` turns the screen id the page review holds into a\n * {@link HeldPageSubject} (`@aglyn/shared-util-email/held-page`): the page's\n * kind, name and route, the entry it was showing, the layout or component\n * the flagged content came from, and what visitors see meanwhile.\n *\n * Run once per review row, never per render: the page review calls it only\n * when it files a row that does not describe its page yet, so the reads it\n * may make — the screen document, the collection that designates a\n * template, the site's usage corpus when a layout or component is the\n * source — are paid once for a page that was flagged, and never for a clean\n * one.\n *\n * The composer knows most of this already and hands it over as a\n * {@link HostedPageContext}; the reads here are the fallback for a caller\n * that does not, and for a page kind the caller cannot see (a layout's\n * content is only a layout's to the one who composed it).\n *=========================================*/\n\nimport { TENANT_APEX } from '@aglyn/aglyn/app-utils/host-naming'\nimport type {\n  HeldPageKind,\n  HeldPageSource,\n  HeldPageSubject,\n  HeldPageVisitorView,\n} from '@aglyn/shared-util-email/held-page'\nimport { screenHostedPage } from '@aglyn/shared-util-email/hosted-page-screen'\nimport type { PhishingScreenSignal } from '@aglyn/shared-util-email/outbound-phishing-screen'\nimport firebaseAdmin from './firebase-admin'\nimport {\n  readUsageSources,\n  screenIdsUsingComponentDeep,\n  screenIdsUsingLayoutDeep,\n} from './live-page-usage'\nimport { canonicalJson } from './outbound-send-review'\n\n/** One document that composes into the page, for attributing a signal. */\nexport interface HostedPagePart {\n  type: 'screen' | 'layout' | 'component'\n  id: string\n  name?: string | null\n  nodes: unknown\n}\n\n/** What the composer knows about the page it is reviewing. */\nexport interface HostedPageContext {\n  /** The screen document it composed (its name and `kind`). */\n  screen?: { displayName?: unknown; name?: unknown; kind?: unknown } | null\n  /**\n   * A template composed against a routed listing or entry: its route pattern\n   * (`/videos`, `/videos/:slug`), what it renders, the address being shown,\n   * and what a visitor gets when the template has no clean version.\n   */\n  template?: {\n    role: 'list' | 'entry'\n    route: string\n    collectionName?: string | null\n    entryPath?: string | null\n    fallback?: 'built-in-design' | 'not-found'\n  } | null\n  /** An experiment variant's version of the page. */\n  variant?: { experimentId: string; variantId: string; name?: string | null } | null\n  /** The page's own nodes and those of each layout and component composed into it. */\n  parts?: () => Promise<HostedPagePart[]>\n}\n\n/** The site's public origin, or null when it has no address yet. */\nexport function hostOrigin(host: Record<string, unknown> | null | undefined): string | null {\n  const subdomain = typeof host?.['subdomain'] === 'string' ? (host['subdomain'] as string) : ''\n  const cname = typeof host?.['cname'] === 'string' ? (host['cname'] as string) : ''\n  if (cname) return `https://${cname}`\n  if (subdomain) return `https://${subdomain}.${TENANT_APEX}`\n  return null\n}\n\n/**\n * A screen's route from the host routing map: `/about`, `/` for the index.\n * Null when the map does not route it — a template, an error screen, an\n * unpublished page. Never the site root for a page the map does not name:\n * that was the row that called a video template \"https://aglyn.com/\".\n */\nexport function routedScreenPath(\n  host: Record<string, unknown> | null | undefined,\n  screenId: string,\n): string | null {\n  const screens = (host?.['screens'] ?? {}) as Record<string, unknown>\n  const raw = screens[screenId]\n  if (typeof raw !== 'string') return null\n  const clean = raw.replace(/^\\/+|\\/+$/g, '')\n  return clean === 'index' || clean === '' ? '/' : `/${clean}`\n}\n\nfunction text(value: unknown): string | null {\n  return typeof value === 'string' && value.trim() ? value.trim() : null\n}\n\nfunction hostRef(hostId: string) {\n  return firebaseAdmin.app().firestore().collection('hosts').doc(hostId)\n}\n\n/**\n * The collection route a template screen renders, by the three fields a\n * collection designates one with (the runtime's own resolution: list through\n * `listScreenId`, entry through `entryScreenId` then the legacy\n * `templateScreenId`). Null when no collection names it.\n */\nasync function collectionTemplateOf(\n  hostId: string,\n  screenId: string,\n): Promise<{ role: 'list' | 'entry'; slug: string; name: string | null } | null> {\n  const collections = hostRef(hostId).collection('collections')\n  for (const [field, role] of [\n    ['entryScreenId', 'entry'],\n    ['templateScreenId', 'entry'],\n    ['listScreenId', 'list'],\n  ] as const) {\n    const found = await collections.where(field, '==', screenId).limit(1).get()\n    const doc = found.docs[0]\n    const slug = text(doc?.get('slug'))\n    if (doc && slug) return { role, slug, name: text(doc.get('displayName')) }\n  }\n  return null\n}\n\nfunction signalKeys(signals: readonly PhishingScreenSignal[]): Set<string> {\n  return new Set(signals.map((signal) => canonicalJson(signal)))\n}\n\n/**\n * Which part of the page carries the flagged content. The page's own nodes\n * first — when they carry any of it, the page is the source and nothing else\n * is named; otherwise the first layout, then the first component, that does.\n */\nexport function attributeHeldSignals(\n  parts: readonly HostedPagePart[],\n  signals: readonly PhishingScreenSignal[],\n  identity: { ownNames?: readonly (string | null | undefined)[]; ownDomains?: readonly (string | null | undefined)[] },\n): HostedPagePart | null {\n  const held = signalKeys(signals)\n  const carries = (part: HostedPagePart) =>\n    screenHostedPage({ nodes: part.nodes, ...identity }).signals.some((signal) =>\n      held.has(canonicalJson(signal)),\n    )\n  const own = parts.filter((part) => part.type === 'screen')\n  if (own.some(carries)) return null\n  return (\n    parts.find((part) => part.type === 'layout' && carries(part)) ??\n    parts.find((part) => part.type === 'component' && carries(part)) ??\n    null\n  )\n}\n\n/** How many live pages render a layout or component, or null past the corpus bound. */\nasync function pagesUsing(hostId: string, part: HostedPagePart): Promise<number | null> {\n  try {\n    const { candidates, truncated } = await readUsageSources(hostRef(hostId), 500)\n    if (truncated) return null\n    const ids =\n      part.type === 'layout'\n        ? screenIdsUsingLayoutDeep(part.id, candidates.screens, candidates.layouts)\n        : screenIdsUsingComponentDeep(part.id, candidates)\n    return ids.length\n  } catch {\n    return null\n  }\n}\n\nasync function sourceOf(\n  hostId: string,\n  part: HostedPagePart,\n): Promise<HeldPageSource> {\n  let name = text(part.name)\n  if (!name) {\n    const doc = await hostRef(hostId)\n      .collection(part.type === 'layout' ? 'layouts' : 'components')\n      .doc(part.id)\n      .get()\n      .catch(() => null)\n    name = text(doc?.get('displayName')) ?? text(doc?.get('name'))\n  }\n  return {\n    type: part.type === 'layout' ? 'layout' : 'component',\n    id: part.id,\n    name,\n    pagesUsing: await pagesUsing(hostId, part),\n  }\n}\n\n/**\n * Describe the reviewed page. Best effort throughout: a read that fails\n * leaves its field empty, and the subject still names what it can — it is a\n * label on a decision already made, never a reason to change it.\n */\nexport async function describeHeldPage(input: {\n  hostId: string\n  screenId: string\n  versionId: string\n  host: Record<string, unknown> | null\n  page?: HostedPageContext | null\n  signals: readonly PhishingScreenSignal[]\n  identity: { ownNames?: readonly (string | null | undefined)[]; ownDomains?: readonly (string | null | undefined)[] }\n  /** The page was already live and keeps serving (the flag path). */\n  live: boolean\n  /** The last version the page served clean, if any. */\n  previousVersionId: string | null\n}): Promise<HeldPageSubject> {\n  const page = input.page ?? {}\n  let screen = page.screen ?? null\n  if (!screen) {\n    screen = await hostRef(input.hostId)\n      .collection('screens')\n      .doc(input.screenId)\n      .get()\n      .then((doc) => (doc.exists ? (doc.data() ?? null) : null))\n      .catch(() => null)\n  }\n  const name = text(screen?.displayName) ?? text(screen?.name)\n  const origin = hostOrigin(input.host)\n  const routed = routedScreenPath(input.host, input.screenId)\n\n  let kind: HeldPageKind = 'screen'\n  let route: string | null = routed\n  let collectionName: string | null = null\n  let entryPath: string | null = null\n  let fallback: 'built-in-design' | 'not-found' = 'not-found'\n\n  if (page.template) {\n    kind = page.template.role === 'list' ? 'list-template' : 'entry-template'\n    route = page.template.route\n    collectionName = text(page.template.collectionName)\n    entryPath = text(page.template.entryPath)\n    fallback = page.template.fallback ?? 'not-found'\n  } else if (!page.variant && !routed) {\n    // Not routed and not handed over: a template the caller did not\n    // describe, or an error screen.\n    const template = await collectionTemplateOf(input.hostId, input.screenId).catch(() => null)\n    if (template) {\n      kind = template.role === 'list' ? 'list-template' : 'entry-template'\n      route = template.role === 'list' ? `/${template.slug}` : `/${template.slug}/:slug`\n      collectionName = template.name\n      fallback = 'built-in-design'\n    } else if (screen?.kind === 'error') {\n      kind = 'error-screen'\n    }\n  }\n  if (page.variant) kind = 'variant'\n\n  let source: HeldPageSource | null = null\n  if (page.parts) {\n    const parts = await page.parts().catch(() => [] as HostedPagePart[])\n    const part = attributeHeldSignals(parts, input.signals, input.identity)\n    if (part) source = await sourceOf(input.hostId, part)\n  }\n\n  const visitorView: HeldPageVisitorView = input.live\n    ? 'live'\n    : kind === 'variant'\n      ? 'published-version'\n      : input.previousVersionId && input.previousVersionId !== input.versionId\n        ? 'previous-version'\n        : kind === 'list-template' || kind === 'entry-template'\n          ? fallback\n          : 'not-found'\n\n  const addressable = kind === 'screen' || kind === 'list-template' || kind === 'variant'\n  return {\n    kind,\n    screenId: input.screenId,\n    versionId: input.versionId,\n    name,\n    route,\n    url: origin && route && addressable ? `${origin}${route === '/' ? '/' : route}` : null,\n    entryUrl: origin && entryPath ? `${origin}${entryPath}` : null,\n    collectionName,\n    variantName: page.variant ? text(page.variant.name) : null,\n    source,\n    visitorView,\n  }\n}\n"],"names":["TENANT_APEX","screenHostedPage","firebaseAdmin","readUsageSources","screenIdsUsingComponentDeep","screenIdsUsingLayoutDeep","canonicalJson","hostOrigin","host","subdomain","cname","routedScreenPath","screenId","screens","raw","clean","replace","text","value","trim","hostRef","hostId","app","firestore","collection","doc","collectionTemplateOf","collections","field","role","found","where","limit","get","docs","slug","name","signalKeys","signals","Set","map","signal","attributeHeldSignals","parts","identity","held","carries","part","nodes","some","has","own","filter","type","find","pagesUsing","candidates","truncated","ids","id","layouts","length","sourceOf","catch","describeHeldPage","input","page","screen","then","exists","data","displayName","origin","routed","kind","route","collectionName","entryPath","fallback","template","variant","source","visitorView","live","previousVersionId","versionId","addressable","url","entryUrl","variantName"],"mappings":"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"}

package/src/lib/server/host-email-tokens.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type RenderedHostEmail } from '@aglyn/shared-util-email';
+import { type EmailChrome, type EmailTheme, type LoadedHostEmail, type RenderedHostEmail } from '@aglyn/shared-util-email';
 /**
  * `renderHostEmail` with `host.*` tokens resolved (AGL-1022).
  *
@@ -44,4 +44,45 @@ import { type RenderedHostEmail } from '@aglyn/shared-util-email';
 export declare function renderHostEmailWithTokens(firestore: FirebaseFirestore.Firestore, hostId: string, templateKey: string, merge?: Record<string, string>, options?: {
     origin?: string;
 }): Promise<RenderedHostEmail | null>;
+/** A site email loaded once for a batch, with the site's tokens beside it. */
+export interface LoadedHostEmailWithTokens {
+    loaded: LoadedHostEmail;
+    hostMerge: Record<string, string>;
+}
+/**
+ * {@link loadHostEmail} for a batch (AGL-3370): the template, or the built-in
+ * copy in the site's header and footer, read ONCE, with the site's `host.*`
+ * tokens beside it for {@link renderLoadedHostEmailWithTokens}. `null` only
+ * for a key with neither, so the batch keeps its own copy.
+ */
+export declare function loadHostEmailWithTokens(firestore: FirebaseFirestore.Firestore, hostId: string, templateKey: string, options?: {
+    origin?: string;
+}): Promise<LoadedHostEmailWithTokens | null>;
+/** One recipient's copy of a batch-loaded site email; no reads. */
+export declare function renderLoadedHostEmailWithTokens(bundle: LoadedHostEmailWithTokens, merge?: Record<string, string>): RenderedHostEmail | null;
+/**
+ * The site's header and footer for one kind of email, its theme, and the
+ * origin and host a stored logo reference resolves against (AGL-3370): for a sender
+ * that renders per recipient itself, such as a typed campaign.
+ */
+export declare function siteEmailFrame(firestore: FirebaseFirestore.Firestore, hostId: string, templateKey: string): Promise<{
+    chrome: EmailChrome;
+    theme: EmailTheme;
+    mediaOrigin?: string;
+    mediaHostId: string;
+}>;
+/**
+ * A text-only site email in the site's header and footer (AGL-3370): a
+ * workflow's email step, or a message a site sends in words nobody designed.
+ * The text arrives resolved; the footer's reason is the kind's, by key.
+ */
+export declare function renderSiteTextEmail(firestore: FirebaseFirestore.Firestore, hostId: string, templateKey: string, message: {
+    subject: string;
+    text: string;
+    preheader?: string;
+}): Promise<{
+    subject: string;
+    html: string;
+    text: string;
+}>;
 export default renderHostEmailWithTokens;

package/src/lib/server/host-email-tokens.js

@@ -17,7 +17,8 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
  */ import { sanitizeAuthorHtml } from "@aglyn/aglyn/app-utils/author-html";
 import { hostTokenMerge } from "@aglyn/aglyn/app-utils/host-tokens";
 import { composeHostComponentNodes } from "@aglyn/aglyn/app-utils/load-referenced-components";
-import { renderHostEmail } from "@aglyn/shared-util-email";
+import { buildSiteEmailChrome } from "@aglyn/aglyn/app-utils/site-email-chrome";
+import { buildEmailPalette, emailPaletteBaseForHost, getTenantEmail, hostEmailOrigin, loadHostEmail, renderFramedTextEmail, renderHostEmail, renderLoadedHostEmail } from "@aglyn/shared-util-email";
 /**
  * `renderHostEmail` with `host.*` tokens resolved (AGL-1022).
  *
@@ -44,16 +45,7 @@ import { renderHostEmail } from "@aglyn/shared-util-email";
  * Costs one host read per send. Emails are not a hot path, and the read buys
  * the guarantee that a template's branding is right by construction.
  */ export async function renderHostEmailWithTokens(firestore, hostId, templateKey, merge = {}, options = {}) {
-    let host;
-    try {
-        const snapshot = await firestore.collection('hosts').doc(hostId).get();
-        host = snapshot.exists ? snapshot.data() : null;
-    } catch (unused) {
-        // A failed read must not stop the send. Every token then resolves to its
-        // empty behaviour, which is the same outcome as a site that set nothing —
-        // an email with a gap where the address would be, rather than no email.
-        host = null;
-    }
+    const host = await readHostTokenSource(firestore, hostId);
     return renderHostEmail(firestore, hostId, templateKey, // Host tokens first: an explicit caller value WINS. A sender passing
     // `host.businessName` is naming a specific thing on purpose (a white-label
     // send, a preview with sample data), and this is not the place to overrule
@@ -71,11 +63,107 @@ import { renderHostEmail } from "@aglyn/shared-util-email";
     // having to know it exists. Style overrides do not survive into mail —
     // they land in `sx`, which `renderEmailHtml` never reads — but property
     // values and attribute overrides do.
+    //
+    // And the site's header and footer (AGL-3370), which the built-in copy is
+    // drawn inside; a design the owner published goes out as they built it.
     _extends({}, options, {
         sanitize: sanitizeAuthorHtml,
-        compose: composeHostComponentNodes
+        compose: composeHostComponentNodes,
+        chrome: siteChromeFor(host, templateKey),
+        theme: siteThemeFor(host)
     }));
 }
+/**
+ * The site's host document as the token and chrome readers see it, or null.
+ *
+ * A failed read must not stop the send. Every token then resolves to its
+ * empty behaviour, which is the same outcome as a site that set nothing —
+ * an email with a gap where the address would be, rather than no email.
+ */ async function readHostTokenSource(firestore, hostId) {
+    try {
+        const snapshot = await firestore.collection('hosts').doc(hostId).get();
+        return snapshot.exists ? snapshot.data() : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * The site's theme as its email draws it (AGL-3370): the palette the
+ * published site renders with, light scheme, since an inbox has one, and its
+ * corner radius for buttons. A site with no theme of its own resolves the
+ * same base the site itself does.
+ */ function siteThemeFor(host) {
+    var _ref;
+    var _host_theme_shape, _host_theme, _host_theme_colorSchemes, _host_theme1;
+    const radius = host == null ? void 0 : (_host_theme = host.theme) == null ? void 0 : (_host_theme_shape = _host_theme.shape) == null ? void 0 : _host_theme_shape.borderRadius;
+    return _extends({
+        palette: buildEmailPalette({
+            base: emailPaletteBaseForHost(host),
+            colors: (_ref = host == null ? void 0 : (_host_theme1 = host.theme) == null ? void 0 : (_host_theme_colorSchemes = _host_theme1.colorSchemes) == null ? void 0 : _host_theme_colorSchemes.light) != null ? _ref : null
+        })
+    }, typeof radius === 'number' ? {
+        buttonRadius: radius
+    } : {});
+}
+/** The site's chrome for one kind of email, with that kind's footer reason. */ function siteChromeFor(host, templateKey) {
+    var _getTenantEmail;
+    return buildSiteEmailChrome({
+        host,
+        reason: (_getTenantEmail = getTenantEmail(templateKey)) == null ? void 0 : _getTenantEmail.footerReason
+    });
+}
+/**
+ * {@link loadHostEmail} for a batch (AGL-3370): the template, or the built-in
+ * copy in the site's header and footer, read ONCE, with the site's `host.*`
+ * tokens beside it for {@link renderLoadedHostEmailWithTokens}. `null` only
+ * for a key with neither, so the batch keeps its own copy.
+ */ export async function loadHostEmailWithTokens(firestore, hostId, templateKey, options = {}) {
+    const host = await readHostTokenSource(firestore, hostId);
+    const loaded = await loadHostEmail(firestore, hostId, templateKey, _extends({}, options, {
+        compose: composeHostComponentNodes,
+        chrome: siteChromeFor(host, templateKey),
+        theme: siteThemeFor(host)
+    }));
+    return loaded ? {
+        loaded,
+        hostMerge: hostTokenMerge(host)
+    } : null;
+}
+/** One recipient's copy of a batch-loaded site email; no reads. */ export function renderLoadedHostEmailWithTokens(bundle, merge = {}) {
+    return renderLoadedHostEmail(bundle.loaded, _extends({}, bundle.hostMerge, merge), sanitizeAuthorHtml);
+}
+/**
+ * The site's header and footer for one kind of email, its theme, and the
+ * origin and host a stored logo reference resolves against (AGL-3370): for a sender
+ * that renders per recipient itself, such as a typed campaign.
+ */ export async function siteEmailFrame(firestore, hostId, templateKey) {
+    const host = await readHostTokenSource(firestore, hostId);
+    const origin = host ? hostEmailOrigin({
+        cname: host.cname,
+        subdomain: host.subdomain
+    }) : undefined;
+    return _extends({
+        chrome: siteChromeFor(host, templateKey),
+        theme: siteThemeFor(host)
+    }, origin ? {
+        mediaOrigin: origin
+    } : {}, {
+        mediaHostId: hostId
+    });
+}
+/**
+ * A text-only site email in the site's header and footer (AGL-3370): a
+ * workflow's email step, or a message a site sends in words nobody designed.
+ * The text arrives resolved; the footer's reason is the kind's, by key.
+ */ export async function renderSiteTextEmail(firestore, hostId, templateKey, message) {
+    const frame = await siteEmailFrame(firestore, hostId, templateKey);
+    const rendered = renderFramedTextEmail(_extends({}, message, frame));
+    return {
+        subject: message.subject,
+        html: rendered.html,
+        text: rendered.text
+    };
+}
 export default renderHostEmailWithTokens;
 
 //# sourceMappingURL=host-email-tokens.js.map

package/src/lib/server/host-email-tokens.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/host-email-tokens.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { sanitizeAuthorHtml } from '@aglyn/aglyn/app-utils/author-html'\nimport {\n  hostTokenMerge,\n  type HostTokenSource,\n} from '@aglyn/aglyn/app-utils/host-tokens'\nimport { composeHostComponentNodes } from '@aglyn/aglyn/app-utils/load-referenced-components'\nimport {\n  renderHostEmail,\n  type RenderedHostEmail,\n} from '@aglyn/shared-util-email'\nimport { firebaseAdmin } from './firebase-admin'\n\n/**\n * `renderHostEmail` with `host.*` tokens resolved (AGL-1022).\n *\n * The whole point of host variables is that a publisher's email template can\n * say \"write to {{host.supportEmail}}\" and have the installing site fill it in.\n * That only happens if something resolves the tokens at SEND time, and the\n * email library cannot: `@aglyn/shared-util-email` is `scope:shared` and may\n * only depend on `scope:shared`, while the token registry is aglyn-scoped.\n *\n * So the join happens here, in the one lib that already sits above both. Three\n * alternatives were weighed and this is the one that cannot fail quietly:\n *\n * * A registration hook inside the email library would mean a provider that is\n *   never registered resolves every token to nothing, silently, on a path whose\n *   output has already been sent to a customer. This repo has shipped a\n *   flawless security control with zero callers before; that is the shape.\n * * Threading the map through all eighteen call sites puts the burden on\n *   whoever adds the nineteenth, and they will not know.\n * * Moving the registry into a `scope:shared` lib is the cleanest end state and\n *   the right thing if a second shared consumer ever appears — but the only\n *   candidate today is `shared/util/tools`, which is generic helpers, and\n *   domain logic does not belong there.\n *\n * Costs one host read per send. Emails are not a hot path, and the read buys\n * the guarantee that a template's branding is right by construction.\n */\nexport async function renderHostEmailWithTokens(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: { origin?: string } = {},\n): Promise<RenderedHostEmail | null> {\n  let host: HostTokenSource | null\n  try {\n    const snapshot = await firestore.collection('hosts').doc(hostId).get()\n    host = snapshot.exists ? (snapshot.data() as HostTokenSource) : null\n  } catch {\n    // A failed read must not stop the send. Every token then resolves to its\n    // empty behaviour, which is the same outcome as a site that set nothing —\n    // an email with a gap where the address would be, rather than no email.\n    host = null\n  }\n  return renderHostEmail(\n    firestore as never,\n    hostId,\n    templateKey,\n    // Host tokens first: an explicit caller value WINS. A sender passing\n    // `host.businessName` is naming a specific thing on purpose (a white-label\n    // send, a preview with sample data), and this is not the place to overrule\n    // it.\n    { ...hostTokenMerge(host), ...merge },\n    // The HTML policy joins here for the same reason the token map does, and\n    // it is the same reason: `renderEmailHtml` requires one, `scope:shared`\n    // cannot import one, and this lib already sits above both. Supplying it\n    // here rather than at each of the nine senders keeps their signatures\n    // untouched and gives the tenth one the right policy without knowing it\n    // needed to ask.\n    //\n    // The component graft joins on the same argument (AGL-3287): a header or\n    // footer the site owner placed is a reference the shared renderer cannot\n    // resolve, so every sender behind this function mails it expanded without\n    // having to know it exists. Style overrides do not survive into mail —\n    // they land in `sx`, which `renderEmailHtml` never reads — but property\n    // values and attribute overrides do.\n    {\n      ...options,\n      sanitize: sanitizeAuthorHtml,\n      compose: composeHostComponentNodes,\n    },\n  )\n}\n\nexport default renderHostEmailWithTokens\n"],"names":["sanitizeAuthorHtml","hostTokenMerge","composeHostComponentNodes","renderHostEmail","renderHostEmailWithTokens","firestore","hostId","templateKey","merge","options","host","snapshot","collection","doc","get","exists","data","sanitize","compose"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,kBAAkB,QAAQ,qCAAoC;AACvE,SACEC,cAAc,QAET,qCAAoC;AAC3C,SAASC,yBAAyB,QAAQ,oDAAmD;AAC7F,SACEC,eAAe,QAEV,2BAA0B;AAGjC;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,eAAeC,0BACpBC,SAAsC,EACtCC,MAAc,EACdC,WAAmB,EACnBC,QAAgC,CAAC,CAAC,EAClCC,UAA+B,CAAC,CAAC;IAEjC,IAAIC;IACJ,IAAI;QACF,MAAMC,WAAW,MAAMN,UAAUO,UAAU,CAAC,SAASC,GAAG,CAACP,QAAQQ,GAAG;QACpEJ,OAAOC,SAASI,MAAM,GAAIJ,SAASK,IAAI,KAAyB;IAClE,EAAE,eAAM;QACN,yEAAyE;QACzE,0EAA0E;QAC1E,wEAAwE;QACxEN,OAAO;IACT;IACA,OAAOP,gBACLE,WACAC,QACAC,aACA,qEAAqE;IACrE,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM;IACN,aAAKN,eAAeS,OAAUF,QAC9B,yEAAyE;IACzE,wEAAwE;IACxE,wEAAwE;IACxE,sEAAsE;IACtE,wEAAwE;IACxE,iBAAiB;IACjB,EAAE;IACF,yEAAyE;IACzE,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,wEAAwE;IACxE,qCAAqC;IACrC,aACKC;QACHQ,UAAUjB;QACVkB,SAAShB;;AAGf;AAEA,eAAeE,0BAAyB"}
+{"version":3,"sources":["../../../../../../../../libs/tenant/data/admin/src/lib/server/host-email-tokens.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { sanitizeAuthorHtml } from '@aglyn/aglyn/app-utils/author-html'\nimport {\n  hostTokenMerge,\n  type HostTokenSource,\n} from '@aglyn/aglyn/app-utils/host-tokens'\nimport { composeHostComponentNodes } from '@aglyn/aglyn/app-utils/load-referenced-components'\nimport { buildSiteEmailChrome } from '@aglyn/aglyn/app-utils/site-email-chrome'\nimport {\n  buildEmailPalette,\n  emailPaletteBaseForHost,\n  getTenantEmail,\n  hostEmailOrigin,\n  loadHostEmail,\n  renderFramedTextEmail,\n  renderHostEmail,\n  renderLoadedHostEmail,\n  type EmailChrome,\n  type EmailTheme,\n  type LoadedHostEmail,\n  type RenderedHostEmail,\n} from '@aglyn/shared-util-email'\nimport { firebaseAdmin } from './firebase-admin'\n\n/**\n * `renderHostEmail` with `host.*` tokens resolved (AGL-1022).\n *\n * The whole point of host variables is that a publisher's email template can\n * say \"write to {{host.supportEmail}}\" and have the installing site fill it in.\n * That only happens if something resolves the tokens at SEND time, and the\n * email library cannot: `@aglyn/shared-util-email` is `scope:shared` and may\n * only depend on `scope:shared`, while the token registry is aglyn-scoped.\n *\n * So the join happens here, in the one lib that already sits above both. Three\n * alternatives were weighed and this is the one that cannot fail quietly:\n *\n * * A registration hook inside the email library would mean a provider that is\n *   never registered resolves every token to nothing, silently, on a path whose\n *   output has already been sent to a customer. This repo has shipped a\n *   flawless security control with zero callers before; that is the shape.\n * * Threading the map through all eighteen call sites puts the burden on\n *   whoever adds the nineteenth, and they will not know.\n * * Moving the registry into a `scope:shared` lib is the cleanest end state and\n *   the right thing if a second shared consumer ever appears — but the only\n *   candidate today is `shared/util/tools`, which is generic helpers, and\n *   domain logic does not belong there.\n *\n * Costs one host read per send. Emails are not a hot path, and the read buys\n * the guarantee that a template's branding is right by construction.\n */\nexport async function renderHostEmailWithTokens(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: { origin?: string } = {},\n): Promise<RenderedHostEmail | null> {\n  const host = await readHostTokenSource(firestore, hostId)\n  return renderHostEmail(\n    firestore as never,\n    hostId,\n    templateKey,\n    // Host tokens first: an explicit caller value WINS. A sender passing\n    // `host.businessName` is naming a specific thing on purpose (a white-label\n    // send, a preview with sample data), and this is not the place to overrule\n    // it.\n    { ...hostTokenMerge(host), ...merge },\n    // The HTML policy joins here for the same reason the token map does, and\n    // it is the same reason: `renderEmailHtml` requires one, `scope:shared`\n    // cannot import one, and this lib already sits above both. Supplying it\n    // here rather than at each of the nine senders keeps their signatures\n    // untouched and gives the tenth one the right policy without knowing it\n    // needed to ask.\n    //\n    // The component graft joins on the same argument (AGL-3287): a header or\n    // footer the site owner placed is a reference the shared renderer cannot\n    // resolve, so every sender behind this function mails it expanded without\n    // having to know it exists. Style overrides do not survive into mail —\n    // they land in `sx`, which `renderEmailHtml` never reads — but property\n    // values and attribute overrides do.\n    //\n    // And the site's header and footer (AGL-3370), which the built-in copy is\n    // drawn inside; a design the owner published goes out as they built it.\n    {\n      ...options,\n      sanitize: sanitizeAuthorHtml,\n      compose: composeHostComponentNodes,\n      chrome: siteChromeFor(host, templateKey),\n      theme: siteThemeFor(host),\n    },\n  )\n}\n\n/**\n * The site's host document as the token and chrome readers see it, or null.\n *\n * A failed read must not stop the send. Every token then resolves to its\n * empty behaviour, which is the same outcome as a site that set nothing —\n * an email with a gap where the address would be, rather than no email.\n */\nasync function readHostTokenSource(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n): Promise<SiteEmailHost | null> {\n  try {\n    const snapshot = await firestore.collection('hosts').doc(hostId).get()\n    return snapshot.exists ? (snapshot.data() as SiteEmailHost) : null\n  } catch {\n    return null\n  }\n}\n\n/** What a site email reads off the host document: its tokens and its theme. */\ntype SiteEmailHost = HostTokenSource & {\n  theme?: {\n    colorSchemes?: { light?: Record<string, unknown> | null }\n    shape?: { borderRadius?: unknown }\n  } | null\n}\n\n/**\n * The site's theme as its email draws it (AGL-3370): the palette the\n * published site renders with, light scheme, since an inbox has one, and its\n * corner radius for buttons. A site with no theme of its own resolves the\n * same base the site itself does.\n */\nfunction siteThemeFor(host: SiteEmailHost | null): EmailTheme {\n  const radius = host?.theme?.shape?.borderRadius\n  return {\n    palette: buildEmailPalette({\n      base: emailPaletteBaseForHost(host),\n      colors: host?.theme?.colorSchemes?.light ?? null,\n    }),\n    ...(typeof radius === 'number' ? { buttonRadius: radius } : {}),\n  }\n}\n\n/** The site's chrome for one kind of email, with that kind's footer reason. */\nfunction siteChromeFor(\n  host: HostTokenSource | null,\n  templateKey: string,\n): EmailChrome {\n  return buildSiteEmailChrome({\n    host,\n    reason: getTenantEmail(templateKey)?.footerReason,\n  })\n}\n\n/** A site email loaded once for a batch, with the site's tokens beside it. */\nexport interface LoadedHostEmailWithTokens {\n  loaded: LoadedHostEmail\n  hostMerge: Record<string, string>\n}\n\n/**\n * {@link loadHostEmail} for a batch (AGL-3370): the template, or the built-in\n * copy in the site's header and footer, read ONCE, with the site's `host.*`\n * tokens beside it for {@link renderLoadedHostEmailWithTokens}. `null` only\n * for a key with neither, so the batch keeps its own copy.\n */\nexport async function loadHostEmailWithTokens(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  templateKey: string,\n  options: { origin?: string } = {},\n): Promise<LoadedHostEmailWithTokens | null> {\n  const host = await readHostTokenSource(firestore, hostId)\n  const loaded = await loadHostEmail(firestore as never, hostId, templateKey, {\n    ...options,\n    compose: composeHostComponentNodes,\n    chrome: siteChromeFor(host, templateKey),\n    theme: siteThemeFor(host),\n  })\n  return loaded ? { loaded, hostMerge: hostTokenMerge(host) } : null\n}\n\n/** One recipient's copy of a batch-loaded site email; no reads. */\nexport function renderLoadedHostEmailWithTokens(\n  bundle: LoadedHostEmailWithTokens,\n  merge: Record<string, string> = {},\n): RenderedHostEmail | null {\n  return renderLoadedHostEmail(\n    bundle.loaded,\n    { ...bundle.hostMerge, ...merge },\n    sanitizeAuthorHtml,\n  )\n}\n\n/**\n * The site's header and footer for one kind of email, its theme, and the\n * origin and host a stored logo reference resolves against (AGL-3370): for a sender\n * that renders per recipient itself, such as a typed campaign.\n */\nexport async function siteEmailFrame(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  templateKey: string,\n): Promise<{\n  chrome: EmailChrome\n  theme: EmailTheme\n  mediaOrigin?: string\n  mediaHostId: string\n}> {\n  const host = await readHostTokenSource(firestore, hostId)\n  const origin = host\n    ? hostEmailOrigin({ cname: host.cname, subdomain: host.subdomain })\n    : undefined\n  return {\n    chrome: siteChromeFor(host, templateKey),\n    theme: siteThemeFor(host),\n    ...(origin ? { mediaOrigin: origin } : {}),\n    mediaHostId: hostId,\n  }\n}\n\n/**\n * A text-only site email in the site's header and footer (AGL-3370): a\n * workflow's email step, or a message a site sends in words nobody designed.\n * The text arrives resolved; the footer's reason is the kind's, by key.\n */\nexport async function renderSiteTextEmail(\n  firestore: FirebaseFirestore.Firestore,\n  hostId: string,\n  templateKey: string,\n  message: { subject: string; text: string; preheader?: string },\n): Promise<{ subject: string; html: string; text: string }> {\n  const frame = await siteEmailFrame(firestore, hostId, templateKey)\n  const rendered = renderFramedTextEmail({ ...message, ...frame })\n  return { subject: message.subject, html: rendered.html, text: rendered.text }\n}\n\nexport default renderHostEmailWithTokens\n"],"names":["sanitizeAuthorHtml","hostTokenMerge","composeHostComponentNodes","buildSiteEmailChrome","buildEmailPalette","emailPaletteBaseForHost","getTenantEmail","hostEmailOrigin","loadHostEmail","renderFramedTextEmail","renderHostEmail","renderLoadedHostEmail","renderHostEmailWithTokens","firestore","hostId","templateKey","merge","options","host","readHostTokenSource","sanitize","compose","chrome","siteChromeFor","theme","siteThemeFor","snapshot","collection","doc","get","exists","data","radius","shape","borderRadius","palette","base","colors","colorSchemes","light","buttonRadius","reason","footerReason","loadHostEmailWithTokens","loaded","hostMerge","renderLoadedHostEmailWithTokens","bundle","siteEmailFrame","origin","cname","subdomain","undefined","mediaOrigin","mediaHostId","renderSiteTextEmail","message","frame","rendered","subject","html","text"],"mappings":"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"}

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

@@ -26,6 +26,7 @@ import { _ as _extends } from "@swc/helpers/_/_extends";
 import { FieldValue } from "firebase-admin/firestore";
 import { attributeCampaignConversion } from "./campaign-conversion-attribution.js";
 import { notifyHostManagers } from "./notifications.js";
+import { scheduleCapturedEmailCheck } from "./capture-email-check.js";
 import firebaseAdmin from "./firebase-admin.js";
 import { consentGroupForSite, orgDataCollectionForHost, scopedToHost } from "./organizations.js";
 import { crmLeadListFields, crmReadTokens, crmScopeTokens } from "@aglyn/aglyn/server";
@@ -261,6 +262,8 @@ const firestore = ()=>firebaseAdmin.app().firestore();
     const { hostRef, hostId, lead } = options;
     const maxPerHost = (_options_ceiling = options.ceiling) != null ? _options_ceiling : LEADS_MAX_PER_HOST;
     try {
+        var _ref;
+        var _leadsRef_parent;
         const leadsRef = await orgLeadsForHost(hostId);
         const firestore = hostRef.firestore;
         /*
@@ -298,8 +301,9 @@ const firestore = ()=>firebaseAdmin.app().firestore();
         } : {});
         let created = false;
         let sourceAdded = false;
+        let predicted = false;
         const refused = await firestore.runTransaction(async (tx)=>{
-            var _existing_data, _existing_data1, _existing_data2;
+            var _existing_data, _existing_data1, _existing_data2, _existing_data3;
             // 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.
@@ -307,6 +311,8 @@ const firestore = ()=>firebaseAdmin.app().firestore();
             sourceAdded = false;
             // ALL READS BEFORE THE WRITE, which Firestore requires.
             const existing = await tx.get(leadRef);
+            // Whether the lead already reads "Would bounce", for the check below.
+            predicted = ((_existing_data = existing.data()) != null ? _existing_data : {})['emailStatus'] === 'undeliverable';
             /*
        * ⛔ THE CEILING GATES A NEW PERSON, NEVER AN EXISTING ONE.
        *
@@ -372,7 +378,7 @@ const firestore = ()=>firebaseAdmin.app().firestore();
        * nothing.
        *
        * Resolved above the transaction — see `group`'s declaration.
-       */ const prior = readMarketingBasis((_existing_data = existing.data()) != null ? _existing_data : null, group);
+       */ const prior = readMarketingBasis((_existing_data1 = existing.data()) != null ? _existing_data1 : null, group);
             const consentAtMs = prior.basis === 'granted' && prior.basisAtMs !== null ? prior.basisAtMs : now;
             created = !existing.exists;
             /*
@@ -381,7 +387,7 @@ const firestore = ()=>firebaseAdmin.app().firestore();
        * counts its leads by this (AGL-3330) — the people it filed, which is
        * what a recount of `sources` finds — so a returning visitor's second
        * submission moves no form's lead count.
-       */ const storedSources = ((_existing_data1 = existing.data()) != null ? _existing_data1 : {})['sources'];
+       */ const storedSources = ((_existing_data2 = existing.data()) != null ? _existing_data2 : {})['sources'];
             sourceAdded = created || !(Array.isArray(storedSources) && storedSources.includes(lead.source));
             /*
        * THE FIELDS THE LEADS LIST QUERIES (AGL-3321), from the lead as it
@@ -389,7 +395,7 @@ const firestore = ()=>firebaseAdmin.app().firestore();
        * capture brings and the scope it widens. A new lead is written
        * `status: 'new'`, so the Open view's `status in [new, working]`
        * finds a lead nobody has touched — an absent field matches no query.
-       */ const stored = (_existing_data2 = existing.data()) != null ? _existing_data2 : {};
+       */ const stored = (_existing_data3 = existing.data()) != null ? _existing_data3 : {};
             const storedScope = Array.isArray(stored['visibleTo']) ? stored['visibleTo'] : [];
             const listFields = crmLeadListFields(_extends({}, stored, {
                 email: lead.email
@@ -457,7 +463,17 @@ const firestore = ()=>firebaseAdmin.app().firestore();
      * 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) {
+     */ /*
+     * THE ADDRESS'S DOMAIN, checked after the response (AGL-3328): a lead
+     * whose domain takes no mail reads "Would bounce". Queued, never
+     * awaited — the write above is the capture, and this costs it nothing.
+     */ scheduleCapturedEmailCheck({
+            orgId: (_ref = (_leadsRef_parent = leadsRef.parent) == null ? void 0 : _leadsRef_parent.id) != null ? _ref : null,
+            hostId,
+            email: lead.email,
+            predicted
+        });
+        if (created && options.touch) {
             await attributeCampaignConversion({
                 hostId,
                 kind: 'lead',