@iskra-bun/mailer-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @iskra-bun/mailer-kit
+
+## 0.1.0
+
+### Minor Changes
+
+- f9654df: Initial public release. Transport-agnostic email kit extracted from web-kit: `EmailAdapter` interface, `MockEmailAdapter`, SMTP/SendGrid/Mailgun/SES providers, and a `createEmailAdapter` factory — usable from workers and cron jobs without an HTTP layer. The previously-unimplemented SES provider is now complete.
+
+### Patch Changes
+
+- Mailer hardening across providers:
+
+    - `sendTemplate` now throws `sendTemplate not supported by <provider>` for the SMTP, Mailgun, SES and SendGrid providers instead of silently reporting success without sending anything.
+    - The SMTP provider enforces TLS: `secure: true` on port 465, otherwise `requireTLS: true`, with `tls.rejectUnauthorized: true`.
+    - The Mailgun provider applies a custom-header allowlist (throwing on non-allowlisted headers) and strips CR/LF from header values, preventing email header injection.
+
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1

package/README.md

@@ -0,0 +1,37 @@
+# @iskra-bun/mailer-kit
+
+Envio de correo de Iskra, agnostico del transporte. Adaptadores intercambiables de SMTP, SendGrid, Mailgun, SES y un mock para tests. Sin acoplamiento HTTP: usalo en workers, cron o cualquier proceso.
+
+## Instalacion
+
+```bash
+bun add @iskra-bun/mailer-kit @iskra-bun/core
+```
+
+## Uso rapido
+
+```typescript
+import { createEmailAdapter } from '@iskra-bun/mailer-kit'
+
+const mailer = await createEmailAdapter({
+    provider: 'smtp',
+    smtp: { host: 'smtp.example.com', port: 587, username: 'user', password: 'pass' },
+    from: { name: 'Mi App', email: 'noreply@example.com' },
+})
+
+await mailer.send({
+    to: 'usuario@example.com',
+    subject: 'Hola',
+    html: '<p>Bienvenido</p>',
+})
+```
+
+Cambia `provider` entre `mock`, `smtp`, `sendgrid`, `mailgun` o `ses`; la API (`send`/`sendTemplate`) es identica entre adaptadores.
+
+## Documentacion
+
+Guia completa: [docs/mailer-kit.md](../../docs/mailer-kit.md)
+
+## Licencia
+
+AGPL-3.0-or-later

package/dist/chunk-4256VN6L.js

@@ -0,0 +1,40 @@
+// src/providers/sendgrid.ts
+import sgMail from "@sendgrid/mail";
+var SendGridEmailAdapter = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.apiKey) throw new Error("SendGrid API Key required");
+    sgMail.setApiKey(config.apiKey);
+  }
+  config;
+  async send(message) {
+    const from = message.from || this.config.from;
+    if (!from) throw new Error("From address required");
+    const msg = {
+      to: message.to,
+      from: from.name ? { email: from.email, name: from.name } : from.email,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+      cc: message.cc,
+      bcc: message.bcc,
+      replyTo: message.replyTo,
+      attachments: message.attachments?.map((a) => ({
+        filename: a.filename,
+        content: typeof a.content === "string" ? a.content : Buffer.from(a.content).toString("base64"),
+        type: a.contentType,
+        disposition: "attachment"
+      }))
+    };
+    const [response] = await sgMail.send(msg);
+    return { messageId: response.headers["x-message-id"], success: true };
+  }
+  async sendTemplate(_templateName, _to, _data) {
+    throw new Error("sendTemplate not supported by sendgrid");
+  }
+};
+
+export {
+  SendGridEmailAdapter
+};
+//# sourceMappingURL=chunk-4256VN6L.js.map

package/dist/chunk-4256VN6L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/sendgrid.ts"],"sourcesContent":["import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from \"../types\";\nimport sgMail from \"@sendgrid/mail\";\n\nexport class SendGridEmailAdapter implements EmailAdapter {\n    constructor(private config: EmailConfig) {\n        if (!config.apiKey) throw new Error(\"SendGrid API Key required\");\n        sgMail.setApiKey(config.apiKey);\n    }\n\n    async send(message: EmailMessage) {\n        const from = message.from || this.config.from;\n        if (!from) throw new Error(\"From address required\");\n\n        const msg = {\n            to: message.to,\n            from: from.name ? { email: from.email, name: from.name } : from.email,\n            subject: message.subject,\n            text: message.text,\n            html: message.html,\n            cc: message.cc as any,\n            bcc: message.bcc as any,\n            replyTo: message.replyTo,\n            attachments: message.attachments?.map(a => ({\n                filename: a.filename,\n                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content).toString(\"base64\"),\n                type: a.contentType,\n                disposition: \"attachment\"\n            }))\n        } as any;\n\n        const [response] = await sgMail.send(msg);\n        return { messageId: response.headers[\"x-message-id\"] as string, success: true };\n    }\n\n    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {\n        // No template engine is implemented yet; fail loudly rather than\n        // silently sending a placeholder body that looks like a real send.\n        throw new Error(\"sendTemplate not supported by sendgrid\");\n    }\n}\n"],"mappings":";AACA,OAAO,YAAY;AAEZ,IAAM,uBAAN,MAAmD;AAAA,EACtD,YAAoB,QAAqB;AAArB;AAChB,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,MAAM,2BAA2B;AAC/D,WAAO,UAAU,OAAO,MAAM;AAAA,EAClC;AAAA,EAHoB;AAAA,EAKpB,MAAM,KAAK,SAAuB;AAC9B,UAAM,OAAO,QAAQ,QAAQ,KAAK,OAAO;AACzC,QAAI,CAAC,KAAM,OAAM,IAAI,MAAM,uBAAuB;AAElD,UAAM,MAAM;AAAA,MACR,IAAI,QAAQ;AAAA,MACZ,MAAM,KAAK,OAAO,EAAE,OAAO,KAAK,OAAO,MAAM,KAAK,KAAK,IAAI,KAAK;AAAA,MAChE,SAAS,QAAQ;AAAA,MACjB,MAAM,QAAQ;AAAA,MACd,MAAM,QAAQ;AAAA,MACd,IAAI,QAAQ;AAAA,MACZ,KAAK,QAAQ;AAAA,MACb,SAAS,QAAQ;AAAA,MACjB,aAAa,QAAQ,aAAa,IAAI,QAAM;AAAA,QACxC,UAAU,EAAE;AAAA,QACZ,SAAS,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,QAAQ;AAAA,QAC7F,MAAM,EAAE;AAAA,QACR,aAAa;AAAA,MACjB,EAAE;AAAA,IACN;AAEA,UAAM,CAAC,QAAQ,IAAI,MAAM,OAAO,KAAK,GAAG;AACxC,WAAO,EAAE,WAAW,SAAS,QAAQ,cAAc,GAAa,SAAS,KAAK;AAAA,EAClF;AAAA,EAEA,MAAM,aAAa,eAAuB,KAAwB,OAAuE;AAGrI,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC5D;AACJ;","names":[]}

package/dist/chunk-4Y2FQY2L.js

@@ -0,0 +1,50 @@
+// src/providers/smtp.ts
+import * as nodemailer from "nodemailer";
+var SmtpEmailAdapter = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.smtp) throw new Error("SMTP config required");
+    const secure = config.smtp.secure ?? config.smtp.port === 465;
+    this.transporter = nodemailer.createTransport({
+      host: config.smtp.host,
+      port: config.smtp.port,
+      secure,
+      requireTLS: secure ? void 0 : true,
+      tls: { rejectUnauthorized: true },
+      auth: {
+        user: config.smtp.username,
+        pass: config.smtp.password
+      }
+    });
+  }
+  config;
+  transporter;
+  async send(message) {
+    const from = message.from || this.config.from;
+    if (!from) throw new Error("From address required");
+    const info = await this.transporter.sendMail({
+      from: from.name ? `"${from.name}" <${from.email}>` : from.email,
+      to: Array.isArray(message.to) ? message.to.join(", ") : message.to,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+      cc: message.cc ? Array.isArray(message.cc) ? message.cc.join(", ") : message.cc : void 0,
+      bcc: message.bcc ? Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc : void 0,
+      replyTo: message.replyTo,
+      attachments: message.attachments?.map((a) => ({
+        filename: a.filename,
+        content: typeof a.content === "string" ? a.content : Buffer.from(a.content),
+        contentType: a.contentType
+      }))
+    });
+    return { messageId: info.messageId, success: true };
+  }
+  async sendTemplate(_templateName, _to, _data) {
+    throw new Error("sendTemplate not supported by smtp");
+  }
+};
+
+export {
+  SmtpEmailAdapter
+};
+//# sourceMappingURL=chunk-4Y2FQY2L.js.map

