@zap-studio/webhooks 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## @zap-studio/webhooks@0.4.0
+
+### Rework the package on Web API `Request`/`Response` (breaking)
+
+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.
+
+## @zap-studio/webhooks@0.3.0
+
+### Migrate to ultracite lint/format; make the adapter contract generic
+
+`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
 
 ## 0.2.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Alexandre Trotel
+Copyright (c) 2026 alexandretrotel
 
 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

@@ -1,6 +1,6 @@
 # @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.
 
@@ -20,7 +20,7 @@ Schemas are the source of truth, and payload types are inferred from them.
 ## Install
 
 ```bash
-pnpm add @zap-studio/webhooks
+npm install @zap-studio/webhooks
 ```
 
 ## Quickstart
@@ -30,27 +30,70 @@ import { createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
 
 const router = createWebhookRouter({
-  prefix: "/webhooks/",
+  prefix: "/webhooks", // default
 });
 
-router.register("payments/succeeded", {
+router.register("/payments/succeeded", {
   schema: z.object({
     id: z.string(),
     amount: z.number().positive(),
     currency: z.string().length(3),
   }),
-  handler: async ({ payload, ack }) => {
+  handler: ({ payload }) => {
     // payload is inferred from schema
-    return ack({ status: 200, body: `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
+
+Because `handle(request)` speaks fetch, integration is one line in most environments:
+
+```ts
+// Bun / Deno / Cloudflare Workers
+export default { fetch: (request: Request) => router.handle(request) };
+
+// Next.js route handler (app/webhooks/[...path]/route.ts)
+export const POST = (request: Request) => router.handle(request);
+
+// Hono
+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).
+
+## 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:
+
+```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"
+}
 ```
 
+Handlers additionally receive `payload`, the schema-validated body.
+
 ## GitHub webhook example
 
 ```ts
-import { createWebhookRouter } from "@zap-studio/webhooks";
-import { createHmacVerifier } from "@zap-studio/webhooks/verify";
+import { createHmacVerifier, createWebhookRouter } from "@zap-studio/webhooks";
 import { z } from "zod";
 
 const router = createWebhookRouter({
@@ -60,16 +103,16 @@ const router = createWebhookRouter({
   }),
 });
 
