@mailerport/service 0.1.0

package/bin/mailport-service.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { createMailService } from "../dist/index.js";
+const service=createMailService({host:process.env.HOST||"0.0.0.0"});
+await service.start();
+const shutdown=async()=>{await service.stop();process.exit(0);};
+process.on("SIGTERM",shutdown);process.on("SIGINT",shutdown);

package/dist/delivery-events.js

@@ -0,0 +1,19 @@
+import { MailPortError, ERROR_CODES } from "@mailerport/core";
+
+export function createDeliveryEventSource({ mail, operations, suppressHardBounces = true, suppressComplaints = true } = {}) {
+  return {
+    async consume(input) {
+      const type = input.type || input.event_type;
+      if (!["delivered", "bounced", "complained"].includes(type))
+        throw new MailPortError(ERROR_CODES.MAIL_DELIVERY_FAILED, `Unsupported delivery event: ${type}`);
+      const message = await mail.recordDeliveryEvent({ ...input, type });
+      if (!message) return null;
+      const shouldSuppress = (type === "bounced" && input.bounce_type === "hard" && suppressHardBounces) ||
+        (type === "complained" && suppressComplaints);
+      if (shouldSuppress && input.recipient) operations.addSuppression({ email: input.recipient,
+        application_id: message.application_id, tenant_id: message.tenant_id,
+        reason: type === "complained" ? "complaint" : "hard_bounce", source: "delivery_event" });
+      return message;
+    },
+  };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import type { MailPort } from "@mailerport/sdk";
+export interface MailServiceOptions { host?:string;port?:number;apiKey?:string;adminKey?:string;applicationId?:string;production?:boolean;transport?:string|Record<string,unknown>;outbox?:{filePath?:string};worker?:{enabled?:boolean;concurrency?:number;pollIntervalMs?:number;leaseMs?:number;maxAttempts?:number};identities?:Record<string,string>;templates?:Record<string,unknown>;testEndpointsEnabled?:boolean;environment?:Record<string,string|undefined> }
+export interface MailService { mail:MailPort;operations:unknown;start():Promise<void>;stop():Promise<void> }
+export function createMailService(options?:MailServiceOptions):MailService;
+export function createMailPortService(mail:MailPort,options?:Record<string,unknown>):Pick<MailService,"start"|"stop">;
+export class FileOperationsStore { constructor(options?:Record<string,unknown>); }
+export function createDeliveryEventSource(options:Record<string,unknown>):{consume(event:Record<string,unknown>):Promise<unknown>};
+export function validateProductionConfig(options?:Record<string,unknown>,environment?:Record<string,string|undefined>):{production:boolean};

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createMailService } from "./service.js";
+export { createMailPortService } from "./remote-service.js";
+export { FileOperationsStore } from "./operations.js";
+export { createDeliveryEventSource } from "./delivery-events.js";
+export { validateProductionConfig } from "./production-config.js";

