@nxgt/janus 0.8.6 → 0.8.7

package/docs/guide/email-flows.md

@@ -29,6 +29,43 @@ const verified = await auth.verifyEmail.confirm(sent.token);
 verified.emailVerified; // true
 ```
 
+## Ready-made e-mails — `@nxgt/janus-mail`
+
+`sendMail` above is yours to write, or
+[`@nxgt/janus-mail`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-mail/README.md)
+writes it: it takes what `send` and `request` answer, as they answer it, and
+sends the verification and reset e-mails — and the *password changed* and
+*e-mail changed* notices — in English and French, over any `@nxgt/mail`
+transport. In progress, and private until its first release.
+
+```ts
+import { janusMail } from '@nxgt/janus-mail';
+
+const mail = janusMail({
+	mailer, // an @nxgt/mail transport
+	from: 'noreply@app.example',
+	brand: 'App',
+	links: {
+		verifyEmail: (token) => `https://app.example/verify?token=${token}`,
+		resetPassword: (token) => `https://app.example/reset?token=${token}`,
+		secureAccount: () => 'https://app.example/account/security',
+	},
+});
+
+await mail.verifyEmail(await auth.verifyEmail.send(user), { name: user.name });
+
+const issued = await auth.resetPassword.request(email);
+if (issued !== null) await mail.resetPassword(issued, { name: issued.user.name });
+```
+
+Each e-mail goes to `issued.email`. A send that fails rejects with the
+mailer's `MailFailure` — never report it as sent — and one refused, a link
+that is not `http(s)` or `mailto:` or an address that is not one, with
+`MailRefused`. A `mailto:` link is accepted on purpose —
+`secureAccount: () => 'mailto:security@app.example'` points a user who made
+no change at your support desk. Each link must answer a string at once: an
+`async` function is a `TypeError` naming the call.
+
 ## Which types have these flows
 
 `verifyEmail` exists on a type with an e-mail field: the one `email` names, or

package/docs/guide/sign-in-code.md

@@ -160,6 +160,21 @@ sign-in completes in the browser that started it.
 Send it to `issued.email`, not to what the visitor typed: it is the address
 the user's field holds, as they registered it.
 
+[`@nxgt/janus-mail`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-mail/README.md)
+sends this e-mail ready-made, in English and French, over any `@nxgt/mail`
+transport — in progress, and private until its first release. It takes the
+whole `IssuedCode` and reads only `code` and `email`: the challenge never
+reaches the e-mail, nor a template of yours.
+
+```ts
+if (issued !== null) await mail.signInCode(issued, { locale: 'fr-CA' }); // the recipient's locale: sent in fr
+```
+
+Its send rejects with the mailer's `MailFailure` when the transport fails, so the `void sendMail(…)` above
+does not carry over: to send after the answer, hand `mail.signInCode` to a
+queue that awaits it and retries a `MailFailure` — a promise nobody awaits
+turns an outage into an unhandled rejection.
+
 ## Keeping the challenge with the visitor
 
 **The challenge is a secret.** The code alone signs nobody in: it is checked

package/docs/guide/vocabulary.md

@@ -56,6 +56,8 @@ either finds this row.
 | **seal**, **sealing key** | To seal is to encrypt a TOTP secret — AES-256-GCM, bound to the user's id — before a store sees it. A sealing key is one `{ id, key }` of `secondFactor.keys`: the first seals, every one opens | "encrypt", "encryption key", "master key", "pepper" |
 | **token** | Never alone in prose: a *session token* or a *one-time token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
 | **e-mail flow** | `verifyEmail` or `resetPassword`: send a one-time token, then confirm it. `signInCode` sends a one-time code instead | |
+| **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send` or `resetPassword.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is | "result", "payload" |
+| **notice** | An e-mail that tells a user of a change and asks for nothing: *password changed*, *e-mail changed* — the latter sent to the former address. `@nxgt/janus-mail` sends both | "alert", "notification" |
 | **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.deleted` — a `UserEvent`, naming the user by id alone, with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
 | **listener** | The one function `janus({ events })` hands every user event to, after the write and awaited | "handler", "hook", "subscriber" |
 
