@xacos/mail 1.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,qBAAqB,CAAC"}

package/dist/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/dist/index.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it, spyOn } from "bun:test";
+import { LogMailer } from "./index";
+describe("LogMailer", () => {
+    it("renders templates with data", async () => {
+        const mailer = new LogMailer();
+        const logSpy = spyOn(console, "log");
+        await mailer.send({
+            to: "test@example.com",
+            subject: "Hello {{ name }}",
+            text: "Welcome to {{ app }}",
+            data: { name: "Alice", app: "XAOCS" }
+        });
+        expect(logSpy).toHaveBeenCalledWith("Subject:", "Hello Alice");
+        expect(logSpy).toHaveBeenCalledWith("Text:   ", "Welcome to XAOCS");
+        logSpy.mockRestore();
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,6BAA6B,EAAE,KAAK,IAAI,EAAE;QAC3C,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAErC,MAAM,MAAM,CAAC,IAAI,CAAC;YAChB,EAAE,EAAE,kBAAkB;YACtB,OAAO,EAAE,kBAAkB;YAC3B,IAAI,EAAE,sBAAsB;YAC5B,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE;SACtC,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;QAC/D,MAAM,CAAC,MAAM,CAAC,CAAC,oBAAoB,CAAC,UAAU,EAAE,kBAAkB,CAAC,CAAC;QAGpE,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/utils/interpolate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Simple string interpolation utility for XAOCS templates.
+ * Replaces {{ variable }} with values from the data object.
+ */
+export declare function interpolate(template: string, data: Record<string, any>): string;
+//# sourceMappingURL=interpolate.d.ts.map

package/dist/utils/interpolate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.d.ts","sourceRoot":"","sources":["../../src/utils/interpolate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAI/E"}

package/dist/utils/interpolate.js

@@ -0,0 +1,10 @@
+/**
+ * Simple string interpolation utility for XAOCS templates.
+ * Replaces {{ variable }} with values from the data object.
+ */
+export function interpolate(template, data) {
+    return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key) => {
+        return data[key]?.toString() ?? match;
+    });
+}
+//# sourceMappingURL=interpolate.js.map

package/dist/utils/interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpolate.js","sourceRoot":"","sources":["../../src/utils/interpolate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,IAAyB;IACrE,OAAO,QAAQ,CAAC,OAAO,CAAC,sBAAsB,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC7D,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,IAAI,KAAK,CAAC;IACxC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@xacos/mail",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-ses": "^3.1048.0",
+    "@xacos/config": "workspace:*",
+    "@xacos/shared": "workspace:*",
+    "form-data": "^4.0.5",
+    "mailgun.js": "^13.0.1",
+    "nodemailer": "^8.0.7",
+    "postmark": "^4.0.7",
+    "resend": "^6.12.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@types/nodemailer": "^8.0.0",
+    "bun-types": "^1.3.12",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test src",
+    "type-check": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "author": "XAOCS Team",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zoherr/xaocs.git",
+    "directory": "packages/mail"
+  },
+  "homepage": "https://xaocs.dev",
+  "bugs": {
+    "url": "https://github.com/zoherr/xaocs/issues"
+  },
+  "keywords": [
+    "xaocs",
+    "xacos",
+    "framework",
+    "typescript",
+    "fullstack",
+    "fastify",
+    "react",
+    "email",
+    "smtp",
+    "ses",
+    "mailgun",
+    "resend",
+    "postmark"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": false
+  },
+  "engines": {
+    "bun": ">=1.0.0",
+    "node": ">=18.0.0"
+  }
+}

package/src/MailManager.ts

