@nxgt/janus-mail 0.1.0

package/dist/janus-mail.d.ts

@@ -0,0 +1,24 @@
+import type { JanusMail, JanusMailLocale, JanusMailOptions } from './types';
+/**
+ * The e-mails of Janus's flows, over your mailer:
+ *
+ * ```ts
+ * const mail = janusMail({
+ * 	mailer,
+ * 	from: 'noreply@acme.example',
+ * 	brand: 'Acme',
+ * 	links: {
+ * 		verifyEmail: (token) => `https://acme.example/verify?token=${token}`,
+ * 		resetPassword: (token) => `https://acme.example/reset?token=${token}`,
+ * 		secureAccount: () => 'https://acme.example/account/security',
+ * 	},
+ * });
+ *
+ * await mail.verifyEmail(await auth.verifyEmail.send(user), { name: user.name, locale: user.locale });
+ * ```
+ *
+ * Reads nothing when called: the default e-mails are read on the first one
+ * sent. A wrong option is a bare `TypeError`, thrown here.
+ */
+export declare function janusMail<const L extends string = JanusMailLocale>(options: JanusMailOptions<L>): JanusMail<L>;
+//# sourceMappingURL=janus-mail.d.ts.map

package/dist/janus-mail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"janus-mail.d.ts","sourceRoot":"","sources":["../src/janus-mail.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACX,SAAS,EACT,eAAe,EACf,gBAAgB,EAGhB,MAAM,SAAS,CAAC;AAqJjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,eAAe,EACjE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAC1B,SAAS,CAAC,CAAC,CAAC,CASd"}

package/dist/mails.d.ts

@@ -0,0 +1,26 @@
+import { type MailRenderer } from '@nxgt/mail/renderer';
+import type { MailEmails } from './generated/mail';
+/**
+ * The folder of the built e-mails, resolved from this module rather than from
+ * the working directory, which is the consumer's.
+ *
+ * **This file must stay directly under `src/`.** `../mails/` is right from
+ * `src/mails.ts` in the specs, and from `dist/index.js` in the tarball,
+ * because the build bundles this module into the single entry
+ * `dist/index.js`, one level under the package as `src/` is. Moved into a
+ * subfolder, or bundled into `dist/chunks/` by a second entry point, it would
+ * resolve a folder that does not exist — which the artifact spec, rendering
+ * from `../dist`, would catch.
+ */
+export declare const MAILS_DIR: string;
+/**
+ * The renderer of the default e-mails, created on first use and shared by
+ * every `janusMail()` and `janusTemplates()` after it.
+ *
+ * Lazy, so importing the package reads nothing: an application that
+ * overrides every template never opens `mails/`. The first default template
+ * rendered reads the whole build once — a missing `mails/` throws there, with
+ * `createMailRenderer`'s own message.
+ */
+export declare function defaultRenderer(): MailRenderer<MailEmails>;
+//# sourceMappingURL=mails.d.ts.map

package/dist/mails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mails.d.ts","sourceRoot":"","sources":["../src/mails.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,QAAuD,CAAC;AAI9E;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAAC,UAAU,CAAC,CAG1D"}

package/dist/options.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `janusMail()`'s options, checked once when it is called. A mistake is a
+ * wiring mistake, so a bare `TypeError` naming the option — never its value —
+ * thrown before anything is sent.
+ */
+import type { Address, Mailer } from '@nxgt/mail';
+import type { JanusMailLinks, JanusMailTemplateName, JanusMailTemplates } from './types';
+/** The templates in the order the documentation lists them. */
+export declare const TEMPLATE_NAMES: readonly JanusMailTemplateName[];
+/** The options once checked, with `string` for the locales: the degenericised mirror. */
+export interface ResolvedOptions {
+    readonly mailer: Mailer;
+    readonly from: Address;
+    readonly replyTo: Address | undefined;
+    readonly brand: string;
+    readonly links: JanusMailLinks;
+    readonly locales: readonly string[];
+    readonly fallbackLocale: string;
+    readonly templates: JanusMailTemplates<string>;
+}
+/**
+ * Checks `janusMail()`'s options and answers them resolved, or throws a
+ * `TypeError`. What was checked is copied and frozen, so the guarantee made
+ * here holds at every send.
+ */
+export declare function resolveOptions(options: unknown): ResolvedOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,KAAK,EACX,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,eAAO,MAAM,cAAc,EAAE,SAAS,qBAAqB,EAM1D,CAAC;AAIF,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC;CAC/C;AAkJD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAmBhE"}

