@pearl-framework/mail 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> @pearl-framework/mail@0.1.0 build /Users/sharvari/Desktop/Sharvari's Work Station/pearljs/packages/mail
+> tsc
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sharvari Divekar
+
+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,65 @@
+# @pearl-framework/mail
+
+> Mailable classes and multi-transport email sending for Pearl.js
+
+## Installation
+
+```bash
+pnpm add @pearl-framework/mail @pearl-framework/core nodemailer
+```
+
+## Usage
+
+### Define a mailable
+
+```ts
+import { Mailable } from '@pearl-framework/mail'
+
+export class WelcomeEmail extends Mailable {
+  constructor(private readonly user: User) { super() }
+
+  build(): this {
+    return this
+      .to(this.user.email)
+      .from({ name: 'Pearl App', address: 'hi@pearl.dev' })
+      .subject('Welcome to Pearl!')
+      .html(`<h1>Hi ${this.user.name}, welcome aboard!</h1>`)
+      .text(`Hi ${this.user.name}, welcome aboard!`)
+  }
+}
+```
+
+### Send mail
+
+```ts
+const mailer = app.make(Mailer)
+await mailer.send(new WelcomeEmail(user))
+await mailer.sendBulk([new WelcomeEmail(u1), new WelcomeEmail(u2)])
+```
+
+### MailServiceProvider
+
+```ts
+export class AppMailServiceProvider extends MailServiceProvider {
+  protected config = {
+    driver: process.env.MAIL_DRIVER as MailDriver,
+    from: { name: 'Pearl App', address: process.env.MAIL_FROM! },
+    smtp: {
+      host:  process.env.MAIL_HOST!,
+      port:  Number(process.env.MAIL_PORT),
+      auth:  { user: process.env.MAIL_USER!, pass: process.env.MAIL_PASS! },
+    },
+  }
+}
+```
+
+### Transports
+
+| Transport | Use case |
+|-----------|---------|
+| `SmtpTransport` | Production SMTP (Mailgun, Postmark, etc.) |
+| `SesTransport` | AWS SES |
+| `LogTransport` | Development — logs to console |
+| `ArrayTransport` | Testing — captures emails in memory |
+
+---

package/dist/Mailer.d.ts

@@ -0,0 +1,14 @@
+import type { MailTransport } from './transports/index.js';
+import type { Mailable, MailAddress } from './mail/Mailable.js';
+export interface MailerConfig {
+    from?: MailAddress | string;
+    transport: MailTransport;
+}
+export declare class Mailer {
+    private readonly config;
+    constructor(config: MailerConfig);
+    send(mailable: Mailable): Promise<void>;
+    sendBulk(mailables: Mailable[]): Promise<void>;
+    get transport(): MailTransport;
+}
+//# sourceMappingURL=Mailer.d.ts.map

package/dist/Mailer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mailer.d.ts","sourceRoot":"","sources":["../src/Mailer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAE/D,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC3B,SAAS,EAAE,aAAa,CAAA;CAC3B;AAED,qBAAa,MAAM;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,YAAY;IAI3C,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD,IAAI,SAAS,IAAI,aAAa,CAE7B;CACJ"}

package/dist/Mailer.js

@@ -0,0 +1,19 @@
+export class Mailer {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    // ─── Sending ──────────────────────────────────────────────────────────────
+    async send(mailable) {
+        const mail = await mailable.compile(this.config.from);
+        await this.config.transport.send(mail);
+    }
+    async sendBulk(mailables) {
+        await Promise.all(mailables.map((m) => this.send(m)));
+    }
+    // ─── Transport access ─────────────────────────────────────────────────────
+    get transport() {
+        return this.config.transport;
+    }
+}
+//# sourceMappingURL=Mailer.js.map