package/dist/chunk-4Y2FQY2L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/smtp.ts"],"sourcesContent":["import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from \"../types\";\nimport * as nodemailer from \"nodemailer\";\n\nexport class SmtpEmailAdapter implements EmailAdapter {\n    private transporter: nodemailer.Transporter;\n\n    constructor(private config: EmailConfig) {\n        if (!config.smtp) throw new Error(\"SMTP config required\");\n        // Implicit TLS on port 465; STARTTLS enforced (requireTLS) elsewhere so\n        // credentials never transit in cleartext. An explicit `secure` wins.\n        const secure = config.smtp.secure ?? config.smtp.port === 465;\n        this.transporter = nodemailer.createTransport({\n            host: config.smtp.host,\n            port: config.smtp.port,\n            secure,\n            requireTLS: secure ? undefined : true,\n            tls: { rejectUnauthorized: true },\n            auth: {\n                user: config.smtp.username,\n                pass: config.smtp.password\n            }\n        });\n    }\n\n    async send(message: EmailMessage) {\n        const from = message.from || this.config.from;\n        if (!from) throw new Error(\"From address required\");\n\n        const info = await this.transporter.sendMail({\n            from: from.name ? `\"${from.name}\" <${from.email}>` : from.email,\n            to: Array.isArray(message.to) ? message.to.join(\", \") : message.to,\n            subject: message.subject,\n            text: message.text,\n            html: message.html,\n            cc: message.cc ? (Array.isArray(message.cc) ? message.cc.join(\", \") : message.cc) : undefined,\n            bcc: message.bcc ? (Array.isArray(message.bcc) ? message.bcc.join(\", \") : message.bcc) : undefined,\n            replyTo: message.replyTo,\n            attachments: message.attachments?.map(a => ({\n                filename: a.filename,\n                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content),\n                contentType: a.contentType\n            }))\n        });\n\n        return { messageId: (info as any).messageId, success: true };\n    }\n\n    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {\n        // No template engine is implemented yet; fail loudly rather than\n        // silently sending a placeholder body that looks like a real send.\n        throw new Error(\"sendTemplate not supported by smtp\");\n    }\n}\n"],"mappings":";AACA,YAAY,gBAAgB;AAErB,IAAM,mBAAN,MAA+C;AAAA,EAGlD,YAAoB,QAAqB;AAArB;AAChB,QAAI,CAAC,OAAO,KAAM,OAAM,IAAI,MAAM,sBAAsB;AAGxD,UAAM,SAAS,OAAO,KAAK,UAAU,OAAO,KAAK,SAAS;AAC1D,SAAK,cAAyB,2BAAgB;AAAA,MAC1C,MAAM,OAAO,KAAK;AAAA,MAClB,MAAM,OAAO,KAAK;AAAA,MAClB;AAAA,MACA,YAAY,SAAS,SAAY;AAAA,MACjC,KAAK,EAAE,oBAAoB,KAAK;AAAA,MAChC,MAAM;AAAA,QACF,MAAM,OAAO,KAAK;AAAA,QAClB,MAAM,OAAO,KAAK;AAAA,MACtB;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAhBoB;AAAA,EAFZ;AAAA,EAoBR,MAAM,KAAK,SAAuB;AAC9B,UAAM,OAAO,QAAQ,QAAQ,KAAK,OAAO;AACzC,QAAI,CAAC,KAAM,OAAM,IAAI,MAAM,uBAAuB;AAElD,UAAM,OAAO,MAAM,KAAK,YAAY,SAAS;AAAA,MACzC,MAAM,KAAK,OAAO,IAAI,KAAK,IAAI,MAAM,KAAK,KAAK,MAAM,KAAK;AAAA,MAC1D,IAAI,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,GAAG,KAAK,IAAI,IAAI,QAAQ;AAAA,MAChE,SAAS,QAAQ;AAAA,MACjB,MAAM,QAAQ;AAAA,MACd,MAAM,QAAQ;AAAA,MACd,IAAI,QAAQ,KAAM,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,GAAG,KAAK,IAAI,IAAI,QAAQ,KAAM;AAAA,MACpF,KAAK,QAAQ,MAAO,MAAM,QAAQ,QAAQ,GAAG,IAAI,QAAQ,IAAI,KAAK,IAAI,IAAI,QAAQ,MAAO;AAAA,MACzF,SAAS,QAAQ;AAAA,MACjB,aAAa,QAAQ,aAAa,IAAI,QAAM;AAAA,QACxC,UAAU,EAAE;AAAA,QACZ,SAAS,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU,OAAO,KAAK,EAAE,OAAO;AAAA,QAC1E,aAAa,EAAE;AAAA,MACnB,EAAE;AAAA,IACN,CAAC;AAED,WAAO,EAAE,WAAY,KAAa,WAAW,SAAS,KAAK;AAAA,EAC/D;AAAA,EAEA,MAAM,aAAa,eAAuB,KAAwB,OAAuE;AAGrI,UAAM,IAAI,MAAM,oCAAoC;AAAA,EACxD;AACJ;","names":[]}

package/dist/chunk-H6SSV4G4.js

@@ -0,0 +1,61 @@
+// src/providers/ses.ts
+var SesEmailAdapter = class {
+  region;
+  defaultFrom;
+  injectedClient;
+  injectedCommand;
+  constructor(config, deps = {}) {
+    this.region = config.region;
+    this.defaultFrom = config.from;
+    this.injectedClient = deps.client;
+    this.injectedCommand = deps.sendEmailCommand;
+  }
+  async resolveSdk() {
+    if (this.injectedClient && this.injectedCommand) {
+      return { client: this.injectedClient, command: this.injectedCommand };
+    }
+    const sdkModule = "@aws-sdk/client-sesv2";
+    const mod = await import(sdkModule);
+    const SESv2Client = mod.SESv2Client;
+    const SendEmailCommand = mod.SendEmailCommand;
+    const client = this.injectedClient ?? new SESv2Client({ region: this.region });
+    const command = this.injectedCommand ?? ((input) => new SendEmailCommand(input));
+    return { client, command };
+  }
+  async send(message) {
+    const from = message.from || this.defaultFrom;
+    if (!from) throw new Error("From address required");
+    const { client, command } = await this.resolveSdk();
+    const toAddresses = Array.isArray(message.to) ? message.to : [message.to];
+    const ccAddresses = message.cc ? Array.isArray(message.cc) ? message.cc : [message.cc] : void 0;
+    const bccAddresses = message.bcc ? Array.isArray(message.bcc) ? message.bcc : [message.bcc] : void 0;
+    const body = {};
+    if (message.text) body.Text = { Data: message.text, Charset: "UTF-8" };
+    if (message.html) body.Html = { Data: message.html, Charset: "UTF-8" };
+    const input = {
+      FromEmailAddress: from.name ? `${from.name} <${from.email}>` : from.email,
+      Destination: {
+        ToAddresses: toAddresses,
+        ...ccAddresses ? { CcAddresses: ccAddresses } : {},
+        ...bccAddresses ? { BccAddresses: bccAddresses } : {}
+      },
+      ...message.replyTo ? { ReplyToAddresses: [message.replyTo] } : {},
+      Content: {
+        Simple: {
+          Subject: { Data: message.subject, Charset: "UTF-8" },
+          Body: body
+        }
+      }
+    };
+    const result = await client.send(command(input));
+    return { messageId: result.MessageId ?? "", success: true };
+  }
+  async sendTemplate(_templateName, _to, _data) {
+    throw new Error("sendTemplate not supported by ses");
+  }
+};
+
+export {
+  SesEmailAdapter
+};
+//# sourceMappingURL=chunk-H6SSV4G4.js.map

