@nymbalhq/email-smtp 0.0.0-stage → 1.5.0

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import { HealthReport, TransactionalEmail, EmailSendResult, CustomerProfile, Logger, EmailAdapter, AdapterContext, AdapterSetting } from '@nymbalhq/types';
+
+interface SmtpTransportConfig {
+    from?: string;
+    smtp?: {
+        host: string;
+        port: number;
+        user?: string;
+        pass?: string;
+        secure?: boolean;
+    };
+}
+/** The send path an email adapter that relays over SMTP shares: one lazily built nodemailer transport. */
+interface SmtpTransportSender {
+    /** Merges `config` over what the sender was built with and builds the transport, as `initialize` does. */
+    configure(config: SmtpTransportConfig): void;
+    /** The SMTP login checked, unbounded: the caller wraps it in `boundedHealthCheck`. */
+    verify(): Promise<HealthReport>;
+    sendTransactional(params: TransactionalEmail): Promise<EmailSendResult>;
+    syncCustomerToList(customer: CustomerProfile): Promise<void>;
+    removeCustomerFromList(customerId: string): Promise<void>;
+}
+declare function createSmtpTransportSender(config: SmtpTransportConfig, logger: Logger): SmtpTransportSender;
+
+type SmtpEmailAdapterConfig = SmtpTransportConfig;
+declare function createSmtpEmailAdapter(deps: {
+    logger: Logger;
+    config?: SmtpEmailAdapterConfig;
+}): EmailAdapter;
+
+/** What this package serves: the kernel refuses it on any other slot or provider. */
+declare const slot = "email";
+declare const provider = "smtp";
+
+/** The SMTP login the admin's Settings may fill; a server that takes mail without one needs neither. */
+declare const settings: AdapterSetting[];
+/** The kernel's entry: `email: { provider: 'smtp', config: SmtpEmailAdapterConfig }`. */
+declare function createAdapter(ctx: AdapterContext): EmailAdapter;
+
+export { createAdapter, createSmtpEmailAdapter, createSmtpTransportSender, provider, settings, slot };
+export type { SmtpEmailAdapterConfig, SmtpTransportConfig, SmtpTransportSender };

package/dist/index.js