package/dist/operations.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto, { randomUUID } from "node:crypto";
+import dns from "node:dns/promises";
+import { MailPortError, ERROR_CODES } from "@mailerport/core";
+
+const clone = (value) => structuredClone(value);
+const now = () => new Date().toISOString();
+const normalizeEmail = (email) => String(email).trim().toLowerCase();
+
+export class FileOperationsStore {
+  constructor({ filePath, resolver = dns } = {}) {
+    this.filePath = filePath;
+    this.resolver = resolver;
+    this.state = { domains: [], identities: [], suppressions: [], keys: [] };
+    this.rate = new Map();
+    this.signingKeys = new Map();
+    this.#load();
+  }
+  #load() {
+    if (!this.filePath || !fs.existsSync(this.filePath)) return;
+    this.state = { ...this.state, ...JSON.parse(fs.readFileSync(this.filePath, "utf8")) };
+    let migratedSecret = false;
+    for (const domain of this.state.domains) {
+      if (domain.dkim?.private_key) { this.signingKeys.set(domain.domain, domain.dkim.private_key); delete domain.dkim.private_key; migratedSecret = true; }
+    }
+    if (migratedSecret) this.#save();
+  }
+  #save() {
+    if (!this.filePath) return;
+    fs.mkdirSync(path.dirname(path.resolve(this.filePath)), { recursive: true });
+    const temp = `${this.filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(temp, JSON.stringify(this.state, null, 2), { mode: 0o600 });
+    fs.renameSync(temp, this.filePath);
+  }
+  createDomain(domainName) {
+    const domain = String(domainName).trim().toLowerCase();
+    const existing = this.state.domains.find((item) => item.domain === domain);
+    if (existing) return clone(existing);
+    const selector = `mailport-${crypto.randomBytes(6).toString("hex")}`;
+    let privateKey = this.signingKeys.get(domain);
+    let publicKey;
+    if (privateKey) {
+      publicKey = crypto.createPublicKey(privateKey).export({ type: "spki", format: "pem" });
+    } else {
+      const generated = crypto.generateKeyPairSync("rsa", { modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" }, privateKeyEncoding: { type: "pkcs8", format: "pem" } });
+      publicKey = generated.publicKey; privateKey = generated.privateKey;
+    }
+    const publicValue = publicKey.replace(/-----[^-]+-----|\s/g, "");
+    const item = { domain, status: "pending", created_at: now(),
+      spf: { status: "pending", name: domain, record: "v=spf1 include:_spf.mailport.local ~all" },
+      dkim: { status: "pending", selector, name: `${selector}._domainkey.${domain}`,
+        record: `v=DKIM1; k=rsa; p=${publicValue}` },
+      dmarc: { status: "recommended", name: `_dmarc.${domain}`, record: "v=DMARC1; p=none; rua=mailto:dmarc@" + domain } };
+    this.signingKeys.set(domain, privateKey);
+    this.state.domains.push(item); this.#save(); return this.#publicDomain(item);
+  }
+  #publicDomain(item) { const value = clone(item); if (value?.dkim) delete value.dkim.private_key; return value; }
+  listDomains() { return this.state.domains.map((item) => this.#publicDomain(item)); }
+  getDomain(domain) { const item = this.state.domains.find((value) => value.domain === domain); return item ? this.#publicDomain(item) : null; }
+  deleteDomain(domain) { this.state.domains = this.state.domains.filter((item) => item.domain !== domain); this.#save(); }
+  async verifyDomain(domainName) {
+    const item = this.state.domains.find((value) => value.domain === domainName);
+    if (!item) return null;
+    item.status = "verifying"; this.#save();
+    const checks = async (name, record) => { try { return (await this.resolver.resolveTxt(name)).flat().join("").includes(record); } catch { return false; } };
+    const [spf, dkim] = await Promise.all([checks(item.spf.name, item.spf.record), checks(item.dkim.name, item.dkim.record)]);
+    item.spf.status = spf ? "verified" : "pending"; item.dkim.status = dkim ? "verified" : "pending";
+    item.status = spf && dkim ? "active" : "pending"; item.verified_at = item.status === "active" ? now() : null;
+    for (const identity of this.state.identities.filter((value) => value.domain === item.domain)) identity.status = item.status === "active" ? "active" : "pending";
+    this.#save(); return this.#publicDomain(item);
+  }
+  createIdentity({ identity, address, application_id = null, tenant_id = null }) {
+    const domain = normalizeEmail(address).split("@").at(-1);
+    if (!this.getDomain(domain)) throw new MailPortError(ERROR_CODES.MAIL_DOMAIN_NOT_VERIFIED, "Identity domain is not configured");
+    const item = { identity, address: normalizeEmail(address), domain, application_id, tenant_id,
+      status: this.getDomain(domain).status === "active" ? "active" : "pending", created_at: now() };
+    this.state.identities = this.state.identities.filter((value) => !(value.identity === identity && value.application_id === application_id));
+    this.state.identities.push(item); this.#save(); return clone(item);
+  }
+  listIdentities(principal) { return this.state.identities.filter((item) => !principal || principal.admin || item.application_id === principal.application_id).map(clone); }
+  signingForIdentity(identityName, principal) {
+    const identity = this.state.identities.find((item) => item.identity === identityName && item.status === "active" &&
+      (!item.application_id || item.application_id === principal.application_id));
+    const domain = identity && this.state.domains.find((item) => item.domain === identity.domain && item.status === "active");
+    const privateKey = domain && this.signingKeys.get(domain.domain);
+    return domain && privateKey ? { domain: domain.domain, selector: domain.dkim.selector, privateKey } : null;
+  }
+  setSigningKey(domain, privateKey) { this.signingKeys.set(domain, privateKey); }
+  signingReady() { return this.state.domains.filter((item) => item.status === "active").every((item) => this.signingKeys.has(item.domain)); }
+  addSuppression({ email, reason = "manual", source = "admin", application_id = null, tenant_id = null }) {
+    const item = { email: normalizeEmail(email), reason, source, application_id, tenant_id, created_at: now() };
+    this.state.suppressions = this.state.suppressions.filter((value) => !(value.email === item.email && value.application_id === application_id));
+    this.state.suppressions.push(item); this.#save(); return clone(item);
+  }
+  listSuppressions(principal) { return this.state.suppressions.filter((item) => !principal || principal.admin || item.application_id === principal.application_id).map(clone); }
+  isSuppressed(email, principal) { return this.state.suppressions.find((item) => item.email === normalizeEmail(email) &&
+    (!item.application_id || item.application_id === principal.application_id) && (!item.tenant_id || item.tenant_id === principal.tenant_id)); }
+  addKey({ token, key_id = `key_${randomUUID()}`, application_id, tenant_id = null, scopes = ["mail.send", "mail.read"] }) {
+    const item = { token_hash: crypto.createHash("sha256").update(token).digest("hex"), key_id, application_id, tenant_id,
+      scopes, status: "active", created_at: now(), last_used_at: null };
+    this.state.keys.push(item); this.#save(); return { ...clone(item), token_hash: undefined };
+  }
+  authenticate(token) {
+    const hash = crypto.createHash("sha256").update(token).digest("hex");
+    const key = this.state.keys.find((item) => item.token_hash === hash && item.status === "active");
+    if (!key) return null; key.last_used_at = now(); this.#save();
+    return { key_id: key.key_id, application_id: key.application_id, tenant_id: key.tenant_id, scopes: key.scopes };
+  }
+  enforceRate(principal, identity, recipients, limits = {}) {
+    const maximum = limits.messagesPerMinute || limits.messages_per_minute;
+    if (!maximum) return;
+    const minute = Math.floor(Date.now() / 60_000);
+    for (const dimension of [`app:${principal.application_id}`, `identity:${principal.application_id}:${identity}`,
+      ...recipients.map((email) => `recipient:${principal.application_id}:${normalizeEmail(email)}`)]) {
+      const key = `${minute}:${dimension}`; const count = (this.rate.get(key) || 0) + 1; this.rate.set(key, count);
+      if (count > maximum) throw new MailPortError(ERROR_CODES.MAIL_RATE_LIMITED, "Mail rate limit exceeded", { retry_after_ms: 60_000 - Date.now() % 60_000 });
+    }
+  }
+}

package/dist/production-config.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { MailPortError, ERROR_CODES } from "@mailerport/core";
+
+export function validateProductionConfig(options = {}, environment = process.env) {
+  const production = options.production ?? environment.NODE_ENV === "production";
+  if (!production) return { production: false };
+  const apiKey = options.apiKey || environment.MAILPORT_API_KEY;
+  const outbox = options.outbox?.filePath || environment.MAILPORT_OUTBOX;
+  const transport = typeof options.transport === "string" ? options.transport : options.transport?.type || options.transport?.kind || environment.MAILPORT_TRANSPORT;
+  const missing = [];
+  if (!apiKey) missing.push("MAILPORT_API_KEY");
+  if (!outbox) missing.push("MAILPORT_OUTBOX");
+  if (!transport) missing.push("MAILPORT_TRANSPORT");
+  if (transport === "smtp") {
+    for (const name of ["MAILPORT_SMTP_HOST", "MAILPORT_SMTP_PORT", "MAILPORT_SMTP_USERNAME", "MAILPORT_SMTP_PASSWORD"])
+      if (!environment[name] && !options.transport?.[name.slice(14).toLowerCase()]) missing.push(name);
+  }
+  if (missing.length) throw new MailPortError(ERROR_CODES.MAIL_NOT_CONFIGURED, `Missing production configuration: ${missing.join(", ")}`);
+  if (/^(dev|test)(-|$)/i.test(apiKey)) throw new MailPortError(ERROR_CODES.MAIL_NOT_CONFIGURED, "Development API keys are forbidden in production");
+  if (!path.isAbsolute(outbox)) throw new MailPortError(ERROR_CODES.MAIL_NOT_CONFIGURED, "MAILPORT_OUTBOX must be an absolute persistent-storage path in production");
+  return { production: true, outbox, transport };
+}

package/dist/remote-service.js

@@ -0,0 +1,254 @@
+import http from "node:http";
+import { URL } from "node:url";
+import { MailPortError, ERROR_CODES } from "@mailerport/core";
+
+function sendJson(res, status, body) {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+}
+function publicMessage(message) {
+  if (!message || typeof message !== "object") return message;
+  const copy = structuredClone(message); delete copy.dkim; return copy;
+}
+
+function parseQueryFilters(searchParams) {
+  const parsed = {};
+  for (const [key, value] of searchParams.entries()) {
+    if (value === "null") parsed[key] = null;
+    else if (value === "undefined") parsed[key] = undefined;
+    else parsed[key] = value;
+  }
+  return parsed;
+}
+
+function parseAuthorization(req) {
+  const header = req.headers.authorization;
+  if (typeof header !== "string" || !/^Bearer [^\s]+$/.test(header)) return null;
+  return header.slice(7);
+}
+
+async function readJsonBody(req, maxBodyBytes) {
+  let total = 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    total += chunk.length;
+    if (total > maxBodyBytes) {
+      throw new MailPortError(ERROR_CODES.MAIL_MESSAGE_TOO_LARGE, "Request body too large");
+    }
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) return {};
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new MailPortError(ERROR_CODES.MAIL_DELIVERY_FAILED, "Invalid JSON body");
+  }
+}
+
+function authorize(req, { apiKey, adminKey, operations, applicationId }) {
+  if (!apiKey && !adminKey && !operations) return { application_id: applicationId || "app", scopes: ["mail.send", "mail.read", "mail.test"] };
+  const token = parseAuthorization(req);
+  if (adminKey && token === adminKey) return { admin: true, application_id: null, scopes: ["*"] };
+  if (apiKey && token === apiKey) return { application_id: applicationId || "app", tenant_id: null, scopes: ["mail.send", "mail.read", "mail.test"] };
+  const principal = token && operations?.authenticate(token);
+  if (!principal) {
+    throw new MailPortError(ERROR_CODES.MAIL_UNAUTHORIZED, "Unauthorized");
+  }
+  return principal;
+}
+function requireScope(principal, scope) {
+  if (!principal.admin && !principal.scopes?.includes(scope)) throw new MailPortError(ERROR_CODES.MAIL_FORBIDDEN, `Missing scope: ${scope}`);
+}
+function requireAdmin(principal) {
+  if (!principal.admin) throw new MailPortError(ERROR_CODES.MAIL_FORBIDDEN, "Administrative credential required");
+}
+
+export function createMailPortService(
+  mail,
+  {
+    host = "127.0.0.1",
+    port = 8789,
+    apiKey,
+    maxBodyBytes = 256 * 1024,
+    testEndpointsEnabled = true,
+    adminKey, operations, rateLimits, applicationId, production, deliveryEvents,
+  } = {}
+) {
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, `http://${host}:${port}`);
+
+      if (req.method === "GET" && url.pathname === "/health") {
+        return sendJson(res, 200, { ok: true });
+      }
+      if (req.method === "GET" && url.pathname === "/ready") {
+        await mail.list();
+        if (production?.production && operations && !operations.signingReady())
+          return sendJson(res, 503, { ready: false, reason: "signing_configuration_unavailable" });
+        return sendJson(res, 200, { ready: true });
+      }
+
+      const principal = url.pathname.startsWith("/v1/")
+        ? authorize(req, { apiKey, adminKey, operations, applicationId }) : null;
+
+      if (req.method === "GET" && url.pathname === "/v1/status") {
+        const status = typeof mail.status === "function" ? await mail.status() : {};
+        const suppressions = operations?.listSuppressions({ admin: true }) || [];
+        return sendJson(res, 200, { service: "mailport", version: "1.0.0", ...status,
+          suppression: { suppressed: suppressions.length, hard_bounces: suppressions.filter((item) => item.reason === "hard_bounce").length,
+            complaints: suppressions.filter((item) => item.reason === "complaint").length } });
+      }
+
+      if (req.method === "POST" && url.pathname === "/v1/domains") {
+        requireAdmin(principal); const body = await readJsonBody(req, maxBodyBytes);
+        return sendJson(res, 201, operations.createDomain(body.domain));
+      }
+      if (req.method === "GET" && url.pathname === "/v1/domains") {
+        requireAdmin(principal); return sendJson(res, 200, operations.listDomains());
+      }
+      if (url.pathname.startsWith("/v1/domains/")) {
+        requireAdmin(principal);
+        const parts = url.pathname.split("/"); const domain = decodeURIComponent(parts[3]);
+        if (req.method === "POST" && parts[4] === "verify") return sendJson(res, 200, await operations.verifyDomain(domain));
+        if (req.method === "GET") { const item = operations.getDomain(domain); return item ? sendJson(res, 200, item) : sendJson(res, 404, { error: "not_found" }); }
+        if (req.method === "DELETE") { operations.deleteDomain(domain); return sendJson(res, 200, { deleted: true }); }
+      }
+      if (req.method === "POST" && url.pathname === "/v1/identities") {
+        requireAdmin(principal); return sendJson(res, 201, operations.createIdentity(await readJsonBody(req, maxBodyBytes)));
+      }
+      if (req.method === "GET" && url.pathname === "/v1/identities") {
+        requireAdmin(principal); return sendJson(res, 200, operations.listIdentities(principal));
+      }
+      if (req.method === "POST" && url.pathname === "/v1/suppressions") {
+        requireAdmin(principal); return sendJson(res, 201, operations.addSuppression(await readJsonBody(req, maxBodyBytes)));
+      }
+      if (req.method === "POST" && url.pathname === "/v1/delivery-events") {
+        requireAdmin(principal);
+        return sendJson(res, 202, publicMessage(await deliveryEvents.consume(await readJsonBody(req, maxBodyBytes))));
+      }
+      if (req.method === "GET" && url.pathname === "/v1/suppressions") {
+        requireAdmin(principal); return sendJson(res, 200, operations.listSuppressions(principal));
+      }
+      if (req.method === "GET" && /^\/v1\/messages\/[^/]+\/events$/.test(url.pathname)) {
+        requireScope(principal, "mail.read"); const id = decodeURIComponent(url.pathname.split("/")[3]);
+        const message = await mail.get(id);
+        if (!message) return sendJson(res, 404, { error: "not_found" });
+        if (!principal.admin && message.application_id !== principal.application_id) throw new MailPortError(ERROR_CODES.MAIL_FORBIDDEN, "Message belongs to another application");
+        return sendJson(res, 200, message.events || []);
+      }
+
+      if (req.method === "POST" && url.pathname === "/v1/messages") {
+        requireScope(principal, "mail.send");
+        const body = await readJsonBody(req, maxBodyBytes);
+        delete body.__applicationId; delete body.__tenantId; delete body.__identityAddress;
+        const payload = body.template ? body.payload || {} : body;
+        const identity = operations?.listIdentities(principal).find((item) => item.identity === payload.identity &&
+          (!item.tenant_id || item.tenant_id === principal.tenant_id));
+        if (identity && identity.status !== "active") throw new MailPortError(ERROR_CODES.MAIL_DOMAIN_NOT_VERIFIED, "Sending identity is not active");
+        const recipients = [...(Array.isArray(payload.to) ? payload.to : [payload.to]), ...(payload.cc || []), ...(payload.bcc || [])].filter(Boolean);
+        const suppressed = recipients.find((email) => operations?.isSuppressed(email, principal));
+        if (suppressed) throw new MailPortError(ERROR_CODES.MAIL_RECIPIENT_SUPPRESSED, "Recipient is suppressed", { recipient: suppressed });
+        operations?.enforceRate(principal, payload.identity, recipients, rateLimits);
+        payload.__applicationId = principal.application_id; payload.__tenantId = principal.tenant_id;
+        if (identity) payload.__identityAddress = identity.address;
+        if (identity) payload.__dkim = operations.signingForIdentity(identity.identity, principal);
+        const message = body.template
+          ? await mail.send(body.template, payload)
+          : await mail.send(body);
+        return sendJson(res, 200, publicMessage(message));
+      }
+
+      if (req.method === "GET" && url.pathname === "/v1/messages") {
+        requireScope(principal, "mail.read");
+        return sendJson(res, 200, (await mail.list(parseQueryFilters(url.searchParams))).filter((item) => principal.admin ||
+          (item.application_id === principal.application_id && (principal.tenant_id == null || item.tenant_id === principal.tenant_id))).map(publicMessage));
+      }
+
+      if (req.method === "GET" && url.pathname.startsWith("/v1/messages/")) {
+        const id = decodeURIComponent(url.pathname.split("/").pop());
+        const message = await mail.get(id);
+        if (!message) return sendJson(res, 404, { error: "not_found" });
+        requireScope(principal, "mail.read");
+        if (!principal.admin && (message.application_id !== principal.application_id ||
+          (principal.tenant_id != null && message.tenant_id !== principal.tenant_id))) throw new MailPortError(ERROR_CODES.MAIL_FORBIDDEN, "Message belongs to another application");
+        return sendJson(res, 200, publicMessage(message));
+      }
+
+      if (req.method === "GET" && url.pathname === "/v1/test/messages") {
+        requireScope(principal, "mail.test");
+        if (!testEndpointsEnabled) {
+          throw new MailPortError(
+            ERROR_CODES.MAIL_TEST_TRANSPORT_DISABLED,
+            "Test API is disabled"
+          );
+        }
+        return sendJson(res, 200, (await mail.test.list(parseQueryFilters(url.searchParams))).filter((item) =>
+          principal.admin || item.application_id === principal.application_id).map(publicMessage));
+      }
+
+      if (req.method === "GET" && url.pathname.startsWith("/v1/test/messages/")) {
+        requireScope(principal, "mail.test");
+        if (!testEndpointsEnabled) {
+          throw new MailPortError(
+            ERROR_CODES.MAIL_TEST_TRANSPORT_DISABLED,
+            "Test API is disabled"
+          );
+        }
+        const id = decodeURIComponent(url.pathname.split("/").pop());
+        const message = await mail.test.get(id);
+        if (!message) return sendJson(res, 404, { error: "not_found" });
+        if (!principal.admin && message.application_id !== principal.application_id) throw new MailPortError(ERROR_CODES.MAIL_FORBIDDEN, "Message belongs to another application");
+        return sendJson(res, 200, publicMessage(message));
+      }
+
+      if (req.method === "DELETE" && url.pathname === "/v1/test/messages") {
+        requireScope(principal, "mail.test");
+        if (!testEndpointsEnabled) {
+          throw new MailPortError(
+            ERROR_CODES.MAIL_TEST_TRANSPORT_DISABLED,
+            "Test API is disabled"
+          );
+        }
+        const filters = parseQueryFilters(url.searchParams);
+        if (!principal.admin || Object.keys(filters).length) await mail.test.clear({ ...filters, application_id: principal.application_id });
+        else await mail.test.clear();
+        return sendJson(res, 200, { cleared: true });
+      }
+
+      return sendJson(res, 404, { error: "not_found" });
+    } catch (error) {
+      if (error instanceof MailPortError) {
+        const status = error.code === ERROR_CODES.MAIL_UNAUTHORIZED ? 401 : error.code === ERROR_CODES.MAIL_FORBIDDEN ? 403 :
+          error.code === ERROR_CODES.MAIL_RATE_LIMITED ? 429 : 400;
+        return sendJson(res, status, { error: error.code, message: error.message, details: error.details });
+      }
+      return sendJson(res, 500, { error: "internal_error" });
+    }
+  });
+
+  return {
+    async start() {
+      await new Promise((resolve, reject) => {
+        const onError = (error) => {
+          server.off("error", onError);
+          reject(error);
+        };
+        server.once("error", onError);
+        server.listen(port, host, () => {
+          server.off("error", onError);
+          resolve();
+        });
+      });
+    },
+    async stop() {
+      if (typeof mail.stopWorker === "function") mail.stopWorker();
+      await new Promise((resolve, reject) =>
+        server.close((error) => (error ? reject(error) : resolve()))
+      );
+      if (typeof mail.close === "function") {
+        await mail.close();
+      }
+    },
+  };
+}

