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

package/src/lib/stored-email-nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/stored-email-nodes.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 { decode } from '@msgpack/msgpack'\n\n/**\n * A COPY of `decodeStoredNodes` from `@aglyn/aglyn` (AGL-1223), for the same\n * reason `email-media-src.ts` carries a copy of `resolveMediaSrc`:\n * `shared-util-email` is tagged `scope:shared`, the module-boundary rule makes\n * shared libs leaves, and the arrow points the other way so every send site\n * can pull the email renderer without the framework.\n *\n * `email-nodes-drift.spec.ts` in the console — which may import both — runs\n * the two implementations over one table of inputs, so a divergence fails a\n * build rather than silently changing what a recipient receives.\n *\n * ## Why an email loader needs this at all\n *\n * An email version's `nodes` is stored in the same two live forms every other\n * besigner document uses: a plain Firestore map, and msgpack bytes. Reading\n * the field raw is not a loud failure — a `Buffer` walks, `Object.keys` over\n * one returns BYTE INDICES rather than nothing, so an emptiness guard passes\n * and the send renders an empty email instead of falling back to its built-in\n * copy.\n */\nexport function decodeEmailNodes<T = Record<string, unknown>>(\n  raw: unknown,\n): T | null {\n  if (raw === null || raw === undefined) return null\n  const bytes = ArrayBuffer.isView(raw)\n    ? // Offset and length, ALWAYS. firebase-admin hands back POOLED Buffers,\n      // so a small field is typically a view into a shared 8 KB allocation\n      // and decoding the whole pool throws on the trailing bytes.\n      new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength)\n    : byteSourceBytes(raw) ?? bufferEnvelopeBytes(raw)\n  if (bytes) {\n    try {\n      return decode(bytes) as T\n    } catch (error) {\n      // Undecodable nodes must never read as \"this template is empty\" — that\n      // is indistinguishable from a template nobody has designed yet.\n      console.error('could not decode stored email nodes', error)\n      return null\n    }\n  }\n  return raw as T\n}\n\n/**\n * The client SDK's `Bytes`, structurally. Matched on the method rather than\n * the class so no Firestore package is imported here. A node map cannot\n * collide: its values are node OBJECTS, never functions.\n */\nfunction byteSourceBytes(raw: unknown): Uint8Array | null {\n  if (typeof raw !== 'object') return null\n  const source = raw as { toUint8Array?: unknown }\n  return typeof source.toUint8Array === 'function'\n    ? (source.toUint8Array as () => Uint8Array)()\n    : null\n}\n\n/**\n * A JSON-serialized Node `Buffer` — what `JSON.stringify` makes of one\n * (AGL-1391). The test is deliberately exact, because the alternative reading\n * is a node map with nodes called `type` and `data`; that map cannot exist,\n * since `type` would have to hold the literal string `'Buffer'` and `data` an\n * array, in the same document.\n */\nfunction bufferEnvelopeBytes(raw: unknown): Uint8Array | null {\n  if (typeof raw !== 'object' || Array.isArray(raw)) return null\n  const value = raw as { type?: unknown; data?: unknown }\n  if (value.type !== 'Buffer' || !Array.isArray(value.data)) return null\n  if (Object.keys(value).length !== 2) return null\n  return Uint8Array.from(value.data as number[])\n}\n\nexport default decodeEmailNodes\n"],"names":["decode","decodeEmailNodes","raw","byteSourceBytes","undefined","bytes","ArrayBuffer","isView","Uint8Array","buffer","byteOffset","byteLength","bufferEnvelopeBytes","error","console","source","toUint8Array","Array","isArray","value","type","data","Object","keys","length","from"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,MAAM,QAAQ,mBAAkB;AAEzC;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,iBACdC,GAAY;QAQRC;IANJ,IAAID,QAAQ,QAAQA,QAAQE,WAAW,OAAO;IAC9C,MAAMC,QAAQC,YAAYC,MAAM,CAACL,OAE7B,qEAAqE;IACrE,4DAA4D;IAC5D,IAAIM,WAAWN,IAAIO,MAAM,EAAEP,IAAIQ,UAAU,EAAER,IAAIS,UAAU,KACzDR,mBAAAA,gBAAgBD,gBAAhBC,mBAAwBS,oBAAoBV;IAChD,IAAIG,OAAO;QACT,IAAI;YACF,OAAOL,OAAOK;QAChB,EAAE,OAAOQ,OAAO;YACd,uEAAuE;YACvE,gEAAgE;YAChEC,QAAQD,KAAK,CAAC,uCAAuCA;YACrD,OAAO;QACT;IACF;IACA,OAAOX;AACT;AAEA;;;;CAIC,GACD,SAASC,gBAAgBD,GAAY;IACnC,IAAI,OAAOA,QAAQ,UAAU,OAAO;IACpC,MAAMa,SAASb;IACf,OAAO,OAAOa,OAAOC,YAAY,KAAK,aAClC,AAACD,OAAOC,YAAY,KACpB;AACN;AAEA;;;;;;CAMC,GACD,SAASJ,oBAAoBV,GAAY;IACvC,IAAI,OAAOA,QAAQ,YAAYe,MAAMC,OAAO,CAAChB,MAAM,OAAO;IAC1D,MAAMiB,QAAQjB;IACd,IAAIiB,MAAMC,IAAI,KAAK,YAAY,CAACH,MAAMC,OAAO,CAACC,MAAME,IAAI,GAAG,OAAO;IAClE,IAAIC,OAAOC,IAAI,CAACJ,OAAOK,MAAM,KAAK,GAAG,OAAO;IAC5C,OAAOhB,WAAWiB,IAAI,CAACN,MAAME,IAAI;AACnC;AAEA,eAAepB,iBAAgB"}

package/src/lib/svix-signature.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @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 ONE SVIX SIGNATURE CHECK.
+ *
+ * Resend signs every webhook the Svix way: HMAC-SHA256 over
+ * `{svix-id}.{svix-timestamp}.{raw body}` with the base64 secret after
+ * `whsec_`, and a `svix-signature` header carrying space-delimited
+ * `v1,<base64>` entries, any one of which may match during a secret
+ * rotation. The delivery-events webhook has verified this since AGL-268;
+ * the CRM's capture webhook (AGL-2657) verifies it too, and a second
+ * implementation would be a second place for the comparison to stop being
+ * constant-time. So the check lives here, and both import it.
+ *
+ * Signs the RAW body — the exact request text, never a re-serialization —
+ * which is why the callers hand this a `Buffer` of `req.rawBody`.
+ */
+export declare function verifySvixSignature(secret: string, id: string, timestamp: string, payload: Buffer, signatureHeader: string): boolean;
+/**
+ * The `svix-signature` header value a test fixture or a replay tool signs a
+ * payload with — the inverse of {@link verifySvixSignature}, so a spec never
+ * spells the HMAC recipe a second time.
+ */
+export declare function signSvixPayload(secret: string, id: string, timestamp: string, payload: Buffer | string): string;

package/src/lib/svix-signature.js

@@ -0,0 +1,55 @@
+/**
+ * @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 { createHmac, timingSafeEqual } from "crypto";
+/**
+ * THE ONE SVIX SIGNATURE CHECK.
+ *
+ * Resend signs every webhook the Svix way: HMAC-SHA256 over
+ * `{svix-id}.{svix-timestamp}.{raw body}` with the base64 secret after
+ * `whsec_`, and a `svix-signature` header carrying space-delimited
+ * `v1,<base64>` entries, any one of which may match during a secret
+ * rotation. The delivery-events webhook has verified this since AGL-268;
+ * the CRM's capture webhook (AGL-2657) verifies it too, and a second
+ * implementation would be a second place for the comparison to stop being
+ * constant-time. So the check lives here, and both import it.
+ *
+ * Signs the RAW body — the exact request text, never a re-serialization —
+ * which is why the callers hand this a `Buffer` of `req.rawBody`.
+ */ export function verifySvixSignature(secret, id, timestamp, payload, signatureHeader) {
+    try {
+        const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
+        const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(payload).digest();
+        return signatureHeader.split(' ').some((entry)=>{
+            const [, signature] = entry.split(',');
+            if (!signature) return false;
+            const candidate = Buffer.from(signature, 'base64');
+            return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+        });
+    } catch (unused) {
+        return false;
+    }
+}
+/**
+ * The `svix-signature` header value a test fixture or a replay tool signs a
+ * payload with — the inverse of {@link verifySvixSignature}, so a spec never
+ * spells the HMAC recipe a second time.
+ */ export function signSvixPayload(secret, id, timestamp, payload) {
+    const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
+    const signature = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload).digest('base64');
+    return `v1,${signature}`;
+}
+
+//# sourceMappingURL=svix-signature.js.map

