@aglyn/shared-util-email 1.0.0-beta.143

package/src/lib/host-email-render.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @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.
+ */
+import { type EmailRenderOptions } from './email-render';
+import { type TenantEmailEntry } from './tenant-email-catalog';
+/**
+ * The slice of the Admin Firestore chain this resolver uses. Structural on
+ * purpose (AGL-770): the plugins that call this already hold an Admin
+ * Firestore instance, so passing it in keeps `@aglyn/shared-util-email` free
+ * of a firebase-admin dependency and importable from every send site.
+ */
+interface AdminDocSnapshotLike {
+    exists: boolean;
+    get(field: string): unknown;
+}
+interface AdminDocRefLike {
+    get(): Promise<AdminDocSnapshotLike>;
+    collection(path: string): AdminCollectionRefLike;
+}
+interface AdminCollectionRefLike {
+    doc(id: string): AdminDocRefLike;
+}
+export interface AdminFirestoreLike {
+    collection(path: string): AdminCollectionRefLike;
+}
+export interface RenderedHostEmail {
+    subject: string;
+    html: string;
+    text: string;
+}
+/**
+ * A site-owner-designed template loaded once, ready to render for any number
+ * of recipients without another Firestore read (AGL-770) — the booking
+ * reminder job renders one per booking.
+ */
+export interface LoadedHostEmail {
+    entry: TenantEmailEntry;
+    nodes: Record<string, unknown>;
+    subjectTemplate: string;
+    preheaderTemplate: string;
+    /** Host doc id, so an org-scoped media reference can be host-qualified. */
+    hostId: string;
+    /**
+     * The site's absolute origin, for absolutizing picked images (AGL-1224).
+     * Undefined only for a host with neither a custom domain nor a subdomain,
+     * in which case those images are dropped rather than sent broken.
+     */
+    origin?: string;
+}
+/**
+ * Loads a site's published email template, or `null` when there is nothing
+ * usable (no document, no published version, an empty node map, an unknown or
+ * non-designable key). The host-scoped mirror of the platform
+ * `loadSystemEmail`: `hosts/{hostId}/emailTemplates/{key}`.
+ *
+ * The caller passes its own Admin Firestore, so this reads through the Admin
+ * SDK — the send path runs as the server, not a signed-in user.
+ *
+ * TWO reads, not one (AGL-1224): the host document is read for the site's
+ * origin, which picked images need to be fetchable from an inbox. It is read
+ * LAST, only once there is something to render, so a site with nothing
+ * published still costs a single read — and it is skipped entirely when the
+ * caller already knows the origin and passes it. Still once per batch, not
+ * once per recipient, which is the property AGL-770 cared about.
+ */
+export declare function loadHostEmail(firestore: AdminFirestoreLike, hostId: string, templateKey: string, options?: {
+    origin?: string;
+}): Promise<LoadedHostEmail | null>;
+/**
+ * Renders a pre-loaded template for one recipient's merge values (AGL-770).
+ * No Firestore access; returns `null` if the node map renders empty so the
+ * caller still falls back to its built-in copy.
+ */
+export declare function renderLoadedHostEmail(loaded: LoadedHostEmail, merge: Record<string, string>, sanitize: EmailRenderOptions['sanitize']): RenderedHostEmail | null;
+/**
+ * Renders a site's designed email, or `null` when nothing usable is published
+ * so the send site keeps its built-in copy (AGL-770). Single-recipient
+ * convenience over {@link loadHostEmail} + {@link renderLoadedHostEmail}; a
+ * batch should call those two so it reads the template once.
+ */
+export declare function renderHostEmail(firestore: AdminFirestoreLike, hostId: string, templateKey: string, merge: Record<string, string>, options: {
+    origin?: string;
+    /** See {@link EmailRenderOptions.sanitize} — required, deliberately. */
+    sanitize: EmailRenderOptions['sanitize'];
+}): Promise<RenderedHostEmail | null>;
+export {};

package/src/lib/host-email-render.js