-router.register("github/push", {
+router.register("/github/push", {
   schema: z.object({
     ref: z.string(),
     repository: z.object({
       full_name: z.string(),
     }),
   }),
-  handler: async ({ payload, ack }) => {
+  handler: ({ payload }) => {
     console.log(`[github] ${payload.repository.full_name} ${payload.ref}`);
-    return ack();
+    return undefined; // default 200 "ok"
   },
 });
 ```
@@ -84,25 +127,29 @@ import { z } from "zod";
 const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
 
 const router = createWebhookRouter({
-  verify: async (req) => {
-    const signature = req.headers.get("stripe-signature");
+  verify: ({ request, rawBody }) => {
+    const signature = request.headers.get("stripe-signature");
     if (!signature) {
       throw new Error("Missing Stripe signature");
     }
 
-    stripe.webhooks.constructEvent(req.rawBody, signature, process.env.STRIPE_WEBHOOK_SECRET!);
+    stripe.webhooks.constructEvent(
+      Buffer.from(rawBody),
+      signature,
+      process.env.STRIPE_WEBHOOK_SECRET!
+    );
   },
 });
 
-router.register("stripe/payment_intent.succeeded", {
+router.register("/stripe/payment_intent.succeeded", {
   schema: z.object({
     id: z.string(),
     object: z.literal("event"),
     type: z.literal("payment_intent.succeeded"),
   }),
-  handler: async ({ payload, ack }) => {
+  handler: ({ payload }) => {
     console.log(`[stripe] event ${payload.id} (${payload.type})`);
-    return ack({ status: 200 });
+    return Response.json("received");
   },
 });
 ```
@@ -117,27 +164,35 @@ Lifecycle hooks let you apply cross-cutting behavior without duplicating code in
 
 ```ts
 const router = createWebhookRouter({
-  before: (req) => {
-    console.log("incoming", req.path);
+  before: (ctx) => {
+    console.log("incoming", ctx.path);
   },
-  after: (_req, res) => {
-    console.log("status", res.status);
+  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);
   },
-  onError: (error) => ({
-    status: 500,
-    body: { error: error.message },
-  }),
 });
 ```
 
 ## Verification helper
 
-`@zap-studio/webhooks/verify` exports `createHmacVerifier`, a small helper that builds a `verify` function for HMAC-signed webhook providers.
+`@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`.
 
 - reads a signature from the header you choose
-- computes an HMAC from `req.rawBody`
+- 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`
@@ -145,8 +200,7 @@ It does not depend on Node APIs. The verifier uses the Web Crypto API, so it wor
 - throws `VerificationError` on verifier setup or signature failures
 
 ```ts
-import { createHmacVerifier } from "@zap-studio/webhooks/verify";
-import { VerificationError } from "@zap-studio/webhooks/errors";
+import { createHmacVerifier, VerificationError } from "@zap-studio/webhooks";
 
 const verify = createHmacVerifier({
   headerName: "x-hub-signature-256",
@@ -155,7 +209,7 @@ const verify = createHmacVerifier({
 });
 
 try {
-  await verify(req);
+  await verify(ctx);
 } catch (error) {
   if (error instanceof VerificationError) {
     console.error("webhook verification failed", error.message);
@@ -165,39 +219,17 @@ try {
 
 Use this when your provider uses standard HMAC signatures. For providers with custom signing formats, pass your own `verify` function.
 
-## Why `BaseAdapter` exists
+## Runtime Support
 
-This package is framework-agnostic by design. It does not include Express/Next/Hono/Elysia adapters.
+| 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) |
 
-`BaseAdapter` exists to help consumers implement adapters consistently:
-
-- 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";
-
-class MyHttpAdapter extends BaseAdapter {
-  async toNormalizedRequest(req: any): Promise<NormalizedRequest> {
-    return {
-      method: req.method,
-      path: req.url,
-      headers: new Headers(req.headers),
-      rawBody: req.rawBody,
-    };
-  }
-
-  async toFrameworkResponse(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.ts

@@ -0,0 +1,23 @@
+//#region src/errors.d.ts
+/**
+ * Error primitives for webhook verification failures.
+ *
+ * @module @zap-studio/webhooks/errors
+ */
+/**
+ * Error thrown when webhook request verification fails.
+ *
+ * This error is used by verifier helpers such as `createHmacVerifier` so
+ * callers can distinguish verification failures from other webhook errors.
+ */
+declare class VerificationError extends Error {
+  /**
+   * Creates a verification error with a human-readable message.
+   *
+   * @param message - Error message describing the verification failure.
+   */
+  constructor(message: string);
+}
+//#endregion
+export { VerificationError };
+//# 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":";;;;;;;;;;;;cAYa,0BAA0B;;;;;;EAMrC,YAAY"}

package/dist/{errors.mjs → errors.js}

@@ -1,11 +1,21 @@
 //#region src/errors.ts
 /**
+* Error primitives for webhook verification failures.
+*
+* @module @zap-studio/webhooks/errors
+*/
+/**
 * Error thrown when webhook request verification fails.
 *
 * This error is used by verifier helpers such as `createHmacVerifier` so
 * callers can distinguish verification failures from other webhook errors.
 */
 var VerificationError = class extends Error {
+	/**
+	* Creates a verification error with a human-readable message.
+	*
+	* @param message - Error message describing the verification failure.
+	*/
 	constructor(message) {
 		super(message);
 		this.name = "VerificationError";
@@ -14,4 +24,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 */\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"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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";
+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,5 @@
+import { VerificationError } from "./errors.js";
+import { WebhookRouter, createWebhookRouter } from "./router.js";
+import { constantTimeEquals } from "./utils.js";
+import { createHmacVerifier } from "./verify.js";
+export { VerificationError, WebhookRouter, constantTimeEquals, createHmacVerifier, createWebhookRouter };

package/dist/router.d.ts

@@ -0,0 +1,80 @@
+import { AfterHook, BeforeHook, ErrorHook, InferSchemaOutput, RegisterOptions, SchemaRouteOptions, VerifyFn, WebhookHandler } 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`.
+ */
+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.
+   */
+  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.
+   */
+  register<Path extends `/${string}`, TSchema extends StandardSchemaV1<unknown, unknown>>(path: Path, handlerOrOptions: SchemaRouteOptions<TSchema>): WebhookRouter<TMap & Record<Path, InferSchemaOutput<TSchema>>>;
+  register<Path extends `/${string}`, TPayload>(path: Path, handlerOrOptions: RegisterOptions<TPayload>): WebhookRouter<TMap & Record<Path, TPayload>>;
+  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.
+   */
+  handle(request: Request): Promise<Response>;
+  private matchPath;
+  private static runBeforeHooks;
+  private static runAfterHooks;
+  private static createHandlerEntry;
+  private static parseRequestBody;
+  private static validatePayload;
+  private static executeHandler;
+  private handleError;
+}
+/**
+ * Factory helper for creating a webhook router instance.
+ *
+ * @param opts - Optional global router options.
+ * @returns A new webhook router.
+ */
+declare const createWebhookRouter: (opts?: WebhookRouterOptions) => WebhookRouter;
+//#endregion
+export { WebhookRouter, WebhookRouterOptions, 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":";;;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"}

package/dist/router.js

@@ -0,0 +1,149 @@
+import { standardValidate } from "@zap-studio/validation";
+//#region src/router.ts
+const toArray = (value) => {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+};
+const notFoundResponse = () => Response.json({ error: "not found" }, { status: 404 });
+const bodyDecoder = new TextDecoder();
+/**
+* Normalizes a path to its canonical form: leading slash, no trailing slash,
+* duplicate slashes collapsed. The root path is `"/"`.
+*/
+const normalizePath = (path) => {
+	const withLeadingSlash = path.startsWith("/") ? path : `/${path}`;
+	const collapsed = withLeadingSlash.includes("//") ? withLeadingSlash.replaceAll(/\/{2,}/gu, "/") : withLeadingSlash;
+	return collapsed.length > 1 && collapsed.endsWith("/") ? collapsed.slice(0, -1) : collapsed;
+};
+/**
+* Main webhook router class.
+*
+* Register routes with typed schemas and call `handle` with a Web API `Request`.
+*/
+var WebhookRouter = class WebhookRouter {
+	handlers = /* @__PURE__ */ new Map();
+	verify;
+	globalBeforeHooks = [];
+	globalAfterHooks = [];
+	globalErrorHook;
+	prefix;
+	prefixWithSlash;
+	/**
+	* Creates a webhook router with optional global hooks and verification behavior.
+	*
+	* @param opts - Router-level options.
+	*/
+	constructor(opts = {}) {
+		this.prefix = normalizePath(opts.prefix ?? "/webhooks");
+		this.prefixWithSlash = `${this.prefix}/`;
+		this.verify = opts.verify;
+		this.globalBeforeHooks = toArray(opts.before);
+		this.globalAfterHooks = toArray(opts.after);
+		this.globalErrorHook = opts.onError;
+	}
+	register(path, handlerOrOptions) {
+		this.handlers.set(normalizePath(path), typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : WebhookRouter.createHandlerEntry(handlerOrOptions));
+		return this;
+	}
+	/**
+	* 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.
+	*/
+	async handle(request) {
+		const path = this.matchPath(request);
+		if (path === null) return notFoundResponse();
+		const handlerEntry = this.handlers.get(path);
+		if (!handlerEntry) return notFoundResponse();
+		const ctx = {
+			path,
+			rawBody: /* @__PURE__ */ new Uint8Array(0),
+			request
+		};
+		try {
+			ctx.rawBody = new Uint8Array(await request.arrayBuffer());
+			await WebhookRouter.runBeforeHooks(ctx, this.globalBeforeHooks);
+			await WebhookRouter.runBeforeHooks(ctx, handlerEntry.before);
+			if (this.verify) await this.verify(ctx);
+			const parsedJson = WebhookRouter.parseRequestBody(ctx);
+			const validationResult = await WebhookRouter.validatePayload(parsedJson, handlerEntry.schema);
+			if (validationResult instanceof Response) return validationResult;
+			const response = await WebhookRouter.executeHandler(handlerEntry.handler, ctx, validationResult);
+			await WebhookRouter.runAfterHooks(ctx, response, handlerEntry.after);
+			await WebhookRouter.runAfterHooks(ctx, response, this.globalAfterHooks);
+			return response;
+		} catch (error) {
+			return await this.handleError(error, ctx);
+		}
+	}
+	matchPath(request) {
+		const pathname = normalizePath(new URL(request.url).pathname);
+		if (this.prefix === "/") return pathname;
+		if (pathname === this.prefix) return "/";
+		if (!pathname.startsWith(this.prefixWithSlash)) return null;
+		return pathname.slice(this.prefix.length);
+	}
+	static async runBeforeHooks(ctx, hooks) {
+		if (!hooks || hooks.length === 0) return;
+		for (const hook of hooks) await hook(ctx);
+	}
+	static async runAfterHooks(ctx, response, hooks) {
+		if (!hooks || hooks.length === 0) return;
+		for (const hook of hooks) await hook(ctx, response);
+	}
+	static createHandlerEntry(options) {
+		const entry = { handler: options.handler };
+		if (options.schema !== void 0) entry.schema = options.schema;
+		if (options.before !== void 0) entry.before = Array.isArray(options.before) ? options.before : [options.before];
+		if (options.after !== void 0) entry.after = Array.isArray(options.after) ? options.after : [options.after];
+		return entry;
+	}
+	static parseRequestBody(ctx) {
+		try {
+			return JSON.parse(bodyDecoder.decode(ctx.rawBody));
+		} catch {
+			return;
+		}
+	}
+	static async validatePayload(parsedJson, schema) {
+		if (!schema) return parsedJson;
+		const result = await standardValidate(schema, parsedJson, { throwOnError: false });
+		if (result.issues) return Response.json({
+			error: "validation failed",
+			issues: result.issues.map((issue) => ({
+				message: issue.message,
+				path: issue.path?.map((p) => typeof p === "object" && "key" in p ? String(p.key) : String(p))
+			}))
+		}, { status: 400 });
+		return result.value;
+	}
+	static async executeHandler(handler, ctx, validatedPayload) {
+		return await handler({
+			...ctx,
+			payload: validatedPayload
+		}) ?? Response.json("ok");
+	}
+	async handleError(error, ctx) {
+		if (this.globalErrorHook) {
+			const normalizedError = error instanceof Error ? error : /* @__PURE__ */ new Error("Internal server error");
+			const errorResponse = await this.globalErrorHook(normalizedError, ctx);
+			if (errorResponse) return errorResponse;
+		}
+		return Response.json({ error: error instanceof Error ? error.message : "Internal server error" }, { status: 500 });
+	}
+};
+/**
+* Factory helper for creating a webhook router instance.
+*
+* @param opts - Optional global router options.
+* @returns A new webhook router.
+*/
+const createWebhookRouter = (opts) => new WebhookRouter(opts);
+//#endregion
+export { WebhookRouter, createWebhookRouter };
+
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","names":[],"sources":["../src/router.ts"],"sourcesContent":["/**\n * Schema-first webhook router primitives.\n *\n * @module @zap-studio/webhooks/router\n */\n\nimport type { StandardSchemaV1 } from \"@zap-studio/validation\";\nimport { standardValidate } from \"@zap-studio/validation\";\n\nimport type {\n  AfterHook,\n  BeforeHook,\n  ErrorHook,\n  InferSchemaOutput,\n  RegisterOptions,\n  SchemaRouteOptions,\n  VerifyFn,\n  WebhookContext,\n  WebhookHandler,\n} from \"./types.js\";\n\n/**\n * Schema-first webhook router with path dispatching, validation, and optional verification.\n *\n * @template TMap - Internal route payload map built incrementally via `register`.\n */\ninterface HandlerEntry<TPayload = unknown> {\n  after?: AfterHook[];\n  before?: BeforeHook[];\n  handler: WebhookHandler<TPayload>;\n  schema?: StandardSchemaV1<unknown, TPayload>;\n}\n\nexport interface WebhookRouterOptions {\n  /** Global hooks executed after successful route handler completion. */\n  after?: AfterHook | AfterHook[];\n  /** Global hooks executed before route-level hooks and verification. */\n  before?: BeforeHook | BeforeHook[];\n  /** Global error hook used to override the default `500` response. */\n  onError?: ErrorHook;\n  /**\n   * Required path prefix for all webhook routes. Defaults to `\"/webhooks\"`.\n   *\n   * Normalized internally: leading slash added, trailing slash stripped,\n   * duplicate slashes collapsed. Use `\"\"` or `\"/\"` to mount at the root.\n   */\n  prefix?: string;\n  /** Optional request verification function (for signature checks, auth, etc.). */\n  verify?: VerifyFn;\n}\n\nconst toArray = <T>(value: T | T[] | undefined): T[] => {\n  if (value === undefined) {\n    return [];\n  }\n\n  return Array.isArray(value) ? value : [value];\n};\n\nconst notFoundResponse = (): Response =>\n  Response.json({ error: \"not found\" }, { status: 404 });\n\nconst bodyDecoder = new TextDecoder();\n\n/**\n * Normalizes a path to its canonical form: leading slash, no trailing slash,\n * duplicate slashes collapsed. The root path is `\"/\"`.\n */\nconst normalizePath = (path: string): string => {\n  const withLeadingSlash = path.startsWith(\"/\") ? path : `/${path}`;\n  const collapsed = withLeadingSlash.includes(\"//\")\n    ? withLeadingSlash.replaceAll(/\\/{2,}/gu, \"/\")\n    : withLeadingSlash;\n\n  return collapsed.length > 1 && collapsed.endsWith(\"/\")\n    ? collapsed.slice(0, -1)\n    : collapsed;\n};\n\n/**\n * Main webhook router class.\n *\n * Register routes with typed schemas and call `handle` with a Web API `Request`.\n */\nexport class WebhookRouter<TMap = unknown> {\n  private readonly handlers = new Map<string, HandlerEntry>();\n  private readonly verify: VerifyFn | undefined;\n  private readonly globalBeforeHooks: BeforeHook[] = [];\n  private readonly globalAfterHooks: AfterHook[] = [];\n  private readonly globalErrorHook: ErrorHook | undefined;\n  private readonly prefix: string;\n  private readonly prefixWithSlash: string;\n\n  /**\n   * Creates a webhook router with optional global hooks and verification behavior.\n   *\n   * @param opts - Router-level options.\n   */\n  constructor(opts: WebhookRouterOptions = {}) {\n    this.prefix = normalizePath(opts.prefix ?? \"/webhooks\");\n    this.prefixWithSlash = `${this.prefix}/`;\n    this.verify = opts.verify;\n    this.globalBeforeHooks = toArray(opts.before);\n    this.globalAfterHooks = toArray(opts.after);\n    this.globalErrorHook = opts.onError;\n  }\n\n  /**\n   * Register a webhook handler for a specific path.\n   *\n   * When a schema is provided, `payload` is inferred from the schema output type.\n   *\n   * @param path - Route path relative to configured prefix, starting with `/` (e.g. `\"/stripe\"`).\n   * @param handlerOrOptions - Handler function or schema-based registration options.\n   * @returns The same router instance with an updated internal route type map.\n   */\n  register<\n    Path extends `/${string}`,\n    TSchema extends StandardSchemaV1<unknown, unknown>,\n  >(\n    path: Path,\n    handlerOrOptions: SchemaRouteOptions<TSchema>\n  ): WebhookRouter<TMap & Record<Path, InferSchemaOutput<TSchema>>>;\n  register<Path extends `/${string}`, TPayload>(\n    path: Path,\n    handlerOrOptions: RegisterOptions<TPayload>\n  ): WebhookRouter<TMap & Record<Path, TPayload>>;\n  register<Path extends `/${string}`>(\n    path: Path,\n    handlerOrOptions: WebhookHandler\n  ): WebhookRouter<TMap & Record<Path, unknown>>;\n  register(\n    path: string,\n    handlerOrOptions: WebhookHandler | RegisterOptions<unknown>\n  ): this {\n    this.handlers.set(\n      normalizePath(path),\n      typeof handlerOrOptions === \"function\"\n        ? { handler: handlerOrOptions }\n        : WebhookRouter.createHandlerEntry(handlerOrOptions)\n    );\n\n    return this;\n  }\n\n  /**\n   * Handles an incoming webhook request.\n   *\n   * The request body is read exactly once; hooks and handlers receive the raw\n   * bytes through the webhook context instead of the request stream.\n   *\n   * @param request - Incoming Web API request.\n   * @returns Web API response for the runtime to send back.\n   */\n  async handle(request: Request): Promise<Response> {\n    const path = this.matchPath(request);\n    if (path === null) {\n      return notFoundResponse();\n    }\n\n    const handlerEntry = this.handlers.get(path);\n    if (!handlerEntry) {\n      return notFoundResponse();\n    }\n\n    const ctx: WebhookContext = {\n      path,\n      rawBody: new Uint8Array(0),\n      request,\n    };\n\n    try {\n      ctx.rawBody = new Uint8Array(await request.arrayBuffer());\n\n      await WebhookRouter.runBeforeHooks(ctx, this.globalBeforeHooks);\n      await WebhookRouter.runBeforeHooks(ctx, handlerEntry.before);\n\n      if (this.verify) {\n        await this.verify(ctx);\n      }\n\n      const parsedJson = WebhookRouter.parseRequestBody(ctx);\n      const validationResult = await WebhookRouter.validatePayload(\n        parsedJson,\n        handlerEntry.schema\n      );\n\n      if (validationResult instanceof Response) {\n        return validationResult;\n      }\n\n      const response = await WebhookRouter.executeHandler(\n        handlerEntry.handler,\n        ctx,\n        validationResult\n      );\n\n      await WebhookRouter.runAfterHooks(ctx, response, handlerEntry.after);\n      await WebhookRouter.runAfterHooks(ctx, response, this.globalAfterHooks);\n\n      return response;\n    } catch (error) {\n      return await this.handleError(error, ctx);\n    }\n  }\n\n  private matchPath(request: Request): string | null {\n    const pathname = normalizePath(new URL(request.url).pathname);\n\n    // Root mount: the whole pathname is the route path.\n    if (this.prefix === \"/\") {\n      return pathname;\n    }\n\n    if (pathname === this.prefix) {\n      return \"/\";\n    }\n\n    // Require prefix followed by a segment boundary, then match handlers on\n    // the remainder (e.g. /webhooks/stripe -> /stripe).\n    if (!pathname.startsWith(this.prefixWithSlash)) {\n      return null;\n    }\n\n    return pathname.slice(this.prefix.length);\n  }\n\n  private static async runBeforeHooks(\n    ctx: WebhookContext,\n    hooks?: BeforeHook[]\n  ): Promise<void> {\n    if (!hooks || hooks.length === 0) {\n      return;\n    }\n\n    for (const hook of hooks) {\n      // oxlint-disable-next-line no-await-in-loop -- hooks run sequentially; order + short-circuit matter.\n      await hook(ctx);\n    }\n  }\n\n  private static async runAfterHooks(\n    ctx: WebhookContext,\n    response: Response,\n    hooks?: AfterHook[]\n  ): Promise<void> {\n    if (!hooks || hooks.length === 0) {\n      return;\n    }\n\n    for (const hook of hooks) {\n      // oxlint-disable-next-line no-await-in-loop -- hooks run sequentially; order + short-circuit matter.\n      await hook(ctx, response);\n    }\n  }\n\n  private static createHandlerEntry(\n    options: RegisterOptions<unknown>\n  ): HandlerEntry {\n    const entry: HandlerEntry = {\n      handler: options.handler,\n    };\n\n    if (options.schema !== undefined) {\n      entry.schema = options.schema;\n    }\n\n    if (options.before !== undefined) {\n      entry.before = Array.isArray(options.before)\n        ? options.before\n        : [options.before];\n    }\n\n    if (options.after !== undefined) {\n      entry.after = Array.isArray(options.after)\n        ? options.after\n        : [options.after];\n    }\n\n    return entry;\n  }\n\n  private static parseRequestBody(ctx: WebhookContext): unknown {\n    try {\n      return JSON.parse(bodyDecoder.decode(ctx.rawBody)) as unknown;\n    } catch {\n      return undefined;\n    }\n  }\n\n  private static async validatePayload<TPayload>(\n    parsedJson: unknown,\n    schema?: StandardSchemaV1<unknown, TPayload>\n  ): Promise<TPayload | Response> {\n    if (!schema) {\n      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- Without a schema, caller-declared payload type is the route contract.\n      return parsedJson as TPayload;\n    }\n\n    const result = await standardValidate(schema, parsedJson, {\n      throwOnError: false,\n    });\n\n    if (result.issues) {\n      return Response.json(\n        {\n          error: \"validation failed\",\n          issues: result.issues.map((issue) => ({\n            message: issue.message,\n            path: issue.path?.map((p) =>\n              typeof p === \"object\" && \"key\" in p ? String(p.key) : String(p)\n            ),\n          })),\n        },\n        { status: 400 }\n      );\n    }\n\n    return result.value;\n  }\n\n  private static async executeHandler<TPayload = unknown>(\n    handler: WebhookHandler<TPayload>,\n    ctx: WebhookContext,\n    validatedPayload: TPayload\n  ): Promise<Response> {\n    const responded = await handler({\n      ...ctx,\n      payload: validatedPayload,\n    });\n\n    return responded ?? Response.json(\"ok\");\n  }\n\n  private async handleError(\n    error: unknown,\n    ctx: WebhookContext\n  ): Promise<Response> {\n    if (this.globalErrorHook) {\n      const normalizedError =\n        error instanceof Error ? error : new Error(\"Internal server error\");\n      const errorResponse = await this.globalErrorHook(normalizedError, ctx);\n      if (errorResponse) {\n        return errorResponse;\n      }\n    }\n\n    return Response.json(\n      {\n        error: error instanceof Error ? error.message : \"Internal server error\",\n      },\n      { status: 500 }\n    );\n  }\n}\n\n/**\n * Factory helper for creating a webhook router instance.\n *\n * @param opts - Optional global router options.\n * @returns A new webhook router.\n */\nexport const createWebhookRouter = (\n  opts?: WebhookRouterOptions\n): WebhookRouter => new WebhookRouter(opts);\n"],"mappings":"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"}