@nxgt/janus-mail 0.8.0 → 0.9.1

package/dist/link-types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The links of the e-mails, in their own file for its length. Re-exported
+ * by `./types`.
+ */
+/**
+ * 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 — their
+     * security settings. `passwordChanged`, `emailChanged`, `twoFactorEnabled`,
+     * `twoFactorDisabled` and `newSignIn` link to it, and so does `stepUp`, for
+     * a user who asked for no code.
+     */
+    readonly secureAccount: () => string;
+    /**
+     * Where a new user starts — your application's home, or its sign-in page
+     * for an account someone else created. `welcome` links to it, from its
+     * "Get started" button.
+     */
+    readonly getStarted: () => string;
+    /**
+     * Where a user regenerates their recovery codes — `recoveryCodeUsed`
+     * links to it, from its "Secure my account" button. **Optional**: without
+     * it, that e-mail links to `secureAccount`, the security settings where
+     * the codes usually are.
+     */
+    readonly recoveryCodes?: () => string;
+    /**
+     * The page a sign-in link opens, given its one-time token —
+     * `magicLink` links to it. **Optional**, for an application that sends no
+     * sign-in link; without it, `magicLink` throws a `TypeError` before
+     * anything is rendered. That page spends nothing: its button posts the
+     * token to the route that calls `auth.magicLink.confirm`, so a mail
+     * scanner that opens the link does not sign in for the user.
+     */
+    readonly magicLink?: (token: string) => string;
+}
+//# sourceMappingURL=link-types.d.ts.map

package/dist/link-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-types.d.ts","sourceRoot":"","sources":["../src/link-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC9B,6HAA6H;IAC7H,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAChD,mEAAmE;IACnE,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IACtC;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CAC/C"}

package/dist/new-sign-in-mail.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `newSignIn`: the notice of a sign-in from a device the user had not signed
+ * in from — which device, when, and where when the sender knows — linking to
+ * where the account is secured.
+ *
+ * Apart from the other notices because of its optional `location`: Janus
+ * sees no IP, so the sender may know none, and the e-mail then says so in
+ * the send's locale — "Location Unknown", "Lieu Inconnu" (`./no-location`).
+ */
+import type { ResolvedOptions } from './options';
+import type { JanusMail } from './types';
+/** The new sign-in notice, over the resolved options. */
+export declare function newSignInMail(options: ResolvedOptions): Pick<JanusMail<string>, 'newSignIn'>;
+//# sourceMappingURL=new-sign-in-mail.d.ts.map

package/dist/new-sign-in-mail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-sign-in-mail.d.ts","sourceRoot":"","sources":["../src/new-sign-in-mail.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAiBzC,yDAAyD;AACzD,wBAAgB,aAAa,CAC5B,OAAO,EAAE,eAAe,GACtB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAiBtC"}

package/dist/no-location.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What `newSignIn` shows where the sender knew no location — "Unknown",
+ * "Inconnu" — in the recipient's locale: the value after the row's label,
+ * so "Location Unknown", "Lieu Inconnu".
+ *
+ * A map written here, not a message in `mail/locales/*.json`: those
+ * catalogues are read by the Maizzle build alone, and hold only the
+ * presets' own keys, which the build checks against `@nxgt/mail-presets`'
+ * `en`. This string is a send's — whether a location was given is known
+ * only then — so it is chosen at send time, as the codes left are
+ * (`./codes-left`). Keyed by `JanusMailLocale`, so a locale added to the
+ * build without its text here is a compile error.
+ */
+import type { JanusMailLocale } from './generated/locales';
+/** The text of a missing location, by built locale. */
+export declare const NO_LOCATION: Readonly<Record<JanusMailLocale, string>>;
+/**
+ * The text of a missing location in `locale` — the one `localeFor` picked —
+ * else in its language (`fr` for `fr-CA`), else in `en`: a locale beyond
+ * the built ones is sent only through templates of the consumer's own.
+ */
+export declare function noLocationText(locale: string): string;
+//# sourceMappingURL=no-location.d.ts.map