package/dist/chunk-H6SSV4G4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/ses.ts"],"sourcesContent":["import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from \"../types\";\n\n/**\n * Minimal structural shape of the value returned by\n * `@aws-sdk/client-sesv2`'s `SendEmailCommand` constructor. We only need\n * an opaque object to hand back to `client.send`, so typing it as an\n * unknown-bearing record keeps `tsc` happy without the SDK installed.\n */\nexport interface SesCommand {\n    readonly input: unknown;\n}\n\n/**\n * Structural type for the SESv2 client. Declared locally so this module\n * type-checks even when `@aws-sdk/client-sesv2` is not installed; the real\n * SDK client satisfies this shape at runtime.\n */\nexport interface SesClient {\n    send(command: SesCommand): Promise<{ MessageId?: string }>;\n}\n\n/** Factory that builds a `SendEmailCommand` from its input object. */\nexport type SesCommandFactory = (input: unknown) => SesCommand;\n\nexport interface SesAdapterDeps {\n    /** Pre-built client (used by tests to avoid importing the real SDK). */\n    client?: SesClient;\n    /** Pre-built command factory (used by tests to avoid importing the real SDK). */\n    sendEmailCommand?: SesCommandFactory;\n}\n\nexport class SesEmailAdapter implements EmailAdapter {\n    private region?: string;\n    private defaultFrom?: { name?: string; email: string };\n    private injectedClient?: SesClient;\n    private injectedCommand?: SesCommandFactory;\n\n    constructor(config: EmailConfig, deps: SesAdapterDeps = {}) {\n        // The effective `from` address is validated at send time (it can come\n        // from the message or the config), so construction stays permissive.\n        this.region = config.region;\n        this.defaultFrom = config.from;\n        this.injectedClient = deps.client;\n        this.injectedCommand = deps.sendEmailCommand;\n    }\n\n    private async resolveSdk(): Promise<{ client: SesClient; command: SesCommandFactory }> {\n        if (this.injectedClient && this.injectedCommand) {\n            return { client: this.injectedClient, command: this.injectedCommand };\n        }\n\n        // Lazy load only when actually sending so `tsc`/`bun test` stay green\n        // without `@aws-sdk/client-sesv2` installed. The specifier is held in a\n        // variable so TypeScript does not try to resolve the module at compile\n        // time (it is a real runtime dependency, declared in package.json).\n        const sdkModule = \"@aws-sdk/client-sesv2\";\n        const mod: any = await import(sdkModule);\n        const SESv2Client = mod.SESv2Client as new (cfg: { region?: string }) => SesClient;\n        const SendEmailCommand = mod.SendEmailCommand as new (input: unknown) => SesCommand;\n\n        const client = this.injectedClient ?? new SESv2Client({ region: this.region });\n        const command: SesCommandFactory = this.injectedCommand ?? ((input) => new SendEmailCommand(input));\n\n        return { client, command };\n    }\n\n    async send(message: EmailMessage): Promise<{ messageId: string; success: boolean }> {\n        const from = message.from || this.defaultFrom;\n        if (!from) throw new Error(\"From address required\");\n\n        const { client, command } = await this.resolveSdk();\n\n        const toAddresses = Array.isArray(message.to) ? message.to : [message.to];\n        const ccAddresses = message.cc ? (Array.isArray(message.cc) ? message.cc : [message.cc]) : undefined;\n        const bccAddresses = message.bcc ? (Array.isArray(message.bcc) ? message.bcc : [message.bcc]) : undefined;\n\n        const body: Record<string, { Data: string; Charset: string }> = {};\n        if (message.text) body.Text = { Data: message.text, Charset: \"UTF-8\" };\n        if (message.html) body.Html = { Data: message.html, Charset: \"UTF-8\" };\n\n        const input = {\n            FromEmailAddress: from.name ? `${from.name} <${from.email}>` : from.email,\n            Destination: {\n                ToAddresses: toAddresses,\n                ...(ccAddresses ? { CcAddresses: ccAddresses } : {}),\n                ...(bccAddresses ? { BccAddresses: bccAddresses } : {}),\n            },\n            ...(message.replyTo ? { ReplyToAddresses: [message.replyTo] } : {}),\n            Content: {\n                Simple: {\n                    Subject: { Data: message.subject, Charset: \"UTF-8\" },\n                    Body: body,\n                },\n            },\n        };\n\n        const result = await client.send(command(input));\n        return { messageId: result.MessageId ?? \"\", success: true };\n    }\n\n    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {\n        // No template engine is implemented yet; fail loudly rather than\n        // silently sending a placeholder body that looks like a real send.\n        throw new Error(\"sendTemplate not supported by ses\");\n    }\n}\n"],"mappings":";AA+BO,IAAM,kBAAN,MAA8C;AAAA,EACzC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAER,YAAY,QAAqB,OAAuB,CAAC,GAAG;AAGxD,SAAK,SAAS,OAAO;AACrB,SAAK,cAAc,OAAO;AAC1B,SAAK,iBAAiB,KAAK;AAC3B,SAAK,kBAAkB,KAAK;AAAA,EAChC;AAAA,EAEA,MAAc,aAAyE;AACnF,QAAI,KAAK,kBAAkB,KAAK,iBAAiB;AAC7C,aAAO,EAAE,QAAQ,KAAK,gBAAgB,SAAS,KAAK,gBAAgB;AAAA,IACxE;AAMA,UAAM,YAAY;AAClB,UAAM,MAAW,MAAM,OAAO;AAC9B,UAAM,cAAc,IAAI;AACxB,UAAM,mBAAmB,IAAI;AAE7B,UAAM,SAAS,KAAK,kBAAkB,IAAI,YAAY,EAAE,QAAQ,KAAK,OAAO,CAAC;AAC7E,UAAM,UAA6B,KAAK,oBAAoB,CAAC,UAAU,IAAI,iBAAiB,KAAK;AAEjG,WAAO,EAAE,QAAQ,QAAQ;AAAA,EAC7B;AAAA,EAEA,MAAM,KAAK,SAAyE;AAChF,UAAM,OAAO,QAAQ,QAAQ,KAAK;AAClC,QAAI,CAAC,KAAM,OAAM,IAAI,MAAM,uBAAuB;AAElD,UAAM,EAAE,QAAQ,QAAQ,IAAI,MAAM,KAAK,WAAW;AAElD,UAAM,cAAc,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,KAAK,CAAC,QAAQ,EAAE;AACxE,UAAM,cAAc,QAAQ,KAAM,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,KAAK,CAAC,QAAQ,EAAE,IAAK;AAC3F,UAAM,eAAe,QAAQ,MAAO,MAAM,QAAQ,QAAQ,GAAG,IAAI,QAAQ,MAAM,CAAC,QAAQ,GAAG,IAAK;AAEhG,UAAM,OAA0D,CAAC;AACjE,QAAI,QAAQ,KAAM,MAAK,OAAO,EAAE,MAAM,QAAQ,MAAM,SAAS,QAAQ;AACrE,QAAI,QAAQ,KAAM,MAAK,OAAO,EAAE,MAAM,QAAQ,MAAM,SAAS,QAAQ;AAErE,UAAM,QAAQ;AAAA,MACV,kBAAkB,KAAK,OAAO,GAAG,KAAK,IAAI,KAAK,KAAK,KAAK,MAAM,KAAK;AAAA,MACpE,aAAa;AAAA,QACT,aAAa;AAAA,QACb,GAAI,cAAc,EAAE,aAAa,YAAY,IAAI,CAAC;AAAA,QAClD,GAAI,eAAe,EAAE,cAAc,aAAa,IAAI,CAAC;AAAA,MACzD;AAAA,MACA,GAAI,QAAQ,UAAU,EAAE,kBAAkB,CAAC,QAAQ,OAAO,EAAE,IAAI,CAAC;AAAA,MACjE,SAAS;AAAA,QACL,QAAQ;AAAA,UACJ,SAAS,EAAE,MAAM,QAAQ,SAAS,SAAS,QAAQ;AAAA,UACnD,MAAM;AAAA,QACV;AAAA,MACJ;AAAA,IACJ;AAEA,UAAM,SAAS,MAAM,OAAO,KAAK,QAAQ,KAAK,CAAC;AAC/C,WAAO,EAAE,WAAW,OAAO,aAAa,IAAI,SAAS,KAAK;AAAA,EAC9D;AAAA,EAEA,MAAM,aAAa,eAAuB,KAAwB,OAAuE;AAGrI,UAAM,IAAI,MAAM,mCAAmC;AAAA,EACvD;AACJ;","names":[]}

