@rudderjs/mail 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suleiman Shahbari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @rudderjs/mail
+
+Mail facade, mailable abstraction, and provider factory with built-in `log` and `smtp` drivers.
+
+## Installation
+
+```bash
+pnpm add @rudderjs/mail
+```
+
+## Setup
+
+```ts
+// config/mail.ts
+import type { MailConfig } from '@rudderjs/mail'
+
+export default {
+  default: Env.get('MAIL_MAILER', 'log'),
+  from: {
+    address: Env.get('MAIL_FROM_ADDRESS', 'noreply@example.com'),
+    name:    Env.get('MAIL_FROM_NAME', 'My App'),
+  },
+  mailers: {
+    log: { driver: 'log' },
+    smtp: {
+      driver:     'smtp',
+      host:       Env.get('MAIL_HOST', 'smtp.mailtrap.io'),
+      port:       Number(Env.get('MAIL_PORT', '587')),
+      username:   Env.get('MAIL_USERNAME', ''),
+      password:   Env.get('MAIL_PASSWORD', ''),
+      encryption: 'tls',
+    },
+  },
+} satisfies MailConfig
+```
+
+```ts
+// bootstrap/providers.ts
+import { mail } from '@rudderjs/mail'
+import configs from '../config/index.js'
+
+export default [mail(configs.mail)]
+```
+
+## Defining Mailables
+
+Mailables describe an email. Extend `Mailable` and implement `build()` to set the subject, HTML, and plain-text body using the fluent protected methods.
+
+```ts
+import { Mailable } from '@rudderjs/mail'
+
+export class WelcomeEmail extends Mailable {
+  constructor(private readonly name: string) { super() }
+
+  build() {
+    return this
+      .subject(`Welcome, ${this.name}!`)
+      .html(`<h1>Hi ${this.name}, welcome aboard.</h1>`)
+      .text(`Hi ${this.name}, welcome aboard.`)
+  }
+}
+```
+
+## Sending Mail
+
+```ts
+import { Mail } from '@rudderjs/mail'
+import { WelcomeEmail } from './WelcomeEmail.js'
+
+// Single recipient
+await Mail.to('user@example.com').send(new WelcomeEmail('Alice'))
+
+// Multiple recipients with CC and BCC
+await Mail.to('a@example.com', 'b@example.com')
+  .cc('manager@example.com')
+  .bcc('audit@example.com')
+  .send(new WelcomeEmail('Alice'))
+```
+
+## `Mail` / `MailPendingSend` Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `Mail.to(...addresses)` | `MailPendingSend` | Start a fluent send chain. |
+| `.cc(...addresses)` | `this` | Add CC recipients. |
+| `.bcc(...addresses)` | `this` | Add BCC recipients. |
+| `.send(mailable)` | `Promise<void>` | Compile and send via the registered adapter. |
+
+## `Mailable` Protected Methods
+
+| Method | Description |
+|--------|-------------|
+| `subject(text)` | Set the email subject. |
+| `html(html)` | Set the HTML body. |
+| `text(text)` | Set the plain-text body. |
+
+## Configuration
+
+### `MailConfig`
+
+```ts
+interface MailConfig {
+  default: string
+  from: { address: string; name?: string }
+  mailers: Record<string, MailConnectionConfig>
+}
+```
+
+### `NodemailerConfig` (smtp driver)
+
+```ts
+{
+  driver:      'smtp',
+  host:        string,
+  port:        number,
+  username?:   string,
+  password?:   string,
+  encryption?: 'tls' | 'ssl' | 'none',
+}
+```
+
+## Built-in Drivers
+
+### `log`
+
+Prints outgoing emails to the console. No external dependencies. Ideal for local development.
+
+```ts
+{ driver: 'log' }
+```
+
+### `smtp`
+
+Sends emails via SMTP using Nodemailer. Requires `pnpm add nodemailer`.
+
+```ts
+{ driver: 'smtp', host: 'smtp.mailtrap.io', port: 587 }
+```
+
+## `LogAdapter`
+
+Exported for standalone use and testing:
+
+```ts
+import { LogAdapter } from '@rudderjs/mail'
+
+const adapter = new LogAdapter()
+await adapter.send(mailable, { to: ['user@example.com'], from: { address: 'noreply@app.com' } })
+```
+
+## Notes
+
+- `build()` can be `async` — useful for loading dynamic content before sending.
+- Both `html` and `text` are optional — set at least one for deliverability.
+- The global `from` address in config is used for all outgoing mail unless overridden per-mailable.
+- `smtp` driver requires `pnpm add nodemailer` — it is an optional dependency.

