@nxgt/mail 0.1.0

package/dist/index.js

@@ -0,0 +1,29 @@
+import {
+  pickLocale2,
+  parseAcceptLanguage2
+} from "./chunks/index-vq4e9n8f.js";
+import {
+  recipientsOf2,
+  addressOf2,
+  checkMessage2,
+  createMemoryMailer2
+} from "./chunks/index-0f7kdb8k.js";
+import {
+  MailError2,
+  MailFailure2,
+  MailRefused2
+} from "./chunks/index-we4n5yfz.js";
+export {
+  MailError2 as MailError,
+  MailFailure2 as MailFailure,
+  MailRefused2 as MailRefused,
+  addressOf2 as addressOf,
+  checkMessage2 as checkMessage,
+  createMemoryMailer2 as createMemoryMailer,
+  parseAcceptLanguage2 as parseAcceptLanguage,
+  pickLocale2 as pickLocale,
+  recipientsOf2 as recipientsOf
+};
+
+//# debugId=F6BB19285305093D64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,9 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [
+  ],
+  "mappings": "",
+  "debugId": "F6BB19285305093D64756E2164756E21",
+  "names": []
+}

package/dist/locale.d.ts

@@ -0,0 +1,33 @@
+/** What {@link pickLocale} accepts as the wanted locales. */
+export type WantedLocales = string | null | undefined | readonly (string | null | undefined)[];
+/**
+ * The locale to render an e-mail in: the first wanted locale this build
+ * supports, or `fallback`.
+ *
+ * `wanted` is in order of preference — typically the recipient's stored
+ * locale, then their `Accept-Language` (see {@link parseAcceptLanguage}).
+ * For each wanted locale in turn, an exact match wins (case and `_` or `-`
+ * do not matter), then a match on the language alone: `fr-CA` picks `fr`,
+ * and `fr` picks `fr-CA` when that is the only French supported. Nothing
+ * matching, or nothing wanted, answers `fallback`.
+ *
+ * Pure, with no request context: **the locale of an e-mail is the
+ * recipient's**, usually a field of the user, and not the language of the
+ * request that triggered the send.
+ *
+ * Throws a `TypeError` when `supported` is empty or does not hold `fallback`.
+ * That is a wiring mistake, not a request's.
+ */
+export declare function pickLocale<const L extends string>(wanted: WantedLocales, supported: readonly L[], fallback: NoInfer<L>): L;
+/**
+ * The locales of an `Accept-Language` header, most wanted first.
+ *
+ * Entries are ordered by their `q` weight, ties keeping the header's order;
+ * `q=0` entries and `*` are dropped. A missing or empty header answers `[]`.
+ *
+ * ```ts
+ * parseAcceptLanguage('fr-CA,fr;q=0.9,en;q=0.8'); // ['fr-CA', 'fr', 'en']
+ * ```
+ */
+export declare function parseAcceptLanguage(header: string | null | undefined): string[];
+//# sourceMappingURL=locale.d.ts.map

package/dist/locale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../src/locale.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GACtB,MAAM,GACN,IAAI,GACJ,SAAS,GACT,SAAS,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;AAM1C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAChD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,CAAC,EAAE,EACvB,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,CAAC,CAoBH;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,EAAE,CAeV"}

package/dist/memory.d.ts

@@ -0,0 +1,34 @@
+import { type MailError } from './errors';
+import type { Mailer, MailMessage } from './types';
+/** One message the memory mailer accepted, with the id it gave it. */
+export interface MemoryMail extends MailMessage {
+    readonly messageId: string;
+}
+/**
+ * The reference transport: it keeps what it sends in memory, for tests.
+ *
+ * It refuses exactly what every transport refuses (it calls
+ * {@link checkMessage}), and it can be told to fail, so a test can prove what
+ * the application does when a send throws.
+ */
+export interface MemoryMailer extends Mailer {
+    /** Every message accepted so far, oldest first. A copy: mutating it changes nothing. */
+    readonly sent: readonly MemoryMail[];
+    /**
+     * How many sends reached the hand-over, failed ones included. A message
+     * refused as malformed never reaches it. A caller that retries in secret
+     * shows up here.
+     */
+    readonly attempts: number;
+    /**
+     * Makes the next send that reaches the hand-over reject with `error`, by
+     * default a {@link MailFailure} as an outage would. Calls queue: two calls
+     * fail the next two sends.
+     */
+    failNext(error?: MailError): void;
+    /** Forgets what was sent, the attempts, and any queued failure. */
+    clear(): void;
+}
+/** Creates a {@link MemoryMailer}. Message ids are `memory-1`, `memory-2`, … */
+export declare function createMemoryMailer(): MemoryMailer;
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAe,MAAM,UAAU,CAAC;AAEvD,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAY,MAAM,SAAS,CAAC;AAE7D,sEAAsE;AACtE,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAa,SAAQ,MAAM;IAC3C,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,mEAAmE;IACnE,KAAK,IAAI,IAAI,CAAC;CACd;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,YAAY,CAyCjD"}