package/dist/Mailer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mailer.js","sourceRoot":"","sources":["../src/Mailer.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,MAAM;IACc;IAA7B,YAA6B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAErD,6EAA6E;IAE7E,KAAK,CAAC,IAAI,CAAC,QAAkB;QACzB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACrD,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC1C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,SAAqB;QAChC,MAAM,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACzD,CAAC;IAED,6EAA6E;IAE7E,IAAI,SAAS;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAA;IAChC,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { Mailable } from './mail/Mailable.js';
+export type { MailAddress, MailEnvelope, MailContent, BuiltMail } from './mail/Mailable.js';
+export { Mailer } from './Mailer.js';
+export type { MailerConfig } from './Mailer.js';
+export { SmtpTransport, LogTransport, ArrayTransport, SesTransport } from './transports/index.js';
+export type { MailTransport, SmtpConfig, SesConfig } from './transports/index.js';
+export { MailServiceProvider } from './providers/MailServiceProvider.js';
+export type { MailServiceConfig, MailDriver } from './providers/MailServiceProvider.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":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE3F,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACjG,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Mailable } from './mail/Mailable.js';
+export { Mailer } from './Mailer.js';
+export { SmtpTransport, LogTransport, ArrayTransport, SesTransport } from './transports/index.js';
+export { MailServiceProvider } from './providers/MailServiceProvider.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAG7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGjG,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA"}

package/dist/mail/Mailable.d.ts

@@ -0,0 +1,73 @@
+import type { Attachment } from 'nodemailer/lib/mailer/index.js';
+export interface MailAddress {
+    name?: string;
+    address: string;
+}
+export interface MailEnvelope {
+    from?: MailAddress | string;
+    to: Array<MailAddress | string>;
+    cc?: Array<MailAddress | string>;
+    bcc?: Array<MailAddress | string>;
+    replyTo?: MailAddress | string;
+    subject: string;
+}
+export interface MailContent {
+    html?: string;
+    text?: string;
+    attachments?: Attachment[];
+}
+export interface BuiltMail extends MailContent {
+    from?: MailAddress | string;
+    to: Array<MailAddress | string>;
+    cc?: Array<MailAddress | string>;
+    bcc?: Array<MailAddress | string>;
+    replyTo?: MailAddress | string;
+    subject: string;
+}
+/**
+ * Base class for all Pearl mailables.
+ *
+ * Usage:
+ *   export class WelcomeEmail extends Mailable {
+ *     constructor(private readonly user: User) {
+ *       super()
+ *     }
+ *
+ *     build(): this {
+ *       return this
+ *         .to(this.user.email)
+ *         .subject('Welcome to Pearl!')
+ *         .html(`<h1>Hi ${this.user.name}!</h1>`)
+ *     }
+ *   }
+ */
+export declare abstract class Mailable {
+    private _from?;
+    private _to;
+    private _cc;
+    private _bcc;
+    private _replyTo?;
+    private _subject;
+    private _html?;
+    private _text?;
+    private _attachments;
+    from(address: MailAddress | string): this;
+    to(...addresses: Array<MailAddress | string>): this;
+    cc(...addresses: Array<MailAddress | string>): this;
+    bcc(...addresses: Array<MailAddress | string>): this;
+    replyTo(address: MailAddress | string): this;
+    subject(value: string): this;
+    html(content: string): this;
+    text(content: string): this;
+    attach(attachment: Attachment): this;
+    /**
+     * Implement this to configure the email.
+     * Call this.to(), this.subject(), this.html() etc.
+     */
+    abstract build(): this | Promise<this>;
+    compile(defaultFrom?: MailAddress | string): Promise<BuiltMail>;
+    /** Override to send via queue instead of synchronously */
+    shouldQueue(): boolean;
+    get queue(): string;
+}
+//# sourceMappingURL=Mailable.d.ts.map