@@ -0,0 +1,76 @@
+import type { XacosConfig } from '@xacos/config';
+import type { Mailer, MailMessage, MailResult } from './Mailer';
+import { LogMailer } from './drivers/LogMailer';
+import { SmtpMailer } from './drivers/SmtpMailer';
+import { SesMailer } from './drivers/SesMailer';
+import { MailgunMailer } from './drivers/MailgunMailer';
+import { PostmarkMailer } from './drivers/PostmarkMailer';
+import { ResendMailer } from './drivers/ResendMailer';
+
+
+export class MailManager {
+  private mailer: Mailer | null = null;
+
+  constructor(private config: XacosConfig['mail'] = {}) {}
+
+  getMailer(): Mailer {
+    if (this.mailer) return this.mailer;
+
+    const config = this.config ?? {};
+    const driver = config.driver ?? 'log';
+
+    switch (driver) {
+      case 'smtp':
+        this.mailer = new SmtpMailer({
+          host: config.host ?? 'localhost',
+          port: config.port ?? 587,
+          user: config.user ?? '',
+          pass: config.pass ?? '',
+          from: config.from ?? 'noreply@xacos.dev',
+        });
+        break;
+      case 'ses':
+        if (!config.ses) throw new Error('[XAOCS Mail] SES config missing');
+        this.mailer = new SesMailer({
+          region: config.ses.region ?? 'us-east-1',
+          key: config.ses.key ?? '',
+          secret: config.ses.secret ?? '',
+          from: config.from ?? 'noreply@xacos.dev',
+        });
+        break;
+      case 'mailgun':
+        this.mailer = new MailgunMailer({
+          apiKey: process.env['MAILGUN_API_KEY'] ?? '',
+          domain: process.env['MAILGUN_DOMAIN'] ?? '',
+          from: config.from ?? 'noreply@xacos.dev',
+          host: process.env['MAILGUN_HOST'] ?? undefined,
+        });
+        break;
+
+      case 'postmark':
+        this.mailer = new PostmarkMailer({
+          serverToken: process.env['POSTMARK_SERVER_TOKEN'] ?? '',
+          from: config.from ?? 'noreply@xacos.dev',
+        });
+        break;
+      case 'resend':
+        this.mailer = new ResendMailer({
+          apiKey: process.env['RESEND_API_KEY'] ?? '',
+          from: config.from ?? 'noreply@xacos.dev',
+        });
+        break;
+
+      case 'log':
+      default:
+        this.mailer = new LogMailer(config.from);
+        break;
+    }
+
+    return this.mailer;
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    return this.getMailer().send(message);
+  }
+}
+

package/src/Mailer.ts

@@ -0,0 +1,22 @@
+export interface MailMessage {
+  from?: string;
+  to: string | string[];
+  subject: string;
+  template?: string;
+  data?: Record<string, any>;
+  text?: string;
+  html?: string;
+}
+
+export interface MailResult {
+  success: boolean;
+  messageId?: string | undefined;
+  error?: string | undefined;
+  provider: string;
+}
+
+
+export abstract class Mailer {
+  abstract send(message: MailMessage): Promise<MailResult>;
+}
+

package/src/drivers/LogMailer.ts

@@ -0,0 +1,29 @@
+import type { Mailer, MailMessage, MailResult } from '../Mailer';
+import { interpolate } from '../utils/interpolate';
+
+export class LogMailer implements Mailer {
+  constructor(private from: string = 'noreply@xacos.dev') {
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const subject = interpolate(message.subject, message.data ?? {});
+    const text = message.text ? interpolate(message.text, message.data ?? {}) : undefined;
+    const html = message.template 
+      ? interpolate(message.template, message.data ?? {}) 
+      : (message.html ? interpolate(message.html, message.data ?? {}) : undefined);
+
+    console.log('\n--- [MAIL LOG] ---');
+    console.log('From:   ', message.from ?? this.from);
+    console.log('To:     ', message.to);
+    console.log('Subject:', subject);
+    if (text) console.log('Text:   ', text);
+    if (html) console.log('HTML:   ', '[Rendered HTML Content]');
+    console.log('------------------\n');
+
+    return {
+      success: true,
+      provider: 'log',
+    };
+  }
+}
+

package/src/drivers/MailgunMailer.ts

@@ -0,0 +1,56 @@
+import Mailgun from 'mailgun.js';
+import FormData from 'form-data';
+import type { Mailer, MailMessage, MailResult } from '../Mailer';
+import { interpolate } from '../utils/interpolate';
+
+export interface MailgunConfig {
+  apiKey: string;
+  domain: string;
+  from: string;
+  host?: string | undefined; // default: 'api.mailgun.net', use 'api.eu.mailgun.net' for EU
+}
+
+export class MailgunMailer implements Mailer {
+  private client: ReturnType<InstanceType<typeof Mailgun>['client']>;
+  private config: MailgunConfig;
+
+  constructor(config: MailgunConfig) {
+    this.config = config;
+    const mg = new Mailgun(FormData);
+    this.client = mg.client({
+      username: 'api',
+      key: config.apiKey,
+      url: config.host ?? 'https://api.mailgun.net',
+    });
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const html = message.template
+      ? interpolate(message.template, message.data ?? {})
+      : message.html ?? '';
+
+    try {
+      const response = await this.client.messages.create(this.config.domain, {
+        from: message.from ?? this.config.from,
+        to: Array.isArray(message.to) ? message.to : [message.to],
+        subject: message.subject,
+        html,
+        text: message.text,
+      } as any);
+
+
+      return {
+        success: true,
+        messageId: response.id,
+        provider: 'mailgun',
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+        provider: 'mailgun',
+      };
+    }
+  }
+}
+

