@core-tecnologias-empresariales/core-mail 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @core-tecnologias-empresariales/core-mail
+
+Envío de correo del ecosistema Core Tecnología Empresarial. Motor de transporte: [Nodemailer](https://nodemailer.com/) (SMTP, sin dependencia de un proveedor específico).
+
+## Para qué sirve
+
+**Fallback multi-SMTP** (CLAUDE.md §13/§74) — lo que este paquete aporta sobre usar Nodemailer directo:
+
+```text
+SMTP principal → falló → SMTP secundario → falló → SMTP terciario
+```
+
+## API
+
+```ts
+import { createMailer, createSmtpTransport } from "@core-tecnologias-empresariales/core-mail";
+
+const mailer = createMailer([
+  createSmtpTransport({ name: "principal", host: "smtp1.example.com", port: 587, auth: { user, pass } }),
+  createSmtpTransport({ name: "backup", host: "smtp2.example.com", port: 587, auth: { user: user2, pass: pass2 } }),
+]);
+
+const { transport } = await mailer.send({
+  to: "user@example.com",
+  from: "noreply@core.dev",
+  subject: "Recuperación de contraseña",
+  html: "<p>Tu código: 483920</p>",
+});
+// transport === "principal" (o "backup" si el principal falló)
+```
+
+Si todos los transportes fallan, `mailer.send()` lanza `MailDeliveryError` con `attemptedTransports` (los nombres, en orden) y `cause` (el último error real) — nunca se pierde el correo silenciosamente.
+
+### Seguridad
+
+Las credenciales SMTP (`auth.user`/`auth.pass`) nunca se hardcodean: se inyectan desde environment variables o un secret manager al llamar `createSmtpTransport()` — este paquete no las persiste ni las expone.
+
+## Para qué NO sirve (`ponytail:` diferido)
+
+- **Templates.** CLAUDE.md deja templates como responsabilidad de cada producto cuando el contenido es específico del negocio; v0.1 no incluye un motor de templates especulativo.
+- **Categorización por tipo de correo** (transactional/security/notification) y **priorización de correos críticos** — se agregan cuando exista un consumidor real (probablemente junto con `core-notifications`).
+
+## Instalación
+
+```bash
+pnpm add @core-tecnologias-empresariales/core-mail
+```
+
+## Desarrollo
+
+```bash
+pnpm build
+pnpm test
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createMailer, MailDeliveryError } from "./mailer.js";
+export type { Mailer } from "./mailer.js";
+export { createSmtpTransport } from "./smtp-transport.js";
+export type { SmtpConfig } from "./smtp-transport.js";
+export type { MailMessage, MailTransport } from "./transport.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createMailer, MailDeliveryError } from "./mailer.js";
+export { createSmtpTransport } from "./smtp-transport.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,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/mailer.d.ts

@@ -0,0 +1,16 @@
+import type { MailMessage, MailTransport } from "./transport.js";
+export declare class MailDeliveryError extends Error {
+    readonly attemptedTransports: string[];
+    readonly cause: unknown;
+    constructor(attemptedTransports: string[], cause: unknown);
+}
+export interface Mailer {
+    send(message: MailMessage): Promise<{
+        transport: string;
+    }>;
+}
+/**
+ * Orquesta varios `MailTransport` con fallback en orden (CLAUDE.md §13/§74):
+ * SMTP 1 → falló → SMTP 2 → falló → SMTP 3. Se detiene en el primero que envía con éxito.
+ */
+export declare function createMailer(transports: MailTransport[]): Mailer;

package/dist/mailer.js

@@ -0,0 +1,35 @@
+export class MailDeliveryError extends Error {
+    attemptedTransports;
+    cause;
+    constructor(attemptedTransports, cause) {
+        super(`No se pudo enviar el correo tras intentar: ${attemptedTransports.join(", ")}`);
+        this.name = "MailDeliveryError";
+        this.attemptedTransports = attemptedTransports;
+        this.cause = cause;
+    }
+}
+/**
+ * Orquesta varios `MailTransport` con fallback en orden (CLAUDE.md §13/§74):
+ * SMTP 1 → falló → SMTP 2 → falló → SMTP 3. Se detiene en el primero que envía con éxito.
+ */
+export function createMailer(transports) {
+    if (transports.length === 0) {
+        throw new Error("createMailer requiere al menos un MailTransport");
+    }
+    return {
+        async send(message) {
+            let lastError;
+            for (const transport of transports) {
+                try {
+                    await transport.send(message);
+                    return { transport: transport.name };
+                }
+                catch (error) {
+                    lastError = error;
+                }
+            }
+            throw new MailDeliveryError(transports.map((t) => t.name), lastError);
+        },
+    };
+}
+//# sourceMappingURL=mailer.js.map

package/dist/mailer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer.js","sourceRoot":"","sources":["../src/mailer.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,mBAAmB,CAAW;IACrB,KAAK,CAAU;IAEjC,YAAY,mBAA6B,EAAE,KAAc;QACvD,KAAK,CAAC,8CAA8C,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,mBAAmB,GAAG,mBAAmB,CAAC;QAC/C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAMD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,UAA2B;IACtD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,OAAO;YAChB,IAAI,SAAkB,CAAC;YACvB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAC9B,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,IAAI,EAAE,CAAC;gBACvC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,SAAS,GAAG,KAAK,CAAC;gBACpB,CAAC;YACH,CAAC;YACD,MAAM,IAAI,iBAAiB,CACzB,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAC7B,SAAS,CACV,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/mailer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mailer.test.js

@@ -0,0 +1,35 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createMailer, MailDeliveryError } from "./mailer.js";
+function fakeTransport(name, behavior) {
+    return {
+        name,
+        async send() {
+            if (behavior === "fail")
+                throw new Error(`${name} down`);
+        },
+    };
+}
+const message = { to: "user@example.com", from: "noreply@core.dev", subject: "hola" };
+test("sends via the first working transport", async () => {
+    const mailer = createMailer([fakeTransport("primary", "ok"), fakeTransport("secondary", "ok")]);
+    const result = await mailer.send(message);
+    assert.equal(result.transport, "primary");
+});
+test("falls back to the next transport when the first fails", async () => {
+    const mailer = createMailer([fakeTransport("primary", "fail"), fakeTransport("secondary", "ok")]);
+    const result = await mailer.send(message);
+    assert.equal(result.transport, "secondary");
+});
+test("throws MailDeliveryError listing every attempted transport when all fail", async () => {
+    const mailer = createMailer([fakeTransport("primary", "fail"), fakeTransport("secondary", "fail")]);
+    await assert.rejects(() => mailer.send(message), (error) => {
+        assert.ok(error instanceof MailDeliveryError);
+        assert.deepEqual(error.attemptedTransports, ["primary", "secondary"]);
+        return true;
+    });
+});
+test("createMailer requires at least one transport", () => {
+    assert.throws(() => createMailer([]));
+});
+//# sourceMappingURL=mailer.test.js.map

package/dist/mailer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailer.test.js","sourceRoot":"","sources":["../src/mailer.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG9D,SAAS,aAAa,CAAC,IAAY,EAAE,QAAuB;IAC1D,OAAO;QACL,IAAI;QACJ,KAAK,CAAC,IAAI;YACR,IAAI,QAAQ,KAAK,MAAM;gBAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,OAAO,CAAC,CAAC;QAC3D,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,GAAgB,EAAE,EAAE,EAAE,kBAAkB,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAEnG,IAAI,CAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;IACvD,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAChG,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAC5C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;IACvE,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IAClG,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAC9C,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0EAA0E,EAAE,KAAK,IAAI,EAAE;IAC1F,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACpG,MAAM,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,KAAc,EAAE,EAAE;QAClE,MAAM,CAAC,EAAE,CAAC,KAAK,YAAY,iBAAiB,CAAC,CAAC;QAC9C,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,mBAAmB,EAAE,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,8CAA8C,EAAE,GAAG,EAAE;IACxD,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC,CAAC,CAAC"}

package/dist/smtp-transport.d.ts

@@ -0,0 +1,14 @@
+import type { MailTransport } from "./transport.js";
+export interface SmtpConfig {
+    name: string;
+    host: string;
+    port: number;
+    secure?: boolean;
+    /** Credenciales: nunca hardcodear — inyectar desde environment variables o secret manager (CLAUDE.md §76). */
+    auth?: {
+        user: string;
+        pass: string;
+    };
+}
+/** Transporte SMTP concreto sobre Nodemailer. */
+export declare function createSmtpTransport(config: SmtpConfig): MailTransport;

package/dist/smtp-transport.js

@@ -0,0 +1,17 @@
+import nodemailer from "nodemailer";
+/** Transporte SMTP concreto sobre Nodemailer. */
+export function createSmtpTransport(config) {
+    const transporter = nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: config.auth,
+    });
+    return {
+        name: config.name,
+        async send(message) {
+            await transporter.sendMail(message);
+        },
+    };
+}
+//# sourceMappingURL=smtp-transport.js.map

package/dist/smtp-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-transport.js","sourceRoot":"","sources":["../src/smtp-transport.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AAYpC,iDAAiD;AACjD,MAAM,UAAU,mBAAmB,CAAC,MAAkB;IACpD,MAAM,WAAW,GAAG,UAAU,CAAC,eAAe,CAAC;QAC7C,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI;KAClB,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,CAAC,IAAI,CAAC,OAAO;YAChB,MAAM,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/smtp-transport.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/smtp-transport.test.js

@@ -0,0 +1,9 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createSmtpTransport } from "./smtp-transport.js";
+test("createSmtpTransport returns a MailTransport with the given name", () => {
+    const transport = createSmtpTransport({ name: "principal", host: "smtp.example.com", port: 587 });
+    assert.equal(transport.name, "principal");
+    assert.equal(typeof transport.send, "function");
+});
+//# sourceMappingURL=smtp-transport.test.js.map

package/dist/smtp-transport.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp-transport.test.js","sourceRoot":"","sources":["../src/smtp-transport.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE1D,IAAI,CAAC,iEAAiE,EAAE,GAAG,EAAE;IAC3E,MAAM,SAAS,GAAG,mBAAmB,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IAClG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC1C,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAClD,CAAC,CAAC,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,13 @@
+export interface MailMessage {
+    to: string | string[];
+    from: string;
+    subject: string;
+    html?: string;
+    text?: string;
+    replyTo?: string;
+}
+/** Un canal de envío concreto (un SMTP configurado). `core-mail` orquesta varios vía `createMailer()`. */
+export interface MailTransport {
+    name: string;
+    send(message: MailMessage): Promise<void>;
+}

package/dist/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@core-tecnologias-empresariales/core-mail",
+  "version": "0.1.0",
+  "description": "Envío de correo con múltiples SMTP y fallback para el ecosistema Core Tecnología Empresarial.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "nodemailer": "^6.9.16"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^20.14.0",
+    "@types/nodemailer": "^6.4.16"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test dist"
+  }
+}