package/dist/failover.d.ts

@@ -0,0 +1,26 @@
+import type { Mailable } from './mailable.js';
+import type { MailAdapter, SendOptions } from './index.js';
+/**
+ * Tries mailers in order — if the first fails, falls back to the next.
+ * All configured mailers must fail before the send is considered a failure.
+ *
+ * @example
+ * // In config/mail.ts:
+ * mailers: {
+ *   failover: {
+ *     driver: 'failover',
+ *     mailers: ['smtp', 'ses', 'log'],
+ *     retryAfter: 60, // seconds before retrying a failed mailer
+ *   },
+ *   smtp: { driver: 'smtp', host: '...', port: 587 },
+ *   ses: { driver: 'smtp', host: 'email-smtp.us-east-1.amazonaws.com', ... },
+ * }
+ */
+export declare class FailoverAdapter implements MailAdapter {
+    private readonly _adapters;
+    private readonly _retryAfter;
+    private _lastFailures;
+    constructor(_adapters: MailAdapter[], _retryAfter?: number);
+    send(mailable: Mailable, options: SendOptions): Promise<void>;
+}
+//# sourceMappingURL=failover.d.ts.map

package/dist/failover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failover.d.ts","sourceRoot":"","sources":["../src/failover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAI1D;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAI/C,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJ9B,OAAO,CAAC,aAAa,CAA4B;gBAG9B,SAAS,EAAE,WAAW,EAAE,EACxB,WAAW,SAAK;IAG7B,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;CAyBpE"}

package/dist/failover.js

@@ -0,0 +1,48 @@
+// ─── FailoverAdapter ────────────────────────────────────────
+/**
+ * Tries mailers in order — if the first fails, falls back to the next.
+ * All configured mailers must fail before the send is considered a failure.
+ *
+ * @example
+ * // In config/mail.ts:
+ * mailers: {
+ *   failover: {
+ *     driver: 'failover',
+ *     mailers: ['smtp', 'ses', 'log'],
+ *     retryAfter: 60, // seconds before retrying a failed mailer
+ *   },
+ *   smtp: { driver: 'smtp', host: '...', port: 587 },
+ *   ses: { driver: 'smtp', host: 'email-smtp.us-east-1.amazonaws.com', ... },
+ * }
+ */
+export class FailoverAdapter {
+    _adapters;
+    _retryAfter;
+    _lastFailures = new Map();
+    constructor(_adapters, _retryAfter = 60) {
+        this._adapters = _adapters;
+        this._retryAfter = _retryAfter;
+    }
+    async send(mailable, options) {
+        const errors = [];
+        const now = Date.now();
+        for (let i = 0; i < this._adapters.length; i++) {
+            // Skip adapters that recently failed (within retryAfter window)
+            const lastFailure = this._lastFailures.get(i);
+            if (lastFailure !== undefined && now - lastFailure < this._retryAfter * 1000) {
+                continue;
+            }
+            try {
+                await this._adapters[i].send(mailable, options);
+                return; // success
+            }
+            catch (err) {
+                this._lastFailures.set(i, now);
+                errors.push(err instanceof Error ? err : new Error(String(err)));
+            }
+        }
+        throw new Error(`[RudderJS Mail] All mailers failed.\n` +
+            errors.map((e, i) => `  Mailer ${i}: ${e.message}`).join('\n'));
+    }
+}
+//# sourceMappingURL=failover.js.map

package/dist/failover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failover.js","sourceRoot":"","sources":["../src/failover.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAIP;IACA;IAJX,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAA;IAEjD,YACmB,SAAwB,EACxB,cAAc,EAAE;QADhB,cAAS,GAAT,SAAS,CAAe;QACxB,gBAAW,GAAX,WAAW,CAAK;IAChC,CAAC;IAEJ,KAAK,CAAC,IAAI,CAAC,QAAkB,EAAE,OAAoB;QACjD,MAAM,MAAM,GAAY,EAAE,CAAA;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAC/C,gEAAgE;YAChE,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAC7C,IAAI,WAAW,KAAK,SAAS,IAAI,GAAG,GAAG,WAAW,GAAG,IAAI,CAAC,WAAW,GAAG,IAAI,EAAE,CAAC;gBAC7E,SAAQ;YACV,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,SAAS,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;gBAChD,OAAM,CAAC,UAAU;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;gBAC9B,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;YAClE,CAAC;QACH,CAAC;QAED,MAAM,IAAI,KAAK,CACb,uCAAuC;YACvC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC/D,CAAA;IACH,CAAC;CACF"}

