@zap-studio/webhooks 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -1,70 +1,101 @@
-## @zap-studio/webhooks@0.3.0
+# Changelog
 
-### Migrate to ultracite lint/format; make the adapter contract generic
+All notable changes to this project will be documented in this file.
 
-`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.
+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).
 
-Also: `register()` now returns `this`, error hooks always receive a real `Error` instance, and `rawBody` is typed as `Uint8Array`.
+## [1.0.0]
 
-# @zap-studio/webhooks
+### Changed
 
-## 0.2.2
+`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.
 
-### Dependencies
+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).
 
-- Updated dependency `@zap-studio/validation` to `0.3.4`.
+`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`.
 
-## 0.2.1
+### Removed
 
-### Fixed
+Removed the `./utils` subpath export.
 
-- 3a950dc: Preserve registered hook assignment types while keeping the schema-first router API unchanged.
+## [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:**
+
+- `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)`.
+- Hooks and `verify` are retyped against the context: `BeforeHook(ctx)`, `AfterHook(ctx, response)`, `ErrorHook(error, ctx)`, `VerifyFn(ctx)`. After hooks must `clone()` the response before reading its body.
+- `Adapter`, `BaseAdapter`, and the `./adapters/base` export are removed. Node `http` users can bridge with `srvx` or `@hono/node-server`.
+- The prefix is normalized to a trailing slash and only matches on a path boundary: `prefix: "/api"` now behaves as `/api/`, so `/apihello` no longer matches a route (previously it matched `ihello`).
+
+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.
+
+## [0.3.0]
+
+### 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`. Internal formatting and lint cleanup migrated to ultracite.
+
+## [0.2.2]
+
+### Changed
+
+- Updated dependency `@zap-studio/validation` to `0.3.4`.
+
+## [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/README.md

@@ -1,215 +1,150 @@
 # @zap-studio/webhooks
 
-Schema-first, type-safe webhook routing with runtime-agnostic signature verification support.
+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
+## Installation
 
-Webhook handlers usually repeat the same plumbing:
+```bash
+npm install @zap-studio/webhooks
+```
 
