@upyo/mailgun 0.1.0-dev.10

package/README.md

@@ -0,0 +1,62 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/mailgun
+=============
+
+[Mailgun] transport for Upyo email library.
+
+[Mailgun]: https://www.mailgun.com/
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/mailgun
+pnpm add       @upyo/core @upyo/mailgun
+yarn add       @upyo/core @upyo/mailgun
+deno add --jsr @upyo/core @upyo/mailgun
+bun  add       @upyo/core @upyo/mailgun
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { MailgunTransport } from '@upyo/mailgun';
+
+const transport = new MailgunTransport({
+  apiKey: 'your-api-key',
+  domain: 'your-domain.com'
+});
+
+const message = {
+  sender: { address: 'sender@example.com' },
+  recipients: [{ address: 'recipient@example.com' }],
+  subject: 'Hello from Mailgun!',
+  content: { text: 'Hello, World!' }
+};
+
+const receipt = await transport.send(message);
+console.log('Message sent:', receipt.messageId);
+~~~~
+
+
+Configuration
+-------------
+
+See the [Mailgun docs] for more information about configuration options.
+
+[Mailgun docs]: https://documentation.mailgun.com/
+
+### Available Options
+
+ -  `apiKey`: Your Mailgun API key
+ -  `domain`: Your Mailgun domain
+ -  `region`: Mailgun region (`us` or `eu`, defaults to `us`)
+ -  `timeout`: Request timeout in milliseconds (default: 30000)
+ -  `retries`: Number of retry attempts (default: 3)
+ -  `tracking`: Enable tracking (default: true)
+ -  `clickTracking`: Enable click tracking (default: true)
+ -  `openTracking`: Enable open tracking (default: true)

package/dist/index.cjs

