npm - @c9up/rover - Versions diffs - 0.1.3 - Mend

@c9up/rover 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/LICENSE +21 -0
package/README.md +91 -0
package/dist/BaseMail.d.ts +28 -0
package/dist/BaseMail.d.ts.map +1 -0
package/dist/BaseMail.js +42 -0
package/dist/BaseMail.js.map +1 -0
package/dist/Mail.d.ts +166 -0
package/dist/Mail.d.ts.map +1 -0
package/dist/Mail.js +451 -0
package/dist/Mail.js.map +1 -0
package/dist/MessageBuilder.d.ts +38 -0
package/dist/MessageBuilder.d.ts.map +1 -0
package/dist/MessageBuilder.js +70 -0
package/dist/MessageBuilder.js.map +1 -0
package/dist/RoverError.d.ts +30 -0
package/dist/RoverError.d.ts.map +1 -0
package/dist/RoverError.js +33 -0
package/dist/RoverError.js.map +1 -0
package/dist/RoverProvider.d.ts +24 -0
package/dist/RoverProvider.d.ts.map +1 -0
package/dist/RoverProvider.js +51 -0
package/dist/RoverProvider.js.map +1 -0
package/dist/config.d.ts +4 -0
package/dist/config.d.ts.map +1 -0
package/dist/config.js +4 -0
package/dist/config.js.map +1 -0
package/dist/index.d.ts +9 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +7 -0
package/dist/index.js.map +1 -0
package/dist/queue/MailJob.d.ts +41 -0
package/dist/queue/MailJob.d.ts.map +1 -0
package/dist/queue/MailJob.js +75 -0
package/dist/queue/MailJob.js.map +1 -0
package/dist/retry.d.ts +20 -0
package/dist/retry.d.ts.map +1 -0
package/dist/retry.js +101 -0
package/dist/retry.js.map +1 -0
package/dist/services/main.d.ts +20 -0
package/dist/services/main.d.ts.map +1 -0
package/dist/services/main.js +33 -0
package/dist/services/main.js.map +1 -0
package/dist/templating/SimpleTemplate.d.ts +7 -0
package/dist/templating/SimpleTemplate.d.ts.map +1 -0
package/dist/templating/SimpleTemplate.js +192 -0
package/dist/templating/SimpleTemplate.js.map +1 -0
package/dist/templating/loadNapi.d.ts +21 -0
package/dist/templating/loadNapi.d.ts.map +1 -0
package/dist/templating/loadNapi.js +115 -0
package/dist/templating/loadNapi.js.map +1 -0
package/dist/testing/FakeMail.d.ts +31 -0
package/dist/testing/FakeMail.d.ts.map +1 -0
package/dist/testing/FakeMail.js +90 -0
package/dist/testing/FakeMail.js.map +1 -0
package/dist/transports/MailgunTransport.d.ts +7 -0
package/dist/transports/MailgunTransport.d.ts.map +1 -0
package/dist/transports/MailgunTransport.js +149 -0
package/dist/transports/MailgunTransport.js.map +1 -0
package/dist/transports/ResendTransport.d.ts +7 -0
package/dist/transports/ResendTransport.d.ts.map +1 -0
package/dist/transports/ResendTransport.js +111 -0
package/dist/transports/ResendTransport.js.map +1 -0
package/dist/transports/SendGridTransport.d.ts +7 -0
package/dist/transports/SendGridTransport.d.ts.map +1 -0
package/dist/transports/SendGridTransport.js +165 -0
package/dist/transports/SendGridTransport.js.map +1 -0
package/dist/transports/SesTransport.d.ts +7 -0
package/dist/transports/SesTransport.d.ts.map +1 -0
package/dist/transports/SesTransport.js +334 -0
package/dist/transports/SesTransport.js.map +1 -0
package/dist/transports/fetchError.d.ts +13 -0
package/dist/transports/fetchError.d.ts.map +1 -0
package/dist/transports/fetchError.js +35 -0
package/dist/transports/fetchError.js.map +1 -0
package/dist/webhooks/context.d.ts +35 -0
package/dist/webhooks/context.d.ts.map +1 -0
package/dist/webhooks/context.js +7 -0
package/dist/webhooks/context.js.map +1 -0
package/dist/webhooks/mailgun.d.ts +13 -0
package/dist/webhooks/mailgun.d.ts.map +1 -0
package/dist/webhooks/mailgun.js +102 -0
package/dist/webhooks/mailgun.js.map +1 -0
package/dist/webhooks/resend.d.ts +16 -0
package/dist/webhooks/resend.d.ts.map +1 -0
package/dist/webhooks/resend.js +121 -0
package/dist/webhooks/resend.js.map +1 -0
package/dist/webhooks/sendgrid.d.ts +13 -0
package/dist/webhooks/sendgrid.d.ts.map +1 -0
package/dist/webhooks/sendgrid.js +104 -0
package/dist/webhooks/sendgrid.js.map +1 -0
package/index.darwin-arm64.node +0 -0
package/index.darwin-x64.node +0 -0
package/index.linux-arm64-gnu.node +0 -0
package/index.linux-x64-gnu.node +0 -0
package/index.win32-x64-msvc.node +0 -0
package/package.json +97 -0
package/scripts/copy-napi.mjs +62 -0
package/src/BaseMail.ts +52 -0
package/src/Mail.ts +663 -0
package/src/MessageBuilder.ts +101 -0
package/src/RoverError.ts +44 -0
package/src/RoverProvider.ts +72 -0
package/src/config.ts +7 -0
package/src/index.ts +30 -0
package/src/queue/MailJob.ts +131 -0
package/src/retry.ts +135 -0
package/src/services/main.ts +41 -0
package/src/templating/SimpleTemplate.ts +240 -0
package/src/templating/loadNapi.ts +169 -0
package/src/testing/FakeMail.ts +112 -0
package/src/transports/MailgunTransport.ts +204 -0
package/src/transports/ResendTransport.ts +147 -0
package/src/transports/SendGridTransport.ts +246 -0
package/src/transports/SesTransport.ts +394 -0
package/src/transports/fetchError.ts +42 -0
package/src/webhooks/context.ts +41 -0
package/src/webhooks/mailgun.ts +134 -0
package/src/webhooks/resend.ts +164 -0
package/src/webhooks/sendgrid.ts +133 -0