@@ -0,0 +1,126 @@
+/**
+ * @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.
+ */ import { hostEmailOrigin } from "./email-media-src.js";
+import { decodeEmailNodes } from "./stored-email-nodes.js";
+import { EMAIL_NODE_ROOT_ID, renderEmailHtml, substituteMergeTokens } from "./email-render.js";
+import { getTenantEmail, isTenantEmailEditable, TENANT_EMAIL_COLLECTION } from "./tenant-email-catalog.js";
+/** Blanks any `{{token}}` the caller did not supply, so a customer never
+ * sees a raw tag. Mirrors the platform system-email resolver. */ function blankUnresolvedTokens(value) {
+    return value.replace(/\{\{[^}]*\}\}/g, '');
+}
+/**
+ * Loads a site's published email template, or `null` when there is nothing
+ * usable (no document, no published version, an empty node map, an unknown or
+ * non-designable key). The host-scoped mirror of the platform
+ * `loadSystemEmail`: `hosts/{hostId}/emailTemplates/{key}`.
+ *
+ * The caller passes its own Admin Firestore, so this reads through the Admin
+ * SDK — the send path runs as the server, not a signed-in user.
+ *
+ * TWO reads, not one (AGL-1224): the host document is read for the site's
+ * origin, which picked images need to be fetchable from an inbox. It is read
+ * LAST, only once there is something to render, so a site with nothing
+ * published still costs a single read — and it is skipped entirely when the
+ * caller already knows the origin and passes it. Still once per batch, not
+ * once per recipient, which is the property AGL-770 cared about.
+ */ export async function loadHostEmail(firestore, hostId, templateKey, options = {}) {
+    const entry = getTenantEmail(templateKey);
+    if (!entry || !isTenantEmailEditable(entry)) return null;
+    if (!hostId) return null;
+    try {
+        var _templateSnapshot_get, _templateSnapshot_get1;
+        const hostRef = firestore.collection('hosts').doc(hostId);
+        const templateRef = hostRef.collection(TENANT_EMAIL_COLLECTION).doc(templateKey);
+        const templateSnapshot = await templateRef.get();
+        if (!templateSnapshot.exists) return null;
+        const versionId = templateSnapshot.get('versionId');
+        if (!versionId) return null;
+        const versionSnapshot = await templateRef.collection('versions').doc(String(versionId)).get();
+        // BOTH stored forms. The email besigner compresses like every other
+        // besigner document (AGL-1151), and every version written before it did
+        // is still a plain map — a plain map comes back unchanged, so a single
+        // call serves both and keeps serving both.
+        //
+        // Reading the field raw is the failure the guard below cannot catch: over
+        // a `Buffer`, `Object.keys` counts BYTE INDICES, so the emptiness test
+        // passes and the caller renders an empty email instead of falling back to
+        // its built-in copy (AGL-1223).
+        const nodes = decodeEmailNodes(versionSnapshot.get('nodes'));
+        if (!nodes || !Object.keys(nodes).length) return null;
+        let origin = options.origin;
+        if (!origin) {
+            const hostSnapshot = await hostRef.get();
+            origin = hostEmailOrigin({
+                cname: hostSnapshot.get('cname'),
+                subdomain: hostSnapshot.get('subdomain')
+            });
+        }
+        return {
+            entry,
+            nodes,
+            hostId,
+            origin,
+            subjectTemplate: String((_templateSnapshot_get = templateSnapshot.get('subject')) != null ? _templateSnapshot_get : '') || entry.defaultSubject || '',
+            preheaderTemplate: String((_templateSnapshot_get1 = templateSnapshot.get('preheader')) != null ? _templateSnapshot_get1 : '')
+        };
+    } catch (error) {
+        // Never let a template problem block the send — the caller falls back to
+        // its built-in copy and the customer still gets their email.
+        console.error(`host email template ${templateKey} failed to load`, error);
+        return null;
+    }
+}
+/**
+ * Renders a pre-loaded template for one recipient's merge values (AGL-770).
+ * No Firestore access; returns `null` if the node map renders empty so the
+ * caller still falls back to its built-in copy.
+ */ export function renderLoadedHostEmail(loaded, merge = {}, sanitize) {
+    var _rendered_text;
+    const rendered = renderEmailHtml({
+        nodes: loaded.nodes,
+        // A site owner designs these in the besigner, so a template's richtext is
+        // author markup exactly as a campaign's is. The policy has to arrive from
+        // above for the reason this lib documents everywhere: `scope:shared`
+        // cannot import the aglyn-scoped sanitizer.
+        sanitize,
+        // Besigner maps are rooted at '_@_' (AGL-765).
+        rootId: EMAIL_NODE_ROOT_ID,
+        subject: substituteMergeTokens(loaded.subjectTemplate, merge),
+        preheader: substituteMergeTokens(loaded.preheaderTemplate, merge),
+        merge,
+        // A picked image is stored as a reference; the site's own origin is what
+        // makes it fetchable from a recipient's inbox (AGL-1224).
+        mediaOrigin: loaded.origin,
+        mediaHostId: loaded.hostId
+    });
+    if (!(rendered == null ? void 0 : rendered.html)) return null;
+    return {
+        subject: blankUnresolvedTokens(substituteMergeTokens(loaded.subjectTemplate, merge)),
+        html: blankUnresolvedTokens(rendered.html),
+        text: blankUnresolvedTokens((_rendered_text = rendered.text) != null ? _rendered_text : '')
+    };
+}
+/**
+ * Renders a site's designed email, or `null` when nothing usable is published
+ * so the send site keeps its built-in copy (AGL-770). Single-recipient
+ * convenience over {@link loadHostEmail} + {@link renderLoadedHostEmail}; a
+ * batch should call those two so it reads the template once.
+ */ export async function renderHostEmail(firestore, hostId, templateKey, merge = {}, options) {
+    const loaded = await loadHostEmail(firestore, hostId, templateKey, options);
+    return loaded ? renderLoadedHostEmail(loaded, merge, options.sanitize) : null;
+}
+
+//# sourceMappingURL=host-email-render.js.map