package/dist/service.js

@@ -0,0 +1,43 @@
+import { createMailPort } from "@mailerport/sdk";
+import { createSmtpTransport } from "@mailerport/smtp";
+import { createMailPortService } from "./remote-service.js";
+import { FileOperationsStore } from "./operations.js";
+import { validateProductionConfig } from "./production-config.js";
+import { createDeliveryEventSource } from "./delivery-events.js";
+
+export function createMailService(options = {}) {
+  const environment = options.environment || process.env;
+  const production = validateProductionConfig(options, environment);
+  const worker = options.worker || {};
+  const transport = options.transport || { type: environment.MAILPORT_TRANSPORT || "local" };
+  let transportConfig = typeof transport === "string" ? transport : { ...transport, kind: transport.kind || transport.type };
+  if ((transportConfig === "smtp" || transportConfig.kind === "smtp" || transportConfig.type === "smtp")) {
+    transportConfig = createSmtpTransport({
+      ...(typeof transportConfig === "object" ? transportConfig : {}), host: transportConfig.host || environment.MAILPORT_SMTP_HOST,
+      port: Number(transportConfig.port || environment.MAILPORT_SMTP_PORT || 25), username: transportConfig.username || environment.MAILPORT_SMTP_USERNAME,
+      password: transportConfig.password || environment.MAILPORT_SMTP_PASSWORD, secure: transportConfig.secure ?? environment.MAILPORT_SMTP_SECURE === "true",
+      requireTLS: transportConfig.requireTLS ?? (environment.MAILPORT_SMTP_REQUIRE_TLS === "true" || environment.NODE_ENV === "production") });
+  }
+  const mail = createMailPort({
+    applicationId: options.applicationId || environment.MAILPORT_APPLICATION_ID || "app",
+    identities: options.identities || { system: "notifications@example.test" },
+    templates: options.templates || {}, environment,
+    transport: transportConfig,
+    testEndpointsEnabled: options.testEndpointsEnabled ?? transportConfig.kind !== "smtp",
+    outbox: { enabled: true, filePath: options.outbox?.filePath || environment.MAILPORT_OUTBOX || ".mailport/outbox.json",
+      workerEnabled: worker.enabled !== false, pollIntervalMs: worker.pollIntervalMs,
+      leaseMs: worker.leaseMs, maxAttempts: worker.maxAttempts, retryBaseMs: worker.retryBaseMs },
+  });
+  const operations = options.operationsStore || new FileOperationsStore({ filePath: options.operations?.filePath || environment.MAILPORT_OPERATIONS,
+    resolver: options.operations?.resolver });
+  for (const key of options.apiKeys || []) operations.addKey(key);
+  if (environment.MAILPORT_DKIM_DOMAIN && environment.MAILPORT_DKIM_PRIVATE_KEY)
+    operations.setSigningKey(environment.MAILPORT_DKIM_DOMAIN, environment.MAILPORT_DKIM_PRIVATE_KEY.replace(/\\n/g, "\n"));
+  const deliveryEvents = createDeliveryEventSource({ mail, operations, ...(options.deliveryEvents || {}) });
+  const server = createMailPortService(mail, { host: options.host, port: options.port || Number(environment.PORT) || 8789,
+    apiKey: options.apiKey || environment.MAILPORT_API_KEY,
+    adminKey: options.adminKey || environment.MAILPORT_ADMIN_KEY, operations, rateLimits: options.limits,
+    applicationId: options.applicationId || environment.MAILPORT_APPLICATION_ID || "app", production, deliveryEvents,
+    maxBodyBytes: options.maxBodyBytes, testEndpointsEnabled: options.testEndpointsEnabled ?? transportConfig.kind !== "smtp" });
+  return { ...server, mail, operations, deliveryEvents, production, config: options };
+}

package/package.json

@@ -0,0 +1 @@
+{"name":"@mailerport/service","version":"0.1.0","description":"Standalone MailPort transactional mail service","type":"module","bin":{"mailport-service":"./bin/mailport-service.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"types":"./dist/index.d.ts","files":["dist","bin"],"scripts":{"build":"node ../../scripts/build-package.js service","prepack":"npm run build"},"dependencies":{"@mailerport/core":"0.1.0","@mailerport/sdk":"0.1.0","@mailerport/smtp":"0.1.0"},"engines":{"node":">=20"},"license":"MIT","publishConfig":{"access":"public"}}