@upyo/sendgrid 0.1.0-dev.13

package/README.md

@@ -0,0 +1,77 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/sendgrid
+==============
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+[SendGrid] transport for the [Upyo] email library.
+
+[JSR]: https://jsr.io/@upyo/sendgrid
+[JSR badge]: https://jsr.io/badges/@upyo/sendgrid
+[npm]: https://www.npmjs.com/package/@upyo/sendgrid
+[npm badge]: https://img.shields.io/npm/v/@upyo/sendgrid?logo=npm
+[SendGrid]: https://sendgrid.com/
+[Upyo]: https://upyo.org/
+
+
+Installation
+------------
+
+~~~~ sh
+npm  add       @upyo/core @upyo/sendgrid
+pnpm add       @upyo/core @upyo/sendgrid
+yarn add       @upyo/core @upyo/sendgrid
+deno add --jsr @upyo/core @upyo/sendgrid
+bun  add       @upyo/core @upyo/sendgrid
+~~~~
+
+
+Usage
+-----
+
+~~~~ typescript
+import { createMessage } from "@upyo/core";
+import { SendGridTransport } from "@upyo/sendgrid";
+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 SendGridTransport({
+  apiKey: process.env.SENDGRID_API_KEY!,
+});
+
+const receipt = await transport.send(message);
+console.log("Email sent:", receipt.successful);
+~~~~
+
+
+Configuration
+-------------
+
+See the [SendGrid docs] for more information about configuration options.
+
+[SendGrid docs]: https://docs.sendgrid.com/
+
+### Available Options
+
+ -  `apiKey`: Your SendGrid API key (starts with `SG.`)
+ -  `baseUrl`: SendGrid API base URL (default: `https://api.sendgrid.com/v3`)
+ -  `timeout`: Request timeout in milliseconds (default: 30000)
+ -  `retries`: Number of retry attempts (default: 3)
+ -  `clickTracking`: Enable click tracking (default: true)
+ -  `openTracking`: Enable open tracking (default: true)
+ -  `subscriptionTracking`: Enable subscription tracking (default: false)
+ -  `googleAnalytics`: Enable Google Analytics tracking (default: false)

package/dist/index.cjs

