@upyo/maileroo 0.6.0-dev.0

package/dist/index.js

@@ -0,0 +1,436 @@
+import { combineSignals, createFailedReceipt, parseRetryAfter } from "@upyo/core";
+
+//#region src/config.ts
+/**
+* Creates a resolved Maileroo configuration by applying default values.
+*
+* @param config The Maileroo configuration with optional fields.
+* @returns A resolved configuration with all defaults applied.
+* @since 0.6.0
+*/
+function createMailerooConfig(config) {
+	return {
+		apiKey: config.apiKey,
+		baseUrl: normalizeBaseUrl(config.baseUrl ?? "https://smtp.maileroo.com/api/v2"),
+		timeout: config.timeout ?? 3e4,
+		retries: config.retries ?? 3,
+		headers: config.headers ?? {},
+		tracking: config.tracking,
+		tags: config.tags == null ? void 0 : { ...config.tags }
+	};
+}
+function normalizeBaseUrl(baseUrl) {
+	return baseUrl.replace(/\/+$/, "");
+}
+
+//#endregion
+//#region src/http-client.ts
+/**
+* Maileroo API error class for API-specific failures.
+*
+* @since 0.6.0
+*/
+var MailerooApiError = class extends Error {
+	statusCode;
+	retryAfterMilliseconds;
+	attempts;
+	/**
+	* Creates a Maileroo API error.
+	*
+	* @param message Error message.
+	* @param statusCode HTTP status code.
+	* @param retryAfterMilliseconds Retry delay from the response.
+	* @param attempts Number of attempts made before this error.
+	*/
+	constructor(message, statusCode, retryAfterMilliseconds, attempts) {
+		super(message);
+		this.name = "MailerooApiError";
+		this.statusCode = statusCode;
+		this.retryAfterMilliseconds = retryAfterMilliseconds;
+		this.attempts = attempts;
+	}
+};
+/**
+* Maileroo request timeout error.
+*
+* @since 0.6.0
+*/
+var MailerooTimeoutError = class extends Error {
+	/**
+	* Request timeout in milliseconds.
+	*
+	* @since 0.6.0
+	*/
+	timeout;
+	/**
+	* Number of attempts made before this error was produced.
+	*
+	* @since 0.6.0
+	*/
+	attempts;
+	/**
+	* Creates a Maileroo request timeout error.
+	*
+	* @param timeout Request timeout in milliseconds.
+	* @param attempts Number of attempts made before this error.
+	*/
+	constructor(timeout, attempts) {
+		super(`Maileroo API request timed out after ${timeout} ms.`);
+		this.name = "MailerooTimeoutError";
+		this.timeout = timeout;
+		this.attempts = attempts;
+	}
+};
+/**
+* HTTP client wrapper for Maileroo API requests.
+*
+* @since 0.6.0
+*/
+var MailerooHttpClient = class {
+	config;
+	/**
+	* Creates a new Maileroo HTTP client.
+	*
+	* @param config Resolved Maileroo configuration.
+	*/
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Sends a single message via Maileroo API.
+	*
+	* @param messageData The JSON data to send to Maileroo.
+	* @param signal Optional AbortSignal for cancellation.
+	* @returns Promise that resolves to the Maileroo response.
+	*/
+	sendMessage(messageData, signal) {
+		const url = `${this.config.baseUrl}/emails`;
+		return this.makeRequest(url, messageData, signal);
+	}
+	async makeRequest(url, body, signal) {
+		let lastError = null;
+		for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+			signal?.throwIfAborted();
+			try {
+				const response = await this.fetchWithAuth(url, body, signal);
+				const text = await response.text();
+				if (!response.ok) throw new MailerooApiError(parseErrorMessage(text, response.status), response.status, parseRetryAfter(response.headers.get("Retry-After")), attempt + 1);
+				try {
+					return JSON.parse(text);
+				} catch (error) {
+					throw new SyntaxError(`Invalid JSON response from Maileroo API: ${error instanceof Error ? error.message : String(error)}.`);
+				}
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+				if (error instanceof MailerooApiError && !isRetryable(error)) throw error;
+				if (error instanceof Error && error.name === "AbortError" && signal?.aborted) throw error;
+				if (attempt === this.config.retries) throw withAttempts(lastError, attempt + 1);
+				await sleep(calculateRetryDelay(attempt), signal);
+			}
+		}
+		throw lastError ?? /* @__PURE__ */ new Error("Request failed after all retry attempts.");
+	}
+	async fetchWithAuth(url, body, signal) {
+		const headers = new Headers({
+			"Content-Type": "application/json",
+			"X-API-Key": this.config.apiKey
+		});
+		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 MailerooTimeoutError(this.config.timeout);
+			throw error;
+		} finally {
+			requestSignal.cleanup();
+			if (timeoutId !== void 0) clearTimeout(timeoutId);
+		}
+	}
+};
+function withAttempts(error, attempts) {
+	if (error instanceof MailerooTimeoutError) return new MailerooTimeoutError(error.timeout, attempts);
+	if (error instanceof MailerooApiError) return error;
+	return Object.assign(error, { attempts });
+}
+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 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 Maileroo API JSON format.
+*
+* @param message The Upyo message to convert.
+* @param config The resolved Maileroo configuration.
+* @returns JSON object ready for Maileroo API submission.
+* @since 0.6.0
+*/
+async function convertMessage(message, config) {
+	const emailData = {
+		from: convertAddress(message.sender),
+		to: convertAddressList(message.recipients),
+		subject: message.subject
+	};
+	const cc = convertOptionalAddressList(message.ccRecipients);
+	if (cc !== void 0) emailData.cc = cc;
+	const bcc = convertOptionalAddressList(message.bccRecipients);
+	if (bcc !== void 0) emailData.bcc = bcc;
+	const replyTo = convertOptionalAddressList(message.replyRecipients);
+	if (replyTo !== void 0) emailData.reply_to = replyTo;
+	if ("html" in message.content) {
+		emailData.html = message.content.html;
+		if (message.content.text !== void 0) emailData.plain = message.content.text;
+	} else emailData.plain = message.content.text;
+	if (config.tracking !== void 0) emailData.tracking = config.tracking;
+	const tags = convertTags(message, config);
+	if (Object.keys(tags).length > 0) emailData.tags = tags;
+	const headers = convertHeaders(message);
+	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 convertAddress(address) {
+	return address.name == null || address.name === "" ? { address: address.address } : {
+		address: address.address,
+		display_name: address.name
+	};
+}
+function convertAddressList(addresses) {
+	const converted = addresses.map(convertAddress);
+	return converted.length === 1 ? converted[0] : converted;
+}
+function convertOptionalAddressList(addresses) {
+	return addresses.length === 0 ? void 0 : convertAddressList(addresses);
+}
+function convertTags(message, config) {
+	const tags = config.tags == null ? {} : { ...config.tags };
+	for (const [index, tag] of message.tags.entries()) tags[`tag${index + 1}`] = tag;
+	return tags;
+}
+function convertHeaders(message) {
+	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;
+	return headers;
+}
+async function convertAttachment(attachment) {
+	const content = await attachment.content;
+	return {
+		file_name: attachment.filename,
+		content_type: attachment.contentType,
+		content: uint8ArrayToBase64(content),
+		inline: attachment.inline || void 0
+	};
+}
+function uint8ArrayToBase64(bytes) {
+	const nativeToBase64 = getNativeToBase64(bytes);
+	if (nativeToBase64 != null) return nativeToBase64();
+	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 getNativeToBase64(bytes) {
+	const candidate = bytes;
+	const toBase64 = candidate.toBase64;
+	if (typeof toBase64 !== "function") return void 0;
+	return () => toBase64.call(bytes);
+}
+function isStandardHeader(headerName) {
+	return STANDARD_HEADERS.has(headerName.toLowerCase());
+}
+
+//#endregion
+//#region src/maileroo-transport.ts
+/**
+* Maileroo transport implementation for sending emails via Maileroo API.
+*
+* @example
+* ```typescript
+* import { createMessage } from "@upyo/core";
+* import { MailerooTransport } from "@upyo/maileroo";
+*
+* const transport = new MailerooTransport({
+*   apiKey: "your-sending-key",
+* });
+*
+* const receipt = await transport.send(createMessage({
+*   from: "sender@example.com",
+*   to: "recipient@example.com",
+*   subject: "Hello from Maileroo",
+*   content: { text: "Hello!" },
+* }));
+* ```
+*
+* @since 0.6.0
+*/
+var MailerooTransport = class {
+	id = "maileroo";
+	/**
+	* The resolved Maileroo configuration used by this transport.
+	*/
+	config;
+	httpClient;
+	/**
+	* Creates a new Maileroo transport instance.
+	*
+	* @param config Maileroo configuration including API key and options.
+	*/
+	constructor(config) {
+		this.config = createMailerooConfig(config);
+		this.httpClient = new MailerooHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message via Maileroo 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);
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendMessage(emailData, options?.signal);
+			return responseToReceipt(response);
+		} catch (error) {
+			if (isCallerAbort(error, options?.signal)) throw error;
+			return createMailerooFailure(error instanceof Error ? error.message : String(error), error);
+		}
+	}
+	/**
+	* Sends multiple email messages sequentially via Maileroo API.
+	*
+	* @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();
+		for await (const message of messages) {
+			options?.signal?.throwIfAborted();
+			yield await this.send(message, options);
+		}
+	}
+};
+function responseToReceipt(response) {
+	if (!response.success) return createFailedReceipt(response.message ?? "Maileroo reported an unsuccessful response.", {
+		provider: "maileroo",
+		category: "rejected",
+		code: "maileroo.unsuccessful",
+		retryable: false,
+		providerDetails: response
+	});
+	const messageId = response.data?.reference_id;
+	if (messageId == null || messageId === "") return createFailedReceipt("Maileroo response is missing a reference ID.", {
+		provider: "maileroo",
+		category: "unknown",
+		code: "maileroo.missing_reference_id",
+		retryable: false,
+		providerDetails: response
+	});
+	return {
+		successful: true,
+		messageId,
+		provider: "maileroo"
+	};
+}
+function createMailerooFailure(message, error) {
+	if (error instanceof MailerooApiError) return createFailedReceipt(message, {
+		provider: "maileroo",
+		statusCode: error.statusCode,
+		retryAfterMilliseconds: error.retryAfterMilliseconds,
+		attempts: error.attempts
+	});
+	if (error instanceof MailerooTimeoutError) return createFailedReceipt(message, {
+		provider: "maileroo",
+		category: "timeout",
+		code: "timeout",
+		retryable: true,
+		attempts: error.attempts
+	});
+	return createFailedReceipt(message, {
+		provider: "maileroo",
+		attempts: getErrorAttempts(error)
+	});
+}
+function getErrorAttempts(error) {
+	if (typeof error !== "object" || error == null || !("attempts" in error)) return void 0;
+	const attempts = error.attempts;
+	return typeof attempts === "number" ? attempts : void 0;
+}
+function isAbortError(error) {
+	return error instanceof Error && error.name === "AbortError";
+}
+function isCallerAbort(error, signal) {
+	return signal?.aborted === true && (isAbortError(error) || error === signal.reason);
+}
+
+//#endregion
+export { MailerooApiError, MailerooTimeoutError, MailerooTransport, createMailerooConfig };

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@upyo/maileroo",
+  "version": "0.6.0-dev.0",
+  "description": "Maileroo transport for Upyo email library",
+  "keywords": [
+    "email",
+    "mail",
+    "sendmail",
+    "maileroo"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/transports/maileroo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/maileroo/"
+  },
+  "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.6.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3"
+  },
+  "scripts": {
+    "prepublish": "mise run --no-deps :build"
+  }
+}