package/dist/fake.d.ts

@@ -0,0 +1,62 @@
+import type { MailAdapter, SendOptions } from './index.js';
+import type { Mailable } from './mailable.js';
+/**
+ * Testing fake for @rudderjs/mail.
+ *
+ * Records all sent and queued mailables instead of delivering them,
+ * and provides assertion methods for verifying mail behavior in tests.
+ *
+ * @example
+ * const fake = FakeMailAdapter.fake()
+ *
+ * await Mail.to('user@example.com').send(new WelcomeMail())
+ *
+ * fake.assertSent(WelcomeMail)
+ * fake.assertSentCount(1)
+ * fake.restore()
+ */
+export declare class FakeMailAdapter implements MailAdapter {
+    private readonly _sent;
+    private readonly _queued;
+    send(mailable: Mailable, options: SendOptions): Promise<void>;
+    /** Record a mailable as queued (called internally by the queue integration). */
+    recordQueued(mailable: Mailable, options: SendOptions): void;
+    /** Assert that a mailable of the given class was sent, optionally matching a predicate. */
+    assertSent(mailableClass: new (...args: unknown[]) => Mailable, predicate?: (entry: {
+        mailable: Mailable;
+        options: SendOptions;
+    }) => boolean): void;
+    /** Assert that exactly N mailables were sent (across all classes). */
+    assertSentCount(count: number): void;
+    /** Assert that a mailable of the given class was NOT sent. */
+    assertNotSent(mailableClass: new (...args: unknown[]) => Mailable): void;
+    /** Assert that no mailables were sent at all. */
+    assertNothingSent(): void;
+    /** Assert that a mailable of the given class was queued. */
+    assertQueued(mailableClass: new (...args: unknown[]) => Mailable, predicate?: (entry: {
+        mailable: Mailable;
+        options: SendOptions;
+    }) => boolean): void;
+    /** Assert that a mailable of the given class was NOT queued. */
+    assertNotQueued(mailableClass: new (...args: unknown[]) => Mailable): void;
+    /** Assert that no mailables were queued at all. */
+    assertNothingQueued(): void;
+    /** Get all sent mailables, optionally filtered by class. */
+    sent(mailableClass?: new (...args: unknown[]) => Mailable): Array<{
+        mailable: Mailable;
+        options: SendOptions;
+    }>;
+    /** Get all queued mailables, optionally filtered by class. */
+    queued(mailableClass?: new (...args: unknown[]) => Mailable): Array<{
+        mailable: Mailable;
+        options: SendOptions;
+    }>;
+    /** Restore the mail registry — clears the fake adapter. */
+    restore(): void;
+    /** Install the fake — replaces the registered mail adapter with this fake. */
+    static fake(): FakeMailAdapter;
+    private _isInstance;
+    private _matchingSent;
+    private _matchingQueued;
+}
+//# sourceMappingURL=fake.d.ts.map

package/dist/fake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake.d.ts","sourceRoot":"","sources":["../src/fake.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4D;IAClF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0D;IAI5E,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnE,gFAAgF;IAChF,YAAY,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI;IAM5D,2FAA2F;IAC3F,UAAU,CACR,aAAa,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,EACnD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,GAC3E,IAAI;IAQP,sEAAsE;IACtE,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAQpC,8DAA8D;IAC9D,aAAa,CAAC,aAAa,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,GAAG,IAAI;IASxE,iDAAiD;IACjD,iBAAiB,IAAI,IAAI;IAUzB,4DAA4D;IAC5D,YAAY,CACV,aAAa,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,EACnD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,GAC3E,IAAI;IAQP,gEAAgE;IAChE,eAAe,CAAC,aAAa,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,GAAG,IAAI;IAS1E,mDAAmD;IACnD,mBAAmB,IAAI,IAAI;IAU3B,4DAA4D;IAC5D,IAAI,CACF,aAAa,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,GACnD,KAAK,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC;IAKtD,8DAA8D;IAC9D,MAAM,CACJ,aAAa,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,QAAQ,GACnD,KAAK,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC;IAOtD,2DAA2D;IAC3D,OAAO,IAAI,IAAI;IAMf,8EAA8E;IAC9E,MAAM,CAAC,IAAI,IAAI,eAAe;IAQ9B,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,eAAe;CAUxB"}

