@elevora-tech/mailcap 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathew Mozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+# @elevora-tech/mailcap
+
+Zero-branching email SDK. One function, identical in every environment — env
+vars alone decide whether an email is captured by [Mailcap](https://github.com/mat-hiretalk/mailcap)
+for local/dev/staging inspection, or delivered for real via Resend, SendGrid,
+or Mailgun.
+
+```ts
+import { sendEmail } from "@elevora-tech/mailcap";
+
+await sendEmail({ from, to, subject, html }); // or { text } / { attachments }
+```
+
+That line never changes between `local-dave`, staging, and production. What
+changes is your environment configuration:
+
+```bash
+# Captured — nothing is delivered
+MAILCAP_API_KEY=mc_...
+MAILCAP_URL=https://mailcap.yourdomain.com
+
+# Delivered for real (production)
+MAIL_PROVIDER=resend       # or sendgrid | mailgun
+RESEND_API_KEY=re_...
+```
+
+## Guarantees
+
+- **No mode flag.** Capture activates purely from `MAILCAP_API_KEY` being
+  present. There is no branch in your code that could ship the wrong way.
+- **Real-send guard.** Outside `NODE_ENV=production`, real provider delivery is
+  refused unless you set `MAILCAP_ALLOW_REAL_SEND=true`. A dev machine that
+  happens to have a real provider key configured still can't email real people.
+  This guard is checked *before* provider config is validated — so if you see
+  the guard error while genuinely expecting capture, the fix is almost always
+  `MAILCAP_API_KEY` (+ `MAILCAP_URL`), not the override.
+- **Loud misconfiguration.** Missing or contradictory env vars throw
+  immediately, naming exactly what's missing — never a silent no-op.
+- **Ingest failures are never silent.** If Mailcap capture fails, `sendEmail`
+  rejects; your app sees the error.
+
+## Providers
+
+| `MAIL_PROVIDER` | Required env vars |
+|---|---|
+| `resend` | `RESEND_API_KEY` |
+| `sendgrid` | `SENDGRID_API_KEY` |
+| `mailgun` | `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, optional `MAILGUN_REGION=us\|eu` |
+
+Switching providers is a config change only — no call-site changes.
+
+## Advanced: explicit config
+
+`sendEmail` reads `process.env` lazily on first call. For tests or multiple
+mailer instances, use `createMailer` with explicit overrides:
+
+```ts
+import { createMailer } from "@elevora-tech/mailcap";
+
+const mailer = createMailer({
+  captureApiKey: "mc_test",
+  captureUrl: "https://mailcap.example.test",
+});
+
+await mailer.send({ from, to, subject, html });
+```
+
+## Already have a provider client wired up everywhere?
+
+`sendEmail()` is the ideal shape for new code, but rewriting a codebase that
+already calls `mailgun.messages.create(...)` (or `@sendgrid/mail`'s `.send()`,
+or Resend's `.emails.send()`) at many call sites is real, risky work you can
+reasonably not want to do. Wrap the client instead — the call shape at every
+existing site stays identical:
+
+```ts
+import Mailgun from "mailgun.js";
+import { wrapMailgunClient } from "@elevora-tech/mailcap";
+
+const rawClient = new Mailgun(formData).client({ username: "api", key: apiKey });
+export const mailgun = wrapMailgunClient(rawClient); // <- only this line changes
+
+// every existing call site, completely unchanged:
+await mailgun.messages.create(domain, {
+  from, to, subject,
+  template: "login_otp_template",
+  "t:variables": JSON.stringify({ otp }),
+});
+```
+
+`wrapSendGridClient` and `wrapResendClient` work the same way for
+`@sendgrid/mail` and `resend`. All three apply the identical capture-vs-deliver
+routing, real-send guard, and loud misconfiguration errors as `sendEmail`.
+
+For call shapes that don't fit a wrapper, there's a lower-level manual gate:
+
+```ts
+import { isMailcapCaptureEnabled, captureRaw } from "@elevora-tech/mailcap";
+
+if (isMailcapCaptureEnabled()) {
+  await captureRaw({ from, to, subject, html });
+} else {
+  await existingProviderCall(); // untouched
+}
+```
+
+## Version compatibility — what happens when Resend/SendGrid/Mailgun update?
+
+`wrapResendClient`, `wrapSendGridClient`, and `wrapMailgunClient` never import
+the vendor SDK. Each takes a **structural type**
+(`ResendLikeClient`/`SendGridLikeClient`/`MailgunLikeClient`) describing only
+the one method call shape Mailcap needs — `client.emails.send(payload)`,
+`client.send(msg)`, `client.messages.create(domain, data)`. There is no
+version of `resend`, `@sendgrid/mail`, or `mailgun.js` pinned anywhere in this
+package, so there's nothing in mailcap-sdk to upgrade in lockstep with those
+vendors.
+
+In practice that means:
+
+- **Internal vendor changes are invisible to Mailcap.** New optional params,
+  auth changes, retry logic, bundling changes — none of it touches the
+  wrapper, because the wrapper never calls into vendor internals, only the one
+  public method it wraps.
+- **The only thing that can break a wrapper** is the vendor changing the
+  *shape* Mailcap depends on: the method name/signature itself, or a payload
+  field name the translator reads (e.g. SendGrid's `personalizations`,
+  `templateId`, `dynamicTemplateData`; Mailgun's `template` / `t:variables`).
+  These are long-stable, publicly documented wire shapes, not implementation
+  details — vendors change them rarely and usually only in a major version.
+- **If that ever does happen**, it fails loudly, not silently:
+  `emailMessageSchema.parse` throws on missing/malformed required fields
+  rather than shipping a half-populated capture. You'd see a validation error
+  pointing at the exact field, not a mysteriously empty inbox entry.
+- **Your existing call sites are unaffected either way** — you're still
+  calling the vendor client the same way; the wrapper just intercepts the one
+  method. Upgrading the vendor package in your own app is a decision you make
+  independently of Mailcap.
+
+## Provider-side templates
+
+Some providers render from a template stored on their side rather than an
+`html` string you supply — Mailgun's `template` name + `t:variables`,
+SendGrid's `templateId` + `dynamicTemplateData`. Pass it as `template`
+instead of `html`/`text`:
+
+```ts
+await sendEmail({
+  from, to, subject,
+  template: { id: "d-abc123", provider: "sendgrid", data: { name: "Dave" } },
+});
+```
+
+Mailcap has no access to the real template, so its inbox falls back to a
+locally-registered preview (or a plain data table if none is registered) —
+see the [service's docs](https://github.com/mat-hiretalk/mailcap) for the mock
+template registry. Resend has no provider-side template API — a template-only
+message on `MAIL_PROVIDER=resend` throws a clear error telling you to render
+`html` first (e.g. with React Email) or switch providers for that send.
+
+## Idempotency
+
+Pass `messageId` to dedupe retries — Mailcap only stores the first delivery
+for a given id within an environment:
+
+```ts
+await sendEmail({ from, to, subject, html, messageId: "signup-verify-42" });
+```
+
+## Maintenance note: `dist/` is committed
+
+This package isn't published to npm yet (N7's long-term plan; no npm token
+available in this environment). Consumers install it as a git dependency
+(`github:Elevora-Tech/mailcap-sdk#<commit>`), which is why `dist/` is checked
+into this repo instead of gitignored — a git-sourced install ships repo
+content as-is, and there's no install-time build step gating it. **After any
+change to `src/`, run `pnpm build` and commit the resulting `dist/` alongside
+it**, or consumers pinned to that commit won't see the change.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+import { z } from 'zod';
+
+/**
+ * Single source of truth for the email message shape (spec F10).
+ * The Mailcap service imports this same schema to validate /api/ingest,
+ * so SDK and service can never drift silently — a shape mismatch is a
+ * validation error, not a bug discovered in production.
+ */
+declare const attachmentSchema: z.ZodObject<{
+    filename: z.ZodString;
+    contentType: z.ZodString;
+    /** Base64-encoded content. Total message size is capped by the service (F5, 10MB). */
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    filename: string;
+    contentType: string;
+    content: string;
+}, {
+    filename: string;
+    contentType: string;
+    content: string;
+}>;
+/**
+ * Provider-side template reference (F37a) — for sends where the provider
+ * renders a server-side template (Mailgun's `template` name, SendGrid's
+ * `templateId`) instead of the caller supplying html/text. Mailcap has no
+ * access to the real template, so it captures the reference + data and
+ * falls back to a mock-template preview or a data table (F37b).
+ */
+declare const templateRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    provider: z.ZodOptional<z.ZodEnum<["mailgun", "sendgrid"]>>;
+    data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider?: "mailgun" | "sendgrid" | undefined;
+    data?: Record<string, unknown> | undefined;
+}, {
+    id: string;
+    provider?: "mailgun" | "sendgrid" | undefined;
+    data?: Record<string, unknown> | undefined;
+}>;
+declare const emailMessageSchema: z.ZodEffects<z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodArray<z.ZodString, "many">;
+    cc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    bcc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    subject: z.ZodString;
+    html: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    /** Provider-side template reference — alternative to html/text (F37a). */
+    template: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        provider: z.ZodOptional<z.ZodEnum<["mailgun", "sendgrid"]>>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        provider?: "mailgun" | "sendgrid" | undefined;
+        data?: Record<string, unknown> | undefined;
+    }, {
+        id: string;
+        provider?: "mailgun" | "sendgrid" | undefined;
+        data?: Record<string, unknown> | undefined;
+    }>>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        contentType: z.ZodString;
+        /** Base64-encoded content. Total message size is capped by the service (F5, 10MB). */
+        content: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        filename: string;
+        contentType: string;
+        content: string;
+    }, {
+        filename: string;
+        contentType: string;
+        content: string;
+    }>, "many">>;
+    /** Optional client-supplied id for idempotency (F7). */
+    messageId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string[];
+    subject: string;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    html?: string | undefined;
+    text?: string | undefined;
+    template?: {
+        id: string;
+        provider?: "mailgun" | "sendgrid" | undefined;
+        data?: Record<string, unknown> | undefined;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    attachments?: {
+        filename: string;
+        contentType: string;
+        content: string;
+    }[] | undefined;
+    messageId?: string | undefined;
+}, {
+    from: string;
+    to: string[];
+    subject: string;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    html?: string | undefined;
+    text?: string | undefined;
+    template?: {
+        id: string;
+        provider?: "mailgun" | "sendgrid" | undefined;
+        data?: Record<string, unknown> | undefined;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    attachments?: {
+        filename: string;
+        contentType: string;
+        content: string;
+    }[] | undefined;
+    messageId?: string | undefined;
+}>, {
+    from: string;
+    to: string[];
+    subject: string;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    html?: string | undefined;
+    text?: string | undefined;
+    template?: {
+        id: string;
+        provider?: "mailgun" | "sendgrid" | undefined;
+        data?: Record<string, unknown> | undefined;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    attachments?: {
+        filename: string;
+        contentType: string;
+        content: string;
+    }[] | undefined;
+    messageId?: string | undefined;
+}, {
+    from: string;
+    to: string[];
+    subject: string;
+    cc?: string[] | undefined;
+    bcc?: string[] | undefined;
+    html?: string | undefined;
+    text?: string | undefined;
+    template?: {
+        id: string;
+        provider?: "mailgun" | "sendgrid" | undefined;
+        data?: Record<string, unknown> | undefined;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    attachments?: {
+        filename: string;
+        contentType: string;
+        content: string;
+    }[] | undefined;
+    messageId?: string | undefined;
+}>;
+type EmailMessage = z.infer<typeof emailMessageSchema>;
+type Attachment = z.infer<typeof attachmentSchema>;
+type TemplateRef = z.infer<typeof templateRefSchema>;
+declare const ingestResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+type IngestResponse = z.infer<typeof ingestResponseSchema>;
+
+type MailProvider = "resend" | "sendgrid" | "mailgun";
+interface MailcapConfig {
+    /** Presence of this key routes sends to Mailcap capture instead of real delivery. */
+    captureApiKey?: string;
+    captureUrl?: string;
+    provider?: MailProvider;
+    resendApiKey?: string;
+    sendgridApiKey?: string;
+    mailgunApiKey?: string;
+    mailgunDomain?: string;
+    mailgunRegion?: "us" | "eu";
+    /** Defaults to process.env.NODE_ENV. Overridable for tests. */
+    nodeEnv?: string;
+    /** Escape hatch for F31's guard — real delivery outside production requires this. */
+    allowRealSend?: boolean;
+}
+interface SendResult {
+    id: string;
+    mode: "captured" | "delivered";
+    provider?: MailProvider;
+}
+interface Mailer {
+    send(message: EmailMessage): Promise<SendResult>;
+}
+/**
+ * Builds a Mailer from explicit config (falls back to env vars for anything
+ * not overridden). Prefer this in tests or when a project needs more than one
+ * mailer instance; most app code should use the top-level `sendEmail` instead.
+ */
+declare function createMailer(overrides?: Partial<MailcapConfig>): Mailer;
+/**
+ * The one function app code calls, identical in every environment (F30).
+ * Env vars alone decide whether this captures or delivers for real.
+ */
+declare function sendEmail(message: EmailMessage): Promise<SendResult>;
+/** Test-only escape hatch to reset the memoized default mailer between env changes. */
+declare function __resetDefaultMailer(): void;
+
+/**
+ * F36 — brownfield integration for codebases that already call a provider
+ * SDK directly at many call sites (Thriveworks' notification service calls
+ * `mailgun.messages.create(domain, { template, "t:variables", ... })` at
+ * ~15 sites with no shared wrapper). Rewriting every call site to adopt
+ * `sendEmail()` is real, risky work a team can reasonably refuse — these
+ * wrappers let the migration touch only the client construction line.
+ */
+/** Pure boolean check — true when MAILCAP_API_KEY is set (capture is active). */
+declare function isMailcapCaptureEnabled(overrides?: Partial<MailcapConfig>): boolean;
+/**
+ * POSTs an already-shared-schema-shaped message to Mailcap ingest directly,
+ * without going through a provider translator. Use this to hand-write your
+ * own `if (isMailcapCaptureEnabled()) { ... } else { <existing call> }` gate
+ * around code that neither `sendEmail()` nor the wrap-mode adapters below
+ * fit cleanly.
+ */
+declare function captureRaw(message: EmailMessage, overrides?: Partial<MailcapConfig>): Promise<{
+    id: string;
+}>;
+interface MailgunLikeClient {
+    messages: {
+        create: (domain: string, data: Record<string, unknown>) => Promise<unknown>;
+    };
+}
+/**
+ * Wraps an existing `mailgun.js` client (`new Mailgun(formData).client({...})`).
+ * `wrapped.messages.create(domain, data)` — identical call shape — captures
+ * in dev/staging, delivers for real in production, exactly like `sendEmail`.
+ */
+declare function wrapMailgunClient(client: MailgunLikeClient, overrides?: Partial<MailcapConfig>): MailgunLikeClient;
+interface SendGridLikeClient {
+    send: (msg: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Wraps an existing `@sendgrid/mail` client (`sgMail` after `.setApiKey(...)`).
+ * `wrapped.send(msg)` — identical call shape — captures in dev/staging,
+ * delivers for real in production, exactly like `sendEmail`.
+ */
+declare function wrapSendGridClient(client: SendGridLikeClient, overrides?: Partial<MailcapConfig>): SendGridLikeClient;
+interface ResendLikeClient {
+    emails: {
+        send: (payload: Record<string, unknown>) => Promise<unknown>;
+    };
+}
+/**
+ * Wraps an existing `resend` client (`new Resend(apiKey)`).
+ * `wrapped.emails.send(payload)` — identical call shape — captures in
+ * dev/staging, delivers for real in production, exactly like `sendEmail`.
+ */
+declare function wrapResendClient(client: ResendLikeClient, overrides?: Partial<MailcapConfig>): ResendLikeClient;
+
+/** Thrown when required configuration is missing or contradictory (F30). */
+declare class MailcapConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when real provider delivery is attempted outside production without
+ * an explicit override (F31) — the guard against emailing real people from a
+ * dev machine that happens to have a real provider key configured.
+ */
+declare class MailcapRealSendGuardError extends Error {
+    constructor();
+}
+/** Thrown when the capture ingest call itself fails (F4) — never a silent drop. */
+declare class MailcapIngestError extends Error {
+    readonly status: number | undefined;
+    readonly body: string;
+    constructor(status: number | undefined, body: string);
+}
+
+interface DeliveryResult {
+    id: string;
+}
+interface ProviderAdapter {
+    name: string;
+    deliver(message: EmailMessage): Promise<DeliveryResult>;
+}
+declare class ProviderDeliveryError extends Error {
+    readonly provider: string;
+    readonly status: number | undefined;
+    readonly body: string;
+    constructor(provider: string, status: number | undefined, body: string);
+}
+
+declare function createResendAdapter(apiKey: string): ProviderAdapter;
+
+declare function createSendGridAdapter(apiKey: string): ProviderAdapter;
+
+interface MailgunConfig {
+    apiKey: string;
+    domain: string;
+    /** Mailgun has US and EU regions with different API hosts. Defaults to US. */
+    region?: "us" | "eu";
+}
+declare function createMailgunAdapter(config: MailgunConfig): ProviderAdapter;
+
+export { type Attachment, type DeliveryResult, type EmailMessage, type IngestResponse, type MailProvider, type MailcapConfig, MailcapConfigError, MailcapIngestError, MailcapRealSendGuardError, type Mailer, type MailgunLikeClient, type ProviderAdapter, ProviderDeliveryError, type ResendLikeClient, type SendGridLikeClient, type SendResult, type TemplateRef, __resetDefaultMailer, attachmentSchema, captureRaw, createMailer, createMailgunAdapter, createResendAdapter, createSendGridAdapter, emailMessageSchema, ingestResponseSchema, isMailcapCaptureEnabled, sendEmail, templateRefSchema, wrapMailgunClient, wrapResendClient, wrapSendGridClient };

package/dist/index.js

@@ -0,0 +1,476 @@
+// src/schema.ts
+import { z } from "zod";
+var attachmentSchema = z.object({
+  filename: z.string().min(1),
+  contentType: z.string().min(1),
+  /** Base64-encoded content. Total message size is capped by the service (F5, 10MB). */
+  content: z.string().min(1)
+});
+var templateRefSchema = z.object({
+  id: z.string().min(1),
+  provider: z.enum(["mailgun", "sendgrid"]).optional(),
+  data: z.record(z.string(), z.unknown()).optional()
+});
+var emailMessageSchema = z.object({
+  from: z.string().email(),
+  to: z.array(z.string().email()).min(1),
+  cc: z.array(z.string().email()).optional(),
+  bcc: z.array(z.string().email()).optional(),
+  subject: z.string().min(1),
+  html: z.string().optional(),
+  text: z.string().optional(),
+  /** Provider-side template reference — alternative to html/text (F37a). */
+  template: templateRefSchema.optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+  attachments: z.array(attachmentSchema).optional(),
+  /** Optional client-supplied id for idempotency (F7). */
+  messageId: z.string().optional()
+}).refine((msg) => msg.html !== void 0 || msg.text !== void 0 || msg.template !== void 0, {
+  message: "Message must have at least one of html, text, or template."
+});
+var ingestResponseSchema = z.object({
+  id: z.string()
+});
+
+// src/errors.ts
+var MailcapConfigError = class extends Error {
+  constructor(message) {
+    super(`[mailcap] ${message}`);
+    this.name = "MailcapConfigError";
+  }
+};
+var MailcapRealSendGuardError = class extends Error {
+  constructor() {
+    super(
+      "[mailcap] Refusing to send: NODE_ENV is not 'production' and no MAILCAP_API_KEY is set, so this send would otherwise go out to a REAL recipient from a dev/test machine. Most likely fix: set MAILCAP_API_KEY (+ MAILCAP_URL) to capture instead. If you actually intend to send real email from here, set MAILCAP_ALLOW_REAL_SEND=true \u2014 note this check runs before provider config is validated, so you may see a follow-up error about MAIL_PROVIDER once this guard is satisfied."
+    );
+    this.name = "MailcapRealSendGuardError";
+  }
+};
+var MailcapIngestError = class extends Error {
+  constructor(status, body) {
+    super(`[mailcap] Ingest failed (status ${status ?? "n/a"}): ${body}`);
+    this.status = status;
+    this.body = body;
+    this.name = "MailcapIngestError";
+  }
+  status;
+  body;
+};
+
+// src/adapters/types.ts
+var ProviderDeliveryError = class extends Error {
+  constructor(provider, status, body) {
+    super(`[mailcap] ${provider} delivery failed (status ${status ?? "n/a"}): ${body}`);
+    this.provider = provider;
+    this.status = status;
+    this.body = body;
+    this.name = "ProviderDeliveryError";
+  }
+  provider;
+  status;
+  body;
+};
+
+// src/adapters/resend.ts
+function toAttachmentPayload(message) {
+  if (!message.attachments?.length) return void 0;
+  return message.attachments.map((a) => ({
+    filename: a.filename,
+    content: a.content,
+    content_type: a.contentType
+  }));
+}
+function createResendAdapter(apiKey) {
+  return {
+    name: "resend",
+    async deliver(message) {
+      if (message.template && !message.html && !message.text) {
+        throw new MailcapConfigError(
+          "Resend has no provider-side template API \u2014 it has no `template` to deliver via. Render html client-side (e.g. React Email) before sending, or switch MAIL_PROVIDER to mailgun/sendgrid for this message."
+        );
+      }
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          from: message.from,
+          to: message.to,
+          cc: message.cc,
+          bcc: message.bcc,
+          subject: message.subject,
+          html: message.html,
+          text: message.text,
+          headers: message.headers,
+          attachments: toAttachmentPayload(message)
+        })
+      });
+      if (!res.ok) {
+        throw new ProviderDeliveryError("resend", res.status, await res.text());
+      }
+      const data = await res.json();
+      return { id: data.id };
+    }
+  };
+}
+
+// src/adapters/sendgrid.ts
+function toAttachmentPayload2(message) {
+  if (!message.attachments?.length) return void 0;
+  return message.attachments.map((a) => ({
+    filename: a.filename,
+    content: a.content,
+    type: a.contentType
+  }));
+}
+function toHeadersPayload(message) {
+  if (!message.headers) return void 0;
+  return message.headers;
+}
+function createSendGridAdapter(apiKey) {
+  return {
+    name: "sendgrid",
+    async deliver(message) {
+      const res = await fetch("https://api.sendgrid.com/v3/mail/send", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          personalizations: [
+            {
+              to: message.to.map((email) => ({ email })),
+              cc: message.cc?.map((email) => ({ email })),
+              bcc: message.bcc?.map((email) => ({ email }))
+            }
+          ],
+          from: { email: message.from },
+          subject: message.subject,
+          content: message.text || message.html ? [
+            message.text ? { type: "text/plain", value: message.text } : null,
+            message.html ? { type: "text/html", value: message.html } : null
+          ].filter((c) => c !== null) : void 0,
+          template_id: message.template?.provider === "sendgrid" ? message.template.id : void 0,
+          dynamic_template_data: message.template?.provider === "sendgrid" ? message.template.data : void 0,
+          headers: toHeadersPayload(message),
+          attachments: toAttachmentPayload2(message)
+        })
+      });
+      if (!res.ok) {
+        throw new ProviderDeliveryError("sendgrid", res.status, await res.text());
+      }
+      const id = res.headers.get("x-message-id") ?? crypto.randomUUID();
+      return { id };
+    }
+  };
+}
+
+// src/adapters/mailgun.ts
+function base64ToBlob(content, contentType) {
+  const binary = atob(content);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return new Blob([bytes], { type: contentType });
+}
+function createMailgunAdapter(config) {
+  const host = config.region === "eu" ? "api.eu.mailgun.net" : "api.mailgun.net";
+  return {
+    name: "mailgun",
+    async deliver(message) {
+      const form = new FormData();
+      form.append("from", message.from);
+      for (const to of message.to) form.append("to", to);
+      for (const cc of message.cc ?? []) form.append("cc", cc);
+      for (const bcc of message.bcc ?? []) form.append("bcc", bcc);
+      form.append("subject", message.subject);
+      if (message.text) form.append("text", message.text);
+      if (message.html) form.append("html", message.html);
+      if (message.template?.provider === "mailgun") {
+        form.append("template", message.template.id);
+        if (message.template.data) {
+          form.append("t:variables", JSON.stringify(message.template.data));
+        }
+      }
+      for (const [key, value] of Object.entries(message.headers ?? {})) {
+        form.append(`h:${key}`, value);
+      }
+      for (const attachment of message.attachments ?? []) {
+        form.append(
+          "attachment",
+          base64ToBlob(attachment.content, attachment.contentType),
+          attachment.filename
+        );
+      }
+      const res = await fetch(`https://${host}/v3/${config.domain}/messages`, {
+        method: "POST",
+        headers: {
+          Authorization: `Basic ${btoa(`api:${config.apiKey}`)}`
+        },
+        body: form
+      });
+      if (!res.ok) {
+        throw new ProviderDeliveryError("mailgun", res.status, await res.text());
+      }
+      const data = await res.json();
+      return { id: data.id };
+    }
+  };
+}
+
+// src/mailer.ts
+function readConfigFromEnv() {
+  const env = typeof process !== "undefined" ? process.env : {};
+  return {
+    captureApiKey: env.MAILCAP_API_KEY,
+    captureUrl: env.MAILCAP_URL,
+    provider: env.MAIL_PROVIDER,
+    resendApiKey: env.RESEND_API_KEY,
+    sendgridApiKey: env.SENDGRID_API_KEY,
+    mailgunApiKey: env.MAILGUN_API_KEY,
+    mailgunDomain: env.MAILGUN_DOMAIN,
+    mailgunRegion: env.MAILGUN_REGION,
+    nodeEnv: env.NODE_ENV,
+    allowRealSend: env.MAILCAP_ALLOW_REAL_SEND === "true"
+  };
+}
+function resolveAdapter(config) {
+  if (!config.provider) {
+    throw new MailcapConfigError(
+      "No capture key present and MAIL_PROVIDER is not set. Set MAILCAP_API_KEY to capture, or set MAIL_PROVIDER=resend|sendgrid|mailgun plus that provider's API key to deliver for real."
+    );
+  }
+  switch (config.provider) {
+    case "resend": {
+      if (!config.resendApiKey) {
+        throw new MailcapConfigError(
+          "MAIL_PROVIDER=resend but RESEND_API_KEY is not set."
+        );
+      }
+      return createResendAdapter(config.resendApiKey);
+    }
+    case "sendgrid": {
+      if (!config.sendgridApiKey) {
+        throw new MailcapConfigError(
+          "MAIL_PROVIDER=sendgrid but SENDGRID_API_KEY is not set."
+        );
+      }
+      return createSendGridAdapter(config.sendgridApiKey);
+    }
+    case "mailgun": {
+      if (!config.mailgunApiKey) {
+        throw new MailcapConfigError(
+          "MAIL_PROVIDER=mailgun but MAILGUN_API_KEY is not set."
+        );
+      }
+      if (!config.mailgunDomain) {
+        throw new MailcapConfigError(
+          "MAIL_PROVIDER=mailgun but MAILGUN_DOMAIN is not set."
+        );
+      }
+      return createMailgunAdapter({
+        apiKey: config.mailgunApiKey,
+        domain: config.mailgunDomain,
+        region: config.mailgunRegion
+      });
+    }
+    default:
+      throw new MailcapConfigError(
+        `MAIL_PROVIDER=${String(config.provider)} is not a recognized provider (expected resend, sendgrid, or mailgun).`
+      );
+  }
+}
+async function deliverToCapture(message, config) {
+  if (!config.captureUrl) {
+    throw new MailcapConfigError(
+      "MAILCAP_API_KEY is set but MAILCAP_URL is not \u2014 cannot reach the Mailcap service."
+    );
+  }
+  const res = await fetch(new URL("/api/ingest", config.captureUrl), {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.captureApiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(message)
+  });
+  if (!res.ok) {
+    throw new MailcapIngestError(res.status, await res.text());
+  }
+  const parsed = ingestResponseSchema.parse(await res.json());
+  return { id: parsed.id, mode: "captured" };
+}
+function assertRealSendAllowed(config) {
+  const nodeEnv = config.nodeEnv ?? "development";
+  if (nodeEnv !== "production" && !config.allowRealSend) {
+    throw new MailcapRealSendGuardError();
+  }
+}
+async function deliverToProvider(message, config) {
+  assertRealSendAllowed(config);
+  const adapter = resolveAdapter(config);
+  const result = await adapter.deliver(message);
+  return { id: result.id, mode: "delivered", provider: config.provider };
+}
+function createMailer(overrides = {}) {
+  const config = { ...readConfigFromEnv(), ...overrides };
+  return {
+    async send(message) {
+      const validated = emailMessageSchema.parse(message);
+      if (config.captureApiKey) {
+        return deliverToCapture(validated, config);
+      }
+      return deliverToProvider(validated, config);
+    }
+  };
+}
+var defaultMailer;
+function sendEmail(message) {
+  if (!defaultMailer) {
+    defaultMailer = createMailer();
+  }
+  return defaultMailer.send(message);
+}
+function __resetDefaultMailer() {
+  defaultMailer = void 0;
+}
+
+// src/wrap.ts
+function isMailcapCaptureEnabled(overrides = {}) {
+  const config = { ...readConfigFromEnv(), ...overrides };
+  return Boolean(config.captureApiKey);
+}
+async function captureRaw(message, overrides = {}) {
+  const config = { ...readConfigFromEnv(), ...overrides };
+  const validated = emailMessageSchema.parse(message);
+  const result = await deliverToCapture(validated, config);
+  return { id: result.id };
+}
+function normalizeRecipients(value) {
+  if (!value) return [];
+  if (typeof value === "string") return value.split(",").map((s) => s.trim()).filter(Boolean);
+  if (Array.isArray(value)) {
+    return value.map((v) => typeof v === "string" ? v : v.email);
+  }
+  return [];
+}
+function mailgunPayloadToMessage(data) {
+  const template = data.template ? {
+    id: String(data.template),
+    provider: "mailgun",
+    data: data["t:variables"] ? JSON.parse(String(data["t:variables"])) : void 0
+  } : void 0;
+  return emailMessageSchema.parse({
+    from: data.from,
+    to: normalizeRecipients(data.to),
+    cc: normalizeRecipients(data.cc),
+    bcc: normalizeRecipients(data.bcc),
+    subject: data.subject,
+    html: data.html,
+    text: data.text,
+    template
+  });
+}
+function wrapMailgunClient(client, overrides = {}) {
+  return {
+    messages: {
+      async create(domain, data) {
+        const config = { ...readConfigFromEnv(), ...overrides };
+        if (config.captureApiKey) {
+          const message = mailgunPayloadToMessage(data);
+          const result = await deliverToCapture(message, config);
+          return { id: result.id, message: "Queued. Thank you." };
+        }
+        assertRealSendAllowed(config);
+        return client.messages.create(domain, data);
+      }
+    }
+  };
+}
+function sendgridPayloadToMessage(msg) {
+  const personalizations = msg.personalizations;
+  const first = personalizations?.[0];
+  const template = msg.templateId ? {
+    id: String(msg.templateId),
+    provider: "sendgrid",
+    data: msg.dynamicTemplateData
+  } : void 0;
+  const from = typeof msg.from === "string" ? msg.from : msg.from?.email;
+  return emailMessageSchema.parse({
+    from,
+    to: normalizeRecipients(first?.to ?? msg.to),
+    cc: normalizeRecipients(first?.cc ?? msg.cc),
+    bcc: normalizeRecipients(first?.bcc ?? msg.bcc),
+    subject: msg.subject,
+    html: msg.html,
+    text: msg.text,
+    template
+  });
+}
+function wrapSendGridClient(client, overrides = {}) {
+  return {
+    async send(msg) {
+      const config = { ...readConfigFromEnv(), ...overrides };
+      if (config.captureApiKey) {
+        const message = sendgridPayloadToMessage(msg);
+        const result = await deliverToCapture(message, config);
+        return [{ statusCode: 202, headers: { "x-message-id": result.id } }, {}];
+      }
+      assertRealSendAllowed(config);
+      return client.send(msg);
+    }
+  };
+}
+function resendPayloadToMessage(payload) {
+  return emailMessageSchema.parse({
+    from: payload.from,
+    to: normalizeRecipients(payload.to),
+    cc: normalizeRecipients(payload.cc),
+    bcc: normalizeRecipients(payload.bcc),
+    subject: payload.subject,
+    html: payload.html,
+    text: payload.text
+  });
+}
+function wrapResendClient(client, overrides = {}) {
+  return {
+    emails: {
+      async send(payload) {
+        const config = { ...readConfigFromEnv(), ...overrides };
+        if (config.captureApiKey) {
+          const message = resendPayloadToMessage(payload);
+          const result = await deliverToCapture(message, config);
+          return { data: { id: result.id }, error: null };
+        }
+        assertRealSendAllowed(config);
+        return client.emails.send(payload);
+      }
+    }
+  };
+}
+export {
+  MailcapConfigError,
+  MailcapIngestError,
+  MailcapRealSendGuardError,
+  ProviderDeliveryError,
+  __resetDefaultMailer,
+  attachmentSchema,
+  captureRaw,
+  createMailer,
+  createMailgunAdapter,
+  createResendAdapter,
+  createSendGridAdapter,
+  emailMessageSchema,
+  ingestResponseSchema,
+  isMailcapCaptureEnabled,
+  sendEmail,
+  templateRefSchema,
+  wrapMailgunClient,
+  wrapResendClient,
+  wrapSendGridClient
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@elevora-tech/mailcap",
+  "version": "0.2.0",
+  "description": "Zero-branching email SDK: captures in dev/staging via Mailcap, delivers for real via Resend, SendGrid, or Mailgun in production.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "email",
+    "testing",
+    "resend",
+    "sendgrid",
+    "mailgun",
+    "sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Elevora-Tech/mailcap-sdk"
+  },
+  "homepage": "https://github.com/Elevora-Tech/mailcap-sdk#readme",
+  "bugs": "https://github.com/Elevora-Tech/mailcap-sdk/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.17.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.64.0",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}