package/src/drivers/PostmarkMailer.ts

@@ -0,0 +1,53 @@
+import { ServerClient } from 'postmark';
+import type { Mailer, MailMessage, MailResult } from '../Mailer';
+import { interpolate } from '../utils/interpolate';
+
+export interface PostmarkConfig {
+  serverToken: string;
+  from: string;
+}
+
+export class PostmarkMailer implements Mailer {
+  private client: ServerClient;
+  private config: PostmarkConfig;
+
+  constructor(config: PostmarkConfig) {
+    this.config = config;
+    this.client = new ServerClient(config.serverToken);
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const htmlBody = message.template
+      ? interpolate(message.template, message.data ?? {})
+      : message.html ?? '';
+
+    try {
+      const messageData: any = {
+        From: message.from ?? this.config.from,
+        To: Array.isArray(message.to) ? message.to.join(',') : message.to,
+        Subject: message.subject,
+        MessageStream: 'outbound',
+      };
+
+      if (htmlBody) messageData.HtmlBody = htmlBody;
+      if (message.text) messageData.TextBody = message.text;
+
+      const response = await this.client.sendEmail(messageData);
+
+
+
+      return {
+        success: true,
+        messageId: response.MessageID,
+        provider: 'postmark',
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+        provider: 'postmark',
+      };
+    }
+  }
+}
+

package/src/drivers/ResendMailer.ts

@@ -0,0 +1,56 @@
+import { Resend } from 'resend';
+import type { Mailer, MailMessage, MailResult } from '../Mailer';
+import { interpolate } from '../utils/interpolate';
+
+export interface ResendConfig {
+  apiKey: string;
+  from: string;
+}
+
+export class ResendMailer implements Mailer {
+  private client: Resend;
+  private config: ResendConfig;
+
+  constructor(config: ResendConfig) {
+    this.config = config;
+    this.client = new Resend(config.apiKey);
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const html = message.template
+      ? interpolate(message.template, message.data ?? {})
+      : message.html ?? '';
+
+    try {
+      const response = await this.client.emails.send({
+        from: message.from ?? this.config.from,
+        to: Array.isArray(message.to) ? message.to : [message.to],
+        subject: message.subject,
+        html,
+        text: message.text,
+      } as any);
+
+
+      if (response.error) {
+        return {
+          success: false,
+          error: response.error.message,
+          provider: 'resend',
+        };
+      }
+
+      return {
+        success: true,
+        messageId: response.data?.id,
+        provider: 'resend',
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+        provider: 'resend',
+      };
+    }
+  }
+}
+

package/src/drivers/SesMailer.ts

@@ -0,0 +1,64 @@
+import { SESClient, SendEmailCommand } from '@aws-sdk/client-ses';
+import type { Mailer, MailMessage, MailResult } from '../Mailer';
+import { interpolate } from '../utils/interpolate';
+
+export interface SesConfig {
+  region: string;
+  key: string;
+  secret: string;
+  from: string;
+}
+
+export class SesMailer implements Mailer {
+  private client: SESClient;
+  private defaultFrom: string;
+
+  constructor(config: SesConfig) {
+    this.defaultFrom = config.from;
+    this.client = new SESClient({
+      region: config.region,
+      credentials: {
+        accessKeyId: config.key,
+        secretAccessKey: config.secret,
+      },
+    });
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const subject = interpolate(message.subject, message.data ?? {});
+    const text = message.text ? interpolate(message.text, message.data ?? {}) : undefined;
+    const html = message.template 
+      ? interpolate(message.template, message.data ?? {}) 
+      : (message.html ? interpolate(message.html, message.data ?? {}) : undefined);
+
+    const command = new SendEmailCommand({
+      Source: message.from ?? this.defaultFrom,
+      Destination: {
+        ToAddresses: Array.isArray(message.to) ? message.to : [message.to],
+      },
+      Message: {
+        Subject: { Data: subject },
+        Body: {
+          Text: text ? { Data: text } : undefined,
+          Html: html ? { Data: html } : undefined,
+        },
+      },
+    });
+
+    try {
+      const response = await this.client.send(command);
+      return {
+        success: true,
+        messageId: response.MessageId,
+        provider: 'ses',
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+        provider: 'ses',
+      };
+    }
+  }
+}
+

