@upyo/mailgun 0.1.0-dev.9 → 0.1.0

package/README.md

@@ -3,9 +3,17 @@
 @upyo/mailgun
 =============
 
-[Mailgun] transport for Upyo email library.
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
 
+[Mailgun] transport for the [Upyo] email library.
+
+[JSR]: https://jsr.io/@upyo/mailgun
+[JSR badge]: https://jsr.io/badges/@upyo/mailgun
+[npm]: https://www.npmjs.com/package/@upyo/mailgun
+[npm badge]: https://img.shields.io/npm/v/@upyo/mailgun?logo=npm
 [Mailgun]: https://www.mailgun.com/
+[Upyo]: https://upyo.org/
 
 
 Installation
@@ -24,22 +32,35 @@ Usage
 -----
 
 ~~~~ typescript
-import { MailgunTransport } from '@upyo/mailgun';
+import { createMessage } from "@upyo/core";
+import { MailgunTransport } from "@upyo/mailgun";
+import fs from "node:fs/promises";
+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." },
+  attachments: [
+    new File(
+      [await fs.readFile("image.jpg"), "image.jpg", { type: "image/jpeg" }]
+    )
+  ],
+});
 
 const transport = new MailgunTransport({
-  apiKey: 'your-api-key',
-  domain: 'your-domain.com'
+  apiKey: process.env.MAILGUN_KEY!,
+  domain: process.env.MAILGUN_DOMAIN!,
+  region: process.env.MAILGUN_REGION as "us" | "eu",
 });
 
-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);
+if (receipt.successful) {
+  console.log("Message sent with ID:", receipt.messageId);
+} else {
+  console.error("Send failed:", receipt.errorMessages.join(", "));
+}
 ~~~~
 
 

package/dist/index.cjs

@@ -5,21 +5,11 @@
 *
 * This function takes a partial Mailgun configuration and returns a complete
 * configuration with all optional fields filled with sensible defaults.
+* It is used internally by the Mailgun transport.
 *
 * @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)
-* ```
+* @internal
 */
 function createMailgunConfig(config) {
 	const region = config.region ?? "us";
@@ -162,11 +152,11 @@ var MailgunApiError = class extends Error {
 *
 * @example
 * ```typescript