package/dist/no-location.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-location.d.ts","sourceRoot":"","sources":["../src/no-location.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,uDAAuD;AACvD,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAI/D,CAAC;AAMJ;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrD"}

package/dist/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAKlD,OAAO,KAAK,EACX,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,eAAO,MAAM,cAAc,EAAE,SAAS,qBAAqB,EAY1D,CAAC;AAEF,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;IAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACtB;AAiJD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAoBhE"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAKlD,OAAO,KAAK,EACX,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,eAAO,MAAM,cAAc,EAAE,SAAS,qBAAqB,EAa1D,CAAC;AAEF,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;IAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACtB;AAiJD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAoBhE"}

package/dist/template-types.d.ts

@@ -84,6 +84,21 @@ export interface JanusMailVariables {
         readonly recoveryCodesLeft: string;
         readonly link: string;
     };
+    /**
+     * `device`, `time` and `location` are the sender's text, already in the
+     * recipient's locale. Without a `location` from the sender, it is
+     * "Unknown" in the send's locale — "Inconnu" in `fr` — the
+     * language's text for a regional `en` or `fr` tag, `en`'s for any other.
+     * `link` is where the account is secured.
+     */
+    readonly newSignIn: {
+        readonly brand: string;
+        readonly name: string;
+        readonly device: string;
+        readonly location: string;
+        readonly time: string;
+        readonly link: string;
+    };
     /** `name` is in the subject too: "Welcome, Ada". */
     readonly welcome: {
         readonly brand: string;
@@ -91,7 +106,7 @@ export interface JanusMailVariables {
         readonly link: string;
     };
 }
-/** The name of one of the eleven templates: `verifyEmail`, `resetPassword`, … */
+/** The name of one of the twelve templates: `verifyEmail`, `resetPassword`, … */
 export type JanusMailTemplateName = keyof JanusMailVariables;
 /**
  * One e-mail: its variables and the locale picked for the recipient, in; its
@@ -102,7 +117,7 @@ export type JanusMailTemplateName = keyof JanusMailVariables;
 export type JanusMailTemplate<V, L extends string = JanusMailLocale> = (variables: V & {
     readonly locale: L;
 }) => Rendered | PromiseLike<Rendered>;
-/** The eleven templates, each for the locales `L`. */
+/** The twelve templates, each for the locales `L`. */
 export type JanusMailTemplates<L extends string = JanusMailLocale> = {
     readonly [K in JanusMailTemplateName]: JanusMailTemplate<JanusMailVariables[K], L>;
 };