package/src/drivers/SmtpMailer.ts

@@ -0,0 +1,59 @@
+import nodemailer from 'nodemailer';
+import type { Mailer, MailMessage, MailResult } from '../Mailer';
+import { interpolate } from '../utils/interpolate';
+
+export interface SmtpConfig {
+  host: string;
+  port: number;
+  user: string;
+  pass: string;
+  from: string;
+}
+
+export class SmtpMailer implements Mailer {
+  private transporter: nodemailer.Transporter;
+  private defaultFrom: string;
+
+  constructor(config: SmtpConfig) {
+    this.defaultFrom = config.from;
+    this.transporter = nodemailer.createTransport({
+      host: config.host,
+      port: config.port,
+      auth: {
+        user: config.user,
+        pass: config.pass,
+      },
+    });
+  }
+
+  async send(message: MailMessage): Promise<MailResult> {
+    const subject = interpolate(message.subject, message.data ?? {});
+    const text = message.text ? interpolate(message.text, message.data ?? {}) : undefined;
+    const html = message.template 
+      ? interpolate(message.template, message.data ?? {}) 
+      : (message.html ? interpolate(message.html, message.data ?? {}) : undefined);
+
+    try {
+      const response = await this.transporter.sendMail({
+        from: message.from ?? this.defaultFrom,
+        to: Array.isArray(message.to) ? message.to.join(', ') : message.to,
+        subject,
+        text,
+        html,
+      });
+
+      return {
+        success: true,
+        messageId: response.messageId,
+        provider: 'smtp',
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: (error as Error).message,
+        provider: 'smtp',
+      };
+    }
+  }
+}
+

package/src/drivers/drivers.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from "bun:test";
+import { MailgunMailer } from "./MailgunMailer";
+import { PostmarkMailer } from "./PostmarkMailer";
+import { ResendMailer } from "./ResendMailer";
+
+describe("MailgunMailer", () => {
+  it("constructs without throwing", () => {
+    expect(() => new MailgunMailer({
+      apiKey: "key-test",
+      domain: "test.example.com",
+      from: "test@example.com",
+    })).not.toThrow();
+  });
+});
+
+describe("PostmarkMailer", () => {
+  it("constructs without throwing", () => {
+    expect(() => new PostmarkMailer({
+      serverToken: "token-test",
+      from: "test@example.com",
+    })).not.toThrow();
+  });
+});
+
+describe("ResendMailer", () => {
+  it("constructs without throwing", () => {
+    expect(() => new ResendMailer({
+      apiKey: "re_test",
+      from: "test@example.com",
+    })).not.toThrow();
+  });
+});
+
+

package/src/index.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it, spyOn } from "bun:test";
+import { LogMailer } from "./index";
+
+describe("LogMailer", () => {
+  it("renders templates with data", async () => {
+    const mailer = new LogMailer();
+    const logSpy = spyOn(console, "log");
+    
+    await mailer.send({
+      to: "test@example.com",
+      subject: "Hello {{ name }}",
+      text: "Welcome to {{ app }}",
+      data: { name: "Alice", app: "XAOCS" }
+    });
+
+    expect(logSpy).toHaveBeenCalledWith("Subject:", "Hello Alice");
+    expect(logSpy).toHaveBeenCalledWith("Text:   ", "Welcome to XAOCS");
+
+    
+    logSpy.mockRestore();
+  });
+});
+

package/src/index.ts

@@ -0,0 +1,11 @@
+export * from './Mailer';
+export * from './MailManager';
+export * from './drivers/LogMailer';
+export * from './drivers/SmtpMailer';
+export * from './drivers/SesMailer';
+export * from './drivers/MailgunMailer';
+export * from './drivers/PostmarkMailer';
+export * from './drivers/ResendMailer';
+
+export * from './utils/interpolate';
+

package/src/utils/interpolate.ts

@@ -0,0 +1,10 @@
+/**
+ * Simple string interpolation utility for XAOCS templates.
+ * Replaces {{ variable }} with values from the data object.
+ */
+export function interpolate(template: string, data: Record<string, any>): string {
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, key) => {
+    return data[key]?.toString() ?? match;
+  });
+}
+