package/src/lib/svix-signature.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/email/src/lib/svix-signature.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 { createHmac, timingSafeEqual } from 'crypto'\n\n/**\n * THE ONE SVIX SIGNATURE CHECK.\n *\n * Resend signs every webhook the Svix way: HMAC-SHA256 over\n * `{svix-id}.{svix-timestamp}.{raw body}` with the base64 secret after\n * `whsec_`, and a `svix-signature` header carrying space-delimited\n * `v1,<base64>` entries, any one of which may match during a secret\n * rotation. The delivery-events webhook has verified this since AGL-268;\n * the CRM's capture webhook (AGL-2657) verifies it too, and a second\n * implementation would be a second place for the comparison to stop being\n * constant-time. So the check lives here, and both import it.\n *\n * Signs the RAW body — the exact request text, never a re-serialization —\n * which is why the callers hand this a `Buffer` of `req.rawBody`.\n */\nexport function verifySvixSignature(\n  secret: string,\n  id: string,\n  timestamp: string,\n  payload: Buffer,\n  signatureHeader: string,\n): boolean {\n  try {\n    const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')\n    const expected = createHmac('sha256', key)\n      .update(`${id}.${timestamp}.`)\n      .update(payload)\n      .digest()\n    return signatureHeader.split(' ').some((entry) => {\n      const [, signature] = entry.split(',')\n      if (!signature) return false\n      const candidate = Buffer.from(signature, 'base64')\n      return (\n        candidate.length === expected.length &&\n        timingSafeEqual(candidate, expected)\n      )\n    })\n  } catch {\n    return false\n  }\n}\n\n/**\n * The `svix-signature` header value a test fixture or a replay tool signs a\n * payload with — the inverse of {@link verifySvixSignature}, so a spec never\n * spells the HMAC recipe a second time.\n */\nexport function signSvixPayload(\n  secret: string,\n  id: string,\n  timestamp: string,\n  payload: Buffer | string,\n): string {\n  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')\n  const signature = createHmac('sha256', key)\n    .update(`${id}.${timestamp}.`)\n    .update(typeof payload === 'string' ? Buffer.from(payload, 'utf8') : payload)\n    .digest('base64')\n  return `v1,${signature}`\n}\n"],"names":["createHmac","timingSafeEqual","verifySvixSignature","secret","id","timestamp","payload","signatureHeader","key","Buffer","from","replace","expected","update","digest","split","some","entry","signature","candidate","length","signSvixPayload"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,UAAU,EAAEC,eAAe,QAAQ,SAAQ;AAEpD;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,oBACdC,MAAc,EACdC,EAAU,EACVC,SAAiB,EACjBC,OAAe,EACfC,eAAuB;IAEvB,IAAI;QACF,MAAMC,MAAMC,OAAOC,IAAI,CAACP,OAAOQ,OAAO,CAAC,WAAW,KAAK;QACvD,MAAMC,WAAWZ,WAAW,UAAUQ,KACnCK,MAAM,CAAC,GAAGT,GAAG,CAAC,EAAEC,UAAU,CAAC,CAAC,EAC5BQ,MAAM,CAACP,SACPQ,MAAM;QACT,OAAOP,gBAAgBQ,KAAK,CAAC,KAAKC,IAAI,CAAC,CAACC;YACtC,MAAM,GAAGC,UAAU,GAAGD,MAAMF,KAAK,CAAC;YAClC,IAAI,CAACG,WAAW,OAAO;YACvB,MAAMC,YAAYV,OAAOC,IAAI,CAACQ,WAAW;YACzC,OACEC,UAAUC,MAAM,KAAKR,SAASQ,MAAM,IACpCnB,gBAAgBkB,WAAWP;QAE/B;IACF,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASS,gBACdlB,MAAc,EACdC,EAAU,EACVC,SAAiB,EACjBC,OAAwB;IAExB,MAAME,MAAMC,OAAOC,IAAI,CAACP,OAAOQ,OAAO,CAAC,WAAW,KAAK;IACvD,MAAMO,YAAYlB,WAAW,UAAUQ,KACpCK,MAAM,CAAC,GAAGT,GAAG,CAAC,EAAEC,UAAU,CAAC,CAAC,EAC5BQ,MAAM,CAAC,OAAOP,YAAY,WAAWG,OAAOC,IAAI,CAACJ,SAAS,UAAUA,SACpEQ,MAAM,CAAC;IACV,OAAO,CAAC,GAAG,EAAEI,WAAW;AAC1B"}

package/src/lib/system-email-catalog.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @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.
+ */
+/**
+ * Who actually puts the message on the wire.
+ *
+ * `resend` — Aglyn composes and sends it, so a besigner template can change
+ * what the recipient sees.
+ *
+ * `firebase` — Firebase Auth sends it from its own templates, configured in
+ * the Firebase console. **A besigner template cannot affect these at all**
+ * because the sender owns the copy (AGL-767).
+ *
+ * `stripe` — Stripe sends it on Aglyn's behalf from the Dashboard's
+ * Customer-emails settings (billing receipts, dunning, refunds, expiring-card
+ * notices). Aglyn never composes these, so like `firebase` they cannot be
+ * designed here (AGL-767).
+ *
+ * The non-`resend` entries are listed so staff can see the full set of mail
+ * the product sends and where each one is controlled; the UI must present
+ * them as non-editable rather than offering an editor that silently does
+ * nothing.
+ */
+/**
+ * Who actually puts the message on the wire.
+ *
+ * `'firebase'` was removed by AGL-1112, once nothing was left that Firebase
+ * Auth composed. Deliberately not kept "just in case": with the variant gone,
+ * reintroducing a Firebase-sent email is a compile error rather than a row in
+ * a table that quietly stops being editable. The staff editor is wired to
+ * `'resend'`, so any other value silently produces a template that renders
+ * nothing — which is exactly how the `[aglyn.io]` subject survived so long.
+ */
+export type SystemEmailDeliveredBy = 'resend' | 'stripe';
+export interface SystemEmailMergeToken {
+    /** Token as written in the template, without braces. */
+    name: string;
+    description: string;
+    /** Stand-in used by the staff preview. */
+    sample: string;
+}
+/**
+ * One block of a template's starting content (AGL-764). Declarative on
+ * purpose: the catalog stays a dependency-free data module, and the console
+ * turns these into email-plugin nodes (`emailSection` → `emailText`/
+ * `emailButton`) when it seeds the first version. Mirror the copy the send
+ * site uses today, with the same `{{tokens}}`, so a staffer who opens the
+ * editor starts from what recipients actually get rather than a blank canvas.
+ */
+export type SystemEmailDefaultBlock = {
+    block: 'text';
+    text: string;
+    variant?: 'heading' | 'subheading' | 'body' | 'caption';
+} | {
+    block: 'button';
+    label: string;
+    href: string;
+};
+export interface SystemEmailTemplateDefinition {
+    /** Stable storage key — the Firestore document id. Never rename. */
+    key: string;
+    name: string;
+    description: string;
+    deliveredBy: SystemEmailDeliveredBy;
+    /** Subject used when no template has been published. */
+    defaultSubject: string;
+    mergeTokens: SystemEmailMergeToken[];
+    /**
+     * Starting content for the first version staff design (AGL-764). Every
+     * `resend` template should carry one; a `firebase` template has no editor
+     * so it needs none. Absent → the editor seeds a minimal placeholder.
+     */
+    defaultBody?: readonly SystemEmailDefaultBlock[];
+    /**
+     * Where the fallback copy lives, for staff wondering what recipients get
+     * today. Informational — nothing reads it at runtime.
+     */
+    source: string;
+}
+/**
+ * Every system email Aglyn sends.
+ *
+ * Deliberately **code-defined and fixed**: staff edit the system emails that
+ * exist, they do not create or delete them. Adding one is a code change,
+ * which is what keeps this list from drifting into advertising an email the
+ * product never actually sends — the failure mode a Firestore-backed list
+ * would have.
+ *
+ * The staff page renders from this registry, not from Firestore, so an email
+ * with no template designed yet still appears (as "Using default").
+ */
+/**
+ * Brand tokens EVERY system email resolves (AGL-2139).
+ *
+ * White-label used to invert precisely when staff published a template: the
+ * designed template wins over each sender's branded fallback, and the copy
+ * here hard-coded "Aglyn". Nor was there anything to design against — the
+ * merge maps carried `org.name`, `invite.role`, `signInUrl` and friends and
+ * nothing about the brand, while `blankUnresolvedTokens` DELETES any token
+ * the caller did not supply, so a designer who typed `{{brand.productName}}`
+ * would have shipped an email with a hole in the sentence.
+ *
+ * Declared once and appended to every template's own list rather than copied
+ * into each: 13 hand-maintained copies is how the token list falls behind the
+ * copy, and the editor renders this list as the palette a designer picks
+ * from — a token missing here is a token nobody knows exists.
+ *
+ * The samples are the DEPLOYMENT's own values (`BRAND.ORG_NAME`, AGL-2319),
+ * because that is what an unbranded org genuinely renders — on a self-host
+ * install a hardcoded "Aglyn" would preview a brand that appears nowhere in
+ * the mail the designer is editing.
+ */
+export declare const BRAND_MERGE_TOKENS: readonly SystemEmailMergeToken[];
+/**
+ * Every system email Aglyn sends, each with the universal brand tokens
+ * appended to its own (AGL-2139).
+ *
+ * The template's own tokens come FIRST so the editor's palette still leads
+ * with what is specific to that email; the brand block reads as the shared
+ * footer it is.
+ */
+export declare const SYSTEM_EMAIL_TEMPLATES: readonly SystemEmailTemplateDefinition[];
+/** Firestore collection holding the designed templates. */
+export declare const SYSTEM_EMAIL_COLLECTION = "systemEmailTemplates";
+export declare function getSystemEmailTemplate(key: string): SystemEmailTemplateDefinition | undefined;
+/** True when a besigner template can actually change what is delivered. */
+export declare function isSystemEmailEditable(definition: SystemEmailTemplateDefinition): boolean;
+/** The stored template document, when staff have designed one. */
+export interface SystemEmailTemplateDoc {
+    subject?: string;
+    preheader?: string;
+    versionId?: string;
+    updatedAt?: unknown;
+    updatedByEmail?: string;
+}
+/** A besigner node in the flat, denormalized map a version stores. */
+export interface SystemEmailNode {
+    $id: string;
+    componentId: string;
+    pluginId?: string;
+    parentId?: string;
+    props?: Record<string, unknown>;
+    nodes?: string[];
+}
+/**
+ * Turns a template's `defaultBody` into the besigner node map the editor
+ * seeds and the send-time default renders (AGL-764/766).
+ *
+ * One place builds this so the two never diverge — the version a staffer
+ * opens is byte-for-byte what a test/send renders when nothing is published.
+ * Rooted at {@link EMAIL_NODE_ROOT_ID} so `renderEmailHtml` finds it (AGL-765),
+ * with deterministic ids: a version doc only needs ids unique within itself,
+ * and determinism keeps the map stable and diffable.
+ */
+export declare function buildDefaultEmailNodeMap(definition: {
+    defaultBody?: readonly SystemEmailDefaultBlock[];
+}): Record<string, SystemEmailNode>;