@@ -0,0 +1,403 @@
+
+//#region src/config.ts
+/**
+* Creates a resolved Mailgun configuration by applying default values to optional fields.
+*
+* This function takes a partial Mailgun configuration and returns a complete
+* configuration with all optional fields filled with sensible defaults.
+*
+* @param config - The Mailgun configuration with optional fields
+* @returns A resolved configuration with all defaults applied
+*
+* @example
+* ```typescript
+* const resolved = createMailgunConfig({
+*   apiKey: 'your-api-key',
+*   domain: 'your-domain.com'
+* });
+*
+* // resolved.region will be 'us' (default)
+* // resolved.timeout will be 30000 (default)
+* // resolved.retries will be 3 (default)
+* ```
+*/
+function createMailgunConfig(config) {
+	const region = config.region ?? "us";
+	const baseUrl = config.baseUrl ?? getDefaultBaseUrl(region);
+	return {
+		apiKey: config.apiKey,
+		domain: config.domain,
+		region,
+		baseUrl,
+		timeout: config.timeout ?? 3e4,
+		retries: config.retries ?? 3,
+		validateSsl: config.validateSsl ?? true,
+		headers: config.headers ?? {},
+		tracking: config.tracking ?? true,
+		clickTracking: config.clickTracking ?? true,
+		openTracking: config.openTracking ?? true
+	};
+}
+/**
+* Gets the default base URL for a given Mailgun region.
+*
+* @param region - The Mailgun region
+* @returns The default base URL for the region
+*/
+function getDefaultBaseUrl(region) {
+	switch (region) {
+		case "us": return "https://api.mailgun.net/v3";
+		case "eu": return "https://api.eu.mailgun.net/v3";
+		default: throw new Error(`Unsupported region: ${region}`);
+	}
+}
+
+//#endregion
+//#region src/http-client.ts
+/**
+* HTTP client wrapper for Mailgun API requests.
+*
+* This class handles authentication, request formatting, error handling,
+* and retry logic for Mailgun API calls.
+*/
+var MailgunHttpClient = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Sends a message via Mailgun API.
+	*
+	* @param formData The form data to send to Mailgun.
+	* @param signal Optional AbortSignal for cancellation.
+	* @returns Promise that resolves to the Mailgun response.
+	*/
+	sendMessage(formData, signal) {
+		const url = `${this.config.baseUrl}/${this.config.domain}/messages`;
+		return this.makeRequest(url, {
+			method: "POST",
+			body: formData,
+			signal
+		});
+	}
+	/**
+	* Makes an HTTP request to Mailgun 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();
+			let data;
+			try {
+				data = JSON.parse(text);
+			} catch {
+				throw new Error(text);
+			}
+			if (!response.ok) throw new MailgunApiError(data.message ?? `HTTP ${response.status}`, response.status);
+			return data;
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+			if (error instanceof MailgunApiError && error.statusCode && error.statusCode >= 400 && error.statusCode < 500) throw error;
+			if (attempt === this.config.retries) throw error;
+			const delay = Math.pow(2, attempt) * 1e3;
+			await new Promise((resolve) => setTimeout(resolve, delay));
+		}
+		throw lastError || /* @__PURE__ */ new Error("Request failed after all retries");
+	}
+	/**
+	* Makes a fetch request with Mailgun authentication.
+	*
+	* @param url The URL to make the request to.
+	* @param options Fetch options.
+	* @returns Promise that resolves to the fetch response.
+	*/
+	async fetchWithAuth(url, options) {
+		const headers = new Headers(options.headers);
+		const auth = btoa(`api:${this.config.apiKey}`);
+		headers.set("Authorization", `Basic ${auth}`);
+		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 = controller.signal;
+		if (options.signal) signal = AbortSignal.any([controller.signal, options.signal]);
+		try {
+			return await globalThis.fetch(url, {
+				...options,
+				headers,
+				signal
+			});
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+};
+/**
+* Custom error class for Mailgun API errors.
+*/
+var MailgunApiError = class extends Error {
+	statusCode;
+	constructor(message, statusCode) {
+		super(message);
+		this.name = "MailgunApiError";
+		this.statusCode = statusCode;
+	}
+};
+
+//#endregion
+//#region src/message-converter.ts
+/**
+* Converts a Upyo Message to Mailgun API FormData format.
+*
+* This function transforms the standardized Upyo message format into
+* the specific format expected by the Mailgun API.
+*
+* @param message - The Upyo message to convert
+* @param config - The resolved Mailgun configuration
+* @returns FormData object ready for Mailgun API submission
+*
+* @example
+* ```typescript
+* const formData = convertMessage(message, config);
+* const response = await fetch(url, { method: 'POST', body: formData });
+* ```
+*/
+function convertMessage(message, config) {
+	const formData = new FormData();
+	formData.append("from", formatAddress(message.sender));
+	for (const recipient of message.recipients) formData.append("to", formatAddress(recipient));
+	for (const ccRecipient of message.ccRecipients) formData.append("cc", formatAddress(ccRecipient));
+	for (const bccRecipient of message.bccRecipients) formData.append("bcc", formatAddress(bccRecipient));
+	if (message.replyRecipients.length > 0) {
+		const replyTo = message.replyRecipients.map(formatAddress).join(", ");
+		formData.append("h:Reply-To", replyTo);
+	}
+	formData.append("subject", message.subject);
+	if ("html" in message.content) {
+		formData.append("html", message.content.html);
+		if (message.content.text) formData.append("text", message.content.text);
+	} else formData.append("text", message.content.text);
+	if (message.priority !== "normal") {
+		const priorityMap = {
+			"high": "1",
+			"normal": "3",
+			"low": "5"
+		};
+		formData.append("h:X-Priority", priorityMap[message.priority]);
+	}
+	for (const tag of message.tags) formData.append("o:tag", tag);
+	for (const [key, value] of message.headers.entries()) if (!isStandardHeader(key)) formData.append(`h:${key}`, value);
+	for (const attachment of message.attachments) appendAttachment(formData, attachment);
+	if (config.tracking !== void 0) formData.append("o:tracking", config.tracking ? "yes" : "no");
+	if (config.clickTracking !== void 0) formData.append("o:tracking-clicks", config.clickTracking ? "yes" : "no");
+	if (config.openTracking !== void 0) formData.append("o:tracking-opens", config.openTracking ? "yes" : "no");
+	return formData;
+}
+/**
+* Formats an address for Mailgun API.
+*
+* @param address - The address to format
+* @returns Formatted address string
+*/
+function formatAddress(address) {
+	if (address.name) {
+		const escapedName = address.name.replace(/"/g, "\\\"");
+		return `"${escapedName}" <${address.address}>`;
+	}
+	return address.address;
+}
+/**
+* Appends an attachment to the FormData.
+*
+* @param formData - The FormData to append to
+* @param attachment - The attachment to append
+*/
+function appendAttachment(formData, attachment) {
+	const blob = new Blob([attachment.content], { type: attachment.contentType });
+	if (attachment.contentId) formData.append("inline", blob, attachment.filename);
+	else formData.append("attachment", blob, attachment.filename);
+}
+/**
+* Checks if a header is a standard email header that should not be prefixed with 'h:'.
+*
+* @param headerName - The header name to check
+* @returns True if it's a standard header
+*/
+function isStandardHeader(headerName) {
+	const standardHeaders = [
+		"from",
+		"to",
+		"cc",
+		"bcc",
+		"reply-to",
+		"subject",
+		"date",
+		"message-id",
+		"content-type",
+		"content-transfer-encoding",
+		"mime-version"
+	];
+	return standardHeaders.includes(headerName.toLowerCase());
+}
+
+//#endregion
+//#region src/mailgun-transport.ts
+/**
+* Mailgun transport implementation for sending emails via Mailgun API.
+*
+* This transport provides efficient email delivery using Mailgun's HTTP API,
+* with support for authentication, retry logic, and batch sending capabilities.
+*
+* @example
+* ```typescript
+* import { MailgunTransport } from '@upyo/mailgun';
+*
+* const transport = new MailgunTransport({
+*   apiKey: 'your-api-key',
+*   domain: 'your-domain.com',
+*   region: 'us' // or 'eu'
+* });
+*
+* const receipt = await transport.send(message);
+* console.log('Message sent:', receipt.messageId);
+* ```
+*/
+var MailgunTransport = class {
+	config;
+	httpClient;
+	/**
+	* Creates a new Mailgun transport instance.
+	*
+	* @param config Mailgun configuration including API key, domain, and options.
+	*/
+	constructor(config) {
+		this.config = createMailgunConfig(config);
+		this.httpClient = new MailgunHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message via Mailgun API.
+	*
+	* This method converts the message to Mailgun format, makes an HTTP request
+	* to the Mailgun API, 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) {
+		options?.signal?.throwIfAborted();
+		try {
+			const formData = convertMessage(message, this.config);
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendMessage(formData, options?.signal);
+			return {
+				messageId: response.id,
+				errorMessages: [],
+				successful: true
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			return {
+				messageId: "",
+				errorMessages: [errorMessage],
+				successful: false
+			};
+		}
+	}
+	/**
+	* Sends multiple email messages efficiently via Mailgun API.
+	*
+	* This method sends each message individually but provides a streamlined
+	* interface for processing multiple messages. Each message is sent as a
+	* separate API request to Mailgun.
+	*
+	* @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;
+		if (isAsyncIterable) for await (const message of messages) {
+			options?.signal?.throwIfAborted();
+			yield await this.send(message, options);
+		}
+		else for (const message of messages) {
+			options?.signal?.throwIfAborted();
+			yield await this.send(message, options);
+		}
+	}
+};
+
+//#endregion
+exports.MailgunApiError = MailgunApiError;
+exports.MailgunTransport = MailgunTransport;
+exports.createMailgunConfig = createMailgunConfig;