@zap-studio/webhooks 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @zap-studio/webhooks
 
+## 0.2.1
+
+### Fixed
+
+- 3a950dc: Preserve registered hook assignment types while keeping the schema-first router API unchanged.
+
+### Changed
+
+- 5fa58b1: Reduced webhook router complexity by consolidating hook normalization and handler entry creation.
+- 7004e9f: Allow explicit `undefined` in option handling, then follow with d707800 to remove redundant `| undefined` unions from public types.
+- 9f31f87: Switched the package build to ESNext-aligned output and updated package tooling and publish metadata.
+
+### Dependencies
+
+- Updated dependency `@zap-studio/validation` to `0.3.3`.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -21,10 +21,10 @@ interface WebhookRouterOptions {
 */
 declare class WebhookRouter<TMap = unknown> {
   private readonly handlers;
-  private readonly verify?;
+  private readonly verify;
   private readonly globalBeforeHooks;
   private readonly globalAfterHooks;
-  private readonly globalErrorHook?;
+  private readonly globalErrorHook;
   private readonly prefix;
   constructor(opts?: WebhookRouterOptions);
   /**
@@ -48,6 +48,7 @@ declare class WebhookRouter<TMap = unknown> {
   handle(req: NormalizedRequest): Promise<NormalizedResponse>;
   private normalizePath;
   private runGlobalBeforeHooks;
+  private createHandlerEntry;
   private runRouteBeforeHooks;
   private parseRequestBody;
   private isErrorResponse;

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;UA6BiB,oBAAA;;EAEf,KAAA,GAAQ,SAAA,GAAY,SAAA;EAFL;EAIf,MAAA,GAAS,UAAA,GAAa,UAAA;;EAEtB,OAAA,GAAU,SAAA;;EAEV,MAAA;;EAEA,MAAA,IAAU,GAAA,EAAK,iBAAA,KAAsB,OAAA;AAAA;;;;;;cAQ1B,aAAA;EAAA,iBACM,QAAA;EAAA,iBACA,MAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,gBAAA;EAAA,iBACA,eAAA;EAAA,iBACA,MAAA;EAEjB,WAAA,CAAY,IAAA,GAAO,oBAAA;;;;;AARrB;;;;;EAkCE,QAAA,sCAA8C,gBAAA,mBAAA,CAC5C,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,kBAAA,CAAmB,OAAA,IACpC,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA,EAAM,iBAAA,CAAkB,OAAA;EACvD,QAAA,+BAAA,CACE,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,eAAA,CAAgB,QAAA,IACjC,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA,EAAM,QAAA;EACrC,QAAA,qBAAA,CACE,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,cAAA,YACjB,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA;;;;;;;EAkD/B,MAAA,CAAa,GAAA,EAAK,iBAAA,GAAoB,OAAA,CAAQ,kBAAA;EAAA,QAsCtC,aAAA;EAAA,QA0BM,oBAAA;EAAA,QAMA,mBAAA;EAAA,QAQN,gBAAA;EAAA,QAUA,eAAA;EAAA,QASM,eAAA;EAAA,QA8BA,cAAA;EAAA,QAyBA,kBAAA;EAAA,QAYA,mBAAA;EAAA,QASA,WAAA;AAAA;;;;;;;iBA0BA,mBAAA,CAAoB,IAAA,GAAO,oBAAA,GAAuB,aAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;;;UA6BiB,oBAAA;;EAEf,KAAA,GAAQ,SAAA,GAAY,SAAA;EAFL;EAIf,MAAA,GAAS,UAAA,GAAa,UAAA;;EAEtB,OAAA,GAAU,SAAA;;EAEV,MAAA;;EAEA,MAAA,IAAU,GAAA,EAAK,iBAAA,KAAsB,OAAA;AAAA;;;;;;cAgB1B,aAAA;EAAA,iBACM,QAAA;EAAA,iBACA,MAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,gBAAA;EAAA,iBACA,eAAA;EAAA,iBACA,MAAA;EAEjB,WAAA,CAAY,IAAA,GAAM,oBAAA;;;;;AARpB;;;;;EAyBE,QAAA,sCAA8C,gBAAA,mBAAA,CAC5C,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,kBAAA,CAAmB,OAAA,IACpC,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA,EAAM,iBAAA,CAAkB,OAAA;EACvD,QAAA,+BAAA,CACE,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,eAAA,CAAgB,QAAA,IACjC,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA,EAAM,QAAA;EACrC,QAAA,qBAAA,CACE,IAAA,EAAM,IAAA,EACN,gBAAA,EAAkB,cAAA,YACjB,aAAA,CAAc,IAAA,GAAO,MAAA,CAAO,IAAA;;;;;;;EAoB/B,MAAA,CAAa,GAAA,EAAK,iBAAA,GAAoB,OAAA,CAAQ,kBAAA;EAAA,QAsCtC,aAAA;EAAA,QA0BM,oBAAA;EAAA,QAMN,kBAAA;EAAA,QAoBM,mBAAA;EAAA,QAQN,gBAAA;EAAA,QAUA,eAAA;EAAA,QASM,eAAA;EAAA,QA8BA,cAAA;EAAA,QAyBA,kBAAA;EAAA,QAYA,mBAAA;EAAA,QASA,WAAA;AAAA;;;;;;;iBA0BA,mBAAA,CAAoB,IAAA,GAAO,oBAAA,GAAuB,aAAA"}

package/dist/index.mjs

@@ -1,5 +1,9 @@
 import { standardValidate } from "@zap-studio/validation";
 //#region src/index.ts
+function toArray(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
 /**
 * Main webhook router class.
 *
@@ -12,26 +16,16 @@ var WebhookRouter = class {
 	globalAfterHooks = [];
 	globalErrorHook;
 	prefix;
-	constructor(opts) {
-		this.prefix = opts?.prefix ?? "/webhooks/";
-		if (opts?.verify) this.verify = opts.verify;
-		if (opts?.before) this.globalBeforeHooks = Array.isArray(opts.before) ? opts.before : [opts.before];
-		if (opts?.after) this.globalAfterHooks = Array.isArray(opts.after) ? opts.after : [opts.after];
-		if (opts?.onError) this.globalErrorHook = opts.onError;
+	constructor(opts = {}) {
+		this.prefix = opts.prefix ?? "/webhooks/";
+		this.verify = opts.verify;
+		this.globalBeforeHooks = toArray(opts.before);
+		this.globalAfterHooks = toArray(opts.after);
+		this.globalErrorHook = opts.onError;
 	}
 	register(path, handlerOrOptions) {
 		if (typeof handlerOrOptions === "function") this.handlers[path] = { handler: handlerOrOptions };
-		else {
-			let beforeHooks;
-			if (handlerOrOptions.before) beforeHooks = Array.isArray(handlerOrOptions.before) ? handlerOrOptions.before : [handlerOrOptions.before];
-			let afterHooks;
-			if (handlerOrOptions.after) afterHooks = Array.isArray(handlerOrOptions.after) ? handlerOrOptions.after : [handlerOrOptions.after];
-			const entry = { handler: handlerOrOptions.handler };
-			if (handlerOrOptions.schema !== void 0) entry.schema = handlerOrOptions.schema;
-			if (beforeHooks !== void 0) entry.before = beforeHooks;
-			if (afterHooks !== void 0) entry.after = afterHooks;
-			this.handlers[path] = entry;
-		}
+		else this.handlers[path] = this.createHandlerEntry(handlerOrOptions);
 		return this;
 	}
 	/**
@@ -79,6 +73,13 @@ var WebhookRouter = class {
 	async runGlobalBeforeHooks(req) {
 		for (const hook of this.globalBeforeHooks) await hook(req);
 	}
+	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;
+	}
 	async runRouteBeforeHooks(req, before) {
 		if (before) for (const hook of before) await hook(req);
 	}

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@zap-studio/validation\";\nimport { standardValidate } from \"@zap-studio/validation\";\nimport type {\n  AfterHook,\n  BeforeHook,\n  ErrorHook,\n  InferSchemaOutput,\n  NormalizedRequest,\n  NormalizedResponse,\n  RegisterOptions,\n  SchemaRouteOptions,\n  WebhookHandler,\n} from \"./types/index.js\";\n\n/**\n * Schema-first webhook router with path dispatching, validation, and optional verification.\n *\n * @typeParam TMap - Internal route payload map built incrementally via `register`.\n */\n\ninterface HandlerEntry<TPayload = unknown> {\n  after?: AfterHook[];\n  before?: BeforeHook[];\n  handler: WebhookHandler<TPayload>;\n  schema?: StandardSchemaV1<unknown, TPayload>;\n}\n\ntype HandlerStore = Record<string, HandlerEntry<unknown>>;\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  /** Required path prefix for all webhook routes. Defaults to `\"/webhooks/\"`. */\n  prefix?: string;\n  /** Optional request verification function (for signature checks, auth, etc.). */\n  verify?: (req: NormalizedRequest) => Promise<void> | void;\n}\n\n/**\n * Main webhook router class.\n *\n * Register routes with typed schemas and call `handle` with a normalized request.\n */\nexport class WebhookRouter<TMap = unknown> {\n  private readonly handlers: HandlerStore = {};\n  private readonly verify?: (req: NormalizedRequest) => Promise<void> | void;\n  private readonly globalBeforeHooks: BeforeHook[] = [];\n  private readonly globalAfterHooks: AfterHook[] = [];\n  private readonly globalErrorHook?: ErrorHook;\n  private readonly prefix: string;\n\n  constructor(opts?: WebhookRouterOptions) {\n    this.prefix = opts?.prefix ?? \"/webhooks/\";\n\n    if (opts?.verify) {\n      this.verify = opts.verify;\n    }\n    if (opts?.before) {\n      this.globalBeforeHooks = Array.isArray(opts.before) ? opts.before : [opts.before];\n    }\n    if (opts?.after) {\n      this.globalAfterHooks = Array.isArray(opts.after) ? opts.after : [opts.after];\n    }\n    if (opts?.onError) {\n      this.globalErrorHook = opts.onError;\n    }\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.\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<Path extends string, TSchema extends StandardSchemaV1<unknown, unknown>>(\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<unknown>,\n  ): WebhookRouter<TMap & Record<Path, unknown>>;\n  register(\n    path: string,\n    handlerOrOptions: WebhookHandler<unknown> | RegisterOptions<unknown>,\n  ): WebhookRouter<TMap> {\n    if (typeof handlerOrOptions === \"function\") {\n      this.handlers[path] = {\n        handler: handlerOrOptions,\n      };\n    } else {\n      let beforeHooks: BeforeHook[] | undefined;\n      if (handlerOrOptions.before) {\n        beforeHooks = Array.isArray(handlerOrOptions.before)\n          ? handlerOrOptions.before\n          : [handlerOrOptions.before];\n      }\n\n      let afterHooks: AfterHook[] | undefined;\n      if (handlerOrOptions.after) {\n        afterHooks = Array.isArray(handlerOrOptions.after)\n          ? handlerOrOptions.after\n          : [handlerOrOptions.after];\n      }\n\n      const entry: HandlerEntry<unknown> = {\n        handler: handlerOrOptions.handler,\n      };\n\n      if (handlerOrOptions.schema !== undefined) {\n        entry.schema = handlerOrOptions.schema;\n      }\n      if (beforeHooks !== undefined) {\n        entry.before = beforeHooks;\n      }\n      if (afterHooks !== undefined) {\n        entry.after = afterHooks;\n      }\n\n      this.handlers[path] = entry;\n    }\n\n    return this;\n  }\n\n  /**\n   * Handles a normalized incoming webhook request.\n   *\n   * @param req - Normalized request object.\n   * @returns Normalized response for the adapter/framework layer.\n   */\n  async handle(req: NormalizedRequest): Promise<NormalizedResponse> {\n    try {\n      const normalizedPath = this.normalizePath(req);\n\n      if (normalizedPath === null) {\n        return { status: 404, body: { error: \"not found\" } };\n      }\n\n      const handlerEntry = this.handlers[normalizedPath];\n      if (!handlerEntry) {\n        return { status: 404, body: { error: \"not found\" } };\n      }\n\n      await this.runGlobalBeforeHooks(req);\n      await this.runRouteBeforeHooks(req, handlerEntry.before);\n\n      if (this.verify) {\n        await this.verify(req);\n      }\n\n      const parsedJson = this.parseRequestBody(req);\n      const validationResult = await this.validatePayload(parsedJson, handlerEntry.schema);\n\n      if (this.isErrorResponse(validationResult)) {\n        return validationResult;\n      }\n\n      const response = await this.executeHandler(handlerEntry.handler, req, validationResult);\n\n      await this.runRouteAfterHooks(req, response, handlerEntry.after);\n      await this.runGlobalAfterHooks(req, response);\n\n      return response;\n    } catch (error) {\n      return this.handleError(error, req);\n    }\n  }\n\n  private normalizePath(req: NormalizedRequest): string | null {\n    let pathname = req.path;\n    try {\n      // Try to parse as URL (e.g. handles full URLs like https://example.com/webhooks/path -> /webhooks/path)\n      const url = new URL(req.path);\n      pathname = url.pathname;\n    } catch {\n      // Not a full URL, use the path as-is\n    }\n\n    // Require prefix (e.g. /webhooks/path -> /path)\n    if (!pathname.startsWith(this.prefix)) {\n      // Path doesn't start with the required prefix - not a webhook route\n      return null;\n    }\n\n    // Strip prefix and keep the leading slash\n    pathname = pathname.slice(this.prefix.length - 1);\n    req.path = pathname;\n\n    // Normalize path by removing leading slash for handler matching (e.g. /path -> path)\n    const normalizedPath = pathname.startsWith(\"/\") ? pathname.slice(1) : pathname;\n\n    return normalizedPath;\n  }\n\n  private async runGlobalBeforeHooks(req: NormalizedRequest): Promise<void> {\n    for (const hook of this.globalBeforeHooks) {\n      await hook(req);\n    }\n  }\n\n  private async runRouteBeforeHooks(req: NormalizedRequest, before?: BeforeHook[]): Promise<void> {\n    if (before) {\n      for (const hook of before) {\n        await hook(req);\n      }\n    }\n  }\n\n  private parseRequestBody<TParsed = unknown>(req: NormalizedRequest): TParsed | undefined {\n    try {\n      const parsed = JSON.parse(new TextDecoder().decode(req.rawBody));\n      req.json = parsed;\n      return parsed as TParsed;\n    } catch {\n      return;\n    }\n  }\n\n  private isErrorResponse(value: unknown): value is NormalizedResponse {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      \"status\" in value &&\n      typeof value.status === \"number\"\n    );\n  }\n\n  private async validatePayload<TPayload>(\n    parsedJson: unknown,\n    schema?: StandardSchemaV1<unknown, TPayload>,\n  ): Promise<TPayload | NormalizedResponse> {\n    if (!schema) {\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 {\n        status: 400,\n        body: {\n          error: \"validation failed\",\n          issues: result.issues.map((issue) => ({\n            path: issue.path?.map((p) =>\n              typeof p === \"object\" && \"key\" in p ? String(p.key) : String(p),\n            ),\n            message: issue.message,\n          })),\n        },\n      };\n    }\n\n    return result.value as TPayload;\n  }\n\n  private async executeHandler<TPayload = unknown>(\n    handler: WebhookHandler<TPayload>,\n    req: NormalizedRequest,\n    validatedPayload: TPayload,\n  ): Promise<NormalizedResponse> {\n    const responded = await handler({\n      req,\n      payload: validatedPayload,\n      ack: async (r?: Partial<NormalizedResponse>) => {\n        const response: NormalizedResponse = {\n          status: r?.status ?? 200,\n          body: r?.body ?? \"ok\",\n        };\n\n        if (r?.headers !== undefined) {\n          response.headers = r.headers;\n        }\n\n        return response;\n      },\n    });\n\n    return responded ?? { status: 200, body: \"ok\" };\n  }\n\n  private async runRouteAfterHooks(\n    req: NormalizedRequest,\n    response: NormalizedResponse,\n    after?: AfterHook[],\n  ): Promise<void> {\n    if (after) {\n      for (const hook of after) {\n        await hook(req, response);\n      }\n    }\n  }\n\n  private async runGlobalAfterHooks(\n    req: NormalizedRequest,\n    response: NormalizedResponse,\n  ): Promise<void> {\n    for (const hook of this.globalAfterHooks) {\n      await hook(req, response);\n    }\n  }\n\n  private async handleError<TError = unknown>(\n    error: TError,\n    req: NormalizedRequest,\n  ): Promise<NormalizedResponse> {\n    if (this.globalErrorHook) {\n      const errorResponse = await this.globalErrorHook(error as Error, req);\n      if (errorResponse) {\n        return errorResponse;\n      }\n    }\n\n    return {\n      status: 500,\n      body: {\n        error: error instanceof Error ? error.message : \"Internal server error\",\n      },\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 function createWebhookRouter(opts?: WebhookRouterOptions): WebhookRouter {\n  return new WebhookRouter(opts);\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@zap-studio/validation\";\nimport { standardValidate } from \"@zap-studio/validation\";\n\nimport type {\n  AfterHook,\n  BeforeHook,\n  ErrorHook,\n  InferSchemaOutput,\n  NormalizedRequest,\n  NormalizedResponse,\n  RegisterOptions,\n  SchemaRouteOptions,\n  WebhookHandler,\n} from \"./types/index.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\ntype HandlerStore = Record<string, HandlerEntry<unknown>>;\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  /** Required path prefix for all webhook routes. Defaults to `\"/webhooks/\"`. */\n  prefix?: string;\n  /** Optional request verification function (for signature checks, auth, etc.). */\n  verify?: (req: NormalizedRequest) => Promise<void> | void;\n}\n\nfunction toArray<T>(value: T | T[] | undefined): T[] {\n  if (value === undefined) {\n    return [];\n  }\n\n  return Array.isArray(value) ? value : [value];\n}\n\n/**\n * Main webhook router class.\n *\n * Register routes with typed schemas and call `handle` with a normalized request.\n */\nexport class WebhookRouter<TMap = unknown> {\n  private readonly handlers: HandlerStore = {};\n  private readonly verify: ((req: NormalizedRequest) => Promise<void> | void) | undefined;\n  private readonly globalBeforeHooks: BeforeHook[] = [];\n  private readonly globalAfterHooks: AfterHook[] = [];\n  private readonly globalErrorHook: ErrorHook | undefined;\n  private readonly prefix: string;\n\n  constructor(opts: WebhookRouterOptions = {}) {\n    this.prefix = opts.prefix ?? \"/webhooks/\";\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.\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<Path extends string, TSchema extends StandardSchemaV1<unknown, unknown>>(\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<unknown>,\n  ): WebhookRouter<TMap & Record<Path, unknown>>;\n  register(\n    path: string,\n    handlerOrOptions: WebhookHandler<unknown> | RegisterOptions<unknown>,\n  ): WebhookRouter<TMap> {\n    if (typeof handlerOrOptions === \"function\") {\n      this.handlers[path] = { handler: handlerOrOptions };\n    } else {\n      this.handlers[path] = this.createHandlerEntry(handlerOrOptions);\n    }\n\n    return this;\n  }\n\n  /**\n   * Handles a normalized incoming webhook request.\n   *\n   * @param req - Normalized request object.\n   * @returns Normalized response for the adapter/framework layer.\n   */\n  async handle(req: NormalizedRequest): Promise<NormalizedResponse> {\n    try {\n      const normalizedPath = this.normalizePath(req);\n\n      if (normalizedPath === null) {\n        return { status: 404, body: { error: \"not found\" } };\n      }\n\n      const handlerEntry = this.handlers[normalizedPath];\n      if (!handlerEntry) {\n        return { status: 404, body: { error: \"not found\" } };\n      }\n\n      await this.runGlobalBeforeHooks(req);\n      await this.runRouteBeforeHooks(req, handlerEntry.before);\n\n      if (this.verify) {\n        await this.verify(req);\n      }\n\n      const parsedJson = this.parseRequestBody(req);\n      const validationResult = await this.validatePayload(parsedJson, handlerEntry.schema);\n\n      if (this.isErrorResponse(validationResult)) {\n        return validationResult;\n      }\n\n      const response = await this.executeHandler(handlerEntry.handler, req, validationResult);\n\n      await this.runRouteAfterHooks(req, response, handlerEntry.after);\n      await this.runGlobalAfterHooks(req, response);\n\n      return response;\n    } catch (error) {\n      return this.handleError(error, req);\n    }\n  }\n\n  private normalizePath(req: NormalizedRequest): string | null {\n    let pathname = req.path;\n    try {\n      // Try to parse as URL (e.g. handles full URLs like https://example.com/webhooks/path -> /webhooks/path)\n      const url = new URL(req.path);\n      pathname = url.pathname;\n    } catch {\n      // Not a full URL, use the path as-is\n    }\n\n    // Require prefix (e.g. /webhooks/path -> /path)\n    if (!pathname.startsWith(this.prefix)) {\n      // Path doesn't start with the required prefix - not a webhook route\n      return null;\n    }\n\n    // Strip prefix and keep the leading slash\n    pathname = pathname.slice(this.prefix.length - 1);\n    req.path = pathname;\n\n    // Normalize path by removing leading slash for handler matching (e.g. /path -> path)\n    const normalizedPath = pathname.startsWith(\"/\") ? pathname.slice(1) : pathname;\n\n    return normalizedPath;\n  }\n\n  private async runGlobalBeforeHooks(req: NormalizedRequest): Promise<void> {\n    for (const hook of this.globalBeforeHooks) {\n      await hook(req);\n    }\n  }\n\n  private createHandlerEntry(options: RegisterOptions<unknown>): HandlerEntry<unknown> {\n    const entry: HandlerEntry<unknown> = {\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) ? options.before : [options.before];\n    }\n\n    if (options.after !== undefined) {\n      entry.after = Array.isArray(options.after) ? options.after : [options.after];\n    }\n\n    return entry;\n  }\n\n  private async runRouteBeforeHooks(req: NormalizedRequest, before?: BeforeHook[]): Promise<void> {\n    if (before) {\n      for (const hook of before) {\n        await hook(req);\n      }\n    }\n  }\n\n  private parseRequestBody<TParsed = unknown>(req: NormalizedRequest): TParsed | undefined {\n    try {\n      const parsed = JSON.parse(new TextDecoder().decode(req.rawBody));\n      req.json = parsed;\n      return parsed as TParsed;\n    } catch {\n      return;\n    }\n  }\n\n  private isErrorResponse(value: unknown): value is NormalizedResponse {\n    return (\n      typeof value === \"object\" &&\n      value !== null &&\n      \"status\" in value &&\n      typeof value.status === \"number\"\n    );\n  }\n\n  private async validatePayload<TPayload>(\n    parsedJson: unknown,\n    schema?: StandardSchemaV1<unknown, TPayload>,\n  ): Promise<TPayload | NormalizedResponse> {\n    if (!schema) {\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 {\n        status: 400,\n        body: {\n          error: \"validation failed\",\n          issues: result.issues.map((issue) => ({\n            path: issue.path?.map((p) =>\n              typeof p === \"object\" && \"key\" in p ? String(p.key) : String(p),\n            ),\n            message: issue.message,\n          })),\n        },\n      };\n    }\n\n    return result.value as TPayload;\n  }\n\n  private async executeHandler<TPayload = unknown>(\n    handler: WebhookHandler<TPayload>,\n    req: NormalizedRequest,\n    validatedPayload: TPayload,\n  ): Promise<NormalizedResponse> {\n    const responded = await handler({\n      req,\n      payload: validatedPayload,\n      ack: async (r?: Partial<NormalizedResponse>) => {\n        const response: NormalizedResponse = {\n          status: r?.status ?? 200,\n          body: r?.body ?? \"ok\",\n        };\n\n        if (r?.headers !== undefined) {\n          response.headers = r.headers;\n        }\n\n        return response;\n      },\n    });\n\n    return responded ?? { status: 200, body: \"ok\" };\n  }\n\n  private async runRouteAfterHooks(\n    req: NormalizedRequest,\n    response: NormalizedResponse,\n    after?: AfterHook[],\n  ): Promise<void> {\n    if (after) {\n      for (const hook of after) {\n        await hook(req, response);\n      }\n    }\n  }\n\n  private async runGlobalAfterHooks(\n    req: NormalizedRequest,\n    response: NormalizedResponse,\n  ): Promise<void> {\n    for (const hook of this.globalAfterHooks) {\n      await hook(req, response);\n    }\n  }\n\n  private async handleError<TError = unknown>(\n    error: TError,\n    req: NormalizedRequest,\n  ): Promise<NormalizedResponse> {\n    if (this.globalErrorHook) {\n      const errorResponse = await this.globalErrorHook(error as Error, req);\n      if (errorResponse) {\n        return errorResponse;\n      }\n    }\n\n    return {\n      status: 500,\n      body: {\n        error: error instanceof Error ? error.message : \"Internal server error\",\n      },\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 function createWebhookRouter(opts?: WebhookRouterOptions): WebhookRouter {\n  return new WebhookRouter(opts);\n}\n"],"mappings":"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"}

package/dist/types/index.d.mts

@@ -43,13 +43,13 @@ interface RegisterOptions<T> {
 /**
 * Infers the output type from a Standard Schema instance.
 *
-* @typeParam TSchema - A Standard Schema type.
+* @template TSchema - A Standard Schema type.
 */
 type InferSchemaOutput<TSchema> = TSchema extends StandardSchemaV1<unknown, infer TOutput> ? TOutput : never;
 /**
 * Route options where schema is required and handler payload is inferred.
 *
-* @typeParam TSchema - Schema used to infer handler payload type.
+* @template TSchema - Schema used to infer handler payload type.
 */
 type SchemaRouteOptions<TSchema extends StandardSchemaV1<unknown, unknown>> = Omit<RegisterOptions<InferSchemaOutput<TSchema>>, "schema"> & {
   schema: TSchema;
@@ -63,7 +63,7 @@ interface RouteLike {
 /**
 * Applies schema-driven payload inference to each route entry.
 *
-* @typeParam TRoutes - Route dictionary keyed by webhook path.
+* @template TRoutes - Route dictionary keyed by webhook path.
 */
 type SchemaRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: SchemaRouteOptions<TRoutes[P]["schema"]> };
 /** The webhook handler function, responsible for processing incoming webhook events. */
@@ -77,7 +77,7 @@ type HandlerMap<TMap extends Record<string, unknown>> = { [P in keyof TMap]: Web
 /**
 * Builds a webhook payload map from a schema-based route dictionary.
 *
-* @typeParam TRoutes - Route dictionary keyed by webhook path.
+* @template TRoutes - Route dictionary keyed by webhook path.
 */
 type InferWebhookMapFromRoutes<TRoutes extends Record<string, RouteLike>> = { [P in keyof TRoutes]: InferSchemaOutput<TRoutes[P]["schema"]> };
 /** Verification function for incoming requests */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zap-studio/webhooks",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "description": "A lightweight, type-safe webhook router with Standard Schema validation, signature verification, and lifecycle hooks.",
   "keywords": [
@@ -22,20 +22,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zap-studio/monorepo.git",
+    "url": "git+https://github.com/zap-studio/monorepo.git",
     "directory": "packages/webhooks"
   },
-  "bin": {
-    "intent": "./bin/intent.js"
-  },
   "files": [
     "dist",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md",
-    "skills",
-    "bin",
-    "!skills/_artifacts"
+    "README.md"
   ],
   "type": "module",
   "sideEffects": false,
@@ -53,15 +47,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@zap-studio/validation": "0.3.2"
+    "@zap-studio/validation": "0.3.3"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "typescript": "^5.9.3",
-    "vite-plus": "latest",
-    "zod": "^4.2.0",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.1.19",
+    "zod": "^4.3.6",
     "@zap-studio/typescript": "0.0.0"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
     "build": "vp pack",
     "test": "vp test run",

package/bin/intent.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-// Auto-generated by @tanstack/intent setup
-// Exposes the intent end-user CLI for consumers of this library.
-await import("@tanstack/intent/intent-library");

package/skills/zap-webhooks-routing-and-verification/SKILL.md

@@ -1,172 +0,0 @@
----
-name: zap-webhooks-routing-and-verification
-description: >
-  Build webhook ingestion with @zap-studio/webhooks using createWebhookRouter,
-  register path keys, prefix normalization, schema validation, lifecycle hooks,
-  createHmacVerifier, and BaseAdapter request/response mapping.
-type: core
-library: "@zap-studio/webhooks"
-library_version: "0.1.3"
-sources:
-  - "zap-studio/monorepo:packages/webhooks/README.md"
-  - "zap-studio/monorepo:packages/webhooks/src/index.ts"
-  - "zap-studio/monorepo:packages/webhooks/src/verify.ts"
-  - "zap-studio/monorepo:packages/webhooks/src/adapters/base.ts"
----
-
-# @zap-studio/webhooks — Routing and Verification
-
-## Setup
-
-```ts
-import { createWebhookRouter } from "@zap-studio/webhooks";
-import { createHmacVerifier } from "@zap-studio/webhooks/verify";
-import { z } from "zod";
-
-const router = createWebhookRouter({
-  prefix: "/webhooks/",
-  verify: createHmacVerifier({
-    headerName: "x-hub-signature-256",
-    secret: process.env.WEBHOOK_SECRET!,
-  }),
-});
-
-router.register("github/push", {
-  schema: z.object({ ref: z.string() }),
-  handler: async ({ payload, ack }) => {
-    console.log(payload.ref);
-    return ack({ status: 200, body: "ok" });
-  },
-});
-```
-
-## Core Patterns
-
-### Add global hooks for observability and error shaping
-
-```ts
-const router = createWebhookRouter({
-  before: (req) => {
-    console.log("incoming", req.path);
-  },
-  after: (_req, res) => {
-    console.log("status", res.status);
-  },
-  onError: (error) => ({
-    status: 500,
-    body: { error: error.message },
-  }),
-});
-```
-
-### Register route-specific hooks
-
-```ts
-router.register("payments/succeeded", {
-  schema: PaymentSchema,
-  before: (req) => {
-    req.headers.set("x-processed", "1");
-  },
-  after: (_req, res) => {
-    console.log("finished", res.status);
-  },
-  handler: async ({ payload, ack }) => ack({ body: { id: payload.id } }),
-});
-```
-
-### Implement an adapter with `BaseAdapter`
-
-```ts
-import { BaseAdapter } from "@zap-studio/webhooks/adapters/base";
-
-class MyAdapter extends BaseAdapter {
-  async toNormalizedRequest(req: Request) {
-    return {
-      method: req.method,
-      path: req.url,
-      headers: req.headers,
-      rawBody: Buffer.from(await req.text()),
-    };
-  }
-
-  async toFrameworkResponse(res: Response, normalized) {
-    return new Response(JSON.stringify(normalized.body), {
-      status: normalized.status,
-      headers: normalized.headers,
-    }) as unknown as Response;
-  }
-}
-```
-
-## Common Mistakes
-
-### HIGH Registering paths with leading slash
-
-Wrong:
-
-```ts
-router.register("/github/push", {
-  schema: PushSchema,
-  handler,
-});
-```
-
-Correct:
-
-```ts
-router.register("github/push", {
-  schema: PushSchema,
-  handler,
-});
-```
-
-Incoming paths normalize to slashless keys; leading slash route keys do not match and return 404.
-
-Source: zap-studio/monorepo:packages/webhooks/src/index.ts
-
-### CRITICAL Verifying a transformed payload instead of raw body
-
-Wrong:
-
-```ts
-const parsed = JSON.parse(req.rawBody.toString());
-await verifyProvider(JSON.stringify(parsed));
-```
-
-Correct:
-
-```ts
-await verify(req); // uses req.rawBody bytes
-const parsed = JSON.parse(req.rawBody.toString());
-```
-
-Signature checks must run on exact raw bytes; any parse/serialize transformation can invalidate signatures.
-
-Source: zap-studio/monorepo:packages/webhooks/src/verify.ts
-
-### HIGH Assuming `createHmacVerifier` is Node-only
-
-Wrong:
-
-```ts
-const verify = createHmacVerifier({
-  headerName: "x-signature",
-  secret: env.WEBHOOK_SECRET,
-});
-// used in edge runtime
-```
-
-Correct:
-
-```ts
-const verify = createHmacVerifier({
-  headerName: "x-signature",
-  secret: env.WEBHOOK_SECRET,
-});
-```
-
-`createHmacVerifier` uses the Web Crypto API and works across runtimes that expose `globalThis.crypto.subtle`.
-
-Source: zap-studio/monorepo:packages/webhooks/src/verify.ts
-
-See also: zap-validation-standard-schema/SKILL.md — payload validation result handling.