@kizunajs/resend 2.0.0-beta.12

package/LICENSE.MD

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sondre Ørland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @kizunajs/resend
+
+`@kizunajs/resend` connects your API to Resend. Your route and job handlers send email and newsletters, and Resend's webhook events run functions you write.
+
+## Installation
+
+```sh
+pnpm add @kizunajs/resend resend
+```
+
+## Usage
+
+```ts
+// kizuna.config.ts
+import { resendPlugin } from '@kizunajs/resend';
+
+export default defineConfig({
+    adapter: expressAdapter(),
+    routes,
+    plugins: [
+        resendPlugin({
+            apiKey: process.env.RESEND_API_KEY,
+            from: 'Kizuna <hello@example.com>',
+        }),
+    ],
+});
+```
+
+Every route and job handler reaches it at `plugins.resend`:
+
+```ts
+await plugins.resend.sendEmail({
+    to: user.email,
+    subject: 'Welcome',
+    html: `<p>Welcome, ${user.name}.</p>`,
+});
+```
+
+## Documentation
+
+[Resend](https://kizunajs.com/docs/resend)

package/dist/index.cjs

@@ -0,0 +1,434 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let resend = require("resend");
+let kizunajs_plugin = require("kizunajs/plugin");
+let zod = require("zod");
+let kizunajs_schemas = require("kizunajs/schemas");
+//#region src/options.ts
+/**
+* A list an app sends to: the Resend segment its contacts sit in, and the topic
+* they opt in and out of.
+*/
+const ResendListSchema = zod.z.object({
+	/**
+	* The segment the list's contacts are added to, and broadcasts go to.
+	*/
+	segmentId: zod.z.string(),
+	/**
+	* The topic a contact opts in and out of, so unsubscribing from one list
+	* leaves the others alone.
+	*/
+	topicId: zod.z.string().optional()
+});
+/**
+* The loosest of Zod's email patterns, so the plugin never refuses an address
+* Resend would accept.
+*/
+const EmailSchema = zod.z.email({ pattern: zod.z.regexes.unicodeEmail });
+/**
+* A sender as Resend takes it: an address, or a name and an address in angle
+* brackets.
+*/
+const isSender = (value) => {
+	const named = /^[^<>]+<([^<>]+)>$/.exec(value.trim());
+	return EmailSchema.safeParse(named === null ? value.trim() : named[1]).success;
+};
+const SenderSchema = zod.z.string().refine(isSender, { error: "must be an address, or a name and an address like `Kizuna <hello@example.com>`" });
+const ResendPluginOptionsSchema = zod.z.object({
+	/**
+	* The Resend API key.
+	*/
+	apiKey: zod.z.string(),
+	/**
+	* The sender every email and broadcast uses unless it names its own.
+	*
+	* @example
+	* from: 'Kizuna <hello@example.com>',
+	*/
+	from: SenderSchema,
+	/**
+	* The lists `subscribe`, `unsubscribe` and `broadcast` name, keyed by
+	* the name handlers use.
+	*
+	* @example
+	* lists: {
+	*     weekly: {
+	*         segmentId: 'seg_123',
+	*         topicId: 'top_456',
+	*     },
+	* },
+	*/
+	lists: zod.z.record(zod.z.string(), ResendListSchema).optional(),
+	/**
+	* The webhook's signing secret. The webhook route is served when it's set.
+	*/
+	webhookSecret: zod.z.string().optional(),
+	/**
+	* What runs for each webhook event, keyed by its type.
+	*/
+	on: zod.z.custom((value) => typeof value === "object" && value !== null, { error: "must map event types to functions" }).optional(),
+	/**
+	* Catch every email outside production and forward it to `forwardTo`
+	* instead of its real recipients.
+	*
+	* @example
+	* intercept: {
+	*     enabled: process.env.NODE_ENV !== 'production',
+	*     forwardTo: process.env.EMAIL_FORWARD_TO,
+	*     deliverTo: ['@example.com'],
+	* },
+	*/
+	intercept: zod.z.object({
+		/**
+		* Whether emails are intercepted.
+		*/
+		enabled: zod.z.boolean(),
+		/**
+		* Where every email is forwarded, one address or several.
+		* Required when `enabled` is true.
+		*/
+		forwardTo: zod.z.union([EmailSchema, zod.z.array(EmailSchema).min(1)]).optional(),
+		/**
+		* Addresses, or whole domains like `@example.com`, whose emails are
+		* delivered as normal, with `forwardTo` in bcc.
+		*/
+		deliverTo: zod.z.array(zod.z.string()).optional(),
+		/**
+		* Put in front of every intercepted email's subject.
+		*
+		* @example
+		* subjectPrefix: '[dev]',
+		*/
+		subjectPrefix: zod.z.string().optional()
+	}).refine((intercept) => !intercept.enabled || intercept.forwardTo !== void 0, {
+		error: "is required when intercept is enabled",
+		path: ["forwardTo"]
+	}).optional(),
+	/**
+	* Passed to the Resend client as it is.
+	*/
+	resend: zod.z.custom().optional()
+}).refine((options) => options.on === void 0 || options.webhookSecret !== void 0, {
+	error: "is required when `on` is set",
+	path: ["webhookSecret"]
+});
+//#endregion
+//#region src/requests.ts
+/**
+* A call to Resend that answered with an error.
+*/
+var ResendRequestError = class extends Error {
+	action;
+	error;
+	constructor(action, error) {
+		super(`[kizuna/resend] ${action} failed: ${error.message}`);
+		this.action = action;
+		this.error = error;
+	}
+};
+/**
+* How many times a rate-limited call is tried again.
+*/
+const RATE_LIMIT_RETRIES = 3;
+const wait = (milliseconds) => new Promise((resolve) => {
+	setTimeout(resolve, milliseconds);
+});
+/**
+* Call Resend, retrying when it's rate limited, and throw its error.
+*/
+const call = async (action, request) => {
+	let response = await request();
+	for (let retry = 0; retry < RATE_LIMIT_RETRIES && response.error?.name === "rate_limit_exceeded"; retry++) {
+		const seconds = Number(response.headers?.["retry-after"] ?? 1);
+		await wait((Number.isFinite(seconds) ? seconds : 1) * 1e3);
+		response = await request();
+	}
+	if (response.error !== null) throw new ResendRequestError(action, response.error);
+	return response.data;
+};
+/**
+* Every item of a paginated Resend list.
+*/
+const everyPage = async (action, request) => {
+	const items = [];
+	let after;
+	for (;;) {
+		const page = await call(action, () => request(after));
+		items.push(...page.data);
+		const last = page.data.at(-1);
+		if (!page.has_more || last === void 0) return items;
+		after = last.id;
+	}
+};
+const listOf = (addresses) => addresses === void 0 ? [] : Array.isArray(addresses) ? addresses : [addresses];
+/**
+* The email as `intercept` sends it: to the `deliverTo` addresses it names, and
+* to `forwardTo` in their place or in bcc. Headers keep who it was for.
+*/
+const intercepted = (email, intercept) => {
+	if (!intercept.enabled) return email;
+	const forwardTo = listOf(intercept.forwardTo);
+	const deliverTo = (intercept.deliverTo ?? []).map((entry) => entry.toLowerCase());
+	const delivered = (address) => {
+		const lowered = address.toLowerCase();
+		return deliverTo.some((entry) => entry.startsWith("@") ? lowered.endsWith(entry) : lowered === entry);
+	};
+	const to = listOf(email.to).filter(delivered);
+	const cc = listOf(email.cc).filter(delivered);
+	const bcc = listOf(email.bcc).filter(delivered);
+	const originals = {
+		"X-Intercepted-To": listOf(email.to),
+		"X-Intercepted-Cc": listOf(email.cc),
+		"X-Intercepted-Bcc": listOf(email.bcc)
+	};
+	const headers = {
+		...email.headers,
+		...Object.fromEntries(Object.entries(originals).filter(([, addresses]) => addresses.length > 0).map(([name, addresses]) => [name, addresses.join(", ")]))
+	};
+	return {
+		...email,
+		to: to.length > 0 ? to : forwardTo,
+		cc,
+		bcc: to.length > 0 ? [...bcc, ...forwardTo] : bcc,
+		subject: intercept.subjectPrefix === void 0 ? email.subject : `${intercept.subjectPrefix} ${email.subject}`,
+		headers
+	};
+};
+/**
+* What handlers reach at `plugins.resend`.
+*/
+const resendExports = (resend, options) => {
+	const listNamed = (name) => {
+		const list = options.lists?.[name];
+		if (list === void 0) throw new Error(`[kizuna/resend] No list is named '${name}'. Declare it under \`lists\`.`);
+		return list;
+	};
+	return {
+		/**
+		* The Resend client, for anything the plugin doesn't cover.
+		*/
+		client: resend,
+		/**
+		* Send one email.
+		*/
+		sendEmail: (email) => {
+			const addressed = options.intercept === void 0 ? email : intercepted(email, options.intercept);
+			return call("Sending the email", () => resend.emails.send({
+				from: options.from,
+				...addressed
+			}));
+		},
+		/**
+		* Add a contact to a list, creating the contact when it's new.
+		*/
+		subscribe: async ({ email, list: name, firstName, lastName }) => {
+			const list = listNamed(name);
+			const topics = list.topicId === void 0 ? [] : [{
+				id: list.topicId,
+				subscription: "opt_in"
+			}];
+			const found = await resend.contacts.get({ email });
+			if (found.error?.name === "not_found") return { contactId: (await call("Creating the contact", () => resend.contacts.create({
+				email,
+				firstName,
+				lastName,
+				segments: [{ id: list.segmentId }],
+				topics
+			}))).id };
+			if (found.error !== null) throw new ResendRequestError("Looking up the contact", found.error);
+			await call("Updating the contact", () => resend.contacts.update({
+				email,
+				unsubscribed: false,
+				firstName,
+				lastName
+			}));
+			await call("Adding the contact to the segment", () => resend.contacts.segments.add({
+				email,
+				segmentId: list.segmentId
+			}));
+			if (topics.length > 0) await call("Opting the contact in to the topic", () => resend.contacts.topics.update({
+				email,
+				topics
+			}));
+			return { contactId: found.data.id };
+		},
+		/**
+		* Move a contact to a new address, keeping its name, its lists and its
+		* topics. Resend can't change a contact's email, so this creates the new
+		* contact and removes the old one.
+		*/
+		changeEmail: async ({ from, to }) => {
+			const contact = await call("Looking up the contact", () => resend.contacts.get({ email: from }));
+			const segments = await everyPage("Listing the contact segments", (after) => resend.contacts.segments.list({
+				email: from,
+				limit: 100,
+				...after === void 0 ? {} : { after }
+			}));
+			const topics = await everyPage("Listing the contact topics", (after) => resend.contacts.topics.list({
+				email: from,
+				limit: 100,
+				...after === void 0 ? {} : { after }
+			}));
+			const created = await call("Creating the contact", () => resend.contacts.create({
+				email: to,
+				firstName: contact.first_name ?? void 0,
+				lastName: contact.last_name ?? void 0,
+				unsubscribed: contact.unsubscribed,
+				segments: segments.map((segment) => ({ id: segment.id })),
+				topics: topics.map((topic) => ({
+					id: topic.id,
+					subscription: topic.subscription
+				}))
+			}));
+			await call("Removing the old contact", () => resend.contacts.remove({ email: from }));
+			return { contactId: created.id };
+		},
+		/**
+		* Take a contact off one list, or off everything.
+		*/
+		unsubscribe: async ({ email, list: name }) => {
+			if (name === void 0) {
+				await call("Unsubscribing the contact", () => resend.contacts.update({
+					email,
+					unsubscribed: true
+				}));
+				return;
+			}
+			const { segmentId, topicId } = listNamed(name);
+			if (topicId === void 0) {
+				await call("Removing the contact from the segment", () => resend.contacts.segments.remove({
+					email,
+					segmentId
+				}));
+				return;
+			}
+			await call("Opting the contact out of the topic", () => resend.contacts.topics.update({
+				email,
+				topics: [{
+					id: topicId,
+					subscription: "opt_out"
+				}]
+			}));
+		},
+		/**
+		* Send a broadcast to a list, now or at `scheduledAt`.
+		*/
+		sendBroadcast: ({ list: name, from, scheduledAt, ...content }) => {
+			const list = listNamed(name);
+			return call("Sending the broadcast", () => resend.broadcasts.create({
+				...content,
+				from: from ?? options.from,
+				segmentId: list.segmentId,
+				topicId: list.topicId,
+				send: true,
+				scheduledAt
+			}));
+		}
+	};
+};
+//#endregion
+//#region src/webhooks.ts
+/**
+* The webhook event functions, with `jobs` and `plugins` typed from `Config`.
+*
+* @example
+* export const resendEvents = defineResendEvents<Config>({
+*     'email.bounced': async ({ event, jobs }) => {
+*         await jobs.users.markUndeliverable.queue({
+*             input: {
+*                 email: event.data.to[0],
+*             },
+*         });
+*     },
+* });
+*/
+const defineResendEvents = (handlers) => handlers;
+/**
+* Checks each delivery's signature, then runs the function for its event.
+*/
+const webhookRoute = (resend, webhookSecret, on) => (0, kizunajs_plugin.route)({
+	method: "POST",
+	path: "/webhooks",
+	auth: false,
+	rawBody: true,
+	summary: "Receive Resend webhook events",
+	headers: zod.z.object({
+		"svix-id": zod.z.string(),
+		"svix-timestamp": zod.z.string(),
+		"svix-signature": zod.z.string()
+	}),
+	body: zod.z.unknown(),
+	responses: {
+		204: zod.z.void(),
+		400: kizunajs_schemas.ProblemDetailsSchema
+	}
+}).handler(async (args) => {
+	const { rawBody, headers, throwError } = args;
+	let event;
+	try {
+		event = resend.webhooks.verify({
+			payload: rawBody,
+			headers: {
+				id: headers["svix-id"],
+				timestamp: headers["svix-timestamp"],
+				signature: headers["svix-signature"]
+			},
+			webhookSecret
+		});
+	} catch {
+		return throwError({
+			status: 400,
+			body: { detail: "The webhook signature doesn't match its body." }
+		});
+	}
+	const handle = on[event.type];
+	const { jobs, plugins } = args;
+	await handle?.({
+		event,
+		deliveryId: headers["svix-id"],
+		jobs,
+		plugins
+	});
+	return {
+		status: 204,
+		body: void 0
+	};
+});
+//#endregion
+//#region src/plugin.ts
+/**
+* Send email, run newsletters and broadcasts, and receive webhooks through
+* Resend. Handlers reach it at `plugins.resend`.
+*
+* @example
+* ```ts
+* export default defineConfig({
+*     routes,
+*     plugins: [
+*         resendPlugin({
+*             apiKey: process.env.RESEND_API_KEY,
+*             from: 'Kizuna <hello@example.com>',
+*         }),
+*     ],
+* });
+* ```
+*/
+const resendPlugin = (0, kizunajs_plugin.definePlugin)({
+	slug: "resend",
+	basePath: "/resend",
+	options: ResendPluginOptionsSchema,
+	setup: ({ options }) => {
+		const resend$1 = new resend.Resend(options.apiKey, options.resend);
+		const routes = {};
+		if (options.webhookSecret !== void 0) routes.webhook = webhookRoute(resend$1, options.webhookSecret, options.on ?? {});
+		return {
+			exports: resendExports(resend$1, options),
+			routes
+		};
+	}
+});
+//#endregion
+exports.ResendListSchema = ResendListSchema;
+exports.ResendPluginOptionsSchema = ResendPluginOptionsSchema;
+exports.ResendRequestError = ResendRequestError;
+exports.defineResendEvents = defineResendEvents;
+exports.resendPlugin = resendPlugin;