package/dist/mail/Mailable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mailable.d.ts","sourceRoot":"","sources":["../../src/mail/Mailable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAA;AAEhE,MAAM,WAAW,WAAW;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC3B,EAAE,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAA;IAC/B,EAAE,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAA;IAChC,GAAG,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC9B,OAAO,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC1C,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC3B,EAAE,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAA;IAC/B,EAAE,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAA;IAChC,GAAG,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,CAAA;IACjC,OAAO,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC9B,OAAO,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,QAAQ;IAC1B,OAAO,CAAC,KAAK,CAAC,CAAsB;IACpC,OAAO,CAAC,GAAG,CAAkC;IAC7C,OAAO,CAAC,GAAG,CAAkC;IAC7C,OAAO,CAAC,IAAI,CAAkC;IAC9C,OAAO,CAAC,QAAQ,CAAC,CAAsB;IACvC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAC,CAAQ;IACtB,OAAO,CAAC,YAAY,CAAmB;IAIvC,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAKzC,EAAE,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,IAAI;IAKnD,EAAE,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,IAAI;IAKnD,GAAG,CAAC,GAAG,SAAS,EAAE,KAAK,CAAC,WAAW,GAAG,MAAM,CAAC,GAAG,IAAI;IAKpD,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI;IAK5C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK5B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK3B,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI;IAOpC;;;OAGG;IACH,QAAQ,CAAC,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEhC,OAAO,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAoBrE,0DAA0D;IAC1D,WAAW,IAAI,OAAO;IAItB,IAAI,KAAK,IAAI,MAAM,CAElB;CACJ"}

package/dist/mail/Mailable.js

@@ -0,0 +1,89 @@
+/**
+ * Base class for all Pearl mailables.
+ *
+ * Usage:
+ *   export class WelcomeEmail extends Mailable {
+ *     constructor(private readonly user: User) {
+ *       super()
+ *     }
+ *
+ *     build(): this {
+ *       return this
+ *         .to(this.user.email)
+ *         .subject('Welcome to Pearl!')
+ *         .html(`<h1>Hi ${this.user.name}!</h1>`)
+ *     }
+ *   }
+ */
+export class Mailable {
+    _from;
+    _to = [];
+    _cc = [];
+    _bcc = [];
+    _replyTo;
+    _subject = '';
+    _html;
+    _text;
+    _attachments = [];
+    // ─── Builder methods ──────────────────────────────────────────────────────
+    from(address) {
+        this._from = address;
+        return this;
+    }
+    to(...addresses) {
+        this._to.push(...addresses);
+        return this;
+    }
+    cc(...addresses) {
+        this._cc.push(...addresses);
+        return this;
+    }
+    bcc(...addresses) {
+        this._bcc.push(...addresses);
+        return this;
+    }
+    replyTo(address) {
+        this._replyTo = address;
+        return this;
+    }
+    subject(value) {
+        this._subject = value;
+        return this;
+    }
+    html(content) {
+        this._html = content;
+        return this;
+    }
+    text(content) {
+        this._text = content;
+        return this;
+    }
+    attach(attachment) {
+        this._attachments.push(attachment);
+        return this;
+    }
+    async compile(defaultFrom) {
+        await this.build();
+        const from = this._from ?? defaultFrom;
+        return {
+            ...(from !== undefined && { from }),
+            to: this._to,
+            ...(this._cc.length && { cc: this._cc }),
+            ...(this._bcc.length && { bcc: this._bcc }),
+            ...(this._replyTo !== undefined && { replyTo: this._replyTo }),
+            subject: this._subject,
+            ...(this._html !== undefined && { html: this._html }),
+            ...(this._text !== undefined && { text: this._text }),
+            ...(this._attachments.length && { attachments: this._attachments }),
+        };
+    }
+    // ─── Queue support ────────────────────────────────────────────────────────
+    /** Override to send via queue instead of synchronously */
+    shouldQueue() {
+        return false;
+    }
+    get queue() {
+        return 'mail';
+    }
+}
+//# sourceMappingURL=Mailable.js.map

package/dist/mail/Mailable.js.map

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

package/dist/providers/MailServiceProvider.d.ts

