@shaferllc/keel 0.66.0 → 0.68.0

package/dist/core/mail.d.ts

@@ -13,8 +13,28 @@
  *     .html("<h1>Hi</h1>")
  *     .send();
  *
- * In tests, register an `ArrayTransport` and assert on `transport.sent`.
+ * Sending is slow and it fails — which is exactly what a queue is for. `sendLater()`
+ * puts the message on the queue instead of holding the request open for an SMTP
+ * round trip:
+ *
+ *   await mail().to(user.email).subject("Welcome").html(body).sendLater();
+ *
+ * In tests, `fakeMail()` swaps the transport for one that records and asserts.
  */
+import { Job } from "./queue.js";
+/** A file travelling with the message. */
+export interface Attachment {
+    filename: string;
+    /** Raw bytes, or a string (UTF-8 encoded). */
+    content: string | Uint8Array;
+    /** MIME type. Inferred from the filename's extension when omitted. */
+    contentType?: string;
+    /**
+     * A content id, for embedding in the HTML body: an attachment with `cid: "logo"`
+     * is referenced as `<img src="cid:logo">`. Implies an inline disposition.
+     */
+    cid?: string;
+}
 /** A normalized, ready-to-send message. */
 export interface Message {
     to: string[];
@@ -26,6 +46,7 @@ export interface Message {
     text?: string;
     html?: string;
     headers?: Record<string, string>;
+    attachments?: Attachment[];
 }
 /** The bridge to your email provider. */
 export interface Transport {
@@ -34,8 +55,10 @@ export interface Transport {
 export interface MailerOptions {
     /** Default `from` address for messages that don't set one. */
     from?: string;
+    /** Default `replyTo` for messages that don't set one. */
+    replyTo?: string;
 }
-/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+/** A fluent, immutable-ish builder — chain setters, then `send()` or `sendLater()`. */
 export declare class PendingMail {
     private mailer;
     private message;
@@ -49,23 +72,76 @@ export declare class PendingMail {
     text(text: string): this;
     html(html: string): this;
     header(name: string, value: string): this;
+    /** Attach a file. The content type is inferred from the extension if omitted. */
+    attach(filename: string, content: string | Uint8Array, contentType?: string): this;
+    /**
+     * Attach an image and give it a content id, so the HTML body can show it inline:
+     *
+     *   .embed("logo", bytes, "logo.png").html(`<img src="cid:logo">`)
+     */
+    embed(cid: string, content: string | Uint8Array, filename?: string, contentType?: string): this;
     /** Seed several fields at once (merges into what's been chained). */
     fill(partial: Partial<{
         to: string | string[];
         cc: string | string[];
         bcc: string | string[];
     } & Omit<Message, "to" | "cc" | "bcc">>): this;
+    /** The message as composed so far — before the mailer applies its defaults. */
+    toMessage(): Message;
     /** Freeze and hand the message to the mailer. */
     send(): Promise<Message>;
+    /**
+     * Queue the message instead of sending it now — the request returns without
+     * waiting on the provider, and a failed send retries on the queue rather than
+     * failing the user's action.
+     *
+     * With the default `SyncDriver` this still sends inline; register a real queue
+     * driver to actually defer it.
+     */
+    sendLater(): Promise<void>;
+}
+/**
+ * A reusable, testable email as a class — the mail equivalent of a `Job`.
+ * Implement `build()` to compose the message; the mailer calls it for you.
+ *
+ *   export class WelcomeEmail extends BaseMail {
+ *     constructor(private user: User) { super(); }
+ *
+ *     build(message: PendingMail) {
+ *       message.to(this.user.email).subject("Welcome").html(`<h1>Hi ${this.user.name}</h1>`);
+ *     }
+ *   }
+ *
+ *   await send(new WelcomeEmail(user));       // or sendLater(new WelcomeEmail(user))
+ */
+export declare abstract class BaseMail {
+    abstract build(message: PendingMail): void | Promise<void>;
+}
+/** The job that carries a queued message. Exported so a driver can recognize it. */
+export declare class SendMailJob extends Job {
+    readonly message: Message;
+    readonly mailerName: string;
+    constructor(message: Message, mailerName: string);
+    handle(): Promise<void>;
 }
 export declare class Mailer {
     private transport;
     private options;
-    constructor(transport: Transport, options?: MailerOptions);
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    readonly name: string;
+    constructor(transport: Transport, options?: MailerOptions, 
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    name?: string);
     /** Start composing a message. */
     message(): PendingMail;
+    /** Apply this mailer's defaults and check the message is sendable. */
+    protected prepare(message: Message): Message;
     /** Validate, apply defaults, and dispatch through the transport. */
     send(message: Message): Promise<Message>;
+    /** Validate, apply defaults, and put the message on the queue. */
+    sendLater(message: Message): Promise<Message>;
+    /** The underlying transport, for provider-specific operations. */
+    get driver(): Transport;
 }
 /** Collects sent messages in memory — the default, and ideal for tests. */
 export declare class ArrayTransport implements Transport {
@@ -86,9 +162,54 @@ export interface FetchTransportOptions {
 }
 /** A generic HTTP transport for provider APIs (Resend, Postmark, …), via `fetch`. */
 export declare function fetchTransport(options: FetchTransportOptions): Transport;
-/** Register the default mailer used by `mail()`. */
-export declare function setMailer(transport: Transport, options?: MailerOptions): Mailer;
+/** A message recorded by the fake, and whether it was sent now or queued. */
+export interface RecordedMail {
+    message: Message;
+    queued: boolean;
+}
+/**
+ * A `Mailer` that records instead of delivering, with assertions — what
+ * `fakeMail()` installs so tests never talk to a provider.
+ */
+export declare class FakeMailer extends Mailer {
+    readonly mails: RecordedMail[];
+    constructor(name?: string, options?: MailerOptions);
+    send(message: Message): Promise<Message>;
+    sendLater(message: Message): Promise<Message>;
+    /** Everything sent immediately. */
+    sent(): Message[];
+    /** Everything queued with `sendLater()`. */
+    queued(): Message[];
+    assertSent(where?: (message: Message) => boolean): void;
+    assertNotSent(where?: (message: Message) => boolean): void;
+    assertSentCount(expected: number): void;
+    assertQueued(where?: (message: Message) => boolean): void;
+    assertNotQueued(where?: (message: Message) => boolean): void;
+    assertQueuedCount(expected: number): void;
+    /** Nothing sent and nothing queued. */
+    assertNothingSent(): void;
+    private summary;
+}
+/** Register a mailer, optionally under a name (default: `"default"`). */
+export declare function setMailer(transport: Transport, options?: MailerOptions, name?: string): Mailer;
+/** The default mailer, or a named one registered with `setMailer(…, …, name)`. */
+export declare function mailer(name?: string): Mailer;
 /** The default mailer instance. */
 export declare function getMailer(): Mailer;
-/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
-export declare function mail(): PendingMail;
+/** Start a message on a mailer: `mail().to(…).subject(…).send()`. */
+export declare function mail(name?: string): PendingMail;
+/** Send a class-based mail now. */
+export declare function send(email: BaseMail, name?: string): Promise<Message>;
+/** Queue a class-based mail. */
+export declare function sendLater(email: BaseMail, name?: string): Promise<Message>;
+/**
+ * Swap a mailer for a `FakeMailer` so tests never talk to a provider, and assert
+ * on what was sent or queued. Undo with `restoreMail()`.
+ *
+ *   const mail = fakeMail();
+ *   await registerUser();
+ *   mail.assertQueued((m) => m.subject === "Welcome");
+ */
+export declare function fakeMail(name?: string): FakeMailer;
+/** Restore the real mailer after `fakeMail()`. With no name, restores them all. */
+export declare function restoreMail(name?: string): void;

package/dist/core/mail.js

@@ -13,15 +13,33 @@
  *     .html("<h1>Hi</h1>")
  *     .send();
  *
- * In tests, register an `ArrayTransport` and assert on `transport.sent`.
+ * Sending is slow and it fails — which is exactly what a queue is for. `sendLater()`
+ * puts the message on the queue instead of holding the request open for an SMTP
+ * round trip:
+ *
+ *   await mail().to(user.email).subject("Welcome").html(body).sendLater();
+ *
+ * In tests, `fakeMail()` swaps the transport for one that records and asserts.
+ */
+import { logger, emit, hasApplication } from "./helpers.js";
+import { dispatch, Job } from "./queue.js";
+import { contentTypeFor } from "./storage.js";
+/**
+ * Fire a mail lifecycle event, but only if there's an application to fire it on —
+ * the mailer has to work in a unit test that never bootstrapped one. A listener
+ * that throws still surfaces; it's only the missing-app case we skip.
  */
-import { logger } from "./helpers.js";
+async function notify(event, message) {
+    if (hasApplication())
+        await emit(event, message);
+}
 function list(value) {
     if (value === undefined)
         return [];
     return Array.isArray(value) ? value : [value];
 }
-/** A fluent, immutable-ish builder — chain setters, then `send()`. */
+/* --------------------------------- builder -------------------------------- */
+/** A fluent, immutable-ish builder — chain setters, then `send()` or `sendLater()`. */
 export class PendingMail {
     mailer;
     message = { to: [], subject: "" };
@@ -64,6 +82,29 @@ export class PendingMail {
         (this.message.headers ??= {})[name] = value;
         return this;
     }
+    /** Attach a file. The content type is inferred from the extension if omitted. */
+    attach(filename, content, contentType) {
+        (this.message.attachments ??= []).push({
+            filename,
+            content,
+            contentType: contentType ?? contentTypeFor(filename),
+        });
+        return this;
+    }
+    /**
+     * Attach an image and give it a content id, so the HTML body can show it inline:
+     *
+     *   .embed("logo", bytes, "logo.png").html(`<img src="cid:logo">`)
+     */
+    embed(cid, content, filename = cid, contentType) {
+        (this.message.attachments ??= []).push({
+            filename,
+            content,
+            contentType: contentType ?? contentTypeFor(filename),
+            cid,
+        });
+        return this;
+    }
     /** Seed several fields at once (merges into what's been chained). */
     fill(partial) {
         const { to, cc, bcc, ...rest } = partial;
@@ -76,25 +117,79 @@ export class PendingMail {
         Object.assign(this.message, rest);
         return this;
     }
+    /** The message as composed so far — before the mailer applies its defaults. */
+    toMessage() {
+        return { ...this.message };
+    }
     /** Freeze and hand the message to the mailer. */
     async send() {
         return this.mailer.send(this.message);
     }
+    /**
+     * Queue the message instead of sending it now — the request returns without
+     * waiting on the provider, and a failed send retries on the queue rather than
+     * failing the user's action.
+     *
+     * With the default `SyncDriver` this still sends inline; register a real queue
+     * driver to actually defer it.
+     */
+    async sendLater() {
+        await this.mailer.sendLater(this.message);
+    }
+}
+/* ------------------------------- class mails ------------------------------ */
+/**
+ * A reusable, testable email as a class — the mail equivalent of a `Job`.
+ * Implement `build()` to compose the message; the mailer calls it for you.
+ *
+ *   export class WelcomeEmail extends BaseMail {
+ *     constructor(private user: User) { super(); }
+ *
+ *     build(message: PendingMail) {
+ *       message.to(this.user.email).subject("Welcome").html(`<h1>Hi ${this.user.name}</h1>`);
+ *     }
+ *   }
+ *
+ *   await send(new WelcomeEmail(user));       // or sendLater(new WelcomeEmail(user))
+ */
+export class BaseMail {
+}
+/** The job that carries a queued message. Exported so a driver can recognize it. */
+export class SendMailJob extends Job {
+    message;
+    mailerName;
+    constructor(message, mailerName) {
+        super();
+        this.message = message;
+        this.mailerName = mailerName;
+    }
+    async handle() {
+        await mailer(this.mailerName).send(this.message);
+    }
 }
+/* --------------------------------- mailer --------------------------------- */
 export class Mailer {
     transport;
     options;
-    constructor(transport, options = {}) {
+    name;
+    constructor(transport, options = {}, 
+    /** The name this mailer is registered under — carried onto queued jobs. */
+    name = "default") {
         this.transport = transport;
         this.options = options;
+        this.name = name;
     }
     /** Start composing a message. */
     message() {
         return new PendingMail(this);
     }
-    /** Validate, apply defaults, and dispatch through the transport. */
-    async send(message) {
-        const final = { ...message, from: message.from ?? this.options.from };
+    /** Apply this mailer's defaults and check the message is sendable. */
+    prepare(message) {
+        const final = {
+            ...message,
+            from: message.from ?? this.options.from,
+            replyTo: message.replyTo ?? this.options.replyTo,
+        };
         if (!final.to.length)
             throw new Error("Mail: at least one recipient (to) is required.");
         if (!final.subject)
@@ -103,9 +198,29 @@ export class Mailer {
             throw new Error("Mail: a text or html body is required.");
         if (!final.from)
             throw new Error("Mail: a from address is required (set one or a default).");
+        return final;
+    }
+    /** Validate, apply defaults, and dispatch through the transport. */
+    async send(message) {
+        const final = this.prepare(message);
+        await notify("mail.sending", final);
         await this.transport.send(final);
+        await notify("mail.sent", final);
+        return final;
+    }
+    /** Validate, apply defaults, and put the message on the queue. */
+    async sendLater(message) {
+        // Validate *now*, not on the worker: a malformed message should blow up at
+        // the call site, where the stack trace means something.
+        const final = this.prepare(message);
+        await dispatch(new SendMailJob(final, this.name));
+        await notify("mail.queued", final);
         return final;
     }
+    /** The underlying transport, for provider-specific operations. */
+    get driver() {
+        return this.transport;
+    }
 }
 /* ------------------------------- transports ------------------------------- */
 /** Collects sent messages in memory — the default, and ideal for tests. */
@@ -140,18 +255,151 @@ export function fetchTransport(options) {
         },
     };
 }
+/**
+ * A `Mailer` that records instead of delivering, with assertions — what
+ * `fakeMail()` installs so tests never talk to a provider.
+ */
+export class FakeMailer extends Mailer {
+    mails = [];
+    constructor(name = "default", options = {}) {
+        // A from address so a fake never trips the "from is required" check.
+        super(new ArrayTransport(), { from: "fake@example.com", ...options }, name);
+    }
+    async send(message) {
+        const final = await super.send(message);
+        this.mails.push({ message: final, queued: false });
+        return final;
+    }
+    async sendLater(message) {
+        // Validate exactly as a real mailer would, but don't touch the queue —
+        // recording the intent *is* the point.
+        const final = this.prepare(message);
+        this.mails.push({ message: final, queued: true });
+        await notify("mail.queued", final);
+        return final;
+    }
+    /** Everything sent immediately. */
+    sent() {
+        return this.mails.filter((m) => !m.queued).map((m) => m.message);
+    }
+    /** Everything queued with `sendLater()`. */
+    queued() {
+        return this.mails.filter((m) => m.queued).map((m) => m.message);
+    }
+    assertSent(where) {
+        const matches = this.sent().filter((m) => where?.(m) ?? true);
+        if (matches.length)
+            return;
+        throw new Error(where && this.sent().length
+            ? `Expected a sent mail matching the predicate. ${this.sent().length} were sent, but none matched.`
+            : `Expected a mail to be sent, but none was. ${this.summary()}`);
+    }
+    assertNotSent(where) {
+        const found = this.sent().filter((m) => where?.(m) ?? true).length;
+        if (found)
+            throw new Error(`Expected no matching mail to be sent, but ${found} was.`);
+    }
+    assertSentCount(expected) {
+        const found = this.sent().length;
+        if (found !== expected) {
+            throw new Error(`Expected ${expected} mail(s) to be sent, but ${found} were.`);
+        }
+    }
+    assertQueued(where) {
+        const matches = this.queued().filter((m) => where?.(m) ?? true);
+        if (matches.length)
+            return;
+        throw new Error(where && this.queued().length
+            ? `Expected a queued mail matching the predicate. ${this.queued().length} were queued, but none matched.`
+            : `Expected a mail to be queued, but none was. ${this.summary()}`);
+    }
+    assertNotQueued(where) {
+        const found = this.queued().filter((m) => where?.(m) ?? true).length;
+        if (found)
+            throw new Error(`Expected no matching mail to be queued, but ${found} was.`);
+    }
+    assertQueuedCount(expected) {
+        const found = this.queued().length;
+        if (found !== expected) {
+            throw new Error(`Expected ${expected} mail(s) to be queued, but ${found} were.`);
+        }
+    }
+    /** Nothing sent and nothing queued. */
+    assertNothingSent() {
+        if (this.mails.length) {
+            throw new Error(`Expected no mail at all, but ${this.mails.length} were recorded. ${this.summary()}`);
+        }
+    }
+    summary() {
+        if (!this.mails.length)
+            return "No mail was sent or queued.";
+        const subjects = this.mails.map((m) => `"${m.message.subject}"`).join(", ");
+        return `Recorded: ${subjects}.`;
+    }
+}
 /* --------------------------------- global --------------------------------- */
-let mailer = new Mailer(new ArrayTransport());
-/** Register the default mailer used by `mail()`. */
-export function setMailer(transport, options = {}) {
-    mailer = new Mailer(transport, options);
-    return mailer;
+const mailers = new Map([["default", new Mailer(new ArrayTransport())]]);
+/** Mailers displaced by `fakeMail()`, so `restoreMail()` can put them back. */
+const realMailers = new Map();
+/** Register a mailer, optionally under a name (default: `"default"`). */
+export function setMailer(transport, options = {}, name = "default") {
+    const instance = new Mailer(transport, options, name);
+    mailers.set(name, instance);
+    return instance;
+}
+/** The default mailer, or a named one registered with `setMailer(…, …, name)`. */
+export function mailer(name = "default") {
+    const instance = mailers.get(name);
+    if (!instance)
+        throw new Error(`No mailer named "${name}". Register it with setMailer().`);
+    return instance;
 }
 /** The default mailer instance. */
 export function getMailer() {
-    return mailer;
+    return mailer();
+}
+/** Start a message on a mailer: `mail().to(…).subject(…).send()`. */
+export function mail(name = "default") {
+    return mailer(name).message();
+}
+/** Build a `BaseMail` into a message on the given mailer. */
+async function build(email, name) {
+    const pending = mailer(name).message();
+    await email.build(pending);
+    return pending.toMessage();
 }
-/** Start a message on the default mailer: `mail().to(…).subject(…).send()`. */
-export function mail() {
-    return mailer.message();
+/** Send a class-based mail now. */
+export async function send(email, name = "default") {
+    return mailer(name).send(await build(email, name));
+}
+/** Queue a class-based mail. */
+export async function sendLater(email, name = "default") {
+    return mailer(name).sendLater(await build(email, name));
+}
+/**
+ * Swap a mailer for a `FakeMailer` so tests never talk to a provider, and assert
+ * on what was sent or queued. Undo with `restoreMail()`.
+ *
+ *   const mail = fakeMail();
+ *   await registerUser();
+ *   mail.assertQueued((m) => m.subject === "Welcome");
+ */
+export function fakeMail(name = "default") {
+    const existing = mailers.get(name);
+    // Only remember the *real* mailer — faking twice must not stash a fake.
+    if (existing && !realMailers.has(name))
+        realMailers.set(name, existing);
+    const fake = new FakeMailer(name);
+    mailers.set(name, fake);
+    return fake;
+}
+/** Restore the real mailer after `fakeMail()`. With no name, restores them all. */
+export function restoreMail(name) {
+    const names = name ? [name] : [...realMailers.keys()];
+    for (const key of names) {
+        const real = realMailers.get(key);
+        if (real)
+            mailers.set(key, real);
+        realMailers.delete(key);
+    }
 }