-- verify request authenticity
-- parse and validate payloads
-- route by event path
-- normalize success/error responses
+You also need a schema library that implements [Standard Schema](https://github.com/standard-schema/standard-schema), such as Zod, Valibot, or ArkType.
 
-`@zap-studio/webhooks` isolates that plumbing so your handler code stays focused on business logic.
+## Features
 
-Schemas are the source of truth, and payload types are inferred from them.
+- **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.
 
-## Install
-
-```bash
-pnpm add @zap-studio/webhooks
-```
-
-## Quickstart
+## Quick Start
 
 ```ts
 import { createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
 
-const router = createWebhookRouter({
-  prefix: "/webhooks/",
-});
+const router = createWebhookRouter({ prefix: "/webhooks" });
 
-router.register("payments/succeeded", {
-  schema: z.object({
-    id: z.string(),
-    amount: z.number().positive(),
-    currency: z.string().length(3),
-  }),
-  handler: async ({ payload, ack }) => {
+router.register("/payments/succeeded", {
+  schema: z.object({ id: z.string(), amount: z.number().positive() }),
+  handler: ({ payload }) => {
     // payload is inferred from schema
-    return ack({ status: 200, body: `processed ${payload.id}` });
+    return Response.json({ processed: payload.id });
   },
 });
+
+export default {
+  fetch: (request: Request) => router.handle(request),
+};
 ```
 
-## GitHub webhook example
+## Web API Native
+
+`handle(request: Request)` returns a `Response`, so the router plugs directly into any fetch-compatible runtime.
 
 ```ts
-import { createWebhookRouter } from "@zap-studio/webhooks";
-import { createHmacVerifier } from "@zap-studio/webhooks/verify";
-import { z } from "zod";
+// Bun / Deno / Cloudflare Workers
+export default { fetch: (request: Request) => router.handle(request) };
 
-const router = createWebhookRouter({
-  verify: createHmacVerifier({
-    headerName: "x-hub-signature-256",
-    secret: process.env.GITHUB_WEBHOOK_SECRET!,
-  }),
-});
+// Next.js route handler (app/webhooks/[...path]/route.ts)
+export const POST = (request: Request) => router.handle(request);
 
-router.register("github/push", {
-  schema: z.object({
-    ref: z.string(),
-    repository: z.object({
-      full_name: z.string(),
-    }),
-  }),
-  handler: async ({ payload, ack }) => {
-    console.log(`[github] ${payload.repository.full_name} ${payload.ref}`);
-    return ack();
+// Hono
+app.all("/webhooks/*", (c) => router.handle(c.req.raw));
+```
+
+## Type-Safe Routing
+
+Handler payload types are inferred from the route schema.
+
+```ts
+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 });
   },
 });
 ```
 
-## Stripe webhook example
+## Standard Schema Validation
+
+Bring Zod, Valibot, ArkType, or any compatible library.
 
 ```ts
-import Stripe from "stripe";
-import { createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
+// or: import * as v from "valibot"; import { type } from "arktype";
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+router.register("/event", {
+  schema: z.object({ id: z.string() }),
+  handler: ({ payload }) => Response.json(payload),
+});
+```
 
-const router = createWebhookRouter({
-  verify: async (req) => {
-    const signature = req.headers.get("stripe-signature");
-    if (!signature) {
-      throw new Error("Missing Stripe signature");
-    }
+## Signature Verification
 
-    stripe.webhooks.constructEvent(
-      req.rawBody,
-      signature,
-      process.env.STRIPE_WEBHOOK_SECRET!
-    );
-  },
-});
+Built-in HMAC verifier with constant-time comparison, or plug in your own `verify` function.
 
-router.register("stripe/payment_intent.succeeded", {
-  schema: z.object({
-    id: z.string(),
-    object: z.literal("event"),
-    type: z.literal("payment_intent.succeeded"),
+```ts
+import {
+  createHmacVerifier,
+  createWebhookRouter,
+  VerificationError,
+} from "@zap-studio/webhooks";
+
+const router = createWebhookRouter({
+  verify: createHmacVerifier({
+    headerName: "x-hub-signature-256",
+    secret: process.env.WEBHOOK_SECRET!,
   }),
-  handler: async ({ payload, ack }) => {
-    console.log(`[stripe] event ${payload.id} (${payload.type})`);
-    return ack({ status: 200 });
+  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: (req) => {
-    console.log("incoming", req.path);
-  },
-  after: (_req, res) => {
-    console.log("status", res.status);
-  },
-  onError: (error) => ({
-    status: 500,
-    body: { error: error.message },
-  }),
+  before: (ctx) => console.log("incoming", ctx.path),
+  after: (_ctx, response) => console.log("status", response.status),
+  onError: (error) => Response.json({ error: error.message }, { status: 500 }),
 });
 ```
 
-## Verification helper
+## Runtime-Agnostic
 
-`@zap-studio/webhooks/verify` 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`.
-
-- reads a signature from the header you choose
-- computes an HMAC from `req.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 } from "@zap-studio/webhooks/verify";
-import { VerificationError } from "@zap-studio/webhooks/errors";
-
+// 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(req);
-} 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.
-
-## Why `BaseAdapter` exists
-
-This package is framework-agnostic by design. It does not include Express/Next/Hono/Elysia adapters.
+## Runtime Support
 
-`BaseAdapter` exists to help consumers implement adapters consistently:
+| Runtime            | Minimum version                                  |
+| ------------------ | ------------------------------------------------ |
+| Node.js            | 18.0.0 (router), 19.0.0 (verification helper)    |
+| Bun                | 1.0.0                                            |
+| Deno               | 1.42                                             |
+| Cloudflare Workers | Any current release                              |
+| Browsers           | Latest evergreen (Chrome, Edge, Firefox, Safari) |
 
-- you only implement `toNormalizedRequest` and `toFrameworkResponse`
-- `BaseAdapter` handles the common `handleWebhook()` flow
-- teams can reuse one adapter implementation across all webhook routes
-
-```ts
-import { BaseAdapter } from "@zap-studio/webhooks/adapters/base";
-import type {
-  NormalizedRequest,
-  NormalizedResponse,
-} from "@zap-studio/webhooks/types";
-
-// `BaseAdapter<TReq, TRes>` is generic over your framework request/response
-// types. Override the mapping members with arrow-property syntax.
-class MyHttpAdapter extends BaseAdapter {
-  toNormalizedRequest = async (req: any): Promise<NormalizedRequest> => ({
-    method: req.method,
-    path: req.url,
-    headers: new Headers(req.headers),
-    rawBody: req.rawBody,
-  });
-
-  toFrameworkResponse = async (
-    res: any,
-    normalized: NormalizedResponse
-  ): Promise<any> => {
-    res.statusCode = normalized.status;
-    res.end(
-      typeof normalized.body === "string"
-        ? normalized.body
-        : JSON.stringify(normalized.body)
-    );
-    return res;
-  };
-}
-```
+The router only needs the standard `Request`/`Response` APIs, available globally since Node.js 18. The verification helper additionally needs `globalThis.crypto.subtle`, which is global by default from Node.js 19 (on Node.js 18, pass the `--experimental-global-webcrypto` flag). In browsers, Web Crypto requires a secure context (HTTPS). Deno 1.42 is the first release that can install packages from JSR (`deno add jsr:@zap-studio/webhooks`).
 
 ## License
 

package/dist/{errors.d.mts → 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 {
   /**
@@ -20,4 +36,4 @@ declare class VerificationError extends Error {
 }
 //#endregion
 export { VerificationError };
-//# sourceMappingURL=errors.d.mts.map
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/{errors.mjs → 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 {
 	/**
@@ -24,4 +40,4 @@ var VerificationError = class extends Error {
 //#endregion
 export { VerificationError };
 
-//# sourceMappingURL=errors.mjs.map
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +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 *\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

@@ -0,0 +1,5 @@
+import { VerificationError } from "./errors.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

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

package/dist/router.d.ts

@@ -0,0 +1,137 @@
+import { InferSchemaOutput, RegisterOptions, SchemaRouteOptions, WebhookHandler, WebhookRouterOptions } from "./types.js";
+import { StandardSchemaV1 } from "@zap-studio/validation";
+//#region src/router.d.ts
+/**
+ * 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;
+  private readonly verify;
+  private readonly globalBeforeHooks;
+  private readonly globalAfterHooks;
+  private readonly globalErrorHook;
+  private readonly prefix;
+  private readonly prefixWithSlash;
+  /**
+   * 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);
+  /**
+   * Register a webhook handler for a specific path.
+   *
+   * When a schema is provided, `payload` is inferred from the schema output type.
+   *
+   * @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.
+   *
+   * The request body is read exactly once; hooks and handlers receive the raw
+   * bytes through the webhook context instead of the request stream.
+   *
+   * @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;
+  /** Builds the error response for a failed request, deferring to the global error hook when set. */
+  private handleError;
+}
+/**
+ * Factory helper for creating a webhook router instance.
+ *
+ * @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, createWebhookRouter };
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"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"}