@reuters-graphics/gfx-better-auth 0.1.0

package/dist/emails/_components/index.js

@@ -0,0 +1,14 @@
+/**
+ * Brand components for the sign-in email, ported from
+ * `rngs.io/src/lib/emails/_components/`.
+ *
+ * Not in the package's `exports` map, so not public API — a consumer cannot
+ * import these, and they can change without a major.
+ */
+export { Brand } from './Brand.js';
+export { CentreCard } from './CentreCard.js';
+export { CentreWell } from './CentreWell.js';
+export { Footer } from './Footer.js';
+export { Head } from './Head.js';
+export { OpenButton } from './OpenButton.js';
+export { colors, fontFamily, supportEmail } from './tokens.js';

package/dist/emails/_components/tokens.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The design tokens behind the sign-in email, ported from
+ * `rngs.io/src/lib/emails/_components/`.
+ *
+ * Kept in one place because email clients require inline styles — there is no
+ * stylesheet to hold them, so every component reaches for these directly.
+ */
+/** Inter Tight, with a full fallback stack for clients that ignore webfonts. */
+export declare const fontFamily = "\"Inter Tight\",-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell,\"Helvetica Neue\",sans-serif";
+export declare const colors: {
+    /** The dark card `rngs.io` uses, and the page behind it. */
+    readonly card: "#323944";
+    readonly page: "#282e37";
+    readonly text: "#ffffff";
+    /** Footnotes and the eyebrow above the app name. */
+    readonly muted: "rgba(255,255,255,0.72)";
+    readonly buttonBg: "#4f5b6d";
+    readonly buttonBorder: "#64748b";
+    readonly rule: "rgba(255,255,255,0.18)";
+    /**
+     * Reuters orange. It stands in for the wordmark `rngs.io` loads as a PNG:
+     * this package ships no image assets, so the brand is carried by a rule and
+     * type rather than by a file we would have to host.
+     */
+    readonly reuters: "#ff8000";
+};
+/** The support address `rngs.io` points people at. */
+export declare const supportEmail = "all.graphics@thomsonreuters.com";

package/dist/emails/_components/tokens.js

@@ -0,0 +1,28 @@
+/**
+ * The design tokens behind the sign-in email, ported from
+ * `rngs.io/src/lib/emails/_components/`.
+ *
+ * Kept in one place because email clients require inline styles — there is no
+ * stylesheet to hold them, so every component reaches for these directly.
+ */
+/** Inter Tight, with a full fallback stack for clients that ignore webfonts. */
+export const fontFamily = '"Inter Tight",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Oxygen-Sans,Ubuntu,Cantarell,"Helvetica Neue",sans-serif';
+export const colors = {
+    /** The dark card `rngs.io` uses, and the page behind it. */
+    card: '#323944',
+    page: '#282e37',
+    text: '#ffffff',
+    /** Footnotes and the eyebrow above the app name. */
+    muted: 'rgba(255,255,255,0.72)',
+    buttonBg: '#4f5b6d',
+    buttonBorder: '#64748b',
+    rule: 'rgba(255,255,255,0.18)',
+    /**
+     * Reuters orange. It stands in for the wordmark `rngs.io` loads as a PNG:
+     * this package ships no image assets, so the brand is carried by a rule and
+     * type rather than by a file we would have to host.
+     */
+    reuters: '#ff8000',
+};
+/** The support address `rngs.io` points people at. */
+export const supportEmail = 'all.graphics@thomsonreuters.com';

package/dist/emails/index.d.ts