package/dist/chunk-P5HWUNVS.js

@@ -0,0 +1,78 @@
+// src/providers/mailgun.ts
+var ALLOWED_HEADERS = /* @__PURE__ */ new Set([
+  "reply-to",
+  "in-reply-to",
+  "references",
+  "list-unsubscribe",
+  "list-unsubscribe-post",
+  "list-id",
+  "x-mailgun-variables",
+  "x-mailgun-tag"
+]);
+var stripCrlf = (value) => value.split(/[\r\n]/)[0] ?? "";
+var MailgunEmailAdapter = class {
+  apiKey;
+  domain;
+  baseUrl;
+  defaultFrom;
+  constructor(config) {
+    if (!config.apiKey) throw new Error("Mailgun requires apiKey");
+    if (!config.domain) throw new Error("Mailgun requires domain");
+    this.apiKey = config.apiKey;
+    this.domain = config.domain;
+    this.baseUrl = config.baseUrl || "https://api.mailgun.net/v3";
+    this.defaultFrom = config.from;
+  }
+  async send(message) {
+    const form = new FormData();
+    const from = message.from || this.defaultFrom;
+    if (from) {
+      form.append("from", from.name ? `${from.name} <${from.email}>` : from.email);
+    }
+    const to = Array.isArray(message.to) ? message.to.join(",") : message.to;
+    form.append("to", to);
+    form.append("subject", message.subject);
+    if (message.text) form.append("text", message.text);
+    if (message.html) form.append("html", message.html);
+    if (message.cc) form.append("cc", Array.isArray(message.cc) ? message.cc.join(",") : message.cc);
+    if (message.bcc) form.append("bcc", Array.isArray(message.bcc) ? message.bcc.join(",") : message.bcc);
+    if (message.replyTo) form.append("h:Reply-To", message.replyTo);
+    if (message.headers) {
+      for (const [key, value] of Object.entries(message.headers)) {
+        if (!ALLOWED_HEADERS.has(key.toLowerCase())) {
+          throw new Error(`Header "${key}" is not allowed`);
+        }
+        form.append(`h:${key}`, stripCrlf(value));
+      }
+    }
+    if (message.attachments) {
+      for (const att of message.attachments) {
+        const content = typeof att.content === "string" ? new TextEncoder().encode(att.content) : att.content;
+        const bytes = new Uint8Array(content);
+        const blob = new Blob([bytes], { type: att.contentType || "application/octet-stream" });
+        form.append("attachment", blob, att.filename);
+      }
+    }
+    const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
+      method: "POST",
+      headers: {
+        Authorization: "Basic " + btoa(`api:${this.apiKey}`)
+      },
+      body: form
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Mailgun API error (${response.status}): ${errorText}`);
+    }
+    const result = await response.json();
+    return { messageId: result.id, success: true };
+  }
+  async sendTemplate(_templateName, _to, _data) {
+    throw new Error("sendTemplate not supported by mailgun");
+  }
+};
+
+export {
+  MailgunEmailAdapter
+};
+//# sourceMappingURL=chunk-P5HWUNVS.js.map

package/dist/chunk-P5HWUNVS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/providers/mailgun.ts"],"sourcesContent":["import type { EmailAdapter, EmailMessage, EmailConfig, TemplateData } from \"../types\";\n\n/**\n * Outbound custom mail headers callers are permitted to set. Anything outside\n * this set is rejected so a caller cannot spoof Reply-To / Sender / routing\n * headers via the generic `headers` map.\n */\nconst ALLOWED_HEADERS = new Set([\n    \"reply-to\",\n    \"in-reply-to\",\n    \"references\",\n    \"list-unsubscribe\",\n    \"list-unsubscribe-post\",\n    \"list-id\",\n    \"x-mailgun-variables\",\n    \"x-mailgun-tag\",\n]);\n\n/**\n * Truncate a header value at the first CR/LF. Anything after a line break is an\n * injected header (or folded continuation) and must be dropped, not preserved.\n */\nconst stripCrlf = (value: string): string => value.split(/[\\r\\n]/)[0] ?? \"\";\n\nexport class MailgunEmailAdapter implements EmailAdapter {\n    private apiKey: string;\n    private domain: string;\n    private baseUrl: string;\n    private defaultFrom?: { name?: string; email: string };\n\n    constructor(config: EmailConfig) {\n        if (!config.apiKey) throw new Error(\"Mailgun requires apiKey\");\n        if (!config.domain) throw new Error(\"Mailgun requires domain\");\n\n        this.apiKey = config.apiKey;\n        this.domain = config.domain;\n        this.baseUrl = config.baseUrl || \"https://api.mailgun.net/v3\";\n        this.defaultFrom = config.from;\n    }\n\n    async send(message: EmailMessage): Promise<{ messageId: string; success: boolean }> {\n        const form = new FormData();\n\n        const from = message.from || this.defaultFrom;\n        if (from) {\n            form.append(\"from\", from.name ? `${from.name} <${from.email}>` : from.email);\n        }\n\n        const to = Array.isArray(message.to) ? message.to.join(\",\") : message.to;\n        form.append(\"to\", to);\n        form.append(\"subject\", message.subject);\n\n        if (message.text) form.append(\"text\", message.text);\n        if (message.html) form.append(\"html\", message.html);\n        if (message.cc) form.append(\"cc\", Array.isArray(message.cc) ? message.cc.join(\",\") : message.cc);\n        if (message.bcc) form.append(\"bcc\", Array.isArray(message.bcc) ? message.bcc.join(\",\") : message.bcc);\n        if (message.replyTo) form.append(\"h:Reply-To\", message.replyTo);\n\n        if (message.headers) {\n            for (const [key, value] of Object.entries(message.headers)) {\n                if (!ALLOWED_HEADERS.has(key.toLowerCase())) {\n                    throw new Error(`Header \"${key}\" is not allowed`);\n                }\n                form.append(`h:${key}`, stripCrlf(value));\n            }\n        }\n\n        if (message.attachments) {\n            for (const att of message.attachments) {\n                const content = typeof att.content === \"string\"\n                    ? new TextEncoder().encode(att.content)\n                    : att.content;\n                const bytes = new Uint8Array(content);\n                const blob = new Blob([bytes], { type: att.contentType || \"application/octet-stream\" });\n                form.append(\"attachment\", blob, att.filename);\n            }\n        }\n\n        const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {\n            method: \"POST\",\n            headers: {\n                Authorization: \"Basic \" + btoa(`api:${this.apiKey}`),\n            },\n            body: form,\n        });\n\n        if (!response.ok) {\n            const errorText = await response.text();\n            throw new Error(`Mailgun API error (${response.status}): ${errorText}`);\n        }\n\n        const result = await response.json() as { id: string; message: string };\n        return { messageId: result.id, success: true };\n    }\n\n    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {\n        // No template engine is implemented yet; fail loudly rather than\n        // silently sending a placeholder that looks like a real send.\n        throw new Error(\"sendTemplate not supported by mailgun\");\n    }\n}\n"],"mappings":";AAOA,IAAM,kBAAkB,oBAAI,IAAI;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACJ,CAAC;AAMD,IAAM,YAAY,CAAC,UAA0B,MAAM,MAAM,QAAQ,EAAE,CAAC,KAAK;AAElE,IAAM,sBAAN,MAAkD;AAAA,EAC7C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAER,YAAY,QAAqB;AAC7B,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,MAAM,yBAAyB;AAC7D,QAAI,CAAC,OAAO,OAAQ,OAAM,IAAI,MAAM,yBAAyB;AAE7D,SAAK,SAAS,OAAO;AACrB,SAAK,SAAS,OAAO;AACrB,SAAK,UAAU,OAAO,WAAW;AACjC,SAAK,cAAc,OAAO;AAAA,EAC9B;AAAA,EAEA,MAAM,KAAK,SAAyE;AAChF,UAAM,OAAO,IAAI,SAAS;AAE1B,UAAM,OAAO,QAAQ,QAAQ,KAAK;AAClC,QAAI,MAAM;AACN,WAAK,OAAO,QAAQ,KAAK,OAAO,GAAG,KAAK,IAAI,KAAK,KAAK,KAAK,MAAM,KAAK,KAAK;AAAA,IAC/E;AAEA,UAAM,KAAK,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,GAAG,KAAK,GAAG,IAAI,QAAQ;AACtE,SAAK,OAAO,MAAM,EAAE;AACpB,SAAK,OAAO,WAAW,QAAQ,OAAO;AAEtC,QAAI,QAAQ,KAAM,MAAK,OAAO,QAAQ,QAAQ,IAAI;AAClD,QAAI,QAAQ,KAAM,MAAK,OAAO,QAAQ,QAAQ,IAAI;AAClD,QAAI,QAAQ,GAAI,MAAK,OAAO,MAAM,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,GAAG,KAAK,GAAG,IAAI,QAAQ,EAAE;AAC/F,QAAI,QAAQ,IAAK,MAAK,OAAO,OAAO,MAAM,QAAQ,QAAQ,GAAG,IAAI,QAAQ,IAAI,KAAK,GAAG,IAAI,QAAQ,GAAG;AACpG,QAAI,QAAQ,QAAS,MAAK,OAAO,cAAc,QAAQ,OAAO;AAE9D,QAAI,QAAQ,SAAS;AACjB,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,QAAQ,OAAO,GAAG;AACxD,YAAI,CAAC,gBAAgB,IAAI,IAAI,YAAY,CAAC,GAAG;AACzC,gBAAM,IAAI,MAAM,WAAW,GAAG,kBAAkB;AAAA,QACpD;AACA,aAAK,OAAO,KAAK,GAAG,IAAI,UAAU,KAAK,CAAC;AAAA,MAC5C;AAAA,IACJ;AAEA,QAAI,QAAQ,aAAa;AACrB,iBAAW,OAAO,QAAQ,aAAa;AACnC,cAAM,UAAU,OAAO,IAAI,YAAY,WACjC,IAAI,YAAY,EAAE,OAAO,IAAI,OAAO,IACpC,IAAI;AACV,cAAM,QAAQ,IAAI,WAAW,OAAO;AACpC,cAAM,OAAO,IAAI,KAAK,CAAC,KAAK,GAAG,EAAE,MAAM,IAAI,eAAe,2BAA2B,CAAC;AACtF,aAAK,OAAO,cAAc,MAAM,IAAI,QAAQ;AAAA,MAChD;AAAA,IACJ;AAEA,UAAM,WAAW,MAAM,MAAM,GAAG,KAAK,OAAO,IAAI,KAAK,MAAM,aAAa;AAAA,MACpE,QAAQ;AAAA,MACR,SAAS;AAAA,QACL,eAAe,WAAW,KAAK,OAAO,KAAK,MAAM,EAAE;AAAA,MACvD;AAAA,MACA,MAAM;AAAA,IACV,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AACd,YAAM,YAAY,MAAM,SAAS,KAAK;AACtC,YAAM,IAAI,MAAM,sBAAsB,SAAS,MAAM,MAAM,SAAS,EAAE;AAAA,IAC1E;AAEA,UAAM,SAAS,MAAM,SAAS,KAAK;AACnC,WAAO,EAAE,WAAW,OAAO,IAAI,SAAS,KAAK;AAAA,EACjD;AAAA,EAEA,MAAM,aAAa,eAAuB,KAAwB,OAAuE;AAGrI,UAAM,IAAI,MAAM,uCAAuC;AAAA,EAC3D;AACJ;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+interface EmailConfig {
+    provider: "smtp" | "sendgrid" | "mock" | "mailgun" | "ses";
+    smtp?: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+        secure?: boolean;
+    };
+    apiKey?: string;
+    apiSecret?: string;
+    region?: string;
+    domain?: string;
+    baseUrl?: string;
+    from?: {
+        name?: string;
+        email: string;
+    };
+    templateDir?: string;
+}
+interface EmailMessage {
+    to: string | string[];
+    from?: {
+        name?: string;
+        email: string;
+    };
+    subject: string;
+    text?: string;
+    html?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: Array<{
+        filename: string;
+        content: Uint8Array | string;
+        contentType?: string;
+    }>;
+    headers?: Record<string, string>;
+}
+interface TemplateData {
+    [key: string]: unknown;
+}
+interface EmailAdapter {
+    send(message: EmailMessage): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+    sendTemplate(templateName: string, to: string | string[], data: TemplateData): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+}
+
+/**
+ * In-memory email adapter used for tests and local development.
+ * It performs no network I/O and stays silent (no stdout) so it is
+ * safe to use inside library code and background workers.
+ */
+declare class MockEmailAdapter implements EmailAdapter {
+    send(_message: EmailMessage): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+    sendTemplate(name: string, to: string | string[], data: TemplateData): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+}
+
+/**
+ * Builds the email adapter for the given provider. Providers are loaded
+ * lazily via dynamic `import()` so an app only pays for (and only needs
+ * installed) the SDK of the provider it actually uses.
+ */
+declare function createEmailAdapter(config: EmailConfig): Promise<EmailAdapter>;
+
+declare class SmtpEmailAdapter implements EmailAdapter {
+    private config;
+    private transporter;
+    constructor(config: EmailConfig);
+    send(message: EmailMessage): Promise<{
+        messageId: any;
+        success: boolean;
+    }>;
+    sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+}
+
+declare class SendGridEmailAdapter implements EmailAdapter {
+    private config;
+    constructor(config: EmailConfig);
+    send(message: EmailMessage): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+    sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+}
+
+declare class MailgunEmailAdapter implements EmailAdapter {
+    private apiKey;
+    private domain;
+    private baseUrl;
+    private defaultFrom?;
+    constructor(config: EmailConfig);
+    send(message: EmailMessage): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+    sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+}
+
+/**
+ * Minimal structural shape of the value returned by
+ * `@aws-sdk/client-sesv2`'s `SendEmailCommand` constructor. We only need
+ * an opaque object to hand back to `client.send`, so typing it as an
+ * unknown-bearing record keeps `tsc` happy without the SDK installed.
+ */
+interface SesCommand {
+    readonly input: unknown;
+}
+/**
+ * Structural type for the SESv2 client. Declared locally so this module
+ * type-checks even when `@aws-sdk/client-sesv2` is not installed; the real
+ * SDK client satisfies this shape at runtime.
+ */
+interface SesClient {
+    send(command: SesCommand): Promise<{
+        MessageId?: string;
+    }>;
+}
+/** Factory that builds a `SendEmailCommand` from its input object. */
+type SesCommandFactory = (input: unknown) => SesCommand;
+interface SesAdapterDeps {
+    /** Pre-built client (used by tests to avoid importing the real SDK). */
+    client?: SesClient;
+    /** Pre-built command factory (used by tests to avoid importing the real SDK). */
+    sendEmailCommand?: SesCommandFactory;
+}
+declare class SesEmailAdapter implements EmailAdapter {
+    private region?;
+    private defaultFrom?;
+    private injectedClient?;
+    private injectedCommand?;
+    constructor(config: EmailConfig, deps?: SesAdapterDeps);
+    private resolveSdk;
+    send(message: EmailMessage): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+    sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{
+        messageId: string;
+        success: boolean;
+    }>;
+}
+
+export { type EmailAdapter, type EmailConfig, type EmailMessage, MailgunEmailAdapter, MockEmailAdapter, SendGridEmailAdapter, type SesAdapterDeps, type SesClient, type SesCommand, type SesCommandFactory, SesEmailAdapter, SmtpEmailAdapter, type TemplateData, createEmailAdapter };

