@zap-studio/webhooks 0.4.0 → 1.0.0

package/CHANGELOG.md

@@ -1,10 +1,30 @@
-## @zap-studio/webhooks@0.4.0
+# Changelog
 
-### Rework the package on Web API `Request`/`Response` (breaking)
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0]
+
+### Changed
+
+`WebhookRouter`'s stateless private static methods (`runBeforeHooks`, `runAfterHooks`, `createHandlerEntry`, `parseRequestBody`, `validatePayload`, `executeHandler`) are now module-level functions in `router.ts`. Internal-only change; the public API (`WebhookRouter`, `createWebhookRouter`, `.register()`, `.handle()`) is unaffected.
+
+HMAC signature verification decodes the incoming header's hex signature to bytes and compares it against the computed digest byte-for-byte, instead of hex-encoding the digest and comparing hex text. Behavior is unchanged for valid requests; this only affects internals (fewer bytes compared, and the header's hex is no longer case-normalized as text since decoding handles case natively).
+
+`constantTimeEquals` moved from `utils.ts` into `verify.ts` (its only consumer) and now compares `Uint8Array`s (bytes) instead of strings. Still exported from `@zap-studio/webhooks` and `@zap-studio/webhooks/verify`.
+
+### Removed
+
+Removed the `./utils` subpath export.
+
+## [0.4.0]
+
+### Changed
 
 The custom `NormalizedRequest`/`NormalizedResponse` contract is gone. `router.handle` now takes a standard Web API `Request` and returns a standard `Response`, so the router plugs directly into fetch-native runtimes (Bun, Deno, Cloudflare Workers, Next.js route handlers, Hono) with no adapter layer.
 
-Breaking changes:
+**Breaking changes:**
 
 - `handle(req: NormalizedRequest): Promise<NormalizedResponse>` → `handle(request: Request): Promise<Response>`.
 - Handlers receive `{ request, rawBody, path, payload }` (a `WebhookContext` plus the validated `payload`) and return a `Response` or `undefined` (default `200` `"ok"`). The `ack` helper is removed — use `Response.json(body, init)`.
@@ -14,73 +34,68 @@ Breaking changes:
 
 Behavior kept: hook execution order, prefix semantics (default `/webhooks/`), exact-match routing, HMAC verification, and the `404`/`400`/`500` error body shapes. Unknown routes now return `404` without reading the request body.
 
-## @zap-studio/webhooks@0.3.0
+## [0.3.0]
 
-### Migrate to ultracite lint/format; make the adapter contract generic
+### Changed
 
 `Adapter` and `BaseAdapter` are now generic over the framework request/response types (`Adapter<TReq, TRes>`, `BaseAdapter<TReq, TRes>`), replacing the previous per-method generics. The mapping members (`toNormalizedRequest`, `toFrameworkResponse`, `handleWebhook`) are now arrow properties, so custom adapters must override them with property syntax rather than method syntax.
 
-Also: `register()` now returns `this`, error hooks always receive a real `Error` instance, and `rawBody` is typed as `Uint8Array`.
-
-# @zap-studio/webhooks
+Also: `register()` now returns `this`, error hooks always receive a real `Error` instance, and `rawBody` is typed as `Uint8Array`. Internal formatting and lint cleanup migrated to ultracite.
 
-## 0.2.2
+## [0.2.2]
 
-### Dependencies
+### Changed
 
 - Updated dependency `@zap-studio/validation` to `0.3.4`.
 
-## 0.2.1
-
-### Fixed
-
-- 3a950dc: Preserve registered hook assignment types while keeping the schema-first router API unchanged.
+## [0.2.1]
 
 ### Changed
 
 - 5fa58b1: Reduced webhook router complexity by consolidating hook normalization and handler entry creation.
 - 7004e9f: Allow explicit `undefined` in option handling, then follow with d707800 to remove redundant `| undefined` unions from public types.
 - 9f31f87: Switched the package build to ESNext-aligned output and updated package tooling and publish metadata.
+- Updated dependency `@zap-studio/validation` to `0.3.3`.
 
-### Dependencies
+### Fixed
 
-- Updated dependency `@zap-studio/validation` to `0.3.3`.
+- 3a950dc: Preserve registered hook assignment types while keeping the schema-first router API unchanged.
 