package/dist/template-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"template-types.d.ts","sourceRoot":"","sources":["../src/template-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"template-types.d.ts","sourceRoot":"","sources":["../src/template-types.ts"],"names":[],"mappings":"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"}

package/dist/templates.d.ts

@@ -1,6 +1,6 @@
 import type { JanusMailTemplates } from './types';
 /**
- * The eleven default templates, in the locales they are built in. The
+ * The twelve default templates, in the locales they are built in. The
  * renderer behind them is created on the first render, not here.
  *
  * ```ts

package/dist/templates.d.ts.map

@@ -1 +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,CAwEnD"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAgClD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI,kBAAkB,CA6DnD"}

package/dist/types.d.ts

@@ -6,8 +6,10 @@
 import type { Clock, IssuedCode, IssuedToken, StepUpByEmail } from '@nxgt/janus';
 import type { Address, Mailer, SentMail, WantedLocales } from '@nxgt/mail';
 import type { JanusMailLocale } from './generated/locales';
+import type { JanusMailLinks } from './link-types';
 import type { JanusMailTemplates } from './template-types';
 export type { JanusMailLocale } from './generated/locales';
+export type { JanusMailLinks } from './link-types';
 export type { JanusMailTemplate, JanusMailTemplateName, JanusMailTemplates, JanusMailVariables, } from './template-types';
 /**
  * Who an e-mail is for, besides the address: the name it greets, and the
@@ -19,52 +21,6 @@ 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 — their
-     * security settings. `passwordChanged`, `emailChanged`, `twoFactorEnabled`
-     * and `twoFactorDisabled` link to it, and so does `stepUp`, for a user who
-     * asked for no code.
-     */
-    readonly secureAccount: () => string;
-    /**
-     * Where a new user starts — your application's home, or its sign-in page
-     * for an account someone else created. `welcome` links to it, from its
-     * "Get started" button.
-     */
-    readonly getStarted: () => string;
-    /**
-     * Where a user regenerates their recovery codes — `recoveryCodeUsed`
-     * links to it, from its "Secure my account" button. **Optional**: without
-     * it, that e-mail links to `secureAccount`, the security settings where
-     * the codes usually are.
-     */
-    readonly recoveryCodes?: () => string;
-    /**
-     * The page a sign-in link opens, given its one-time token —
-     * `magicLink` links to it. **Optional**, for an application that sends no
-     * sign-in link; without it, `magicLink` throws a `TypeError` before
-     * anything is rendered. That page spends nothing: its button posts the
-     * token to the route that calls `auth.magicLink.confirm`, so a mail
-     * scanner that opens the link does not sign in for the user.
-     */
-    readonly magicLink?: (token: string) => string;
-}
 /** The options every locale set shares. */
 interface JanusMailBaseOptions<L extends string> {
     /** The transport — `@nxgt/mail-smtp`, `@nxgt/mail-resend`, or `createMemoryMailer()` in tests. */
@@ -200,6 +156,24 @@ export interface JanusMail<L extends string = JanusMailLocale> {
         readonly when: string;
         readonly recoveryCodesLeft: number | string;
     }): Promise<SentMail>;
