@upyo/lettermint 0.5.0-dev.0

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,105 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/lettermint
+================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+[Lettermint] transport for the [Upyo] email library.
+
+[JSR badge]: https://jsr.io/badges/@upyo/lettermint
+[JSR]: https://jsr.io/@upyo/lettermint
+[npm badge]: https://img.shields.io/npm/v/@upyo/lettermint?logo=npm
+[npm]: https://www.npmjs.com/package/@upyo/lettermint
+[Lettermint]: https://lettermint.co/
+[Upyo]: https://upyo.org/
+
+
+Features
+--------
+
+ -  Single and batch email sending via Lettermint's HTTP API
+ -  Idempotency key support through `Message.idempotencyKey`
+ -  Cross-runtime compatibility (Node.js, Deno, Bun, edge functions)
+ -  Rich content support: HTML emails, attachments, inline images, and custom
+    headers
+ -  Lettermint route, tag, metadata, and tracking settings
+ -  Retry logic with exponential backoff
+ -  Type-safe configuration with sensible defaults
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/lettermint
+pnpm add       @upyo/core @upyo/lettermint
+yarn add       @upyo/core @upyo/lettermint
+deno add --jsr @upyo/core @upyo/lettermint
+bun  add       @upyo/core @upyo/lettermint
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { LettermintTransport } from "@upyo/lettermint";
+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." },
+  idempotencyKey: "welcome-recipient-example-net",
+});
+
+const transport = new LettermintTransport({
+  apiToken: process.env.LETTERMINT_API_TOKEN!,
+});
+
+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 [Lettermint docs] for more information about configuration options.
+
+[Lettermint docs]: https://docs.lettermint.co/
+
+### Available options
+
+ -  `apiToken`: Your Lettermint project sending API token
+ -  `baseUrl`: Lettermint API base URL (default:
+    `https://api.lettermint.co`)
+ -  `timeout`: Request timeout in milliseconds (default: `30000`)
+ -  `retries`: Number of retry attempts (default: `3`)
+ -  `headers`: Additional HTTP headers
+ -  `route`: Lettermint route for sent messages
+ -  `tag`: Default Lettermint tag when a message has no `Message.tags`
+ -  `metadata`: Metadata to track with sent messages
+ -  `settings`: Lettermint tracking settings (`trackOpens`, `trackClicks`)

package/dist/index.cjs