-## 0.2.0
+## [0.2.0]
 
-### Minor Changes
+### Changed
 
 - c686862: Switch `createHmacVerifier` to Web Crypto and standardize the verifier around string secrets.
 
   This change removes the Node `crypto` dependency from the verifier path, keeps `req.rawBody` as `Uint8Array`, simplifies `createHmacVerifier` to take a string secret, and adds public `VerificationError` in `@zap-studio/webhooks/errors` for verifier setup and signature failures.
 
-## 0.1.4
+## [0.1.4]
 
-### Patch Changes
+### Changed
 
 - e26293e: Updated dependencies.
   - @zap-studio/validation@0.3.2
 
-## 0.1.3
+## [0.1.3]
 
-### Patch Changes
+### Changed
 
 - 5ea3d3b: Updated dependencies.
   - @zap-studio/validation@0.3.1
 
-## 0.1.2
+## [0.1.2]
 
-### Patch Changes
+### Fixed
 
 - c209a27: Fix payload schema validation internals to use the current async `standardValidate` options API (`{ throwOnError: false }`), restoring typecheck compatibility after the validation helper signature update.
 
-## 0.1.1
+## [0.1.1]
 
-### Dependencies
+### Changed
 
 - f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
 
-## 0.1.0
+## [0.1.0]
 
 ### Added
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 alexandretrotel
+Copyright (c) 2026 Alexandre Trotel
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,66 +2,50 @@
 
 Schema-first, type-safe webhook routing built on the standard Web API [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) primitives, with runtime-agnostic signature verification support.
 
-Works with any validation library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), including Zod, Valibot, and ArkType.
+Full documentation: [zapstudio.dev/webhooks](https://www.zapstudio.dev/webhooks)
 
-## Why this package exists
-
-Webhook handlers usually repeat the same plumbing:
-
-- verify request authenticity
-- parse and validate payloads
-- route by event path
-- normalize success/error responses
-
-`@zap-studio/webhooks` isolates that plumbing so your handler code stays focused on business logic.
-
-Schemas are the source of truth, and payload types are inferred from them.
-
-## Install
+## Installation
 
 ```bash
 npm install @zap-studio/webhooks
 ```
 
-## Quickstart
+You also need a schema library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), such as Zod, Valibot, or ArkType.
+
+## Features
+
+- **Web API native** — `handle(request: Request)` returns a `Response`, so the router plugs directly into Bun, Deno, Cloudflare Workers, Next.js route handlers, Hono, and any other fetch-compatible runtime.
+- **Type-safe routing** — handler payload types are inferred from the route schema.
+- **Standard Schema validation** — bring Zod, Valibot, ArkType, or any compatible library.
+- **Signature verification** — built-in HMAC verifier with constant-time comparison, or plug in your own `verify` function.
+- **Lifecycle hooks** — global `before`, `after`, and `onError` hooks for cross-cutting behavior.
+- **Runtime-agnostic** — uses the Web Crypto API, not Node-specific APIs.
+- **Tree-shakeable** — validation and hook-running internals are standalone functions; unused exports are dropped by any modern bundler.
+
+## Quick Start
 
 ```ts
 import { createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
 
-const router = createWebhookRouter({
-  prefix: "/webhooks", // default
-});
+const router = createWebhookRouter({ prefix: "/webhooks" });
 
 router.register("/payments/succeeded", {
-  schema: z.object({
-    id: z.string(),
-    amount: z.number().positive(),
-    currency: z.string().length(3),
-  }),
+  schema: z.object({ id: z.string(), amount: z.number().positive() }),
   handler: ({ payload }) => {
     // payload is inferred from schema
-    return Response.json(`processed ${payload.id}`);
+    return Response.json({ processed: payload.id });
   },
 });
 
-// Any fetch-compatible runtime: Bun, Deno, Cloudflare Workers, ...
 export default {
   fetch: (request: Request) => router.handle(request),
 };
 ```
 
