@headless-lms/adapter-email-ses 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdwt
+
+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,27 @@
+# @headless-lms/adapter-email-ses
+
+AWS SES (SESv2) implementation of the `EmailSender` port from `@headless-lms/core/types`.
+
+The adapter reads no environment itself — the installation's `config.ts` parses
+env into a `SesEmailConfig` and injects the constructed adapter:
+
+```ts
+import { SesEmailAdapter } from "@headless-lms/adapter-email-ses";
+
+const container = await createContainer(config, {
+  adapters: { email: new SesEmailAdapter({ region, from }) },
+});
+```
+
+Omit `accessKeyId`/`secretAccessKey` to use the default AWS credential chain
+(IAM role, env vars, shared profile).
+
+## Environment variables (reference installation)
+
+| Variable                 | Required | Maps to                | Notes                                                       |
+| ------------------------ | -------- | ---------------------- | ----------------------------------------------------------- |
+| `SES_REGION`             | yes      | `region`               |                                                             |
+| `EMAIL_FROM`             | yes      | `from`                 | e.g. `Acme LMS <noreply@acme.com>`, a verified SES identity.|
+| `SES_ACCESS_KEY`         | no       | `accessKeyId`          | Omit for the default credential chain.                      |
+| `SES_SECRET_KEY`         | no       | `secretAccessKey`      | Omit for the default credential chain.                      |
+| `SES_CONFIGURATION_SET`  | no       | `configurationSetName` | SES configuration set to send through.                      |

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { SendEmailCommand } from "@aws-sdk/client-sesv2";
+import { EmailMessage, EmailSender, Logger } from "@headless-lms/core/types";
+//#region src/index.d.ts
+interface SesEmailConfig {
+  region: string;
+  /** Sender, e.g. "Acme LMS <noreply@acme.com>". Must be a verified SES identity. */
+  from: string;
+  /** Omit both keys to use the default AWS credential chain (IAM role, env, profile). */
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  /** SES configuration set to send through. */
+  configurationSetName?: string;
+}
+interface SesClient {
+  send(command: SendEmailCommand): Promise<unknown>;
+}
+declare class SesEmailAdapter implements EmailSender {
+  private readonly config;
+  private readonly logger?;
+  private readonly client;
+  constructor(config: SesEmailConfig, logger?: Logger | undefined, client?: SesClient);
+  send(message: EmailMessage): Promise<void>;
+}
+//#endregion
+export { SesEmailAdapter, SesEmailConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,56 @@
+import { SESv2Client, SendEmailCommand } from "@aws-sdk/client-sesv2";
+//#region src/index.ts
+var SesEmailAdapter = class {
+	config;
+	logger;
+	client;
+	constructor(config, logger, client) {
+		this.config = config;
+		this.logger = logger;
+		this.client = client ?? new SESv2Client({
+			region: config.region,
+			...config.accessKeyId && config.secretAccessKey ? { credentials: {
+				accessKeyId: config.accessKeyId,
+				secretAccessKey: config.secretAccessKey
+			} } : {}
+		});
+	}
+	async send(message) {
+		const command = new SendEmailCommand({
+			FromEmailAddress: this.config.from,
+			Destination: { ToAddresses: [message.to] },
+			...this.config.configurationSetName ? { ConfigurationSetName: this.config.configurationSetName } : {},
+			Content: { Simple: {
+				Subject: {
+					Data: message.subject,
+					Charset: "UTF-8"
+				},
+				Body: {
+					Text: {
+						Data: message.text,
+						Charset: "UTF-8"
+					},
+					...message.html !== void 0 ? { Html: {
+						Data: message.html,
+						Charset: "UTF-8"
+					} } : {}
+				}
+			} }
+		});
+		try {
+			await this.client.send(command);
+		} catch (err) {
+			const e = err;
+			this.logger?.error("email send failed", {
+				to: message.to,
+				name: e?.name ?? "",
+				detail: e?.message ?? ""
+			});
+			throw err;
+		}
+	}
+};
+//#endregion
+export { SesEmailAdapter };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// AWS SES implementation of the EmailSender port.\nimport { SendEmailCommand, SESv2Client } from \"@aws-sdk/client-sesv2\";\nimport type { EmailSender, EmailMessage, Logger } from \"@headless-lms/core/types\";\n\nexport interface SesEmailConfig {\n  region: string;\n  /** Sender, e.g. \"Acme LMS <noreply@acme.com>\". Must be a verified SES identity. */\n  from: string;\n  /** Omit both keys to use the default AWS credential chain (IAM role, env, profile). */\n  accessKeyId?: string;\n  secretAccessKey?: string;\n  /** SES configuration set to send through. */\n  configurationSetName?: string;\n}\n\ninterface SesClient {\n  send(command: SendEmailCommand): Promise<unknown>;\n}\n\nexport class SesEmailAdapter implements EmailSender {\n  private readonly client: SesClient;\n\n  constructor(\n    private readonly config: SesEmailConfig,\n    private readonly logger?: Logger,\n    client?: SesClient,\n  ) {\n    this.client =\n      client ??\n      new SESv2Client({\n        region: config.region,\n        ...(config.accessKeyId && config.secretAccessKey\n          ? {\n              credentials: {\n                accessKeyId: config.accessKeyId,\n                secretAccessKey: config.secretAccessKey,\n              },\n            }\n          : {}),\n      });\n  }\n\n  async send(message: EmailMessage): Promise<void> {\n    const command = new SendEmailCommand({\n      FromEmailAddress: this.config.from,\n      Destination: { ToAddresses: [message.to] },\n      ...(this.config.configurationSetName\n        ? { ConfigurationSetName: this.config.configurationSetName }\n        : {}),\n      Content: {\n        Simple: {\n          Subject: { Data: message.subject, Charset: \"UTF-8\" },\n          Body: {\n            Text: { Data: message.text, Charset: \"UTF-8\" },\n            ...(message.html !== undefined\n              ? { Html: { Data: message.html, Charset: \"UTF-8\" } }\n              : {}),\n          },\n        },\n      },\n    });\n    try {\n      await this.client.send(command);\n    } catch (err) {\n      const e = err as { name?: string; message?: string };\n      this.logger?.error(\"email send failed\", {\n        to: message.to,\n        name: e?.name ?? \"\",\n        detail: e?.message ?? \"\",\n      });\n      throw err;\n    }\n  }\n}\n"],"mappings":";;AAmBA,IAAa,kBAAb,MAAoD;CAI/B;CACA;CAJnB;CAEA,YACE,QACA,QACA,QACA;EAHiB,KAAA,SAAA;EACA,KAAA,SAAA;EAGjB,KAAK,SACH,UACA,IAAI,YAAY;GACd,QAAQ,OAAO;GACf,GAAI,OAAO,eAAe,OAAO,kBAC7B,EACE,aAAa;IACX,aAAa,OAAO;IACpB,iBAAiB,OAAO;GAC1B,EACF,IACA,CAAC;EACP,CAAC;CACL;CAEA,MAAM,KAAK,SAAsC;EAC/C,MAAM,UAAU,IAAI,iBAAiB;GACnC,kBAAkB,KAAK,OAAO;GAC9B,aAAa,EAAE,aAAa,CAAC,QAAQ,EAAE,EAAE;GACzC,GAAI,KAAK,OAAO,uBACZ,EAAE,sBAAsB,KAAK,OAAO,qBAAqB,IACzD,CAAC;GACL,SAAS,EACP,QAAQ;IACN,SAAS;KAAE,MAAM,QAAQ;KAAS,SAAS;IAAQ;IACnD,MAAM;KACJ,MAAM;MAAE,MAAM,QAAQ;MAAM,SAAS;KAAQ;KAC7C,GAAI,QAAQ,SAAS,KAAA,IACjB,EAAE,MAAM;MAAE,MAAM,QAAQ;MAAM,SAAS;KAAQ,EAAE,IACjD,CAAC;IACP;GACF,EACF;EACF,CAAC;EACD,IAAI;GACF,MAAM,KAAK,OAAO,KAAK,OAAO;EAChC,SAAS,KAAK;GACZ,MAAM,IAAI;GACV,KAAK,QAAQ,MAAM,qBAAqB;IACtC,IAAI,QAAQ;IACZ,MAAM,GAAG,QAAQ;IACjB,QAAQ,GAAG,WAAW;GACxB,CAAC;GACD,MAAM;EACR;CACF;AACF"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@headless-lms/adapter-email-ses",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-sesv2": "^3.712.0",
+    "@headless-lms/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "description": "AWS SES email adapter for the headless LMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "adapters/email-ses"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}