@keystrokehq/resend 0.0.1

package/dist/topics.mjs

@@ -0,0 +1,113 @@
+import { createResendClient } from "./client.mjs";
+import { paginationQuerySchema, resendListEnvelope } from "./schemas.mjs";
+import { t as resendOperation } from "./factory-B3VyPRsL.mjs";
+import { z } from "zod";
+
+//#region src/topics.ts
+/**
+* resend/topics.ts
+*
+* Operations backing the Resend `/topics` endpoints.
+* PLAN.md § 6.9: 5 operations.
+*
+* Topics model recipient subscription preferences. A broadcast sent
+* with `topic_id` honours each recipient's opt-in/opt-out state.
+*/
+const topicDefaultSubscriptionSchema = z.enum(["opt_in", "opt_out"]);
+const topicSchema = z.object({
+	id: z.string(),
+	name: z.string().optional(),
+	description: z.string().optional().nullable(),
+	default_subscription: topicDefaultSubscriptionSchema.optional(),
+	created_at: z.string().optional(),
+	updated_at: z.string().optional()
+}).passthrough();
+const listTopicsResponseSchema = resendListEnvelope(topicSchema);
+const createTopic = resendOperation({
+	id: "create_resend_topic",
+	name: "Create Resend Topic",
+	description: "Create a new subscription topic.",
+	input: z.object({
+		name: z.string().min(1),
+		default_subscription: topicDefaultSubscriptionSchema,
+		description: z.string().optional()
+	}),
+	output: topicSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		return createResendClient(credentials).request({
+			method: "POST",
+			path: "/topics",
+			body: input
+		});
+	}
+});
+const listTopics = resendOperation({
+	id: "list_resend_topics",
+	name: "List Resend Topics",
+	description: "Retrieve a cursor-paginated list of topics.",
+	input: paginationQuerySchema,
+	output: listTopicsResponseSchema,
+	run: async (input, credentials) => {
+		return createResendClient(credentials).request({
+			method: "GET",
+			path: "/topics",
+			query: input
+		});
+	}
+});
+const retrieveTopic = resendOperation({
+	id: "retrieve_resend_topic",
+	name: "Retrieve Resend Topic",
+	description: "Retrieve a single topic by id.",
+	input: z.object({ id: z.string().min(1) }),
+	output: topicSchema,
+	run: async (input, credentials) => {
+		return createResendClient(credentials).request({
+			method: "GET",
+			path: `/topics/${encodeURIComponent(input.id)}`
+		});
+	}
+});
+const updateTopic = resendOperation({
+	id: "update_resend_topic",
+	name: "Update Resend Topic",
+	description: "Update an existing topic.",
+	input: z.object({
+		id: z.string().min(1),
+		name: z.string().optional(),
+		description: z.string().optional(),
+		default_subscription: topicDefaultSubscriptionSchema.optional()
+	}),
+	output: topicSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const { id, ...body } = input;
+		return createResendClient(credentials).request({
+			method: "PATCH",
+			path: `/topics/${encodeURIComponent(id)}`,
+			body
+		});
+	}
+});
+const deleteTopic = resendOperation({
+	id: "delete_resend_topic",
+	name: "Delete Resend Topic",
+	description: "Delete a topic.",
+	input: z.object({ id: z.string().min(1) }),
+	output: z.object({
+		object: z.literal("topic").optional(),
+		id: z.string(),
+		deleted: z.boolean().optional()
+	}).passthrough(),
+	needsApproval: true,
+	run: async (input, credentials) => {
+		return createResendClient(credentials).request({
+			method: "DELETE",
+			path: `/topics/${encodeURIComponent(input.id)}`
+		});
+	}
+});
+
+//#endregion
+export { createTopic, deleteTopic, listTopics, retrieveTopic, updateTopic };

package/dist/triggers.d.mts