@@ -0,0 +1,470 @@
+
+//#region src/config.ts
+/**
+* Creates a resolved SendGrid configuration by applying default values to optional fields.
+*
+* This function takes a partial SendGrid configuration and returns a complete
+* configuration with all optional fields filled with sensible defaults.
+*
+* @param config - The SendGrid configuration with optional fields
+* @returns A resolved configuration with all defaults applied
+*
+* @example
+* ```typescript
+* const resolved = createSendGridConfig({
+*   apiKey: 'your-api-key'
+* });
+*
+* // resolved.baseUrl will be 'https://api.sendgrid.com/v3' (default)
+* // resolved.timeout will be 30000 (default)
+* // resolved.retries will be 3 (default)
+* ```
+*/
+function createSendGridConfig(config) {
+	return {
+		apiKey: config.apiKey,
+		baseUrl: config.baseUrl ?? "https://api.sendgrid.com/v3",
+		timeout: config.timeout ?? 3e4,
+		retries: config.retries ?? 3,
+		validateSsl: config.validateSsl ?? true,
+		headers: config.headers ?? {},
+		clickTracking: config.clickTracking ?? true,
+		openTracking: config.openTracking ?? true,
+		subscriptionTracking: config.subscriptionTracking ?? false,
+		googleAnalytics: config.googleAnalytics ?? false
+	};
+}
+
+//#endregion
+//#region src/http-client.ts
+/**
+* HTTP client wrapper for SendGrid API requests.
+*
+* This class handles authentication, request formatting, error handling,
+* and retry logic for SendGrid API calls.
+*/
+var SendGridHttpClient = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Sends a message via SendGrid API.
+	*
+	* @param messageData The JSON data to send to SendGrid.
+	* @param signal Optional AbortSignal for cancellation.
+	* @returns Promise that resolves to the SendGrid response.
+	*/
+	sendMessage(messageData, signal) {
+		const url = `${this.config.baseUrl}/mail/send`;
+		return this.makeRequest(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(messageData),
+			signal
+		});
+	}
+	/**
+	* Makes an HTTP request to SendGrid 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();
+			if (response.status === 202) return {
+				statusCode: response.status,
+				body: text,
+				headers: this.headersToRecord(response.headers)
+			};
+			let errorData;
+			try {
+				errorData = JSON.parse(text);
+			} catch {
+				errorData = { message: text || `HTTP ${response.status}` };
+			}
+			throw new SendGridApiError(errorData.message || `HTTP ${response.status}`, response.status, errorData.errors);
+		} catch (error) {
+			lastError = error instanceof Error ? error : new Error(String(error));
+			if (error instanceof SendGridApiError && 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 SendGrid 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);
+		headers.set("Authorization", `Bearer ${this.config.apiKey}`);
+		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 = options.signal;
+			if (options.signal.aborted) controller.abort();
+			else options.signal.addEventListener("abort", () => controller.abort());
+		}
+		try {
+			return await globalThis.fetch(url, {
+				...options,
+				headers,
+				signal
+			});
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+	/**
+	* Converts Headers object to a plain Record.
+	*
+	* @param headers The Headers object to convert.
+	* @returns A plain object with header key-value pairs.
+	*/
+	headersToRecord(headers) {
+		const record = {};
+		for (const [key, value] of headers.entries()) record[key] = value;
+		return record;
+	}
+};
+/**
+* Custom error class for SendGrid API errors.
+*/
+var SendGridApiError = class extends Error {
+	statusCode;
+	errors;
+	constructor(message, statusCode, errors) {
+		super(message);
+		this.name = "SendGridApiError";
+		this.statusCode = statusCode;
+		this.errors = errors;
+	}
+};
+
+//#endregion
+//#region src/message-converter.ts
+/**
+* Converts a Upyo Message to SendGrid API JSON format.
+*
+* This function transforms the standardized Upyo message format into
+* the specific format expected by the SendGrid API.
+*
+* @param message - The Upyo message to convert
+* @param config - The resolved SendGrid configuration
+* @returns Promise that resolves to a SendGrid mail object
+*
+* @example
+* ```typescript
+* const mailData = await convertMessage(message, config);
+* const response = await httpClient.sendMessage(mailData);
+* ```
+*/
+async function convertMessage(message, config) {
+	const sendGridMail = {
+		personalizations: [],
+		from: formatAddress(message.sender)
+	};
+	const personalization = {
+		to: message.recipients.map(formatAddress),
+		subject: message.subject
+	};
+	if (message.ccRecipients.length > 0) personalization.cc = message.ccRecipients.map(formatAddress);
+	if (message.bccRecipients.length > 0) personalization.bcc = message.bccRecipients.map(formatAddress);
+	sendGridMail.personalizations.push(personalization);
+	if (message.replyRecipients.length > 0) if (message.replyRecipients.length === 1) sendGridMail.reply_to = formatAddress(message.replyRecipients[0]);
+	else sendGridMail.reply_to_list = message.replyRecipients.map(formatAddress);
+	const content = [];
+	if ("html" in message.content) {
+		if (message.content.text) content.push({
+			type: "text/plain",
+			value: message.content.text
+		});
+		content.push({
+			type: "text/html",
+			value: message.content.html
+		});
+	} else content.push({
+		type: "text/plain",
+		value: message.content.text
+	});
+	sendGridMail.content = content;
+	if (message.priority !== "normal") {
+		const headers = {};
+		switch (message.priority) {
+			case "high":
+				headers["X-Priority"] = "1";
+				headers["X-MSMail-Priority"] = "High";
+				headers["Importance"] = "High";
+				break;
+			case "low":
+				headers["X-Priority"] = "5";
+				headers["X-MSMail-Priority"] = "Low";
+				headers["Importance"] = "Low";
+				break;
+		}
+		sendGridMail.headers = {
+			...sendGridMail.headers,
+			...headers
+		};
+	}
+	if (message.tags.length > 0) sendGridMail.categories = message.tags;
+	const customHeaders = {};
+	for (const [key, value] of message.headers.entries()) if (!isStandardHeader(key)) customHeaders[key] = value;
+	if (Object.keys(customHeaders).length > 0) sendGridMail.headers = {
+		...sendGridMail.headers,
+		...customHeaders
+	};
+	if (message.attachments.length > 0) sendGridMail.attachments = await Promise.all(message.attachments.map(convertAttachment));
+	const trackingSettings = {};
+	if (config.clickTracking !== void 0) trackingSettings.click_tracking = {
+		enable: config.clickTracking,
+		enable_text: config.clickTracking
+	};
+	if (config.openTracking !== void 0) trackingSettings.open_tracking = { enable: config.openTracking };
+	if (config.subscriptionTracking !== void 0) trackingSettings.subscription_tracking = { enable: config.subscriptionTracking };
+	if (config.googleAnalytics !== void 0) trackingSettings.ganalytics = { enable: config.googleAnalytics };
+	if (Object.keys(trackingSettings).length > 0) sendGridMail.tracking_settings = trackingSettings;
+	return sendGridMail;
+}
+/**
+* Formats an address for SendGrid API.
+*
+* @param address - The address to format
+* @returns Formatted address object
+*/
+function formatAddress(address) {
+	const result = { email: address.address };
+	if (address.name) result.name = address.name;
+	return result;
+}
+/**
+* Converts a Upyo attachment to SendGrid format.
+*
+* @param attachment - The attachment to convert
+* @returns Promise that resolves to a SendGrid attachment object
+*/
+async function convertAttachment(attachment) {
+	const contentBytes = await attachment.content;
+	const base64Content = btoa(String.fromCharCode(...contentBytes));
+	const sendGridAttachment = {
+		content: base64Content,
+		filename: attachment.filename
+	};
+	if (attachment.contentType) sendGridAttachment.type = attachment.contentType;
+	if (attachment.inline && attachment.contentId) {
+		sendGridAttachment.disposition = "inline";
+		sendGridAttachment.content_id = attachment.contentId;
+	} else sendGridAttachment.disposition = "attachment";
+	return sendGridAttachment;
+}
+/**
+* Checks if a header is a standard email header that should not be added as custom header.
+*
+* @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",
+		"x-priority",
+		"x-msmail-priority",
+		"importance"
+	];
+	return standardHeaders.includes(headerName.toLowerCase());
+}
+
+//#endregion
+//#region src/sendgrid-transport.ts
+/**
+* SendGrid transport implementation for sending emails via SendGrid API.
+*
+* This transport provides efficient email delivery using SendGrid's v3 HTTP API,
+* with support for authentication, retry logic, and batch sending capabilities.
+*
+* @example
+* ```typescript
+* import { SendGridTransport } from '@upyo/sendgrid';
+*
+* const transport = new SendGridTransport({
+*   apiKey: 'your-sendgrid-api-key',
+*   clickTracking: true,
+*   openTracking: true
+* });
+*
+* const receipt = await transport.send(message);
+* console.log('Message sent:', receipt.messageId);
+* ```
+*/
+var SendGridTransport = class {
+	config;
+	httpClient;
+	/**
+	* Creates a new SendGrid transport instance.
+	*
+	* @param config SendGrid configuration including API key and options.
+	*/
+	constructor(config) {
+		this.config = createSendGridConfig(config);
+		this.httpClient = new SendGridHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message via SendGrid API.
+	*
+	* This method converts the message to SendGrid format, makes an HTTP request
+	* to the SendGrid 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 successfully');
+	* }
+	* ```
+	*
+	* @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 mailData = await convertMessage(message, this.config);
+			options?.signal?.throwIfAborted();
+			const response = await this.httpClient.sendMessage(mailData, options?.signal);
+			const messageId = this.extractMessageId(response);
+			return {
+				messageId,
+				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 SendGrid 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 SendGrid.
+	*
+	* @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);
+		}
+	}
+	/**
+	* Extracts or generates a message ID from the SendGrid response.
+	*
+	* SendGrid doesn't return a message ID in the response body for successful sends,
+	* so we generate a synthetic ID based on timestamp and some response data.
+	*
+	* @param response The SendGrid API response.
+	* @returns A message ID string.
+	*/
+	extractMessageId(response) {
+		const messageIdHeader = response.headers?.["x-message-id"] || response.headers?.["X-Message-Id"];
+		if (messageIdHeader) return messageIdHeader;
+		const timestamp = Date.now();
+		const random = Math.random().toString(36).substring(2, 8);
+		return `sendgrid-${timestamp}-${random}`;
+	}
+};
+
+//#endregion
+exports.SendGridApiError = SendGridApiError;
+exports.SendGridTransport = SendGridTransport;
+exports.createSendGridConfig = createSendGridConfig;