package/dist/templates.d.ts

@@ -0,0 +1,15 @@
+import type { JanusMailTemplates } from './types';
+/**
+ * The five default templates, in the locales they are built in. The
+ * renderer behind them is created on the first render, not here.
+ *
+ * ```ts
+ * const defaults = janusTemplates();
+ * const { subject } = await defaults.verifyEmail({ brand: 'Acme', name: 'Ada', link, locale: 'fr' });
+ * ```
+ *
+ * A URL that is not `http:`, `https:` or `mailto:` throws `MailRefused`; a
+ * missing `mails/` folder throws when the first one renders.
+ */
+export declare function janusTemplates(): JanusMailTemplates;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CA6BnD"}

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The public types of `@nxgt/janus-mail`, in their generic form. The
+ * implementation works on a degenericised mirror (`string` locales) and casts
+ * once, in `janusMail()`.
+ */
+import type { IssuedCode, IssuedToken } from '@nxgt/janus';
+import type { Address, Mailer, Rendered, SentMail, WantedLocales } from '@nxgt/mail';
+import type { JanusMailLocale } from './generated/locales';
+export type { JanusMailLocale } from './generated/locales';
+/**
+ * What each e-mail's template is given, by template name. Every value is
+ * text: `brand` is the name `janusMail({ brand })` was given, `name` the
+ * recipient's, `link` an absolute URL from `links`.
+ *
+ * Held equal to the build's variables by `test/types/variables.ts`: an e-mail
+ * of the build that gains or loses a variable fails the typecheck there.
+ */
+export interface JanusMailVariables {
+    readonly verifyEmail: {
+        readonly brand: string;
+        readonly name: string;
+        readonly link: string;
+    };
+    readonly resetPassword: {
+        readonly brand: string;
+        readonly name: string;
+        readonly link: string;
+    };
+    /** No `challenge`, ever: it is the visitor's secret, and never goes in an e-mail. */
+    readonly signInCode: {
+        readonly brand: string;
+        readonly code: string;
+    };
+    readonly passwordChanged: {
+        readonly brand: string;
+        readonly name: string;
+        readonly link: string;
+    };
+    readonly emailChanged: {
+        readonly brand: string;
+        readonly name: string;
+        readonly link: string;
+        readonly newEmail: string;
+    };
+}
+/** The name of one of the five templates: `verifyEmail`, `resetPassword`, … */
+export type JanusMailTemplateName = keyof JanusMailVariables;
+/**
+ * One e-mail: its variables and the locale picked for the recipient, in; its
+ * `subject`, `html` and `text`, out — escaping is then the function's job. A
+ * default, from the prebuilt e-mails, or yours: React Email, a string, or
+ * another Maizzle build.
+ */
+export type JanusMailTemplate<V, L extends string = JanusMailLocale> = (variables: V & {
+    readonly locale: L;
+}) => Rendered | PromiseLike<Rendered>;
+/** The five templates, each for the locales `L`. */
+export type JanusMailTemplates<L extends string = JanusMailLocale> = {
+    readonly [K in JanusMailTemplateName]: JanusMailTemplate<JanusMailVariables[K], L>;
+};
+/**
+ * Who an e-mail is for, besides the address: the name it greets, and the
+ * locales they want, most wanted first — their stored locale, then their
+ * `Accept-Language` when they are the visitor. Picked with `pickLocale`:
+ * `fr-CA` sends `fr`, and nothing matching sends the fallback locale.
+ */
+export interface Recipient {
+    readonly name: string;
+    readonly locale?: WantedLocales;
+}
+/**
+ * The links of the e-mails, each an absolute `http(s)` URL of your
+ * application. Each is called at send time and must answer a string
+ * synchronously: an `async` function or a `URL` object is a compile error,
+ * and from JavaScript, or through a cast, the send throws a `TypeError`
+ * naming the call. A
+ * `mailto:` URL is accepted too — `secureAccount: () => 'mailto:security@acme.example'`
+ * sends the user to your support desk; any other scheme is refused by the
+ * renderer with a `MailRefused`. The functions are copied when `janusMail()`
+ * is called: replacing one afterwards changes nothing.
+ */
+export interface JanusMailLinks {
+    /** The page that confirms an e-mail, given the one-time token: `(token) => \`https://app.example/verify?token=${token}\`` */
+    readonly verifyEmail: (token: string) => string;
+    /** The page that sets a new password, given the one-time token. */
+    readonly resetPassword: (token: string) => string;
+    /** Where a user who did not make a change secures their account — `passwordChanged` and `emailChanged` link to it. */
+    readonly secureAccount: () => string;
+}
+/** The options every locale set shares. */
+interface JanusMailBaseOptions<L extends string> {
+    /** The transport — `@nxgt/mail-smtp`, `@nxgt/mail-resend`, or `createMemoryMailer()` in tests. */
+    readonly mailer: Mailer;
+    /** The sender of every e-mail. */
+    readonly from: Address;
+    /** Where a reply goes, when not to `from`. */
+    readonly replyTo?: Address;
+    /** The name the e-mails show — in the header, the body and the footer. Text only. */
+    readonly brand: string;
+    readonly links: JanusMailLinks;
+    /** The locales to send in. Default the built ones, `['en', 'fr']`. */
+    readonly locales?: readonly L[];
+    /** The locale when the recipient wants none of `locales`. Default `en`, else the first of `locales`. */
+    readonly fallbackLocale?: NoInfer<L>;
+}
+/**
+ * `janusMail()`'s options. `templates` replaces any of the defaults — and
+ * **every** one once `locales` holds a locale the defaults are not built in:
+ * a default could not render it.
+ */
+export type JanusMailOptions<L extends string = JanusMailLocale> = JanusMailBaseOptions<L> & ([L] extends [JanusMailLocale] ? {
+    readonly templates?: Partial<JanusMailTemplates<L>>;
+} : {
+    readonly templates: JanusMailTemplates<L>;
+});
+/**
+ * The e-mails of Janus's flows, each sent to the address the flow answered.
+ * Each method resolves once the mailer took the e-mail, with its answer, and
+ * rejects with the mailer's `MailFailure` or `MailRefused`, untouched.
+ */
+export interface JanusMail<L extends string = JanusMailLocale> {
+    /** What `auth.verifyEmail.send(user)` answered, to `issued.email`. */
+    verifyEmail(issued: IssuedToken, to: Recipient): Promise<SentMail>;
+    /** What `auth.resetPassword.request(email)` answered, once checked for `null`, to `issued.email`. */
+    resetPassword(issued: IssuedToken, to: Recipient): Promise<SentMail>;
+    /**
+     * The code `auth.signInCode.request(email)` answered, to `issued.email`.
+     * Reads `code` and `email` only: the challenge never reaches the e-mail.
+     */
+    signInCode(issued: Pick<IssuedCode<unknown>, 'code' | 'email'>, to?: Pick<Recipient, 'locale'>): Promise<SentMail>;
+    /** Tells `to.email` their password was changed, with a link to secure the account. */
+    passwordChanged(to: Recipient & {
+        readonly email: string;
+    }): Promise<SentMail>;
+    /** Tells the **former** address that the e-mail changed to `newEmail`, with a link to secure the account. */
+    emailChanged(to: Recipient & {
+        readonly formerEmail: string;
+        readonly newEmail: string;
+    }): Promise<SentMail>;
+    /** The templates in use: the defaults, with `templates` over them. */
+    readonly templates: JanusMailTemplates<L>;
+    /** The locales sent in. */
+    readonly locales: readonly L[];
+}
+//# 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":"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"}

