mailchannels-sdk 1.6.0 → 1.7.0

package/README.md

@@ -18,7 +18,10 @@ This library provides a simple way to interact with the [MailChannels Email API]
 <!-- #endregion overview -->
 
 - [✨ Release Notes](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js/src/HEAD/CHANGELOG.md)
-- [📖 Documentation](https://mailchannels.yizack.com)
+- [📖 Official quickstart](https://docs.mailchannels.com/email-api/javascript/quickstart)
+- [📦 npm package](https://www.npmjs.com/package/mailchannels-sdk)
+- [📚 SDK reference](https://mailchannels.yizack.com)
+- [Nuxt community module](https://nuxt.com/modules/mailchannels) — maintained separately from this SDK.
 
 ## Contents
 

package/dist/_chunks/mailchannels.mjs

@@ -3,7 +3,7 @@ import { subtle } from "node:crypto";
 import { Buffer } from "node:buffer";
 import mime from "mime";
 var name = "mailchannels-sdk";
-var version = "1.6.0";
+var version = "1.7.0";
 var MailChannelsClient = class MailChannelsClient {
 	static DEFAULT_BASE_URL = "https://api.mailchannels.net";
 	static DEFAULT_TIMEOUT = 12e4;
@@ -1563,7 +1563,7 @@ var SubAccountsLimits = class {
 				error
 			};
 		}
-		if (options.sends < 0) {
+		if (!Number.isInteger(options.sends) || options.sends < 0) {
 			error = createValidationError("The sends value must be at least 0.");
 			return {
 				success: false,

package/dist/cli/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Attachment, Emails, MailChannelsClient, name, version } from "../_chunks/mailchannels.mjs";
+import { Attachment, Emails, MailChannelsClient, Suppressions, Webhooks, name, version } from "../_chunks/mailchannels.mjs";
 import { createSimulator } from "../_chunks/simulator.mjs";
 import { defineCommand, runMain } from "citty";
 var simulate_default = defineCommand({
@@ -39,16 +39,42 @@ var simulate_default = defineCommand({
 		process.on("SIGTERM", shutdown);
 	}
 });
+const getApiKey = (apiKey) => {
+	const { MAILCHANNELS_API_KEY } = process.env;
+	const key = apiKey || MAILCHANNELS_API_KEY;
+	if (!key) {
+		console.error("Missing API key. Provide it using the '--api-key' flag or set the 'MAILCHANNELS_API_KEY' environment variable.");
+		process.exit(1);
+	}
+	return key;
+};
+const sharedArgs = { "api-key": {
+	type: "string",
+	alias: "k",
+	valueHint: "key"
+} };
 const emailArgs = {
-	"api-key": {
+	...sharedArgs,
+	"campaign-id": {
+		type: "string",
+		valueHint: "id"
+	},
+	"dkim-domain": {
+		type: "string",
+		valueHint: "domain"
+	},
+	"dkim-selector": {
+		type: "string",
+		valueHint: "selector"
+	},
+	"dkim-private-key": {
+		type: "string",
+		valueHint: "key"
+	},
+	"envelope-from": {
 		type: "string",
-		alias: "k"
+		valueHint: "address"
 	},
-	"campaign-id": { type: "string" },
-	"dkim-domain": { type: "string" },
-	"dkim-selector": { type: "string" },
-	"dkim-private-key": { type: "string" },
-	"envelope-from": { type: "string" },
 	"tracking-click": {
 		type: "boolean",
 		default: false
@@ -67,16 +93,17 @@ const emailArgs = {
 	},
 	"from": {
 		type: "string",
-		required: true
+		required: true,
+		valueHint: "address"
 	},
 	"headers": {
 		type: "string",
-		alias: "h",
-		valueHint: "JSON"
+		valueHint: "json"
 	},
 	"to": {
 		type: "string",
-		required: true
+		required: true,
+		valueHint: "addresses"
 	},
 	"subject": {
 		type: "string",
@@ -90,9 +117,18 @@ const emailArgs = {
 		type: "string",
 		default: ""
 	},
-	"cc": { type: "string" },
-	"bcc": { type: "string" },
-	"reply-to": { type: "string" },
+	"cc": {
+		type: "string",
+		valueHint: "addresses"
+	},
+	"bcc": {
+		type: "string",
+		valueHint: "addresses"
+	},
+	"reply-to": {
+		type: "string",
+		valueHint: "address"
+	},
 	"attachments": {
 		type: "boolean",
 		alias: "a",
@@ -107,15 +143,6 @@ const emailArgs = {
 		valueHint: "name"
 	}
 };
-const getApiKey = (apiKey) => {
-	const { MAILCHANNELS_API_KEY } = process.env;
-	const key = MAILCHANNELS_API_KEY || apiKey;
-	if (!key) {
-		console.error("[Emails] Missing API key. Provide it using the '--api-key' flag or set the 'MAILCHANNELS_API_KEY' environment variable.");
-		process.exit(1);
-	}
-	return key;
-};
 const parseAttachments = async (rawAttachments) => {
 	if (!rawAttachments) return;
 	if (process.stdin.isTTY) {
@@ -196,7 +223,7 @@ const parseOptions = async (args) => {
 var send_default = defineCommand({
 	meta: {
 		name: "send",
-		description: "Send an email using the MailChannels Email API"
+		description: "Send an email"
 	},
 	args: {
 		...emailArgs,
@@ -221,7 +248,7 @@ var send_default = defineCommand({
 var queue_default = defineCommand({
 	meta: {
 		name: "queue",
-		description: "Queue an email to be sent using the MailChannels Email API"
+		description: "Queue an email to be sent"
 	},
 	args: emailArgs,
 	async run({ args }) {
@@ -240,7 +267,7 @@ var queue_default = defineCommand({
 var emails_default = defineCommand({
 	meta: {
 		name: "emails",
-		description: "Commands for sending emails using the MailChannels Email API"
+		description: "Commands for sending emails"
 	},
 	args: {},
 	subCommands: {
@@ -248,6 +275,431 @@ var emails_default = defineCommand({
 		queue: queue_default
 	}
 });
+const isValidEntry = (value) => {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const entry = value;
+	return typeof entry.recipient === "string" && (entry.types === void 0 || Array.isArray(entry.types));
+};
+const parseEntries = async (rawEntries, recipient, types, notes) => {
+	if (rawEntries) {
+		if (recipient) console.warn("[Suppressions] Warning: both '--entries' and '--recipient' are provided. Using '--entries'.");
+		if (types || notes) console.warn("[Suppressions] Warning: '--entries' ignores '--types' and '--notes'.");
+		if (process.stdin.isTTY) {
+			console.error("[Suppressions] '--entries' requires JSON input piped to stdin.");
+			process.exit(1);
+		}
+		let input = "";
+		for await (const chunk of process.stdin) input += chunk;
+		let parsed;
+		try {
+			parsed = JSON.parse(input);
+		} catch {
+			console.error("[Suppressions] JSON input for '--entries' is not valid.");
+			process.exit(1);
+		}
+		if (!Array.isArray(parsed) || !parsed.every(isValidEntry)) {
+			console.error("[Suppressions] '--entries' must be a JSON array of suppression entries.");
+			process.exit(1);
+		}
+		return parsed;
+	}
+	if (!recipient) {
+		console.error("[Suppressions] Either '--entries' or '--recipient' is required.");
+		process.exit(1);
+	}
+	const entry = { recipient };
+	const parsedTypes = types?.split(",").map((type) => type.trim());
+	if (parsedTypes?.length) entry.types = parsedTypes;
+	if (notes) entry.notes = notes;
+	return [entry];
+};
+var create_default$1 = defineCommand({
+	meta: {
+		name: "create",
+		description: "Create suppression entries"
+	},
+	args: {
+		...sharedArgs,
+		"recipient": {
+			type: "string",
+			valueHint: "address"
+		},
+		"types": {
+			type: "string",
+			valueHint: "types"
+		},
+		"notes": { type: "string" },
+		"entries": {
+			type: "boolean",
+			default: false
+		},
+		"add-to-sub-accounts": {
+			type: "boolean",
+			default: false
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const suppressions = new Suppressions(client);
+		const entries = await parseEntries(args["entries"], args["recipient"], args["types"], args["notes"]);
+		const { error } = await suppressions.create(entries, { addToSubAccounts: args["add-to-sub-accounts"] });
+		if (error) {
+			console.error(`[Suppressions] ${error.message}`);
+			process.exit(1);
+		}
+		console.info("[Suppressions] Suppression entries created successfully.");
+	}
+});
+var delete_default = defineCommand({
+	meta: {
+		name: "delete",
+		description: "Delete a suppression entry"
+	},
+	args: {
+		...sharedArgs,
+		recipient: {
+			type: "string",
+			required: true,
+			valueHint: "address"
+		},
+		source: {
+			type: "string",
+			valueHint: "source"
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { error } = await new Suppressions(client).delete(args["recipient"], args["source"]);
+		if (error) {
+			console.error(`[Suppressions] ${error.message}`);
+			process.exit(1);
+		}
+		console.info("[Suppressions] Suppression entry deleted successfully.");
+	}
+});
+const parsePagination = (limit, offset) => {
+	return {
+		limit: limit ? Number(limit) : void 0,
+		offset: offset ? Number(offset) : void 0
+	};
+};
+const escape = "\x1B";
+const createStyle = (code, reset = 39) => (text) => {
+	return `${escape}[${code}m${text}${escape}[${reset}m`;
+};
+const styles = {
+	green: createStyle(32),
+	yellow: createStyle(33),
+	blue: createStyle(34),
+	underline: createStyle(4, 24)
+};
+const styleText = (format, text) => {
+	if (Array.isArray(format)) return format.reduceRight((styledText, currentFormat) => styles[currentFormat](styledText), text);
+	return styles[format](text);
+};
+const styleValue = (value) => {
+	if (Array.isArray(value)) return `[ ${value.map(styleValue).join(", ")} ]`;
+	if (value !== null && typeof value === "object") return `{ ${Object.entries(value).map(([key, nestedValue]) => `${key}: ${styleValue(nestedValue)}`).join(", ")} }`;
+	const text = String(value);
+	switch (typeof value) {
+		case "number":
+		case "boolean": return styleText("yellow", text);
+		case "string": return styleText("green", `'${text}'`);
+		default: return text;
+	}
+};
+const camelCaseToWords = (text) => {
+	return text.replace(/([A-Z])/g, " $1").replace(/^./, (str) => str.toUpperCase());
+};
+const toWordsKeys = (record) => {
+	if (Array.isArray(record)) return record.map((item) => typeof item === "object" && item !== null ? toWordsKeys(item) : item);
+	return Object.fromEntries(Object.entries(record).map(([key, value]) => [camelCaseToWords(key), typeof value === "object" && value !== null ? toWordsKeys(value) : value]));
+};
+const separatorChar = "─";
+const separatorLength = 64;
+const markerStart = 2;
+const separator = separatorChar.repeat(separatorLength);
+const separatorWithIndex = (index) => {
+	const marker = ` [${index}] `;
+	return separator.slice(0, markerStart) + marker + separator.slice(markerStart + marker.length);
+};
+const tabulate = (record) => {
+	const entries = Object.entries(toWordsKeys(record));
+	const labelWidth = Math.max(...entries.map(([label]) => label.length));
+	return entries.map(([label, value]) => `  ${label.padEnd(labelWidth + 2)}${styleValue(value)}`).join("\n");
+};
+const tabulatedSections = (records) => {
+	const isArray = Array.isArray(records);
+	const arr = isArray ? records : [records];
+	return arr.map((record, i) => {
+		const content = tabulate(record);
+		return `\n${isArray ? separatorWithIndex(i) : separator}\n${content}${i < arr.length - 1 ? "" : "\n" + separator}`;
+	}).join("");
+};
+var list_default$1 = defineCommand({
+	meta: {
+		name: "list",
+		description: "List suppression entries"
+	},
+	args: {
+		...sharedArgs,
+		"recipient": {
+			type: "string",
+			valueHint: "address"
+		},
+		"source": {
+			type: "string",
+			valueHint: "source"
+		},
+		"created-after": {
+			type: "string",
+			valueHint: "datetime"
+		},
+		"created-before": {
+			type: "string",
+			valueHint: "datetime"
+		},
+		"limit": {
+			type: "string",
+			alias: "l",
+			valueHint: "number"
+		},
+		"offset": {
+			type: "string",
+			alias: "o",
+			valueHint: "number"
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { data, error } = await new Suppressions(client).list({
+			recipient: args["recipient"],
+			source: args["source"],
+			createdAfter: args["created-after"],
+			createdBefore: args["created-before"],
+			...parsePagination(args["limit"], args["offset"])
+		});
+		if (error) {
+			console.error(`[Suppressions] ${error.message}`);
+			process.exit(1);
+		}
+		if (!data.length) {
+			console.info("[Suppressions] No suppression entries found.");
+			return;
+		}
+		console.info("[Suppressions] Retrieved suppression entries:" + tabulatedSections(data));
+		console.info("[Suppressions] Total suppression entries retrieved:", data.length, `(with limit: ${styleText("yellow", args["limit"] ?? "1000")}, offset: ${styleText("yellow", args["offset"] ?? "0")})`);
+	}
+});
+var suppressions_default = defineCommand({
+	meta: {
+		name: "suppressions",
+		description: "Commands for managing suppression entries"
+	},
+	args: {},
+	subCommands: {
+		create: create_default$1,
+		delete: delete_default,
+		list: list_default$1
+	}
+});
+var create_default = defineCommand({
+	meta: {
+		name: "create",
+		description: "Enroll a new webhook endpoint"
+	},
+	args: {
+		...sharedArgs,
+		endpoint: {
+			type: "string",
+			alias: "e",
+			required: true,
+			valueHint: "url"
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { error } = await new Webhooks(client).create(args["endpoint"]);
+		if (error) {
+			console.error(`[Webhooks] ${error.message}`);
+			process.exit(1);
+		}
+		console.info("[Webhooks] Webhook created successfully.");
+	}
+});
+var delete_all_default = defineCommand({
+	meta: {
+		name: "delete-all",
+		description: "Delete all webhook endpoints"
+	},
+	args: { ...sharedArgs },
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { error } = await new Webhooks(client).deleteAll();
+		if (error) {
+			console.error(`[Webhooks] ${error.message}`);
+			process.exit(1);
+		}
+		console.info("[Webhooks] All webhooks deleted successfully.");
+	}
+});
+var list_default = defineCommand({
+	meta: {
+		name: "list",
+		description: "List all webhook endpoints"
+	},
+	args: { ...sharedArgs },
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { data, error } = await new Webhooks(client).list();
+		if (error) {
+			console.error(`[Webhooks] ${error.message}`);
+			process.exit(1);
+		}
+		if (!data.length) {
+			console.info("[Webhooks] No registered webhooks found.");
+			return;
+		}
+		console.info("[Webhooks] Registered webhook endpoints:");
+		console.table(toWordsKeys(data));
+	}
+});
+var batches_default = defineCommand({
+	meta: {
+		name: "batches",
+		description: "Retrieve paged webhook batches"
+	},
+	args: {
+		...sharedArgs,
+		"created-after": {
+			type: "string",
+			valueHint: "datetime"
+		},
+		"created-before": {
+			type: "string",
+			valueHint: "datetime"
+		},
+		"statuses": {
+			type: "string",
+			alias: "s"
+		},
+		"webhook": {
+			type: "string",
+			alias: ["e", "endpoint"],
+			valueHint: "url"
+		},
+		"limit": {
+			type: "string",
+			alias: "l",
+			valueHint: "number"
+		},
+		"offset": {
+			type: "string",
+			alias: "o",
+			valueHint: "number"
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { data, error } = await new Webhooks(client).batches({
+			createdAfter: args["created-after"],
+			createdBefore: args["created-before"],
+			statuses: args["statuses"]?.split(",").map((s) => s.trim()),
+			webhook: args["webhook"],
+			...parsePagination(args["limit"], args["offset"])
+		});
+		if (error) {
+			console.error(`[Webhooks] ${error.message}`);
+			process.exit(1);
+		}
+		if (!data.length) {
+			console.info("[Webhooks] No webhook batches found.");
+			return;
+		}
+		console.info("[Webhooks] Retrieved webhook batches:" + tabulatedSections(data.map((batch) => ({
+			...batch,
+			duration: batch.duration ? `${batch.duration.value} ${batch.duration.unit}` : ""
+		}))));
+		console.info("[Webhooks] Total batches retrieved:", data.length, `(with limit: ${styleText("yellow", args["limit"] ?? "500")}, offset: ${styleText("yellow", args["offset"] ?? "0")})`);
+	}
+});
+var resend_batch_default = defineCommand({
+	meta: {
+		name: "resend-batch",
+		description: "Resend a webhook batch"
+	},
+	args: {
+		...sharedArgs,
+		"batch-id": {
+			type: "string",
+			alias: "b",
+			required: true,
+			valueHint: "id"
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { data, error } = await new Webhooks(client).resendBatch(Number(args["batch-id"]));
+		if (error) {
+			console.error(`[Webhooks] ${error.message}`);
+			process.exit(1);
+		}
+		console.info("[Webhooks] Webhook batch resent:" + tabulatedSections(data));
+	}
+});
+var validate_default = defineCommand({
+	meta: {
+		name: "validate",
+		description: "Validate enrolled webhooks"
+	},
+	args: {
+		...sharedArgs,
+		"request-id": {
+			type: "string",
+			alias: "r",
+			valueHint: "id"
+		}
+	},
+	async run({ args }) {
+		const apiKey = getApiKey(args["api-key"]);
+		const client = new MailChannelsClient(apiKey);
+		const { data, error } = await new Webhooks(client).validate(args["request-id"]);
+		if (error) {
+			console.error(`[Webhooks] ${error.message}`);
+			process.exit(1);
+		}
+		console.info("[Webhooks] Webhook validation result:");
+		console.table(toWordsKeys(data.results.map(({ result, webhook, response }) => ({
+			result,
+			webhook,
+			status: response?.status
+		}))));
+		console.info("[Webhooks] Total webhooks validated:", data.results.length, "all passed?:", data.allPassed);
+	}
+});
+var webhooks_default = defineCommand({
+	meta: {
+		name: "webhooks",
+		description: "Commands for managing webhooks"
+	},
+	args: {},
+	subCommands: {
+		create: create_default,
+		"delete-all": delete_all_default,
+		list: list_default,
+		batches: batches_default,
+		"resend-batch": resend_batch_default,
+		validate: validate_default
+	}
+});
 const main = defineCommand({
 	meta: {
 		name,
@@ -256,11 +708,14 @@ const main = defineCommand({
 	},
 	subCommands: {
 		simulate: simulate_default,
-		emails: emails_default
+		emails: emails_default,
+		suppressions: suppressions_default,
+		webhooks: webhooks_default
 	},
 	setup() {
 		const LOGGER_NAME = "[MailChannels-CLI]";
 		console.info = console.info.bind(console, LOGGER_NAME);
+		console.warn = console.warn.bind(console, LOGGER_NAME);
 		console.error = console.error.bind(console, LOGGER_NAME);
 	}
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mailchannels-sdk",
-  "version": "1.6.0",
-  "description": "Node.js SDK to integrate MailChannels Email API into your JavaScript or TypeScript server-side applications.",
+  "version": "1.7.0",
+  "description": "Official MailChannels Email API SDK for sending transactional email from server-side JavaScript and TypeScript applications.",
   "type": "module",
   "license": "MIT",
   "keywords": [
@@ -9,13 +9,16 @@
     "typescript",
     "email",
     "transactional-email",
-    "sdk"
+    "sdk",
+    "email-api",
+    "javascript",
+    "nodejs"
   ],
   "repository": {
     "type": "git",
     "url": "git+https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js.git"
   },
-  "homepage": "https://mailchannels.yizack.com",
+  "homepage": "https://docs.mailchannels.com/email-api/javascript/quickstart",
   "author": {
     "name": "MailChannels",
     "email": "dev@mailchannels.com"
@@ -52,18 +55,18 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/markdown-it": "^14.2.0",
-    "@types/node": "^26.5.0",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@types/node": "^26.6.3",
+    "@vitest/coverage-v8": "^5.0.3",
     "changelogen": "^0.6.2",
-    "nodemailer": "^10.0.1",
-    "obuild": "^0.4.39",
-    "oxlint": "^1.82.0",
+    "nodemailer": "^10.0.13",
+    "obuild": "^0.4.43",
+    "oxlint": "^1.86.0",
     "scule": "^1.3.0",
     "typescript": "^6.0.3",
     "vitepress": "^2.0.0-alpha.20",
     "vitepress-plugin-group-icons": "^1.7.6",
-    "vitepress-plugin-llms": "^1.13.5",
-    "vitest": "^5.0.0"
+    "vitepress-plugin-llms": "^1.14.0",
+    "vitest": "^5.0.3"
   },
   "engines": {
     "node": ">=20"