package/dist/message.d.ts

@@ -0,0 +1,23 @@
+import type { Address, MailMessage } from './types';
+/** Every recipient of a message, as bare addresses, in order. */
+export declare function recipientsOf(message: MailMessage): string[];
+/** The bare address of an {@link Address}. */
+export declare function addressOf(address: Address): string;
+/**
+ * Refuses a message no transport should hand over, with a {@link MailRefused}
+ * that names **where** the problem is and never the value.
+ *
+ * A transport calls it first thing in `send`, so the refusals are the same
+ * whichever transport is wired. It checks:
+ *
+ * - at least one recipient, each one an address;
+ * - `from` and `replyTo`, when present, are addresses;
+ * - `subject`, `html` and `text` are strings, and `subject` holds no line
+ *   break — a line break in a subject is a header injection;
+ * - every header name is letters, digits and hyphens, none names what the
+ *   transport writes from the message (`To`, `Cc`, `Bcc`, `From`, `Sender`,
+ *   `Reply-To`, `Return-Path`, `Subject`, `MIME-Version`, `Content-*`, in
+ *   any case), and no header value holds a line break.
+ */
+export declare function checkMessage(message: MailMessage): void;
+//# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAgBpD,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CAG3D;AAED,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAElD;AAuBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CA2CvD"}

package/dist/renderer.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `@nxgt/mail/renderer` — fills the files `maizzle build` wrote with
+ * `@nxgt/mail-i18n`. Its own entry because it reads them with `node:fs`: the
+ * main entry, which every transport imports, stays free of Node built-ins.
+ */
+import { type WantedLocales } from './locale';
+import type { Rendered } from './types';
+/**
+ * A value only known at send time. A number is written as `String(n)`; any
+ * other type is refused, so an object never renders as `[object Object]`.
+ */
+export type MailVariables = Readonly<Record<string, string | number>>;
+/**
+ * The e-mails of a build, each with the variables it takes: the `MailEmails`
+ * that `@nxgt/mail-i18n` writes in `generated/mail.ts`.
+ */
+export type MailEmailsOf<E> = {
+    readonly [K in keyof E]: MailVariables;
+};
+/** What any build takes, when the renderer is not given its `MailEmails`. */
+export type AnyMailEmails = Readonly<Record<string, MailVariables>>;
+/**
+ * `render`'s arguments after the e-mail's name: its variables, which may be
+ * left out when it takes none, and the options. An e-mail without variables
+ * is `Readonly<Record<string, never>>`, as `@nxgt/mail-i18n`'s
+ * `rendererTypes()` writes it: change both together.
+ */
+export type RenderArguments<V> = Readonly<Record<string, never>> extends V ? [variables?: V, options?: RenderOptions] : [variables: V, options?: RenderOptions];
+export interface MailRendererOptions {
+    /** The build's output folder — where `mail-manifest.json` is — as `dist`. */
+    readonly dir: string;
+    /**
+     * The locales wanted, most wanted first, asked at each render — as
+     * `@nxgt/i18n`'s language provider: `() => user.locale`, or a Hono
+     * handler's `() => c.get('language')`. Picked with `pickLocale`. Default:
+     * none, so the fallback locale.
+     */
+    readonly getLanguage?: () => WantedLocales;
+    /** The locale when none wanted is built. Default the manifest's. */
+    readonly fallbackLocale?: string;
+}
+export interface RenderOptions {
+    /** Render in this locale, one the build wrote, rather than asking `getLanguage`. */
+    readonly locale?: string;
+}
+/**
+ * Given the build's `MailEmails`, an unknown e-mail, a missing or unknown
+ * variable, or a number for a URL is a compile error; without it, any name
+ * and any variables compile, and the same mistakes throw.
+ */
+export interface MailRenderer<E extends MailEmailsOf<E> = AnyMailEmails> {
+    /** The e-mails of the build, sorted, as `['reset-password', 'verify-email']`. */
+    readonly emails: readonly (keyof E & string)[];
+    /** The locales of the build. */
+    readonly locales: readonly string[];
+    /**
+     * `email` in the wanted locale, every `{{ variable }}` filled: escaped in
+     * `html`, as is in `text` and the subject. A missing or unknown variable,
+     * an unknown e-mail or locale **throws** an `Error`; a URL variable that
+     * is not an `http:`, `https:` or `mailto:` URL throws `MailRefused`.
+     */
+    render<N extends keyof E & string>(email: N, ...rest: RenderArguments<E[N]>): Rendered;
+}
+/**
+ * The run-time renderer: the files `maizzle build` wrote with
+ * `@nxgt/mail-i18n`, filled with the values of one send.
+ *
+ * ```ts
+ * import type { MailEmails } from './generated/mail';
+ *
+ * const mails = createMailRenderer<MailEmails>({ dir: 'dist', getLanguage: () => user.locale });
+ * await mailer.send({ to: user.email, ...mails.render('verify-email', { name, link }) });
+ * ```
+ *
+ * Reads the manifest and every file once, here: a missing or broken build
+ * **throws** when the renderer is created, not at the first send. A wrong
+ * option is a `TypeError`.
+ */
+export declare function createMailRenderer<E extends MailEmailsOf<E> = AnyMailEmails>(options: MailRendererOptions): MailRenderer<E>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKxC;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa;CAAE,CAAC;AAEzE,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAC5B,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,SAAS,CAAC,GACtC,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,GACxC,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,aAAa,CAAC;IAC3C,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa;IACtE,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC;IAC/C,gCAAgC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAChC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAC5B,QAAQ,CAAC;CACZ;AA8ND;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,EAC3E,OAAO,EAAE,mBAAmB,GAC1B,YAAY,CAAC,CAAC,CAAC,CAmDjB"}

