@better-webhook/resend 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Endalkachew Biruk
+
+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,163 @@
+# @better-webhook/resend
+
+[![npm](https://img.shields.io/npm/v/@better-webhook/resend?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/@better-webhook/resend)
+
+Type-safe Resend webhook handling for `better-webhook`.
+
+## Features
+
+- Typed webhook envelopes for all 17 documented Resend event types
+- Automatic Svix-compatible signature verification using `svix-*` headers
+- Default signed timestamp freshness checks (`300` seconds)
+- Replay key support via `svix-id`
+- Tree-shakeable event exports from `@better-webhook/resend/events`
+- Verified but unhandled events acknowledge with `200` to match Resend's delivery contract
+
+## Installation
+
+```bash
+npm install @better-webhook/resend @better-webhook/core
+# or
+pnpm add @better-webhook/resend @better-webhook/core
+# or
+yarn add @better-webhook/resend @better-webhook/core
+```
+
+Install one adapter package too:
+
+```bash
+# Pick one:
+npm install @better-webhook/nextjs
+npm install @better-webhook/express
+npm install @better-webhook/nestjs
+npm install @better-webhook/hono
+npm install @better-webhook/gcp-functions
+```
+
+## Quick Start
+
+```ts
+import { resend } from "@better-webhook/resend";
+import {
+  email_bounced,
+  email_delivered,
+  email_received,
+} from "@better-webhook/resend/events";
+import { toNextJS } from "@better-webhook/nextjs";
+
+const webhook = resend({
+  secret: process.env.RESEND_WEBHOOK_SECRET,
+})
+  .event(email_delivered, async (payload) => {
+    console.log("delivered:", payload.data.email_id);
+  })
+  .event(email_bounced, async (payload) => {
+    console.log("bounce type:", payload.data.bounce.type);
+  })
+  .event(email_received, async (payload) => {
+    console.log("inbound message:", payload.data.message_id);
+  });
+
+export const POST = toNextJS(webhook);
+```
+
+## Supported Events
+
+### Email Events
+
+- `email_sent` (`email.sent`)
+- `email_scheduled` (`email.scheduled`)
+- `email_delivered` (`email.delivered`)
+- `email_delivery_delayed` (`email.delivery_delayed`)
+- `email_complained` (`email.complained`)
+- `email_bounced` (`email.bounced`)
+- `email_opened` (`email.opened`)
+- `email_clicked` (`email.clicked`)
+- `email_received` (`email.received`)
+- `email_failed` (`email.failed`)
+- `email_suppressed` (`email.suppressed`)
+
+### Domain Events
+
+- `domain_created` (`domain.created`)
+- `domain_updated` (`domain.updated`)
+- `domain_deleted` (`domain.deleted`)
+
+### Contact Events
+
+- `contact_created` (`contact.created`)
+- `contact_updated` (`contact.updated`)
+- `contact_deleted` (`contact.deleted`)
+
+## Signature Verification
+
+Resend signs webhook requests with Svix-compatible headers:
+
+- `svix-id`
+- `svix-timestamp`
+- `svix-signature`
+
+This package verifies the exact raw body using HMAC-SHA256 over:
+
+```text
+${svixId}.${svixTimestamp}.${rawBody}
+```
+
+using the base64-decoded portion of the `whsec_...` signing secret.
+
+Verification behavior:
+
+- rejects missing `svix-*` headers
+- rejects malformed timestamps
+- rejects stale or far-future timestamps outside the configured tolerance window
+- accepts any valid `v1` entry in a multi-signature `svix-signature` header
+
+Use the raw request body exactly as Resend sent it. Re-serializing JSON before
+verification will break the signature.
+
+## Replay Protection and Idempotency
+
+Resend delivers webhooks with at-least-once semantics and may retry or replay
+the same message. The provider exposes:
+
+- `context.deliveryId` from `svix-id`
+- replay metadata via `svix-id` + `svix-timestamp`
+
+With core replay protection enabled, duplicate `svix-id` values return `409` by
+default:
+
+```ts
+import { createInMemoryReplayStore } from "@better-webhook/core";
+
+const webhook = resend({ secret: process.env.RESEND_WEBHOOK_SECRET })
+  .withReplayProtection({
+    store: createInMemoryReplayStore(),
+  })
+  .event(email_delivered, async (payload) => {
+    await persistEvent(payload);
+  });
+```
+
+For production, use a shared durable replay store so deduplication works across
+instances and restarts.
+
+## Payload Notes
+
+- Handlers receive the full Resend webhook envelope: `{ type, created_at, data }`.
+- `email.received` webhooks contain metadata only. Fetch the full inbound body,
+  headers, and attachments through Resend's receiving APIs if you need message
+  content.
+- `email.received` payloads may omit `data.subject`; the schema normalizes a
+  missing subject to `""`.
+- `data.tags` follows Resend's documented `Record<string, string>` shape.
+
+## Environment Variables
+
+When no explicit secret is provided, Better Webhook resolves:
+
+1. `RESEND_WEBHOOK_SECRET`
+2. `WEBHOOK_SECRET`
+
+## License
+
+MIT

package/dist/events.cjs

@@ -0,0 +1,276 @@
+'use strict';
+
+var core = require('@better-webhook/core');
+var zod = require('zod');
+
+// src/events.ts
+var ResendTagsMapSchema = zod.z.record(zod.z.string(), zod.z.string());
+var ResendEmailEventDataSchema = zod.z.object({
+  broadcast_id: zod.z.string().optional(),
+  created_at: zod.z.string(),
+  email_id: zod.z.string(),
+  from: zod.z.string(),
+  to: zod.z.array(zod.z.string()),
+  subject: zod.z.string(),
+  template_id: zod.z.string().optional(),
+  tags: ResendTagsMapSchema.optional()
+}).passthrough();
+var ResendBounceSchema = zod.z.object({
+  diagnosticCode: zod.z.array(zod.z.string()).optional(),
+  message: zod.z.string(),
+  subType: zod.z.string(),
+  type: zod.z.string()
+}).passthrough();
+var ResendClickSchema = zod.z.object({
+  ipAddress: zod.z.string(),
+  link: zod.z.string(),
+  timestamp: zod.z.string(),
+  userAgent: zod.z.string()
+}).passthrough();
+var ResendFailedSchema = zod.z.object({
+  reason: zod.z.string()
+}).passthrough();
+var ResendSuppressedSchema = zod.z.object({
+  message: zod.z.string(),
+  type: zod.z.string()
+}).passthrough();
+var ResendReceivedAttachmentSchema = zod.z.object({
+  id: zod.z.string(),
+  filename: zod.z.string().nullable(),
+  content_type: zod.z.string(),
+  content_disposition: zod.z.string().nullable(),
+  content_id: zod.z.string().nullable()
+}).passthrough();
+var ResendReceivedEmailEventDataSchema = zod.z.object({
+  email_id: zod.z.string(),
+  created_at: zod.z.string(),
+  from: zod.z.string(),
+  to: zod.z.array(zod.z.string()),
+  bcc: zod.z.array(zod.z.string()).optional(),
+  cc: zod.z.array(zod.z.string()).optional(),
+  message_id: zod.z.string(),
+  subject: zod.z.string().default(""),
+  attachments: zod.z.array(ResendReceivedAttachmentSchema).optional()
+}).passthrough();
+var ResendContactEventDataSchema = zod.z.object({
+  id: zod.z.string(),
+  audience_id: zod.z.string().optional(),
+  segment_ids: zod.z.array(zod.z.string()),
+  created_at: zod.z.string(),
+  updated_at: zod.z.string(),
+  email: zod.z.string(),
+  first_name: zod.z.string().optional(),
+  last_name: zod.z.string().optional(),
+  unsubscribed: zod.z.boolean()
+}).passthrough();
+var ResendContactDeletedEventDataSchema = ResendContactEventDataSchema.extend(
+  {
+    segment_ids: zod.z.array(zod.z.string()).optional(),
+    unsubscribed: zod.z.boolean().optional()
+  }
+).passthrough();
+var ResendDomainRecordSchema = zod.z.object({
+  record: zod.z.string(),
+  name: zod.z.string(),
+  type: zod.z.string(),
+  value: zod.z.string(),
+  ttl: zod.z.string(),
+  status: zod.z.string(),
+  priority: zod.z.number().optional()
+}).passthrough();
+var ResendDomainEventDataSchema = zod.z.object({
+  id: zod.z.string(),
+  name: zod.z.string(),
+  status: zod.z.string(),
+  created_at: zod.z.string(),
+  region: zod.z.string(),
+  records: zod.z.array(ResendDomainRecordSchema)
+}).passthrough();
+function createResendEventSchema(eventType, dataSchema) {
+  return zod.z.object({
+    type: zod.z.literal(eventType),
+    created_at: zod.z.string(),
+    data: dataSchema
+  }).passthrough();
+}
+var ResendEmailSentEventSchema = createResendEventSchema(
+  "email.sent",
+  ResendEmailEventDataSchema
+);
+var ResendEmailScheduledEventSchema = createResendEventSchema(
+  "email.scheduled",
+  ResendEmailEventDataSchema
+);
+var ResendEmailDeliveredEventSchema = createResendEventSchema(
+  "email.delivered",
+  ResendEmailEventDataSchema
+);
+var ResendEmailDeliveryDelayedEventSchema = createResendEventSchema(
+  "email.delivery_delayed",
+  ResendEmailEventDataSchema
+);
+var ResendEmailComplainedEventSchema = createResendEventSchema(
+  "email.complained",
+  ResendEmailEventDataSchema
+);
+var ResendEmailBouncedEventSchema = createResendEventSchema(
+  "email.bounced",
+  ResendEmailEventDataSchema.extend({
+    bounce: ResendBounceSchema
+  })
+);
+var ResendEmailOpenedEventSchema = createResendEventSchema(
+  "email.opened",
+  ResendEmailEventDataSchema
+);
+var ResendEmailClickedEventSchema = createResendEventSchema(
+  "email.clicked",
+  ResendEmailEventDataSchema.extend({
+    click: ResendClickSchema
+  })
+);
+var ResendEmailReceivedEventSchema = createResendEventSchema(
+  "email.received",
+  ResendReceivedEmailEventDataSchema
+);
+var ResendEmailFailedEventSchema = createResendEventSchema(
+  "email.failed",
+  ResendEmailEventDataSchema.extend({
+    failed: ResendFailedSchema
+  })
+);
+var ResendEmailSuppressedEventSchema = createResendEventSchema(
+  "email.suppressed",
+  ResendEmailEventDataSchema.extend({
+    suppressed: ResendSuppressedSchema
+  })
+);
+var ResendContactCreatedEventSchema = createResendEventSchema(
+  "contact.created",
+  ResendContactEventDataSchema
+);
+var ResendContactUpdatedEventSchema = createResendEventSchema(
+  "contact.updated",
+  ResendContactEventDataSchema
+);
+var ResendContactDeletedEventSchema = createResendEventSchema(
+  "contact.deleted",
+  ResendContactDeletedEventDataSchema
+);
+var ResendDomainCreatedEventSchema = createResendEventSchema(
+  "domain.created",
+  ResendDomainEventDataSchema
+);
+var ResendDomainUpdatedEventSchema = createResendEventSchema(
+  "domain.updated",
+  ResendDomainEventDataSchema
+);
+var ResendDomainDeletedEventSchema = createResendEventSchema(
+  "domain.deleted",
+  ResendDomainEventDataSchema
+);
+
+// src/events.ts
+var email_sent = core.defineEvent({
+  name: "email.sent",
+  schema: ResendEmailSentEventSchema,
+  provider: "resend"
+});
+var email_scheduled = core.defineEvent({
+  name: "email.scheduled",
+  schema: ResendEmailScheduledEventSchema,
+  provider: "resend"
+});
+var email_delivered = core.defineEvent({
+  name: "email.delivered",
+  schema: ResendEmailDeliveredEventSchema,
+  provider: "resend"
+});
+var email_delivery_delayed = core.defineEvent({
+  name: "email.delivery_delayed",
+  schema: ResendEmailDeliveryDelayedEventSchema,
+  provider: "resend"
+});
+var email_complained = core.defineEvent({
+  name: "email.complained",
+  schema: ResendEmailComplainedEventSchema,
+  provider: "resend"
+});
+var email_bounced = core.defineEvent({
+  name: "email.bounced",
+  schema: ResendEmailBouncedEventSchema,
+  provider: "resend"
+});
+var email_opened = core.defineEvent({
+  name: "email.opened",
+  schema: ResendEmailOpenedEventSchema,
+  provider: "resend"
+});
+var email_clicked = core.defineEvent({
+  name: "email.clicked",
+  schema: ResendEmailClickedEventSchema,
+  provider: "resend"
+});
+var email_received = core.defineEvent({
+  name: "email.received",
+  schema: ResendEmailReceivedEventSchema,
+  provider: "resend"
+});
+var email_failed = core.defineEvent({
+  name: "email.failed",
+  schema: ResendEmailFailedEventSchema,
+  provider: "resend"
+});
+var email_suppressed = core.defineEvent({
+  name: "email.suppressed",
+  schema: ResendEmailSuppressedEventSchema,
+  provider: "resend"
+});
+var contact_created = core.defineEvent({
+  name: "contact.created",
+  schema: ResendContactCreatedEventSchema,
+  provider: "resend"
+});
+var contact_updated = core.defineEvent({
+  name: "contact.updated",
+  schema: ResendContactUpdatedEventSchema,
+  provider: "resend"
+});
+var contact_deleted = core.defineEvent({
+  name: "contact.deleted",
+  schema: ResendContactDeletedEventSchema,
+  provider: "resend"
+});
+var domain_created = core.defineEvent({
+  name: "domain.created",
+  schema: ResendDomainCreatedEventSchema,
+  provider: "resend"
+});
+var domain_updated = core.defineEvent({
+  name: "domain.updated",
+  schema: ResendDomainUpdatedEventSchema,
+  provider: "resend"
+});
+var domain_deleted = core.defineEvent({
+  name: "domain.deleted",
+  schema: ResendDomainDeletedEventSchema,
+  provider: "resend"
+});
+
+exports.contact_created = contact_created;
+exports.contact_deleted = contact_deleted;
+exports.contact_updated = contact_updated;
+exports.domain_created = domain_created;
+exports.domain_deleted = domain_deleted;
+exports.domain_updated = domain_updated;
+exports.email_bounced = email_bounced;
+exports.email_clicked = email_clicked;
+exports.email_complained = email_complained;
+exports.email_delivered = email_delivered;
+exports.email_delivery_delayed = email_delivery_delayed;
+exports.email_failed = email_failed;
+exports.email_opened = email_opened;
+exports.email_received = email_received;
+exports.email_scheduled = email_scheduled;
+exports.email_sent = email_sent;
+exports.email_suppressed = email_suppressed;