package/dist/fake.js

@@ -0,0 +1,113 @@
+import assert from 'node:assert/strict';
+import { MailRegistry } from './index.js';
+/**
+ * Testing fake for @rudderjs/mail.
+ *
+ * Records all sent and queued mailables instead of delivering them,
+ * and provides assertion methods for verifying mail behavior in tests.
+ *
+ * @example
+ * const fake = FakeMailAdapter.fake()
+ *
+ * await Mail.to('user@example.com').send(new WelcomeMail())
+ *
+ * fake.assertSent(WelcomeMail)
+ * fake.assertSentCount(1)
+ * fake.restore()
+ */
+export class FakeMailAdapter {
+    _sent = [];
+    _queued = [];
+    // ─── MailAdapter interface ───────────────────────────────
+    async send(mailable, options) {
+        this._sent.push({ mailable, options });
+    }
+    // ─── Queued mail tracking ────────────────────────────────
+    /** Record a mailable as queued (called internally by the queue integration). */
+    recordQueued(mailable, options) {
+        this._queued.push({ mailable, options });
+    }
+    // ─── Assertions: sent ────────────────────────────────────
+    /** Assert that a mailable of the given class was sent, optionally matching a predicate. */
+    assertSent(mailableClass, predicate) {
+        const matching = this._matchingSent(mailableClass, predicate);
+        assert.ok(matching.length > 0, `[RudderJS Mail] Expected "${mailableClass.name}" to be sent, but it was not.`);
+    }
+    /** Assert that exactly N mailables were sent (across all classes). */
+    assertSentCount(count) {
+        assert.strictEqual(this._sent.length, count, `[RudderJS Mail] Expected ${count} mail(s) to be sent, but ${this._sent.length} were sent.`);
+    }
+    /** Assert that a mailable of the given class was NOT sent. */
+    assertNotSent(mailableClass) {
+        const matching = this._matchingSent(mailableClass);
+        assert.strictEqual(matching.length, 0, `[RudderJS Mail] Expected "${mailableClass.name}" not to be sent, but it was sent ${matching.length} time(s).`);
+    }
+    /** Assert that no mailables were sent at all. */
+    assertNothingSent() {
+        assert.strictEqual(this._sent.length, 0, `[RudderJS Mail] Expected no mail to be sent, but ${this._sent.length} were sent.`);
+    }
+    // ─── Assertions: queued ──────────────────────────────────
+    /** Assert that a mailable of the given class was queued. */
+    assertQueued(mailableClass, predicate) {
+        const matching = this._matchingQueued(mailableClass, predicate);
+        assert.ok(matching.length > 0, `[RudderJS Mail] Expected "${mailableClass.name}" to be queued, but it was not.`);
+    }
+    /** Assert that a mailable of the given class was NOT queued. */
+    assertNotQueued(mailableClass) {
+        const matching = this._matchingQueued(mailableClass);
+        assert.strictEqual(matching.length, 0, `[RudderJS Mail] Expected "${mailableClass.name}" not to be queued, but it was queued ${matching.length} time(s).`);
+    }
+    /** Assert that no mailables were queued at all. */
+    assertNothingQueued() {
+        assert.strictEqual(this._queued.length, 0, `[RudderJS Mail] Expected no mail to be queued, but ${this._queued.length} were queued.`);
+    }
+    // ─── Access ──────────────────────────────────────────────
+    /** Get all sent mailables, optionally filtered by class. */
+    sent(mailableClass) {
+        if (!mailableClass)
+            return [...this._sent];
+        return this._matchingSent(mailableClass);
+    }
+    /** Get all queued mailables, optionally filtered by class. */
+    queued(mailableClass) {
+        if (!mailableClass)
+            return [...this._queued];
+        return this._matchingQueued(mailableClass);
+    }
+    // ─── Cleanup ─────────────────────────────────────────────
+    /** Restore the mail registry — clears the fake adapter. */
+    restore() {
+        MailRegistry.reset();
+    }
+    // ─── Install ─────────────────────────────────────────────
+    /** Install the fake — replaces the registered mail adapter with this fake. */
+    static fake() {
+        const fake = new FakeMailAdapter();
+        MailRegistry.set(fake);
+        return fake;
+    }
+    // ─── Internal ────────────────────────────────────────────
+    _isInstance(mailable, mailableClass) {
+        return (mailable instanceof mailableClass ||
+            mailable.constructor.name === mailableClass.name);
+    }
+    _matchingSent(mailableClass, predicate) {
+        return this._sent.filter((entry) => {
+            if (!this._isInstance(entry.mailable, mailableClass))
+                return false;
+            if (predicate && !predicate(entry))
+                return false;
+            return true;
+        });
+    }
+    _matchingQueued(mailableClass, predicate) {
+        return this._queued.filter((entry) => {
+            if (!this._isInstance(entry.mailable, mailableClass))
+                return false;
+            if (predicate && !predicate(entry))
+                return false;
+            return true;
+        });
+    }
+}
+//# sourceMappingURL=fake.js.map