-* const formData = convertMessage(message, config);
+* const formData = await convertMessage(message, config);
 * const response = await fetch(url, { method: 'POST', body: formData });
 * ```
 */
-function convertMessage(message, config) {
+async 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));
@@ -191,7 +181,7 @@ function convertMessage(message, config) {
 	}
 	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);
+	for (const attachment of message.attachments) await 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");
@@ -216,8 +206,8 @@ function formatAddress(address) {
 * @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 });
+async function appendAttachment(formData, attachment) {
+	const blob = new Blob([await attachment.content], { type: attachment.contentType });
 	if (attachment.contentId) formData.append("inline", blob, attachment.filename);
 	else formData.append("attachment", blob, attachment.filename);
 }
@@ -263,10 +253,17 @@ function isStandardHeader(headerName) {
 * });
 *
 * const receipt = await transport.send(message);
-* console.log('Message sent:', receipt.messageId);
+* if (receipt.successful) {
+*   console.log('Message sent with ID:', receipt.messageId);
+* } else {
+*   console.error('Send failed:', receipt.errorMessages.join(', '));
+* }
 * ```
 */
 var MailgunTransport = class {
+	/**
+	* The resolved Mailgun configuration used by this transport.
+	*/
 	config;
 	httpClient;
 	/**
@@ -314,20 +311,18 @@ var MailgunTransport = class {
 	async send(message, options) {
 		options?.signal?.throwIfAborted();
 		try {
-			const formData = convertMessage(message, this.config);
+			const formData = await convertMessage(message, this.config);
 			options?.signal?.throwIfAborted();
 			const response = await this.httpClient.sendMessage(formData, options?.signal);
 			return {
-				messageId: response.id,
-				errorMessages: [],
-				successful: true
+				successful: true,
+				messageId: response.id
 			};
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
 			return {
-				messageId: "",
-				errorMessages: [errorMessage],
-				successful: false
+				successful: false,
+				errorMessages: [errorMessage]
 			};
 		}
 	}
@@ -399,5 +394,4 @@ var MailgunTransport = class {
 
 //#endregion
 exports.MailgunApiError = MailgunApiError;
-exports.MailgunTransport = MailgunTransport;
-exports.createMailgunConfig = createMailgunConfig;
+exports.MailgunTransport = MailgunTransport;

package/dist/index.d.cts

@@ -100,83 +100,12 @@ type ResolvedMailgunConfig = Required<MailgunConfig>;
  *
  * This function takes a partial Mailgun configuration and returns a complete
  * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Mailgun transport.
  *
  * @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)
- * ```
+ * @internal
  */
-declare function createMailgunConfig(config: MailgunConfig): ResolvedMailgunConfig;
-//#endregion
-//#region src/http-client.d.ts
-/**
- * Response from Mailgun API for sending messages.
- */
-interface MailgunResponse {
-  /**
-   * The message ID returned by Mailgun.
-   */
-  id: string;
-  /**
-   * Success message from Mailgun.
-   */
-  message: string;
-}
-/**
- * Error response from Mailgun API.
- */
-
-/**
- * HTTP client wrapper for Mailgun API requests.
- *
- * This class handles authentication, request formatting, error handling,
- * and retry logic for Mailgun API calls.
- */
-declare class MailgunHttpClient {
-  private config;
-  constructor(config: ResolvedMailgunConfig);
-  /**
-   * 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: FormData, signal?: AbortSignal): Promise<MailgunResponse>;
-  /**
-   * 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.
-   */
-  private makeRequest;
-  /**
-   * 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.
-   */
-  private fetchWithAuth;
-}
-/**
- * Custom error class for Mailgun API errors.
- */
-declare class MailgunApiError extends Error {
-  statusCode?: number;
-  constructor(message: string, statusCode?: number);
-}
 //#endregion
 //#region src/mailgun-transport.d.ts
 /**
@@ -196,12 +125,19 @@ declare class MailgunApiError extends Error {
  * });
  *
  * const receipt = await transport.send(message);
- * console.log('Message sent:', receipt.messageId);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
  * ```
  */
 declare class MailgunTransport implements Transport {
-  config: ReturnType<typeof createMailgunConfig>;
-  httpClient: MailgunHttpClient;
+  /**
+   * The resolved Mailgun configuration used by this transport.
+   */
+  config: ResolvedMailgunConfig;
+  private httpClient;
   /**
    * Creates a new Mailgun transport instance.
    *
@@ -297,4 +233,14 @@ declare class MailgunTransport implements Transport {
   sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
 }
 //#endregion
-export { MailgunApiError, MailgunConfig, MailgunTransport, createMailgunConfig };
+//#region src/http-client.d.ts
+
+/**
+ * Custom error class for Mailgun API errors.
+ */
+declare class MailgunApiError extends Error {
+  statusCode?: number;
+  constructor(message: string, statusCode?: number);
+}
+//#endregion
+export { MailgunApiError, MailgunConfig, MailgunTransport };

package/dist/index.d.ts

@@ -100,83 +100,12 @@ type ResolvedMailgunConfig = Required<MailgunConfig>;
  *
  * This function takes a partial Mailgun configuration and returns a complete
  * configuration with all optional fields filled with sensible defaults.
+ * It is used internally by the Mailgun transport.
  *
  * @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)
- * ```
+ * @internal
  */
-declare function createMailgunConfig(config: MailgunConfig): ResolvedMailgunConfig;
-//#endregion
-//#region src/http-client.d.ts
-/**
- * Response from Mailgun API for sending messages.
- */
-interface MailgunResponse {
-  /**
-   * The message ID returned by Mailgun.
-   */
-  id: string;
-  /**
-   * Success message from Mailgun.
-   */
-  message: string;
-}
-/**
- * Error response from Mailgun API.
- */
-
-/**
- * HTTP client wrapper for Mailgun API requests.
- *
- * This class handles authentication, request formatting, error handling,
- * and retry logic for Mailgun API calls.
- */
-declare class MailgunHttpClient {
-  private config;
-  constructor(config: ResolvedMailgunConfig);
-  /**
-   * 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: FormData, signal?: AbortSignal): Promise<MailgunResponse>;
-  /**
-   * 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.
-   */
-  private makeRequest;
-  /**
-   * 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.
-   */
-  private fetchWithAuth;
-}
-/**
- * Custom error class for Mailgun API errors.
- */
-declare class MailgunApiError extends Error {
-  statusCode?: number;
-  constructor(message: string, statusCode?: number);
-}
 //#endregion
 //#region src/mailgun-transport.d.ts
 /**
@@ -196,12 +125,19 @@ declare class MailgunApiError extends Error {
  * });
  *
  * const receipt = await transport.send(message);
- * console.log('Message sent:', receipt.messageId);
+ * if (receipt.successful) {
+ *   console.log('Message sent with ID:', receipt.messageId);
+ * } else {
+ *   console.error('Send failed:', receipt.errorMessages.join(', '));
+ * }
  * ```
  */
 declare class MailgunTransport implements Transport {
-  config: ReturnType<typeof createMailgunConfig>;
-  httpClient: MailgunHttpClient;
+  /**
+   * The resolved Mailgun configuration used by this transport.
+   */
+  config: ResolvedMailgunConfig;
+  private httpClient;
   /**
    * Creates a new Mailgun transport instance.
    *
@@ -297,4 +233,14 @@ declare class MailgunTransport implements Transport {
   sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
 }
 //#endregion
-export { MailgunApiError, MailgunConfig, MailgunTransport, createMailgunConfig };
+//#region src/http-client.d.ts
+
+/**
+ * Custom error class for Mailgun API errors.
+ */
+declare class MailgunApiError extends Error {
+  statusCode?: number;
+  constructor(message: string, statusCode?: number);
+}
+//#endregion
+export { MailgunApiError, MailgunConfig, MailgunTransport };

package/dist/index.js

@@ -4,21 +4,11 @@
 *
 * This function takes a partial Mailgun configuration and returns a complete
 * configuration with all optional fields filled with sensible defaults.
+* It is used internally by the Mailgun transport.
 *
 * @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)
-* ```
+* @internal
 */
 function createMailgunConfig(config) {
 	const region = config.region ?? "us";
@@ -161,11 +151,11 @@ var MailgunApiError = class extends Error {
 *
 * @example
 * ```typescript
-* const formData = convertMessage(message, config);
+* const formData = await convertMessage(message, config);
 * const response = await fetch(url, { method: 'POST', body: formData });
 * ```
 */
-function convertMessage(message, config) {
+async 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));
@@ -190,7 +180,7 @@ function convertMessage(message, config) {
 	}
 	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);
+	for (const attachment of message.attachments) await 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");
@@ -215,8 +205,8 @@ function formatAddress(address) {
 * @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 });
+async function appendAttachment(formData, attachment) {
+	const blob = new Blob([await attachment.content], { type: attachment.contentType });
 	if (attachment.contentId) formData.append("inline", blob, attachment.filename);
 	else formData.append("attachment", blob, attachment.filename);
 }
@@ -262,10 +252,17 @@ function isStandardHeader(headerName) {
 * });
 *
 * const receipt = await transport.send(message);
-* console.log('Message sent:', receipt.messageId);
+* if (receipt.successful) {
+*   console.log('Message sent with ID:', receipt.messageId);
+* } else {
+*   console.error('Send failed:', receipt.errorMessages.join(', '));
+* }
 * ```
 */
 var MailgunTransport = class {
+	/**
+	* The resolved Mailgun configuration used by this transport.
+	*/
 	config;
 	httpClient;
 	/**
@@ -313,20 +310,18 @@ var MailgunTransport = class {
 	async send(message, options) {
 		options?.signal?.throwIfAborted();
 		try {
-			const formData = convertMessage(message, this.config);
+			const formData = await convertMessage(message, this.config);
 			options?.signal?.throwIfAborted();
 			const response = await this.httpClient.sendMessage(formData, options?.signal);
 			return {
-				messageId: response.id,
-				errorMessages: [],
-				successful: true
+				successful: true,
+				messageId: response.id
 			};
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
 			return {
-				messageId: "",
-				errorMessages: [errorMessage],
-				successful: false
+				successful: false,
+				errorMessages: [errorMessage]
 			};
 		}
 	}
@@ -397,4 +392,4 @@ var MailgunTransport = class {
 };
 
 //#endregion
-export { MailgunApiError, MailgunTransport, createMailgunConfig };
+export { MailgunApiError, MailgunTransport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/mailgun",
-  "version": "0.1.0-dev.9+a57dde18",
+  "version": "0.1.0",
   "description": "Mailgun transport for Upyo email library",
   "keywords": [
     "email",
@@ -53,12 +53,12 @@
   },
   "sideEffects": false,
   "peerDependencies": {
-    "@upyo/core": "0.1.0-dev.9+a57dde18"
+    "@upyo/core": "0.1.0"
   },
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.47.3",
     "tsdown": "^0.12.7",
-    "typescript": "^5.8.3"
+    "typescript": "5.8.3"
   },
   "scripts": {
     "build": "tsdown",