mailchannels-sdk 1.1.0 → 1.3.0

package/dist/mailchannels.mjs

@@ -2,7 +2,7 @@ import { $fetch } from "ofetch";
 import { subtle } from "node:crypto";
 import { Buffer } from "node:buffer";
 import mime from "mime";
-var version = "1.1.0";
+var version = "1.3.0";
 var MailChannelsClient = class MailChannelsClient {
 	static DEFAULT_BASE_URL = "https://api.mailchannels.net";
 	static DEFAULT_TIMEOUT = 12e4;
@@ -79,21 +79,26 @@ const STATUS_ERROR_TYPE_MAP = {
 	[429]: "rate_limit_error",
 	[500]: "internal_server_error"
 };
-const createError = (message, statusCode = null, type) => {
+const createError = (message, statusCode = null, type, response = null) => {
 	return {
 		message,
 		statusCode,
-		type
+		type,
+		response
 	};
 };
 const getStatusError = (response, errors = {}) => {
 	const statusText = errors[response.status] || "Unknown error.";
 	const payload = response._data ?? response.data;
 	let details;
+	let errorResponse = null;
 	if (typeof payload === "string") details = payload;
-	else if (payload?.message) details = payload.message;
-	else if (Array.isArray(payload?.errors) && payload.errors?.length) details = payload.errors.join(", ");
-	return createError(details ? `${statusText} ${details}` : statusText, response.status ?? null, STATUS_ERROR_TYPE_MAP[response.status] || "api_error");
+	else if (typeof payload === "object" && payload !== null) {
+		if (typeof payload.message === "string") details = payload.message;
+		else if (Array.isArray(payload.errors) && payload.errors.length) details = payload.errors.join(", ");
+		errorResponse = payload;
+	}
+	return createError(details ? `${statusText} ${details}` : statusText, response.status ?? null, STATUS_ERROR_TYPE_MAP[response.status] || "api_error", errorResponse);
 };
 const getResultError = (e, fallback) => {
 	return createError(e instanceof Error ? e.message : fallback, null, "application_error");
@@ -107,6 +112,12 @@ const validatePagination = (pagination = {}) => {
 	if (typeof offset === "number" && offset < 0) return createValidationError("Offset must be greater than or equal to 0.");
 	return null;
 };
+const CUSTOM_TRACKING_NAME_PATTERN = /^[a-z0-9-]+$/;
+const validateCustomTrackingName = (name) => {
+	if (!name || name.length < 1 || name.length > 64) return createValidationError("The custom tracking domain name must be between 1 and 64 characters.");
+	if (!CUSTOM_TRACKING_NAME_PATTERN.test(name)) return createValidationError("The custom tracking domain name must match ^[a-z0-9-]+$");
+	return null;
+};
 const clean = (data) => {
 	if (Array.isArray(data)) {
 		const result = [];
@@ -305,6 +316,18 @@ const buildSendPayload = async (options) => {
 			return getRecipientCount(personalization.to) + getRecipientCount(personalization.cc) + getRecipientCount(personalization.bcc) !== 1;
 		})) return "Non-transactional messages must have exactly one recipient per personalization.";
 	}
+	if (options.tracking?.click?.customDomainName !== void 0) {
+		const clickCustomTrackingNameError = validateCustomTrackingName(options.tracking.click.customDomainName);
+		if (clickCustomTrackingNameError) return `Invalid click tracking: ${clickCustomTrackingNameError.message}`;
+	}
+	if (options.tracking?.open?.customDomainName !== void 0) {
+		const openCustomTrackingNameError = validateCustomTrackingName(options.tracking.open.customDomainName);
+		if (openCustomTrackingNameError) return `Invalid open tracking: ${openCustomTrackingNameError.message}`;
+	}
+	if (options.unsubscribe?.customDomainName !== void 0) {
+		const unsubscribeCustomTrackingNameError = validateCustomTrackingName(options.unsubscribe.customDomainName);
+		if (unsubscribeCustomTrackingNameError) return `Invalid unsubscribe settings: ${unsubscribeCustomTrackingNameError.message}`;
+	}
 	const content = [];
 	const template_type = options.template?.type;
 	if (text) content.push({
@@ -335,11 +358,18 @@ const buildSendPayload = async (options) => {
 		from: parsedFrom,
 		subject: options.subject,
 		content,
-		tracking_settings: options.tracking ? {
-			click_tracking: options.tracking.click ? { enable: options.tracking.click.enable } : void 0,
-			open_tracking: options.tracking.open ? { enable: options.tracking.open.enable } : void 0
-		} : void 0,
-		transactional: options.transactional
+		tracking_settings: options.tracking && {
+			click_tracking: options.tracking.click && {
+				custom_domain_name: options.tracking.click.customDomainName,
+				enable: options.tracking.click.enable
+			},
+			open_tracking: options.tracking.open && {
+				custom_domain_name: options.tracking.open.customDomainName,
+				enable: options.tracking.open.enable
+			}
+		},
+		transactional: options.transactional,
+		unsubscribe_settings: options.unsubscribe && { custom_domain_name: options.unsubscribe.customDomainName }
 	};
 };
 var Emails = class {
@@ -603,12 +633,245 @@ var DomainsDkim = class {
 		};
 	}
 };
+var DomainsCustomTracking = class DomainsCustomTracking {
+	mailchannels;
+	static SCOPE_VALUES = /* @__PURE__ */ new Set([
+		"click",
+		"open",
+		"unsubscribe"
+	]);
+	constructor(mailchannels) {
+		this.mailchannels = mailchannels;
+	}
+	async list(options) {
+		let error = null;
+		error = validatePagination({
+			...options,
+			max: 1e3
+		});
+		if (error) return {
+			data: null,
+			error
+		};
+		const response = await this.mailchannels.get("/tx/v1/custom-tracking-domains", {
+			query: options,
+			onResponseError: async ({ response }) => {
+				error = getStatusError(response, { [400]: "Bad Request." });
+			}
+		}).catch((e) => {
+			error ||= getResultError(e, "Failed to fetch custom tracking domains.");
+			return null;
+		});
+		if (!response) return {
+			data: null,
+			error
+		};
+		return {
+			data: clean({
+				customTrackingDomains: response.custom_tracking_domains.map((d) => ({
+					name: d.name,
+					hostname: d.hostname,
+					scope: d.scope,
+					status: d.status,
+					createdAt: d.created_at
+				})),
+				total: response.total
+			}),
+			error: null
+		};
+	}
+	async create(name, hostname, scope) {
+		let error = null;
+		error = validateCustomTrackingName(name);
+		if (error) return {
+			data: null,
+			error
+		};
+		if (!hostname) {
+			error = createValidationError("Hostname is required.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (!scope || !DomainsCustomTracking.SCOPE_VALUES.has(scope)) {
+			error = createValidationError("Scope must be one of 'click', 'open', or 'unsubscribe'.");
+			return {
+				data: null,
+				error
+			};
+		}
+		const payload = {
+			name,
+			hostname,
+			scope
+		};
+		let statusCode = null;
+		const response = await this.mailchannels.post("/tx/v1/custom-tracking-domains", {
+			body: payload,
+			onResponse: async ({ response }) => {
+				statusCode = response.status;
+			},
+			onResponseError: async ({ response }) => {
+				error = getStatusError(response, {
+					[400]: "Invalid request body.",
+					[403]: "No permission to register this domain.",
+					[409]: "A domain with the same name already exists, or the hostname and scope combination is already registered.",
+					[422]: "DNS verification incomplete. Either the TXT ownership record has not propagated yet or the hostname CNAME does not point to the required target."
+				});
+			}
+		}).catch((e) => {
+			error ||= getResultError(e, "Failed to create custom tracking domain.");
+			return null;
+		});
+		if (!response) return {
+			data: null,
+			error
+		};
+		if (statusCode === 202) {
+			const dnsSetupRequiredResponse = response;
+			return {
+				data: clean({
+					dnsSetupRequired: true,
+					token: dnsSetupRequiredResponse.token,
+					txtRecordName: dnsSetupRequiredResponse.txt_record_name,
+					txtRecordValue: dnsSetupRequiredResponse.txt_record_value,
+					instructions: dnsSetupRequiredResponse.instructions
+				}),
+				error: null
+			};
+		}
+		const createResponse = response;
+		return {
+			data: clean({
+				dnsSetupRequired: false,
+				name: createResponse.name,
+				hostname: createResponse.hostname,
+				scope: createResponse.scope,
+				status: createResponse.status,
+				createdAt: createResponse.created_at
+			}),
+			error: null
+		};
+	}
+	async update(hostname, scope, options) {
+		let error = null;
+		if (!hostname) {
+			error = createValidationError("Hostname is required.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (!scope || !DomainsCustomTracking.SCOPE_VALUES.has(scope)) {
+			error = createValidationError("Scope must be one of 'click', 'open', or 'unsubscribe'.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (options.name !== void 0) {
+			error = validateCustomTrackingName(options.name);
+			if (error) return {
+				data: null,
+				error
+			};
+		}
+		if (options.name === void 0 && options.status === void 0) {
+			error = createValidationError("At least one of 'name' or 'status' must be provided.");
+			return {
+				data: null,
+				error
+			};
+		}
+		const payload = {
+			name: options.name,
+			status: options.status
+		};
+		let statusCode = null;
+		const response = await this.mailchannels.patch(`/tx/v1/custom-tracking-domains/${encodeURIComponent(hostname)}/${encodeURIComponent(scope)}`, {
+			body: payload,
+			onResponse: async ({ response }) => {
+				statusCode = response.status;
+			},
+			onResponseError: async ({ response }) => {
+				error = getStatusError(response, {
+					[400]: "Bad Request.",
+					[403]: "No permission to update this domain.",
+					[404]: `Custom tracking domain for hostname '${hostname}' and scope '${scope}' not found.`,
+					[409]: "Name already used by another domain.",
+					[422]: "DNS verification incomplete. Either the TXT ownership record has not propagated yet or the hostname CNAME does not point to the required target."
+				});
+			}
+		}).catch((e) => {
+			error ||= getResultError(e, "Failed to update custom tracking domain.");
+			return null;
+		});
+		if (!response) return {
+			data: null,
+			error
+		};
+		if (statusCode === 202) {
+			const dnsSetupRequiredResponse = response;
+			return {
+				data: clean({
+					dnsSetupRequired: true,
+					token: dnsSetupRequiredResponse.token,
+					txtRecordName: dnsSetupRequiredResponse.txt_record_name,
+					txtRecordValue: dnsSetupRequiredResponse.txt_record_value,
+					instructions: dnsSetupRequiredResponse.instructions
+				}),
+				error: null
+			};
+		}
+		const updateResponse = response;
+		return {
+			data: clean({
+				dnsSetupRequired: false,
+				name: updateResponse.name,
+				hostname: updateResponse.hostname,
+				scope: updateResponse.scope,
+				status: updateResponse.status,
+				createdAt: updateResponse.created_at
+			}),
+			error: null
+		};
+	}
+	async delete(hostname, scope) {
+		let error = null;
+		if (!hostname) {
+			error = createValidationError("Hostname is required.");
+			return {
+				success: false,
+				error
+			};
+		}
+		if (!scope || !DomainsCustomTracking.SCOPE_VALUES.has(scope)) {
+			error = createValidationError("Scope must be one of 'click', 'open', or 'unsubscribe'.");
+			return {
+				success: false,
+				error
+			};
+		}
+		await this.mailchannels.delete(`/tx/v1/custom-tracking-domains/${encodeURIComponent(hostname)}/${encodeURIComponent(scope)}`, { onResponseError: async ({ response }) => {
+			error = getStatusError(response, { [400]: "Invalid hostname or scope value" });
+		} }).catch((e) => {
+			error ||= getResultError(e, "Failed to delete custom tracking domain.");
+		});
+		return {
+			success: !error,
+			error
+		};
+	}
+};
 var Domains = class {
 	mailchannels;
 	dkim;
+	customTracking;
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 		this.dkim = new DomainsDkim(mailchannels);
+		this.customTracking = new DomainsCustomTracking(mailchannels);
 	}
 	async check(domain, options) {
 		let error = null;
@@ -1480,7 +1743,8 @@ var SubAccounts = class SubAccounts {
 			data: clean({
 				endDate: response.period_end_date,
 				startDate: response.period_start_date,
-				total: response.total_usage
+				total: response.total_usage,
+				monthlyLimit: response.monthly_limit
 			}),
 			error: null
 		};
@@ -1558,14 +1822,22 @@ var Metrics = class {
 					click: response.buckets.click.map(mapBucket),
 					clickTrackingDelivered: response.buckets.click_tracking_delivered.map(mapBucket),
 					open: response.buckets.open.map(mapBucket),
-					openTrackingDelivered: response.buckets.open_tracking_delivered.map(mapBucket)
+					openTrackingDelivered: response.buckets.open_tracking_delivered.map(mapBucket),
+					uniqueClick: response.buckets.unique_click?.map(mapBucket),
+					uniqueClickTrackingDelivered: response.buckets.unique_click_tracking_delivered?.map(mapBucket),
+					uniqueOpen: response.buckets.unique_open?.map(mapBucket),
+					uniqueOpenTrackingDelivered: response.buckets.unique_open_tracking_delivered?.map(mapBucket)
 				},
 				click: response.click,
 				clickTrackingDelivered: response.click_tracking_delivered,
 				endTime: response.end_time,
 				open: response.open,
 				openTrackingDelivered: response.open_tracking_delivered,
-				startTime: response.start_time
+				startTime: response.start_time,
+				uniqueClick: response.unique_click,
+				uniqueClickTrackingDelivered: response.unique_click_tracking_delivered,
+				uniqueOpen: response.unique_open,
+				uniqueOpenTrackingDelivered: response.unique_open_tracking_delivered
 			}),
 			error: null
 		};
@@ -1601,8 +1873,10 @@ var Metrics = class {
 		return {
 			data: clean({
 				bounced: response.bounced,
+				complained: response.complained,
 				buckets: {
 					bounced: response.buckets.bounced.map(mapBucket),
+					complained: response.buckets.complained.map(mapBucket),
 					delivered: response.buckets.delivered.map(mapBucket),
 					processed: response.buckets.processed.map(mapBucket)
 				},
@@ -1716,7 +1990,8 @@ var Metrics = class {
 			data: clean({
 				endDate: response.period_end_date,
 				startDate: response.period_start_date,
-				total: response.total_usage
+				total: response.total_usage,
+				monthlyLimit: response.monthly_limit
 			}),
 			error: null
 		};
@@ -1776,9 +2051,10 @@ var Suppressions = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
-	async create(options) {
+	async create(entriesOrOptions, options) {
 		let error = null;
-		const { addToSubAccounts, entries } = options;
+		const entries = Array.isArray(entriesOrOptions) ? entriesOrOptions : entriesOrOptions.entries;
+		const createOptions = Array.isArray(entriesOrOptions) ? options : entriesOrOptions;
 		if (entries.length > 1e3) {
 			error = createValidationError("The number of suppression entries must not exceed 1000.");
 			return {
@@ -1787,7 +2063,7 @@ var Suppressions = class {
 			};
 		}
 		const payload = {
-			add_to_sub_accounts: addToSubAccounts,
+			add_to_sub_accounts: createOptions?.addToSubAccounts,
 			suppression_entries: entries.map((entry) => ({
 				notes: entry.notes,
 				recipient: entry.recipient,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailchannels-sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Node.js SDK to integrate MailChannels Email API into your JavaScript or TypeScript server-side applications.",
   "type": "module",
   "license": "MIT",
@@ -43,17 +43,17 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.9.3",
-    "@vitest/coverage-v8": "^4.1.9",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
     "changelogen": "^0.6.2",
-    "obuild": "^0.4.36",
-    "oxlint": "^1.70.0",
+    "obuild": "^0.4.38",
+    "oxlint": "^1.74.0",
     "scule": "^1.3.0",
     "typescript": "^6.0.3",
-    "vitepress": "^2.0.0-alpha.17",
+    "vitepress": "^2.0.0-alpha.18",
     "vitepress-plugin-group-icons": "^1.7.5",
-    "vitepress-plugin-llms": "^1.13.1",
-    "vitest": "^4.1.9"
+    "vitepress-plugin-llms": "^1.13.3",
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=20"