package/dist/renderer.js

@@ -0,0 +1,169 @@
+import {
+  pickLocale2
+} from "./chunks/index-vq4e9n8f.js";
+import {
+  MailRefused2
+} from "./chunks/index-we4n5yfz.js";
+
+// src/renderer.ts
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+var MANIFEST_FILE = "mail-manifest.json";
+var PLACEHOLDER = /\{\{\s*([a-z][a-zA-Z0-9]*)\s*\}\}/g;
+var LINE_BREAKS = /[\r\n\v\f\u0085\u2028\u2029]+/g;
+var SAFE_URL = /^(?:https?:\/\/|mailto:)/i;
+var hasUnsafeUrlChar = (value) => [...value].some((char) => {
+  const code = char.codePointAt(0) ?? 0;
+  return code < 33 || code === 127 || /[\s"'<>`]/.test(char);
+});
+var HTML_ESCAPES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+var escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char] ?? char);
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+function checkOptions(options) {
+  if (!isObject(options)) {
+    throw new TypeError("createMailRenderer: options must be an object, as { dir: 'dist' }");
+  }
+  if (typeof options.dir !== "string" || options.dir.trim() === "") {
+    throw new TypeError("createMailRenderer: dir must be the folder maizzle build wrote, as dist");
+  }
+  if (options.getLanguage !== undefined && typeof options.getLanguage !== "function") {
+    throw new TypeError("createMailRenderer: getLanguage must be a function that answers the wanted locales, as () => user.locale");
+  }
+}
+function readBuilt(dir, path) {
+  try {
+    return readFileSync(join(dir, path), "utf8");
+  } catch (error) {
+    throw new Error(`createMailRenderer: ${join(dir, path)} cannot be read — run maizzle build, and deploy its output folder`, { cause: error });
+  }
+}
+function readManifest(dir) {
+  const file = join(dir, MANIFEST_FILE);
+  let manifest;
+  try {
+    manifest = JSON.parse(readBuilt(dir, MANIFEST_FILE));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`createMailRenderer: ${file} is not valid JSON`, {
+        cause: error
+      });
+    }
+    throw error;
+  }
+  if (!isObject(manifest) || !isStringList(manifest.locales) || manifest.locales.length === 0 || typeof manifest.fallbackLocale !== "string" || !isObject(manifest.emails)) {
+    throw new Error(`createMailRenderer: ${file} is not a manifest of @nxgt/mail-i18n — build with its i18n() plugin`);
+  }
+  return {
+    locales: manifest.locales,
+    fallbackLocale: manifest.fallbackLocale,
+    emails: manifest.emails
+  };
+}
+function readEmail(dir, name, entry, locales) {
+  const broken = () => new Error(`createMailRenderer: ${MANIFEST_FILE} describes ${name} in a shape this version does not read — rebuild with the same version of @nxgt/mail-i18n`);
+  if (!isObject(entry) || !isStringList(entry.variables) || !isStringList(entry.urlVariables) || !isObject(entry.subject) || !isObject(entry.files)) {
+    throw broken();
+  }
+  const parts = new Map;
+  for (const locale of locales) {
+    const subject = entry.subject[locale];
+    const files = entry.files[locale];
+    if (typeof subject !== "string" || !isObject(files) || typeof files.html !== "string") {
+      throw broken();
+    }
+    if (typeof files.text !== "string") {
+      throw new Error(`createMailRenderer: ${name} has no text part in ${locale} — keep Maizzle's plaintext on, as @nxgt/mail-config sets it`);
+    }
+    parts.set(locale, {
+      subject,
+      html: readBuilt(dir, files.html),
+      text: readBuilt(dir, files.text)
+    });
+  }
+  return {
+    variables: new Set(entry.variables),
+    urlVariables: new Set(entry.urlVariables),
+    locales: parts
+  };
+}
+function checkVariables(name, email, variables) {
+  if (!isObject(variables)) {
+    throw new TypeError(`render: the variables of ${name} must be an object, as { name: 'Ada' }`);
+  }
+  const values = new Map;
+  for (const [key, value] of Object.entries(variables)) {
+    if (!email.variables.has(key)) {
+      throw new Error(`render: ${name} has no variable ${key} — it takes ${[...email.variables].join(", ") || "none"}`);
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      values.set(key, String(value));
+    } else if (typeof value === "string") {
+      values.set(key, value);
+    } else {
+      throw new TypeError(`render: ${name}: ${key} must be a string or a finite number`);
+    }
+  }
+  for (const key of email.variables) {
+    const value = values.get(key);
+    if (value === undefined) {
+      throw new Error(`render: ${name} needs the variable ${key}`);
+    }
+    if (email.urlVariables.has(key) && (!SAFE_URL.test(value) || hasUnsafeUrlChar(value) || !URL.canParse(value))) {
+      throw new MailRefused2(`render: ${name}: ${key} must be an http:, https: or mailto: URL`);
+    }
+  }
+  return values;
+}
+var fill = (source, values, write) => source.replace(PLACEHOLDER, (mark, key) => {
+  const value = values.get(key);
+  return value === undefined ? mark : write(value);
+});
+function createMailRenderer(options) {
+  checkOptions(options);
+  const { dir } = options;
+  const manifest = readManifest(dir);
+  const fallback = options.fallbackLocale ?? manifest.fallbackLocale;
+  if (!manifest.locales.includes(fallback)) {
+    throw new TypeError(`createMailRenderer: fallbackLocale must be one of the build's locales, ${manifest.locales.join(", ")}`);
+  }
+  const emails = new Map;
+  for (const [name, entry] of Object.entries(manifest.emails)) {
+    emails.set(name, readEmail(dir, name, entry, manifest.locales));
+  }
+  const getLanguage = options.getLanguage;
+  const renderer = Object.freeze({
+    emails: Object.freeze([...emails.keys()].sort()),
+    locales: Object.freeze([...manifest.locales]),
+    render(name, variables = {}, renderOptions = {}) {
+      const email = emails.get(name);
+      if (email === undefined) {
+        throw new Error(`render: ${String(name)} is not an e-mail of the build — one of ${[...emails.keys()].sort().join(", ")}`);
+      }
+      const locale = renderOptions.locale ?? pickLocale2(getLanguage?.(), manifest.locales, fallback);
+      const parts = email.locales.get(locale);
+      if (parts === undefined) {
+        throw new Error(`render: the locale asked for is not one of the build's, ${manifest.locales.join(", ")}`);
+      }
+      const values = checkVariables(name, email, variables);
+      return {
+        subject: fill(parts.subject, values, (value) => value).replace(LINE_BREAKS, " ").trim(),
+        html: fill(parts.html, values, escapeHtml),
+        text: fill(parts.text, values, (value) => value)
+      };
+    }
+  });
+  return renderer;
+}
+export {
+  createMailRenderer
+};
+
+//# debugId=74229904C7DC09F264756E2164756E21
+//# sourceMappingURL=renderer.js.map

