@zap-studio/webhooks 0.4.0 → 1.0.0

package/dist/router.js

@@ -1,5 +1,10 @@
 import { standardValidate } from "@zap-studio/validation";
 //#region src/router.ts
+/**
+* Schema-first webhook router with path dispatching, validation, and optional verification.
+*
+* @template TMap - Internal route payload map built incrementally via `register`.
+*/
 const toArray = (value) => {
 	if (value === void 0) return [];
 	return Array.isArray(value) ? value : [value];
@@ -15,12 +20,74 @@ const normalizePath = (path) => {
 	const collapsed = withLeadingSlash.includes("//") ? withLeadingSlash.replaceAll(/\/{2,}/gu, "/") : withLeadingSlash;
 	return collapsed.length > 1 && collapsed.endsWith("/") ? collapsed.slice(0, -1) : collapsed;
 };
+/** Runs the given before-hooks in order against the request context. */
+const runBeforeHooks = async (ctx, hooks) => {
+	if (!hooks || hooks.length === 0) return;
+	for (const hook of hooks) await hook(ctx);
+};
+/** Runs the given after-hooks in order against the request context and response. */
+const runAfterHooks = async (ctx, response, hooks) => {
+	if (!hooks || hooks.length === 0) return;
+	for (const hook of hooks) await hook(ctx, response);
+};
+/** Builds an internal handler entry from route registration options. */
+const createHandlerEntry = (options) => {
+	const entry = { handler: options.handler };
+	if (options.schema !== void 0) entry.schema = options.schema;
+	if (options.before !== void 0) entry.before = toArray(options.before);
+	if (options.after !== void 0) entry.after = toArray(options.after);
+	return entry;
+};
+/** Parses the request's raw body bytes as JSON, returning `undefined` on invalid JSON. */
+const parseRequestBody = (ctx) => {
+	try {
+		return JSON.parse(bodyDecoder.decode(ctx.rawBody));
+	} catch {
+		return;
+	}
+};
+/** Validates the parsed payload against the route schema, returning either the validated value or a `400` response. */
+const validatePayload = async (parsedJson, schema) => {
+	if (!schema) return parsedJson;
+	const result = await standardValidate(parsedJson, schema, { 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;
+};
+/** Invokes the route handler with the validated payload, defaulting to a `200 "ok"` response. */
+const executeHandler = async (handler, ctx, validatedPayload) => {
+	return await handler({
+		...ctx,
+		payload: validatedPayload
+	}) ?? Response.json("ok");
+};
 /**
 * 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) };
+* ```
 */
-var WebhookRouter = class WebhookRouter {
+var WebhookRouter = class {
 	handlers = /* @__PURE__ */ new Map();
 	verify;
 	globalBeforeHooks = [];
@@ -32,6 +99,15 @@ var WebhookRouter = class WebhookRouter {
 	* 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 = {}) {
 		this.prefix = normalizePath(opts.prefix ?? "/webhooks");
@@ -42,7 +118,7 @@ var WebhookRouter = class WebhookRouter {
 		this.globalErrorHook = opts.onError;
 	}
 	register(path, handlerOrOptions) {
-		this.handlers.set(normalizePath(path), typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : WebhookRouter.createHandlerEntry(handlerOrOptions));
+		this.handlers.set(normalizePath(path), typeof handlerOrOptions === "function" ? { handler: handlerOrOptions } : createHandlerEntry(handlerOrOptions));
 		return this;
 	}
 	/**
@@ -53,6 +129,14 @@ var WebhookRouter = class WebhookRouter {
 	*
 	* @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);
+	* }
+	* ```
 	*/
 	async handle(request) {
 		const path = this.matchPath(request);
@@ -66,20 +150,21 @@ var WebhookRouter = class WebhookRouter {
 		};
 		try {
 			ctx.rawBody = new Uint8Array(await request.arrayBuffer());
-			await WebhookRouter.runBeforeHooks(ctx, this.globalBeforeHooks);
-			await WebhookRouter.runBeforeHooks(ctx, handlerEntry.before);
+			await runBeforeHooks(ctx, this.globalBeforeHooks);
+			await runBeforeHooks(ctx, handlerEntry.before);
 			if (this.verify) await this.verify(ctx);
-			const parsedJson = WebhookRouter.parseRequestBody(ctx);
-			const validationResult = await WebhookRouter.validatePayload(parsedJson, handlerEntry.schema);
+			const parsedJson = parseRequestBody(ctx);
+			const validationResult = await 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);
+			const response = await executeHandler(handlerEntry.handler, ctx, validationResult);
+			await runAfterHooks(ctx, response, handlerEntry.after);
+			await runAfterHooks(ctx, response, this.globalAfterHooks);
 			return response;
 		} catch (error) {
 			return await this.handleError(error, ctx);
 		}
 	}
+	/** Resolves the incoming request's URL to a registered route key, or `null` if it doesn't match the configured prefix. */
 	matchPath(request) {
 		const pathname = normalizePath(new URL(request.url).pathname);
 		if (this.prefix === "/") return pathname;
@@ -87,46 +172,7 @@ var WebhookRouter = class WebhookRouter {
 		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");
-	}
+	/** Builds the error response for a failed request, deferring to the global error hook when set. */
 	async handleError(error, ctx) {
 		if (this.globalErrorHook) {
 			const normalizedError = error instanceof Error ? error : /* @__PURE__ */ new Error("Internal server error");
@@ -141,6 +187,14 @@ var WebhookRouter = class WebhookRouter {
 *
 * @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 });
+* ```
 */
 const createWebhookRouter = (opts) => new WebhookRouter(opts);
 //#endregion

package/dist/router.js.map

@@ -1 +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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"}
+{"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  HandlerEntry,\n  InferSchemaOutput,\n  RegisterOptions,\n  SchemaRouteOptions,\n  VerifyFn,\n  WebhookContext,\n  WebhookHandler,\n  WebhookRouterOptions,\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 */\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/** Runs the given before-hooks in order against the request context. */\nconst runBeforeHooks = async (\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/** Runs the given after-hooks in order against the request context and response. */\nconst runAfterHooks = async (\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/** Builds an internal handler entry from route registration options. */\nconst 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 = toArray(options.before);\n  }\n\n  if (options.after !== undefined) {\n    entry.after = toArray(options.after);\n  }\n\n  return entry;\n};\n\n/** Parses the request's raw body bytes as JSON, returning `undefined` on invalid JSON. */\nconst parseRequestBody = (ctx: WebhookContext): unknown => {\n  try {\n    return JSON.parse(bodyDecoder.decode(ctx.rawBody));\n  } catch {\n    return undefined;\n  }\n};\n\n/** Validates the parsed payload against the route schema, returning either the validated value or a `400` response. */\nconst validatePayload = async <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(parsedJson, schema, {\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/** Invokes the route handler with the validated payload, defaulting to a `200 \"ok\"` response. */\nconst executeHandler = async <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/**\n * Main webhook router class.\n *\n * Register routes with typed schemas and call `handle` with a Web API `Request`.\n *\n * @example\n * ```ts\n * import { WebhookRouter } from \"@zap-studio/webhooks\";\n *\n * const router = new WebhookRouter({ prefix: \"/webhooks\" });\n *\n * router.register(\"/stripe\", {\n *   schema: stripeEventSchema,\n *   handler: async ({ payload }) => {\n *     console.log(\"Stripe event:\", payload.type);\n *   },\n * });\n *\n * export default { fetch: (request: Request) => router.handle(request) };\n * ```\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   * @example\n   * ```ts\n   * const router = new WebhookRouter({\n   *   prefix: \"/webhooks\",\n   *   verify: createHmacVerifier({ headerName: \"x-signature\", secret }),\n   *   onError: (error) => Response.json({ error: error.message }, { status: 500 }),\n   * });\n   * ```\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   * @example\n   * ```ts\n   * router.register(\"/stripe\", {\n   *   schema: stripeEventSchema,\n   *   handler: async ({ payload }) => {\n   *     console.log(payload.type); // typed from stripeEventSchema\n   *   },\n   * });\n   * ```\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  /**\n   * Register a webhook handler for a specific path, with schema-less registration options.\n   *\n   * @param path - Route path relative to configured prefix, starting with `/` (e.g. `\"/stripe\"`).\n   * @param handlerOrOptions - Registration options without a schema.\n   * @returns The same router instance with an updated internal route type map.\n   *\n   * @example\n   * ```ts\n   * router.register(\"/ping\", {\n   *   before: (ctx) => console.log(\"received\", ctx.path),\n   *   handler: () => Response.json({ ok: true }),\n   * });\n   * ```\n   */\n  register<Path extends `/${string}`, TPayload>(\n    path: Path,\n    handlerOrOptions: RegisterOptions<TPayload>\n  ): WebhookRouter<TMap & Record<Path, TPayload>>;\n  /**\n   * Register a webhook handler for a specific path, using a plain handler function.\n   *\n   * @param path - Route path relative to configured prefix, starting with `/` (e.g. `\"/stripe\"`).\n   * @param handlerOrOptions - Handler function to process the webhook.\n   * @returns The same router instance with an updated internal route type map.\n   *\n   * @example\n   * ```ts\n   * router.register(\"/health\", () => Response.json({ status: \"ok\" }));\n   * ```\n   */\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        : 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   * @example\n   * ```ts\n   * // Framework-agnostic: works with any Web API Request/Response runtime.\n   * export async function POST(request: Request): Promise<Response> {\n   *   return router.handle(request);\n   * }\n   * ```\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 runBeforeHooks(ctx, this.globalBeforeHooks);\n      await runBeforeHooks(ctx, handlerEntry.before);\n\n      if (this.verify) {\n        await this.verify(ctx);\n      }\n\n      const parsedJson = parseRequestBody(ctx);\n      const validationResult = await validatePayload(\n        parsedJson,\n        handlerEntry.schema\n      );\n\n      if (validationResult instanceof Response) {\n        return validationResult;\n      }\n\n      const response = await executeHandler(\n        handlerEntry.handler,\n        ctx,\n        validationResult\n      );\n\n      await runAfterHooks(ctx, response, handlerEntry.after);\n      await runAfterHooks(ctx, response, this.globalAfterHooks);\n\n      return response;\n    } catch (error) {\n      return await this.handleError(error, ctx);\n    }\n  }\n\n  /** Resolves the incoming request's URL to a registered route key, or `null` if it doesn't match the configured prefix. */\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  /** Builds the error response for a failed request, deferring to the global error hook when set. */\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 *\n * @example\n * ```ts\n * import { createWebhookRouter } from \"@zap-studio/webhooks\";\n *\n * const router = createWebhookRouter({ prefix: \"/webhooks\" });\n * router.register(\"/stripe\", { schema: stripeEventSchema, handler });\n * ```\n */\nexport const createWebhookRouter = (\n  opts?: WebhookRouterOptions\n): WebhookRouter => new WebhookRouter(opts);\n"],"mappings":"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"}

package/dist/types.d.ts

@@ -5,6 +5,13 @@ import { StandardSchemaV1 } from "@zap-studio/validation";
  *
  * The router consumes the request body exactly once, so `request.body` is
  * already used by the time hooks or handlers run — read `rawBody` instead.
+ *
+ * @example
+ * ```ts
+ * const before: BeforeHook = (ctx: WebhookContext) => {
+ *   console.log("received", ctx.path);
+ * };
+ * ```
  */
 interface WebhookContext {
   /** The matched route key registered on the router (e.g. "stripe") */
@@ -18,12 +25,64 @@ interface WebhookContext {
  * Handler context extending the shared webhook context with the validated payload.
  *
  * @template TPayload - Validated payload type for the matched route.
+ *
+ * @example
+ * ```ts
+ * const handler: WebhookHandler<{ type: string }> = ({ payload }: HandlerContext<{ type: string }>) => {
+ *   console.log(payload.type);
+ * };
+ * ```
  */
 interface HandlerContext<TPayload = unknown> extends WebhookContext {
   /** The validated webhook payload */
   payload: TPayload;
 }
-/** Route registration options for a webhook handler. */
+/** Internal handler entry stored per registered route. */
+interface HandlerEntry<TPayload = unknown> {
+  after?: AfterHook[];
+  before?: BeforeHook[];
+  handler: WebhookHandler<TPayload>;
+  schema?: StandardSchemaV1<unknown, TPayload>;
+}
+/**
+ * Configuration options for creating a `WebhookRouter`.
+ *
+ * @example
+ * ```ts
+ * const options: WebhookRouterOptions = {
+ *   prefix: "/webhooks",
+ *   verify: createHmacVerifier({ headerName: "x-signature", secret }),
+ * };
+ * ```
+ */
+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;
+}
+/**
+ * Route registration options for a webhook handler.
+ *
+ * @example
+ * ```ts
+ * const options: RegisterOptions<{ type: string }> = {
+ *   schema: stripeEventSchema,
+ *   handler: ({ payload }) => console.log(payload.type),
+ * };
+ * ```
+ */
 interface RegisterOptions<T> {
   /** Hooks that run after successful processing (before global after hooks) */
   after?: AfterHook | AfterHook[];
@@ -44,10 +103,19 @@ type InferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1<unknown, infe
  * Route options where schema is required and handler payload is inferred.
  *
  * @template TSchema - Schema used to infer handler payload type.
+ *
+ * @example
+ * ```ts
+ * const stripeRoute: SchemaRouteOptions<typeof stripeEventSchema> = {
+ *   schema: stripeEventSchema,
+ *   handler: ({ payload }) => console.log(payload.type),
+ * };
+ * ```
  */
 type SchemaRouteOptions<TSchema extends StandardSchemaV1<unknown, unknown>> = Omit<RegisterOptions<InferSchemaOutput<TSchema>>, "schema"> & {
   schema: TSchema;
 };
+/** A single route's registration shape, as used by schema-driven route dictionaries. */
 interface RouteLike {
   after?: AfterHook | AfterHook[];
   before?: BeforeHook | BeforeHook[];
@@ -58,6 +126,13 @@ interface RouteLike {
  * Applies schema-driven payload inference to each route entry.
  *
  * @template TRoutes - Route dictionary keyed by webhook path.
+ *
+ * @example
+ * ```ts
+ * const routes: SchemaRoutes<{ "/stripe": { handler: WebhookHandler; schema: typeof stripeEventSchema } }> = {
+ *   "/stripe": { schema: stripeEventSchema, handler: ({ payload }) => console.log(payload.type) },
+ * };
+ * ```
  */
 type SchemaRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: SchemaRouteOptions<TRoutes[P]["schema"]>; };
 /**
@@ -65,29 +140,78 @@ type SchemaRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRo
  *
  * Return a `Response` to control the reply, or `undefined` to let the router
  * respond with its default `200` acknowledgement.
+ *
+ * @example
+ * ```ts
+ * const handler: WebhookHandler<{ type: string }> = ({ payload }) => {
+ *   console.log(payload.type);
+ * };
+ * ```
  */
 type WebhookHandler<TPayload = unknown> = (ctx: HandlerContext<TPayload>) => Promise<Response | undefined> | Response | undefined;
-/** Maps route keys to their payload-specific webhook handlers. */
+/**
+ * Maps route keys to their payload-specific webhook handlers.
+ *
+ * @example
+ * ```ts
+ * const handlers: HandlerMap<{ "/stripe": { type: string } }> = {
+ *   "/stripe": ({ payload }) => console.log(payload.type),
+ * };
+ * ```
+ */
 type HandlerMap<TMap extends Record<string, unknown>> = { [P in keyof TMap]: WebhookHandler<TMap[P]>; };
 /**
  * Builds a webhook payload map from a schema-based route dictionary.
  *
  * @template TRoutes - Route dictionary keyed by webhook path.
+ *
+ * @example
+ * ```ts
+ * type Payloads = InferWebhookMapFromRoutes<{
+ *   "/stripe": { handler: WebhookHandler; schema: typeof stripeEventSchema };
+ * }>;
+ * ```
  */
 type InferWebhookMapFromRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: InferSchemaOutput<TRoutes[P]["schema"]>; };
-/** Verification function for incoming requests. Throws to reject the request. */
+/**
+ * Verification function for incoming requests. Throws to reject the request.
+ *
+ * @example
+ * ```ts
+ * const verify: VerifyFn = createHmacVerifier({ headerName: "x-signature", secret });
+ * ```
+ */
 type VerifyFn = (ctx: WebhookContext) => Promise<void> | void;
-/** Hook function that runs before request processing */
+/**
+ * Hook function that runs before request processing
+ *
+ * @example
+ * ```ts
+ * const before: BeforeHook = (ctx) => console.log("received", ctx.path);
+ * ```
+ */
 type BeforeHook = (ctx: WebhookContext) => Promise<void> | void;
 /**
  * Hook function that runs after successful request processing.
  *
  * The hook receives the outgoing response as-is; call `response.clone()`
  * before reading its body to avoid consuming the stream sent to the client.
+ *
+ * @example
+ * ```ts
+ * const after: AfterHook = (ctx, response) => console.log(response.status);
+ * ```
  */
 type AfterHook = (ctx: WebhookContext, response: Response) => Promise<void> | void;
-/** Hook function that runs when an error occurs */
+/**
+ * Hook function that runs when an error occurs
+ *
+ * @example
+ * ```ts
+ * const onError: ErrorHook = (error) => Response.json({ error: error.message }, { status: 500 });
+ * ```
+ */
 type ErrorHook = (error: Error, ctx: WebhookContext) => Promise<Response | undefined> | Response | undefined;
 //#endregion
-export { AfterHook, BeforeHook, ErrorHook, HandlerContext, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, RegisterOptions, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookContext, WebhookHandler };
+export { AfterHook, BeforeHook, ErrorHook, HandlerContext, HandlerEntry, HandlerMap, InferSchemaOutput, InferWebhookMapFromRoutes, RegisterOptions, RouteLike, SchemaRouteOptions, SchemaRoutes, VerifyFn, WebhookContext, WebhookHandler, WebhookRouterOptions };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;UAciB;;EAEf;;EAEA,SAAS;;EAET,SAAS;;;;;;;UAQM,eAAe,4BAA4B;;EAE1D,SAAS;;;UAIM,gBAAgB;;EAE/B,QAAQ,YAAY;;EAEpB,SAAS,aAAa;;EAEtB,SAAS,eAAe;;EAExB,SAAS,0BAA0B;;;;;;;KAQzB,kBAAkB,WAC5B,gBAAgB,gCAAgC,WAAW;;;;;;KAOjD,mBACV,gBAAgB,sCACd,KAAK,gBAAgB,kBAAkB;EACzC,QAAQ;;UAGA;EACR,QAAQ,YAAY;EACpB,SAAS,aAAa;EACtB,SAAS;EACT,QAAQ;;;;;;;KAQE,aAAa,gBAAgB,eAAe,iBACrD,WAAW,UAAU,mBAAmB,QAAQ;;;;;;;KASvC,eAAe,uBACzB,KAAK,eAAe,cACjB,QAAQ,wBAAwB;;KAGzB,WAAW,aAAa,8BACjC,WAAW,OAAO,eAAe,KAAK;;;;;;KAQ7B,0BACV,gBAAgB,eAAe,iBAE9B,WAAW,UAAU,kBAAkB,QAAQ;;KAItC,YAAY,KAAK,mBAAmB;;KAGpC,cAAc,KAAK,mBAAmB;;;;;;;KAQtC,aACV,KAAK,gBACL,UAAU,aACP;;KAGO,aACV,OAAO,OACP,KAAK,mBACF,QAAQ,wBAAwB"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;;;;;;;;;;;;;;UAqBiB;;EAEf;;EAEA,SAAS;;EAET,SAAS;;;;;;;;;;;;;;UAeM,eAAe,4BAA4B;;EAE1D,SAAS;;;UAIM,aAAa;EAC5B,QAAQ;EACR,SAAS;EACT,SAAS,eAAe;EACxB,SAAS,0BAA0B;;;;;;;;;;;;;UAcpB;;EAEf,QAAQ,YAAY;;EAEpB,SAAS,aAAa;;EAEtB,UAAU;;;;;;;EAOV;;EAEA,SAAS;;;;;;;;;;;;;UAcM,gBAAgB;;EAE/B,QAAQ,YAAY;;EAEpB,SAAS,aAAa;;EAEtB,SAAS,eAAe;;EAExB,SAAS,0BAA0B;;;;;;;KAQzB,kBAAkB,WAC5B,gBAAgB,gCAAgC,WAAW;;;;;;;;;;;;;;KAejD,mBACV,gBAAgB,sCACd,KAAK,gBAAgB,kBAAkB;EACzC,QAAQ;;;UAIO;EACf,QAAQ,YAAY;EACpB,SAAS,aAAa;EACtB,SAAS;EACT,QAAQ;;;;;;;;;;;;;;KAeE,aAAa,gBAAgB,eAAe,iBACrD,WAAW,UAAU,mBAAmB,QAAQ;;;;;;;;;;;;;;KAgBvC,eAAe,uBACzB,KAAK,eAAe,cACjB,QAAQ,wBAAwB;;;;;;;;;;;KAYzB,WAAW,aAAa,8BACjC,WAAW,OAAO,eAAe,KAAK;;;;;;;;;;;;;KAe7B,0BACV,gBAAgB,eAAe,iBAE9B,WAAW,UAAU,kBAAkB,QAAQ;;;;;;;;;KAWtC,YAAY,KAAK,mBAAmB;;;;;;;;;KAUpC,cAAc,KAAK,mBAAmB;;;;;;;;;;;;KAatC,aACV,KAAK,gBACL,UAAU,aACP;;;;;;;;;KAUO,aACV,OAAO,OACP,KAAK,mBACF,QAAQ,wBAAwB"}

package/dist/verify.d.ts

@@ -1,5 +1,9 @@
 import { VerifyFn } from "./types.js";
 //#region src/verify.d.ts
+/**
+ * Compares two byte arrays in constant time to prevent timing attacks.
+ */
+declare const constantTimeEquals: (a: Uint8Array, b: Uint8Array) => boolean;
 declare const HMAC_HASH: {
   readonly sha1: "SHA-1";
   readonly sha256: "SHA-256";
@@ -45,5 +49,5 @@ declare const createHmacVerifier: ({ headerName, secret, algo }: {
   algo?: HmacAlgorithm;
 }) => VerifyFn;
 //#endregion
-export { createHmacVerifier };
+export { constantTimeEquals, createHmacVerifier };
 //# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","names":[],"sources":["../src/verify.ts"],"mappings":";;cAUM;WACJ;WACA;WACA;WACA;;KAGG,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2CrB,uBACX,YACA,QACA;EAEA;EACA;EACA,OAAO;MACL"}
+{"version":3,"file":"verify.d.ts","names":[],"sources":["../src/verify.ts"],"mappings":";;;;;cAYa,qBAAsB,GAAG,YAAY,GAAG;cAc/C;WACJ;WACA;WACA;WACA;;KAGG,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAuDrB,uBACX,YACA,QACA;EAEA;EACA;EACA,OAAO;MACL"}

package/dist/verify.js

@@ -1,19 +1,38 @@
 import { VerificationError } from "./errors.js";
-import { constantTimeEquals } from "./utils.js";
 //#region src/verify.ts
 /**
 * Signature verification helpers for webhook requests.
 *
 * @module @zap-studio/webhooks/verify
 */
+/**
+* Compares two byte arrays in constant time to prevent timing attacks.
+*/
+const constantTimeEquals = (a, b) => {
+	if (a.length !== b.length) return false;
+	let result = 0;
+	for (let i = 0; i < a.length; i += 1)
+ // v8 ignore next -- `?? 0` fallback is unreachable: a Uint8Array never holds `undefined` at an in-bounds index, this exists only to satisfy noUncheckedIndexedAccess.
+	result |= (a[i] ?? 0) ^ (b[i] ?? 0);
+	return result === 0;
+};
 const HMAC_HASH = {
 	sha1: "SHA-1",
 	sha256: "SHA-256",
 	sha384: "SHA-384",
 	sha512: "SHA-512"
 };
-const toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
-const normalizeSignature = (signature) => signature.replace(/^[a-z0-9-]+=/iu, "").trim().toLowerCase();
+const HEX_PATTERN = /^[0-9a-f]*$/iu;
+/**
+* Decodes a hex string into bytes, or `undefined` when it is not valid hex.
+*/
+const hexToBytes = (hex) => {
+	if (hex.length % 2 !== 0 || !HEX_PATTERN.test(hex)) return;
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let i = 0; i < bytes.length; i += 1) bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+	return bytes;
+};
+const normalizeSignature = (signature) => signature.replace(/^[a-z0-9-]+=/iu, "").trim();
 /**
 * Creates a webhook verifier that validates an HMAC signature from a request header.
 *
@@ -60,11 +79,12 @@ const createHmacVerifier = ({ headerName, secret, algo = "sha256" }) => {
 		if (actual === null || actual.length === 0) throw new VerificationError(`Missing signature header: ${headerName}`);
 		const key = await keyPromise;
 		const signature = await subtle.sign("HMAC", key, new Uint8Array(ctx.rawBody));
-		const expected = toHex(new Uint8Array(signature));
-		if (!constantTimeEquals(expected, normalizeSignature(actual))) throw new VerificationError(`Invalid signature for header: ${headerName}`);
+		const expected = new Uint8Array(signature);
+		const provided = hexToBytes(normalizeSignature(actual));
+		if (provided === void 0 || !constantTimeEquals(expected, provided)) throw new VerificationError(`Invalid signature for header: ${headerName}`);
 	};
 };
 //#endregion
-export { createHmacVerifier };
+export { constantTimeEquals, createHmacVerifier };
 
 //# sourceMappingURL=verify.js.map

package/dist/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","names":[],"sources":["../src/verify.ts"],"sourcesContent":["/**\n * Signature verification helpers for webhook requests.\n *\n * @module @zap-studio/webhooks/verify\n */\n\nimport { VerificationError } from \"./errors.js\";\nimport type { VerifyFn } from \"./types.js\";\nimport { constantTimeEquals } from \"./utils.js\";\n\nconst HMAC_HASH = {\n  sha1: \"SHA-1\",\n  sha256: \"SHA-256\",\n  sha384: \"SHA-384\",\n  sha512: \"SHA-512\",\n} as const;\n\ntype HmacAlgorithm = keyof typeof HMAC_HASH;\n\nconst toHex = (bytes: Uint8Array): string =>\n  Array.from(bytes, (byte) => byte.toString(16).padStart(2, \"0\")).join(\"\");\n\nconst normalizeSignature = (signature: string): string =>\n  signature\n    .replace(/^[a-z0-9-]+=/iu, \"\")\n    .trim()\n    .toLowerCase();\n\n/**\n * Creates a webhook verifier that validates an HMAC signature from a request header.\n *\n * The verifier imports the provided string secret once, computes an HMAC from\n * `ctx.rawBody`, normalizes the incoming header value, and compares both\n * signatures in constant time.\n *\n * Header values like `sha256=<hex>` are supported so common provider formats\n * such as GitHub work without extra parsing.\n *\n * @example\n * ```ts\n * import { createWebhookRouter } from \"@zap-studio/webhooks\";\n * import { createHmacVerifier } from \"@zap-studio/webhooks/verify\";\n *\n * const router = createWebhookRouter({\n *   verify: createHmacVerifier({\n *     headerName: \"x-hub-signature-256\",\n *     secret: process.env.GITHUB_WEBHOOK_SECRET!,\n *   }),\n * });\n * ```\n *\n * @param options - Verifier configuration.\n * @param options.headerName - Header containing the provider signature.\n * @param options.secret - Shared HMAC secret as a string.\n * @param options.algo - HMAC hash algorithm. Defaults to `\"sha256\"`.\n * @returns A router-compatible request verifier.\n *\n * @throws {VerificationError}\n * Thrown when verifier setup fails or request verification does not pass.\n */\nexport const createHmacVerifier = ({\n  headerName,\n  secret,\n  algo = \"sha256\",\n}: {\n  headerName: string;\n  secret: string;\n  algo?: HmacAlgorithm;\n}): VerifyFn => {\n  if (globalThis.crypto?.subtle === undefined) {\n    throw new VerificationError(\n      \"Web Crypto API is unavailable in this runtime\"\n    );\n  }\n\n  const { subtle } = globalThis.crypto;\n\n  const hash = HMAC_HASH[algo];\n  if (!hash) {\n    throw new VerificationError(`Unsupported HMAC algorithm: ${algo}`);\n  }\n\n  const keyPromise = subtle.importKey(\n    \"raw\",\n    new TextEncoder().encode(secret),\n    { hash, name: \"HMAC\" },\n    false,\n    [\"sign\"]\n  );\n\n  return async (ctx) => {\n    const actual = ctx.request.headers.get(headerName);\n    if (actual === null || actual.length === 0) {\n      throw new VerificationError(`Missing signature header: ${headerName}`);\n    }\n\n    const key = await keyPromise;\n    const signature = await subtle.sign(\n      \"HMAC\",\n      key,\n      new Uint8Array(ctx.rawBody)\n    );\n    const expected = toHex(new Uint8Array(signature));\n\n    if (!constantTimeEquals(expected, normalizeSignature(actual))) {\n      throw new VerificationError(\n        `Invalid signature for header: ${headerName}`\n      );\n    }\n  };\n};\n"],"mappings":";;;;;;;;AAUA,MAAM,YAAY;CAChB,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,QAAQ;AACV;AAIA,MAAM,SAAS,UACb,MAAM,KAAK,QAAQ,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;AAEzE,MAAM,sBAAsB,cAC1B,UACG,QAAQ,kBAAkB,EAAE,CAAC,CAC7B,KAAK,CAAC,CACN,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCjB,MAAa,sBAAsB,EACjC,YACA,QACA,OAAO,eAKO;CACd,IAAI,WAAW,QAAQ,WAAW,KAAA,GAChC,MAAM,IAAI,kBACR,+CACF;CAGF,MAAM,EAAE,WAAW,WAAW;CAE9B,MAAM,OAAO,UAAU;CACvB,IAAI,CAAC,MACH,MAAM,IAAI,kBAAkB,+BAA+B,MAAM;CAGnE,MAAM,aAAa,OAAO,UACxB,OACA,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,GAC/B;EAAE;EAAM,MAAM;CAAO,GACrB,OACA,CAAC,MAAM,CACT;CAEA,OAAO,OAAO,QAAQ;EACpB,MAAM,SAAS,IAAI,QAAQ,QAAQ,IAAI,UAAU;EACjD,IAAI,WAAW,QAAQ,OAAO,WAAW,GACvC,MAAM,IAAI,kBAAkB,6BAA6B,YAAY;EAGvE,MAAM,MAAM,MAAM;EAClB,MAAM,YAAY,MAAM,OAAO,KAC7B,QACA,KACA,IAAI,WAAW,IAAI,OAAO,CAC5B;EACA,MAAM,WAAW,MAAM,IAAI,WAAW,SAAS,CAAC;EAEhD,IAAI,CAAC,mBAAmB,UAAU,mBAAmB,MAAM,CAAC,GAC1D,MAAM,IAAI,kBACR,iCAAiC,YACnC;CAEJ;AACF"}
+{"version":3,"file":"verify.js","names":[],"sources":["../src/verify.ts"],"sourcesContent":["/**\n * Signature verification helpers for webhook requests.\n *\n * @module @zap-studio/webhooks/verify\n */\n\nimport { VerificationError } from \"./errors.js\";\nimport type { VerifyFn } from \"./types.js\";\n\n/**\n * Compares two byte arrays in constant time to prevent timing attacks.\n */\nexport const constantTimeEquals = (a: Uint8Array, b: Uint8Array): boolean => {\n  if (a.length !== b.length) {\n    return false;\n  }\n\n  let result = 0;\n  for (let i = 0; i < a.length; i += 1) {\n    // v8 ignore next -- `?? 0` fallback is unreachable: a Uint8Array never holds `undefined` at an in-bounds index, this exists only to satisfy noUncheckedIndexedAccess.\n    result |= (a[i] ?? 0) ^ (b[i] ?? 0); // oxlint-disable-line no-bitwise -- XOR is the constant-time compare trick.\n  }\n\n  return result === 0;\n};\n\nconst HMAC_HASH = {\n  sha1: \"SHA-1\",\n  sha256: \"SHA-256\",\n  sha384: \"SHA-384\",\n  sha512: \"SHA-512\",\n} as const;\n\ntype HmacAlgorithm = keyof typeof HMAC_HASH;\n\nconst HEX_PATTERN = /^[0-9a-f]*$/iu;\n\n/**\n * Decodes a hex string into bytes, or `undefined` when it is not valid hex.\n */\nconst hexToBytes = (hex: string): Uint8Array | undefined => {\n  if (hex.length % 2 !== 0 || !HEX_PATTERN.test(hex)) {\n    return undefined;\n  }\n\n  const bytes = new Uint8Array(hex.length / 2);\n  for (let i = 0; i < bytes.length; i += 1) {\n    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);\n  }\n\n  return bytes;\n};\n\nconst normalizeSignature = (signature: string): string =>\n  signature.replace(/^[a-z0-9-]+=/iu, \"\").trim();\n\n/**\n * Creates a webhook verifier that validates an HMAC signature from a request header.\n *\n * The verifier imports the provided string secret once, computes an HMAC from\n * `ctx.rawBody`, normalizes the incoming header value, and compares both\n * signatures in constant time.\n *\n * Header values like `sha256=<hex>` are supported so common provider formats\n * such as GitHub work without extra parsing.\n *\n * @example\n * ```ts\n * import { createWebhookRouter } from \"@zap-studio/webhooks\";\n * import { createHmacVerifier } from \"@zap-studio/webhooks/verify\";\n *\n * const router = createWebhookRouter({\n *   verify: createHmacVerifier({\n *     headerName: \"x-hub-signature-256\",\n *     secret: process.env.GITHUB_WEBHOOK_SECRET!,\n *   }),\n * });\n * ```\n *\n * @param options - Verifier configuration.\n * @param options.headerName - Header containing the provider signature.\n * @param options.secret - Shared HMAC secret as a string.\n * @param options.algo - HMAC hash algorithm. Defaults to `\"sha256\"`.\n * @returns A router-compatible request verifier.\n *\n * @throws {VerificationError}\n * Thrown when verifier setup fails or request verification does not pass.\n */\nexport const createHmacVerifier = ({\n  headerName,\n  secret,\n  algo = \"sha256\",\n}: {\n  headerName: string;\n  secret: string;\n  algo?: HmacAlgorithm;\n}): VerifyFn => {\n  if (globalThis.crypto?.subtle === undefined) {\n    throw new VerificationError(\n      \"Web Crypto API is unavailable in this runtime\"\n    );\n  }\n\n  const { subtle } = globalThis.crypto;\n\n  const hash = HMAC_HASH[algo];\n  if (!hash) {\n    throw new VerificationError(`Unsupported HMAC algorithm: ${algo}`);\n  }\n\n  const keyPromise = subtle.importKey(\n    \"raw\",\n    new TextEncoder().encode(secret),\n    { hash, name: \"HMAC\" },\n    false,\n    [\"sign\"]\n  );\n\n  return async (ctx) => {\n    const actual = ctx.request.headers.get(headerName);\n    if (actual === null || actual.length === 0) {\n      throw new VerificationError(`Missing signature header: ${headerName}`);\n    }\n\n    const key = await keyPromise;\n    const signature = await subtle.sign(\n      \"HMAC\",\n      key,\n      new Uint8Array(ctx.rawBody)\n    );\n    const expected = new Uint8Array(signature);\n    const provided = hexToBytes(normalizeSignature(actual));\n\n    if (provided === undefined || !constantTimeEquals(expected, provided)) {\n      throw new VerificationError(\n        `Invalid signature for header: ${headerName}`\n      );\n    }\n  };\n};\n"],"mappings":";;;;;;;;;;AAYA,MAAa,sBAAsB,GAAe,MAA2B;CAC3E,IAAI,EAAE,WAAW,EAAE,QACjB,OAAO;CAGT,IAAI,SAAS;CACb,KAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;;CAEjC,WAAW,EAAE,MAAM,MAAM,EAAE,MAAM;CAGnC,OAAO,WAAW;AACpB;AAEA,MAAM,YAAY;CAChB,MAAM;CACN,QAAQ;CACR,QAAQ;CACR,QAAQ;AACV;AAIA,MAAM,cAAc;;;;AAKpB,MAAM,cAAc,QAAwC;CAC1D,IAAI,IAAI,SAAS,MAAM,KAAK,CAAC,YAAY,KAAK,GAAG,GAC/C;CAGF,MAAM,QAAQ,IAAI,WAAW,IAAI,SAAS,CAAC;CAC3C,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,GACrC,MAAM,KAAK,OAAO,SAAS,IAAI,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE;CAG5D,OAAO;AACT;AAEA,MAAM,sBAAsB,cAC1B,UAAU,QAAQ,kBAAkB,EAAE,CAAC,CAAC,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkC/C,MAAa,sBAAsB,EACjC,YACA,QACA,OAAO,eAKO;CACd,IAAI,WAAW,QAAQ,WAAW,KAAA,GAChC,MAAM,IAAI,kBACR,+CACF;CAGF,MAAM,EAAE,WAAW,WAAW;CAE9B,MAAM,OAAO,UAAU;CACvB,IAAI,CAAC,MACH,MAAM,IAAI,kBAAkB,+BAA+B,MAAM;CAGnE,MAAM,aAAa,OAAO,UACxB,OACA,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,GAC/B;EAAE;EAAM,MAAM;CAAO,GACrB,OACA,CAAC,MAAM,CACT;CAEA,OAAO,OAAO,QAAQ;EACpB,MAAM,SAAS,IAAI,QAAQ,QAAQ,IAAI,UAAU;EACjD,IAAI,WAAW,QAAQ,OAAO,WAAW,GACvC,MAAM,IAAI,kBAAkB,6BAA6B,YAAY;EAGvE,MAAM,MAAM,MAAM;EAClB,MAAM,YAAY,MAAM,OAAO,KAC7B,QACA,KACA,IAAI,WAAW,IAAI,OAAO,CAC5B;EACA,MAAM,WAAW,IAAI,WAAW,SAAS;EACzC,MAAM,WAAW,WAAW,mBAAmB,MAAM,CAAC;EAEtD,IAAI,aAAa,KAAA,KAAa,CAAC,mBAAmB,UAAU,QAAQ,GAClE,MAAM,IAAI,kBACR,iCAAiC,YACnC;CAEJ;AACF"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zap-studio/webhooks",
-  "version": "0.4.0",
+  "version": "1.0.0",
   "private": false,
-  "description": "A lightweight, type-safe webhook router with Standard Schema validation, signature verification, and lifecycle hooks.",
+  "description": "A lightweight, type-safe, tree-shakeable webhook router with Standard Schema validation, signature verification, and lifecycle hooks.",
   "keywords": [
     "arktype",
     "lifecycle hooks",
@@ -39,7 +39,6 @@
     "./errors": "./dist/errors.js",
     "./router": "./dist/router.js",
     "./types": "./dist/types.js",
-    "./utils": "./dist/utils.js",
     "./verify": "./dist/verify.js",
     "./package.json": "./package.json"
   },
@@ -47,16 +46,16 @@
     "access": "public"
   },
   "dependencies": {
-    "@zap-studio/validation": "workspace:*"
+    "@zap-studio/validation": "1.0.0"
   },
   "devDependencies": {
-    "@zap-studio/typescript": "workspace:*",
-    "tsdown": "catalog:",
-    "typescript": "catalog:",
-    "vitest": "catalog:",
-    "zod": "catalog:"
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zap-studio/typescript": "0.0.0"
   },
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}