@porulle/adapter-ses 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# @porulle/adapter-ses
+
+Transactional email via [AWS SES v2](https://docs.aws.amazon.com/ses/latest/dg/Welcome.html).
+
+## Usage
+
+```ts
+import { defineConfig } from "@porulle/core";
+import { sesEmailAdapter } from "@porulle/adapter-ses";
+
+export default defineConfig({
+  email: {
+    send: sesEmailAdapter({
+      region: "us-east-1",
+      from: "Acme Store <orders@acme.com>",      // must be a verified SES identity
+      credentials: {                              // optional — falls back to AWS credential chain
+        accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      },
+      subjects: { "order-confirmation": (d) => `Order ${d.orderNumber}` },
+      templates: { "order-confirmation": (d) => `<p>Thanks!</p>` },
+    }),
+  },
+  // …
+});
+```
+
+## Notes
+
+- The `from` address must be a verified identity in SES (domain or address). If you're in the SES sandbox, all recipients must be verified too.
+- Credentials are optional — the adapter uses the default AWS credential chain (env vars, IAM role, profile) if `credentials` is omitted.
+- For Workers / non-Node runtimes, prefer `@porulle/adapter-resend` (the AWS SDK isn't worker-friendly).
+
+## See also
+
+- [AWS SES v2 API reference](https://docs.aws.amazon.com/ses/latest/APIReference-V2/Welcome.html)
+- `@porulle/adapter-resend` — simpler, edge-friendly alternative

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+export interface SESAdapterOptions {
+    /** AWS region (e.g., "us-east-1"). */
+    region: string;
+    /** Default sender address (e.g., "Acme Store <orders@acme.com>"). Must be verified in SES. */
+    from: string;
+    /** AWS credentials. If omitted, uses the default credential chain (env vars, IAM role, etc.). */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+    /**
+     * Maps template names to subject line generators.
+     * If a template is not in this map, the subject defaults to the template name.
+     */
+    subjects?: Record<string, (data: Record<string, unknown>) => string>;
+    /**
+     * Maps template names to HTML body generators.
+     * If a template is not in this map, a minimal default is used.
+     */
+    templates?: Record<string, (data: Record<string, unknown>) => string>;
+}
+/**
+ * Creates an email adapter backed by AWS SES v2.
+ *
+ * Implements the `config.email.send()` interface consumed by checkout hooks,
+ * auth (password reset, email verification), and appointment plugin notifications.
+ *
+ * Sender address must be verified in SES. If your account is in the SES sandbox,
+ * recipient addresses must also be verified.
+ *
+ * @example
+ * ```typescript
+ * import { sesAdapter } from "@porulle/adapter-ses";
+ *
+ * export default defineConfig({
+ *   email: sesAdapter({
+ *     region: "us-east-1",
+ *     from: "Acme Store <orders@acme.com>",
+ *   }),
+ * });
+ * ```
+ */
+export declare function sesAdapter(options: SESAdapterOptions): {
+    send(input: {
+        template: string;
+        to: string;
+        data?: Record<string, unknown>;
+    }): Promise<void>;
+};
+//# 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":"AAEA,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,WAAW,CAAC,EAAE;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IACrE;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;CACvE;AAgCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG;IACtD,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9F,CAyCA"}

package/dist/index.js

@@ -0,0 +1,79 @@
+import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
+const DEFAULT_SUBJECTS = {
+    "order-confirmation": (d) => `Order Confirmed${d.orderId ? ` - #${String(d.orderId).slice(0, 8)}` : ""}`,
+    "order-status-change": (d) => `Order Update - ${d.newStatus ?? "Status Changed"}`,
+    "password-reset": () => "Reset Your Password",
+    "email-verification": () => "Verify Your Email Address",
+    "appointment:reminder": (d) => `Appointment Reminder${d.reminderType === "1h" ? " - Starting Soon" : ""}`,
+    "appointment:confirmation-notice": () => "Appointment Confirmed",
+    "appointment:cancellation-notice": () => "Appointment Cancelled",
+    "appointment:no-show-notice": () => "Missed Appointment",
+};
+const DEFAULT_TEMPLATES = {
+    "order-confirmation": (d) => `<h2>Order Confirmed</h2><p>Thank you for your order${d.orderId ? ` <strong>#${String(d.orderId).slice(0, 8)}</strong>` : ""}.</p>${d.total ? `<p>Total: ${d.currency ?? "USD"} ${String(d.total)}</p>` : ""}`,
+    "order-status-change": (d) => `<h2>Order Update</h2><p>Your order${d.orderId ? ` <strong>#${String(d.orderId).slice(0, 8)}</strong>` : ""} status has been updated to <strong>${d.newStatus ?? "unknown"}</strong>.</p>`,
+    "password-reset": (d) => `<h2>Reset Your Password</h2><p>Click the link below to reset your password:</p><p><a href="${d.url ?? "#"}">Reset Password</a></p>`,
+    "email-verification": (d) => `<h2>Verify Your Email</h2><p>Click the link below to verify your email address:</p><p><a href="${d.url ?? "#"}">Verify Email</a></p>`,
+    "appointment:reminder": (d) => `<h2>Appointment Reminder</h2><p>This is a${d.reminderType === "1h" ? " 1-hour" : " 24-hour"} reminder for your upcoming appointment.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+    "appointment:confirmation-notice": (d) => `<h2>Appointment Confirmed</h2><p>Your appointment has been confirmed.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+    "appointment:cancellation-notice": (d) => `<h2>Appointment Cancelled</h2><p>Your appointment has been cancelled.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+    "appointment:no-show-notice": (d) => `<h2>Missed Appointment</h2><p>You missed your appointment. Please contact us to rebook.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+};
+/**
+ * Creates an email adapter backed by AWS SES v2.
+ *
+ * Implements the `config.email.send()` interface consumed by checkout hooks,
+ * auth (password reset, email verification), and appointment plugin notifications.
+ *
+ * Sender address must be verified in SES. If your account is in the SES sandbox,
+ * recipient addresses must also be verified.
+ *
+ * @example
+ * ```typescript
+ * import { sesAdapter } from "@porulle/adapter-ses";
+ *
+ * export default defineConfig({
+ *   email: sesAdapter({
+ *     region: "us-east-1",
+ *     from: "Acme Store <orders@acme.com>",
+ *   }),
+ * });
+ * ```
+ */
+export function sesAdapter(options) {
+    const client = new SESv2Client({
+        region: options.region,
+        ...(options.credentials ? { credentials: options.credentials } : {}),
+    });
+    const subjects = { ...DEFAULT_SUBJECTS, ...options.subjects };
+    const templates = { ...DEFAULT_TEMPLATES, ...options.templates };
+    return {
+        async send(input) {
+            const data = input.data ?? {};
+            const subjectFn = subjects[input.template];
+            const subject = subjectFn ? subjectFn(data) : input.template;
+            const templateFn = templates[input.template];
+            const html = templateFn
+                ? templateFn(data)
+                : `<p>Notification: ${input.template}</p><pre>${JSON.stringify(data, null, 2)}</pre>`;
+            const command = new SendEmailCommand({
+                FromEmailAddress: options.from,
+                Destination: {
+                    ToAddresses: [input.to],
+                },
+                Content: {
+                    Simple: {
+                        Subject: { Data: subject, Charset: "UTF-8" },
+                        Body: {
+                            Html: { Data: html, Charset: "UTF-8" },
+                        },
+                    },
+                },
+            });
+            const result = await client.send(command);
+            if (!result.MessageId) {
+                throw new Error("SES email failed: no MessageId returned");
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@porulle/adapter-ses",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@aws-sdk/client-sesv2": "^3.700.0"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "description": "Transactional email via AWS SES v2.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/adapters/adapter-ses"
+  },
+  "author": "Porulle contributors"
+}

package/src/index.ts

@@ -0,0 +1,119 @@
+import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
+
+export interface SESAdapterOptions {
+  /** AWS region (e.g., "us-east-1"). */
+  region: string;
+  /** Default sender address (e.g., "Acme Store <orders@acme.com>"). Must be verified in SES. */
+  from: string;
+  /** AWS credentials. If omitted, uses the default credential chain (env vars, IAM role, etc.). */
+  credentials?: {
+    accessKeyId: string;
+    secretAccessKey: string;
+  };
+  /**
+   * Maps template names to subject line generators.
+   * If a template is not in this map, the subject defaults to the template name.
+   */
+  subjects?: Record<string, (data: Record<string, unknown>) => string>;
+  /**
+   * Maps template names to HTML body generators.
+   * If a template is not in this map, a minimal default is used.
+   */
+  templates?: Record<string, (data: Record<string, unknown>) => string>;
+}
+
+const DEFAULT_SUBJECTS: Record<string, (data: Record<string, unknown>) => string> = {
+  "order-confirmation": (d) => `Order Confirmed${d.orderId ? ` - #${String(d.orderId).slice(0, 8)}` : ""}`,
+  "order-status-change": (d) => `Order Update - ${d.newStatus ?? "Status Changed"}`,
+  "password-reset": () => "Reset Your Password",
+  "email-verification": () => "Verify Your Email Address",
+  "appointment:reminder": (d) => `Appointment Reminder${d.reminderType === "1h" ? " - Starting Soon" : ""}`,
+  "appointment:confirmation-notice": () => "Appointment Confirmed",
+  "appointment:cancellation-notice": () => "Appointment Cancelled",
+  "appointment:no-show-notice": () => "Missed Appointment",
+};
+
+const DEFAULT_TEMPLATES: Record<string, (data: Record<string, unknown>) => string> = {
+  "order-confirmation": (d) =>
+    `<h2>Order Confirmed</h2><p>Thank you for your order${d.orderId ? ` <strong>#${String(d.orderId).slice(0, 8)}</strong>` : ""}.</p>${d.total ? `<p>Total: ${d.currency ?? "USD"} ${String(d.total)}</p>` : ""}`,
+  "order-status-change": (d) =>
+    `<h2>Order Update</h2><p>Your order${d.orderId ? ` <strong>#${String(d.orderId).slice(0, 8)}</strong>` : ""} status has been updated to <strong>${d.newStatus ?? "unknown"}</strong>.</p>`,
+  "password-reset": (d) =>
+    `<h2>Reset Your Password</h2><p>Click the link below to reset your password:</p><p><a href="${d.url ?? "#"}">Reset Password</a></p>`,
+  "email-verification": (d) =>
+    `<h2>Verify Your Email</h2><p>Click the link below to verify your email address:</p><p><a href="${d.url ?? "#"}">Verify Email</a></p>`,
+  "appointment:reminder": (d) =>
+    `<h2>Appointment Reminder</h2><p>This is a${d.reminderType === "1h" ? " 1-hour" : " 24-hour"} reminder for your upcoming appointment.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+  "appointment:confirmation-notice": (d) =>
+    `<h2>Appointment Confirmed</h2><p>Your appointment has been confirmed.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+  "appointment:cancellation-notice": (d) =>
+    `<h2>Appointment Cancelled</h2><p>Your appointment has been cancelled.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+  "appointment:no-show-notice": (d) =>
+    `<h2>Missed Appointment</h2><p>You missed your appointment. Please contact us to rebook.</p><p>Booking ID: ${d.bookingId ?? "N/A"}</p>`,
+};
+
+/**
+ * Creates an email adapter backed by AWS SES v2.
+ *
+ * Implements the `config.email.send()` interface consumed by checkout hooks,
+ * auth (password reset, email verification), and appointment plugin notifications.
+ *
+ * Sender address must be verified in SES. If your account is in the SES sandbox,
+ * recipient addresses must also be verified.
+ *
+ * @example
+ * ```typescript
+ * import { sesAdapter } from "@porulle/adapter-ses";
+ *
+ * export default defineConfig({
+ *   email: sesAdapter({
+ *     region: "us-east-1",
+ *     from: "Acme Store <orders@acme.com>",
+ *   }),
+ * });
+ * ```
+ */
+export function sesAdapter(options: SESAdapterOptions): {
+  send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void>;
+} {
+  const client = new SESv2Client({
+    region: options.region,
+    ...(options.credentials ? { credentials: options.credentials } : {}),
+  });
+
+  const subjects = { ...DEFAULT_SUBJECTS, ...options.subjects };
+  const templates = { ...DEFAULT_TEMPLATES, ...options.templates };
+
+  return {
+    async send(input) {
+      const data = input.data ?? {};
+      const subjectFn = subjects[input.template];
+      const subject = subjectFn ? subjectFn(data) : input.template;
+
+      const templateFn = templates[input.template];
+      const html = templateFn
+        ? templateFn(data)
+        : `<p>Notification: ${input.template}</p><pre>${JSON.stringify(data, null, 2)}</pre>`;
+
+      const command = new SendEmailCommand({
+        FromEmailAddress: options.from,
+        Destination: {
+          ToAddresses: [input.to],
+        },
+        Content: {
+          Simple: {
+            Subject: { Data: subject, Charset: "UTF-8" },
+            Body: {
+              Html: { Data: html, Charset: "UTF-8" },
+            },
+          },
+        },
+      });
+
+      const result = await client.send(command);
+      if (!result.MessageId) {
+        throw new Error("SES email failed: no MessageId returned");
+      }
+    },
+  };
+}