package/dist/renderer.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/renderer.ts"],
+  "sourcesContent": [
+    "/**\n * `@nxgt/mail/renderer` — fills the files `maizzle build` wrote with\n * `@nxgt/mail-i18n`. Its own entry because it reads them with `node:fs`: the\n * main entry, which every transport imports, stays free of Node built-ins.\n */\n\nimport { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\nimport { MailRefused } from './errors';\nimport { pickLocale, type WantedLocales } from './locale';\nimport type { Rendered } from './types';\n\n/** The manifest's name in the build's output folder, as `@nxgt/mail-i18n` writes it. */\nconst MANIFEST_FILE = 'mail-manifest.json';\n\n/**\n * A value only known at send time. A number is written as `String(n)`; any\n * other type is refused, so an object never renders as `[object Object]`.\n */\nexport type MailVariables = Readonly<Record<string, string | number>>;\n\n/**\n * The e-mails of a build, each with the variables it takes: the `MailEmails`\n * that `@nxgt/mail-i18n` writes in `generated/mail.ts`.\n */\nexport type MailEmailsOf<E> = { readonly [K in keyof E]: MailVariables };\n\n/** What any build takes, when the renderer is not given its `MailEmails`. */\nexport type AnyMailEmails = Readonly<Record<string, MailVariables>>;\n\n/**\n * `render`'s arguments after the e-mail's name: its variables, which may be\n * left out when it takes none, and the options. An e-mail without variables\n * is `Readonly<Record<string, never>>`, as `@nxgt/mail-i18n`'s\n * `rendererTypes()` writes it: change both together.\n */\nexport type RenderArguments<V> =\n\tReadonly<Record<string, never>> extends V\n\t\t? [variables?: V, options?: RenderOptions]\n\t\t: [variables: V, options?: RenderOptions];\n\nexport interface MailRendererOptions {\n\t/** The build's output folder — where `mail-manifest.json` is — as `dist`. */\n\treadonly dir: string;\n\t/**\n\t * The locales wanted, most wanted first, asked at each render — as\n\t * `@nxgt/i18n`'s language provider: `() => user.locale`, or a Hono\n\t * handler's `() => c.get('language')`. Picked with `pickLocale`. Default:\n\t * none, so the fallback locale.\n\t */\n\treadonly getLanguage?: () => WantedLocales;\n\t/** The locale when none wanted is built. Default the manifest's. */\n\treadonly fallbackLocale?: string;\n}\n\nexport interface RenderOptions {\n\t/** Render in this locale, one the build wrote, rather than asking `getLanguage`. */\n\treadonly locale?: string;\n}\n\n/**\n * Given the build's `MailEmails`, an unknown e-mail, a missing or unknown\n * variable, or a number for a URL is a compile error; without it, any name\n * and any variables compile, and the same mistakes throw.\n */\nexport interface MailRenderer<E extends MailEmailsOf<E> = AnyMailEmails> {\n\t/** The e-mails of the build, sorted, as `['reset-password', 'verify-email']`. */\n\treadonly emails: readonly (keyof E & string)[];\n\t/** The locales of the build. */\n\treadonly locales: readonly string[];\n\t/**\n\t * `email` in the wanted locale, every `{{ variable }}` filled: escaped in\n\t * `html`, as is in `text` and the subject. A missing or unknown variable,\n\t * an unknown e-mail or locale **throws** an `Error`; a URL variable that\n\t * is not an `http:`, `https:` or `mailto:` URL throws `MailRefused`.\n\t */\n\trender<N extends keyof E & string>(\n\t\temail: N,\n\t\t...rest: RenderArguments<E[N]>\n\t): Rendered;\n}\n\n/** One e-mail in one locale, read. */\ninterface Parts {\n\treadonly subject: string;\n\treadonly html: string;\n\treadonly text: string;\n}\n\ninterface Email {\n\treadonly variables: ReadonlySet<string>;\n\treadonly urlVariables: ReadonlySet<string>;\n\treadonly locales: ReadonlyMap<string, Parts>;\n}\n\n/**\n * `{{ name }}` — what `@nxgt/mail-i18n`'s `placeholder('name')` writes. A\n * copy of `PLACEHOLDER` in `packages/mail-i18n/src/manifest.ts`, as is the\n * manifest's shape below: change both, or a declared variable goes unfilled.\n */\nconst PLACEHOLDER = /\\{\\{\\s*([a-z][a-zA-Z0-9]*)\\s*\\}\\}/g;\n\n/** A line break a header would split on: each run becomes one space. */\nconst LINE_BREAKS = /[\\r\\n\\v\\f\\u0085\\u2028\\u2029]+/g;\n\n/** What a URL variable may hold: a scheme a mail client cannot run. */\nconst SAFE_URL = /^(?:https?:\\/\\/|mailto:)/i;\n\n/** Whitespace, a control, a quote or a bracket: what no URL holds as is. */\nconst hasUnsafeUrlChar = (value: string) =>\n\t[...value].some((char) => {\n\t\tconst code = char.codePointAt(0) ?? 0;\n\t\treturn code < 0x21 || code === 0x7f || /[\\s\"'<>`]/.test(char);\n\t});\n\nconst HTML_ESCAPES: Readonly<Record<string, string>> = {\n\t'&': '&amp;',\n\t'<': '&lt;',\n\t'>': '&gt;',\n\t'\"': '&quot;',\n\t\"'\": '&#39;',\n};\n\nconst escapeHtml = (value: string) =>\n\tvalue.replace(/[&<>\"']/g, (char) => HTML_ESCAPES[char] ?? char);\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n\ttypeof value === 'object' && value !== null && !Array.isArray(value);\n\nconst isStringList = (value: unknown): value is string[] =>\n\tArray.isArray(value) && value.every((item) => typeof item === 'string');\n\nfunction checkOptions(options: MailRendererOptions): void {\n\tif (!isObject(options)) {\n\t\tthrow new TypeError(\n\t\t\t\"createMailRenderer: options must be an object, as { dir: 'dist' }\",\n\t\t);\n\t}\n\tif (typeof options.dir !== 'string' || options.dir.trim() === '') {\n\t\tthrow new TypeError(\n\t\t\t'createMailRenderer: dir must be the folder maizzle build wrote, as dist',\n\t\t);\n\t}\n\tif (\n\t\toptions.getLanguage !== undefined &&\n\t\ttypeof options.getLanguage !== 'function'\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createMailRenderer: getLanguage must be a function that answers the wanted locales, as () => user.locale',\n\t\t);\n\t}\n}\n\n/** Reads `dir/path`; a missing file **throws**, naming it. */\nfunction readBuilt(dir: string, path: string): string {\n\ttry {\n\t\treturn readFileSync(join(dir, path), 'utf8');\n\t} catch (error) {\n\t\tthrow new Error(\n\t\t\t`createMailRenderer: ${join(dir, path)} cannot be read — run maizzle build, and deploy its output folder`,\n\t\t\t{ cause: error },\n\t\t);\n\t}\n}\n\n/** The manifest, its shape checked: a broken one **throws**. */\nfunction readManifest(dir: string) {\n\tconst file = join(dir, MANIFEST_FILE);\n\tlet manifest: unknown;\n\ttry {\n\t\tmanifest = JSON.parse(readBuilt(dir, MANIFEST_FILE));\n\t} catch (error) {\n\t\tif (error instanceof SyntaxError) {\n\t\t\tthrow new Error(`createMailRenderer: ${file} is not valid JSON`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t}\n\t\tthrow error;\n\t}\n\tif (\n\t\t!isObject(manifest) ||\n\t\t!isStringList(manifest.locales) ||\n\t\tmanifest.locales.length === 0 ||\n\t\ttypeof manifest.fallbackLocale !== 'string' ||\n\t\t!isObject(manifest.emails)\n\t) {\n\t\tthrow new Error(\n\t\t\t`createMailRenderer: ${file} is not a manifest of @nxgt/mail-i18n — build with its i18n() plugin`,\n\t\t);\n\t}\n\treturn {\n\t\tlocales: manifest.locales,\n\t\tfallbackLocale: manifest.fallbackLocale,\n\t\temails: manifest.emails,\n\t};\n}\n\n/** One e-mail of the manifest, with its files read in every locale. */\nfunction readEmail(\n\tdir: string,\n\tname: string,\n\tentry: unknown,\n\tlocales: readonly string[],\n): Email {\n\tconst broken = () =>\n\t\tnew Error(\n\t\t\t`createMailRenderer: ${MANIFEST_FILE} describes ${name} in a shape this version does not read — rebuild with the same version of @nxgt/mail-i18n`,\n\t\t);\n\tif (\n\t\t!isObject(entry) ||\n\t\t!isStringList(entry.variables) ||\n\t\t!isStringList(entry.urlVariables) ||\n\t\t!isObject(entry.subject) ||\n\t\t!isObject(entry.files)\n\t) {\n\t\tthrow broken();\n\t}\n\tconst parts = new Map<string, Parts>();\n\tfor (const locale of locales) {\n\t\tconst subject = entry.subject[locale];\n\t\tconst files = entry.files[locale];\n\t\tif (\n\t\t\ttypeof subject !== 'string' ||\n\t\t\t!isObject(files) ||\n\t\t\ttypeof files.html !== 'string'\n\t\t) {\n\t\t\tthrow broken();\n\t\t}\n\t\tif (typeof files.text !== 'string') {\n\t\t\tthrow new Error(\n\t\t\t\t`createMailRenderer: ${name} has no text part in ${locale} — keep Maizzle's plaintext on, as @nxgt/mail-config sets it`,\n\t\t\t);\n\t\t}\n\t\tparts.set(locale, {\n\t\t\tsubject,\n\t\t\thtml: readBuilt(dir, files.html),\n\t\t\ttext: readBuilt(dir, files.text),\n\t\t});\n\t}\n\treturn {\n\t\tvariables: new Set(entry.variables),\n\t\turlVariables: new Set(entry.urlVariables),\n\t\tlocales: parts,\n\t};\n}\n\n/** Each variable of `email` as a string, checked against what it declares. */\nfunction checkVariables(\n\tname: string,\n\temail: Email,\n\tvariables: unknown,\n): Map<string, string> {\n\tif (!isObject(variables)) {\n\t\tthrow new TypeError(\n\t\t\t`render: the variables of ${name} must be an object, as { name: 'Ada' }`,\n\t\t);\n\t}\n\tconst values = new Map<string, string>();\n\tfor (const [key, value] of Object.entries(variables)) {\n\t\tif (!email.variables.has(key)) {\n\t\t\tthrow new Error(\n\t\t\t\t`render: ${name} has no variable ${key} — it takes ${[...email.variables].join(', ') || 'none'}`,\n\t\t\t);\n\t\t}\n\t\tif (typeof value === 'number' && Number.isFinite(value)) {\n\t\t\tvalues.set(key, String(value));\n\t\t} else if (typeof value === 'string') {\n\t\t\tvalues.set(key, value);\n\t\t} else {\n\t\t\tthrow new TypeError(\n\t\t\t\t`render: ${name}: ${key} must be a string or a finite number`,\n\t\t\t);\n\t\t}\n\t}\n\tfor (const key of email.variables) {\n\t\tconst value = values.get(key);\n\t\tif (value === undefined) {\n\t\t\tthrow new Error(`render: ${name} needs the variable ${key}`);\n\t\t}\n\t\tif (\n\t\t\temail.urlVariables.has(key) &&\n\t\t\t(!SAFE_URL.test(value) || hasUnsafeUrlChar(value) || !URL.canParse(value))\n\t\t) {\n\t\t\tthrow new MailRefused(\n\t\t\t\t`render: ${name}: ${key} must be an http:, https: or mailto: URL`,\n\t\t\t);\n\t\t}\n\t}\n\treturn values;\n}\n\n/** `source` with each placeholder replaced, in one pass: a value is never read again. */\nconst fill = (\n\tsource: string,\n\tvalues: ReadonlyMap<string, string>,\n\twrite: (value: string) => string,\n) =>\n\tsource.replace(PLACEHOLDER, (mark, key: string) => {\n\t\tconst value = values.get(key);\n\t\treturn value === undefined ? mark : write(value);\n\t});\n\n/**\n * The run-time renderer: the files `maizzle build` wrote with\n * `@nxgt/mail-i18n`, filled with the values of one send.\n *\n * ```ts\n * import type { MailEmails } from './generated/mail';\n *\n * const mails = createMailRenderer<MailEmails>({ dir: 'dist', getLanguage: () => user.locale });\n * await mailer.send({ to: user.email, ...mails.render('verify-email', { name, link }) });\n * ```\n *\n * Reads the manifest and every file once, here: a missing or broken build\n * **throws** when the renderer is created, not at the first send. A wrong\n * option is a `TypeError`.\n */\nexport function createMailRenderer<E extends MailEmailsOf<E> = AnyMailEmails>(\n\toptions: MailRendererOptions,\n): MailRenderer<E> {\n\tcheckOptions(options);\n\tconst { dir } = options;\n\tconst manifest = readManifest(dir);\n\tconst fallback = options.fallbackLocale ?? manifest.fallbackLocale;\n\tif (!manifest.locales.includes(fallback)) {\n\t\tthrow new TypeError(\n\t\t\t`createMailRenderer: fallbackLocale must be one of the build's locales, ${manifest.locales.join(', ')}`,\n\t\t);\n\t}\n\tconst emails = new Map<string, Email>();\n\tfor (const [name, entry] of Object.entries(manifest.emails)) {\n\t\temails.set(name, readEmail(dir, name, entry, manifest.locales));\n\t}\n\tconst getLanguage = options.getLanguage;\n\n\tconst renderer: MailRenderer = Object.freeze({\n\t\temails: Object.freeze([...emails.keys()].sort()),\n\t\tlocales: Object.freeze([...manifest.locales]),\n\t\trender(\n\t\t\tname: string,\n\t\t\tvariables: MailVariables = {},\n\t\t\trenderOptions: RenderOptions = {},\n\t\t): Rendered {\n\t\t\tconst email = emails.get(name);\n\t\t\tif (email === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`render: ${String(name)} is not an e-mail of the build — one of ${[...emails.keys()].sort().join(', ')}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst locale =\n\t\t\t\trenderOptions.locale ??\n\t\t\t\tpickLocale(getLanguage?.(), manifest.locales, fallback);\n\t\t\tconst parts = email.locales.get(locale);\n\t\t\tif (parts === undefined) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`render: the locale asked for is not one of the build's, ${manifest.locales.join(', ')}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst values = checkVariables(name, email, variables);\n\t\t\treturn {\n\t\t\t\tsubject: fill(parts.subject, values, (value) => value)\n\t\t\t\t\t.replace(LINE_BREAKS, ' ')\n\t\t\t\t\t.trim(),\n\t\t\t\thtml: fill(parts.html, values, escapeHtml),\n\t\t\t\ttext: fill(parts.text, values, (value) => value),\n\t\t\t};\n\t\t},\n\t});\n\t// The types only narrow what the same checks refuse at run time.\n\treturn renderer as unknown as MailRenderer<E>;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "74229904C7DC09F264756E2164756E21",
+  "names": []
+}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * An e-mail address: bare (`ada@example.com`), or with the name a mail client
+ * shows beside it.
+ *
+ * A string is **only** an address — `"Ada <ada@example.com>"` is refused, and
+ * so is a string holding whitespace, `,`, `;` or `:` — so a transport never
+ * has to parse one, and a parser that does finds one mailbox. A name is free text (`Doe, John` is a
+ * name), refused only when it holds a line break; **quoting or encoding it
+ * is the transport's job**, and the conformance case `send.hostileName`
+ * fails a transport whose name lets a second recipient through.
+ */
+export type Address = string | {
+    readonly name: string;
+    readonly address: string;
+};
+/**
+ * The three parts of one e-mail, in one locale, with every value already
+ * filled in and escaped: what the run-time renderer answers
+ * (`createMailRenderer(…).render(…)`), or any hand-written function answering the
+ * same shape — escaping is then that function's job.
+ */
+export interface Rendered {
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+}
+/**
+ * A rendered e-mail, addressed. What a {@link Mailer} sends.
+ *
+ * `from` is optional because a transport is usually wired with a default
+ * sender; a transport with none refuses a message without one.
+ */
+export interface MailMessage extends Rendered {
+    readonly to: Address | readonly Address[];
+    readonly from?: Address;
+    readonly replyTo?: Address;
+    /**
+     * Extra headers, such as `List-Unsubscribe`. A name is letters, digits and
+     * hyphens; neither a name nor a value may hold a line break. What the
+     * transport writes from the message — `To`, `Cc`, `Bcc`, `From`, `Sender`,
+     * `Reply-To`, `Return-Path`, `Subject`, `MIME-Version`, `Content-*`, in any
+     * case — is refused.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** What a transport answers once it has handed a message over. */
+export interface SentMail {
+    /**
+     * The id the transport gave the message, or `null` when it gives none. An
+     * absence, not a failure: a failure throws.
+     */
+    readonly messageId: string | null;
+}
+/**
+ * The port every transport implements.
+ *
+ * **A failure throws; it never answers.** `send` resolves only once the
+ * transport has accepted the message. Otherwise it rejects with a
+ * {@link MailFailure} (the transport could not be reached or did not answer)
+ * or a {@link MailRefused} (the message itself was refused). It never resolves
+ * `false`, and it never logs and resolves: a caller that maps a failed send to
+ * "sent" has told a user to check an inbox that will stay empty.
+ *
+ * `@nxgt/mail/conformance` checks a transport against this contract.
+ */
+export interface Mailer {
+    send(message: MailMessage): Promise<SentMail>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,OAAO,GAChB,MAAM,GACN;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC5C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,kEAAkE;AAClE,MAAM,WAAW,QAAQ;IACxB;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,MAAM;IACtB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9C"}

package/docs/README.md

@@ -0,0 +1,16 @@
+# @nxgt/mail — documentation
+
+The [README](../README.md) shows that it works; these pages show how, one area
+at a time, with an example for every option. The words they use — e-mail,
+mailer, transport, hand-over, refusal, failure — are defined once, in the
+[vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md).
+
+| Page | Read it when |
+| --- | --- |
+| [Rendering](guide/rendering.md) | You are turning a Maizzle build of `@nxgt/mail-i18n` into an e-mail with `createMailRenderer`: its options, typing it with the build's `MailEmails`, choosing the locale, escaping, URL variables, deploying the build, and every error |
+| [Sending](guide/sending.md) | You are calling `mailer.send`: the `MailMessage` shape, addresses, headers, what `send` answers, and turning `MailFailure` and `MailRefused` into a response |
+| [Testing](guide/testing.md) | You are testing code that sends e-mail with `createMemoryMailer`: reading the outbox, making a send fail, counting attempts |
+| [Locales](guide/locales.md) | You are choosing the locale an e-mail is rendered in, with `pickLocale` and `parseAcceptLanguage` |
+| [Writing a transport](guide/transports.md) | You are implementing the `Mailer` port for a provider, and running `@nxgt/mail/conformance` against it |
+| [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
+| [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |