@beignet/provider-mail-resend 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-mail-resend
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,90 @@
+# @beignet/provider-mail-resend
+
+Resend-backed mail provider for Beignet.
+
+The provider installs the app-facing `ctx.ports.mailer` port and exposes
+`ctx.ports.resend.client` only as an escape hatch for Resend-specific features.
+
+## Install
+
+```bash
+bun add @beignet/provider-mail-resend resend
+```
+
+## Setup
+
+```typescript
+import { mailResendProvider } from "@beignet/provider-mail-resend";
+import { createServer } from "@beignet/core/server";
+
+const server = await createServer({
+  ports: basePorts,
+  providers: [mailResendProvider],
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+Required environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `RESEND_API_KEY` | Resend API key |
+| `RESEND_FROM` | Default sender, e.g. `My App <no-reply@example.com>` |
+
+## Use in application code
+
+```typescript
+await ctx.ports.mailer.send({
+  to: "user@example.com",
+  subject: "Welcome",
+  html: "<h1>Hello</h1>",
+});
+```
+
+The same `MailerPort` works with SMTP, memory fakes, and other adapters:
+
+```typescript
+await ctx.ports.mailer.send({
+  from: { email: "support@example.com", name: "Support" },
+  to: ["user@example.com", "admin@example.com"],
+  replyTo: "support@example.com",
+  subject: "Account updated",
+  text: "Your account was updated.",
+  html: "<p>Your account was updated.</p>",
+});
+```
+
+## Escape hatch
+
+Use the Resend client only when you need a Resend-specific feature not covered
+by `MailerPort`:
+
+```typescript
+await ctx.ports.resend.client.emails.send({
+  from: "sender@example.com",
+  to: "user@example.com",
+  subject: "Invoice",
+  html: "<p>Attached.</p>",
+  attachments: [
+    {
+      filename: "invoice.pdf",
+      content: pdfBuffer,
+    },
+  ],
+});
+```
+
+## Devtools
+
+When `ctx.ports.devtools` is installed, this provider records `mail.send`,
+`mail.sent`, and `mail.failed` events under the `mail` watcher.
+
+## Errors
+
+Delivery failures throw `MailDeliveryError` from `@beignet/core/mail`.
+Startup configuration problems throw during provider setup.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @beignet/provider-mail-resend
+ *
+ * Resend-backed mail provider for Beignet.
+ */
+import { type MailAddress, type MailerPort } from "@beignet/core/mail";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import { Resend } from "resend";
+import { z } from "zod";
+declare const ResendMailConfigSchema: z.ZodObject<{
+    API_KEY: z.ZodString;
+    FROM: z.ZodString;
+}, z.core.$strip>;
+export type ResendMailConfig = z.infer<typeof ResendMailConfigSchema>;
+export interface ResendMailEscapeHatch {
+    client: Resend;
+}
+export interface ResendMailProviderPorts {
+    mailer: MailerPort;
+    resend: ResendMailEscapeHatch;
+}
+export interface CreateResendMailerOptions {
+    client: Resend;
+    from: MailAddress;
+    instrumentation?: ProviderInstrumentationTarget;
+}
+export declare function createResendMailer({ client, from, instrumentation: instrumentationTarget, }: CreateResendMailerOptions): MailerPort;
+export declare const mailResendProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    API_KEY: z.ZodString;
+    FROM: z.ZodString;
+}, z.core.$strip>, {
+    mailer: MailerPort;
+    resend: {
+        client: Resend;
+    };
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAGL,KAAK,WAAW,EAEhB,KAAK,UAAU,EAIhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAA2B,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAqDD,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,yBAAyB,GAAG,UAAU,CAsFxC;AAED,eAAO,MAAM,kBAAkB;;;;;;;;EAkC7B,CAAC"}

package/dist/index.js

@@ -0,0 +1,148 @@
+/**
+ * @beignet/provider-mail-resend
+ *
+ * Resend-backed mail provider for Beignet.
+ */
+import { formatMailAddress, formatMailAddressList, MailDeliveryError, normalizeMailMessage, } from "@beignet/core/mail";
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { Resend } from "resend";
+import { z } from "zod";
+const ResendMailConfigSchema = z.object({
+    API_KEY: z.string().min(1),
+    FROM: z.string().min(1),
+});
+function addOptional(target, key, value) {
+    if (value !== undefined) {
+        Object.assign(target, { [key]: value });
+    }
+}
+function createResendPayload(message, defaultFrom) {
+    const normalized = normalizeMailMessage(message, { defaultFrom });
+    if (!normalized.from) {
+        throw new MailDeliveryError({
+            provider: "resend",
+            message: "Cannot send email without a from address.",
+        });
+    }
+    const payload = {
+        from: formatMailAddress(normalized.from),
+        to: formatMailAddressList(normalized.to),
+        subject: normalized.subject,
+    };
+    addOptional(payload, "text", normalized.text);
+    addOptional(payload, "html", normalized.html);
+    addOptional(payload, "cc", normalized.cc ? formatMailAddressList(normalized.cc) : undefined);
+    addOptional(payload, "bcc", normalized.bcc ? formatMailAddressList(normalized.bcc) : undefined);
+    addOptional(payload, "replyTo", normalized.replyTo ? formatMailAddressList(normalized.replyTo) : undefined);
+    addOptional(payload, "headers", normalized.headers);
+    return payload;
+}
+export function createResendMailer({ client, from, instrumentation: instrumentationTarget, }) {
+    const instrumentation = createProviderInstrumentation(instrumentationTarget, {
+        providerName: "mail-resend",
+        watcher: "mail",
+    });
+    return {
+        async send(message) {
+            const payload = createResendPayload(message, from);
+            instrumentation.custom({
+                name: "mail.send",
+                label: "Mail send",
+                summary: `Sending "${message.subject}"`,
+                details: {
+                    provider: "resend",
+                    subject: message.subject,
+                    to: payload.to,
+                },
+            });
+            try {
+                const result = await client.emails.send(payload);
+                if (result.error) {
+                    instrumentation.custom({
+                        name: "mail.failed",
+                        label: "Mail failed",
+                        summary: `Failed to send "${message.subject}"`,
+                        details: {
+                            provider: "resend",
+                            subject: message.subject,
+                            to: payload.to,
+                            error: result.error.message,
+                        },
+                    });
+                    throw new MailDeliveryError({
+                        provider: "resend",
+                        message: result.error.message || "Resend failed to send email.",
+                        cause: result.error,
+                    });
+                }
+                instrumentation.custom({
+                    name: "mail.sent",
+                    label: "Mail sent",
+                    summary: `Sent "${message.subject}"`,
+                    details: {
+                        provider: "resend",
+                        subject: message.subject,
+                        to: payload.to,
+                        id: result.data?.id,
+                    },
+                });
+                return {
+                    id: result.data?.id,
+                    provider: "resend",
+                };
+            }
+            catch (error) {
+                if (error instanceof MailDeliveryError) {
+                    throw error;
+                }
+                instrumentation.custom({
+                    name: "mail.failed",
+                    label: "Mail failed",
+                    summary: `Failed to send "${message.subject}"`,
+                    details: {
+                        provider: "resend",
+                        subject: message.subject,
+                        to: payload.to,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+                throw new MailDeliveryError({
+                    provider: "resend",
+                    message: error instanceof Error
+                        ? error.message
+                        : "Resend failed to send email.",
+                    cause: error,
+                });
+            }
+        },
+    };
+}
+export const mailResendProvider = createProvider({
+    name: "mail-resend",
+    config: {
+        schema: ResendMailConfigSchema,
+        envPrefix: "RESEND_",
+    },
+    async setup({ config, ports }) {
+        if (!config) {
+            throw new Error("[mailResendProvider] Missing Resend config. " +
+                "Please set RESEND_API_KEY and RESEND_FROM environment variables.");
+        }
+        const client = new Resend(config.API_KEY);
+        const instrumentation = createProviderInstrumentation(ports, {
+            providerName: "mail-resend",
+            watcher: "mail",
+        });
+        const mailer = createResendMailer({
+            client,
+            from: config.FROM,
+            instrumentation,
+        });
+        return {
+            ports: {
+                mailer,
+                resend: { client },
+            },
+        };
+    },
+});

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@beignet/provider-mail-resend",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Resend mail provider for Beignet - adds mailer port using Resend",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "mail",
+    "email",
+    "provider",
+    "resend",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-mail-resend"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "resend": "^2.0.0 || ^3.0.0 || ^4.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "resend": "^4.0.1",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,224 @@
+/**
+ * @beignet/provider-mail-resend
+ *
+ * Resend-backed mail provider for Beignet.
+ */
+
+import {
+  formatMailAddress,
+  formatMailAddressList,
+  type MailAddress,
+  MailDeliveryError,
+  type MailerPort,
+  normalizeMailMessage,
+  type SendMailOptions,
+  type SendMailResult,
+} from "@beignet/core/mail";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import { type CreateEmailOptions, Resend } from "resend";
+import { z } from "zod";
+
+const ResendMailConfigSchema = z.object({
+  API_KEY: z.string().min(1),
+  FROM: z.string().min(1),
+});
+
+export type ResendMailConfig = z.infer<typeof ResendMailConfigSchema>;
+
+export interface ResendMailEscapeHatch {
+  client: Resend;
+}
+
+export interface ResendMailProviderPorts {
+  mailer: MailerPort;
+  resend: ResendMailEscapeHatch;
+}
+
+export interface CreateResendMailerOptions {
+  client: Resend;
+  from: MailAddress;
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+function addOptional<T extends Record<string, unknown>, K extends string, V>(
+  target: T,
+  key: K,
+  value: V | undefined,
+): void {
+  if (value !== undefined) {
+    Object.assign(target, { [key]: value });
+  }
+}
+
+function createResendPayload(
+  message: SendMailOptions,
+  defaultFrom: MailAddress,
+): CreateEmailOptions {
+  const normalized = normalizeMailMessage(message, { defaultFrom });
+
+  if (!normalized.from) {
+    throw new MailDeliveryError({
+      provider: "resend",
+      message: "Cannot send email without a from address.",
+    });
+  }
+
+  const payload = {
+    from: formatMailAddress(normalized.from),
+    to: formatMailAddressList(normalized.to),
+    subject: normalized.subject,
+  } satisfies Partial<CreateEmailOptions>;
+
+  addOptional(payload, "text", normalized.text);
+  addOptional(payload, "html", normalized.html);
+  addOptional(
+    payload,
+    "cc",
+    normalized.cc ? formatMailAddressList(normalized.cc) : undefined,
+  );
+  addOptional(
+    payload,
+    "bcc",
+    normalized.bcc ? formatMailAddressList(normalized.bcc) : undefined,
+  );
+  addOptional(
+    payload,
+    "replyTo",
+    normalized.replyTo ? formatMailAddressList(normalized.replyTo) : undefined,
+  );
+  addOptional(payload, "headers", normalized.headers);
+
+  return payload as CreateEmailOptions;
+}
+
+export function createResendMailer({
+  client,
+  from,
+  instrumentation: instrumentationTarget,
+}: CreateResendMailerOptions): MailerPort {
+  const instrumentation = createProviderInstrumentation(instrumentationTarget, {
+    providerName: "mail-resend",
+    watcher: "mail",
+  });
+
+  return {
+    async send(message): Promise<SendMailResult> {
+      const payload = createResendPayload(message, from);
+      instrumentation.custom({
+        name: "mail.send",
+        label: "Mail send",
+        summary: `Sending "${message.subject}"`,
+        details: {
+          provider: "resend",
+          subject: message.subject,
+          to: payload.to,
+        },
+      });
+
+      try {
+        const result = await client.emails.send(payload);
+
+        if (result.error) {
+          instrumentation.custom({
+            name: "mail.failed",
+            label: "Mail failed",
+            summary: `Failed to send "${message.subject}"`,
+            details: {
+              provider: "resend",
+              subject: message.subject,
+              to: payload.to,
+              error: result.error.message,
+            },
+          });
+          throw new MailDeliveryError({
+            provider: "resend",
+            message: result.error.message || "Resend failed to send email.",
+            cause: result.error,
+          });
+        }
+
+        instrumentation.custom({
+          name: "mail.sent",
+          label: "Mail sent",
+          summary: `Sent "${message.subject}"`,
+          details: {
+            provider: "resend",
+            subject: message.subject,
+            to: payload.to,
+            id: result.data?.id,
+          },
+        });
+
+        return {
+          id: result.data?.id,
+          provider: "resend",
+        };
+      } catch (error) {
+        if (error instanceof MailDeliveryError) {
+          throw error;
+        }
+
+        instrumentation.custom({
+          name: "mail.failed",
+          label: "Mail failed",
+          summary: `Failed to send "${message.subject}"`,
+          details: {
+            provider: "resend",
+            subject: message.subject,
+            to: payload.to,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+
+        throw new MailDeliveryError({
+          provider: "resend",
+          message:
+            error instanceof Error
+              ? error.message
+              : "Resend failed to send email.",
+          cause: error,
+        });
+      }
+    },
+  };
+}
+
+export const mailResendProvider = createProvider({
+  name: "mail-resend",
+
+  config: {
+    schema: ResendMailConfigSchema,
+    envPrefix: "RESEND_",
+  },
+
+  async setup({ config, ports }) {
+    if (!config) {
+      throw new Error(
+        "[mailResendProvider] Missing Resend config. " +
+          "Please set RESEND_API_KEY and RESEND_FROM environment variables.",
+      );
+    }
+
+    const client = new Resend(config.API_KEY);
+    const instrumentation = createProviderInstrumentation(ports, {
+      providerName: "mail-resend",
+      watcher: "mail",
+    });
+    const mailer = createResendMailer({
+      client,
+      from: config.FROM,
+      instrumentation,
+    });
+
+    return {
+      ports: {
+        mailer,
+        resend: { client },
+      } satisfies ResendMailProviderPorts,
+    };
+  },
+});