@@ -0,0 +1,68 @@
+import { n as resend, t as ResendCredentials } from "./integration-ClH0F7x-.mjs";
+import { ResendGenericWebhookEvent, ResendWebhookEventName } from "./events.mjs";
+import { IntegrationTriggerBindingOptions } from "@keystrokehq/integration-authoring";
+import { BoundTrigger, WebhookRequest } from "@keystrokehq/core";
+import { WebhookTriggerManifest } from "@keystrokehq/core/trigger";
+
+//#region src/triggers.d.ts
+type ResendTriggerCredentialSets = readonly [typeof resend];
+type ResendWebhookBoundTrigger<TOutput = ResendGenericWebhookEvent> = BoundTrigger<ResendGenericWebhookEvent, ResendTriggerCredentialSets, WebhookTriggerManifest, TOutput, WebhookRequest>;
+type ResendWebhookBindingOptions<TOutput = ResendGenericWebhookEvent> = IntegrationTriggerBindingOptions<ResendGenericWebhookEvent, TOutput, WebhookRequest>;
+type ResendWebhookBindingSurface = <TOutput = ResendGenericWebhookEvent>(options?: ResendWebhookBindingOptions<TOutput>) => ResendWebhookBoundTrigger<TOutput>;
+interface ResendTriggersNamespace {
+  readonly emailSent: ResendWebhookBindingSurface;
+  readonly emailDelivered: ResendWebhookBindingSurface;
+  readonly emailDeliveryDelayed: ResendWebhookBindingSurface;
+  readonly emailBounced: ResendWebhookBindingSurface;
+  readonly emailComplained: ResendWebhookBindingSurface;
+  /** MPP-opens are filtered by default; pass your own `filter` to opt in. */
+  readonly emailOpened: ResendWebhookBindingSurface;
+  readonly emailClicked: ResendWebhookBindingSurface;
+  readonly emailFailed: ResendWebhookBindingSurface;
+  readonly emailReceived: ResendWebhookBindingSurface;
+  readonly emailScheduled: ResendWebhookBindingSurface;
+  readonly emailSuppressed: ResendWebhookBindingSurface;
+  readonly domainCreated: ResendWebhookBindingSurface;
+  readonly domainUpdated: ResendWebhookBindingSurface;
+  readonly domainDeleted: ResendWebhookBindingSurface;
+  readonly contactCreated: ResendWebhookBindingSurface;
+  readonly contactUpdated: ResendWebhookBindingSurface;
+  readonly contactDeleted: ResendWebhookBindingSurface;
+}
+declare const triggers: ResendTriggersNamespace;
+/**
+ * Idempotently register (or update) a Resend webhook endpoint and
+ * return its id + signing secret. Workflows that bind triggers
+ * typically call this once to persist the `whsec_…` into the
+ * connection credentials before a trigger can verify inbound payloads.
+ *
+ * Behavior:
+ *
+ * 1. Look up existing webhooks via `GET /webhooks`.
+ * 2. If one already points to `endpointUrl`, reuse it. If its event
+ *    list drifted, `PATCH` to reconcile.
+ * 3. Otherwise `POST /webhooks` with the requested events.
+ * 4. Return `{ webhookId, signingSecret, endpointUrl, events }`.
+ *
+ * Does NOT mutate the vault. Callers are responsible for writing
+ * the returned `signingSecret` into
+ * `credentials.RESEND_WEBHOOK_SIGNING_SECRETS[webhookId]`.
+ */
+interface EnsureResendWebhookParams {
+  readonly credentials: ResendCredentials;
+  readonly endpointUrl: string;
+  /** Events to subscribe to. Pass `'all'` to subscribe to every event. */
+  readonly events: 'all' | readonly ResendWebhookEventName[];
+  readonly status?: 'enabled' | 'disabled';
+}
+interface EnsureResendWebhookResult {
+  readonly webhookId: string;
+  readonly signingSecret: string;
+  readonly endpointUrl: string;
+  readonly events: readonly ResendWebhookEventName[] | 'all';
+  readonly created: boolean;
+  readonly updated: boolean;
+}
+declare function ensureResendWebhook(params: EnsureResendWebhookParams): Promise<EnsureResendWebhookResult>;
+//#endregion
+export { EnsureResendWebhookParams, EnsureResendWebhookResult, ResendTriggersNamespace, ensureResendWebhook, triggers };

package/dist/triggers.mjs