@@ -0,0 +1,32 @@
+import { ServiceProvider } from '@pearl-framework/core';
+import { type SmtpConfig } from '../transports/index.js';
+import type { MailAddress } from '../mail/Mailable.js';
+export type MailDriver = 'smtp' | 'log' | 'array';
+export interface MailServiceConfig {
+    driver: MailDriver;
+    from?: MailAddress | string;
+    smtp?: SmtpConfig;
+}
+/**
+ * MailServiceProvider registers the Mailer into the container.
+ *
+ * Usage — extend this in your app:
+ *
+ *   export class AppMailServiceProvider extends MailServiceProvider {
+ *     protected config: MailServiceConfig = {
+ *       driver: env('MAIL_DRIVER') as MailDriver,
+ *       from: { name: 'Pearl App', address: env('MAIL_FROM') },
+ *       smtp: {
+ *         host: env('MAIL_HOST'),
+ *         port: env.number('MAIL_PORT'),
+ *         auth: { user: env('MAIL_USER'), pass: env('MAIL_PASS') },
+ *       },
+ *     }
+ *   }
+ */
+export declare class MailServiceProvider extends ServiceProvider {
+    protected config: MailServiceConfig;
+    register(): void;
+    private resolveTransport;
+}
+//# sourceMappingURL=MailServiceProvider.d.ts.map

package/dist/providers/MailServiceProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MailServiceProvider.d.ts","sourceRoot":"","sources":["../../src/providers/MailServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAA;AAEjD,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAA;IAC3B,IAAI,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACpD,SAAS,CAAC,MAAM,EAAE,iBAAiB,CAElC;IAED,QAAQ,IAAI,IAAI;IAUhB,OAAO,CAAC,gBAAgB;CAe3B"}

package/dist/providers/MailServiceProvider.js

@@ -0,0 +1,50 @@
+import { ServiceProvider } from '@pearl-framework/core';
+import { Mailer } from '../Mailer.js';
+import { SmtpTransport, LogTransport, ArrayTransport, } from '../transports/index.js';
+/**
+ * MailServiceProvider registers the Mailer into the container.
+ *
+ * Usage — extend this in your app:
+ *
+ *   export class AppMailServiceProvider extends MailServiceProvider {
+ *     protected config: MailServiceConfig = {
+ *       driver: env('MAIL_DRIVER') as MailDriver,
+ *       from: { name: 'Pearl App', address: env('MAIL_FROM') },
+ *       smtp: {
+ *         host: env('MAIL_HOST'),
+ *         port: env.number('MAIL_PORT'),
+ *         auth: { user: env('MAIL_USER'), pass: env('MAIL_PASS') },
+ *       },
+ *     }
+ *   }
+ */
+export class MailServiceProvider extends ServiceProvider {
+    config = {
+        driver: 'log',
+    };
+    register() {
+        this.container.singleton(Mailer, () => {
+            const transport = this.resolveTransport();
+            return new Mailer({
+                transport,
+                ...(this.config.from !== undefined && { from: this.config.from }),
+            });
+        });
+    }
+    resolveTransport() {
+        switch (this.config.driver) {
+            case 'smtp': {
+                if (!this.config.smtp) {
+                    throw new Error('SMTP config is required when using the smtp mail driver.');
+                }
+                return new SmtpTransport(this.config.smtp);
+            }
+            case 'array':
+                return new ArrayTransport();
+            case 'log':
+            default:
+                return new LogTransport();
+        }
+    }
+}
+//# sourceMappingURL=MailServiceProvider.js.map

package/dist/providers/MailServiceProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MailServiceProvider.js","sourceRoot":"","sources":["../../src/providers/MailServiceProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AACrC,OAAO,EACH,aAAa,EACb,YAAY,EACZ,cAAc,GAGjB,MAAM,wBAAwB,CAAA;AAW/B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,mBAAoB,SAAQ,eAAe;IAC1C,MAAM,GAAsB;QAClC,MAAM,EAAE,KAAK;KAChB,CAAA;IAED,QAAQ;QACJ,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE;YACtC,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAA;YACzC,OAAO,IAAI,MAAM,CAAC;gBACd,SAAS;gBACT,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;aACpE,CAAC,CAAA;QACF,CAAC,CAAC,CAAA;IACN,CAAC;IAEO,gBAAgB;QACpB,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC7B,KAAK,MAAM,CAAC,CAAC,CAAC;gBACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;oBACxB,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAA;gBAC3E,CAAC;gBACD,OAAO,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YAC9C,CAAC;YACD,KAAK,OAAO;gBACR,OAAO,IAAI,cAAc,EAAE,CAAA;YAC/B,KAAK,KAAK,CAAC;YACX;gBACI,OAAO,IAAI,YAAY,EAAE,CAAA;QAC7B,CAAC;IACL,CAAC;CACJ"}