package/dist/index.js

@@ -0,0 +1,57 @@
+import {
+  SmtpEmailAdapter
+} from "./chunk-4Y2FQY2L.js";
+import {
+  SendGridEmailAdapter
+} from "./chunk-4256VN6L.js";
+import {
+  MailgunEmailAdapter
+} from "./chunk-P5HWUNVS.js";
+import {
+  SesEmailAdapter
+} from "./chunk-H6SSV4G4.js";
+
+// src/mock.ts
+var MockEmailAdapter = class {
+  async send(_message) {
+    return { messageId: `mock-${Date.now()}`, success: true };
+  }
+  async sendTemplate(name, to, data) {
+    return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });
+  }
+};
+
+// src/factory.ts
+async function createEmailAdapter(config) {
+  switch (config.provider) {
+    case "mock":
+      return new MockEmailAdapter();
+    case "smtp": {
+      const { SmtpEmailAdapter: SmtpEmailAdapter2 } = await import("./smtp-GZ4DZMCQ.js");
+      return new SmtpEmailAdapter2(config);
+    }
+    case "sendgrid": {
+      const { SendGridEmailAdapter: SendGridEmailAdapter2 } = await import("./sendgrid-EYSREU2M.js");
+      return new SendGridEmailAdapter2(config);
+    }
+    case "mailgun": {
+      const { MailgunEmailAdapter: MailgunEmailAdapter2 } = await import("./mailgun-CKVSFBJE.js");
+      return new MailgunEmailAdapter2(config);
+    }
+    case "ses": {
+      const { SesEmailAdapter: SesEmailAdapter2 } = await import("./ses-KGJG5IB5.js");
+      return new SesEmailAdapter2(config);
+    }
+    default:
+      throw new Error(`Provider ${config.provider} not implemented`);
+  }
+}
+export {
+  MailgunEmailAdapter,
+  MockEmailAdapter,
+  SendGridEmailAdapter,
+  SesEmailAdapter,
+  SmtpEmailAdapter,
+  createEmailAdapter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mock.ts","../src/factory.ts"],"sourcesContent":["import type { EmailAdapter, EmailMessage, TemplateData } from \"./types\";\n\n/**\n * In-memory email adapter used for tests and local development.\n * It performs no network I/O and stays silent (no stdout) so it is\n * safe to use inside library code and background workers.\n */\nexport class MockEmailAdapter implements EmailAdapter {\n    async send(_message: EmailMessage) {\n        return { messageId: `mock-${Date.now()}`, success: true };\n    }\n\n    async sendTemplate(name: string, to: string | string[], data: TemplateData) {\n        return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });\n    }\n}\n","import type { EmailAdapter, EmailConfig } from \"./types\";\nimport { MockEmailAdapter } from \"./mock\";\n\n/**\n * Builds the email adapter for the given provider. Providers are loaded\n * lazily via dynamic `import()` so an app only pays for (and only needs\n * installed) the SDK of the provider it actually uses.\n */\nexport async function createEmailAdapter(config: EmailConfig): Promise<EmailAdapter> {\n    switch (config.provider) {\n        case \"mock\":\n            return new MockEmailAdapter();\n        case \"smtp\": {\n            const { SmtpEmailAdapter } = await import(\"./providers/smtp\");\n            return new SmtpEmailAdapter(config);\n        }\n        case \"sendgrid\": {\n            const { SendGridEmailAdapter } = await import(\"./providers/sendgrid\");\n            return new SendGridEmailAdapter(config);\n        }\n        case \"mailgun\": {\n            const { MailgunEmailAdapter } = await import(\"./providers/mailgun\");\n            return new MailgunEmailAdapter(config);\n        }\n        case \"ses\": {\n            const { SesEmailAdapter } = await import(\"./providers/ses\");\n            return new SesEmailAdapter(config);\n        }\n        default:\n            throw new Error(`Provider ${config.provider} not implemented`);\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;AAOO,IAAM,mBAAN,MAA+C;AAAA,EAClD,MAAM,KAAK,UAAwB;AAC/B,WAAO,EAAE,WAAW,QAAQ,KAAK,IAAI,CAAC,IAAI,SAAS,KAAK;AAAA,EAC5D;AAAA,EAEA,MAAM,aAAa,MAAc,IAAuB,MAAoB;AACxE,WAAO,KAAK,KAAK,EAAE,IAAI,SAAS,aAAa,IAAI,IAAI,MAAM,YAAY,IAAI,eAAe,KAAK,UAAU,IAAI,CAAC,GAAG,CAAC;AAAA,EACtH;AACJ;;;ACPA,eAAsB,mBAAmB,QAA4C;AACjF,UAAQ,OAAO,UAAU;AAAA,IACrB,KAAK;AACD,aAAO,IAAI,iBAAiB;AAAA,IAChC,KAAK,QAAQ;AACT,YAAM,EAAE,kBAAAA,kBAAiB,IAAI,MAAM,OAAO,oBAAkB;AAC5D,aAAO,IAAIA,kBAAiB,MAAM;AAAA,IACtC;AAAA,IACA,KAAK,YAAY;AACb,YAAM,EAAE,sBAAAC,sBAAqB,IAAI,MAAM,OAAO,wBAAsB;AACpE,aAAO,IAAIA,sBAAqB,MAAM;AAAA,IAC1C;AAAA,IACA,KAAK,WAAW;AACZ,YAAM,EAAE,qBAAAC,qBAAoB,IAAI,MAAM,OAAO,uBAAqB;AAClE,aAAO,IAAIA,qBAAoB,MAAM;AAAA,IACzC;AAAA,IACA,KAAK,OAAO;AACR,YAAM,EAAE,iBAAAC,iBAAgB,IAAI,MAAM,OAAO,mBAAiB;AAC1D,aAAO,IAAIA,iBAAgB,MAAM;AAAA,IACrC;AAAA,IACA;AACI,YAAM,IAAI,MAAM,YAAY,OAAO,QAAQ,kBAAkB;AAAA,EACrE;AACJ;","names":["SmtpEmailAdapter","SendGridEmailAdapter","MailgunEmailAdapter","SesEmailAdapter"]}

