mailchannels-sdk 1.5.2 → 1.7.0

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/dist/plugins/nodemailer/index.d.mts

@@ -1,9 +1,9 @@
 import { EmailsQueueResponse, EmailsSendOptions, EmailsSendResponse, MailChannelsClientOptions } from "../../_chunks/mailchannels.mjs";
-import { Transport as Transport$1 } from "nodemailer";
+import { Transport, TransportOptions, Transporter } from "nodemailer";
 import MimeNode from "nodemailer/lib/mime-node";
-type MailChannelsTransportSendOptions = Pick<EmailsSendOptions, "campaignId" | "tracking" | "transactional" | "unsubscribe">;
-type MailChannelsTransportSendMode = "sync" | "async";
-interface MailChannelsTransportOptions<T extends MailChannelsTransportSendMode = "async"> extends MailChannelsClientOptions {
+export type MailChannelsTransportSendOptions = Pick<EmailsSendOptions, "campaignId" | "tracking" | "transactional" | "unsubscribe">;
+export type MailChannelsTransportSendMode = "sync" | "async";
+export interface MailChannelsTransportOptions<T extends MailChannelsTransportSendMode = "async"> extends MailChannelsClientOptions {
   /**
    * The MailChannels Email API key.
    */
@@ -14,7 +14,7 @@ interface MailChannelsTransportOptions<T extends MailChannelsTransportSendMode =
    */
   sendMode?: T;
 }
-interface MailChannelsTransportInfo<T extends MailChannelsTransportSendMode> {
+export interface MailChannelsTransportInfo<T extends MailChannelsTransportSendMode> {
   messageId: string | null;
   accepted: string[];
   rejected: string[];
@@ -22,12 +22,14 @@ interface MailChannelsTransportInfo<T extends MailChannelsTransportSendMode> {
   response: (T extends "sync" ? EmailsSendResponse : EmailsQueueResponse) | null;
 }
 declare module "nodemailer" {
-  function createTransport<T>(transport: Transport<T> | TransportOptions, defaults?: TransportOptions): Transporter<T, TransportOptions>;
+  function createTransport<T>(transport: Transport<T> | TransportOptions, defaults?: TransportOptions): Transporter<T>;
+  interface SendMailOptions {
+    mailchannels?: MailChannelsTransportSendOptions;
+  }
 }
 declare module "nodemailer/lib/mailer" {
   interface Options {
     mailchannels?: MailChannelsTransportSendOptions;
   }
 }
-declare const mailchannelsTransport: <T extends MailChannelsTransportSendMode = "async">(options: MailChannelsTransportOptions<T>) => Transport$1<MailChannelsTransportInfo<T>>;
-export { MailChannelsTransportInfo, MailChannelsTransportOptions, MailChannelsTransportSendMode, MailChannelsTransportSendOptions, mailchannelsTransport };
+export declare const mailchannelsTransport: <T extends MailChannelsTransportSendMode = "async">(options: MailChannelsTransportOptions<T>) => Transport<MailChannelsTransportInfo<T>>;

package/dist/plugins/nodemailer/index.mjs

@@ -5,9 +5,10 @@ const parseAddress = (address) => {
 	if (!address) return "";
 	if (Array.isArray(address)) return parseAddress(address[0]);
 	if (typeof address === "string") return address;
+	if (!address.address) return "";
 	return {
 		email: address.address,
-		name: address.name || void 0
+		name: address.name
 	};
 };
 const parseAddresses = (addresses) => {
@@ -41,7 +42,7 @@ const parseDkim = (dkim) => {
 	if ("keys" in dkim) throw new Error("Multiple DKIM signatures are not supported");
 	let privateKey;
 	if (typeof dkim.privateKey === "string") privateKey = dkim.privateKey;
-	else if (dkim.privateKey?.key && dkim.privateKey?.passphrase) try {
+	else if (dkim.privateKey && "key" in dkim.privateKey && "passphrase" in dkim.privateKey) try {
 		privateKey = createPrivateKey({
 			key: dkim.privateKey.key,
 			passphrase: dkim.privateKey.passphrase
@@ -62,7 +63,8 @@ const parseDkim = (dkim) => {
 const parseHeaders = (headers) => {
 	if (!headers) return;
 	if (Array.isArray(headers)) return headers.reduce((acc, { key, value }) => {
-		acc[key] = value;
+		if (value == void 0) return acc;
+		acc[key] = value.toString();
 		return acc;
 	}, {});
 	return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, Array.isArray(value) ? value.join(",") : value && typeof value === "object" && "value" in value ? String(value.value) : String(value)]));
@@ -94,7 +96,10 @@ const mailchannelsTransport = (options) => {
 				messageId: null,
 				accepted: [],
 				rejected: [],
-				envelope: mail.message.getEnvelope(),
+				envelope: mail.message?.getEnvelope() ?? {
+					from: false,
+					to: []
+				},
 				response: null
 			};
 			mail.normalize(async (err, data) => {

package/dist/simulator/index.d.mts

@@ -1,4 +1,4 @@
-declare const createSimulator: (options?: {
+export declare const createSimulator: (options?: {
   host?: string;
   port?: number;
   silent?: boolean;
@@ -16,5 +16,4 @@ declare const createSimulator: (options?: {
     host?: string;
     port?: number;
   }): Promise<string>;
-};
-export { createSimulator };
+};