@upyo/resend 0.3.0-dev.33

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025 Hong Minhee
+
+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,102 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/resend
+============
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+[Resend] transport for the [Upyo] email library.
+
+[JSR]: https://jsr.io/@upyo/resend
+[JSR badge]: https://jsr.io/badges/@upyo/resend
+[npm]: https://www.npmjs.com/package/@upyo/resend
+[npm badge]: https://img.shields.io/npm/v/@upyo/resend?logo=npm
+[Resend]: https://resend.com/
+[Upyo]: https://upyo.org/
+
+
+Features
+--------
+
+ -  Single and batch email sending via Resend's HTTP API
+ -  Automatic idempotency for reliable delivery
+ -  Smart batch optimization: uses batch API when possible
+ -  Cross-runtime compatibility (Node.js, Deno, Bun, edge functions)
+ -  Rich content support: HTML emails, attachments, custom headers
+ -  Retry logic with exponential backoff
+ -  Type-safe configuration with sensible defaults
+ -  Comprehensive error handling
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/resend
+pnpm add       @upyo/core @upyo/resend
+yarn add       @upyo/core @upyo/resend
+deno add --jsr @upyo/core @upyo/resend
+bun  add       @upyo/core @upyo/resend
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { ResendTransport } from "@upyo/resend";
+import process from "node:process";
+
+const message = createMessage({
+  from: "sender@example.com",
+  to: "recipient@example.net",
+  subject: "Hello from Upyo!",
+  content: { text: "This is a test email." },
+});
+
+const transport = new ResendTransport({
+  apiKey: process.env.RESEND_API_KEY!,
+});
+
+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(", "));
+}
+~~~~
+
+### Sending Multiple Emails
+
+~~~~ typescript
+const messages = [message1, message2, message3];
+
+for await (const receipt of transport.sendMany(messages)) {
+  if (receipt.successful) {
+    console.log(`Email sent with ID: ${receipt.messageId}`);
+  } else {
+    console.error(`Email failed: ${receipt.errorMessages.join(", ")}`);
+  }
+}
+~~~~
+
+
+
+
+Configuration
+-------------
+
+See the [Resend docs] for more information about configuration options.
+
+[Resend docs]: https://resend.com/docs
+
+### Available Options
+
+ -  `apiKey`: Your Resend API key
+ -  `baseUrl`: Resend API base URL (default: `https://api.resend.com`)
+ -  `timeout`: Request timeout in milliseconds (default: `30000`)
+ -  `retries`: Number of retry attempts (default: `3`)
+ -  `validateSsl`: Whether to validate SSL certificates (default: `true`)
+ -  `headers`: Additional HTTP headers

package/dist/index.cjs

@@ -0,0 +1,553 @@
+
+//#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
+exports.ResendTransport = ResendTransport;