package/docs/README.md

@@ -0,0 +1,34 @@
+# @nxgt/janus-mail — documentation
+
+The [README](../README.md) shows each e-mail in one example; these pages give
+the detail.
+
+| Page | Read it when |
+| --- | --- |
+| [Sending](guide/sending.md) | You are wiring `janusMail()` into your routes: the options, each method, where each e-mail goes, what a failure looks like, and a test |
+| [Templates](guide/templates.md) | You want an e-mail of your own: what a template takes and answers, a partial override, `janusTemplates()`, and what the defaults say |
+| [Locales](guide/locales.md) | You send in more than one language: how the locale is picked, `fallbackLocale`, fewer locales, and adding one |
+| [Building](guide/building.md) | You work on this package: the Maizzle project in `mail/`, `mails/`, the generated files, and why none of it reaches a consumer's build |
+| [Troubleshooting](troubleshooting.md) | A `TypeError` at wiring or at a call, a `MailRefused`, a `MailFailure`, or a compile error |
+| [Roadmap](roadmap.md) | You want to know what is coming, and what is deliberately not planned |
+
+## Words
+
+The words **user**, **one-time token**, **one-time code**, **challenge** and
+**e-mail flow** are
+[`@nxgt/janus`'s vocabulary](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/vocabulary.md);
+**mailer**, **transport**, **rendered**, **placeholder** and **manifest** are
+[`@nxgt/mail`'s](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md).
+They mean the same here. These pages add:
+
+| Word | Means | Not |
+| --- | --- | --- |
+| **e-mail** | One of the five this package sends: `verify-email`, `reset-password`, `sign-in-code`, `password-changed`, `email-changed` — by the name of its built file | "mail", "message" — a *message* is what a mailer sends, addressed |
+| **template** | The function that renders one e-mail: `(variables & { locale }) => Rendered`. Named in camelCase, after the method that sends it: `verifyEmail`, `signInCode` | "renderer" — the renderer is `@nxgt/mail`'s, and reads the build |
+| **default template** | A template of `janusTemplates()`: the prebuilt e-mail, filled by the renderer | "preset" — a preset is `@nxgt/mail-presets`' source, which the build compiles |
+| **override** | A template of yours, passed in `templates`, used instead of the default | "custom template" |
+| **issued** | What a flow answered: an `IssuedToken` from `verifyEmail.send` or `resetPassword.request`, an `IssuedCode` from `signInCode.request` | "result", "payload" |
+| **recipient** | Who an e-mail is for besides the address: a `Recipient`, `{ name, locale? }` | "user" — a user is a record of `@nxgt/janus`; "to" is the address |
+| **notice** | An e-mail that tells, and asks for nothing: `passwordChanged`, `emailChanged`. It links to `links.secureAccount()` | "alert", "notification" |
+| **brand** | The name the e-mails show, `janusMail({ brand })`: text, filled at send time | "logo", "company" |
+| **the build** | The e-mails as `scripts/build-mail.ts` writes them to `mails/`: HTML and text per locale, and the manifest | "dist" — `mails/` is not `dist/` |

package/docs/guide/building.md

@@ -0,0 +1,130 @@
+# Building
+
+This page is for working on the package itself: how the default e-mails are
+built, what is committed and what is shipped, and why a consumer needs none
+of it. An application that uses `@nxgt/janus-mail` never runs this build.
+
+```sh
+cd packages/janus-mail
+bun run build        # build:mail, then the TypeScript build
+bun run build:mail   # the e-mails alone
+```
+
+## Maizzle runs at our build, never at the consumer's
+
+The e-mails are compiled once, when this package is built: Maizzle, Vue,
+Tailwind CSS and the `@nxgt/mail-*` build packages are **devDependencies**.
+The tarball carries their output — HTML and text per locale, and a manifest —
+and at send time `@nxgt/mail/renderer` fills its placeholders. A consumer
+installs `@nxgt/mail` and nothing that builds.
+
+```text
+packages/janus-mail/
+  mail/                    the Maizzle project — not shipped
+    maizzle.config.ts      presets({ only: the 5 }), ui(), i18n()
+    locales/en.json        {} — the presets' messages, unchanged
+    locales/fr.json
+  mails/                   what the build wrote — shipped, never committed
+    mail-manifest.json
+    en/verify-email.html   en/verify-email.txt   …
+    fr/verify-email.html   fr/verify-email.txt   …
+  scripts/build-mail.ts    runs maizzle build, checks the manifest, writes locales.ts
+  src/generated/           written by the build — committed
+    mail.ts                MailEmails: each e-mail and its variables
+    locales.ts             LOCALES and JanusMailLocale
+```
+
+## What `build:mail` does
+
+1. `maizzle build` in `mail/`, with `productionConfig`: minified HTML, a
+   text part for each e-mail, written to `../mails/`. Maizzle empties the
+   folder first, so an e-mail removed leaves no file behind.
+2. `@nxgt/mail-i18n` writes `mails/mail-manifest.json` and
+   `src/generated/mail.ts` (`rendererTypes`), from the build.
+3. `scripts/build-mail.ts` reads the manifest and **fails unless its
+   format is one every `@nxgt/mail` the peer admits reads** — see below —
+   and **unless exactly the five e-mails were built**: a sixth from a new
+   `@nxgt/mail-presets`, or one missing, stops the build.
+4. It writes `src/generated/locales.ts` from the manifest's locales, only
+   when its content changed.
+
+Then `../../build.ts` builds `dist/`, as for every package.
+
+## The manifest's format keeps the peer honest
+
+The package peers `@nxgt/mail` at `>=0.1.0 <1`, so the build it ships must
+be readable by `@nxgt/mail` 0.1.0. The manifest says which format it is in —
+`formatVersion`, its first key, `MANIFEST_FORMAT` of the `@nxgt/mail-i18n`
+that built it — and within 0.x a renderer reads every format up to its own.
+`@nxgt/mail` 0.1.0 through 0.5.0 read format 1, and a manifest without the
+field is format 1.
+
+`formatProblem` in `scripts/build-mail.ts` (spec'd beside it) fails the build
+when:
+
+| Message | Cause | Fix |
+| --- | --- | --- |
+| `build-mail: mails/mail-manifest.json is manifest format 2, where @nxgt/mail-i18n writes 1 — a mails/ left by another build; run the build again` | `mails/` is not what this `@nxgt/mail-i18n` wrote | Run `bun run build:mail` again |
+| `build-mail: mails/mail-manifest.json is manifest format 2, and @nxgt/mail 0.1.0, the peer's floor, reads up to 1 — raise the @nxgt/mail peer's floor to the first version that reads it` | A new `@nxgt/mail-i18n` writes a format the floor cannot read | Raise the peer's floor, then `PEER_FLOOR_READS` with it |
+
+`PEER_FLOOR_READS` is a constant, `1`, rather than `MANIFEST_FORMAT` from
+`@nxgt/mail/renderer`: the devDependency is newer than the floor, and
+`@nxgt/mail` 0.5.0 and earlier export no `MANIFEST_FORMAT`. The pattern is
+`@nxgt/mail-i18n`'s
+[Shipping a build in a package](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-i18n/docs/guide/manifest.md#shipping-a-build-in-a-package).
+
+## The brand is a placeholder
+
+`maizzle.config.ts` gives `ui()` the brand `{ name: '{{ brand }}' }`. Every
+place `@nxgt/mail-ui`'s layout and the presets write the brand's name — the
+header, the body, the footer — holds the placeholder `{{ brand }}`, so the
+manifest lists `brand` among each e-mail's variables, and the renderer
+requires it and escapes it like any other value. That is why the brand is
+text only: a URL or a logo must be absolute when `ui()` is called.
+
+The build's check is the renderer's own: a variable left out of `render`
+throws, so no e-mail can go out with `{{ brand }}` in it. The specs render
+each e-mail in both locales and search every part for `{{`.
+
+## The locales are the catalogues
+
+`locales` is read from `mail/locales/*.json`, `en` first — the fallback
+locale every other catalogue is checked against. The catalogues are `{}`:
+the presets' messages are used as they are. A new file adds a locale, and
+the build fails until it holds every message the presets use in `en` (see
+`@nxgt/mail-presets`'
+[Another locale](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-presets/docs/guide/presets.md#another-locale)).
+
+## Why `mails/` is not in `dist/`
+
+The root `build.ts` removes from `dist/` every file it did not write itself,
+so a module moved or deleted never ships. The built e-mails would be removed
+on every TypeScript build. They live beside it, in `mails/`, listed in
+`files`, and ignored by the package's `.gitignore`.
+
+`src/mails.ts` resolves the folder from its own URL,
+`new URL('../mails/', import.meta.url)`, which is right from `src/` in the
+specs and from `dist/index.js` in the tarball — because the module sits
+directly under `src/` and the package has one entry point. A second entry
+point would move it into `dist/chunks/`, one level deeper: the artifact spec
+renders from `../dist` and would fail.
+
+`scripts/verify-artifacts.ts` checks that every `files` entry is in the
+packed tarball, so a `mails/` that was not built, or that a packer left out,
+fails before a release.
+
+## What is committed
+
+| Path | Committed | Why |
+| --- | --- | --- |
+| `mail/` | yes | The source of the build |
+| `mails/` | no | Rebuilt by every build; shipped in the tarball |
+| `mail/.maizzle/` | no | Maizzle's own generated files |
+| `src/generated/` | yes | So the package type-checks without a Maizzle build. CI rebuilds it and runs `git diff --exit-code` on it: a stale copy fails. `generated/mail.ts`'s header says *never committed* — `@nxgt/mail-i18n`'s advice to an application; this package commits it on purpose |
+
+## See also
+
+- `@nxgt/mail-i18n`'s [manifest guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-i18n/docs/guide/manifest.md)
+  — the manifest and `generated/mail.ts`.
+- `@nxgt/mail-ui`'s [plugin guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-ui/docs/guide/plugin.md)
+  — `ui({ brand, theme })`.

package/docs/guide/locales.md

@@ -0,0 +1,113 @@
+# Locales
+
+This page is for sending in the recipient's language: how the locale of each
+e-mail is picked, what `locales` and `fallbackLocale` change, and how to add a
+language the defaults are not built in.
+
+```ts
+import { parseAcceptLanguage } from '@nxgt/mail';
+
+await mail.verifyEmail(issued, {
+	name: user.name,
+	locale: [user.locale, ...parseAcceptLanguage(request.headers.get('accept-language'))],
+});
+// user.locale 'fr-CA' → fr; null, with 'de,en;q=0.8' → en; nothing matching → the fallback
+```
+
+## How the locale is picked
+
+Each method passes `to.locale` to `@nxgt/mail`'s `pickLocale`, with
+`locales` and `fallbackLocale`:
+
+1. For each wanted locale, in order, an exact match wins (case, `_` and `-`
+   do not matter), then a match on the language: `fr-CA` sends `fr`.
+2. Nothing matching — or `null`, `undefined`, an empty list — sends
+   `fallbackLocale`.
+
+`to.locale` is a `WantedLocales`: a string, `null`, `undefined`, or a list of
+them, most wanted first. **The locale is the recipient's**, not the
+request's: an administrator who resets a user's password sends in the
+*user's* locale. Put their stored locale first, and the visitor's
+`Accept-Language` after it only when the recipient is the visitor.
+
+| `to.locale` | Sent in |
+| --- | --- |
+| `'fr'`, `'fr-CA'`, `'FR_be'` | `fr` |
+| `'en-GB'` | `en` |
+| `'de'` | the fallback, `en` |
+| `null`, `undefined`, `[]` | the fallback |
+| `[null, 'de-DE', 'fr']` | `fr` |
+
+The template is given the locale picked — `'fr'`, never `'fr-CA'` — so an
+override can branch on it.
+
+## `locales` and `fallbackLocale`
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `locales` | `['en', 'fr']`, the built ones | The locales an e-mail can be sent in. Its type is inferred as written: `['en']` makes `L` `'en'` |
+| `fallbackLocale` | `'en'` when in `locales`, else the first of them | Sent when the recipient wants none of `locales`. Must be one of them: another is a compile error, and a `TypeError` |
+
+**Fewer locales.** `locales: ['en']` sends English to everyone, a French
+speaker included; the defaults still fit, and `templates` stays partial.
+
+```ts
+const mail = janusMail({ mailer, from, brand: 'Acme', links, locales: ['en'] });
+mail.locales; // readonly 'en'[]
+```
+
+**Another fallback.** A service whose users are mostly French:
+
+```ts
+janusMail({ mailer, from, brand: 'Acme', links, fallbackLocale: 'fr' });
+```
+
+## Adding a locale
+
+The defaults are built in `en` and `fr` only. A locale beyond them needs
+**every template**: a default could not render it. `JanusMailOptions` makes
+`templates` required and whole once `locales` holds one:
+
+```ts
+import { janusMail, type JanusMailTemplates } from '@nxgt/janus-mail';
+
+type Locale = 'en' | 'fr' | 'de';
+
+const templates: JanusMailTemplates<Locale> = {
+	verifyEmail: ({ name, link, locale }) => render('verify-email', locale, { name, link }),
+	resetPassword: ({ name, link, locale }) => render('reset-password', locale, { name, link }),
+	signInCode: ({ code, locale }) => render('sign-in-code', locale, { code }),
+	passwordChanged: ({ name, link, locale }) => render('password-changed', locale, { name, link }),
+	emailChanged: ({ name, link, newEmail, locale }) => render('email-changed', locale, { name, link, newEmail }),
+};
+
+const mail = janusMail({ mailer, from, brand: 'Acme', links, locales: ['en', 'fr', 'de'], templates });
+mail.locales; // readonly ('en' | 'fr' | 'de')[]
+```
+
+`render` here is yours — a renderer over a Maizzle build of your own, with
+`@nxgt/mail-presets` and a `locales/de.json`, is the closest to the defaults.
+With only some templates, the call does not compile — the error lands on
+`templates`:
+
+```text
+TS2739: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': resetPassword, signInCode, passwordChanged, emailChanged
+```
+
+and in JavaScript it throws when `janusMail()` is called:
+
+```text
+TypeError: janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; resetPassword, signInCode, passwordChanged, emailChanged missing
+```
+
+A default template is typed for `'en' | 'fr'`, so reusing one in a wider set
+is refused too: `verifyEmail: janusTemplates().verifyEmail` in a
+`JanusMailTemplates<'en' | 'fr' | 'de'>` is a compile error.
+
+Built-in locales for more languages are on the [roadmap](../roadmap.md).
+
+## See also
+
+- `@nxgt/mail`'s [locales guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/locales.md)
+  — `pickLocale` and `parseAcceptLanguage` in full.
+- [Templates](templates.md) — writing the five for a new locale.