package/dist/mailgun-CKVSFBJE.js

@@ -0,0 +1,7 @@
+import {
+  MailgunEmailAdapter
+} from "./chunk-P5HWUNVS.js";
+export {
+  MailgunEmailAdapter
+};
+//# sourceMappingURL=mailgun-CKVSFBJE.js.map

package/dist/mailgun-CKVSFBJE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sendgrid-EYSREU2M.js

@@ -0,0 +1,7 @@
+import {
+  SendGridEmailAdapter
+} from "./chunk-4256VN6L.js";
+export {
+  SendGridEmailAdapter
+};
+//# sourceMappingURL=sendgrid-EYSREU2M.js.map

package/dist/sendgrid-EYSREU2M.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/ses-KGJG5IB5.js

@@ -0,0 +1,7 @@
+import {
+  SesEmailAdapter
+} from "./chunk-H6SSV4G4.js";
+export {
+  SesEmailAdapter
+};
+//# sourceMappingURL=ses-KGJG5IB5.js.map

package/dist/ses-KGJG5IB5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/smtp-GZ4DZMCQ.js

@@ -0,0 +1,7 @@
+import {
+  SmtpEmailAdapter
+} from "./chunk-4Y2FQY2L.js";
+export {
+  SmtpEmailAdapter
+};
+//# sourceMappingURL=smtp-GZ4DZMCQ.js.map