package/src/webhooks/resend.ts ADDED Viewed

@@ -0,0 +1,164 @@
+import { Buffer } from "node:buffer";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type {
+	WebhookEmitter,
+	WebhookHttpContext,
+	WebhookMiddleware,
+} from "./context.js";
+export interface ResendWebhookOptions {
+	/**
+	 * Webhook signing secret from the Resend dashboard. Supports the full
+	 * `whsec_...` prefix or a raw base64-encoded key.
+	 */
+	secret: string;
+	emitter: WebhookEmitter;
+	/**
+	 * Maximum age in seconds for a signed payload (default 300 = 5 minutes).
+	 * Set to `Number.POSITIVE_INFINITY` to disable (not recommended).
+	 */
+	maxAgeSeconds?: number;
+}
+/**
+ * Parse a provider-supplied `created_at` into an epoch-ms timestamp,
+ * falling back to "now" for anything unparseable. Without the
+ * `Number.isFinite` guard, a malformed value like `"not-a-date"`
+ * yields `new Date(...).getTime()` === `NaN`, which then leaks into
+ * the `mail.*` event payload and breaks any consumer that sorts,
+ * persists, or numerically compares the timestamp.
+ */
+function parseTimestamp(raw: string | undefined): number {
+	if (raw !== undefined && raw !== "") {
+		const t = new Date(raw).getTime();
+		if (Number.isFinite(t)) return t;
+	}
+	return Date.now();
+}
+interface ResendPayload {
+	type?: string;
+	data?: {
+		email_id?: string;
+		to?: string | string[];
+		reason?: string;
+		created_at?: string;
+	};
+}
+/**
+ * Resend event → Rover event. Only map events that correspond to durable,
+ * decision-grade outcomes. `email.delivery_delayed` is intermediate (not a
+ * final failure) and `email.complained` is a deliverability signal (not a
+ * delivery failure) — both are dropped to keep the event bus signal-dense.
+ */
+const EVENT_MAP: Record<string, string> = {
+	"email.delivered": "mail.delivered",
+	"email.bounced": "mail.bounced",
+};
+export function createResendWebhookHandler(
+	options: ResendWebhookOptions,
+): WebhookMiddleware {
+	if (!options.secret) {
+		throw new Error(
+			"createResendWebhookHandler: secret is required for HMAC verification.",
+		);
+	}
+	const secretRaw = options.secret.startsWith("whsec_")
+		? options.secret.slice(6)
+		: options.secret;
+	const keyBytes = Buffer.from(secretRaw, "base64");
+	const emitter = options.emitter;
+	const maxAgeSeconds = options.maxAgeSeconds ?? 300;
+	return async (ctx: WebhookHttpContext, _next): Promise<void> => {
+		const raw = await Promise.resolve(ctx.request.rawBody());
+		const id = ctx.request.header("svix-id");
+		const timestamp = ctx.request.header("svix-timestamp");
+		const signatureHeader = ctx.request.header("svix-signature");
+		if (!id || !timestamp || !signatureHeader) {
+			ctx.response.status(401).json({ error: "missing_signature" });
+			return;
+		}
+		const tsSeconds = Number(timestamp);
+		if (!Number.isFinite(tsSeconds)) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		const nowSeconds = Date.now() / 1000;
+		if (Math.abs(nowSeconds - tsSeconds) > maxAgeSeconds) {
+			ctx.response.status(401).json({ error: "stale_signature" });
+			return;
+		}
+		if (!verifySvixSignature(raw, id, timestamp, signatureHeader, keyBytes)) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		let payload: ResendPayload;
+		try {
+			payload = JSON.parse(raw.toString("utf8")) as ResendPayload;
+		} catch {
+			ctx.response.status(400).json({ error: "invalid_json" });
+			return;
+		}
+		emitMappedEvent(emitter, payload);
+		ctx.response.status(200).json({ ok: true });
+	};
+}
+/**
+ * Verify a Svix signature header. Svix signs `<id>.<timestamp>.<body>` and emits
+ * a space-separated list of `v1,<base64sig>` candidates — accept if any matches
+ * (constant-time compare).
+ */
+function verifySvixSignature(
+	raw: Buffer,
+	id: string,
+	timestamp: string,
+	signatureHeader: string,
+	keyBytes: Buffer,
+): boolean {
+	const toSign = Buffer.concat([
+		Buffer.from(`${id}.${timestamp}.`, "utf8"),
+		raw,
+	]);
+	const expected = createHmac("sha256", keyBytes)
+		.update(toSign)
+		.digest("base64");
+	for (const part of signatureHeader.split(" ")) {
+		const [scheme, sig] = part.split(",");
+		if (scheme !== "v1" || !sig) continue;
+		const sigBuf = Buffer.from(sig, "base64");
+		const expBuf = Buffer.from(expected, "base64");
+		if (sigBuf.length !== expBuf.length) continue;
+		if (timingSafeEqual(sigBuf, expBuf)) return true;
+	}
+	return false;
+}
+/** Map a Resend payload to a mail event and emit it; emitter throws are swallowed. */
+function emitMappedEvent(
+	emitter: WebhookEmitter,
+	payload: ResendPayload,
+): void {
+	const mapped = payload.type ? EVENT_MAP[payload.type] : undefined;
+	if (!mapped) return;
+	const to = Array.isArray(payload.data?.to)
+		? (payload.data.to[0] ?? "")
+		: (payload.data?.to ?? "");
+	try {
+		emitter.emit(mapped, {
+			messageId: payload.data?.email_id ?? "",
+			to,
+			reason: payload.data?.reason,
+			timestamp: parseTimestamp(payload.data?.created_at),
+		});
+	} catch {
+		// Emitter failures must not flip the webhook response; providers will
+		// replay on non-2xx and flood the bus.
+	}
+}