@@ -0,0 +1,141 @@
+import { t as resend } from "./integration-BR1nTAnU.mjs";
+import { createResendClient } from "./client.mjs";
+import { RESEND_WEBHOOK_EVENT_NAMES, resendGenericWebhookEventSchema } from "./events.mjs";
+import { verifyResendWebhookRequest } from "./verification.mjs";
+import { createWebhookTriggerBindingFactory } from "@keystrokehq/integration-authoring";
+
+//#region src/triggers.ts
+function resolveSigningSecret(credentials) {
+	const map = credentials.RESEND_WEBHOOK_SIGNING_SECRETS;
+	if (map === void 0) return [];
+	return Object.values(map);
+}
+function idempotencyFromPayload(payload) {
+	const data = payload.data;
+	for (const key of ["email_id", "id"]) {
+		const value = data[key];
+		if (typeof value === "string" && value.length > 0) return `${payload.type}:${value}`;
+	}
+	return `${payload.type}:unknown`;
+}
+function isAppleMppOpen(payload) {
+	if (payload.type !== "email.opened") return false;
+	return payload.data.is_machine_opened === true;
+}
+function defaultDefinitionFilter(eventType) {
+	if (eventType === "email.opened") return (payload) => payload.type === eventType && !isAppleMppOpen(payload);
+	return (payload) => payload.type === eventType;
+}
+function buildBinding(eventType) {
+	return createWebhookTriggerBindingFactory({
+		defaultName: `Resend ${eventType}`,
+		defaultDescription: `Fires when Resend emits the ${eventType} webhook event.`,
+		path: "/resend",
+		method: "POST",
+		payload: resendGenericWebhookEventSchema,
+		credentialSets: [resend],
+		verify: (request, ctx) => {
+			const credentials = ctx.credentials.resend;
+			const secrets = resolveSigningSecret(credentials);
+			if (secrets.length === 0) throw new Error("Resend webhook signing secret is not configured. Populate `RESEND_WEBHOOK_SIGNING_SECRETS` on the connection (e.g. via `ensureResendWebhook`) before binding webhook triggers.");
+			for (const signingSecret of secrets) if (verifyResendWebhookRequest({
+				rawBody: request.rawBody,
+				headers: request.headers,
+				signingSecret
+			}).ok) return;
+			throw new Error("Invalid Resend webhook signature.");
+		},
+		definitionFilter: defaultDefinitionFilter(eventType),
+		idempotencyKey: (payload) => idempotencyFromPayload(payload),
+		response: { successStatus: 200 }
+	});
+}
+const bindingTable = Object.fromEntries(RESEND_WEBHOOK_EVENT_NAMES.map((eventName) => [eventName, buildBinding(eventName)]));
+function bind(eventType) {
+	return (options) => bindingTable[eventType](options);
+}
+const triggers = Object.freeze({
+	emailSent: bind("email.sent"),
+	emailDelivered: bind("email.delivered"),
+	emailDeliveryDelayed: bind("email.delivery_delayed"),
+	emailBounced: bind("email.bounced"),
+	emailComplained: bind("email.complained"),
+	emailOpened: bind("email.opened"),
+	emailClicked: bind("email.clicked"),
+	emailFailed: bind("email.failed"),
+	emailReceived: bind("email.received"),
+	emailScheduled: bind("email.scheduled"),
+	emailSuppressed: bind("email.suppressed"),
+	domainCreated: bind("domain.created"),
+	domainUpdated: bind("domain.updated"),
+	domainDeleted: bind("domain.deleted"),
+	contactCreated: bind("contact.created"),
+	contactUpdated: bind("contact.updated"),
+	contactDeleted: bind("contact.deleted")
+});
+async function ensureResendWebhook(params) {
+	const client = createResendClient(params.credentials);
+	const existing = (await client.request({
+		method: "GET",
+		path: "/webhooks"
+	})).data.find((w) => w.endpoint_url === params.endpointUrl);
+	if (existing) {
+		const existingEvents = new Set(existing.events ?? []);
+		const desiredEvents = params.events === "all" ? /* @__PURE__ */ new Set() : new Set(params.events);
+		const eventsChanged = params.events === "all" ? false : existingEvents.size !== desiredEvents.size || [...desiredEvents].some((e) => !existingEvents.has(e));
+		const statusChanged = params.status !== void 0 && existing.status !== params.status;
+		if (eventsChanged || statusChanged) {
+			const secret = (await client.request({
+				method: "PATCH",
+				path: `/webhooks/${encodeURIComponent(existing.id)}`,
+				body: {
+					...eventsChanged ? { events: params.events } : {},
+					...statusChanged ? { status: params.status } : {}
+				}
+			})).signing_secret ?? (await client.request({
+				method: "GET",
+				path: `/webhooks/${encodeURIComponent(existing.id)}`
+			})).signing_secret;
+			return {
+				webhookId: existing.id,
+				signingSecret: secret,
+				endpointUrl: params.endpointUrl,
+				events: params.events,
+				created: false,
+				updated: true
+			};
+		}
+		const refreshed = await client.request({
+			method: "GET",
+			path: `/webhooks/${encodeURIComponent(existing.id)}`
+		});
+		return {
+			webhookId: existing.id,
+			signingSecret: refreshed.signing_secret,
+			endpointUrl: params.endpointUrl,
+			events: params.events,
+			created: false,
+			updated: false
+		};
+	}
+	const created = await client.request({
+		method: "POST",
+		path: "/webhooks",
+		body: {
+			endpoint_url: params.endpointUrl,
+			events: params.events,
+			...params.status ? { status: params.status } : {}
+		}
+	});
+	return {
+		webhookId: created.id,
+		signingSecret: created.signing_secret,
+		endpointUrl: params.endpointUrl,
+		events: params.events,
+		created: true,
+		updated: false
+	};
+}
+
+//#endregion
+export { ensureResendWebhook, triggers };