@@ -0,0 +1,96 @@
+import type { SignInEmailContext } from './Template.js';
+export type { SignInEmailContext };
+/**
+ * The Postmark block of the validated config. Restated structurally rather
+ * than imported, so `src/emails/` does not depend on `src/server/`.
+ */
+export interface SignInEmailPostmarkConfig {
+    /**
+     * Postmark server token. Optional, because the dev flow skips the inbox
+     * (ADR-0003, ADR-0007). Sending without one throws.
+     */
+    token?: string | undefined;
+    /** The `From` address. Must be a verified Postmark sender signature. */
+    from: string;
+    /** Postmark message stream, e.g. `"login-requests"`. */
+    messageStream: string;
+}
+/**
+ * Everything one sign-in email needs. Structurally `SignInEmail` from
+ * `src/server/config.ts`.
+ */
+export interface SignInEmailMessage extends SignInEmailContext {
+    to: string;
+    postmark: SignInEmailPostmarkConfig;
+}
+/**
+ * The one method of Postmark's `ServerClient` this package uses.
+ *
+ * Declared structurally so a fake can be injected without importing
+ * `postmark` — which is how tests and the fixture app stay off the wire
+ * (conventions § Testing: *no test may send real email*).
+ */
+export interface PostmarkLike {
+    sendEmail(message: {
+        From: string;
+        To: string;
+        Subject: string;
+        HtmlBody: string;
+        TextBody: string;
+        MessageStream: string;
+    }): Promise<unknown>;
+}
+/**
+ * The address hard-bounced and Postmark has **deactivated** it.
+ *
+ * This is the signal a consumer can use to set `user.disabledAt` — see
+ * `USAGE.md`. It is thrown,
+ * never swallowed: a caller that ignores it silently tells someone a link is
+ * on its way when it is not.
+ *
+ * Distinguishable without importing `postmark` — check
+ * `error instanceof InactiveRecipientError`, or
+ * `error.name === 'InactiveRecipientError'`, which is assigned from a string
+ * literal rather than `constructor.name` so it survives minification.
+ */
+export declare class InactiveRecipientError extends Error {
+    /** The address we tried to send to. */
+    readonly email: string;
+    /** Addresses Postmark named in the message; usually just {@link email}. */
+    readonly recipients: string[];
+    constructor(email: string, options?: {
+        recipients?: string[] | undefined;
+        cause?: unknown;
+    });
+}
+/** The rendered email, before it is handed to a transport. */
+export interface RenderedSignInEmail {
+    subject: string;
+    html: string;
+    text: string;
+}
+/**
+ * Render the sign-in email without sending it. Useful for a snapshot, and for
+ * a consumer wiring its own transport.
+ *
+ * ⚠️ **`render()` is async here.** react-email 6 / React 19 returns a
+ * `Promise<string>`; the 2.x examples all over the web are synchronous, and
+ * forgetting the `await` puts `[object Promise]` in the body of an email.
+ */
+export declare const renderSignInEmail: (context: SignInEmailContext) => Promise<RenderedSignInEmail>;
+/**
+ * Render the sign-in email and post it to Postmark.
+ *
+ * @param message The address, the **confirm** URL, the app name, the link
+ * lifetime, and the Postmark config to send with.
+ * @param options.client A stand-in for Postmark's `ServerClient`. Supply it
+ * from a test or the fixture app; leave it out and a real client is built
+ * from `message.postmark.token` on first use and cached.
+ *
+ * @throws {InactiveRecipientError} when Postmark has deactivated the address —
+ * the `disabledAt` signal (ADR-0004). Deliberately not swallowed.
+ * @throws {Error} when no `token` is configured and no `client` was supplied.
+ */
+export declare const sendSignInEmail: (message: SignInEmailMessage, options?: {
+    client?: PostmarkLike;
+}) => Promise<void>;

package/dist/emails/index.js

