ts-mailkit 2.0.1 → 2.1.0

package/dist/index.cjs

@@ -68,6 +68,8 @@ var TransportError = class extends MailKitError {
 	transportName;
 	statusCode;
 	responseBody;
+	/** Parsed raw provider response, when available. */
+	rawResponse;
 	cause;
 	constructor(message, options) {
 		super(message);
@@ -75,6 +77,7 @@ var TransportError = class extends MailKitError {
 		this.transportName = options.transportName;
 		this.statusCode = options.statusCode;
 		this.responseBody = options.responseBody;
+		this.rawResponse = options.rawResponse;
 		this.cause = options.cause;
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
@@ -221,18 +224,16 @@ var MailKit = class {
 	*
 	* Example:
 	* ```ts
-	* await mailer.send({
+	* await mailer.sendMail({
 	*   to: 'user@example.com',
 	*   template: myDto,
 	* });
 	* ```
 	*/
-	async send(options) {
+	async sendMail(options) {
 		const template = options.template;
 		const recipientName = options.toName ?? template.userName;
-		let resolvedFromName = options.fromName ?? template.fromName;
-		if (!resolvedFromName && this.brandNameResolver) resolvedFromName = await this.brandNameResolver();
-		if (!resolvedFromName) resolvedFromName = this.defaultBrandName;
+		const resolvedFromName = await this.resolveFromName(template, options.fromName);
 		const rendered = await this.renderer.render(template);
 		const plaintextBody = template.noHtmlMessage ?? rendered.text;
 		let toRecipients;
@@ -241,11 +242,7 @@ var MailKit = class {
 			name: recipientName
 		};
 		else toRecipients = options.to;
-		let from = options.from ?? this.defaultFrom;
-		if (resolvedFromName && from) from = {
-			address: normalizeRecipient(from).address,
-			name: resolvedFromName
-		};
+		const from = this.applyFromName(options.from ?? this.defaultFrom, resolvedFromName);
 		return await this.sendRaw({
 			to: toRecipients,
 			from,
@@ -262,6 +259,88 @@ var MailKit = class {
 		});
 	}
 	/**
+	* @deprecated Use {@link sendMail} instead.
+	*/
+	async send(options) {
+		return await this.sendMail(options);
+	}
+	/**
+	* Sends a bulk email using a strongly-typed template DTO.
+	*
+	* The transport delivers an individual copy to each recipient, so
+	* recipients are not exposed to one another. Per-recipient personalization
+	* is available via {@link sendBulkKnownTemplate}.
+	*
+	* Example:
+	* ```ts
+	* await mailer.sendBulkMail({
+	*   to: ['a@example.com', 'b@example.com'],
+	*   template: myDto,
+	* });
+	* ```
+	*/
+	async sendBulkMail(options) {
+		const transport = this.transport;
+		if (typeof transport.sendBulk !== "function") throw new ConfigurationError("MailKit: The configured transport does not support bulk sending (sendBulk).");
+		const template = options.template;
+		const resolvedFromName = await this.resolveFromName(template);
+		const rendered = await this.renderer.render(template);
+		const plaintextBody = template.noHtmlMessage ?? rendered.text;
+		const from = this.applyFromName(options.from ?? this.defaultFrom, resolvedFromName);
+		return await transport.sendBulk({
+			to: options.to,
+			from,
+			subject: template.subject,
+			html: rendered.html,
+			text: plaintextBody,
+			cc: options.cc,
+			bcc: options.bcc,
+			replyTo: options.replyTo,
+			attachments: options.attachments,
+			headers: options.headers,
+			tags: options.tags,
+			metadata: options.metadata,
+			trackClicks: options.trackClicks,
+			trackOpens: options.trackOpens
+		});
+	}
+	/**
+	* Sends a single email using a provider-side template.
+	*/
+	async sendKnownTemplate(options) {
+		const transport = this.transport;
+		if (typeof transport.sendKnownTemplate !== "function") throw new ConfigurationError("MailKit: The configured transport does not support template sending (sendKnownTemplate).");
+		return await transport.sendKnownTemplate({
+			...options,
+			from: options.from ?? this.defaultFrom
+		});
+	}
+	/**
+	* Sends a bulk email using a provider-side template with optional
+	* per-recipient merge data.
+	*/
+	async sendBulkKnownTemplate(options) {
+		const transport = this.transport;
+		if (typeof transport.sendBulkKnownTemplate !== "function") throw new ConfigurationError("MailKit: The configured transport does not support bulk template sending (sendBulkKnownTemplate).");
+		return await transport.sendBulkKnownTemplate({
+			...options,
+			from: options.from ?? this.defaultFrom
+		});
+	}
+	async resolveFromName(template, explicitFromName) {
+		let resolved = explicitFromName ?? template.fromName;
+		if (!resolved && this.brandNameResolver) resolved = await this.brandNameResolver();
+		if (!resolved) resolved = this.defaultBrandName;
+		return resolved;
+	}
+	applyFromName(from, fromName) {
+		if (fromName && from) return {
+			address: normalizeRecipient(from).address,
+			name: fromName
+		};
+		return from;
+	}
+	/**
 	* Dispatches a raw, pre-rendered email directly through the transport.
 	* If `options.text` is omitted, plain text is automatically derived from `options.html`.
 	*/
@@ -283,38 +362,73 @@ function createMailKit(options) {
 }
 
 //#endregion
-//#region src/transports/zeptomail/zeptomail-sender.ts
+//#region src/transports/cpaas/cpaas-sender.ts
 /**
-* ZeptoMail (Zoho Mail transactional email HTTP API) transport adapter.
+* Zoho CPaaS (formerly ZeptoMail) transactional email HTTP transport adapter.
 *
-* Designed for zero dependencies and universal edge compatibility (Node.js, Bun, Deno, Cloudflare Workers)
-* by utilizing the standard global `fetch` API.
+* Uses the standard global `fetch` API for zero-dependency, universal edge
+* compatibility (Node.js, Bun, Deno, Cloudflare Workers).
+*
+* Supports:
+* - `send` — single raw email (`POST /v1.1/email`)
+* - `sendBulk` — batch raw email (`POST /v1.1/email/batch`)
+* - `sendKnownTemplate` — single template email (`POST /v1.1/email/template`)
+* - `sendBulkKnownTemplate` — batch template email (`POST /v1.1/email/template/batch`)
 */
-var ZeptoMailHttpSender = class {
-	name = "zeptomail";
-	apiUrl;
+var CpaasHttpSender = class {
+	name = "cpaas";
+	apiBase;
 	authHeader;
 	defaultFrom;
+	preferTemplateAlias;
 	fetchImpl;
 	constructor(config) {
-		if (!config.apiToken || typeof config.apiToken !== "string") throw new ConfigurationError("ZeptoMailHttpSender: Missing or invalid apiToken.");
-		if (!config.from) throw new ConfigurationError("ZeptoMailHttpSender: Missing required default from address.");
-		const host = (config.apiHost || "api.zeptomail.com").replace(/^https?:\/\//, "").replace(/\/+$/, "");
-		this.apiUrl = `https://${host}/v1.1/email`;
+		if (!config.apiToken || typeof config.apiToken !== "string") throw new ConfigurationError("CpaasHttpSender: Missing or invalid apiToken.");
+		if (!config.from) throw new ConfigurationError("CpaasHttpSender: Missing required default from address.");
+		const host = (config.apiHost || "cpaas.zoho.com").replace(/^https?:\/\//, "").replace(/\/+$/, "");
+		this.apiBase = `https://${host}/v1.1`;
 		const token = config.apiToken.trim();
 		this.authHeader = token.startsWith("Zoho-") ? token : `Zoho-enczapikey ${token}`;
 		this.defaultFrom = normalizeRecipient(config.from);
-		if (!this.defaultFrom.address) throw new ConfigurationError("ZeptoMailHttpSender: Configured from address must not be empty.");
+		if (!this.defaultFrom.address) throw new ConfigurationError("CpaasHttpSender: Configured from address must not be empty.");
+		this.preferTemplateAlias = config.preferTemplateAlias ?? false;
 		const fetchImpl = config.fetch ?? globalThis.fetch;
-		if (typeof fetchImpl !== "function") throw new ConfigurationError("ZeptoMailHttpSender: No global fetch implementation found. Pass a custom fetch to ZeptoMailHttpConfig if running on Node < 18.");
+		if (typeof fetchImpl !== "function") throw new ConfigurationError("CpaasHttpSender: No global fetch implementation found. Pass a custom fetch to CpaasHttpConfig if running on Node < 18.");
 		this.fetchImpl = fetchImpl.bind(globalThis);
 	}
 	/**
-	* Dispatches an email using Zoho ZeptoMail API v1.1.
+	* Dispatches a single raw email using Zoho CPaaS API.
 	*/
 	async send(options) {
+		const payload = this.buildSendPayload(options);
+		return await this.post(`${this.apiBase}/email`, payload);
+	}
+	/**
+	* Dispatches a batch of a single raw email content to many recipients.
+	* The provider delivers an individual copy to each recipient.
+	*/
+	async sendBulk(options) {
+		const payload = this.buildSendPayload(options);
+		return await this.post(`${this.apiBase}/email/batch`, payload);
+	}
+	/**
+	* Dispatches a single email using a provider-side template.
+	*/
+	async sendKnownTemplate(options) {
+		const payload = this.buildTemplatePayload(options);
+		return await this.post(`${this.apiBase}/email/template`, payload);
+	}
+	/**
+	* Dispatches a batch of emails using a provider-side template, with
+	* optional per-recipient merge data.
+	*/
+	async sendBulkKnownTemplate(options) {
+		const payload = this.buildBatchTemplatePayload(options);
+		return await this.post(`${this.apiBase}/email/template/batch`, payload);
+	}
+	buildSendPayload(options) {
 		const toRecipients = normalizeRecipients(options.to);
-		if (toRecipients.length === 0) throw new TransportError("ZeptoMailHttpSender: At least one recipient (to) must be specified.", { transportName: this.name });
+		if (toRecipients.length === 0) throw new TransportError("CpaasHttpSender: At least one recipient (to) must be specified.", { transportName: this.name });
 		const resolvedFrom = options.from ? normalizeRecipient(options.from) : this.defaultFrom;
 		const payload = {
 			from: {
@@ -329,6 +443,52 @@ var ZeptoMailHttpSender = class {
 			htmlbody: options.html,
 			textbody: options.text
 		};
+		this.applyCommon(payload, options);
+		return payload;
+	}
+	buildTemplatePayload(options) {
+		const toRecipients = normalizeRecipients(options.to);
+		if (toRecipients.length === 0) throw new TransportError("CpaasHttpSender: At least one recipient (to) must be specified.", { transportName: this.name });
+		const resolvedFrom = options.from ? normalizeRecipient(options.from) : this.defaultFrom;
+		const payload = {
+			...this.templateRef(options.templateId),
+			from: {
+				address: resolvedFrom.address,
+				name: resolvedFrom.name
+			},
+			to: toRecipients.map((r) => ({ email_address: {
+				address: r.address,
+				name: r.name || ""
+			} }))
+		};
+		if (options.mergeInfo) payload.merge_info = options.mergeInfo;
+		this.applyCommon(payload, options);
+		return payload;
+	}
+	buildBatchTemplatePayload(options) {
+		if (!options.to || options.to.length === 0) throw new TransportError("CpaasHttpSender: At least one recipient (to) must be specified.", { transportName: this.name });
+		const resolvedFrom = options.from ? normalizeRecipient(options.from) : this.defaultFrom;
+		const payload = {
+			...this.templateRef(options.templateId),
+			from: {
+				address: resolvedFrom.address,
+				name: resolvedFrom.name
+			},
+			to: options.to.map((r) => ({
+				email_address: {
+					address: r.address,
+					name: r.name || ""
+				},
+				...r.mergeInfo ? { merge_info: r.mergeInfo } : {}
+			}))
+		};
+		this.applyCommon(payload, options);
+		return payload;
+	}
+	templateRef(templateId) {
+		return this.preferTemplateAlias ? { template_alias: templateId } : { template_key: templateId };
+	}
+	applyCommon(payload, options) {
 		if (options.cc) {
 			const ccList = normalizeRecipients(options.cc);
 			if (ccList.length > 0) payload.cc = ccList.map((r) => ({ email_address: {
@@ -350,26 +510,33 @@ var ZeptoMailHttpSender = class {
 				name: r.name
 			}));
 		}
-		if (options.attachments && options.attachments.length > 0) payload.attachments = options.attachments.map((att) => {
-			let contentBase64;
-			if (typeof att.content === "string") contentBase64 = att.content;
-			else if (typeof Buffer !== "undefined") contentBase64 = Buffer.from(att.content).toString("base64");
-			else {
-				let binary = "";
-				const bytes = new Uint8Array(att.content);
-				for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
-				contentBase64 = btoa(binary);
-			}
-			return {
-				name: att.filename,
-				content: contentBase64,
-				mime_type: att.mimeType || att.contentType || "application/octet-stream",
-				cid: att.cid
-			};
-		});
+		if (options.attachments && options.attachments.length > 0) payload.attachments = options.attachments.map((att) => this.toAttachmentPayload(att));
+		if (options.trackClicks !== void 0) payload.track_clicks = options.trackClicks;
+		if (options.trackOpens !== void 0) payload.track_opens = options.trackOpens;
+		if (options.bounceAddress !== void 0) payload.bounce_address = options.bounceAddress;
+		if (options.clientReference !== void 0) payload.client_reference = options.clientReference;
+	}
+	toAttachmentPayload(att) {
+		let contentBase64;
+		if (typeof att.content === "string") contentBase64 = att.content;
+		else if (typeof Buffer !== "undefined") contentBase64 = Buffer.from(att.content).toString("base64");
+		else {
+			let binary = "";
+			const bytes = new Uint8Array(att.content);
+			for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
+			contentBase64 = btoa(binary);
+		}
+		return {
+			name: att.filename,
+			content: contentBase64,
+			mime_type: att.mimeType || att.contentType || "application/octet-stream",
+			cid: att.cid
+		};
+	}
+	async post(url, payload) {
 		let response;
 		try {
-			response = await this.fetchImpl(this.apiUrl, {
+			response = await this.fetchImpl(url, {
 				method: "POST",
 				headers: {
 					Accept: "application/json",
@@ -379,7 +546,7 @@ var ZeptoMailHttpSender = class {
 				body: JSON.stringify(payload)
 			});
 		} catch (err) {
-			throw new TransportError(`ZeptoMailHttpSender: Network request failed: ${err instanceof Error ? err.message : String(err)}`, {
+			throw new TransportError(`CpaasHttpSender: Network request failed: ${err instanceof Error ? err.message : String(err)}`, {
 				transportName: this.name,
 				cause: err
 			});
@@ -392,16 +559,18 @@ var ZeptoMailHttpSender = class {
 			responseData = { raw: responseText };
 		}
 		if (!response.ok) {
-			const errorMessage = responseData?.error?.message || responseData?.message || `HTTP ${response.status}: ${responseText || response.statusText}`;
-			throw new TransportError(`ZeptoMailHttpSender: Failed to send email - ${errorMessage}`, {
+			const errorMessage = responseData?.data?.message || responseData?.error?.message || responseData?.message || `HTTP ${response.status}: ${responseText || response.statusText}`;
+			throw new TransportError(`CpaasHttpSender: Failed to send email - ${errorMessage}`, {
 				transportName: this.name,
 				statusCode: response.status,
-				responseBody: responseText
+				responseBody: responseText,
+				rawResponse: responseData
 			});
 		}
 		return {
 			success: true,
 			messageId: responseData?.data?.[0]?.message_id,
+			rawResponse: responseData,
 			response: responseData
 		};
 	}
@@ -416,36 +585,78 @@ var ZeptoMailHttpSender = class {
 var MemoryEmailSender = class {
 	name = "memory";
 	sentMails = [];
+	sentBulkMails = [];
+	sentTemplateMails = [];
+	sentBulkTemplateMails = [];
 	nextId = 1;
-	async send(options) {
-		this.sentMails.push({ ...options });
-		const messageId = `mem-${this.nextId++}-${Date.now()}`;
+	result(prefix) {
+		const id = this.nextId++;
+		const messageId = prefix ? `mem-${prefix}-${id}-${Date.now()}` : `mem-${id}-${Date.now()}`;
+		const rawResponse = { id: messageId };
 		return {
 			success: true,
 			messageId,
-			response: { id: messageId }
+			rawResponse,
+			response: rawResponse
 		};
 	}
+	async send(options) {
+		this.sentMails.push({ ...options });
+		return this.result();
+	}
+	async sendBulk(options) {
+		this.sentBulkMails.push({ ...options });
+		return this.result("bulk");
+	}
+	async sendKnownTemplate(options) {
+		this.sentTemplateMails.push({ ...options });
+		return this.result("tpl");
+	}
+	async sendBulkKnownTemplate(options) {
+		this.sentBulkTemplateMails.push({ ...options });
+		return this.result("bulk-tpl");
+	}
 	/**
-	* Returns a copy of all emails sent through this transport instance.
+	* Returns a copy of all single emails sent through this transport instance.
 	*/
 	getSentMails() {
 		return [...this.sentMails];
 	}
 	/**
-	* Returns the most recent email sent, or undefined if no emails have been sent.
+	* Returns the most recent single email sent, or undefined if none have been sent.
 	*/
 	getLastMail() {
 		return this.sentMails.length > 0 ? { ...this.sentMails[this.sentMails.length - 1] } : void 0;
 	}
 	/**
-	* Clears all recorded sent emails.
+	* Returns a copy of all bulk emails sent through this transport instance.
+	*/
+	getSentBulkMails() {
+		return [...this.sentBulkMails];
+	}
+	/**
+	* Returns a copy of all single template emails sent through this transport instance.
+	*/
+	getSentTemplateMails() {
+		return [...this.sentTemplateMails];
+	}
+	/**
+	* Returns a copy of all bulk template emails sent through this transport instance.
+	*/
+	getSentBulkTemplateMails() {
+		return [...this.sentBulkTemplateMails];
+	}
+	/**
+	* Clears all recorded emails.
 	*/
 	clear() {
 		this.sentMails = [];
+		this.sentBulkMails = [];
+		this.sentTemplateMails = [];
+		this.sentBulkTemplateMails = [];
 	}
 	/**
-	* Returns the total count of sent emails.
+	* Returns the total count of single emails sent.
 	*/
 	count() {
 		return this.sentMails.length;
@@ -468,33 +679,72 @@ var ConsoleEmailSender = class {
 		this.includeHtml = options.includeHtml ?? false;
 	}
 	async send(options) {
-		const to = normalizeRecipients(options.to).map((r) => r.name ? `${r.name} <${r.address}>` : r.address).join(", ");
-		const from = options.from ? JSON.stringify(options.from) : "(default)";
+		return this.logDispatch({
+			kind: "EMAIL",
+			to: options.to,
+			from: options.from,
+			subject: options.subject,
+			text: options.text,
+			html: options.html
+		});
+	}
+	async sendBulk(options) {
+		return this.logDispatch({
+			kind: "BULK EMAIL",
+			to: options.to,
+			from: options.from,
+			subject: options.subject,
+			text: options.text,
+			html: options.html
+		});
+	}
+	async sendKnownTemplate(options) {
+		return this.logDispatch({
+			kind: "TEMPLATE EMAIL",
+			to: options.to,
+			from: options.from,
+			templateId: options.templateId
+		});
+	}
+	async sendBulkKnownTemplate(options) {
+		return this.logDispatch({
+			kind: "BULK TEMPLATE EMAIL",
+			to: options.to,
+			from: options.from,
+			templateId: options.templateId
+		});
+	}
+	logDispatch(entry) {
+		const to = normalizeRecipients(entry.to).map((r) => r.name ? `${r.name} <${r.address}>` : r.address).join(", ");
+		const from = entry.from ? JSON.stringify(entry.from) : "(default)";
 		const messageId = `console-${this.nextId++}-${Date.now()}`;
 		const separator = "─".repeat(60);
 		const lines = [
 			`\n┌${separator}┐`,
-			`│ [ts-mailkit:console] DISPATCHED EMAIL (${messageId})`,
+			`│ [ts-mailkit:console] DISPATCHED ${entry.kind} (${messageId})`,
 			`├${separator}┤`,
 			`│ From:    ${from}`,
-			`│ To:      ${to}`,
-			`│ Subject: ${options.subject}`,
-			`├${separator}┤`
+			`│ To:      ${to}`
 		];
-		if (options.text) {
+		if (entry.subject !== void 0) lines.push(`│ Subject: ${entry.subject}`);
+		if (entry.templateId !== void 0) lines.push(`│ Template: ${entry.templateId}`);
+		lines.push(`├${separator}┤`);
+		if (entry.text) {
 			lines.push("│ Text Body:");
-			for (const line of options.text.split("\n")) lines.push(`│   ${line}`);
+			for (const line of entry.text.split("\n")) lines.push(`│   ${line}`);
 		}
-		if (this.includeHtml && options.html) {
+		if (this.includeHtml && entry.html) {
 			lines.push("│ HTML Body:");
-			for (const line of options.html.split("\n")) lines.push(`│   ${line}`);
+			for (const line of entry.html.split("\n")) lines.push(`│   ${line}`);
 		}
 		lines.push(`└${separator}┘\n`);
 		this.log(lines.join("\n"));
+		const rawResponse = { logged: true };
 		return {
 			success: true,
 			messageId,
-			response: { logged: true }
+			rawResponse,
+			response: rawResponse
 		};
 	}
 };
@@ -680,9 +930,28 @@ var EmailTemplateFactory = class EmailTemplateFactory {
 	}
 };
 
+//#endregion
+//#region src/templates/template-builder.ts
+/**
+* Builds an upload-ready HTML template from the canonical {@link EmailTemplateDto}.
+*
+* The output can be uploaded to a messaging platform (Zoho CPaaS, SendGrid, etc.)
+* as a provider-side template.
+*/
+function buildHTMLTemplate(dto, options = {}) {
+	return buildHtml(dto, options);
+}
+/**
+* Builds an upload-ready plain-text template from the canonical {@link EmailTemplateDto}.
+*/
+function buildPlainTextTemplate(dto, _options) {
+	return buildPlainText(dto);
+}
+
 //#endregion
 exports.ConfigurationError = ConfigurationError;
 exports.ConsoleEmailSender = ConsoleEmailSender;
+exports.CpaasHttpSender = CpaasHttpSender;
 exports.DefaultEmailRenderer = DefaultEmailRenderer;
 exports.EmailTemplateFactory = EmailTemplateFactory;
 exports.MailKit = MailKit;
@@ -690,9 +959,11 @@ exports.MailKitError = MailKitError;
 exports.MemoryEmailSender = MemoryEmailSender;
 exports.TemplateError = TemplateError;
 exports.TransportError = TransportError;
-exports.ZeptoMailHttpSender = ZeptoMailHttpSender;
+exports.ZeptoMailHttpSender = CpaasHttpSender;
+exports.buildHTMLTemplate = buildHTMLTemplate;
 exports.buildHtml = buildHtml;
 exports.buildPlainText = buildPlainText;
+exports.buildPlainTextTemplate = buildPlainTextTemplate;
 exports.createMailKit = createMailKit;
 exports.decodeHtmlEntities = decodeHtmlEntities;
 exports.htmlToPlainText = htmlToPlainText;