@kizunajs/resend 2.0.0-beta.12

package/dist/index.mjs

@@ -0,0 +1,429 @@
+import { Resend } from "resend";
+import { definePlugin, route } from "kizunajs/plugin";
+import { z } from "zod";
+import { ProblemDetailsSchema } from "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 = z.object({
+	/**
+	* The segment the list's contacts are added to, and broadcasts go to.
+	*/
+	segmentId: z.string(),
+	/**
+	* The topic a contact opts in and out of, so unsubscribing from one list
+	* leaves the others alone.
+	*/
+	topicId: z.string().optional()
+});
+/**
+* The loosest of Zod's email patterns, so the plugin never refuses an address
+* Resend would accept.
+*/
+const EmailSchema = z.email({ pattern: 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 = z.string().refine(isSender, { error: "must be an address, or a name and an address like `Kizuna <hello@example.com>`" });
+const ResendPluginOptionsSchema = z.object({
+	/**
+	* The Resend API key.
+	*/
+	apiKey: 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: z.record(z.string(), ResendListSchema).optional(),
+	/**
+	* The webhook's signing secret. The webhook route is served when it's set.
+	*/
+	webhookSecret: z.string().optional(),
+	/**
+	* What runs for each webhook event, keyed by its type.
+	*/
+	on: 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: z.object({
+		/**
+		* Whether emails are intercepted.
+		*/
+		enabled: z.boolean(),
+		/**
+		* Where every email is forwarded, one address or several.
+		* Required when `enabled` is true.
+		*/
+		forwardTo: z.union([EmailSchema, z.array(EmailSchema).min(1)]).optional(),
+		/**
+		* Addresses, or whole domains like `@example.com`, whose emails are
+		* delivered as normal, with `forwardTo` in bcc.
+		*/
+		deliverTo: z.array(z.string()).optional(),
+		/**
+		* Put in front of every intercepted email's subject.
+		*
+		* @example
+		* subjectPrefix: '[dev]',
+		*/
+		subjectPrefix: 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: 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) => route({
+	method: "POST",
+	path: "/webhooks",
+	auth: false,
+	rawBody: true,
+	summary: "Receive Resend webhook events",
+	headers: z.object({
+		"svix-id": z.string(),
+		"svix-timestamp": z.string(),
+		"svix-signature": z.string()
+	}),
+	body: z.unknown(),
+	responses: {
+		204: z.void(),
+		400: 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 = definePlugin({
+	slug: "resend",
+	basePath: "/resend",
+	options: ResendPluginOptionsSchema,
+	setup: ({ options }) => {
+		const resend = new Resend(options.apiKey, options.resend);
+		const routes = {};
+		if (options.webhookSecret !== void 0) routes.webhook = webhookRoute(resend, options.webhookSecret, options.on ?? {});
+		return {
+			exports: resendExports(resend, options),
+			routes
+		};
+	}
+});
+//#endregion
+export { ResendListSchema, ResendPluginOptionsSchema, ResendRequestError, defineResendEvents, resendPlugin };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@kizunajs/resend",
+  "version": "2.0.0-beta.12",
+  "description": "Resend plugin for Kizuna.js: send email, run newsletters and broadcasts, and receive webhooks",
+  "keywords": [
+    "kizunajs",
+    "typescript",
+    "zod",
+    "openapi",
+    "spec-driven",
+    "type-safe",
+    "rest",
+    "api",
+    "resend",
+    "email",
+    "newsletter",
+    "webhooks"
+  ],
+  "license": "MIT",
+  "homepage": "https://kizunajs.com/docs/resend",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kizunajs/kizuna.git",
+    "directory": "packages/resend"
+  },
+  "bugs": "https://github.com/kizunajs/kizuna/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "kizuna": {
+    "entries": {
+      ".": "server"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "resend": "^6.18.0",
+    "zod": "^4.0.0",
+    "kizunajs": "2.0.0-beta.12"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "express": "^5.0.0",
+    "resend": "^6.30.0",
+    "tsdown": "^0.21.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.0.0",
+    "@kizunajs/express": "2.0.0-beta.12",
+    "kizunajs": "2.0.0-beta.12"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm,cjs --dts --clean --external kizunajs --external zod --external resend",
+    "typecheck": "tsc --noEmit"
+  }
+}