package/dist/fake.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import { ServiceProvider, type Application } from '@rudderjs/core';
+import { Mailable } from './mailable.js';
+export { Mailable } from './mailable.js';
+export type { MailMessage } from './mailable.js';
+export interface SendOptions {
+    to: string[];
+    from: {
+        address: string;
+        name?: string;
+    };
+    cc?: string[];
+    bcc?: string[];
+}
+export interface MailAdapter {
+    send(mailable: Mailable, options: SendOptions): Promise<void>;
+}
+export interface MailAdapterProvider {
+    create(): MailAdapter;
+}
+export declare class MailRegistry {
+    private static adapter;
+    private static _from;
+    static set(adapter: MailAdapter): void;
+    static get(): MailAdapter | null;
+    static setFrom(from: {
+        address: string;
+        name?: string;
+    }): void;
+    static getFrom(): {
+        address: string;
+        name?: string;
+    };
+    /** @internal — clears the registered adapter and resets from. Used for testing. */
+    static reset(): void;
+}
+export declare class MailPendingSend {
+    private readonly _to;
+    private _cc;
+    private _bcc;
+    private _queue?;
+    constructor(_to: string[]);
+    cc(...addresses: string[]): this;
+    bcc(...addresses: string[]): this;
+    /** Specify which queue to use for queued mail. */
+    onQueue(name: string): this;
+    send(mailable: Mailable): Promise<void>;
+    /** Queue the mailable for background sending. Requires `@rudderjs/queue`. */
+    queue(mailable: Mailable): Promise<void>;
+    /** Queue the mailable to be sent after a delay (ms). Requires `@rudderjs/queue`. */
+    later(delay: number, mailable: Mailable): Promise<void>;
+}
+export declare class Mail {
+    static to(...addresses: string[]): MailPendingSend;
+    /** Replace the mail adapter with a fake for testing. */
+    static fake(): import('./fake.js').FakeMailAdapter;
+}
+export interface MailConnectionConfig {
+    driver: string;
+    [key: string]: unknown;
+}
+export interface MailConfig {
+    /** The default mailer connection name */
+    default: string;
+    /** From address used on all outgoing mail */
+    from: {
+        address: string;
+        name?: string;
+    };
+    /** Named mailer connections */
+    mailers: Record<string, MailConnectionConfig>;
+}
+export interface NodemailerConfig {
+    driver: 'smtp';
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+    encryption?: 'tls' | 'ssl' | 'none';
+}
+export declare class LogAdapter implements MailAdapter {
+    send(mailable: Mailable, options: SendOptions): Promise<void>;
+}
+export declare function nodemailer(config: NodemailerConfig, from: {
+    address: string;
+    name?: string;
+}): MailAdapterProvider;
+/**
+ * Returns a MailServiceProvider class configured for the given mail config.
+ *
+ * Built-in drivers:  log (prints to console — great for dev), smtp (Nodemailer)
+ *
+ * Usage in bootstrap/providers.ts:
+ *   import { mail } from '@rudderjs/mail'
+ *   import configs from '../config/index.js'
+ *   export default [..., mail(configs.mail), ...]
+ */
+export declare function mail(config: MailConfig): new (app: Application) => ServiceProvider;
+export { FailoverAdapter } from './failover.js';
+export { MarkdownMailable } from './markdown.js';
+export { mailPreview } from './preview.js';
+export { FakeMailAdapter } from './fake.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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