@upyo/ses 0.2.0-dev.19

package/dist/index.js

@@ -0,0 +1,432 @@
+//#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
+export { SesTransport };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@upyo/ses",
+  "version": "0.2.0-dev.19+e02d7bd8",
+  "description": "Amazon SES transport for Upyo email library",
+  "keywords": [
+    "email",
+    "mail",
+    "sendmail",
+    "ses",
+    "amazon",
+    "aws"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/ses/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/upyo/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@upyo/core": "0.2.0-dev.19+e02d7bd8"
+  },
+  "devDependencies": {
+    "@dotenvx/dotenvx": "^1.47.3",
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && dotenvx run --ignore=MISSING_ENV_FILE -- node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test --timeout=30000 --env-file=.env",
+    "test:deno": "deno test --allow-env --allow-net --env-file=.env"
+  }
+}