@upyo/maileroo 0.6.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,102 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/maileroo
+==============
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+[Maileroo] transport for the [Upyo] email library.
+
+[JSR badge]: https://jsr.io/badges/@upyo/maileroo
+[JSR]: https://jsr.io/@upyo/maileroo
+[npm badge]: https://img.shields.io/npm/v/@upyo/maileroo?logo=npm
+[npm]: https://www.npmjs.com/package/@upyo/maileroo
+[Maileroo]: https://maileroo.com/
+[Upyo]: https://upyo.org/
+
+
+Features
+--------
+
+ -  Single email sending via Maileroo's JSON Email API
+ -  Sequential `sendMany()` support through Upyo's transport interface
+ -  Cross-runtime compatibility (Node.js, Deno, Bun, edge functions)
+ -  Rich content support: HTML emails, attachments, inline images, and custom
+    headers
+ -  Maileroo tags and tracking settings
+ -  Retry logic with exponential backoff
+ -  Type-safe configuration with sensible defaults
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/maileroo
+pnpm add       @upyo/core @upyo/maileroo
+yarn add       @upyo/core @upyo/maileroo
+deno add --jsr @upyo/core @upyo/maileroo
+bun  add       @upyo/core @upyo/maileroo
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { MailerooTransport } from "@upyo/maileroo";
+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 MailerooTransport({
+  apiKey: process.env.MAILEROO_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 [Maileroo docs] for more information about configuration options.
+
+[Maileroo docs]: https://maileroo.com/docs/email-api/introduction/
+
+### Available options
+
+ -  `apiKey`: Your Maileroo sending key
+ -  `baseUrl`: Maileroo Email API base URL (default:
+    `https://smtp.maileroo.com/api/v2`)
+ -  `timeout`: Request timeout in milliseconds (default: `30000`)
+ -  `retries`: Number of retry attempts (default: `3`)
+ -  `headers`: Additional HTTP request headers
+ -  `tracking`: Whether to enable Maileroo open and click tracking
+ -  `tags`: Default Maileroo tags for sent messages

package/dist/index.cjs

@@ -0,0 +1,462 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __upyo_core = __toESM(require("@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, (0, __upyo_core.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 = (0, __upyo_core.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 (0, __upyo_core.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 (0, __upyo_core.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 (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "maileroo",
+		statusCode: error.statusCode,
+		retryAfterMilliseconds: error.retryAfterMilliseconds,
+		attempts: error.attempts
+	});
+	if (error instanceof MailerooTimeoutError) return (0, __upyo_core.createFailedReceipt)(message, {
+		provider: "maileroo",
+		category: "timeout",
+		code: "timeout",
+		retryable: true,
+		attempts: error.attempts
+	});
+	return (0, __upyo_core.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
+exports.MailerooApiError = MailerooApiError;
+exports.MailerooTimeoutError = MailerooTimeoutError;
+exports.MailerooTransport = MailerooTransport;
+exports.createMailerooConfig = createMailerooConfig;