@@ -0,0 +1,496 @@
+
+//#region src/config.ts
+/**
+* Creates a resolved Lettermint configuration by applying default values.
+*
+* @param config The Lettermint configuration with optional fields.
+* @returns A resolved configuration with all defaults applied.
+* @since 0.5.0
+*/
+function createLettermintConfig(config) {
+	return {
+		apiToken: config.apiToken,
+		baseUrl: config.baseUrl ?? "https://api.lettermint.co",
+		timeout: config.timeout ?? 3e4,
+		retries: config.retries ?? 3,
+		headers: config.headers ?? {},
+		route: config.route,
+		tag: config.tag,
+		metadata: config.metadata == null ? void 0 : { ...config.metadata },
+		settings: config.settings == null ? void 0 : { ...config.settings }
+	};
+}
+
+//#endregion
+//#region src/http-client.ts
+/**
+* Lettermint API error class for API-specific failures.
+*
+* @since 0.5.0
+*/
+var LettermintApiError = class extends Error {
+	statusCode;
+	/**
+	* Creates a Lettermint API error.
+	*
+	* @param message Error message.
+	* @param statusCode HTTP status code.
+	*/
+	constructor(message, statusCode) {
+		super(message);
+		this.name = "LettermintApiError";
+		this.statusCode = statusCode;
+	}
+};
+/**
+* Lettermint request timeout error.
+*
+* @since 0.5.0
+*/
+var LettermintTimeoutError = class extends Error {
+	timeout;
+	/**
+	* Creates a Lettermint request timeout error.
+	*
+	* @param timeout Request timeout in milliseconds.
+	*/
+	constructor(timeout) {
+		super(`Lettermint API request timed out after ${timeout} ms.`);
+		this.name = "LettermintTimeoutError";
+		this.timeout = timeout;
+	}
+};
+/**
+* HTTP client wrapper for Lettermint API requests.
+*
+* @since 0.5.0
+*/
+var LettermintHttpClient = class {
+	config;
+	/**
+	* Creates a new Lettermint HTTP client.
+	*
+	* @param config Resolved Lettermint configuration.
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Sends a single message via Lettermint API.
+	*
+	* @param messageData The JSON data to send to Lettermint.
+	* @param signal Optional AbortSignal for cancellation.
+	* @param idempotencyKey Optional idempotency key for request deduplication.
+	* @returns Promise that resolves to the Lettermint response.
+	*/
+	sendMessage(messageData, signal, idempotencyKey) {
+		const url = `${this.config.baseUrl}/v1/send`;
+		return this.makeRequest(url, messageData, signal, idempotencyKey);
+	}
+	/**
+	* Sends multiple messages via Lettermint batch API.
+	*
+	* @param messagesData The messages to send to Lettermint.
+	* @param signal Optional AbortSignal for cancellation.
+	* @param idempotencyKey Optional idempotency key for request deduplication.
+	* @returns Promise that resolves to the Lettermint batch response.
+	*/
+	sendBatch(messagesData, signal, idempotencyKey) {
+		const url = `${this.config.baseUrl}/v1/send/batch`;
+		return this.makeRequest(url, messagesData, signal, idempotencyKey);
+	}
+	async makeRequest(url, body, signal, idempotencyKey) {
+		let lastError = null;
+		for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+			signal?.throwIfAborted();
+			try {
+				const response = await this.fetchWithAuth(url, body, signal, idempotencyKey);
+				const text = await response.text();
+				if (!response.ok) throw new LettermintApiError(parseErrorMessage(text, response.status), response.status);
+				try {
+					return JSON.parse(text);
+				} catch (error) {
+					throw new SyntaxError(`Invalid JSON response from Lettermint API: ${error instanceof Error ? error.message : String(error)}.`);
+				}
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+				if (error instanceof LettermintApiError && !isRetryable(error)) throw error;
+				if (error instanceof Error && error.name === "AbortError" && signal?.aborted) throw error;
+				if (attempt === this.config.retries) throw lastError;
+				await sleep(calculateRetryDelay(attempt), signal);
+			}
+		}
+		throw lastError ?? /* @__PURE__ */ new Error("Request failed after all retry attempts.");
+	}
+	async fetchWithAuth(url, body, signal, idempotencyKey) {
+		const headers = new Headers({
+			"Content-Type": "application/json",
+			"x-lettermint-token": this.config.apiToken
+		});
+		if (idempotencyKey) headers.set("Idempotency-Key", idempotencyKey);
+		for (const [key, value] of Object.entries(this.config.headers)) headers.set(key, value);
+		const timeoutController = new AbortController();
+		const timeoutId = this.config.timeout > 0 ? setTimeout(() => timeoutController.abort(), this.config.timeout) : void 0;
+		const requestSignal = combineSignals(timeoutController.signal, signal);
+		try {
+			return await globalThis.fetch(url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(body),
+				signal: requestSignal.signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError" && timeoutController.signal.aborted && !signal?.aborted) throw new LettermintTimeoutError(this.config.timeout);
+			throw error;
+		} finally {
+			requestSignal.cleanup();
+			if (timeoutId !== void 0) clearTimeout(timeoutId);
+		}
+	}
+};
+function isRetryable(error) {
+	return error.statusCode === 408 || error.statusCode === 429 || error.statusCode >= 500;
+}
+function calculateRetryDelay(attempt) {
+	const baseDelay = Math.min(1e3 * Math.pow(2, attempt), 1e4);
+	return Math.round(baseDelay / 2 + Math.random() * (baseDelay / 2));
+}
+function parseErrorMessage(text, statusCode) {
+	try {
+		const errorBody = JSON.parse(text);
+		if (typeof errorBody.message === "string" && errorBody.message !== "") return errorBody.message;
+		if (typeof errorBody.error === "string" && errorBody.error !== "") return errorBody.error;
+		if (Array.isArray(errorBody.errors) && errorBody.errors.length > 0) return JSON.stringify(errorBody.errors);
+	} catch {}
+	return text || `HTTP ${statusCode}`;
+}
+function combineSignals(timeoutSignal, externalSignal) {
+	if (externalSignal == null) return {
+		signal: timeoutSignal,
+		cleanup: () => {}
+	};
+	if (typeof AbortSignal.any === "function") return {
+		signal: AbortSignal.any([timeoutSignal, externalSignal]),
+		cleanup: () => {}
+	};
+	const controller = new AbortController();
+	const abort = () => controller.abort();
+	timeoutSignal.addEventListener("abort", abort, { once: true });
+	externalSignal.addEventListener("abort", abort, { once: true });
+	if (timeoutSignal.aborted || externalSignal.aborted) controller.abort();
+	return {
+		signal: controller.signal,
+		cleanup: () => {
+			timeoutSignal.removeEventListener("abort", abort);
+			externalSignal.removeEventListener("abort", abort);
+		}
+	};
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DOMException("The operation was aborted.", "AbortError"));
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timeoutId);
+			signal?.removeEventListener("abort", onAbort);
+			reject(new DOMException("The operation was aborted.", "AbortError"));
+		};
+		const timeoutId = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		if (signal?.aborted) {
+			onAbort();
+			return;
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+//#endregion
+//#region src/message-converter.ts
+const STANDARD_HEADERS = new Set([
+	"from",
+	"to",
+	"cc",
+	"bcc",
+	"reply-to",
+	"subject",
+	"date",
+	"message-id",
+	"content-type",
+	"content-transfer-encoding",
+	"mime-version",
+	"x-priority"
+]);
+/**
+* Converts an Upyo message to Lettermint API JSON format.
+*
+* @param message The Upyo message to convert.
+* @param config The resolved Lettermint configuration.
+* @returns JSON object ready for Lettermint API submission.
+* @throws {RangeError} If the message has more than one tag.
+* @since 0.5.0
+*/
+async function convertMessage(message, config) {
+	if (message.tags.length > 1) throw new RangeError("Lettermint supports at most one tag per message.");
+	const emailData = {
+		from: formatAddress(message.sender),
+		to: 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 = message.replyRecipients.map(formatAddress);
+	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 (config.route) emailData.route = config.route;
+	if (message.tags.length === 1) emailData.tag = message.tags[0];
+	else if (config.tag !== void 0) emailData.tag = config.tag;
+	if (config.metadata != null && Object.keys(config.metadata).length > 0) emailData.metadata = { ...config.metadata };
+	const settings = convertSettings(config);
+	if (settings != null) emailData.settings = settings;
+	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 (Object.keys(headers).length > 0) emailData.headers = headers;
+	if (message.attachments.length > 0) emailData.attachments = await Promise.all(message.attachments.map(convertAttachment));
+	return emailData;
+}
+function convertSettings(config) {
+	if (config.settings == null) return void 0;
+	const settings = {};
+	if (config.settings.trackOpens !== void 0) settings.track_opens = config.settings.trackOpens;
+	if (config.settings.trackClicks !== void 0) settings.track_clicks = config.settings.trackClicks;
+	return Object.keys(settings).length > 0 ? settings : void 0;
+}
+function formatAddress(address) {
+	if (address.name) {
+		const escapedName = address.name.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+		return `"${escapedName}" <${address.address}>`;
+	}
+	return address.address;
+}
+async function convertAttachment(attachment) {
+	const content = await attachment.content;
+	const converted = {
+		filename: attachment.filename,
+		content: uint8ArrayToBase64(content),
+		content_type: attachment.contentType
+	};
+	if (attachment.inline && attachment.contentId) converted.content_id = attachment.contentId;
+	return converted;
+}
+function uint8ArrayToBase64(bytes) {
+	const chunkSize = 32768;
+	const chunks = [];
+	for (let offset = 0; offset < bytes.length; offset += chunkSize) chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + chunkSize)));
+	return btoa(chunks.join(""));
+}
+function isStandardHeader(headerName) {
+	return STANDARD_HEADERS.has(headerName.toLowerCase());
+}
+/**
+* Generates a random idempotency key for request deduplication.
+*
+* @returns A unique string suitable for use as an idempotency key.
+* @since 0.5.0
+*/
+function generateIdempotencyKey() {
+	return globalThis.crypto.randomUUID();
+}
+
+//#endregion
+//#region src/lettermint-transport.ts
+const MAX_BATCH_SIZE = 500;
+/**
+* Lettermint transport implementation for sending emails via Lettermint API.
+*
+* @example
+* ```typescript
+* import { createMessage } from "@upyo/core";
+* import { LettermintTransport } from "@upyo/lettermint";
+*
+* const transport = new LettermintTransport({
+*   apiToken: "your-project-api-token",
+* });
+*
+* const receipt = await transport.send(createMessage({
+*   from: "sender@example.com",
+*   to: "recipient@example.com",
+*   subject: "Hello from Lettermint",
+*   content: { text: "Hello!" },
+* }));
+* ```
+*
+* @since 0.5.0
+*/
+var LettermintTransport = class {
+	/**
+	* The resolved Lettermint configuration used by this transport.
+	*/
+	config;
+	httpClient;
+	/**
+	* Creates a new Lettermint transport instance.
+	*
+	* @param config Lettermint configuration including API token and options.
+	*/
+	constructor(config) {
+		this.config = createLettermintConfig(config);
+		this.httpClient = new LettermintHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message via Lettermint API.
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options including `AbortSignal`.
+	* @returns A receipt indicating success or failure.
+	*/
+	async send(message, options) {
+		try {
+			options?.signal?.throwIfAborted();
+			const emailData = await convertMessage(message, this.config);
+			const idempotencyKey = normalizeIdempotencyKey(message.idempotencyKey);
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendMessage(emailData, options?.signal, idempotencyKey);
+			return responseToReceipt(response);
+		} catch (error) {
+			if (isAbortError(error)) throw error;
+			return {
+				successful: false,
+				errorMessages: [error instanceof Error ? error.message : String(error)]
+			};
+		}
+	}
+	/**
+	* Sends multiple email messages via Lettermint batch API.
+	*
+	* Messages are chunked into Lettermint's maximum batch size of 500 messages.
+	*
+	* @param messages An iterable or async iterable of messages to send.
+	* @param options Optional transport options including `AbortSignal`.
+	* @returns An async iterable of receipts, one for each message.
+	*/
+	async *sendMany(messages, options) {
+		options?.signal?.throwIfAborted();
+		let chunk = [];
+		for await (const message of messages) {
+			options?.signal?.throwIfAborted();
+			chunk.push(message);
+			if (chunk.length === MAX_BATCH_SIZE) {
+				yield* this.sendBatch(chunk, options);
+				chunk = [];
+			}
+		}
+		yield* this.sendBatch(chunk, options);
+	}
+	async *sendBatch(messages, options) {
+		if (messages.length === 0) return;
+		if (messages.some(hasIdempotencyKey)) {
+			for (const message of messages) yield await this.send(message, options);
+			return;
+		}
+		const idempotencyKey = normalizeIdempotencyKey(messages[0]?.idempotencyKey);
+		const batchData = [];
+		const receipts = [];
+		for (const message of messages) try {
+			batchData.push(await convertMessage(message, this.config));
+			receipts.push(void 0);
+		} catch (error) {
+			receipts.push({
+				successful: false,
+				errorMessages: [error instanceof Error ? error.message : String(error)]
+			});
+		}
+		if (batchData.length === 0) {
+			for (const receipt of receipts) if (receipt !== void 0) yield receipt;
+			return;
+		}
+		try {
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendBatch(batchData, options?.signal, idempotencyKey);
+			let responseIndex = 0;
+			for (let index = 0; index < receipts.length; index++) {
+				const receipt = receipts[index];
+				if (receipt !== void 0) {
+					yield receipt;
+					continue;
+				}
+				const result = response[responseIndex++];
+				yield responseToReceipt(result);
+			}
+		} catch (error) {
+			if (isAbortError(error)) throw error;
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			for (const receipt of receipts) {
+				if (receipt !== void 0) {
+					yield receipt;
+					continue;
+				}
+				yield {
+					successful: false,
+					errorMessages: [errorMessage]
+				};
+			}
+		}
+	}
+};
+function normalizeIdempotencyKey(idempotencyKey) {
+	return idempotencyKey != null && idempotencyKey !== "" ? idempotencyKey : generateIdempotencyKey();
+}
+function hasIdempotencyKey(message) {
+	return message.idempotencyKey != null && message.idempotencyKey !== "";
+}
+function responseToReceipt(response) {
+	if (response?.message_id == null || response.message_id === "") return {
+		successful: false,
+		errorMessages: ["Lettermint response is missing a message ID."]
+	};
+	if (isSuccessfulStatus(response.status)) return {
+		successful: true,
+		messageId: response.message_id
+	};
+	return {
+		successful: false,
+		errorMessages: [`Lettermint reported message status "${response.status}".`]
+	};
+}
+function isSuccessfulStatus(status) {
+	switch (status) {
+		case "pending":
+		case "queued":
+		case "processed":
+		case "delivered":
+		case "opened":
+		case "clicked": return true;
+		case "suppressed":
+		case "soft_bounced":
+		case "hard_bounced":
+		case "spam_complaint":
+		case "failed":
+		case "blocked":
+		case "policy_rejected":
+		case "unsubscribed": return false;
+	}
+}
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
+
+//#endregion
+exports.LettermintApiError = LettermintApiError;
+exports.LettermintTimeoutError = LettermintTimeoutError;
+exports.LettermintTransport = LettermintTransport;
+exports.createLettermintConfig = createLettermintConfig;