package/dist/verification.d.mts

@@ -0,0 +1,49 @@
+import { WebhookRequest } from "@keystrokehq/core";
+
+//#region src/verification.d.ts
+declare const RESEND_SVIX_ID_HEADER = "svix-id";
+declare const RESEND_SVIX_TIMESTAMP_HEADER = "svix-timestamp";
+declare const RESEND_SVIX_SIGNATURE_HEADER = "svix-signature";
+/** Default replay window: 5 minutes either side of `now`. */
+declare const RESEND_DEFAULT_TIMESTAMP_TOLERANCE_SECONDS = 300;
+type ResendWebhookVerificationResult = {
+  readonly ok: true;
+  readonly svixId: string;
+  readonly svixTimestamp: number;
+} | {
+  readonly ok: false;
+  readonly reason: 'missing_headers' | 'bad_secret_format' | 'bad_timestamp' | 'stale_timestamp' | 'bad_signature';
+};
+interface VerifyResendWebhookOptions {
+  /** Raw, UTF-8 request body. Must be preserved byte-for-byte. */
+  readonly rawBody: string | Buffer;
+  /**
+   * Inbound request headers. Case-insensitive; values may be string
+   * or string[] (HTTP/2 / Node req.headers).
+   */
+  readonly headers: Headers | Record<string, string | string[] | undefined> | Pick<WebhookRequest, 'headers'>['headers'];
+  /** `whsec_<base64>` as returned by Resend. */
+  readonly signingSecret: string;
+  /** Max allowed age of the request in seconds. Defaults to 300. */
+  readonly toleranceSeconds?: number;
+  /** Override the clock for testing. Returns milliseconds since epoch. */
+  readonly now?: () => number;
+}
+/**
+ * Verify a Resend webhook request using Svix v1 signatures.
+ *
+ * Returns a structured result instead of a boolean so that callers
+ * (and tests) can differentiate replay-window failures from signature
+ * failures from bad configuration.
+ */
+declare function verifyResendWebhookRequest(options: VerifyResendWebhookOptions): ResendWebhookVerificationResult;
+/**
+ * Parse the raw (verified) webhook body as JSON.
+ *
+ * Returns `undefined` on parse failure. Callers are expected to run
+ * the result through `resendWebhookEventSchema.parse(...)` (from
+ * `./events`) to get a discriminated-union-typed event.
+ */
+declare function parseResendWebhookBody(rawBody: string | Buffer): unknown;
+//#endregion
+export { RESEND_DEFAULT_TIMESTAMP_TOLERANCE_SECONDS, RESEND_SVIX_ID_HEADER, RESEND_SVIX_SIGNATURE_HEADER, RESEND_SVIX_TIMESTAMP_HEADER, ResendWebhookVerificationResult, VerifyResendWebhookOptions, parseResendWebhookBody, verifyResendWebhookRequest };

package/dist/verification.mjs