@@ -0,0 +1,127 @@
+// src/index.ts
+import {
+  ConfigError
+} from "@nymbalhq/types";
+
+// src/smtp-adapter.ts
+import {
+  boundedHealthCheck,
+  EVT_CART_ABANDONED,
+  EVT_CUSTOMER_CREATED,
+  EVT_ORDER_PLACED,
+  EVT_ORDER_SHIPPED
+} from "@nymbalhq/types";
+
+// src/smtp-transport-sender.ts
+import nodemailer from "nodemailer";
+import {
+  AdapterError,
+  errorText,
+  renderEmailTemplate
+} from "@nymbalhq/types";
+var SMTP_TIMEOUT_MS = 4e3;
+function createSmtpTransportSender(config, logger) {
+  let cfg = config;
+  let transporter = null;
+  function ensureTransport() {
+    if (transporter) return transporter;
+    if (!cfg.smtp) {
+      throw new AdapterError("email.misconfigured", "SMTP provider selected but smtp.host not set");
+    }
+    transporter = nodemailer.createTransport({
+      host: cfg.smtp.host,
+      port: cfg.smtp.port,
+      secure: cfg.smtp.secure ?? cfg.smtp.port === 465,
+      // nodemailer waits two minutes to connect by default; a host that drops packets must fail inside the 6 s bound.
+      connectionTimeout: SMTP_TIMEOUT_MS,
+      greetingTimeout: SMTP_TIMEOUT_MS,
+      socketTimeout: SMTP_TIMEOUT_MS,
+      ...cfg.smtp.user !== void 0 && cfg.smtp.pass !== void 0 ? { auth: { user: cfg.smtp.user, pass: cfg.smtp.pass } } : {}
+    });
+    return transporter;
+  }
+  return {
+    configure(next) {
+      cfg = { ...cfg, ...next };
+      ensureTransport();
+    },
+    async verify() {
+      try {
+        await ensureTransport().verify();
+        return { status: "healthy", detail: "SMTP verified" };
+      } catch (err) {
+        const reachable = err?.code === "EAUTH";
+        return {
+          status: reachable ? "degraded" : "down",
+          detail: `SMTP verify failed: ${errorText(err)}`
+        };
+      }
+    },
+    async sendTransactional(params) {
+      const rendered = renderEmailTemplate(params.template, params.vars);
+      const info = await ensureTransport().sendMail({
+        from: cfg.from ?? "no-reply@nymbal.dev",
+        to: params.to,
+        subject: rendered.subject,
+        text: rendered.text,
+        html: rendered.html
+      });
+      return { messageId: info.messageId ?? null, accepted: (info.accepted ?? []).length > 0 };
+    },
+    async syncCustomerToList(customer) {
+      logger.debug({ customerId: customer.customerId }, "email.syncCustomerToList (stub)");
+    },
+    async removeCustomerFromList(customerId) {
+      logger.debug({ customerId }, "email.removeCustomerFromList (stub)");
+    }
+  };
+}
+
+// src/smtp-adapter.ts
+function createSmtpEmailAdapter(deps) {
+  const log = deps.logger.child({ adapter: "email", provider: "smtp" });
+  const sender = createSmtpTransportSender(deps.config ?? {}, log);
+  return {
+    kind: "email",
+    providerName: "smtp",
+    capabilities: () => ["transactional", "list-sync"],
+    producesEvents: [],
+    consumesEvents: [EVT_ORDER_PLACED, EVT_ORDER_SHIPPED, EVT_CUSTOMER_CREATED, EVT_CART_ABANDONED],
+    async initialize(rawConfig) {
+      sender.configure(rawConfig);
+    },
+    healthCheck: () => boundedHealthCheck(() => sender.verify()),
+    sendTransactional: (params) => sender.sendTransactional(params),
+    syncCustomerToList: (customer) => sender.syncCustomerToList(customer),
+    removeCustomerFromList: (customerId) => sender.removeCustomerFromList(customerId)
+  };
+}
+
+// src/index.ts
+var slot = "email";
+var provider = "smtp";
+var settings = [
+  { path: "smtp.user", label: "SMTP user", secret: true, optional: true },
+  { path: "smtp.pass", label: "SMTP password", secret: true, optional: true }
+];
+function createAdapter(ctx) {
+  if (ctx.slot !== "email") {
+    throw new ConfigError(`@nymbalhq/email-smtp serves email, not ${ctx.slot}`, {
+      code: "adapter.wrong_slot",
+      context: { slot: ctx.slot }
+    });
+  }
+  return createSmtpEmailAdapter({
+    logger: ctx.logger,
+    config: ctx.config
+  });
+}
+export {
+  createAdapter,
+  createSmtpEmailAdapter,
+  createSmtpTransportSender,
+  provider,
+  settings,
+  slot
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/smtp-adapter.ts","../src/smtp-transport-sender.ts"],"sourcesContent":["import {\n  ConfigError,\n  type AdapterContext,\n  type AdapterSetting,\n  type EmailAdapter,\n} from '@nymbalhq/types'\nimport { createSmtpEmailAdapter, type SmtpEmailAdapterConfig } from './smtp-adapter.js'\n\n/** What this package serves: the kernel refuses it on any other slot or provider. */\nexport const slot = 'email'\nexport const provider = 'smtp'\n\nexport { createSmtpEmailAdapter, type SmtpEmailAdapterConfig }\nexport {\n  createSmtpTransportSender,\n  type SmtpTransportConfig,\n  type SmtpTransportSender,\n} from './smtp-transport-sender.js'\n\n/** The SMTP login the admin's Settings may fill; a server that takes mail without one needs neither. */\nexport const settings: AdapterSetting[] = [\n  { path: 'smtp.user', label: 'SMTP user', secret: true, optional: true },\n  { path: 'smtp.pass', label: 'SMTP password', secret: true, optional: true },\n]\n\n/** The kernel's entry: `email: { provider: 'smtp', config: SmtpEmailAdapterConfig }`. */\nexport function createAdapter(ctx: AdapterContext): EmailAdapter {\n  if (ctx.slot !== 'email') {\n    throw new ConfigError(`@nymbalhq/email-smtp serves email, not ${ctx.slot}`, {\n      code: 'adapter.wrong_slot',\n      context: { slot: ctx.slot },\n    })\n  }\n  return createSmtpEmailAdapter({\n    logger: ctx.logger,\n    config: ctx.config as SmtpEmailAdapterConfig,\n  })\n}\n","import {\n  boundedHealthCheck,\n  EVT_CART_ABANDONED,\n  EVT_CUSTOMER_CREATED,\n  EVT_ORDER_PLACED,\n  EVT_ORDER_SHIPPED,\n  type EmailAdapter,\n  type Logger,\n} from '@nymbalhq/types'\nimport { createSmtpTransportSender, type SmtpTransportConfig } from './smtp-transport-sender.js'\n\nexport type SmtpEmailAdapterConfig = SmtpTransportConfig\n\nexport function createSmtpEmailAdapter(deps: {\n  logger: Logger\n  config?: SmtpEmailAdapterConfig\n}): EmailAdapter {\n  const log = deps.logger.child({ adapter: 'email', provider: 'smtp' })\n  const sender = createSmtpTransportSender(deps.config ?? {}, log)\n\n  return {\n    kind: 'email',\n    providerName: 'smtp',\n    capabilities: () => ['transactional', 'list-sync'],\n    producesEvents: [],\n    consumesEvents: [EVT_ORDER_PLACED, EVT_ORDER_SHIPPED, EVT_CUSTOMER_CREATED, EVT_CART_ABANDONED],\n    async initialize(rawConfig) {\n      sender.configure(rawConfig as SmtpEmailAdapterConfig)\n    },\n    healthCheck: () => boundedHealthCheck(() => sender.verify()),\n    sendTransactional: (params) => sender.sendTransactional(params),\n    syncCustomerToList: (customer) => sender.syncCustomerToList(customer),\n    removeCustomerFromList: (customerId) => sender.removeCustomerFromList(customerId),\n  }\n}\n","import nodemailer, { type Transporter } from 'nodemailer'\nimport {\n  AdapterError,\n  errorText,\n  renderEmailTemplate,\n  type CustomerProfile,\n  type EmailSendResult,\n  type HealthReport,\n  type Logger,\n  type TransactionalEmail,\n} from '@nymbalhq/types'\n\nconst SMTP_TIMEOUT_MS = 4000\n\nexport interface SmtpTransportConfig {\n  from?: string\n  smtp?: {\n    host: string\n    port: number\n    user?: string\n    pass?: string\n    secure?: boolean\n  }\n}\n\n/** The send path an email adapter that relays over SMTP shares: one lazily built nodemailer transport. */\nexport interface SmtpTransportSender {\n  /** Merges `config` over what the sender was built with and builds the transport, as `initialize` does. */\n  configure(config: SmtpTransportConfig): void\n  /** The SMTP login checked, unbounded: the caller wraps it in `boundedHealthCheck`. */\n  verify(): Promise<HealthReport>\n  sendTransactional(params: TransactionalEmail): Promise<EmailSendResult>\n  syncCustomerToList(customer: CustomerProfile): Promise<void>\n  removeCustomerFromList(customerId: string): Promise<void>\n}\n\nexport function createSmtpTransportSender(\n  config: SmtpTransportConfig,\n  logger: Logger,\n): SmtpTransportSender {\n  let cfg: SmtpTransportConfig = config\n  let transporter: Transporter | null = null\n\n  function ensureTransport(): Transporter {\n    if (transporter) return transporter\n    if (!cfg.smtp) {\n      throw new AdapterError('email.misconfigured', 'SMTP provider selected but smtp.host not set')\n    }\n    transporter = nodemailer.createTransport({\n      host: cfg.smtp.host,\n      port: cfg.smtp.port,\n      secure: cfg.smtp.secure ?? cfg.smtp.port === 465,\n      // nodemailer waits two minutes to connect by default; a host that drops packets must fail inside the 6 s bound.\n      connectionTimeout: SMTP_TIMEOUT_MS,\n      greetingTimeout: SMTP_TIMEOUT_MS,\n      socketTimeout: SMTP_TIMEOUT_MS,\n      ...(cfg.smtp.user !== undefined && cfg.smtp.pass !== undefined\n        ? { auth: { user: cfg.smtp.user, pass: cfg.smtp.pass } }\n        : {}),\n    })\n    return transporter\n  }\n\n  return {\n    configure(next) {\n      cfg = { ...cfg, ...next }\n      ensureTransport()\n    },\n\n    async verify() {\n      try {\n        await ensureTransport().verify()\n        return { status: 'healthy', detail: 'SMTP verified' }\n      } catch (err) {\n        // A server that answers and refuses the login is there but unusable; one that cannot be reached is down.\n        const reachable = (err as { code?: unknown } | null)?.code === 'EAUTH'\n        return {\n          status: reachable ? 'degraded' : 'down',\n          detail: `SMTP verify failed: ${errorText(err)}`,\n        }\n      }\n    },\n\n    async sendTransactional(params) {\n      const rendered = renderEmailTemplate(params.template, params.vars)\n      const info = await ensureTransport().sendMail({\n        from: cfg.from ?? 'no-reply@nymbal.dev',\n        to: params.to,\n        subject: rendered.subject,\n        text: rendered.text,\n        html: rendered.html,\n      })\n      return { messageId: info.messageId ?? null, accepted: (info.accepted ?? []).length > 0 }\n    },\n\n    async syncCustomerToList(customer) {\n      logger.debug({ customerId: customer.customerId }, 'email.syncCustomerToList (stub)')\n    },\n\n    async removeCustomerFromList(customerId) {\n      logger.debug({ customerId }, 'email.removeCustomerFromList (stub)')\n    },\n  }\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,OAIK;;;ACLP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;;;ACRP,OAAO,gBAAsC;AAC7C;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AAEP,IAAM,kBAAkB;AAwBjB,SAAS,0BACd,QACA,QACqB;AACrB,MAAI,MAA2B;AAC/B,MAAI,cAAkC;AAEtC,WAAS,kBAA+B;AACtC,QAAI,YAAa,QAAO;AACxB,QAAI,CAAC,IAAI,MAAM;AACb,YAAM,IAAI,aAAa,uBAAuB,8CAA8C;AAAA,IAC9F;AACA,kBAAc,WAAW,gBAAgB;AAAA,MACvC,MAAM,IAAI,KAAK;AAAA,MACf,MAAM,IAAI,KAAK;AAAA,MACf,QAAQ,IAAI,KAAK,UAAU,IAAI,KAAK,SAAS;AAAA;AAAA,MAE7C,mBAAmB;AAAA,MACnB,iBAAiB;AAAA,MACjB,eAAe;AAAA,MACf,GAAI,IAAI,KAAK,SAAS,UAAa,IAAI,KAAK,SAAS,SACjD,EAAE,MAAM,EAAE,MAAM,IAAI,KAAK,MAAM,MAAM,IAAI,KAAK,KAAK,EAAE,IACrD,CAAC;AAAA,IACP,CAAC;AACD,WAAO;AAAA,EACT;AAEA,SAAO;AAAA,IACL,UAAU,MAAM;AACd,YAAM,EAAE,GAAG,KAAK,GAAG,KAAK;AACxB,sBAAgB;AAAA,IAClB;AAAA,IAEA,MAAM,SAAS;AACb,UAAI;AACF,cAAM,gBAAgB,EAAE,OAAO;AAC/B,eAAO,EAAE,QAAQ,WAAW,QAAQ,gBAAgB;AAAA,MACtD,SAAS,KAAK;AAEZ,cAAM,YAAa,KAAmC,SAAS;AAC/D,eAAO;AAAA,UACL,QAAQ,YAAY,aAAa;AAAA,UACjC,QAAQ,uBAAuB,UAAU,GAAG,CAAC;AAAA,QAC/C;AAAA,MACF;AAAA,IACF;AAAA,IAEA,MAAM,kBAAkB,QAAQ;AAC9B,YAAM,WAAW,oBAAoB,OAAO,UAAU,OAAO,IAAI;AACjE,YAAM,OAAO,MAAM,gBAAgB,EAAE,SAAS;AAAA,QAC5C,MAAM,IAAI,QAAQ;AAAA,QAClB,IAAI,OAAO;AAAA,QACX,SAAS,SAAS;AAAA,QAClB,MAAM,SAAS;AAAA,QACf,MAAM,SAAS;AAAA,MACjB,CAAC;AACD,aAAO,EAAE,WAAW,KAAK,aAAa,MAAM,WAAW,KAAK,YAAY,CAAC,GAAG,SAAS,EAAE;AAAA,IACzF;AAAA,IAEA,MAAM,mBAAmB,UAAU;AACjC,aAAO,MAAM,EAAE,YAAY,SAAS,WAAW,GAAG,iCAAiC;AAAA,IACrF;AAAA,IAEA,MAAM,uBAAuB,YAAY;AACvC,aAAO,MAAM,EAAE,WAAW,GAAG,qCAAqC;AAAA,IACpE;AAAA,EACF;AACF;;;AD1FO,SAAS,uBAAuB,MAGtB;AACf,QAAM,MAAM,KAAK,OAAO,MAAM,EAAE,SAAS,SAAS,UAAU,OAAO,CAAC;AACpE,QAAM,SAAS,0BAA0B,KAAK,UAAU,CAAC,GAAG,GAAG;AAE/D,SAAO;AAAA,IACL,MAAM;AAAA,IACN,cAAc;AAAA,IACd,cAAc,MAAM,CAAC,iBAAiB,WAAW;AAAA,IACjD,gBAAgB,CAAC;AAAA,IACjB,gBAAgB,CAAC,kBAAkB,mBAAmB,sBAAsB,kBAAkB;AAAA,IAC9F,MAAM,WAAW,WAAW;AAC1B,aAAO,UAAU,SAAmC;AAAA,IACtD;AAAA,IACA,aAAa,MAAM,mBAAmB,MAAM,OAAO,OAAO,CAAC;AAAA,IAC3D,mBAAmB,CAAC,WAAW,OAAO,kBAAkB,MAAM;AAAA,IAC9D,oBAAoB,CAAC,aAAa,OAAO,mBAAmB,QAAQ;AAAA,IACpE,wBAAwB,CAAC,eAAe,OAAO,uBAAuB,UAAU;AAAA,EAClF;AACF;;;ADzBO,IAAM,OAAO;AACb,IAAM,WAAW;AAUjB,IAAM,WAA6B;AAAA,EACxC,EAAE,MAAM,aAAa,OAAO,aAAa,QAAQ,MAAM,UAAU,KAAK;AAAA,EACtE,EAAE,MAAM,aAAa,OAAO,iBAAiB,QAAQ,MAAM,UAAU,KAAK;AAC5E;AAGO,SAAS,cAAc,KAAmC;AAC/D,MAAI,IAAI,SAAS,SAAS;AACxB,UAAM,IAAI,YAAY,0CAA0C,IAAI,IAAI,IAAI;AAAA,MAC1E,MAAM;AAAA,MACN,SAAS,EAAE,MAAM,IAAI,KAAK;AAAA,IAC5B,CAAC;AAAA,EACH;AACA,SAAO,uBAAuB;AAAA,IAC5B,QAAQ,IAAI;AAAA,IACZ,QAAQ,IAAI;AAAA,EACd,CAAC;AACH;","names":[]}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@nymbalhq/email-smtp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.5.0",
+  "description": "SMTP email for Nymbal: the `smtp` email provider (nodemailer)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nymbalhq/nymbal.git",
+    "directory": "packages/adapters/email/smtp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@nymbalhq/types": "^1.5.0",
+    "nodemailer": "^6.9.16"
+  },
+  "devDependencies": {
+    "@nymbalhq/types": "1.5.0",
+    "@types/nodemailer": "^6.4.17",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "nodemailer": "^6.9.16",
+    "tsup": "^9.0.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit --rootDir ../../../.."
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.