+    /**
+     * Tells `to.email` their account was signed in from a device they had
+     * not signed in from, `time`, on `device` — and `location`, when you know
+     * it — with a link to secure the account: once a sign-in answered
+     * `newDevice: true`, or on the `user.newDeviceSignedIn` event.
+     *
+     * Every value is your text, in the recipient's locale: `device` described
+     * from the request (`'Firefox on macOS'`), `time` formatted in their time
+     * zone. **Janus sees no IP**: `location` is yours to work out, and an
+     * e-mail without one says "Unknown" in its place — "Inconnu" in French.
+     */
+    newSignIn(to: Recipient & {
+        readonly email: string;
+    }, signIn: {
+        readonly device: string;
+        readonly time: string;
+        readonly location?: string;
+    }): Promise<SentMail>;
     /** The templates in use: the defaults, with `templates` over them. */
     readonly templates: JanusMailTemplates<L>;
     /** The locales sent in. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -5,7 +5,7 @@ the detail.
 
 | Page | Read it when |
 | --- | --- |
-| [Sending](guide/sending.md) | You are wiring `janusMail()` into your routes: the options, `clock` among them; each method, the step-up's code, the welcome on `user.created`, the recovery code notice on `user.recoveryCodeUsed` and the change notices on `user.passwordChanged` and `user.emailChanged` among them; the expiry an e-mail states and how to set it, where each e-mail goes, what a failure looks like, retrying and tracing the mailer, and a test |
+| [Sending](guide/sending.md) | You are wiring `janusMail()` into your routes: the options, `clock` among them; each method, the step-up's code, the welcome on `user.created`, the recovery code notice on `user.recoveryCodeUsed`, the change notices on `user.passwordChanged` and `user.emailChanged` and the new sign-in notice among them; the expiry an e-mail states and how to set it, where each e-mail goes, what a failure looks like, retrying and tracing the mailer, 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 |
@@ -23,13 +23,13 @@ They mean the same here. These pages add:
 
 | Word | Means | Not |
 | --- | --- | --- |
-| **e-mail** | One of the eleven this package sends: `verify-email`, `reset-password`, `sign-in-code`, `magic-link`, `confirm-action`, `password-changed`, `email-changed`, `two-factor-enabled`, `two-factor-disabled`, `recovery-code-used`, `welcome` — by the name of its built file | "mail", "message" — a *message* is what a mailer sends, addressed |
+| **e-mail** | One of the twelve this package sends: `verify-email`, `reset-password`, `sign-in-code`, `magic-link`, `confirm-action`, `password-changed`, `email-changed`, `two-factor-enabled`, `two-factor-disabled`, `recovery-code-used`, `new-sign-in`, `welcome` — 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`, `resetPassword.request` or `magicLink.request`, an `IssuedCode` from `signInCode.request`, a `StepUpByEmail` from `stepUp.request` once narrowed to `via: 'email'` | "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`, `twoFactorEnabled`, `twoFactorDisabled`, `recoveryCodeUsed`. It links to `links.secureAccount()` — `recoveryCodeUsed` to `links.recoveryCodes()` when given | "alert", "notification" |
+| **notice** | An e-mail that tells, and asks for nothing: `passwordChanged`, `emailChanged`, `twoFactorEnabled`, `twoFactorDisabled`, `recoveryCodeUsed`, `newSignIn`. It links to `links.secureAccount()` — `recoveryCodeUsed` to `links.recoveryCodes()` when given | "alert", "notification" |
 | **welcome** | The e-mail sent once a user was created, on `@nxgt/janus`'s `user.created`: `welcome`. It links to `links.getStarted()` — not a notice, since it warns of nothing | "onboarding", "greeting" |
 | **codes left** | How many recovery codes the user still holds, as the recovery code notice says it: `recoveryCodesLeft`, a sentence written from the count with the preset's plural in the recipient's locale — "You have 1 recovery code left." — or passed as text | "remaining codes" — the count itself is `@nxgt/janus`'s `recoveryCodesLeft` |
 | **expiry** | How long a link or a code lasts, as the e-mail says it: `expiresIn`, derived from the flow's `expiresAt` in the recipient's locale — "1 hour", "1 heure" — or passed per send | "TTL", "lifetime" — the `tokens` TTL is `@nxgt/janus`'s setting, which sets `expiresAt` |

package/docs/guide/building.md

@@ -55,7 +55,7 @@ packages/janus-mail/
    `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 eleven e-mails were built**: a twelfth from a new
+   and **unless exactly the twelve e-mails were built**: a thirteenth from a new
    `@nxgt/mail-presets`, or one missing, stops the build.
 4. It writes `src/generated/locales.ts` from the manifest's locales, and
    `src/generated/codes-left.ts` — below — each only when its content

package/docs/guide/locales.md

@@ -89,6 +89,8 @@ const templates: JanusMailTemplates<Locale> = {
 	twoFactorDisabled: ({ name, link, locale }) => render('two-factor-disabled', locale, { name, link }),
 	recoveryCodeUsed: ({ name, when, recoveryCodesLeft, link, locale }) =>
 		render('recovery-code-used', locale, { name, when, recoveryCodesLeft, link }),
+	newSignIn: ({ name, device, location, time, link, locale }) =>
+		render('new-sign-in', locale, { name, device, location, time, link }),
 	welcome: ({ name, link, locale }) => render('welcome', locale, { name, link }),
 };
 
@@ -102,8 +104,13 @@ mail.locales; // readonly ('en' | 'fr' | 'de')[]
 plural of the codes left in `en` and `fr` only, so a German recipient's
 `mail.recoveryCodeUsed` takes the sentence as text — "Sie haben noch 3
 Wiederherstellungscodes." — and a count is a `TypeError` there.
+`location`, left out of a `newSignIn`, is "Unknown" for `de`:
+the text of a missing location is held in `en` and `fr` only, so pass
+`location` yourself — "Unbekannt", so the row reads `Ort Unbekannt` —
+where it matters.
 `recoveryCodeUsed` is the ninth template, since 0.5.0, `magicLink` the
-tenth, since 0.7.0, and `stepUp` the eleventh, since 0.8.0: a `templates`
+tenth, since 0.7.0, `stepUp` the eleventh, since 0.8.0, and `newSignIn` the
+twelfth, since 0.9.0: a `templates`
 written for an earlier version no longer
 compiles with a locale beyond `en` and `fr` — add the one it lacks. A
 renderer over a Maizzle build of your own, with
@@ -112,13 +119,13 @@ With only some templates, the call does not compile — the error lands on
 `templates`:
 
 ```text
-TS2740: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': welcome, resetPassword, signInCode, magicLink, and 6 more.
+TS2740: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': welcome, resetPassword, signInCode, magicLink, and 7 more.
 ```
 
 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, magicLink, stepUp, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, welcome missing
+TypeError: janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; resetPassword, signInCode, magicLink, stepUp, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, newSignIn, welcome missing
 ```
 
 A default template is typed for `'en' | 'fr'`, so reusing one in a wider set
@@ -131,4 +138,4 @@ Built-in locales for more languages are on the [roadmap](../roadmap.md).
 
 - `@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 eleven for a new locale.
+- [Templates](templates.md) — writing the twelve for a new locale.

package/docs/guide/sending.md

@@ -46,7 +46,7 @@ time one is sent, and kept.
 | `brand` | `string` | required | The name the e-mails show, in the header, the body and the footer. Text: escaped in the HTML |
 | `links.verifyEmail` | `(token) => string` | required | The page that confirms an address, given the one-time token |
 | `links.resetPassword` | `(token) => string` | required | The page that sets a new password, given the one-time token |
-| `links.secureAccount` | `() => string` | required | Where a user who made no change secures their account: the notices link to it, and so does the step-up's code, for a user who asked for none |
+| `links.secureAccount` | `() => string` | required | Where a user who made no change secures their account: the notices link to it — the new sign-in's included — and so does the step-up's code, for a user who asked for none |
 | `links.getStarted` | `() => string` | required | Where a new user starts — your home page, or your sign-in page for an account someone else created: the welcome's **Get started** button links to it |
 | `links.magicLink` | `(token) => string` | none: `magicLink` is a `TypeError` without it | The page a sign-in link opens, given the one-time token. That page spends nothing: its button posts the token to the route that calls `auth.magicLink.confirm` |
 | `links.recoveryCodes` | `() => string` | `links.secureAccount` | Where a user regenerates their recovery codes: the recovery code notice links to it, from its **Secure my account** button |
@@ -349,6 +349,56 @@ when opening the session then fails.
   codes; without it, `links.secureAccount()`. `recoveryCodes` is optional,
   so a `links` written for 0.4 still compiles.
 
+### `newSignIn(to, { device, time, location? })`
+
+```ts
+// From the sign-in's answer, with @nxgt/janus given devices: { keys } and the device cookie:
+const signedIn = await auth.signIn({ email, password }, { device: cookie ?? null });
+if (signedIn.newDevice) {
+	const { name, email, locale } = signedIn.user;
+	await mail.newSignIn(
+		{ name, email, locale },
+		{
+			device: describeDevice(request.headers.get('user-agent')), // yours: 'Firefox on macOS'
+			time: new Intl.DateTimeFormat(locale ?? 'en', {
+				dateStyle: 'long',
+				timeStyle: 'short',
+				timeZone: 'Europe/Paris', // the user's, when you keep it
+			}).format(signedIn.session.createdAt),
+			location: 'Lyon, France', // optional: from a geo-IP of yours
+		},
+	);
+}
+```
+
+A notice for the account at `to.email`: it was signed in from a device the
+user had not signed in from — which device, where and when — with a
+**Secure my account** button to `links.secureAccount()`. Send it when a
+`@nxgt/janus` 0.17 sign-in answers `newDevice: true`, or on the
+`user.newDeviceSignedIn` event it sends then — the event names the user by
+id alone, so read the name, the locale and the address from the user, and
+it carries no request to describe the device from.
+
+- **Every value is your text**, already in the recipient's locale: `device`
+  as you describe the request — "Firefox on macOS", "Firefox sur macOS" —
+  and `time` formatted in their time zone: "29 septembre 2026 à 09:12".
+  The session's `createdAt`, or the event's `occurredAt`, is when it
+  happened.
+- **`location` is optional, and yours.** `@nxgt/janus` sees no IP: a
+  location comes from a geo-IP of your own, if you have one. Left out, the
+  e-mail says so in the locale it is sent in — `Location Unknown`, `Lieu
+  Inconnu` — since every line of the summary is always there. A locale
+  beyond `en` and `fr`, sent through templates of your own, gets its
+  language's text when it is `en` or `fr` (`fr-CA` gets "Inconnu"),
+  and "Unknown" otherwise: pass `location` yourself there. `null` is a
+  compile error, and in JavaScript `janusMail.newSignIn: location must be a
+  string`: spread it in only when you have one,
+  `...(city === null ? {} : { location: city })`.
+- **The text part** gives each line of the summary on one line, its label
+  then its value — `Device Firefox on macOS`, `Location Unknown`,
+  `Time September 29, 2026 at 9:12 AM` — one row per line, with no blank line
+  between rows.
+
 ## The expiry
 
 `verifyEmail`, `resetPassword`, `signInCode`, `magicLink` and `stepUp` say
@@ -406,6 +456,7 @@ a `TypeError`, and nothing reaches the mailer: revive the date with
 | `emailChanged` | `to.formerEmail` | `to.newEmail` |
 | `twoFactorEnabled`, `twoFactorDisabled` | `to.email` | — |
 | `recoveryCodeUsed` | `to.email` | — |
+| `newSignIn` | `to.email` | — |
 | `welcome` | `to.email` | — |
 
 `issued.email` is the address the user's record holds, as they registered

package/docs/guide/templates.md

@@ -1,7 +1,7 @@
 # Templates
 
 This page is for changing what an e-mail says or looks like: what a template
-is given and answers, replacing some of the eleven, using the defaults on their
+is given and answers, replacing some of the twelve, using the defaults on their
 own, and what the defaults say.
 
 ```ts
@@ -22,7 +22,7 @@ const mail = janusMail({
 });
 ```
 
-The sign-in code e-mail is now yours; the ten others stay the defaults.
+The sign-in code e-mail is now yours; the eleven others stay the defaults.
 
 ## What a template is
 
@@ -69,14 +69,18 @@ e-mail.
 | `twoFactorEnabled` | `brand`, `name`, `link` | `mail.twoFactorEnabled(to)` |
 | `twoFactorDisabled` | `brand`, `name`, `link` | `mail.twoFactorDisabled(to)` |
 | `recoveryCodeUsed` | `brand`, `name`, `when`, `recoveryCodesLeft`, `link` | `mail.recoveryCodeUsed(to, { when, recoveryCodesLeft })` |
+| `newSignIn` | `brand`, `name`, `device`, `location`, `time`, `link` | `mail.newSignIn(to, { device, time, location? })` |
 | `welcome` | `brand`, `name`, `link` | `mail.welcome(to)` |
 
 Every one also gets `locale`, one of `locales`. Every value is a string:
 `brand` from the options, `name` from the recipient, `link` from `links` —
-`links.secureAccount()` for the four notices and `stepUp`, `links.recoveryCodes()` (else
+`links.secureAccount()` for the notices other than `recoveryCodeUsed` and
+for `stepUp`, `links.recoveryCodes()` (else
 `links.secureAccount()`) for `recoveryCodeUsed`, `links.getStarted()` for
-`welcome` — `code`, `newEmail` and `when` from the
-call, and `expiresIn` derived from the flow's `expiresAt` in the locale, or
+`welcome` — `code`, `newEmail`, `when`, `device` and `time` from the
+call, `location` from the call or, without one, "Unknown" in the
+send's locale — "Inconnu" in `fr`; for another locale, its
+language's text when it is `en` or `fr` (`fr-CA`), else `en`'s — and `expiresIn` derived from the flow's `expiresAt` in the locale, or
 the send's own `expiresIn` ([Sending](sending.md#the-expiry)).
 
 `recoveryCodesLeft` is a **sentence**, not the count: "You have 9 recovery
@@ -126,11 +130,12 @@ methods live on its prototype and are refused — see
 [troubleshooting](../troubleshooting.md#janusmail-templatesname-is-not-an-own-enumerable-property--pass-a-plain-object-as--name-variables--rendered-).
 
 `templates` is `Partial` while `locales` stays within `en` and `fr`: give
-any of the eleven, and the defaults render the rest. Once `locales` holds
-another locale, it takes **all eleven** — `stepUp` included, since 0.8 — see
+any of the twelve, and the defaults render the rest. Once `locales` holds
+another locale, it takes **all twelve** — `stepUp` included, since 0.8, and
+`newSignIn`, since 0.9 — see
 [Adding a locale](locales.md#adding-a-locale).
 
-`mail.templates` answers the eleven in use — yours, and the defaults for the
+`mail.templates` answers the twelve in use — yours, and the defaults for the
 rest — frozen:
 
 ```ts
@@ -152,7 +157,7 @@ const { subject, html, text } = await defaults.resetPassword({
 });
 ```
 
-It answers the eleven defaults, typed for `'en' | 'fr'`, without a mailer:
+It answers the twelve defaults, typed for `'en' | 'fr'`, without a mailer:
 to preview an e-mail, to wrap one — add a line to the default text, say — or
 to send one through something other than `janusMail()`. A default reused for
 a wider set of locales is a compile error: it could not render the one it
@@ -178,7 +183,7 @@ them renders: that is when the package's `mails/` folder is read, once.
 ## What the defaults say
 
 The defaults are [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail-presets)
-1.1.0, built with a neutral grey theme and no logo:
+1.1.1, built with a neutral grey theme and no logo:
 
 | Template | Built from | Subject (`en`) | Subject (`fr`) |
 | --- | --- | --- | --- |
@@ -192,18 +197,25 @@ The defaults are [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail
 | `twoFactorEnabled` | `two-factor-enabled` | Two-factor authentication was turned on | L'authentification à deux facteurs a été activée |
 | `twoFactorDisabled` | `two-factor-disabled` | Two-factor authentication was turned off | L'authentification à deux facteurs a été désactivée |
 | `recoveryCodeUsed` | `recovery-code-used` | A recovery code was used on your account | Un code de récupération a été utilisé sur votre compte |
+| `newSignIn` | `new-sign-in` | New sign-in to your account | Nouvelle connexion à votre compte |
 | `welcome` | `welcome` | Welcome, `Ada` | Bienvenue, `Ada` |
 
 Each has a header and a footer with the brand, a heading, a greeting by name
 (but `signInCode` and `magicLink`), a button with its link and the link again in text for a
-client that shows no button, and a text part. The four notices but `recoveryCodeUsed` add a warning:
+client that shows no button, and a text part. The notices other than `recoveryCodeUsed` add a warning:
 *if this was not you, secure your account now*. `stepUp` shows its code as
 the sign-in code does, names no action — *someone, we hope you, asked to do
 something sensitive on your account* — and warns not to share the code if
 it was not the user, its button saying **Secure my account**. `recoveryCodeUsed` says it
 too, after a warning banner — *a recovery code was used on your account at
 `when`* — the codes left, and a line on generating new ones; its button says
-**Secure my account**. `welcome` has the brand in
+**Secure my account**. `newSignIn` says the account *was signed in from a
+device we had not seen*, then a summary of three lines — **Device**,
+**Location** and **Time**, *Appareil*, *Lieu* and *Heure* in French — then
+*if this was you, there is nothing to do; if this was not you, secure your
+account now*, its button saying **Secure my account**; in the text part each
+line of the summary is one line, its label then its value — `Device Firefox
+on macOS` — with no blank line between rows. `welcome` has the brand in
 its heading — "Welcome to Acme" — and the recipient's name in its subject,
 filled at send time like the body; its button says **Get started**.
 

package/docs/roadmap.md

@@ -9,9 +9,8 @@ Nothing between releases.
 
 ## Next
 
-- **The other presets** — `new-sign-in` and `invitation` from
-  `@nxgt/mail-presets`, each once `@nxgt/janus` has a flow that sends it: a
-  sign-in from a new device, an invitation to a user type.
+- **The invitation** — `invitation` from `@nxgt/mail-presets`, once
+  `@nxgt/janus` has a flow that sends it: an invitation to a user type.
 - **The other presets of `@nxgt/mail-presets` 0.4.0** — `account-deleted`,
   after a user is deleted, once `@nxgt/janus` has a deletion a link can
   undo; and `invitation-accepted`, once it has invitations.
@@ -47,6 +46,24 @@ Nothing between releases.
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **A readable summary and a location in words, v0.9.1.** Built with
+  `@nxgt/mail-config` 1.0.2 and `@nxgt/mail-presets` 1.1.1, the text part of
+  `newSignIn` gives each row of its summary on one line — `Device Firefox on
+  macOS` — with no blank line between rows, where it split each into a label
+  line and a value line. A new sign-in sent without `location` says
+  "Unknown" — `Location Unknown`, `Lieu Inconnu` in French — in the
+  recipient's locale, where it showed `—`.
+
+- **The new sign-in notice, v0.9.0.** `newSignIn(to, { device, time,
+  location? })`, built from `@nxgt/mail-presets` 1.1.0's `new-sign-in` in
+  English and French — "New sign-in to your account", which device, where
+  and when, and a **Secure my account** button to `links.secureAccount()`:
+  send it when an `@nxgt/janus` 0.17 sign-in answers `newDevice: true`, or
+  on `user.newDeviceSignedIn`. Every value is your text in the recipient's
+  locale; `@nxgt/janus` sees no IP, so `location` is yours, and `—` without
+  one. Twelve e-mails now, and twelve templates to pass for a locale beyond
+  `en` and `fr`.
+
 - **The step-up's code, v0.8.0.** `stepUp(issued, to, options?)`, built
   from `@nxgt/mail-presets` 1.1.0's `confirm-action` in English and French:
   send what `@nxgt/janus`'s `auth.stepUp.request(user)` answered, once
@@ -121,23 +138,3 @@ Newest first; from the first release on, the package's CHANGELOG holds every one
   linking to `links.secureAccount()`: send them on `@nxgt/janus` 0.9's
   `user.secondFactorEnabled` and `user.secondFactorDisabled` events. Seven
   e-mails now, and seven templates to pass for a locale beyond `en` and `fr`.
-- **Dark mode, v0.3.0.** The e-mails follow the reader's dark mode in
-  every client that supports it, Gmail excepted: a dark page, a dark card and
-  light text. Built from `@nxgt/mail-ui` 0.4.0, `@nxgt/mail-presets` 0.4.0
-  and `@nxgt/mail-i18n` 0.5.0; the text parts, subjects and variables are
-  unchanged, the manifest is still format 1, and the `@nxgt/mail` peer stays
-  `>=0.1.0 <1`.
-
-- **The expiry in the e-mail, v0.2.0.** The verification, reset and sign-in
-  code e-mails say how long the link or code lasts — "1 hour", "1 heure" —
-  derived from the flow's `expiresAt` in the recipient's locale, measured
-  against `janusMail({ clock })` (the clock given to `janus()`), or given per
-  send as `{ expiresIn }`. Two breaks: a template called directly takes
-  `expiresIn`, and `signInCode` reads `issued.expiresAt`. Built from
-  `@nxgt/mail-presets` 0.2.0, whose text parts keep each paragraph on one
-  line.
-
-- **The first release, v0.1.0.** The five e-mails of `@nxgt/janus`'s flows,
-  in English and French, over any `@nxgt/mail` transport: `janusMail()` and
-  `janusTemplates()`. Built with Maizzle when the package is built, shipped
-  in `mails/`, and only filled in at send time, every value escaped.