@upyo/resend 0.3.0-dev.33

package/dist/index.js

@@ -0,0 +1,552 @@
+//#region src/config.ts
+/**
+* Creates a resolved Resend configuration by applying default values to optional fields.
+*
+* This function takes a partial Resend configuration and returns a complete
+* configuration with all optional fields filled with sensible defaults.
+* It is used internally by the Resend transport.
+*
+* @param config - The Resend configuration with optional fields
+* @returns A resolved configuration with all defaults applied
+* @internal
+*/
+function createResendConfig(config) {
+	return {
+		apiKey: config.apiKey,
+		baseUrl: config.baseUrl ?? "https://api.resend.com",
+		timeout: config.timeout ?? 3e4,
+		retries: config.retries ?? 3,
+		validateSsl: config.validateSsl ?? true,
+		headers: config.headers ?? {}
+	};
+}
+
+//#endregion
+//#region src/http-client.ts
+/**
+* Resend API error class for handling API-specific errors.
+*/
+var ResendApiError = class extends Error {
+	statusCode;
+	constructor(message, statusCode) {
+		super(message);
+		this.name = "ResendApiError";
+		this.statusCode = statusCode;
+	}
+};
+/**
+* HTTP client wrapper for Resend API requests.
+*
+* This class handles authentication, request formatting, error handling,
+* and retry logic for Resend API calls.
+*/
+var ResendHttpClient = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Sends a single message via Resend API.
+	*
+	* @param messageData The JSON data to send to Resend.
+	* @param signal Optional AbortSignal for cancellation.
+	* @returns Promise that resolves to the Resend response.
+	*/
+	sendMessage(messageData, signal) {
+		const url = `${this.config.baseUrl}/emails`;
+		return this.makeRequest(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(messageData),
+			signal
+		});
+	}
+	/**
+	* Sends multiple messages via Resend batch API.
+	*
+	* @param messagesData Array of message data objects to send.
+	* @param signal Optional AbortSignal for cancellation.
+	* @returns Promise that resolves to the Resend batch response.
+	*/
+	sendBatch(messagesData, signal) {
+		const url = `${this.config.baseUrl}/emails/batch`;
+		return this.makeRequest(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(messagesData),
+			signal
+		});
+	}
+	/**
+	* Makes an HTTP request to Resend API with retry logic.
+	*
+	* @param url The URL to make the request to.
+	* @param options Fetch options.
+	* @returns Promise that resolves to the parsed response.
+	*/
+	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.ok) {
+				let errorMessage;
+				try {
+					const errorBody = JSON.parse(text);
+					errorMessage = errorBody.message;
+				} catch {}
+				throw new ResendApiError(errorMessage || text || `HTTP ${response.status}`, response.status);
+			}
+			try {
+				return JSON.parse(text);
+			} catch (parseError) {
+				throw new Error(`Invalid JSON response from Resend API: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+			}
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+			if (error instanceof ResendApiError && error.statusCode >= 400 && error.statusCode < 500) throw error;
+			if (error instanceof Error && error.name === "AbortError") throw error;
+			if (attempt === this.config.retries) throw lastError;
+			const backoffMs = Math.min(1e3 * Math.pow(2, attempt), 1e4);
+			await new Promise((resolve) => setTimeout(resolve, backoffMs));
+		}
+		throw lastError || /* @__PURE__ */ new Error("Request failed after all retry attempts");
+	}
+	/**
+	* Makes a fetch request with authentication headers.
+	*
+	* @param url The URL to fetch.
+	* @param options Fetch options.
+	* @returns Promise that resolves to the Response.
+	*/
+	async fetchWithAuth(url, options) {
+		const headers = new Headers(options.headers);
+		headers.set("Authorization", `Bearer ${this.config.apiKey}`);
+		for (const [key, value] of Object.entries(this.config.headers)) headers.set(key, value);
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+		let signal;
+		if (options.signal) {
+			const combinedController = new AbortController();
+			const onAbort = () => combinedController.abort();
+			options.signal.addEventListener("abort", onAbort, { once: true });
+			controller.signal.addEventListener("abort", onAbort, { once: true });
+			signal = combinedController.signal;
+		} else signal = controller.signal;
+		try {
+			const response = await fetch(url, {
+				...options,
+				headers,
+				signal
+			});
+			return response;
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+};
+
+//#endregion
+//#region src/message-converter.ts
+/**
+* Converts a Upyo Message to Resend API JSON format.
+*
+* This function transforms the standardized Upyo message format into
+* the specific format expected by the Resend API.
+*
+* @param message - The Upyo message to convert
+* @param config - The resolved Resend configuration
+* @param options - Optional conversion options
+* @returns JSON object ready for Resend API submission
+*
+* @example
+* ```typescript
+* const emailData = await convertMessage(message, config);
+* const response = await fetch(url, {
+*   method: 'POST',
+*   body: JSON.stringify(emailData),
+*   headers: { 'Content-Type': 'application/json' }
+* });
+* ```
+*/
+async function convertMessage(message, _config, options = {}) {
+	const emailData = {
+		from: formatAddress(message.sender),
+		to: message.recipients.length === 1 ? formatAddress(message.recipients[0]) : message.recipients.map(formatAddress),
+		subject: message.subject
+	};
+	if (message.ccRecipients.length > 0) emailData.cc = message.ccRecipients.map(formatAddress);
+	if (message.bccRecipients.length > 0) emailData.bcc = message.bccRecipients.map(formatAddress);
+	if (message.replyRecipients.length > 0) emailData.reply_to = formatAddress(message.replyRecipients[0]);
+	if ("html" in message.content) {
+		emailData.html = message.content.html;
+		if (message.content.text) emailData.text = message.content.text;
+	} else emailData.text = message.content.text;
+	if (message.attachments.length > 0) emailData.attachments = await Promise.all(message.attachments.map(convertAttachment));
+	if (message.tags.length > 0) emailData.tags = message.tags.map((tag, index) => ({
+		name: `tag${index + 1}`,
+		value: tag
+	}));
+	const headers = {};
+	if (message.priority !== "normal") {
+		const priorityMap = {
+			"high": "1",
+			"normal": "3",
+			"low": "5"
+		};
+		headers["X-Priority"] = priorityMap[message.priority];
+	}
+	for (const [key, value] of message.headers.entries()) if (!isStandardHeader(key)) headers[key] = value;
+	if (options.idempotencyKey) headers["Idempotency-Key"] = options.idempotencyKey;
+	if (Object.keys(headers).length > 0) emailData.headers = headers;
+	if (options.scheduledAt) emailData.scheduled_at = options.scheduledAt.toISOString();
+	return emailData;
+}
+/**
+* Converts multiple Upyo Messages to Resend batch API format.
+*
+* This function handles the batch conversion with proper validation
+* for Resend's batch API limitations.
+*
+* @param messages - Array of Upyo messages to convert
+* @param config - The resolved Resend configuration
+* @param options - Optional conversion options
+* @returns Array of JSON objects ready for Resend batch API
+*/
+async function convertMessagesBatch(messages, _config, options = {}) {
+	if (messages.length > 100) throw new Error("Resend batch API supports maximum 100 emails per request");
+	for (const message of messages) {
+		if (message.attachments.length > 0) throw new Error("Attachments are not supported in Resend batch API");
+		if (message.tags.length > 0) throw new Error("Tags are not supported in Resend batch API");
+	}
+	const batchData = await Promise.all(messages.map((message, index) => convertMessage(message, _config, {
+		...options,
+		idempotencyKey: options.idempotencyKey ? `${options.idempotencyKey}-${index}` : void 0
+	})));
+	return batchData;
+}
+/**
+* Formats an Address object into a string suitable for Resend API.
+*
+* @param address - The address to format
+* @returns Formatted address string
+*/
+function formatAddress(address) {
+	if (address.name) {
+		const name = address.name.includes("\"") || address.name.includes(",") || address.name.includes("<") || address.name.includes(">") ? `"${address.name.replace(/"/g, "\\\"")}"` : address.name;
+		return `${name} <${address.address}>`;
+	}
+	return address.address;
+}
+/**
+* Converts a Upyo Attachment to Resend attachment format.
+*
+* @param attachment - The Upyo attachment to convert
+* @returns Resend attachment object
+*/
+async function convertAttachment(attachment) {
+	const content = await attachment.content;
+	const resendAttachment = {
+		filename: attachment.filename,
+		content: await uint8ArrayToBase64(content)
+	};
+	if (attachment.contentType) resendAttachment.content_type = attachment.contentType;
+	return resendAttachment;
+}
+/**
+* Converts a Uint8Array to base64 string using pure JavaScript implementation.
+* This avoids deprecated APIs like btoa() and Node.js-specific Buffer.
+*
+* @param bytes - The Uint8Array to convert
+* @returns Base64 encoded string
+*/
+function uint8ArrayToBase64(bytes) {
+	const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+	let result = "";
+	let i = 0;
+	while (i < bytes.length) {
+		const a = bytes[i++];
+		const b = i < bytes.length ? bytes[i++] : 0;
+		const c = i < bytes.length ? bytes[i++] : 0;
+		const bitmap = a << 16 | b << 8 | c;
+		result += chars.charAt(bitmap >> 18 & 63) + chars.charAt(bitmap >> 12 & 63) + chars.charAt(bitmap >> 6 & 63) + chars.charAt(bitmap & 63);
+	}
+	const padding = 3 - (bytes.length - 1) % 3;
+	if (padding < 3) result = result.slice(0, -padding) + "=".repeat(padding);
+	return result;
+}
+/**
+* Checks if a header is a standard email header that should not be prefixed.
+*
+* @param headerName - The header name to check
+* @returns True if the header is a standard header
+*/
+function isStandardHeader(headerName) {
+	const standardHeaders = new Set([
+		"from",
+		"to",
+		"cc",
+		"bcc",
+		"reply-to",
+		"subject",
+		"content-type",
+		"content-transfer-encoding",
+		"mime-version",
+		"date",
+		"message-id"
+	]);
+	return standardHeaders.has(headerName.toLowerCase());
+}
+/**
+* Generates a random idempotency key for request deduplication.
+*
+* @returns A unique string suitable for use as an idempotency key
+*/
+function generateIdempotencyKey() {
+	const timestamp = Date.now().toString(36);
+	const random1 = Math.random().toString(36).substring(2, 15);
+	const random2 = Math.random().toString(36).substring(2, 15);
+	return `${timestamp}-${random1}${random2}`;
+}
+
+//#endregion
+//#region src/resend-transport.ts
+/**
+* Resend transport implementation for sending emails via Resend API.
+*
+* This transport provides efficient email delivery using Resend's HTTP API,
+* with support for authentication, retry logic, batch sending capabilities,
+* and idempotency for reliable delivery.
+*
+* @example
+* ```typescript
+* import { ResendTransport } from '@upyo/resend';
+*
+* const transport = new ResendTransport({
+*   apiKey: 'your-resend-api-key',
+*   timeout: 30000,
+*   retries: 3
+* });
+*
+* 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(', '));
+* }
+* ```
+*/
+var ResendTransport = class {
+	/**
+	* The resolved Resend configuration used by this transport.
+	*/
+	config;
+	httpClient;
+	/**
+	* Creates a new Resend transport instance.
+	*
+	* @param config Resend configuration including API key and options.
+	*/
+	constructor(config) {
+		this.config = createResendConfig(config);
+		this.httpClient = new ResendHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message via Resend API.
+	*
+	* This method converts the message to Resend format, makes an HTTP request
+	* to the Resend API with automatic idempotency key generation, and returns
+	* a receipt with the result.
+	*
+	* @example
+	* ```typescript
+	* const receipt = await transport.send({
+	*   sender: { address: 'from@example.com' },
+	*   recipients: [{ address: 'to@example.com' }],
+	*   ccRecipients: [],
+	*   bccRecipients: [],
+	*   replyRecipients: [],
+	*   subject: 'Hello',
+	*   content: { text: 'Hello World!' },
+	*   attachments: [],
+	*   priority: 'normal',
+	*   tags: [],
+	*   headers: new Headers()
+	* });
+	*
+	* if (receipt.successful) {
+	*   console.log('Message sent with ID:', receipt.messageId);
+	* }
+	* ```
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options including `AbortSignal` for
+	*                cancellation.
+	* @returns A promise that resolves to a receipt indicating success or
+	*          failure.
+	*/
+	async send(message, options) {
+		try {
+			options?.signal?.throwIfAborted();
+			const idempotencyKey = generateIdempotencyKey();
+			const emailData = await convertMessage(message, this.config, { idempotencyKey });
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendMessage(emailData, options?.signal);
+			return {
+				successful: true,
+				messageId: response.id
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			return {
+				successful: false,
+				errorMessages: [errorMessage]
+			};
+		}
+	}
+	/**
+	* Sends multiple email messages efficiently via Resend API.
+	*
+	* This method intelligently chooses between single requests and batch API
+	* based on message count and features used. For optimal performance:
+	* - Uses batch API for ≤100 messages without attachments or tags
+	* - Falls back to individual requests for messages with unsupported features
+	* - Chunks large batches (>100) into multiple batch requests
+	*
+	* @example
+	* ```typescript
+	* const messages = [
+	*   {
+	*     sender: { address: 'from@example.com' },
+	*     recipients: [{ address: 'user1@example.com' }],
+	*     ccRecipients: [],
+	*     bccRecipients: [],
+	*     replyRecipients: [],
+	*     subject: 'Message 1',
+	*     content: { text: 'Hello User 1!' },
+	*     attachments: [],
+	*     priority: 'normal',
+	*     tags: [],
+	*     headers: new Headers()
+	*   },
+	*   {
+	*     sender: { address: 'from@example.com' },
+	*     recipients: [{ address: 'user2@example.com' }],
+	*     ccRecipients: [],
+	*     bccRecipients: [],
+	*     replyRecipients: [],
+	*     subject: 'Message 2',
+	*     content: { text: 'Hello User 2!' },
+	*     attachments: [],
+	*     priority: 'normal',
+	*     tags: [],
+	*     headers: new Headers()
+	*   }
+	* ];
+	*
+	* 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 including `AbortSignal` for
+	*                cancellation.
+	* @returns An async iterable of receipts, one for each message.
+	*/
+	async *sendMany(messages, options) {
+		options?.signal?.throwIfAborted();
+		const isAsyncIterable = Symbol.asyncIterator in messages;
+		const messageArray = [];
+		if (isAsyncIterable) for await (const message of messages) {
+			options?.signal?.throwIfAborted();
+			messageArray.push(message);
+		}
+		else for (const message of messages) {
+			options?.signal?.throwIfAborted();
+			messageArray.push(message);
+		}
+		yield* this.sendManyOptimized(messageArray, options);
+	}
+	/**
+	* Optimized batch sending that chooses the best strategy based on message features.
+	*
+	* @param messages Array of messages to send
+	* @param options Transport options
+	* @returns Async iterable of receipts
+	*/
+	async *sendManyOptimized(messages, options) {
+		if (messages.length === 0) return;
+		const canUseBatch = this.canUseBatchApi(messages);
+		if (canUseBatch && messages.length <= 100) yield* this.sendBatch(messages, options);
+		else if (canUseBatch && messages.length > 100) {
+			const chunks = this.chunkArray(messages, 100);
+			for (const chunk of chunks) {
+				options?.signal?.throwIfAborted();
+				yield* this.sendBatch(chunk, options);
+			}
+		} else for (const message of messages) {
+			options?.signal?.throwIfAborted();
+			yield await this.send(message, options);
+		}
+	}
+	/**
+	* Sends a batch of messages using Resend's batch API.
+	*
+	* @param messages Array of messages (≤100)
+	* @param options Transport options
+	* @returns Async iterable of receipts
+	*/
+	async *sendBatch(messages, options) {
+		options?.signal?.throwIfAborted();
+		try {
+			const idempotencyKey = generateIdempotencyKey();
+			const batchData = await convertMessagesBatch(messages, this.config, { idempotencyKey });
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendBatch(batchData, options?.signal);
+			for (const result of response.data) yield {
+				successful: true,
+				messageId: result.id
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			for (let i = 0; i < messages.length; i++) yield {
+				successful: false,
+				errorMessages: [errorMessage]
+			};
+		}
+	}
+	/**
+	* Checks if messages can use Resend's batch API.
+	*
+	* Batch API limitations:
+	* - No attachments
+	* - No tags
+	* - No scheduled sending
+	*
+	* @param messages Array of messages to check
+	* @returns True if all messages are suitable for batch API
+	*/
+	canUseBatchApi(messages) {
+		return messages.every((message) => message.attachments.length === 0 && message.tags.length === 0);
+	}
+	/**
+	* Splits an array into chunks of specified size.
+	*
+	* @param array Array to chunk
+	* @param size Chunk size
+	* @returns Array of chunks
+	*/
+	chunkArray(array, size) {
+		const chunks = [];
+		for (let i = 0; i < array.length; i += size) chunks.push(array.slice(i, i + size));
+		return chunks;
+	}
+};
+
+//#endregion
+export { ResendTransport };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@upyo/resend",
+  "version": "0.3.0-dev.33+fd596d86",
+  "description": "Resend transport for Upyo email library",
+  "keywords": [
+    "email",
+    "mail",
+    "sendmail",
+    "resend"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/transports/resend",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/resend/"
+  },
+  "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.3.0-dev.33+fd596d86"
+  },
+  "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"
+  }
+}