package/src/webhooks/sendgrid.ts ADDED Viewed

@@ -0,0 +1,133 @@
+import { Buffer } from "node:buffer";
+import { createPublicKey, verify } from "node:crypto";
+import type {
+	WebhookEmitter,
+	WebhookHttpContext,
+	WebhookMiddleware,
+} from "./context.js";
+export interface SendGridWebhookOptions {
+	/** Base64-DER or PEM-encoded Ed25519 public key, as shown in the SendGrid dashboard. */
+	publicKey: string;
+	emitter: WebhookEmitter;
+	/**
+	 * Maximum age in seconds for a signed payload (default 300 = 5 minutes).
+	 * Set to `Number.POSITIVE_INFINITY` to disable (not recommended).
+	 */
+	maxAgeSeconds?: number;
+}
+interface SendGridEvent {
+	event?: string;
+	email?: string;
+	sg_message_id?: string;
+	reason?: string;
+	timestamp?: number;
+}
+const EVENT_MAP: Record<string, string> = {
+	delivered: "mail.delivered",
+	bounce: "mail.bounced",
+	dropped: "mail.failed",
+	deferred: "mail.failed",
+	blocked: "mail.failed",
+};
+export function createSendGridWebhookHandler(
+	options: SendGridWebhookOptions,
+): WebhookMiddleware {
+	if (!options.publicKey) {
+		throw new Error(
+			"createSendGridWebhookHandler: publicKey is required for Ed25519 verification.",
+		);
+	}
+	const pemKey = toPem(options.publicKey);
+	const key = createPublicKey(pemKey);
+	const emitter = options.emitter;
+	const maxAgeSeconds = options.maxAgeSeconds ?? 300;
+	return async (ctx: WebhookHttpContext, _next): Promise<void> => {
+		const raw = await Promise.resolve(ctx.request.rawBody());
+		const signature = ctx.request.header(
+			"x-twilio-email-event-webhook-signature",
+		);
+		const timestamp = ctx.request.header(
+			"x-twilio-email-event-webhook-timestamp",
+		);
+		if (!signature || !timestamp) {
+			ctx.response.status(401).json({ error: "missing_signature" });
+			return;
+		}
+		const tsSeconds = Number(timestamp);
+		if (!Number.isFinite(tsSeconds)) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		const nowSeconds = Date.now() / 1000;
+		if (Math.abs(nowSeconds - tsSeconds) > maxAgeSeconds) {
+			ctx.response.status(401).json({ error: "stale_signature" });
+			return;
+		}
+		const payloadToVerify = Buffer.concat([
+			Buffer.from(timestamp, "utf8"),
+			raw,
+		]);
+		let sigBytes: Buffer;
+		try {
+			sigBytes = Buffer.from(signature, "base64");
+		} catch {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		const ok = verify(null, payloadToVerify, key, sigBytes);
+		if (!ok) {
+			ctx.response.status(401).json({ error: "invalid_signature" });
+			return;
+		}
+		let events: SendGridEvent[];
+		try {
+			events = JSON.parse(raw.toString("utf8")) as SendGridEvent[];
+		} catch {
+			ctx.response.status(400).json({ error: "invalid_json" });
+			return;
+		}
+		if (!Array.isArray(events)) {
+			ctx.response.status(400).json({ error: "expected_event_array" });
+			return;
+		}
+		for (const ev of events) {
+			if (!ev.event) continue;
+			const mapped = EVENT_MAP[ev.event];
+			if (!mapped) continue;
+			try {
+				emitter.emit(mapped, {
+					messageId: ev.sg_message_id ?? "",
+					to: ev.email ?? "",
+					reason: ev.reason,
+					timestamp: normaliseTimestamp(ev.timestamp),
+				});
+			} catch {
+				// Never let emitter failures flip the webhook response.
+			}
+		}
+		ctx.response.status(200).json({ ok: true });
+	};
+}
+function toPem(key: string): string {
+	const normalised = key.replace(/\r\n/g, "\n");
+	if (normalised.includes("BEGIN PUBLIC KEY")) return normalised;
+	const der = normalised.replace(/\s/g, "");
+	return `-----BEGIN PUBLIC KEY-----\n${der}\n-----END PUBLIC KEY-----`;
+}
+function normaliseTimestamp(ts: number | undefined): number {
+	// Guard non-finite values (NaN / ±Infinity): a malformed `timestamp`
+	// field in the webhook JSON would otherwise multiply into NaN and
+	// leak into the emitted mail.* event, breaking consumers that sort
+	// / persist / compare timestamps numerically.
+	if (ts === undefined || !Number.isFinite(ts)) return Date.now();
+	if (ts > 1e12) return ts;
+	return ts * 1000;
+}