package/src/lib/host-email-render.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/host-email-render.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 { hostEmailOrigin } from './email-media-src'\nimport { decodeEmailNodes } from './stored-email-nodes'\nimport {\n  EMAIL_NODE_ROOT_ID,\n  renderEmailHtml,\n  substituteMergeTokens,\n  type EmailRenderOptions,\n} from './email-render'\nimport {\n  getTenantEmail,\n  isTenantEmailEditable,\n  TENANT_EMAIL_COLLECTION,\n  type TenantEmailEntry,\n} from './tenant-email-catalog'\n\n/**\n * The slice of the Admin Firestore chain this resolver uses. Structural on\n * purpose (AGL-770): the plugins that call this already hold an Admin\n * Firestore instance, so passing it in keeps `@aglyn/shared-util-email` free\n * of a firebase-admin dependency and importable from every send site.\n */\ninterface AdminDocSnapshotLike {\n  exists: boolean\n  get(field: string): unknown\n}\ninterface AdminDocRefLike {\n  get(): Promise<AdminDocSnapshotLike>\n  collection(path: string): AdminCollectionRefLike\n}\ninterface AdminCollectionRefLike {\n  doc(id: string): AdminDocRefLike\n}\nexport interface AdminFirestoreLike {\n  collection(path: string): AdminCollectionRefLike\n}\n\nexport interface RenderedHostEmail {\n  subject: string\n  html: string\n  text: string\n}\n\n/**\n * A site-owner-designed template loaded once, ready to render for any number\n * of recipients without another Firestore read (AGL-770) — the booking\n * reminder job renders one per booking.\n */\nexport interface LoadedHostEmail {\n  entry: TenantEmailEntry\n  nodes: Record<string, unknown>\n  subjectTemplate: string\n  preheaderTemplate: string\n  /** Host doc id, so an org-scoped media reference can be host-qualified. */\n  hostId: string\n  /**\n   * The site's absolute origin, for absolutizing picked images (AGL-1224).\n   * Undefined only for a host with neither a custom domain nor a subdomain,\n   * in which case those images are dropped rather than sent broken.\n   */\n  origin?: string\n}\n\n/** Blanks any `{{token}}` the caller did not supply, so a customer never\n * sees a raw tag. Mirrors the platform system-email resolver. */\nfunction blankUnresolvedTokens(value: string): string {\n  return value.replace(/\\{\\{[^}]*\\}\\}/g, '')\n}\n\n/**\n * Loads a site's published email template, or `null` when there is nothing\n * usable (no document, no published version, an empty node map, an unknown or\n * non-designable key). The host-scoped mirror of the platform\n * `loadSystemEmail`: `hosts/{hostId}/emailTemplates/{key}`.\n *\n * The caller passes its own Admin Firestore, so this reads through the Admin\n * SDK — the send path runs as the server, not a signed-in user.\n *\n * TWO reads, not one (AGL-1224): the host document is read for the site's\n * origin, which picked images need to be fetchable from an inbox. It is read\n * LAST, only once there is something to render, so a site with nothing\n * published still costs a single read — and it is skipped entirely when the\n * caller already knows the origin and passes it. Still once per batch, not\n * once per recipient, which is the property AGL-770 cared about.\n */\nexport async function loadHostEmail(\n  firestore: AdminFirestoreLike,\n  hostId: string,\n  templateKey: string,\n  options: { origin?: string } = {},\n): Promise<LoadedHostEmail | null> {\n  const entry = getTenantEmail(templateKey)\n  if (!entry || !isTenantEmailEditable(entry)) return null\n  if (!hostId) return null\n\n  try {\n    const hostRef = firestore.collection('hosts').doc(hostId)\n    const templateRef = hostRef\n      .collection(TENANT_EMAIL_COLLECTION)\n      .doc(templateKey)\n    const templateSnapshot = await templateRef.get()\n    if (!templateSnapshot.exists) return null\n\n    const versionId = templateSnapshot.get('versionId')\n    if (!versionId) return null\n\n    const versionSnapshot = await templateRef\n      .collection('versions')\n      .doc(String(versionId))\n      .get()\n    // BOTH stored forms. The email besigner compresses like every other\n    // besigner document (AGL-1151), and every version written before it did\n    // is still a plain map — a plain map comes back unchanged, so a single\n    // call serves both and keeps serving both.\n    //\n    // Reading the field raw is the failure the guard below cannot catch: over\n    // a `Buffer`, `Object.keys` counts BYTE INDICES, so the emptiness test\n    // passes and the caller renders an empty email instead of falling back to\n    // its built-in copy (AGL-1223).\n    const nodes = decodeEmailNodes<Record<string, unknown>>(\n      versionSnapshot.get('nodes'),\n    )\n    if (!nodes || !Object.keys(nodes).length) return null\n\n    let origin = options.origin\n    if (!origin) {\n      const hostSnapshot = await hostRef.get()\n      origin = hostEmailOrigin({\n        cname: hostSnapshot.get('cname') as string | undefined,\n        subdomain: hostSnapshot.get('subdomain') as string | undefined,\n      })\n    }\n\n    return {\n      entry,\n      nodes,\n      hostId,\n      origin,\n      subjectTemplate:\n        String(templateSnapshot.get('subject') ?? '') ||\n        entry.defaultSubject ||\n        '',\n      preheaderTemplate: String(templateSnapshot.get('preheader') ?? ''),\n    }\n  } catch (error) {\n    // Never let a template problem block the send — the caller falls back to\n    // its built-in copy and the customer still gets their email.\n    console.error(`host email template ${templateKey} failed to load`, error)\n    return null\n  }\n}\n\n/**\n * Renders a pre-loaded template for one recipient's merge values (AGL-770).\n * No Firestore access; returns `null` if the node map renders empty so the\n * caller still falls back to its built-in copy.\n */\nexport function renderLoadedHostEmail(\n  loaded: LoadedHostEmail,\n  merge: Record<string, string> = {},\n  sanitize: EmailRenderOptions['sanitize'],\n): RenderedHostEmail | null {\n  const rendered = renderEmailHtml({\n    nodes: loaded.nodes as never,\n    // A site owner designs these in the besigner, so a template's richtext is\n    // author markup exactly as a campaign's is. The policy has to arrive from\n    // above for the reason this lib documents everywhere: `scope:shared`\n    // cannot import the aglyn-scoped sanitizer.\n    sanitize,\n    // Besigner maps are rooted at '_@_' (AGL-765).\n    rootId: EMAIL_NODE_ROOT_ID,\n    subject: substituteMergeTokens(loaded.subjectTemplate, merge),\n    preheader: substituteMergeTokens(loaded.preheaderTemplate, merge),\n    merge,\n    // A picked image is stored as a reference; the site's own origin is what\n    // makes it fetchable from a recipient's inbox (AGL-1224).\n    mediaOrigin: loaded.origin,\n    mediaHostId: loaded.hostId,\n  })\n  if (!rendered?.html) return null\n  return {\n    subject: blankUnresolvedTokens(\n      substituteMergeTokens(loaded.subjectTemplate, merge),\n    ),\n    html: blankUnresolvedTokens(rendered.html),\n    text: blankUnresolvedTokens(rendered.text ?? ''),\n  }\n}\n\n/**\n * Renders a site's designed email, or `null` when nothing usable is published\n * so the send site keeps its built-in copy (AGL-770). Single-recipient\n * convenience over {@link loadHostEmail} + {@link renderLoadedHostEmail}; a\n * batch should call those two so it reads the template once.\n */\nexport async function renderHostEmail(\n  firestore: AdminFirestoreLike,\n  hostId: string,\n  templateKey: string,\n  merge: Record<string, string> = {},\n  options: {\n    origin?: string\n    /** See {@link EmailRenderOptions.sanitize} — required, deliberately. */\n    sanitize: EmailRenderOptions['sanitize']\n  },\n): Promise<RenderedHostEmail | null> {\n  const loaded = await loadHostEmail(firestore, hostId, templateKey, options)\n  return loaded ? renderLoadedHostEmail(loaded, merge, options.sanitize) : null\n}\n"],"names":["hostEmailOrigin","decodeEmailNodes","EMAIL_NODE_ROOT_ID","renderEmailHtml","substituteMergeTokens","getTenantEmail","isTenantEmailEditable","TENANT_EMAIL_COLLECTION","blankUnresolvedTokens","value","replace","loadHostEmail","firestore","hostId","templateKey","options","entry","templateSnapshot","hostRef","collection","doc","templateRef","get","exists","versionId","versionSnapshot","String","nodes","Object","keys","length","origin","hostSnapshot","cname","subdomain","subjectTemplate","defaultSubject","preheaderTemplate","error","console","renderLoadedHostEmail","loaded","merge","sanitize","rendered","rootId","subject","preheader","mediaOrigin","mediaHostId","html","text","renderHostEmail"],"mappings":"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"}

package/src/lib/host-sender.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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 subcollection under `hosts/{hostId}` that holds a site's senders. */
+export declare const HOST_SENDERS_COLLECTION = "senders";
+/**
+ * The id the site's original sender lives at.
+ *
+ * A fixed id rather than a generated one, because this document is the
+ * materialized form of something that already existed: the three sender fields
+ * on the host. Materializing it under a random id would make "which row is the
+ * one the host document describes" a question with no answer for anybody
+ * reading the data directly, and would let a second materialization mint a
+ * duplicate of the same sender.
+ */
+export declare const DEFAULT_HOST_SENDER_ID = "default";
+/**
+ * How many senders one site may hold.
+ *
+ * A ceiling rather than a page. Every sender is a mailbox somebody has to
+ * serve — bounces and replies arrive at it whether or not anyone reads them —
+ * so a list long enough to need paging is a list nobody is operating, and the
+ * composer control that renders it is a picker rather than a directory.
+ */
+export declare const HOST_SENDER_LIMIT = 25;
+/** One sender, normalized. Every field present; the optional ones as `''`. */
+export interface HostSenderRecord {
+    id: string;
+    /** The mailbox — the part before the `@`. Never empty on a stored row. */
+    localPart: string;
+    /** The display name in front of the address, or `''`. */
+    fromName: string;
+    /** Where replies go when it is not the sending address, or `''`. */
+    replyTo: string;
+    /** Whether an unnamed send leaves on this one. Exactly one row carries it. */
+    isDefault: boolean;
+    createdAtMs: number;
+}
+/**
+ * One stored sender document, normalized into {@link HostSenderRecord}.
+ *
+ * Every field is re-normalized on the way out rather than trusted. The route
+ * validates on the way in, and a document can also arrive from a restore, a
+ * hand edit or a version of the writer that predates a rule — and these values
+ * reach a `From:` header, where an unflattened one is the injection shape.
+ */
+export declare function readHostSender(options: {
+    id: string;
+    data: Record<string, unknown> | null | undefined;
+    /** `hosts/{hostId}.defaultSenderId`. Decides {@link HostSenderRecord.isDefault}. */
+    defaultSenderId?: string | null;
+}): HostSenderRecord;
+/**
+ * Which row an unnamed send leaves on, when the stored pointer names nobody.
+ *
+ * `defaultSenderId` is written beside every change that could move it, so the
+ * ordinary case is that it names a row in this list. It can still fail to: a
+ * default deleted out of band, a pointer written before the row it names, a
+ * partial restore. Answering with a row rather than with nothing is what keeps
+ * such a site sending — and the order is fixed, so two readers of the same data
+ * cannot disagree about which sender that is.
+ */
+export declare function defaultHostSender(senders: readonly HostSenderRecord[]): HostSenderRecord | null;
+/**
+ * The whole address one sender leaves on, or `null` on a site whose mailbox is
+ * not its own to name.
+ *
+ * The ONE place a sending address is assembled from its two halves. A surface
+ * that built `${localPart}@${domain}` itself would be a second derivation of
+ * the address, and the two would disagree the first time either moved — which
+ * is the same rule the identity route's `IdentityOption.from` already keeps.
+ */
+export declare function hostSenderAddress(localPart: string | null | undefined, domain: string | null | undefined): string | null;

package/src/lib/host-sender.js

@@ -0,0 +1,131 @@
+/**
+ * @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 SENDERS ONE SITE HOLDS — `hosts/{hostId}/senders/{senderId}`.
+ *
+ * A sender is a mailbox this site may send as, together with the display name
+ * and reply address that ordinarily go with it. A site holds several and a
+ * composer picks among them; which one an unnamed send uses is the site's
+ * DEFAULT.
+ *
+ * ## Chosen BY ID, never typed per send
+ *
+ * `sending-mailbox.ts` states the rule this collection exists to keep: a
+ * mailbox addresses something real — a bounce returns to it, and a client
+ * ignoring `Reply-To:` answers to it — so a mailbox that exists in one
+ * campaign's headers and nowhere else is an address nobody serves.
+ * `campaign-send.ts` states the same closure from the other end: the sending
+ * identity named in a send request is read by nothing.
+ *
+ * A sender id does not reopen that path. It names a mailbox that was
+ * configured once, validated once and stored on this site, so the set of
+ * addresses a send can reach is the set an org admin already approved. A free
+ * local part in a send body would be the thing that was closed; a key into a
+ * managed list is not.
+ *
+ * ## The DEFAULT is projected onto the host document
+ *
+ * `hosts/{hostId}` has carried `sendingLocalPart`, `sendingFromName` and
+ * `sendingReplyTo` since before this collection existed, and
+ * `resolveHostSendingIdentity` reads the first of them on every tenant send.
+ * Those fields remain the projection of the default sender rather than being
+ * migrated away: a site already sending as `test@` must not revert to `hello@`
+ * because a subcollection it never had is empty.
+ *
+ * So the two are read in a fixed order. An empty subcollection means the site
+ * has exactly one sender, and it is the one the host fields describe —
+ * {@link DEFAULT_HOST_SENDER_ID} is the id it is synthesized under, and the id
+ * it is materialized at the first time anything writes here.
+ *
+ * ## Pure, for the reason the modules either side of it are pure
+ *
+ * The document shape is read by the console route that writes it, by the send
+ * path that resolves a chosen one, and by the surfaces that render the list.
+ * A shape written down three times is a shape that disagrees with itself the
+ * first time any of the three moves.
+ */ import { normalizeLocalPart } from "./sending-domain.js";
+import { headerSafeText, SENDING_FROM_NAME_MAX, SENDING_REPLY_TO_MAX } from "./sending-mailbox.js";
+/** The subcollection under `hosts/{hostId}` that holds a site's senders. */ export const HOST_SENDERS_COLLECTION = 'senders';
+/**
+ * The id the site's original sender lives at.
+ *
+ * A fixed id rather than a generated one, because this document is the
+ * materialized form of something that already existed: the three sender fields
+ * on the host. Materializing it under a random id would make "which row is the
+ * one the host document describes" a question with no answer for anybody
+ * reading the data directly, and would let a second materialization mint a
+ * duplicate of the same sender.
+ */ export const DEFAULT_HOST_SENDER_ID = 'default';
+/**
+ * How many senders one site may hold.
+ *
+ * A ceiling rather than a page. Every sender is a mailbox somebody has to
+ * serve — bounces and replies arrive at it whether or not anyone reads them —
+ * so a list long enough to need paging is a list nobody is operating, and the
+ * composer control that renders it is a picker rather than a directory.
+ */ export const HOST_SENDER_LIMIT = 25;
+/**
+ * One stored sender document, normalized into {@link HostSenderRecord}.
+ *
+ * Every field is re-normalized on the way out rather than trusted. The route
+ * validates on the way in, and a document can also arrive from a restore, a
+ * hand edit or a version of the writer that predates a rule — and these values
+ * reach a `From:` header, where an unflattened one is the injection shape.
+ */ export function readHostSender(options) {
+    var _ref, _ref1, _data_localPart, _data_fromName, _data_replyTo, _ref2;
+    const data = (_ref = options == null ? void 0 : options.data) != null ? _ref : {};
+    const id = String((_ref1 = options == null ? void 0 : options.id) != null ? _ref1 : '');
+    const createdAtMs = Number(data['createdAtMs']);
+    return {
+        id,
+        localPart: normalizeLocalPart(String((_data_localPart = data['localPart']) != null ? _data_localPart : '')),
+        fromName: headerSafeText(String((_data_fromName = data['fromName']) != null ? _data_fromName : ''), SENDING_FROM_NAME_MAX),
+        replyTo: headerSafeText(String((_data_replyTo = data['replyTo']) != null ? _data_replyTo : ''), SENDING_REPLY_TO_MAX).toLowerCase(),
+        isDefault: Boolean(id) && id === String((_ref2 = options == null ? void 0 : options.defaultSenderId) != null ? _ref2 : ''),
+        createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0
+    };
+}
+/**
+ * Which row an unnamed send leaves on, when the stored pointer names nobody.
+ *
+ * `defaultSenderId` is written beside every change that could move it, so the
+ * ordinary case is that it names a row in this list. It can still fail to: a
+ * default deleted out of band, a pointer written before the row it names, a
+ * partial restore. Answering with a row rather than with nothing is what keeps
+ * such a site sending — and the order is fixed, so two readers of the same data
+ * cannot disagree about which sender that is.
+ */ export function defaultHostSender(senders) {
+    var _ref, _senders_find;
+    if (!(senders == null ? void 0 : senders.length)) return null;
+    return (_ref = (_senders_find = senders.find((sender)=>sender.isDefault)) != null ? _senders_find : senders.find((sender)=>sender.id === DEFAULT_HOST_SENDER_ID)) != null ? _ref : [
+        ...senders
+    ].sort((left, right)=>left.createdAtMs - right.createdAtMs || left.id.localeCompare(right.id))[0];
+}
+/**
+ * The whole address one sender leaves on, or `null` on a site whose mailbox is
+ * not its own to name.
+ *
+ * The ONE place a sending address is assembled from its two halves. A surface
+ * that built `${localPart}@${domain}` itself would be a second derivation of
+ * the address, and the two would disagree the first time either moved — which
+ * is the same rule the identity route's `IdentityOption.from` already keeps.
+ */ export function hostSenderAddress(localPart, domain) {
+    const mailbox = normalizeLocalPart(String(localPart != null ? localPart : ''));
+    const zone = String(domain != null ? domain : '').trim().toLowerCase();
+    return mailbox && zone ? `${mailbox}@${zone}` : null;
+}
+
+//# sourceMappingURL=host-sender.js.map

package/src/lib/host-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/host-sender.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 SENDERS ONE SITE HOLDS — `hosts/{hostId}/senders/{senderId}`.\n *\n * A sender is a mailbox this site may send as, together with the display name\n * and reply address that ordinarily go with it. A site holds several and a\n * composer picks among them; which one an unnamed send uses is the site's\n * DEFAULT.\n *\n * ## Chosen BY ID, never typed per send\n *\n * `sending-mailbox.ts` states the rule this collection exists to keep: a\n * mailbox addresses something real — a bounce returns to it, and a client\n * ignoring `Reply-To:` answers to it — so a mailbox that exists in one\n * campaign's headers and nowhere else is an address nobody serves.\n * `campaign-send.ts` states the same closure from the other end: the sending\n * identity named in a send request is read by nothing.\n *\n * A sender id does not reopen that path. It names a mailbox that was\n * configured once, validated once and stored on this site, so the set of\n * addresses a send can reach is the set an org admin already approved. A free\n * local part in a send body would be the thing that was closed; a key into a\n * managed list is not.\n *\n * ## The DEFAULT is projected onto the host document\n *\n * `hosts/{hostId}` has carried `sendingLocalPart`, `sendingFromName` and\n * `sendingReplyTo` since before this collection existed, and\n * `resolveHostSendingIdentity` reads the first of them on every tenant send.\n * Those fields remain the projection of the default sender rather than being\n * migrated away: a site already sending as `test@` must not revert to `hello@`\n * because a subcollection it never had is empty.\n *\n * So the two are read in a fixed order. An empty subcollection means the site\n * has exactly one sender, and it is the one the host fields describe —\n * {@link DEFAULT_HOST_SENDER_ID} is the id it is synthesized under, and the id\n * it is materialized at the first time anything writes here.\n *\n * ## Pure, for the reason the modules either side of it are pure\n *\n * The document shape is read by the console route that writes it, by the send\n * path that resolves a chosen one, and by the surfaces that render the list.\n * A shape written down three times is a shape that disagrees with itself the\n * first time any of the three moves.\n */\n\nimport { normalizeLocalPart } from './sending-domain'\nimport {\n  headerSafeText,\n  SENDING_FROM_NAME_MAX,\n  SENDING_REPLY_TO_MAX,\n} from './sending-mailbox'\n\n/** The subcollection under `hosts/{hostId}` that holds a site's senders. */\nexport const HOST_SENDERS_COLLECTION = 'senders'\n\n/**\n * The id the site's original sender lives at.\n *\n * A fixed id rather than a generated one, because this document is the\n * materialized form of something that already existed: the three sender fields\n * on the host. Materializing it under a random id would make \"which row is the\n * one the host document describes\" a question with no answer for anybody\n * reading the data directly, and would let a second materialization mint a\n * duplicate of the same sender.\n */\nexport const DEFAULT_HOST_SENDER_ID = 'default'\n\n/**\n * How many senders one site may hold.\n *\n * A ceiling rather than a page. Every sender is a mailbox somebody has to\n * serve — bounces and replies arrive at it whether or not anyone reads them —\n * so a list long enough to need paging is a list nobody is operating, and the\n * composer control that renders it is a picker rather than a directory.\n */\nexport const HOST_SENDER_LIMIT = 25\n\n/** One sender, normalized. Every field present; the optional ones as `''`. */\nexport interface HostSenderRecord {\n  id: string\n  /** The mailbox — the part before the `@`. Never empty on a stored row. */\n  localPart: string\n  /** The display name in front of the address, or `''`. */\n  fromName: string\n  /** Where replies go when it is not the sending address, or `''`. */\n  replyTo: string\n  /** Whether an unnamed send leaves on this one. Exactly one row carries it. */\n  isDefault: boolean\n  createdAtMs: number\n}\n\n/**\n * One stored sender document, normalized into {@link HostSenderRecord}.\n *\n * Every field is re-normalized on the way out rather than trusted. The route\n * validates on the way in, and a document can also arrive from a restore, a\n * hand edit or a version of the writer that predates a rule — and these values\n * reach a `From:` header, where an unflattened one is the injection shape.\n */\nexport function readHostSender(options: {\n  id: string\n  data: Record<string, unknown> | null | undefined\n  /** `hosts/{hostId}.defaultSenderId`. Decides {@link HostSenderRecord.isDefault}. */\n  defaultSenderId?: string | null\n}): HostSenderRecord {\n  const data = options?.data ?? {}\n  const id = String(options?.id ?? '')\n  const createdAtMs = Number(data['createdAtMs'])\n  return {\n    id,\n    localPart: normalizeLocalPart(String(data['localPart'] ?? '')),\n    fromName: headerSafeText(\n      String(data['fromName'] ?? ''),\n      SENDING_FROM_NAME_MAX,\n    ),\n    replyTo: headerSafeText(\n      String(data['replyTo'] ?? ''),\n      SENDING_REPLY_TO_MAX,\n    ).toLowerCase(),\n    isDefault: Boolean(id) && id === String(options?.defaultSenderId ?? ''),\n    createdAtMs: Number.isFinite(createdAtMs) ? createdAtMs : 0,\n  }\n}\n\n/**\n * Which row an unnamed send leaves on, when the stored pointer names nobody.\n *\n * `defaultSenderId` is written beside every change that could move it, so the\n * ordinary case is that it names a row in this list. It can still fail to: a\n * default deleted out of band, a pointer written before the row it names, a\n * partial restore. Answering with a row rather than with nothing is what keeps\n * such a site sending — and the order is fixed, so two readers of the same data\n * cannot disagree about which sender that is.\n */\nexport function defaultHostSender(\n  senders: readonly HostSenderRecord[],\n): HostSenderRecord | null {\n  if (!senders?.length) return null\n  return (\n    senders.find((sender) => sender.isDefault) ??\n    senders.find((sender) => sender.id === DEFAULT_HOST_SENDER_ID) ??\n    [...senders].sort(\n      (left, right) =>\n        left.createdAtMs - right.createdAtMs || left.id.localeCompare(right.id),\n    )[0]\n  )\n}\n\n/**\n * The whole address one sender leaves on, or `null` on a site whose mailbox is\n * not its own to name.\n *\n * The ONE place a sending address is assembled from its two halves. A surface\n * that built `${localPart}@${domain}` itself would be a second derivation of\n * the address, and the two would disagree the first time either moved — which\n * is the same rule the identity route's `IdentityOption.from` already keeps.\n */\nexport function hostSenderAddress(\n  localPart: string | null | undefined,\n  domain: string | null | undefined,\n): string | null {\n  const mailbox = normalizeLocalPart(String(localPart ?? ''))\n  const zone = String(domain ?? '')\n    .trim()\n    .toLowerCase()\n  return mailbox && zone ? `${mailbox}@${zone}` : null\n}\n"],"names":["normalizeLocalPart","headerSafeText","SENDING_FROM_NAME_MAX","SENDING_REPLY_TO_MAX","HOST_SENDERS_COLLECTION","DEFAULT_HOST_SENDER_ID","HOST_SENDER_LIMIT","readHostSender","options","data","id","String","createdAtMs","Number","localPart","fromName","replyTo","toLowerCase","isDefault","Boolean","defaultSenderId","isFinite","defaultHostSender","senders","length","find","sender","sort","left","right","localeCompare","hostSenderAddress","domain","mailbox","zone","trim"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CC,GAED,SAASA,kBAAkB,QAAQ,sBAAkB;AACrD,SACEC,cAAc,EACdC,qBAAqB,EACrBC,oBAAoB,QACf,uBAAmB;AAE1B,0EAA0E,GAC1E,OAAO,MAAMC,0BAA0B,UAAS;AAEhD;;;;;;;;;CASC,GACD,OAAO,MAAMC,yBAAyB,UAAS;AAE/C;;;;;;;CAOC,GACD,OAAO,MAAMC,oBAAoB,GAAE;AAgBnC;;;;;;;CAOC,GACD,OAAO,SAASC,eAAeC,OAK9B;qBAMwCC,iBAE5BA,gBAIAA;IAXX,MAAMA,eAAOD,2BAAAA,QAASC,IAAI,mBAAI,CAAC;IAC/B,MAAMC,KAAKC,gBAAOH,2BAAAA,QAASE,EAAE,oBAAI;IACjC,MAAME,cAAcC,OAAOJ,IAAI,CAAC,cAAc;IAC9C,OAAO;QACLC;QACAI,WAAWd,mBAAmBW,QAAOF,kBAAAA,IAAI,CAAC,YAAY,YAAjBA,kBAAqB;QAC1DM,UAAUd,eACRU,QAAOF,iBAAAA,IAAI,CAAC,WAAW,YAAhBA,iBAAoB,KAC3BP;QAEFc,SAASf,eACPU,QAAOF,gBAAAA,IAAI,CAAC,UAAU,YAAfA,gBAAmB,KAC1BN,sBACAc,WAAW;QACbC,WAAWC,QAAQT,OAAOA,OAAOC,gBAAOH,2BAAAA,QAASY,eAAe,oBAAI;QACpER,aAAaC,OAAOQ,QAAQ,CAACT,eAAeA,cAAc;IAC5D;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASU,kBACdC,OAAoC;QAIlCA,MAAAA;IAFF,IAAI,EAACA,2BAAAA,QAASC,MAAM,GAAE,OAAO;IAC7B,QACED,QAAAA,gBAAAA,QAAQE,IAAI,CAAC,CAACC,SAAWA,OAAOR,SAAS,aAAzCK,gBACAA,QAAQE,IAAI,CAAC,CAACC,SAAWA,OAAOhB,EAAE,KAAKL,mCADvCkB,OAEA;WAAIA;KAAQ,CAACI,IAAI,CACf,CAACC,MAAMC,QACLD,KAAKhB,WAAW,GAAGiB,MAAMjB,WAAW,IAAIgB,KAAKlB,EAAE,CAACoB,aAAa,CAACD,MAAMnB,EAAE,EACzE,CAAC,EAAE;AAER;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASqB,kBACdjB,SAAoC,EACpCkB,MAAiC;IAEjC,MAAMC,UAAUjC,mBAAmBW,OAAOG,oBAAAA,YAAa;IACvD,MAAMoB,OAAOvB,OAAOqB,iBAAAA,SAAU,IAC3BG,IAAI,GACJlB,WAAW;IACd,OAAOgB,WAAWC,OAAO,GAAGD,QAAQ,CAAC,EAAEC,MAAM,GAAG;AAClD"}