-`router.handle` takes a standard `Request` and returns a standard `Response`, so the router plugs directly into any fetch-native runtime — no adapter layer needed.
-
-Handlers can return a `Response`, or `undefined` to let the router reply with its default `200` acknowledgement.
-
-### Paths and the prefix
-
-Routes are registered with a leading slash (`"/payments/succeeded"`) and matched relative to the router's `prefix` (default `"/webhooks"`, no trailing slash) — so the example above answers on `/webhooks/payments/succeeded`. Paths are normalized internally: missing leading slashes are added, trailing slashes stripped, and duplicate slashes collapsed, on both registered routes and incoming request URLs. Set `prefix: ""` (or `"/"`) to mount routes at the root.
-
-## Runtime integration
+## Web API Native
 
-Because `handle(request)` speaks fetch, integration is one line in most environments:
+`handle(request: Request)` returns a `Response`, so the router plugs directly into any fetch-compatible runtime.
 
 ```ts
 // Bun / Deno / Cloudflare Workers
@@ -74,151 +58,82 @@ export const POST = (request: Request) => router.handle(request);
 app.all("/webhooks/*", (c) => router.handle(c.req.raw));
 ```
 
-For raw Node `http` servers, use a fetch-to-Node bridge such as [`srvx`](https://srvx.h3.dev) or [`@hono/node-server`](https://github.com/honojs/node-server).
+## Type-Safe Routing
 
-## The webhook context
-
-Hooks, verifiers, and handlers all receive a context object instead of the raw request stream. The router reads the request body exactly once, so the exact bytes stay available for signature verification:
+Handler payload types are inferred from the route schema.
 
 ```ts
-interface WebhookContext {
-  request: Request; // headers, method, url — body already consumed
-  rawBody: Uint8Array; // exact request body bytes
-  path: string; // matched route key, e.g. "/payments/succeeded"
-}
+router.register("/payments/succeeded", {
+  schema: z.object({ id: z.string(), amount: z.number() }),
+  handler: ({ payload }) => {
+    // payload.id: string, payload.amount: number — inferred from schema
+    return Response.json({ ok: true });
+  },
+});
 ```
 
-Handlers additionally receive `payload`, the schema-validated body.
+## Standard Schema Validation
 
-## GitHub webhook example
+Bring Zod, Valibot, ArkType, or any compatible library.
 
 ```ts
-import { createHmacVerifier, createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
+// or: import * as v from "valibot"; import { type } from "arktype";
 
-const router = createWebhookRouter({
-  verify: createHmacVerifier({
-    headerName: "x-hub-signature-256",
-    secret: process.env.GITHUB_WEBHOOK_SECRET!,
-  }),
-});
-
-router.register("/github/push", {
-  schema: z.object({
-    ref: z.string(),
-    repository: z.object({
-      full_name: z.string(),
-    }),
-  }),
-  handler: ({ payload }) => {
-    console.log(`[github] ${payload.repository.full_name} ${payload.ref}`);
-    return undefined; // default 200 "ok"
-  },
+router.register("/event", {
+  schema: z.object({ id: z.string() }),
+  handler: ({ payload }) => Response.json(payload),
 });
 ```
 
-## Stripe webhook example
+## Signature Verification
 
-```ts
-import Stripe from "stripe";
-import { createWebhookRouter } from "@zap-studio/webhooks";
-import { z } from "zod";
+Built-in HMAC verifier with constant-time comparison, or plug in your own `verify` function.
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+```ts
+import {
+  createHmacVerifier,
+  createWebhookRouter,
+  VerificationError,
+} from "@zap-studio/webhooks";
 
 const router = createWebhookRouter({
-  verify: ({ request, rawBody }) => {
-    const signature = request.headers.get("stripe-signature");
-    if (!signature) {
-      throw new Error("Missing Stripe signature");
-    }
-
-    stripe.webhooks.constructEvent(
-      Buffer.from(rawBody),
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  },
-});
-
-router.register("/stripe/payment_intent.succeeded", {
-  schema: z.object({
-    id: z.string(),
-    object: z.literal("event"),
-    type: z.literal("payment_intent.succeeded"),
+  verify: createHmacVerifier({
+    headerName: "x-hub-signature-256",
+    secret: process.env.WEBHOOK_SECRET!,
   }),
-  handler: ({ payload }) => {
-    console.log(`[stripe] event ${payload.id} (${payload.type})`);
-    return Response.json("received");
+  onError: (error) => {
+    if (error instanceof VerificationError) {
+      return Response.json({ error: "invalid signature" }, { status: 401 });
+    }
   },
 });
 ```
 
-## Lifecycle hooks
-
-Lifecycle hooks let you apply cross-cutting behavior without duplicating code in each handler:
+## Lifecycle Hooks
 
-- `before`: run logic before verify/validation/handler (logging, tracing, rate-limit checks)
-- `after`: run logic after successful handler execution (metrics, audit logs)
-- `onError`: map thrown errors to consistent responses and centralize error reporting
+Global `before`, `after`, and `onError` hooks for cross-cutting behavior.
 
 ```ts
 const router = createWebhookRouter({
-  before: (ctx) => {
-    console.log("incoming", ctx.path);
-  },
-  after: (_ctx, response) => {
-    console.log("status", response.status);
-  },
+  before: (ctx) => console.log("incoming", ctx.path),
+  after: (_ctx, response) => console.log("status", response.status),
   onError: (error) => Response.json({ error: error.message }, { status: 500 }),
 });
 ```
 
-After-hooks receive the outgoing `Response` as-is. If a hook needs to read the body, call `response.clone()` first so the stream sent to the client stays readable:
-
-```ts
-const router = createWebhookRouter({
-  after: async (_ctx, response) => {
-    const body = await response.clone().json();
-    console.log("responded with", body);
-  },
-});
-```
-
-## Verification helper
-
-`@zap-studio/webhooks` exports `createHmacVerifier`, a small helper that builds a `verify` function for HMAC-signed webhook providers.
-
-It does not depend on Node APIs. The verifier uses the Web Crypto API, so it works in any runtime that provides `globalThis.crypto.subtle`.
+## Runtime-Agnostic
 
-- reads a signature from the header you choose
-- computes an HMAC from `ctx.rawBody`
-- compares signatures in constant time
-- uses the Web Crypto API instead of Node `crypto`
-- works across runtimes that provide `globalThis.crypto.subtle`
-- expects a string secret
-- throws `VerificationError` on verifier setup or signature failures
+Uses the Web Crypto API, not Node-specific APIs.
 
 ```ts
-import { createHmacVerifier, VerificationError } from "@zap-studio/webhooks";
-
+// Uses globalThis.crypto.subtle — no Node `crypto` import required
 const verify = createHmacVerifier({
   headerName: "x-hub-signature-256",
   secret: process.env.WEBHOOK_SECRET!,
-  algo: "sha256", // optional, defaults to sha256
 });
-
-try {
-  await verify(ctx);
-} catch (error) {
-  if (error instanceof VerificationError) {
-    console.error("webhook verification failed", error.message);
-  }
-}
 ```
 
-Use this when your provider uses standard HMAC signatures. For providers with custom signing formats, pass your own `verify` function.
-
 ## Runtime Support
 
 | Runtime            | Minimum version                                  |

package/dist/errors.d.ts

@@ -9,6 +9,22 @@
  *
  * This error is used by verifier helpers such as `createHmacVerifier` so
  * callers can distinguish verification failures from other webhook errors.
+ *
+ * @example
+ * ```ts
+ * import { VerificationError } from "@zap-studio/webhooks";
+ *
+ * const response = await router.handle(request);
+ * // Verification failures surface as a 500 response by default, or via onError:
+ * const routerWithHandler = createWebhookRouter({
+ *   verify: createHmacVerifier({ headerName: "x-signature", secret }),
+ *   onError: (error) => {
+ *     if (error instanceof VerificationError) {
+ *       return Response.json({ error: error.message }, { status: 401 });
+ *     }
+ *   },
+ * });
+ * ```
  */
 declare class VerificationError extends Error {
   /**

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;cAYa,0BAA0B;;;;;;EAMrC,YAAY"}
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4Ba,0BAA0B;;;;;;EAMrC,YAAY"}

package/dist/errors.js

@@ -9,6 +9,22 @@
 *
 * This error is used by verifier helpers such as `createHmacVerifier` so
 * callers can distinguish verification failures from other webhook errors.
+*
+* @example
+* ```ts
+* import { VerificationError } from "@zap-studio/webhooks";
+*
+* const response = await router.handle(request);
+* // Verification failures surface as a 500 response by default, or via onError:
+* const routerWithHandler = createWebhookRouter({
+*   verify: createHmacVerifier({ headerName: "x-signature", secret }),
+*   onError: (error) => {
+*     if (error instanceof VerificationError) {
+*       return Response.json({ error: error.message }, { status: 401 });
+*     }
+*   },
+* });
+* ```
 */
 var VerificationError = class extends Error {
 	/**

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error primitives for webhook verification failures.\n *\n * @module @zap-studio/webhooks/errors\n */\n\n/**\n * Error thrown when webhook request verification fails.\n *\n * This error is used by verifier helpers such as `createHmacVerifier` so\n * callers can distinguish verification failures from other webhook errors.\n */\nexport class VerificationError extends Error {\n  /**\n   * Creates a verification error with a human-readable message.\n   *\n   * @param message - Error message describing the verification failure.\n   */\n  constructor(message: string) {\n    super(message);\n    this.name = \"VerificationError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAYA,IAAa,oBAAb,cAAuC,MAAM;;;;;;CAM3C,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Error primitives for webhook verification failures.\n *\n * @module @zap-studio/webhooks/errors\n */\n\n/**\n * Error thrown when webhook request verification fails.\n *\n * This error is used by verifier helpers such as `createHmacVerifier` so\n * callers can distinguish verification failures from other webhook errors.\n *\n * @example\n * ```ts\n * import { VerificationError } from \"@zap-studio/webhooks\";\n *\n * const response = await router.handle(request);\n * // Verification failures surface as a 500 response by default, or via onError:\n * const routerWithHandler = createWebhookRouter({\n *   verify: createHmacVerifier({ headerName: \"x-signature\", secret }),\n *   onError: (error) => {\n *     if (error instanceof VerificationError) {\n *       return Response.json({ error: error.message }, { status: 401 });\n *     }\n *   },\n * });\n * ```\n */\nexport class VerificationError extends Error {\n  /**\n   * Creates a verification error with a human-readable message.\n   *\n   * @param message - Error message describing the verification failure.\n   */\n  constructor(message: string) {\n    super(message);\n    this.name = \"VerificationError\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,IAAa,oBAAb,cAAuC,MAAM;;;;;;CAM3C,YAAY,SAAiB;EAC3B,MAAM,OAAO;EACb,KAAK,OAAO;CACd;AACF"}

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import { VerificationError } from "./errors.js";
-import { AfterHook, BeforeHook, ErrorHook, HandlerContext, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookContext, WebhookHandler } from "./types.js";
-import { WebhookRouter, WebhookRouterOptions, createWebhookRouter } from "./router.js";
-import { constantTimeEquals } from "./utils.js";
-import { createHmacVerifier } from "./verify.js";
+import { AfterHook, BeforeHook, ErrorHook, HandlerContext, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookContext, WebhookHandler, WebhookRouterOptions } from "./types.js";
+import { WebhookRouter, createWebhookRouter } from "./router.js";
+import { constantTimeEquals, createHmacVerifier } from "./verify.js";
 export { type AfterHook, type BeforeHook, type ErrorHook, type HandlerContext, type HandlerMap, type InferSchemaOutput, type InferWebhookMapFromRoutes, type RegisterOptions, type SchemaRouteOptions, type SchemaRoutes, VerificationError, type VerifyFn, type WebhookContext, type WebhookHandler, WebhookRouter, type WebhookRouterOptions, constantTimeEquals, createHmacVerifier, createWebhookRouter };

package/dist/index.js

@@ -1,5 +1,4 @@
 import { VerificationError } from "./errors.js";
 import { WebhookRouter, createWebhookRouter } from "./router.js";
-import { constantTimeEquals } from "./utils.js";
-import { createHmacVerifier } from "./verify.js";
+import { constantTimeEquals, createHmacVerifier } from "./verify.js";
 export { VerificationError, WebhookRouter, constantTimeEquals, createHmacVerifier, createWebhookRouter };

package/dist/router.d.ts

@@ -1,27 +1,26 @@
-import { AfterHook, BeforeHook, ErrorHook, InferSchemaOutput, RegisterOptions, SchemaRouteOptions, VerifyFn, WebhookHandler } from "./types.js";
+import { InferSchemaOutput, RegisterOptions, SchemaRouteOptions, WebhookHandler, WebhookRouterOptions } from "./types.js";
 import { StandardSchemaV1 } from "@zap-studio/validation";
 //#region src/router.d.ts
-interface WebhookRouterOptions {
-  /** Global hooks executed after successful route handler completion. */
-  after?: AfterHook | AfterHook[];
-  /** Global hooks executed before route-level hooks and verification. */
-  before?: BeforeHook | BeforeHook[];
-  /** Global error hook used to override the default `500` response. */
-  onError?: ErrorHook;
-  /**
-   * Required path prefix for all webhook routes. Defaults to `"/webhooks"`.
-   *
-   * Normalized internally: leading slash added, trailing slash stripped,
-   * duplicate slashes collapsed. Use `""` or `"/"` to mount at the root.
-   */
-  prefix?: string;
-  /** Optional request verification function (for signature checks, auth, etc.). */
-  verify?: VerifyFn;
-}
 /**
  * Main webhook router class.
  *
  * Register routes with typed schemas and call `handle` with a Web API `Request`.
+ *
+ * @example
+ * ```ts
+ * import { WebhookRouter } from "@zap-studio/webhooks";
+ *
+ * const router = new WebhookRouter({ prefix: "/webhooks" });
+ *
+ * router.register("/stripe", {
+ *   schema: stripeEventSchema,
+ *   handler: async ({ payload }) => {
+ *     console.log("Stripe event:", payload.type);
+ *   },
+ * });
+ *
+ * export default { fetch: (request: Request) => router.handle(request) };
+ * ```
  */
 declare class WebhookRouter<TMap = unknown> {
   private readonly handlers;
@@ -35,6 +34,15 @@ declare class WebhookRouter<TMap = unknown> {
    * Creates a webhook router with optional global hooks and verification behavior.
    *
    * @param opts - Router-level options.
+   *
+   * @example
+   * ```ts
+   * const router = new WebhookRouter({
+   *   prefix: "/webhooks",
+   *   verify: createHmacVerifier({ headerName: "x-signature", secret }),
+   *   onError: (error) => Response.json({ error: error.message }, { status: 500 }),
+   * });
+   * ```
    */
   constructor(opts?: WebhookRouterOptions);
   /**
@@ -45,9 +53,46 @@ declare class WebhookRouter<TMap = unknown> {
    * @param path - Route path relative to configured prefix, starting with `/` (e.g. `"/stripe"`).
    * @param handlerOrOptions - Handler function or schema-based registration options.
    * @returns The same router instance with an updated internal route type map.
+   *
+   * @example
+   * ```ts
+   * router.register("/stripe", {
+   *   schema: stripeEventSchema,
+   *   handler: async ({ payload }) => {
+   *     console.log(payload.type); // typed from stripeEventSchema
+   *   },
+   * });
+   * ```
    */
   register<Path extends `/${string}`, TSchema extends StandardSchemaV1<unknown, unknown>>(path: Path, handlerOrOptions: SchemaRouteOptions<TSchema>): WebhookRouter<TMap & Record<Path, InferSchemaOutput<TSchema>>>;
+  /**
+   * Register a webhook handler for a specific path, with schema-less registration options.
+   *
+   * @param path - Route path relative to configured prefix, starting with `/` (e.g. `"/stripe"`).
+   * @param handlerOrOptions - Registration options without a schema.
+   * @returns The same router instance with an updated internal route type map.
+   *
+   * @example
+   * ```ts
+   * router.register("/ping", {
+   *   before: (ctx) => console.log("received", ctx.path),
+   *   handler: () => Response.json({ ok: true }),
+   * });
+   * ```
+   */
   register<Path extends `/${string}`, TPayload>(path: Path, handlerOrOptions: RegisterOptions<TPayload>): WebhookRouter<TMap & Record<Path, TPayload>>;
+  /**
+   * Register a webhook handler for a specific path, using a plain handler function.
+   *
+   * @param path - Route path relative to configured prefix, starting with `/` (e.g. `"/stripe"`).
+   * @param handlerOrOptions - Handler function to process the webhook.
+   * @returns The same router instance with an updated internal route type map.
+   *
+   * @example
+   * ```ts
+   * router.register("/health", () => Response.json({ status: "ok" }));
+   * ```
+   */
   register<Path extends `/${string}`>(path: Path, handlerOrOptions: WebhookHandler): WebhookRouter<TMap & Record<Path, unknown>>;
   /**
    * Handles an incoming webhook request.
@@ -57,15 +102,19 @@ declare class WebhookRouter<TMap = unknown> {
    *
    * @param request - Incoming Web API request.
    * @returns Web API response for the runtime to send back.
+   *
+   * @example
+   * ```ts
+   * // Framework-agnostic: works with any Web API Request/Response runtime.
+   * export async function POST(request: Request): Promise<Response> {
+   *   return router.handle(request);
+   * }
+   * ```
    */
   handle(request: Request): Promise<Response>;
+  /** Resolves the incoming request's URL to a registered route key, or `null` if it doesn't match the configured prefix. */
   private matchPath;
-  private static runBeforeHooks;
-  private static runAfterHooks;
-  private static createHandlerEntry;
-  private static parseRequestBody;
-  private static validatePayload;
-  private static executeHandler;
+  /** Builds the error response for a failed request, deferring to the global error hook when set. */
   private handleError;
 }
 /**
@@ -73,8 +122,16 @@ declare class WebhookRouter<TMap = unknown> {
  *
  * @param opts - Optional global router options.
  * @returns A new webhook router.
+ *
+ * @example
+ * ```ts
+ * import { createWebhookRouter } from "@zap-studio/webhooks";
+ *
+ * const router = createWebhookRouter({ prefix: "/webhooks" });
+ * router.register("/stripe", { schema: stripeEventSchema, handler });
+ * ```
  */
 declare const createWebhookRouter: (opts?: WebhookRouterOptions) => WebhookRouter;
 //#endregion
-export { WebhookRouter, WebhookRouterOptions, createWebhookRouter };
+export { WebhookRouter, createWebhookRouter };
 //# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","names":[],"sources":["../src/router.ts"],"mappings":";;;UAiCiB;;EAEf,QAAQ,YAAY;;EAEpB,SAAS,aAAa;;EAEtB,UAAU;;;;;;;EAOV;;EAEA,SAAS;;;;;;;cAoCE,cAAc;mBACR;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;;;;;;EAOjB,YAAY,OAAM;;;;;;;;;;EAkBlB,SACE,2BACA,gBAAgB,oCAEhB,MAAM,MACN,kBAAkB,mBAAmB,WACpC,cAAc,OAAO,OAAO,MAAM,kBAAkB;EACvD,SAAS,2BAA2B,UAClC,MAAM,MACN,kBAAkB,gBAAgB,YACjC,cAAc,OAAO,OAAO,MAAM;EACrC,SAAS,2BACP,MAAM,MACN,kBAAkB,iBACjB,cAAc,OAAO,OAAO;;;;;;;;;;EAwB/B,OAAa,SAAS,UAAU,QAAQ;UAoDhC;iBAqBa;iBAcA;iBAeN;iBA0BA;iBAQM;iBA+BA;UAaP;;;;;;;;cA4BH,sBACX,OAAO,yBACN"}
+{"version":3,"file":"router.d.ts","names":[],"sources":["../src/router.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;cA2La,cAAc;mBACR;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;;;;;;;;;;;;;;;EAgBjB,YAAY,OAAM;;;;;;;;;;;;;;;;;;;;EA4BlB,SACE,2BACA,gBAAgB,oCAEhB,MAAM,MACN,kBAAkB,mBAAmB,WACpC,cAAc,OAAO,OAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;EAgBvD,SAAS,2BAA2B,UAClC,MAAM,MACN,kBAAkB,gBAAgB,YACjC,cAAc,OAAO,OAAO,MAAM;;;;;;;;;;;;;EAarC,SAAS,2BACP,MAAM,MACN,kBAAkB,iBACjB,cAAc,OAAO,OAAO;;;;;;;;;;;;;;;;;;EAgC/B,OAAa,SAAS,UAAU,QAAQ;;UAqDhC;;UAsBM;;;;;;;;;;;;;;;;cAoCH,sBACX,OAAO,yBACN"}