@@ -88,7 +90,7 @@ either finds this row.
 | **store** | Where a side keeps its data, behind a port. The **identity stores** are `users`, `sessions` and `tokens`; the **relation store** holds the tuples | "database", "repository" |
 | **port** | The interface a store implements: `JanusStores` for the identity stores — named after the package, not the side — and `RelationStore` | "driver" |
 | **adapter** | A package implementing the ports for one database: `@nxgt/janus-mongo`, `@nxgt/janus-drizzle`, `@nxgt/janus-redis`. What its `create…Adapter(db)` answers is its stores, keyed as `janus()` takes them — `{ store, relations }` | "plugin", "connector" |
-| **integration** | A package fitting Janus into one web framework or one observability library: `@nxgt/janus-hono`, `@nxgt/janus-telemetry`. It implements no port | "plugin", "adapter" |
+| **integration** | A package fitting Janus into one web framework, one observability library or one mail toolkit: `@nxgt/janus-hono`, `@nxgt/janus-telemetry`, `@nxgt/janus-mail`. It implements no port | "plugin", "adapter" |
 | **kit** | A package that opens the connections and wires adapters and integrations into one object for an application: `@nxgt/janus-kit`'s `connectKit` answers `{ auth, access, db, redis, ping, close }`. It implements no port, and `janus()` and `permissions()` are still written by the application | "framework", "starter" |
 
 ### Answers

package/docs/roadmap.md

@@ -5,7 +5,21 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing between releases.
+- **Sending the e-mails — in progress, private** — in a package of its own,
+  `@nxgt/janus-mail`, built on the `@nxgt/mail` toolkit shared with
+  applications that are not about sign-in: its `Mailer` port takes your
+  transport (SMTP, Resend…), and a transport that fails throws, like a store.
+  `janusMail({ mailer, from, brand, links })` takes what each flow answers —
+  `await mail.verifyEmail(await auth.verifyEmail.send(user), { name, locale })`
+  — and sends five e-mails, in English and French: e-mail verification,
+  password reset, sign-in code, and the notices *password changed* and
+  *e-mail changed*. They are built once, when the package is built, with
+  Maizzle and Tailwind CSS — CSS inlined for mail clients, the text in ICU
+  catalogues — and only filled at send time, every value escaped, your brand
+  included: no template engine in your server. Any one of them can be your
+  own function — React Email, a string — and a language beyond the two takes
+  all five. Built and tested in this repository, not yet published; see its
+  [README](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-mail/README.md).
 
 ## Next
 
@@ -19,23 +33,6 @@ Nothing between releases.
 - **Recovery codes** — single-use codes for the TOTP second factor, so a
   user who loses their authenticator app can still sign in, without an
   operator resetting the account.
-- **Sending the e-mails** — in a package of its own, `@nxgt/janus-mail`, built
-  on a general mail toolkit shared with applications that are not about
-  sign-in: a `Mailer` port you plug your transport into (SMTP, Resend, SES…) —
-  a transport that fails throws, like a store — and default templates for
-  verification, password reset and one-time codes, in English and French. One
-  template per e-mail, never one HTML file per language: the layout is built
-  once with Maizzle and Tailwind CSS 4 — CSS inlined for mail clients — and
-  its text lives in ICU message catalogues, one per language, plurals and
-  dates included. Both are compiled when the package is built into typed
-  functions: `templates.verifyEmail({ locale: 'fr', link })` answers
-  `{ subject, html, text }`, every value escaped, a missing variable or an
-  unknown locale a compile error, a message that fails to format a throw —
-  never an e-mail sent with `{link}` in it. No template engine at run time.
-  The defaults are a starting point, not a requirement: add a language with a
-  catalogue, or replace any one template with your own function of the same
-  shape — built with the same toolkit, React Email or a plain string — and
-  keep the defaults for the rest.
 
 ## Later
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.8.6",
+	"version": "0.8.7",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",