@@ -0,0 +1,139 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+//#region src/verification.ts
+/**
+* resend/verification.ts
+*
+* Svix v1 webhook signature verification for Resend webhooks.
+*
+* Resend signs every webhook POST with Svix. Every request carries:
+*
+*   svix-id:        unique message id (also used as the idempotency key)
+*   svix-timestamp: unix-seconds send time
+*   svix-signature: space-separated list of `v1,<base64>` tokens
+*
+* The signing secret is per-endpoint and returned as `whsec_<base64>`
+* on `POST /webhooks` and `GET /webhooks/{id}`.
+*
+* Wire format (Svix v1):
+*
+*   signing_input   = `${svixId}.${svixTimestamp}.${rawBody}`
+*   hmac_key_bytes  = base64_decode(secret.slice('whsec_'.length))
+*   expected_token  = `v1,${base64(HMAC_SHA256(hmac_key_bytes, signing_input))}`
+*
+* A request is valid when at least one `v1,*` token in
+* `svix-signature` matches `expected_token`, verified with a
+* constant-time comparison, and `svix-timestamp` is within the
+* configurable tolerance (default: 300 s) of the current time.
+*
+* Why hand-rolled:
+*
+* - Runtime: no `svix` npm dependency, keeping the bundle
+*   edge-friendly. See `IMPLEMENTATION_NOTES.md` § 3.
+* - The shared `verifyHmacWebhook` helper in
+*   `@keystrokehq/integration-authoring/webhooks` digests as hex + strips a prefix;
+*   Svix uses base64, multiple tokens, and a base64-decoded secret, so
+*   we need a Svix-specific path.
+*/
+const RESEND_SVIX_ID_HEADER = "svix-id";
+const RESEND_SVIX_TIMESTAMP_HEADER = "svix-timestamp";
+const RESEND_SVIX_SIGNATURE_HEADER = "svix-signature";
+/** Secrets Resend returns on webhook create/retrieve. Always `whsec_<base64>`. */
+const WEBHOOK_SECRET_PREFIX = "whsec_";
+/** Default replay window: 5 minutes either side of `now`. */
+const RESEND_DEFAULT_TIMESTAMP_TOLERANCE_SECONDS = 300;
+function getHeader(headers, name) {
+	if (headers === void 0) return void 0;
+	if (typeof Headers !== "undefined" && headers instanceof Headers) return headers.get(name) ?? void 0;
+	const lower = name.toLowerCase();
+	for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === lower) {
+		if (Array.isArray(value)) return value[0];
+		return value ?? void 0;
+	}
+}
+/**
+* Verify a Resend webhook request using Svix v1 signatures.
+*
+* Returns a structured result instead of a boolean so that callers
+* (and tests) can differentiate replay-window failures from signature
+* failures from bad configuration.
+*/
+function verifyResendWebhookRequest(options) {
+	const svixId = getHeader(options.headers, RESEND_SVIX_ID_HEADER);
+	const svixTimestampRaw = getHeader(options.headers, RESEND_SVIX_TIMESTAMP_HEADER);
+	const svixSignature = getHeader(options.headers, RESEND_SVIX_SIGNATURE_HEADER);
+	if (!svixId || !svixTimestampRaw || !svixSignature) return {
+		ok: false,
+		reason: "missing_headers"
+	};
+	if (!options.signingSecret.startsWith(WEBHOOK_SECRET_PREFIX)) return {
+		ok: false,
+		reason: "bad_secret_format"
+	};
+	const svixTimestamp = Number(svixTimestampRaw);
+	if (!Number.isFinite(svixTimestamp) || !Number.isInteger(svixTimestamp)) return {
+		ok: false,
+		reason: "bad_timestamp"
+	};
+	const nowSeconds = Math.floor((options.now?.() ?? Date.now()) / 1e3);
+	const tolerance = options.toleranceSeconds ?? RESEND_DEFAULT_TIMESTAMP_TOLERANCE_SECONDS;
+	if (Math.abs(nowSeconds - svixTimestamp) > tolerance) return {
+		ok: false,
+		reason: "stale_timestamp"
+	};
+	let secretBytes;
+	try {
+		secretBytes = Buffer.from(options.signingSecret.slice(6), "base64");
+		if (secretBytes.length === 0) return {
+			ok: false,
+			reason: "bad_secret_format"
+		};
+	} catch {
+		return {
+			ok: false,
+			reason: "bad_secret_format"
+		};
+	}
+	const signingInput = `${svixId}.${svixTimestamp}.${typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8")}`;
+	const expected = createHmac("sha256", secretBytes).update(signingInput).digest();
+	const expectedBuffer = Buffer.from(expected);
+	const tokens = svixSignature.split(" ");
+	for (const token of tokens) {
+		if (!token.startsWith("v1,")) continue;
+		const candidate = token.slice(3);
+		let candidateBytes;
+		try {
+			candidateBytes = Buffer.from(candidate, "base64");
+		} catch {
+			continue;
+		}
+		if (candidateBytes.length !== expectedBuffer.length) continue;
+		if (timingSafeEqual(candidateBytes, expectedBuffer)) return {
+			ok: true,
+			svixId,
+			svixTimestamp
+		};
+	}
+	return {
+		ok: false,
+		reason: "bad_signature"
+	};
+}
+/**
+* Parse the raw (verified) webhook body as JSON.
+*
+* Returns `undefined` on parse failure. Callers are expected to run
+* the result through `resendWebhookEventSchema.parse(...)` (from
+* `./events`) to get a discriminated-union-typed event.
+*/
+function parseResendWebhookBody(rawBody) {
+	const text = typeof rawBody === "string" ? rawBody : rawBody.toString("utf8");
+	try {
+		return JSON.parse(text);
+	} catch {
+		return;
+	}
+}
+
+//#endregion
+export { RESEND_DEFAULT_TIMESTAMP_TOLERANCE_SECONDS, RESEND_SVIX_ID_HEADER, RESEND_SVIX_SIGNATURE_HEADER, RESEND_SVIX_TIMESTAMP_HEADER, parseResendWebhookBody, verifyResendWebhookRequest };