package/dist/transports/index.d.ts

@@ -0,0 +1,38 @@
+import type { BuiltMail } from '../mail/Mailable.js';
+export interface MailTransport {
+    send(mail: BuiltMail): Promise<void>;
+}
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+}
+export declare class SmtpTransport implements MailTransport {
+    private readonly config;
+    constructor(config: SmtpConfig);
+    send(mail: BuiltMail): Promise<void>;
+}
+export interface SesConfig {
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+export declare class SesTransport implements MailTransport {
+    private readonly config;
+    constructor(config: SesConfig);
+    send(mail: BuiltMail): Promise<void>;
+}
+export declare class LogTransport implements MailTransport {
+    send(mail: BuiltMail): Promise<void>;
+}
+export declare class ArrayTransport implements MailTransport {
+    readonly sent: BuiltMail[];
+    send(mail: BuiltMail): Promise<void>;
+    clear(): void;
+    last(): BuiltMail | undefined;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/transports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transports/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,qBAAqB,CAAA;AAEjE,MAAM,WAAW,aAAa;IAC1B,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC;AAOD,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CACxC;AAED,qBAAa,aAAc,YAAW,aAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAEzC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAqB7C;AAED,MAAM,WAAW,SAAS;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;CAC1B;AAED,qBAAa,YAAa,YAAW,aAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAExC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAuB7C;AAED,qBAAa,YAAa,YAAW,aAAa;IACxC,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAS7C;AAEG,qBAAa,cAAe,YAAW,aAAa;IACpD,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,CAAK;IACzB,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1C,KAAK,IAAI,IAAI;IACb,IAAI,IAAI,SAAS,GAAG,SAAS;CAChC"}

package/dist/transports/index.js

@@ -0,0 +1,80 @@
+function toNodemailerAddress(addr) {
+    if (typeof addr === 'string')
+        return addr;
+    return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address;
+}
+export class SmtpTransport {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async send(mail) {
+        const nodemailer = await import('nodemailer');
+        const transporter = nodemailer.createTransport({
+            host: this.config.host,
+            port: this.config.port,
+            secure: this.config.secure ?? this.config.port === 465,
+            ...(this.config.auth !== undefined && { auth: this.config.auth }),
+        });
+        await transporter.sendMail({
+            ...(mail.from !== undefined && { from: toNodemailerAddress(mail.from) }),
+            to: mail.to.map(toNodemailerAddress).join(', '),
+            ...(mail.cc !== undefined && { cc: mail.cc.map(toNodemailerAddress).join(', ') }),
+            ...(mail.bcc !== undefined && { bcc: mail.bcc.map(toNodemailerAddress).join(', ') }),
+            ...(mail.replyTo !== undefined && { replyTo: toNodemailerAddress(mail.replyTo) }),
+            subject: mail.subject,
+            ...(mail.html !== undefined && { html: mail.html }),
+            ...(mail.text !== undefined && { text: mail.text }),
+            ...(mail.attachments !== undefined && { attachments: mail.attachments }),
+        });
+    }
+}
+export class SesTransport {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async send(mail) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const aws = await import('@aws-sdk/client-ses');
+        const client = new aws.SESClient({
+            region: this.config.region,
+            credentials: {
+                accessKeyId: this.config.accessKeyId,
+                secretAccessKey: this.config.secretAccessKey,
+            },
+        });
+        const toAddresses = mail.to.map((a) => typeof a === 'string' ? a : a.address);
+        await client.send(new aws.SendEmailCommand({
+            Source: mail.from ? toNodemailerAddress(mail.from) : '',
+            Destination: { ToAddresses: toAddresses },
+            Message: {
+                Subject: { Data: mail.subject },
+                Body: {
+                    ...(mail.html !== undefined && { Html: { Data: mail.html } }),
+                    ...(mail.text !== undefined && { Text: { Data: mail.text } }),
+                },
+            },
+        }));
+    }
+}
+export class LogTransport {
+    async send(mail) {
+        console.log('\n📧 [Pearl Mail — LogTransport]');
+        console.log('  From:   ', mail.from);
+        console.log('  To:     ', mail.to);
+        console.log('  Subject:', mail.subject);
+        if (mail.html)
+            console.log('  HTML:   ', mail.html.slice(0, 100) + '...');
+        if (mail.text)
+            console.log('  Text:   ', mail.text.slice(0, 100) + '...');
+        console.log('');
+    }
+}
+export class ArrayTransport {
+    sent = [];
+    async send(mail) { this.sent.push(mail); }
+    clear() { this.sent.length = 0; }
+    last() { return this.sent[this.sent.length - 1]; }
+}
+//# sourceMappingURL=index.js.map

package/dist/transports/index.js.map

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@pearl-framework/mail",
+  "version": "0.1.0",
+  "description": "Pearl.js mail — Nodemailer-powered mailable classes, transports, and queue support",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "nodemailer": "^6.9.0",
+    "@pearl-framework/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/nodemailer": "^6.4.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skd09/pearl.js.git",
+    "directory": "packages/mail"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/Mailer.ts

@@ -0,0 +1,28 @@
+import type { MailTransport } from './transports/index.js'
+import type { Mailable, MailAddress } from './mail/Mailable.js'
+
+export interface MailerConfig {
+    from?: MailAddress | string
+    transport: MailTransport
+}
+
+export class Mailer {
+    constructor(private readonly config: MailerConfig) {}
+
+    // ─── Sending ──────────────────────────────────────────────────────────────
+
+    async send(mailable: Mailable): Promise<void> {
+        const mail = await mailable.compile(this.config.from)
+        await this.config.transport.send(mail)
+    }
+
+    async sendBulk(mailables: Mailable[]): Promise<void> {
+        await Promise.all(mailables.map((m) => this.send(m)))
+    }
+
+    // ─── Transport access ─────────────────────────────────────────────────────
+
+    get transport(): MailTransport {
+        return this.config.transport
+    }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Mailable } from './mail/Mailable.js'
+export type { MailAddress, MailEnvelope, MailContent, BuiltMail } from './mail/Mailable.js'
+
+export { Mailer } from './Mailer.js'
+export type { MailerConfig } from './Mailer.js'
+
+export { SmtpTransport, LogTransport, ArrayTransport, SesTransport } from './transports/index.js'
+export type { MailTransport, SmtpConfig, SesConfig } from './transports/index.js'
+
+export { MailServiceProvider } from './providers/MailServiceProvider.js'
+export type { MailServiceConfig, MailDriver } from './providers/MailServiceProvider.js'

package/src/mail/Mailable.ts

@@ -0,0 +1,143 @@
+import type { Attachment } from 'nodemailer/lib/mailer/index.js'
+
+export interface MailAddress {
+    name?: string
+    address: string
+}
+
+export interface MailEnvelope {
+    from?: MailAddress | string
+    to: Array<MailAddress | string>
+    cc?: Array<MailAddress | string>
+    bcc?: Array<MailAddress | string>
+    replyTo?: MailAddress | string
+    subject: string
+}
+
+export interface MailContent {
+    html?: string
+    text?: string
+    attachments?: Attachment[]
+}
+
+export interface BuiltMail extends MailContent {
+    from?: MailAddress | string
+    to: Array<MailAddress | string>
+    cc?: Array<MailAddress | string>
+    bcc?: Array<MailAddress | string>
+    replyTo?: MailAddress | string
+    subject: string
+}
+
+/**
+ * Base class for all Pearl mailables.
+ *
+ * Usage:
+ *   export class WelcomeEmail extends Mailable {
+ *     constructor(private readonly user: User) {
+ *       super()
+ *     }
+ *
+ *     build(): this {
+ *       return this
+ *         .to(this.user.email)
+ *         .subject('Welcome to Pearl!')
+ *         .html(`<h1>Hi ${this.user.name}!</h1>`)
+ *     }
+ *   }
+ */
+export abstract class Mailable {
+    private _from?: MailAddress | string
+    private _to: Array<MailAddress | string> = []
+    private _cc: Array<MailAddress | string> = []
+    private _bcc: Array<MailAddress | string> = []
+    private _replyTo?: MailAddress | string
+    private _subject = ''
+    private _html?: string
+    private _text?: string
+    private _attachments: Attachment[] = []
+
+    // ─── Builder methods ──────────────────────────────────────────────────────
+
+    from(address: MailAddress | string): this {
+        this._from = address
+        return this
+    }
+
+    to(...addresses: Array<MailAddress | string>): this {
+        this._to.push(...addresses)
+        return this
+    }
+
+    cc(...addresses: Array<MailAddress | string>): this {
+        this._cc.push(...addresses)
+        return this
+    }
+
+    bcc(...addresses: Array<MailAddress | string>): this {
+        this._bcc.push(...addresses)
+        return this
+    }
+
+    replyTo(address: MailAddress | string): this {
+        this._replyTo = address
+        return this
+    }
+
+    subject(value: string): this {
+        this._subject = value
+        return this
+    }
+
+    html(content: string): this {
+        this._html = content
+        return this
+    }
+
+    text(content: string): this {
+        this._text = content
+        return this
+    }
+
+    attach(attachment: Attachment): this {
+        this._attachments.push(attachment)
+        return this
+    }
+
+    // ─── Build ────────────────────────────────────────────────────────────────
+
+    /**
+     * Implement this to configure the email.
+     * Call this.to(), this.subject(), this.html() etc.
+     */
+    abstract build(): this | Promise<this>
+
+    async compile(defaultFrom?: MailAddress | string): Promise<BuiltMail> {
+        await this.build()
+
+        const from = this._from ?? defaultFrom
+
+        return {
+            ...(from !== undefined && { from }),
+            to: this._to,
+            ...(this._cc.length && { cc: this._cc }),
+            ...(this._bcc.length && { bcc: this._bcc }),
+            ...(this._replyTo !== undefined && { replyTo: this._replyTo }),
+            subject: this._subject,
+            ...(this._html !== undefined && { html: this._html }),
+            ...(this._text !== undefined && { text: this._text }),
+            ...(this._attachments.length && { attachments: this._attachments }),
+        }
+    }
+
+    // ─── Queue support ────────────────────────────────────────────────────────
+
+    /** Override to send via queue instead of synchronously */
+    shouldQueue(): boolean {
+        return false
+    }
+
+    get queue(): string {
+        return 'mail'
+    }
+}

package/src/providers/MailServiceProvider.ts

@@ -0,0 +1,67 @@
+import { ServiceProvider } from '@pearl-framework/core'
+import { Mailer } from '../Mailer.js'
+import {
+    SmtpTransport,
+    LogTransport,
+    ArrayTransport,
+    type MailTransport,
+    type SmtpConfig,
+} from '../transports/index.js'
+import type { MailAddress } from '../mail/Mailable.js'
+
+export type MailDriver = 'smtp' | 'log' | 'array'
+
+export interface MailServiceConfig {
+    driver: MailDriver
+    from?: MailAddress | string
+    smtp?: SmtpConfig
+}
+
+/**
+ * MailServiceProvider registers the Mailer into the container.
+ *
+ * Usage — extend this in your app:
+ *
+ *   export class AppMailServiceProvider extends MailServiceProvider {
+ *     protected config: MailServiceConfig = {
+ *       driver: env('MAIL_DRIVER') as MailDriver,
+ *       from: { name: 'Pearl App', address: env('MAIL_FROM') },
+ *       smtp: {
+ *         host: env('MAIL_HOST'),
+ *         port: env.number('MAIL_PORT'),
+ *         auth: { user: env('MAIL_USER'), pass: env('MAIL_PASS') },
+ *       },
+ *     }
+ *   }
+ */
+export class MailServiceProvider extends ServiceProvider {
+    protected config: MailServiceConfig = {
+        driver: 'log',
+    }
+
+    register(): void {
+        this.container.singleton(Mailer, () => {
+        const transport = this.resolveTransport()
+        return new Mailer({
+            transport,
+            ...(this.config.from !== undefined && { from: this.config.from }),
+        })
+        })
+    }
+
+    private resolveTransport(): MailTransport {
+        switch (this.config.driver) {
+        case 'smtp': {
+            if (!this.config.smtp) {
+            throw new Error('SMTP config is required when using the smtp mail driver.')
+            }
+            return new SmtpTransport(this.config.smtp)
+        }
+        case 'array':
+            return new ArrayTransport()
+        case 'log':
+        default:
+            return new LogTransport()
+        }
+    }
+}

package/src/transports/index.ts

@@ -0,0 +1,96 @@
+import type { BuiltMail, MailAddress } from '../mail/Mailable.js'
+
+export interface MailTransport {
+    send(mail: BuiltMail): Promise<void>
+}
+
+function toNodemailerAddress(addr: MailAddress | string): string {
+    if (typeof addr === 'string') return addr
+    return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address
+}
+
+export interface SmtpConfig {
+    host: string
+    port: number
+    secure?: boolean
+    auth?: { user: string; pass: string }
+}
+
+export class SmtpTransport implements MailTransport {
+    constructor(private readonly config: SmtpConfig) {}
+
+    async send(mail: BuiltMail): Promise<void> {
+        const nodemailer = await import('nodemailer')
+        const transporter = nodemailer.createTransport({
+            host: this.config.host,
+            port: this.config.port,
+            secure: this.config.secure ?? this.config.port === 465,
+            ...(this.config.auth !== undefined && { auth: this.config.auth }),
+        })
+
+        await transporter.sendMail({
+            ...(mail.from !== undefined && { from: toNodemailerAddress(mail.from) }),
+            to: mail.to.map(toNodemailerAddress).join(', '),
+            ...(mail.cc !== undefined && { cc: mail.cc.map(toNodemailerAddress).join(', ') }),
+            ...(mail.bcc !== undefined && { bcc: mail.bcc.map(toNodemailerAddress).join(', ') }),
+            ...(mail.replyTo !== undefined && { replyTo: toNodemailerAddress(mail.replyTo) }),
+            subject: mail.subject,
+            ...(mail.html !== undefined && { html: mail.html }),
+            ...(mail.text !== undefined && { text: mail.text }),
+            ...(mail.attachments !== undefined && { attachments: mail.attachments }),
+        })
+    }
+}
+
+export interface SesConfig {
+    region: string
+    accessKeyId: string
+    secretAccessKey: string
+}
+
+export class SesTransport implements MailTransport {
+    constructor(private readonly config: SesConfig) {}
+
+    async send(mail: BuiltMail): Promise<void> {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const aws = await import('@aws-sdk/client-ses' as string) as any
+        const client = new aws.SESClient({
+        region: this.config.region,
+        credentials: {
+            accessKeyId: this.config.accessKeyId,
+            secretAccessKey: this.config.secretAccessKey,
+        },
+        })
+        const toAddresses = mail.to.map((a) => typeof a === 'string' ? a : a.address)
+        await client.send(new aws.SendEmailCommand({
+        Source: mail.from ? toNodemailerAddress(mail.from) : '',
+        Destination: { ToAddresses: toAddresses },
+        Message: {
+            Subject: { Data: mail.subject },
+            Body: {
+            ...(mail.html !== undefined && { Html: { Data: mail.html } }),
+            ...(mail.text !== undefined && { Text: { Data: mail.text } }),
+            },
+        },
+        }))
+    }
+}
+
+export class LogTransport implements MailTransport {
+    async send(mail: BuiltMail): Promise<void> {
+        console.log('\n📧 [Pearl Mail — LogTransport]')
+        console.log('  From:   ', mail.from)
+        console.log('  To:     ', mail.to)
+        console.log('  Subject:', mail.subject)
+        if (mail.html) console.log('  HTML:   ', mail.html.slice(0, 100) + '...')
+        if (mail.text) console.log('  Text:   ', mail.text.slice(0, 100) + '...')
+        console.log('')
+    }
+}
+
+    export class ArrayTransport implements MailTransport {
+    readonly sent: BuiltMail[] = []
+    async send(mail: BuiltMail): Promise<void> { this.sent.push(mail) }
+    clear(): void { this.sent.length = 0 }
+    last(): BuiltMail | undefined { return this.sent[this.sent.length - 1] }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+}