@@ -0,0 +1,160 @@
+/**
+ * Sign-in email: a Reuters-branded React template rendered with `react-email`
+ * and sent via Postmark.
+ *
+ * 🚨 **Server-only.** It reaches for the Postmark token. Nothing under
+ * `src/client/` or the root entry may import it.
+ *
+ * React is a dependency rather than a peer on purpose: it is an
+ * implementation detail of rendering email, and no consumer should install it
+ * to use this package. The React email ecosystem is simply better than
+ * anything in Svelte, which is the only reason it is here.
+ *
+ * ## The shape, and why
+ *
+ * {@link sendSignInEmail} takes **one message object carrying its own
+ * Postmark config** — `{ to, url, appName, expiresIn, postmark }` — rather
+ * than a config-bound factory or a `(to, context)` pair. That is deliberate:
+ * it is structurally the `SignInEmail` interface in `src/server/config.ts`,
+ * which is also the `sendEmail` seam a consumer can override. One shape means
+ * `createGfxAuth` passes the message straight through, and a consumer's own
+ * transport is a drop-in for ours:
+ *
+ * ```ts
+ * sendEmail?: (message: SignInEmail) => Promise<void>;
+ * ```
+ *
+ * Because the config travels with the message, there is nothing to construct
+ * at boot and nothing to blow up in the dev flow, where there is no token at
+ * all (ADR-0003, ADR-0007). The Postmark client is built on first send and
+ * cached per token.
+ *
+ * ## Authoring note: no JSX
+ *
+ * These files use `createElement` in `.ts`, not JSX in `.tsx`, because
+ * `svelte-package` copies `.tsx` into `dist/` untranspiled. See the docblock
+ * at the top of `./Template.ts` — that constraint is load-bearing.
+ */
+import { ServerClient } from 'postmark';
+import { createElement } from 'react';
+import { render } from 'react-email';
+import { subject as buildSubject, Template, text as buildText, } from './Template.js';
+/**
+ * The address hard-bounced and Postmark has **deactivated** it.
+ *
+ * This is the signal a consumer can use to set `user.disabledAt` — see
+ * `USAGE.md`. It is thrown,
+ * never swallowed: a caller that ignores it silently tells someone a link is
+ * on its way when it is not.
+ *
+ * Distinguishable without importing `postmark` — check
+ * `error instanceof InactiveRecipientError`, or
+ * `error.name === 'InactiveRecipientError'`, which is assigned from a string
+ * literal rather than `constructor.name` so it survives minification.
+ */
+export class InactiveRecipientError extends Error {
+    /** The address we tried to send to. */
+    email;
+    /** Addresses Postmark named in the message; usually just {@link email}. */
+    recipients;
+    constructor(email, options = {}) {
+        super(`Postmark has deactivated ${email}: the address hard bounced, was reported as spam, or was suppressed manually. For a Thomson Reuters inbox this usually means the person has left.`, { cause: options.cause });
+        // A string literal, not `this.constructor.name` — see the class docblock.
+        this.name = 'InactiveRecipientError';
+        this.email = email;
+        this.recipients = options.recipients ?? [email];
+    }
+}
+/**
+ * 🚨 **Detect Postmark's inactive-recipient error by `name` and code, never
+ * `instanceof`.**
+ *
+ * Postmark's error classes do not survive some bundling — `rngs.io` learned
+ * this the hard way — so `instanceof Errors.InactiveRecipientsError` quietly
+ * stops matching and a genuine deactivation looks like a generic
+ * failure. `406` is Postmark's own
+ * `ApiInputError.ERROR_CODES.inactiveRecipient`, kept as a second signal
+ * because upstream sets `name` from `this.constructor.name` and a minifier
+ * can rename the class out from under it.
+ */
+const isInactiveRecipient = (error) => {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const e = error;
+    return e.name === 'InactiveRecipientsError' || e.code === 406;
+};
+/** Postmark parses the bounced addresses out of its own message for us. */
+const inactiveRecipients = (error) => {
+    const recipients = error?.recipients;
+    return (Array.isArray(recipients) &&
+        recipients.every((r) => typeof r === 'string')) ?
+        recipients
+        : undefined;
+};
+/** One client per token, built on demand. `ServerClient` holds a connection. */
+const clients = new Map();
+const getClient = (postmark, injected) => {
+    if (injected)
+        return injected;
+    const { token } = postmark;
+    if (!token) {
+        throw new Error('Cannot send the sign-in email: no Postmark token is configured. Set POSTMARK_API_KEY, or let the dev flow skip the inbox (ADR-0007).');
+    }
+    let client = clients.get(token);
+    if (!client) {
+        client = new ServerClient(token);
+        clients.set(token, client);
+    }
+    return client;
+};
+/**
+ * Render the sign-in email without sending it. Useful for a snapshot, and for
+ * a consumer wiring its own transport.
+ *
+ * ⚠️ **`render()` is async here.** react-email 6 / React 19 returns a
+ * `Promise<string>`; the 2.x examples all over the web are synchronous, and
+ * forgetting the `await` puts `[object Promise]` in the body of an email.
+ */
+export const renderSignInEmail = async (context) => ({
+    subject: buildSubject(context.appName),
+    html: await render(createElement(Template, context)),
+    text: buildText(context),
+});
+/**
+ * Render the sign-in email and post it to Postmark.
+ *
+ * @param message The address, the **confirm** URL, the app name, the link
+ * lifetime, and the Postmark config to send with.
+ * @param options.client A stand-in for Postmark's `ServerClient`. Supply it
+ * from a test or the fixture app; leave it out and a real client is built
+ * from `message.postmark.token` on first use and cached.
+ *
+ * @throws {InactiveRecipientError} when Postmark has deactivated the address —
+ * the `disabledAt` signal (ADR-0004). Deliberately not swallowed.
+ * @throws {Error} when no `token` is configured and no `client` was supplied.
+ */
+export const sendSignInEmail = async (message, options = {}) => {
+    const { to, postmark, ...context } = message;
+    const { subject, html, text } = await renderSignInEmail(context);
+    // Resolved outside the try so a missing token is never read as a bounce.
+    const client = getClient(postmark, options.client);
+    try {
+        await client.sendEmail({
+            From: postmark.from,
+            To: to,
+            Subject: subject,
+            HtmlBody: html,
+            TextBody: text,
+            MessageStream: postmark.messageStream,
+        });
+    }
+    catch (error) {
+        if (isInactiveRecipient(error)) {
+            throw new InactiveRecipientError(to, {
+                recipients: inactiveRecipients(error),
+                cause: error,
+            });
+        }
+        throw error;
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Root entry — types and things safe anywhere.
+ *
+ * Server code is behind `/server`, browser code behind `/client`, tables
+ * behind `/schema`. Keeping them apart is what stops a component importing
+ * something that touches Postmark or the database.
+ */
+export * from './types.js';
+export * from './domains.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Root entry — types and things safe anywhere.
+ *
+ * Server code is behind `/server`, browser code behind `/client`, tables
+ * behind `/schema`. Keeping them apart is what stops a component importing
+ * something that touches Postmark or the database.
+ */
+export * from './types.js';
+export * from './domains.js';