package/dist/smtp-GZ4DZMCQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,60 @@
+{
+    "name": "@iskra-bun/mailer-kit",
+    "version": "0.1.0",
+    "description": "Envio de correo de Iskra, agnostico del transporte, con adaptadores de SMTP, SendGrid, Mailgun y SES.",
+    "keywords": [
+        "iskra",
+        "bun",
+        "email",
+        "smtp",
+        "sendgrid",
+        "mailgun",
+        "ses"
+    ],
+    "author": "Joan Lascano",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fearful/iskra.git",
+        "directory": "packages/mailer-kit"
+    },
+    "homepage": "https://github.com/fearful/iskra/tree/main/packages/mailer-kit#readme",
+    "bugs": "https://github.com/fearful/iskra/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "build": "tsup --config ../../tsup.config.ts"
+    },
+    "dependencies": {
+        "@iskra-bun/core": "0.1.1",
+        "@aws-sdk/client-sesv2": "^3.600.0",
+        "@sendgrid/mail": "^8.1.0",
+        "nodemailer": "^6.9.1"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.5",
+        "@types/node": "^22.10.2",
+        "@types/nodemailer": "^7.0.4"
+    }
+}

package/src/factory.ts

@@ -0,0 +1,32 @@
+import type { EmailAdapter, EmailConfig } from "./types";
+import { MockEmailAdapter } from "./mock";
+
+/**
+ * Builds the email adapter for the given provider. Providers are loaded
+ * lazily via dynamic `import()` so an app only pays for (and only needs
+ * installed) the SDK of the provider it actually uses.
+ */
+export async function createEmailAdapter(config: EmailConfig): Promise<EmailAdapter> {
+    switch (config.provider) {
+        case "mock":
+            return new MockEmailAdapter();
+        case "smtp": {
+            const { SmtpEmailAdapter } = await import("./providers/smtp");
+            return new SmtpEmailAdapter(config);
+        }
+        case "sendgrid": {
+            const { SendGridEmailAdapter } = await import("./providers/sendgrid");
+            return new SendGridEmailAdapter(config);
+        }
+        case "mailgun": {
+            const { MailgunEmailAdapter } = await import("./providers/mailgun");
+            return new MailgunEmailAdapter(config);
+        }
+        case "ses": {
+            const { SesEmailAdapter } = await import("./providers/ses");
+            return new SesEmailAdapter(config);
+        }
+        default:
+            throw new Error(`Provider ${config.provider} not implemented`);
+    }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { EmailConfig, EmailMessage, TemplateData, EmailAdapter } from "./types";
+export { MockEmailAdapter } from "./mock";
+export { createEmailAdapter } from "./factory";
+export { SmtpEmailAdapter } from "./providers/smtp";
+export { SendGridEmailAdapter } from "./providers/sendgrid";
+export { MailgunEmailAdapter } from "./providers/mailgun";
+export { SesEmailAdapter } from "./providers/ses";
+export type { SesClient, SesCommand, SesCommandFactory, SesAdapterDeps } from "./providers/ses";

package/src/mock.ts

@@ -0,0 +1,16 @@
+import type { EmailAdapter, EmailMessage, TemplateData } from "./types";
+
+/**
+ * In-memory email adapter used for tests and local development.
+ * It performs no network I/O and stays silent (no stdout) so it is
+ * safe to use inside library code and background workers.
+ */
+export class MockEmailAdapter implements EmailAdapter {
+    async send(_message: EmailMessage) {
+        return { messageId: `mock-${Date.now()}`, success: true };
+    }
+
+    async sendTemplate(name: string, to: string | string[], data: TemplateData) {
+        return this.send({ to, subject: `Template: ${name}`, html: `Template ${name} with data: ${JSON.stringify(data)}` });
+    }
+}

package/src/providers/mailgun.ts

@@ -0,0 +1,101 @@
+import type { EmailAdapter, EmailMessage, EmailConfig, TemplateData } from "../types";
+
+/**
+ * Outbound custom mail headers callers are permitted to set. Anything outside
+ * this set is rejected so a caller cannot spoof Reply-To / Sender / routing
+ * headers via the generic `headers` map.
+ */
+const ALLOWED_HEADERS = new Set([
+    "reply-to",
+    "in-reply-to",
+    "references",
+    "list-unsubscribe",
+    "list-unsubscribe-post",
+    "list-id",
+    "x-mailgun-variables",
+    "x-mailgun-tag",
+]);
+
+/**
+ * Truncate a header value at the first CR/LF. Anything after a line break is an
+ * injected header (or folded continuation) and must be dropped, not preserved.
+ */
+const stripCrlf = (value: string): string => value.split(/[\r\n]/)[0] ?? "";
+
+export class MailgunEmailAdapter implements EmailAdapter {
+    private apiKey: string;
+    private domain: string;
+    private baseUrl: string;
+    private defaultFrom?: { name?: string; email: string };
+
+    constructor(config: EmailConfig) {
+        if (!config.apiKey) throw new Error("Mailgun requires apiKey");
+        if (!config.domain) throw new Error("Mailgun requires domain");
+
+        this.apiKey = config.apiKey;
+        this.domain = config.domain;
+        this.baseUrl = config.baseUrl || "https://api.mailgun.net/v3";
+        this.defaultFrom = config.from;
+    }
+
+    async send(message: EmailMessage): Promise<{ messageId: string; success: boolean }> {
+        const form = new FormData();
+
+        const from = message.from || this.defaultFrom;
+        if (from) {
+            form.append("from", from.name ? `${from.name} <${from.email}>` : from.email);
+        }
+
+        const to = Array.isArray(message.to) ? message.to.join(",") : message.to;
+        form.append("to", to);
+        form.append("subject", message.subject);
+
+        if (message.text) form.append("text", message.text);
+        if (message.html) form.append("html", message.html);
+        if (message.cc) form.append("cc", Array.isArray(message.cc) ? message.cc.join(",") : message.cc);
+        if (message.bcc) form.append("bcc", Array.isArray(message.bcc) ? message.bcc.join(",") : message.bcc);
+        if (message.replyTo) form.append("h:Reply-To", message.replyTo);
+
+        if (message.headers) {
+            for (const [key, value] of Object.entries(message.headers)) {
+                if (!ALLOWED_HEADERS.has(key.toLowerCase())) {
+                    throw new Error(`Header "${key}" is not allowed`);
+                }
+                form.append(`h:${key}`, stripCrlf(value));
+            }
+        }
+
+        if (message.attachments) {
+            for (const att of message.attachments) {
+                const content = typeof att.content === "string"
+                    ? new TextEncoder().encode(att.content)
+                    : att.content;
+                const bytes = new Uint8Array(content);
+                const blob = new Blob([bytes], { type: att.contentType || "application/octet-stream" });
+                form.append("attachment", blob, att.filename);
+            }
+        }
+
+        const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
+            method: "POST",
+            headers: {
+                Authorization: "Basic " + btoa(`api:${this.apiKey}`),
+            },
+            body: form,
+        });
+
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Mailgun API error (${response.status}): ${errorText}`);
+        }
+
+        const result = await response.json() as { id: string; message: string };
+        return { messageId: result.id, success: true };
+    }
+
+    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+        // No template engine is implemented yet; fail loudly rather than
+        // silently sending a placeholder that looks like a real send.
+        throw new Error("sendTemplate not supported by mailgun");
+    }
+}

package/src/providers/sendgrid.ts

@@ -0,0 +1,40 @@
+import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from "../types";
+import sgMail from "@sendgrid/mail";
+
+export class SendGridEmailAdapter implements EmailAdapter {
+    constructor(private config: EmailConfig) {
+        if (!config.apiKey) throw new Error("SendGrid API Key required");
+        sgMail.setApiKey(config.apiKey);
+    }
+
+    async send(message: EmailMessage) {
+        const from = message.from || this.config.from;
+        if (!from) throw new Error("From address required");
+
+        const msg = {
+            to: message.to,
+            from: from.name ? { email: from.email, name: from.name } : from.email,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            cc: message.cc as any,
+            bcc: message.bcc as any,
+            replyTo: message.replyTo,
+            attachments: message.attachments?.map(a => ({
+                filename: a.filename,
+                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content).toString("base64"),
+                type: a.contentType,
+                disposition: "attachment"
+            }))
+        } as any;
+
+        const [response] = await sgMail.send(msg);
+        return { messageId: response.headers["x-message-id"] as string, success: true };
+    }
+
+    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+        // No template engine is implemented yet; fail loudly rather than
+        // silently sending a placeholder body that looks like a real send.
+        throw new Error("sendTemplate not supported by sendgrid");
+    }
+}

package/src/providers/ses.ts

@@ -0,0 +1,106 @@
+import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from "../types";
+
+/**
+ * Minimal structural shape of the value returned by
+ * `@aws-sdk/client-sesv2`'s `SendEmailCommand` constructor. We only need
+ * an opaque object to hand back to `client.send`, so typing it as an
+ * unknown-bearing record keeps `tsc` happy without the SDK installed.
+ */
+export interface SesCommand {
+    readonly input: unknown;
+}
+
+/**
+ * Structural type for the SESv2 client. Declared locally so this module
+ * type-checks even when `@aws-sdk/client-sesv2` is not installed; the real
+ * SDK client satisfies this shape at runtime.
+ */
+export interface SesClient {
+    send(command: SesCommand): Promise<{ MessageId?: string }>;
+}
+
+/** Factory that builds a `SendEmailCommand` from its input object. */
+export type SesCommandFactory = (input: unknown) => SesCommand;
+
+export interface SesAdapterDeps {
+    /** Pre-built client (used by tests to avoid importing the real SDK). */
+    client?: SesClient;
+    /** Pre-built command factory (used by tests to avoid importing the real SDK). */
+    sendEmailCommand?: SesCommandFactory;
+}
+
+export class SesEmailAdapter implements EmailAdapter {
+    private region?: string;
+    private defaultFrom?: { name?: string; email: string };
+    private injectedClient?: SesClient;
+    private injectedCommand?: SesCommandFactory;
+
+    constructor(config: EmailConfig, deps: SesAdapterDeps = {}) {
+        // The effective `from` address is validated at send time (it can come
+        // from the message or the config), so construction stays permissive.
+        this.region = config.region;
+        this.defaultFrom = config.from;
+        this.injectedClient = deps.client;
+        this.injectedCommand = deps.sendEmailCommand;
+    }
+
+    private async resolveSdk(): Promise<{ client: SesClient; command: SesCommandFactory }> {
+        if (this.injectedClient && this.injectedCommand) {
+            return { client: this.injectedClient, command: this.injectedCommand };
+        }
+
+        // Lazy load only when actually sending so `tsc`/`bun test` stay green
+        // without `@aws-sdk/client-sesv2` installed. The specifier is held in a
+        // variable so TypeScript does not try to resolve the module at compile
+        // time (it is a real runtime dependency, declared in package.json).
+        const sdkModule = "@aws-sdk/client-sesv2";
+        const mod: any = await import(sdkModule);
+        const SESv2Client = mod.SESv2Client as new (cfg: { region?: string }) => SesClient;
+        const SendEmailCommand = mod.SendEmailCommand as new (input: unknown) => SesCommand;
+
+        const client = this.injectedClient ?? new SESv2Client({ region: this.region });
+        const command: SesCommandFactory = this.injectedCommand ?? ((input) => new SendEmailCommand(input));
+
+        return { client, command };
+    }
+
+    async send(message: EmailMessage): Promise<{ messageId: string; success: boolean }> {
+        const from = message.from || this.defaultFrom;
+        if (!from) throw new Error("From address required");
+
+        const { client, command } = await this.resolveSdk();
+
+        const toAddresses = Array.isArray(message.to) ? message.to : [message.to];
+        const ccAddresses = message.cc ? (Array.isArray(message.cc) ? message.cc : [message.cc]) : undefined;
+        const bccAddresses = message.bcc ? (Array.isArray(message.bcc) ? message.bcc : [message.bcc]) : undefined;
+
+        const body: Record<string, { Data: string; Charset: string }> = {};
+        if (message.text) body.Text = { Data: message.text, Charset: "UTF-8" };
+        if (message.html) body.Html = { Data: message.html, Charset: "UTF-8" };
+
+        const input = {
+            FromEmailAddress: from.name ? `${from.name} <${from.email}>` : from.email,
+            Destination: {
+                ToAddresses: toAddresses,
+                ...(ccAddresses ? { CcAddresses: ccAddresses } : {}),
+                ...(bccAddresses ? { BccAddresses: bccAddresses } : {}),
+            },
+            ...(message.replyTo ? { ReplyToAddresses: [message.replyTo] } : {}),
+            Content: {
+                Simple: {
+                    Subject: { Data: message.subject, Charset: "UTF-8" },
+                    Body: body,
+                },
+            },
+        };
+
+        const result = await client.send(command(input));
+        return { messageId: result.MessageId ?? "", success: true };
+    }
+
+    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+        // No template engine is implemented yet; fail loudly rather than
+        // silently sending a placeholder body that looks like a real send.
+        throw new Error("sendTemplate not supported by ses");
+    }
+}

package/src/providers/smtp.ts

@@ -0,0 +1,53 @@
+import type { EmailAdapter, EmailConfig, EmailMessage, TemplateData } from "../types";
+import * as nodemailer from "nodemailer";
+
+export class SmtpEmailAdapter implements EmailAdapter {
+    private transporter: nodemailer.Transporter;
+
+    constructor(private config: EmailConfig) {
+        if (!config.smtp) throw new Error("SMTP config required");
+        // Implicit TLS on port 465; STARTTLS enforced (requireTLS) elsewhere so
+        // credentials never transit in cleartext. An explicit `secure` wins.
+        const secure = config.smtp.secure ?? config.smtp.port === 465;
+        this.transporter = nodemailer.createTransport({
+            host: config.smtp.host,
+            port: config.smtp.port,
+            secure,
+            requireTLS: secure ? undefined : true,
+            tls: { rejectUnauthorized: true },
+            auth: {
+                user: config.smtp.username,
+                pass: config.smtp.password
+            }
+        });
+    }
+
+    async send(message: EmailMessage) {
+        const from = message.from || this.config.from;
+        if (!from) throw new Error("From address required");
+
+        const info = await this.transporter.sendMail({
+            from: from.name ? `"${from.name}" <${from.email}>` : from.email,
+            to: Array.isArray(message.to) ? message.to.join(", ") : message.to,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            cc: message.cc ? (Array.isArray(message.cc) ? message.cc.join(", ") : message.cc) : undefined,
+            bcc: message.bcc ? (Array.isArray(message.bcc) ? message.bcc.join(", ") : message.bcc) : undefined,
+            replyTo: message.replyTo,
+            attachments: message.attachments?.map(a => ({
+                filename: a.filename,
+                content: typeof a.content === 'string' ? a.content : Buffer.from(a.content),
+                contentType: a.contentType
+            }))
+        });
+
+        return { messageId: (info as any).messageId, success: true };
+    }
+
+    async sendTemplate(_templateName: string, _to: string | string[], _data: TemplateData): Promise<{ messageId: string; success: boolean }> {
+        // No template engine is implemented yet; fail loudly rather than
+        // silently sending a placeholder body that looks like a real send.
+        throw new Error("sendTemplate not supported by smtp");
+    }
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+export interface EmailConfig {
+    provider: "smtp" | "sendgrid" | "mock" | "mailgun" | "ses";
+    smtp?: {
+        host: string;
+        port: number;
+        username: string;
+        password: string;
+        secure?: boolean;
+    };
+    apiKey?: string;
+    apiSecret?: string;
+    region?: string;
+    domain?: string;
+    baseUrl?: string;
+    from?: { name?: string; email: string };
+    templateDir?: string;
+}
+
+export interface EmailMessage {
+    to: string | string[];
+    from?: { name?: string; email: string };
+    subject: string;
+    text?: string;
+    html?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    attachments?: Array<{ filename: string; content: Uint8Array | string; contentType?: string }>;
+    headers?: Record<string, string>;
+}
+
+export interface TemplateData {
+    [key: string]: unknown;
+}
+
+export interface EmailAdapter {
+    send(message: EmailMessage): Promise<{ messageId: string; success: boolean }>;
+    sendTemplate(templateName: string, to: string | string[], data: TemplateData): Promise<{ messageId: string; success: boolean }>;
+}