@upyo/lettermint 0.5.0-dev.0

package/dist/index.js

@@ -0,0 +1,492 @@
+//#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
+export { LettermintApiError, LettermintTimeoutError, LettermintTransport, createLettermintConfig };

package/package.json

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