@upyo/ses 0.2.0-dev.19

package/README.md

@@ -0,0 +1,255 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/ses
+=========
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+[Amazon SES] transport for the [Upyo] email library.
+
+[JSR]: https://jsr.io/@upyo/ses
+[JSR badge]: https://jsr.io/badges/@upyo/ses
+[npm]: https://www.npmjs.com/package/@upyo/ses
+[npm badge]: https://img.shields.io/npm/v/@upyo/ses?logo=npm
+[Amazon SES]: https://aws.amazon.com/ses/
+[Upyo]: https://upyo.org/
+
+
+Features
+--------
+
+ -  **Multiple Authentication Methods**: Support for AWS credentials and session
+    tokens
+ -  **Zero Dependencies**: Uses built-in APIs for cross-runtime compatibility
+ -  **AWS Signature v4**: Full implementation of AWS authentication protocol
+ -  **Rich Message Support**: HTML, text, attachments, tags, and priority
+    handling
+ -  **Cross-Runtime**: Works on Node.js, Deno, Bun, and edge functions
+ -  **Type Safety**: Discriminated union types for mutually exclusive
+    authentication methods
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/ses
+pnpm add       @upyo/core @upyo/ses
+yarn add       @upyo/core @upyo/ses
+deno add --jsr @upyo/core @upyo/ses
+bun  add       @upyo/core @upyo/ses
+~~~~
+
+
+Usage
+-----
+
+### Basic Usage with AWS Credentials
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { SesTransport } from "@upyo/ses";
+
+const transport = new SesTransport({
+  authentication: {
+    type: "credentials",
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+  region: "us-east-1",
+});
+
+const message = createMessage({
+  from: "sender@example.com",
+  to: "recipient@example.net",
+  subject: "Hello from Upyo!",
+  content: { text: "This is a test email sent via Amazon SES." },
+});
+
+const receipt = await transport.send(message);
+if (receipt.successful) {
+  console.log("Message sent with ID:", receipt.messageId);
+} else {
+  console.error("Send failed:", receipt.errorMessages.join(", "));
+}
+~~~~
+
+### Using Session Token (Temporary Credentials)
+
+~~~~ typescript
+import { SesTransport } from "@upyo/ses";
+
+const transport = new SesTransport({
+  authentication: {
+    type: "session",
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    sessionToken: process.env.AWS_SESSION_TOKEN!,
+  },
+  region: "us-west-2",
+});
+~~~~
+
+### Using IAM Roles
+
+For IAM role-based authentication, perform the AssumeRole operation externally
+(e.g., using AWS CLI or SDK) and use the resulting temporary credentials with
+the `session` authentication type:
+
+~~~~ typescript
+import { SesTransport } from "@upyo/ses";
+
+// First, assume the role externally:
+// aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/SesRole" --role-session-name "ses-session"
+
+const transport = new SesTransport({
+  authentication: {
+    type: "session",
+    accessKeyId: "ASIAXYZ...",      // From AssumeRole response
+    secretAccessKey: "abc123...",   // From AssumeRole response
+    sessionToken: "FwoGZXIv...",    // From AssumeRole response
+  },
+  region: "eu-west-1",
+});
+~~~~
+
+### HTML Email with Attachments
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { SesTransport } from "@upyo/ses";
+import fs from "node:fs/promises";
+
+const transport = new SesTransport({
+  authentication: {
+    type: "credentials",
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+const message = createMessage({
+  from: { address: "sender@example.com", name: "John Sender" },
+  to: [
+    { address: "recipient1@example.net", name: "Jane Doe" },
+    "recipient2@example.net",
+  ],
+  cc: "manager@example.com",
+  replyTo: "support@example.com",
+  subject: "Monthly Report",
+  content: {
+    html: "<h1>Monthly Report</h1><p>Please find the report attached.</p>",
+    text: "Monthly Report\n\nPlease find the report attached.",
+  },
+  attachments: [
+    new File(
+      [await fs.readFile("report.pdf")],
+      "report.pdf",
+      { type: "application/pdf" }
+    ),
+  ],
+  tags: ["report", "monthly"],
+  priority: "high",
+});
+
+const receipt = await transport.send(message);
+~~~~
+
+### Bulk Sending
+
+~~~~ typescript
+import { SesTransport } from "@upyo/ses";
+
+const transport = new SesTransport({
+  authentication: {
+    type: "credentials",
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+const messages = [
+  createMessage({ /* message 1 */ }),
+  createMessage({ /* message 2 */ }),
+  createMessage({ /* message 3 */ }),
+];
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log("Sent:", receipt.messageId);
+  } else {
+    console.error("Failed:", receipt.errorMessages);
+  }
+}
+~~~~
+
+
+Configuration
+-------------
+
+| Option                 | Type                     | Default       | Description                                                     |
+| ---------------------- | ------------------------ | ------------- | --------------------------------------------------------------- |
+| `authentication`       | `SesAuthentication`      | Required      | Authentication configuration (credentials or session)           |
+| `region`               | `string`                 | `"us-east-1"` | AWS region for SES API endpoints                                |
+| `timeout`              | `number`                 | `30000`       | HTTP request timeout in milliseconds                            |
+| `retries`              | `number`                 | `3`           | Number of retry attempts for failed requests                    |
+| `validateSsl`          | `boolean`                | `true`        | Whether to validate SSL certificates                            |
+| `headers`              | `Record<string, string>` | `{}`          | Additional HTTP headers to include                              |
+| `configurationSetName` | `string`                 | `undefined`   | SES configuration set name for tracking                         |
+| `defaultTags`          | `Record<string, string>` | `{}`          | Default tags to apply to all messages                           |
+| `batchSize`            | `number`                 | `50`          | Maximum number of messages to send concurrently in `sendMany()` |
+
+### Authentication Types
+
+The `authentication` field accepts one of two mutually exclusive types:
+
+#### Credentials Authentication
+~~~~ typescript
+{
+  type: "credentials",
+  accessKeyId: string,
+  secretAccessKey: string,
+}
+~~~~
+
+#### Session Token Authentication
+~~~~ typescript
+{
+  type: "session",
+  accessKeyId: string,
+  secretAccessKey: string,
+  sessionToken: string,
+}
+~~~~
+
+> [!NOTE]
+> For IAM role-based authentication, use external tools to perform AssumeRole
+> and provide the resulting temporary credentials via the `session`
+> authentication type.
+
+
+Error Handling
+--------------
+
+The transport returns a `Receipt` object that uses a discriminated union for
+type-safe error handling:
+
+~~~~ typescript
+const receipt = await transport.send(message);
+
+if (receipt.successful) {
+  // Type is { successful: true; messageId: string }
+  console.log("Message ID:", receipt.messageId);
+} else {
+  // Type is { successful: false; errorMessages: readonly string[] }
+  console.error("Errors:", receipt.errorMessages);
+}
+~~~~
+
+Common SES errors include:
+
+ -  `InvalidParameterValue`: Invalid email addresses or configuration
+ -  `LimitExceededException`: Send rate or quota limits exceeded
+ -  `AccountSuspendedException`: SES account suspended
+ -  `ConfigurationSetDoesNotExistException`: Invalid configuration set name

package/dist/index.cjs

@@ -0,0 +1,433 @@
+
+//#region src/config.ts
+/**
+* Creates a resolved SES configuration with default values applied.
+*
+* This function takes a partial SES configuration and fills in default values
+* for all optional fields, ensuring the transport has all necessary configuration.
+*
+* @example
+* ```typescript
+* const config = createSesConfig({
+*   authentication: {
+*     type: "credentials",
+*     accessKeyId: "AKIA...",
+*     secretAccessKey: "wJal..",
+*   },
+*   region: "eu-west-1",
+* });
+*
+* // config.timeout is now 30000 (default)
+* // config.retries is now 3 (default)
+* // config.batchSize is now 50 (default)
+* ```
+*
+* @param config The SES configuration object.
+* @returns A resolved configuration with all defaults applied.
+*/
+function createSesConfig(config) {
+	return {
+		authentication: config.authentication,
+		region: config.region ?? "us-east-1",
+		timeout: config.timeout ?? 3e4,
+		retries: config.retries ?? 3,
+		validateSsl: config.validateSsl ?? true,
+		headers: config.headers ?? {},
+		configurationSetName: config.configurationSetName,
+		defaultTags: config.defaultTags ?? {},
+		batchSize: config.batchSize ?? 50
+	};
+}
+
+//#endregion
+//#region src/http-client.ts
+var SesHttpClient = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	sendMessage(messageData, signal) {
+		const region = this.config.region;
+		const url = `https://email.${region}.amazonaws.com/v2/email/outbound-emails`;
+		return this.makeRequest(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(messageData),
+			signal
+		});
+	}
+	async makeRequest(url, options) {
+		let lastError = null;
+		for (let attempt = 0; attempt <= this.config.retries; attempt++) try {
+			const response = await this.fetchWithAuth(url, options);
+			const text = await response.text();
+			if (response.status === 200) return {
+				statusCode: response.status,
+				body: text,
+				headers: this.headersToRecord(response.headers)
+			};
+			let errorData;
+			try {
+				errorData = JSON.parse(text);
+			} catch {
+				errorData = { message: text || `HTTP ${response.status}` };
+			}
+			throw new SesApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.errors);
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+			if (error instanceof SesApiError && error.statusCode && error.statusCode >= 400 && error.statusCode < 500) throw error;
+			if (attempt === this.config.retries) throw error;
+			const delay = Math.pow(2, attempt) * 1e3;
+			await new Promise((resolve) => setTimeout(resolve, delay));
+		}
+		throw lastError || /* @__PURE__ */ new Error("Request failed after all retries");
+	}
+	async fetchWithAuth(url, options) {
+		const credentials = await this.getCredentials();
+		const headers = new Headers(options.headers);
+		const signedHeaders = await this.signRequest(url, {
+			...options,
+			headers
+		}, credentials);
+		for (const [key, value] of Object.entries(this.config.headers)) signedHeaders.set(key, value);
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+		let signal = controller.signal;
+		if (options.signal) {
+			signal = options.signal;
+			if (options.signal.aborted) controller.abort();
+			else options.signal.addEventListener("abort", () => controller.abort());
+		}
+		try {
+			return await globalThis.fetch(url, {
+				...options,
+				headers: signedHeaders,
+				signal
+			});
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+	async getCredentials() {
+		const auth = this.config.authentication;
+		switch (auth.type) {
+			case "credentials": return {
+				accessKeyId: auth.accessKeyId,
+				secretAccessKey: auth.secretAccessKey
+			};
+			case "session": return {
+				accessKeyId: auth.accessKeyId,
+				secretAccessKey: auth.secretAccessKey,
+				sessionToken: auth.sessionToken
+			};
+			default: throw new Error(`Unsupported authentication type: ${auth.type}`);
+		}
+	}
+	async signRequest(url, options, credentials) {
+		const parsedUrl = new URL(url);
+		const method = options.method || "GET";
+		const headers = new Headers(options.headers);
+		const host = parsedUrl.host;
+		const path = parsedUrl.pathname + parsedUrl.search;
+		const service = "ses";
+		const region = this.config.region;
+		const now = /* @__PURE__ */ new Date();
+		const amzDate = now.toISOString().replace(/[:-]|\.\d{3}/g, "");
+		const dateStamp = amzDate.substring(0, 8);
+		headers.set("Host", host);
+		headers.set("X-Amz-Date", amzDate);
+		if (credentials.sessionToken) headers.set("X-Amz-Security-Token", credentials.sessionToken);
+		const signedHeaders = "host;x-amz-date" + (credentials.sessionToken ? ";x-amz-security-token" : "");
+		const canonicalHeaders = `host:${host}\nx-amz-date:${amzDate}\n` + (credentials.sessionToken ? `x-amz-security-token:${credentials.sessionToken}\n` : "");
+		const payloadHash = await this.sha256(options.body || "");
+		const canonicalRequest = `${method}\n${path}\n\n${canonicalHeaders}\n${signedHeaders}\n${payloadHash}`;
+		const algorithm = "AWS4-HMAC-SHA256";
+		const credentialScope = `${dateStamp}/${region}/${service}/aws4_request`;
+		const stringToSign = `${algorithm}\n${amzDate}\n${credentialScope}\n${await this.sha256(canonicalRequest)}`;
+		const signingKey = await this.getSignatureKey(credentials.secretAccessKey, dateStamp, region, service);
+		const signature = await this.hmacSha256(signingKey, stringToSign);
+		const authorizationHeader = `${algorithm} Credential=${credentials.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+		headers.set("Authorization", authorizationHeader);
+		return headers;
+	}
+	async sha256(data) {
+		const encoder = new TextEncoder();
+		const dataBuffer = encoder.encode(data);
+		const hashBuffer = await crypto.subtle.digest("SHA-256", dataBuffer);
+		return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+	}
+	async hmacSha256(key, data) {
+		const encoder = new TextEncoder();
+		const dataBuffer = encoder.encode(data);
+		const cryptoKey = await crypto.subtle.importKey("raw", key, {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign"]);
+		const signature = await crypto.subtle.sign("HMAC", cryptoKey, dataBuffer);
+		return Array.from(new Uint8Array(signature)).map((b) => b.toString(16).padStart(2, "0")).join("");
+	}
+	async getSignatureKey(key, dateStamp, regionName, serviceName) {
+		const encoder = new TextEncoder();
+		let keyBuffer = new Uint8Array(encoder.encode("AWS4" + key)).buffer;
+		keyBuffer = await this.hmacSha256Buffer(keyBuffer, dateStamp);
+		keyBuffer = await this.hmacSha256Buffer(keyBuffer, regionName);
+		keyBuffer = await this.hmacSha256Buffer(keyBuffer, serviceName);
+		keyBuffer = await this.hmacSha256Buffer(keyBuffer, "aws4_request");
+		return keyBuffer;
+	}
+	async hmacSha256Buffer(key, data) {
+		const encoder = new TextEncoder();
+		const dataBuffer = encoder.encode(data);
+		const cryptoKey = await crypto.subtle.importKey("raw", key, {
+			name: "HMAC",
+			hash: "SHA-256"
+		}, false, ["sign"]);
+		return await crypto.subtle.sign("HMAC", cryptoKey, dataBuffer);
+	}
+	headersToRecord(headers) {
+		const record = {};
+		for (const [key, value] of headers.entries()) record[key] = value;
+		return record;
+	}
+};
+var SesApiError = class extends Error {
+	statusCode;
+	errors;
+	constructor(message, statusCode, errors) {
+		super(message);
+		this.name = "SesApiError";
+		this.statusCode = statusCode;
+		this.errors = errors;
+	}
+};
+
+//#endregion
+//#region src/message-converter.ts
+async function convertMessage(message, config) {
+	const destination = {};
+	if (message.recipients.length > 0) destination.ToAddresses = message.recipients.map(formatAddress);
+	if (message.ccRecipients.length > 0) destination.CcAddresses = message.ccRecipients.map(formatAddress);
+	if (message.bccRecipients.length > 0) destination.BccAddresses = message.bccRecipients.map(formatAddress);
+	const sesMessage = {
+		Destination: destination,
+		Content: {},
+		FromEmailAddress: formatAddress(message.sender)
+	};
+	if (message.replyRecipients.length > 0) sesMessage.ReplyToAddresses = message.replyRecipients.map(formatAddress);
+	if (config.configurationSetName) sesMessage.ConfigurationSetName = config.configurationSetName;
+	sesMessage.Content.Simple = await createSimpleContent(message);
+	const tags = [];
+	if (message.tags.length > 0) for (const tag of message.tags) tags.push({
+		Name: "category",
+		Value: tag
+	});
+	if (message.priority !== "normal") tags.push({
+		Name: "priority",
+		Value: message.priority
+	});
+	for (const [name, value] of Object.entries(config.defaultTags)) tags.push({
+		Name: name,
+		Value: value
+	});
+	if (tags.length > 0) sesMessage.Tags = tags;
+	return sesMessage;
+}
+async function createSimpleContent(message) {
+	const content = {
+		Subject: {
+			Data: message.subject,
+			Charset: "UTF-8"
+		},
+		Body: {}
+	};
+	if ("html" in message.content) {
+		content.Body.Html = {
+			Data: message.content.html,
+			Charset: "UTF-8"
+		};
+		if (message.content.text) content.Body.Text = {
+			Data: message.content.text,
+			Charset: "UTF-8"
+		};
+	} else content.Body.Text = {
+		Data: message.content.text,
+		Charset: "UTF-8"
+	};
+	if (message.attachments.length > 0) content.Attachments = await Promise.all(message.attachments.map(async (attachment) => {
+		const contentBytes = await attachment.content;
+		const base64Content = btoa(String.fromCharCode(...contentBytes));
+		return {
+			FileName: attachment.filename,
+			ContentType: attachment.contentType || "application/octet-stream",
+			ContentDisposition: attachment.inline ? "INLINE" : "ATTACHMENT",
+			ContentId: attachment.contentId,
+			ContentTransferEncoding: "BASE64",
+			RawContent: base64Content
+		};
+	}));
+	return content;
+}
+function formatAddress(address) {
+	if (address.name) return `"${address.name}" <${address.address}>`;
+	return address.address;
+}
+
+//#endregion
+//#region src/ses-transport.ts
+/**
+* Amazon SES email transport implementation.
+*
+* This transport sends emails through the AWS Simple Email Service (SES) using
+* the v2 API.  It supports AWS Signature v4 authentication, configurable
+* retries, and concurrent batch sending.
+*
+* @example
+* ```typescript
+* import { SesTransport } from "@upyo/ses";
+* import { createMessage } from "@upyo/core";
+*
+* const transport = new SesTransport({
+*   authentication: {
+*     type: "credentials",
+*     accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+*     secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+*   },
+*   region: "us-east-1",
+* });
+*
+* const message = createMessage({
+*   from: "sender@example.com",
+*   to: "recipient@example.com",
+*   subject: "Hello from SES",
+*   content: { text: "This is a test message" },
+* });
+*
+* const receipt = await transport.send(message);
+* if (receipt.successful) {
+*   console.log("Email sent with ID:", receipt.messageId);
+* }
+* ```
+*/
+var SesTransport = class {
+	/** Resolved configuration with defaults applied */
+	config;
+	/** HTTP client for SES API requests */
+	httpClient;
+	/**
+	* Creates a new SES transport instance.
+	*
+	* @param config SES configuration options.
+	*/
+	constructor(config) {
+		this.config = createSesConfig(config);
+		this.httpClient = new SesHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message through Amazon SES.
+	*
+	* This method converts the message to SES format, sends it via the SES v2 API,
+	* and returns a receipt indicating success or failure.
+	*
+	* @example
+	* ```typescript
+	* const message = createMessage({
+	*   from: "sender@example.com",
+	*   to: "recipient@example.com",
+	*   subject: "Hello",
+	*   content: { text: "Hello, world!" },
+	*   attachments: [{
+	*     filename: "document.pdf",
+	*     content: Promise.resolve(pdfBytes),
+	*     contentType: "application/pdf",
+	*   }],
+	* });
+	*
+	* const receipt = await transport.send(message);
+	* ```
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options (e.g., abort signal).
+	* @returns A promise that resolves to a receipt with the result.
+	*/
+	async send(message, options) {
+		options?.signal?.throwIfAborted();
+		try {
+			const sesMessage = await convertMessage(message, this.config);
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendMessage(sesMessage, options?.signal);
+			const messageId = this.extractMessageId(response);
+			return {
+				successful: true,
+				messageId
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			return {
+				successful: false,
+				errorMessages: [errorMessage]
+			};
+		}
+	}
+	/**
+	* Sends multiple email messages concurrently through Amazon SES.
+	*
+	* This method processes messages in batches (configurable via `batchSize`)
+	* and sends each batch concurrently to improve performance. It yields
+	* receipts as they become available, allowing for streaming processing of
+	* results.
+	*
+	* @example
+	* ```typescript
+	* const messages = [
+	*   createMessage({ from: "sender@example.com", to: "user1@example.com", subject: "Hello 1", content: { text: "Message 1" } }),
+	*   createMessage({ from: "sender@example.com", to: "user2@example.com", subject: "Hello 2", content: { text: "Message 2" } }),
+	*   createMessage({ from: "sender@example.com", to: "user3@example.com", subject: "Hello 3", content: { text: "Message 3" } }),
+	* ];
+	*
+	* for await (const receipt of transport.sendMany(messages)) {
+	*   if (receipt.successful) {
+	*     console.log("Sent:", receipt.messageId);
+	*   } else {
+	*     console.error("Failed:", receipt.errorMessages);
+	*   }
+	* }
+	* ```
+	*
+	* @param messages An iterable or async iterable of messages to send.
+	* @param options Optional transport options (e.g., abort signal).
+	* @returns Individual receipts for each message as they complete.
+	*/
+	async *sendMany(messages, options) {
+		options?.signal?.throwIfAborted();
+		const isAsyncIterable = Symbol.asyncIterator in messages;
+		const messageArray = [];
+		if (isAsyncIterable) for await (const message of messages) messageArray.push(message);
+		else for (const message of messages) messageArray.push(message);
+		const batchSize = this.config.batchSize;
+		for (let i = 0; i < messageArray.length; i += batchSize) {
+			options?.signal?.throwIfAborted();
+			const batch = messageArray.slice(i, i + batchSize);
+			const receipts = await this.sendConcurrent(batch, options);
+			for (const receipt of receipts) yield receipt;
+		}
+	}
+	async sendConcurrent(messages, options) {
+		options?.signal?.throwIfAborted();
+		const sendPromises = messages.map((message) => this.send(message, options));
+		return await Promise.all(sendPromises);
+	}
+	extractMessageId(response) {
+		if (response.body) try {
+			const parsed = JSON.parse(response.body);
+			if (parsed.MessageId) return parsed.MessageId;
+		} catch {}
+		const messageIdHeader = response.headers?.["x-amzn-requestid"] || response.headers?.["X-Amzn-RequestId"];
+		if (messageIdHeader) return messageIdHeader;
+		const timestamp = Date.now();
+		const random = Math.random().toString(36).substring(2, 8);
+		return `ses-${timestamp}-${random}`;
+	}
+};
+
+//#endregion
+exports.SesTransport = SesTransport;