ts-mailkit 2.1.0 → 3.1.0

package/dist/index.js

@@ -258,17 +258,12 @@ 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.
+	* Sends the same rendered template DTO to every recipient in a single batch.
 	*
 	* 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}.
+	* recipients are not exposed to one another. The content is identical for
+	* everyone; for per-recipient content, use {@link sendBulkKnownTemplate}
+	* with a provider-side template and `mergeInfo`.
 	*
 	* Example:
 	* ```ts
@@ -300,7 +295,9 @@ var MailKit = class {
 			tags: options.tags,
 			metadata: options.metadata,
 			trackClicks: options.trackClicks,
-			trackOpens: options.trackOpens
+			trackOpens: options.trackOpens,
+			bounceAddress: options.bounceAddress,
+			clientReference: options.clientReference
 		});
 	}
 	/**
@@ -363,7 +360,12 @@ function createMailKit(options) {
 //#endregion
 //#region src/transports/cpaas/cpaas-sender.ts
 /**
-* Zoho CPaaS (formerly ZeptoMail) transactional email HTTP transport adapter.
+* Zoho CPaaS accepts at most 500 recipients per request, counted across
+* `to`, `cc`, and `bcc`.
+*/
+const CPAAS_MAX_RECIPIENTS = 500;
+/**
+* Zoho CPaaS transactional email HTTP transport adapter.
 *
 * Uses the standard global `fetch` API for zero-dependency, universal edge
 * compatibility (Node.js, Bun, Deno, Cloudflare Workers).
@@ -373,6 +375,9 @@ function createMailKit(options) {
 * - `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`)
+*
+* Requests exceeding Zoho's 500-recipient limit (across `to`, `cc`, and `bcc`)
+* are rejected before any network call is made.
 */
 var CpaasHttpSender = class {
 	name = "cpaas";
@@ -425,7 +430,16 @@ var CpaasHttpSender = class {
 		const payload = this.buildBatchTemplatePayload(options);
 		return await this.post(`${this.apiBase}/email/template/batch`, payload);
 	}
+	/**
+	* Guards against requests that exceed Zoho CPaaS's per-request recipient
+	* limit, counted across `to`, `cc`, and `bcc`.
+	*/
+	assertRecipientLimit(to, cc, bcc) {
+		const total = normalizeRecipients(to).length + normalizeRecipients(cc).length + normalizeRecipients(bcc).length;
+		if (total > CPAAS_MAX_RECIPIENTS) throw new TransportError(`CpaasHttpSender: Too many recipients (${total}). Zoho CPaaS accepts at most ${CPAAS_MAX_RECIPIENTS} recipients per request across to, cc, and bcc.`, { transportName: this.name });
+	}
 	buildSendPayload(options) {
+		this.assertRecipientLimit(options.to, options.cc, options.bcc);
 		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;
@@ -446,6 +460,7 @@ var CpaasHttpSender = class {
 		return payload;
 	}
 	buildTemplatePayload(options) {
+		this.assertRecipientLimit(options.to, options.cc, options.bcc);
 		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;
@@ -465,6 +480,7 @@ var CpaasHttpSender = class {
 		return payload;
 	}
 	buildBatchTemplatePayload(options) {
+		this.assertRecipientLimit(options.to, options.cc, options.bcc);
 		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 = {
@@ -569,8 +585,7 @@ var CpaasHttpSender = class {
 		return {
 			success: true,
 			messageId: responseData?.data?.[0]?.message_id,
-			rawResponse: responseData,
-			response: responseData
+			rawResponse: responseData
 		};
 	}
 };
@@ -591,12 +606,10 @@ var MemoryEmailSender = class {
 	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,
-			rawResponse,
-			response: rawResponse
+			rawResponse: { id: messageId }
 		};
 	}
 	async send(options) {
@@ -738,12 +751,10 @@ var ConsoleEmailSender = class {
 		}
 		lines.push(`└${separator}┘\n`);
 		this.log(lines.join("\n"));
-		const rawResponse = { logged: true };
 		return {
 			success: true,
 			messageId,
-			rawResponse,
-			response: rawResponse
+			rawResponse: { logged: true }
 		};
 	}
 };
@@ -778,130 +789,152 @@ var EmailTemplateFactory = class EmailTemplateFactory {
 	buildFooter(brandName) {
 		return this.footerResolver(brandName);
 	}
+	arrangePlainTextWithExtras(base, extraMessage, footer) {
+		const parts = [base];
+		if (extraMessage) parts.push(htmlToPlainText(extraMessage));
+		if (footer) parts.push(htmlToPlainText(footer));
+		return parts.join("\n\n");
+	}
 	/**
 	* Welcome / email-verification email sent after registration.
 	*/
 	createEmailVerification(params) {
-		const { username, verificationUrl, otp, brandName } = params;
+		const { username, verificationUrl, otp, brandName, logoUrl, extraMessage, footer } = params;
 		const brand = this.resolveBrand(brandName);
 		const body = `Hi ${username},<br/>Thank you for signing up. Use the code below or click the button to verify your email address.`;
+		const resolvedExtraMessage = extraMessage ?? this.defaultSecurityMessage;
+		const resolvedFooter = footer ?? this.buildFooter(brand);
+		const plainTextBody = htmlToPlainText(body) + `\n\nYour verification code is: ${otp}\n\nAlternatively, verify here:\n${verificationUrl}`;
 		return {
 			subject: "Verify Your Email Address",
 			header: `Welcome to ${brand}!`,
 			body,
-			logoUrl: this.defaultLogoUrl,
+			logoUrl: logoUrl ?? this.defaultLogoUrl,
 			otpCode: otp,
 			actionUrl: verificationUrl,
 			actionText: "Verify Email",
-			extraMessage: this.defaultSecurityMessage,
-			footer: this.buildFooter(brand),
+			extraMessage: resolvedExtraMessage,
+			footer: resolvedFooter,
 			userName: username,
 			fromName: brand,
-			noHtmlMessage: htmlToPlainText(body) + `\n\nYour verification code is: ${otp}\n\nAlternatively, verify here:\n${verificationUrl}`
+			noHtmlMessage: this.arrangePlainTextWithExtras(plainTextBody, resolvedExtraMessage, resolvedFooter)
 		};
 	}
 	/**
 	* Password-reset email with an optional OTP code and action link.
 	*/
 	createPasswordReset(params) {
-		const { username, resetUrl, otp = "", brandName } = params;
+		const { username, resetUrl, otp = "", brandName, logoUrl, extraMessage, footer } = params;
 		const brand = this.resolveBrand(brandName);
 		const body = `Hi ${username},<br/>We received a request to reset your password. Use the OTP code below or click the button to proceed.`;
 		const plainTextOtp = otp ? `\n\nYour OTP code is: ${otp}` : "";
+		const resolvedExtraMessage = extraMessage ?? this.defaultSecurityMessage;
+		const resolvedFooter = footer ?? this.buildFooter(brand);
+		const plainTextBody = htmlToPlainText(body) + plainTextOtp + `\n\nAlternatively, you can use the following link to reset your password:\n${resetUrl}`;
 		return {
 			subject: "Password Reset Request",
 			header: "Reset Your Password",
 			body,
-			logoUrl: this.defaultLogoUrl,
+			logoUrl: logoUrl ?? this.defaultLogoUrl,
 			otpCode: otp || void 0,
 			actionUrl: resetUrl,
 			actionText: "Reset Password",
-			extraMessage: this.defaultSecurityMessage,
-			footer: this.buildFooter(brand),
+			extraMessage: resolvedExtraMessage,
+			footer: resolvedFooter,
 			userName: username,
 			fromName: brand,
-			noHtmlMessage: htmlToPlainText(body) + plainTextOtp + `\n\nAlternatively, you can use the following link to reset your password:\n${resetUrl}`
+			noHtmlMessage: this.arrangePlainTextWithExtras(plainTextBody, resolvedExtraMessage, resolvedFooter)
 		};
 	}
 	/**
 	* Generic plain message email (no action button, no OTP).
 	*/
 	createSimpleMessage(params) {
-		const { subject, header, body, brandName } = params;
+		const { subject, header, body, brandName, logoUrl, extraMessage, footer } = params;
 		const brand = this.resolveBrand(brandName);
+		const resolvedFooter = footer ?? this.buildFooter(brand);
 		return {
 			subject,
 			header,
 			body,
-			logoUrl: this.defaultLogoUrl,
-			footer: this.buildFooter(brand),
+			logoUrl: logoUrl ?? this.defaultLogoUrl,
+			extraMessage,
+			footer: resolvedFooter,
 			fromName: brand,
-			noHtmlMessage: htmlToPlainText(body)
+			noHtmlMessage: this.arrangePlainTextWithExtras(htmlToPlainText(body), extraMessage, resolvedFooter)
 		};
 	}
 	/**
 	* Newsletter / announcement email with an optional hero image and CTA button.
 	*/
 	createNewsLetter(params) {
-		const { subject, header, body, imageUrl, actionUrl, actionText, brandName, logoUrl } = params;
+		const { subject, header, body, imageUrl, actionUrl, actionText, brandName, logoUrl, extraMessage, footer } = params;
 		const brand = this.resolveBrand(brandName);
-		let noHtmlMessage = htmlToPlainText(body);
-		if (actionUrl) noHtmlMessage += `\n\n${actionText || "Learn more"}: ${actionUrl}`;
+		const resolvedFooter = footer ?? this.buildFooter(brand);
+		let plainTextBody = htmlToPlainText(body);
+		if (actionUrl) plainTextBody += `\n\n${actionText || "Learn more"}: ${actionUrl}`;
 		return {
 			subject,
 			header,
 			body,
-			logoUrl: logoUrl || this.defaultLogoUrl,
+			logoUrl: logoUrl ?? this.defaultLogoUrl,
 			imageUrl,
 			actionUrl,
 			actionText,
-			footer: this.buildFooter(brand),
+			extraMessage,
+			footer: resolvedFooter,
 			fromName: brand,
-			noHtmlMessage
+			noHtmlMessage: this.arrangePlainTextWithExtras(plainTextBody, extraMessage, resolvedFooter)
 		};
 	}
 	/**
 	* Two-factor authentication email with OTP code and optional magic link.
 	*/
 	create2FAEmail(params) {
-		const { username, otp, magicLink = "", brandName } = params;
+		const { username, otp, magicLink = "", brandName, logoUrl, extraMessage, footer } = params;
 		const brand = this.resolveBrand(brandName);
 		const body = `Hi ${username},<br/>Use the code below or click the button to complete your login.`;
 		const plainLink = magicLink ? `\n\nAlternatively, verify here:\n${magicLink}` : "";
+		const resolvedExtraMessage = extraMessage ?? this.defaultSecurityMessage;
+		const resolvedFooter = footer ?? this.buildFooter(brand);
+		const plainTextBody = htmlToPlainText(body) + `\n\nYour verification code is: ${otp}` + plainLink;
 		return {
 			subject: "Your Login Verification Code",
 			header: "Two-Factor Authentication",
 			body,
-			logoUrl: this.defaultLogoUrl,
+			logoUrl: logoUrl ?? this.defaultLogoUrl,
 			otpCode: otp,
 			actionUrl: magicLink || void 0,
 			actionText: magicLink ? "Verify Login" : void 0,
-			extraMessage: this.defaultSecurityMessage,
-			footer: this.buildFooter(brand),
+			extraMessage: resolvedExtraMessage,
+			footer: resolvedFooter,
 			userName: username,
 			fromName: brand,
-			noHtmlMessage: htmlToPlainText(body) + `\n\nYour verification code is: ${otp}` + plainLink
+			noHtmlMessage: this.arrangePlainTextWithExtras(plainTextBody, resolvedExtraMessage, resolvedFooter)
 		};
 	}
 	/**
 	* Magic link sign-in email (no OTP, button only).
 	*/
 	createMagicLinkEmail(params) {
-		const { username, magicLink, brandName } = params;
+		const { username, magicLink, brandName, logoUrl, extraMessage, footer } = params;
 		const brand = this.resolveBrand(brandName);
 		const body = `Hi ${username},<br/>Click the button below to sign in. No password needed.`;
+		const resolvedExtraMessage = extraMessage ?? this.defaultSecurityMessage;
+		const resolvedFooter = footer ?? this.buildFooter(brand);
+		const plainTextBody = htmlToPlainText(body) + `\n\nSign in here:\n${magicLink}`;
 		return {
 			subject: "Your Magic Link",
 			header: `Sign In to ${brand}`,
 			body,
-			logoUrl: this.defaultLogoUrl,
+			logoUrl: logoUrl ?? this.defaultLogoUrl,
 			actionUrl: magicLink,
 			actionText: "Sign In",
-			extraMessage: this.defaultSecurityMessage,
-			footer: this.buildFooter(brand),
+			extraMessage: resolvedExtraMessage,
+			footer: resolvedFooter,
 			userName: username,
 			fromName: brand,
-			noHtmlMessage: htmlToPlainText(body) + `\n\nSign in here:\n${magicLink}`
+			noHtmlMessage: this.arrangePlainTextWithExtras(plainTextBody, resolvedExtraMessage, resolvedFooter)
 		};
 	}
 	static _defaultInstance;
@@ -948,5 +981,5 @@ function buildPlainTextTemplate(dto, _options) {
 }
 
 //#endregion
-export { ConfigurationError, ConsoleEmailSender, CpaasHttpSender, CpaasHttpSender as ZeptoMailHttpSender, DefaultEmailRenderer, EmailTemplateFactory, MailKit, MailKitError, MemoryEmailSender, TemplateError, TransportError, buildHTMLTemplate, buildHtml, buildPlainText, buildPlainTextTemplate, createMailKit, decodeHtmlEntities, htmlToPlainText, isValidHttpUrl, normalizeRecipient, normalizeRecipients, parseEmailAddress };
+export { ConfigurationError, ConsoleEmailSender, CpaasHttpSender, DefaultEmailRenderer, EmailTemplateFactory, MailKit, MailKitError, MemoryEmailSender, TemplateError, TransportError, buildHTMLTemplate, buildHtml, buildPlainText, buildPlainTextTemplate, createMailKit, decodeHtmlEntities, htmlToPlainText, isValidHttpUrl, normalizeRecipient, normalizeRecipients, parseEmailAddress };
 //# sourceMappingURL=index.js.map