hono-webhooks 0.4.1 → 0.5.1

package/dist/otel.d.ts

@@ -1,8 +1,47 @@
-import { type Meter, type Tracer } from '@opentelemetry/api';
+import { type Meter, type Span, type Tracer } from '@opentelemetry/api';
 import type { Env } from 'hono';
 import { type WebhookEvent, type WebhookEventSummary, type WebhooksOptions } from 'hono-webhooks';
 /** The `route` label for 404s, which match no webhook. */
 export declare const UNMATCHED_ROUTE = "__unmatched__";
+/** A metric `otelWebhooks` records, described for a metric catalog. */
+export interface WebhookMetricDefinition {
+    name: string;
+    kind: 'counter' | 'histogram';
+    unit?: string;
+    description: string;
+    /** Attribute key to its closed set of values, or `'string'` when open. */
+    attributes: Record<string, readonly string[] | 'string'>;
+}
+/**
+ * The metrics `otelWebhooks` records, as data: list them in a metric
+ * catalog without creating a second recorder.
+ */
+export declare const webhookMetrics: readonly [{
+    readonly name: 'webhook_request_total';
+    readonly kind: 'counter';
+    readonly description: 'HTTP webhook requests by route template and status';
+    readonly attributes: {
+        readonly route: 'string';
+        readonly status: readonly ['success', 'failed'];
+    };
+}, {
+    readonly name: 'webhook_request_duration_ms';
+    readonly kind: 'histogram';
+    readonly unit: 'ms';
+    readonly description: 'HTTP webhook handler duration by route template and status';
+    readonly attributes: {
+        readonly route: 'string';
+        readonly status: readonly ['success', 'failed'];
+    };
+}];
+/** `summarizeEvent(event)` plus what a completion log needs. */
+export interface WebhookCall extends WebhookEventSummary {
+    /** `error` for 5xx, `warn` for 4xx, else `info`. */
+    level: 'info' | 'warn' | 'error';
+    outcome: 'success' | 'failed' | 'validation_failed';
+}
+/** `console` fits, as does any logger with these three methods. */
+export type WebhookLogger = Record<WebhookCall['level'], (message: string, fields: Record<string, string | number>) => void>;
 export interface OtelWebhooksOptions<E extends Env = any> {
     /** @default trace.getTracer('webhooks') */
     tracer?: Tracer;
@@ -15,7 +54,17 @@ export interface OtelWebhooksOptions<E extends Env = any> {
      * still active: log it, store it. A returned promise is handled like
      * `onEvent`'s.
      */
-    onWebhookCall?: (call: WebhookEventSummary, event: WebhookEvent<E>) => void | Promise<void>;
+    onWebhookCall?: (call: WebhookCall, event: WebhookEvent<E>) => void | Promise<void>;
+    /**
+     * Logs one `webhook.completed` event per request at `call.level`, with
+     * `route`, `method`, `status_code`, `duration_ms`, `status` (the outcome)
+     * and `error_type`. 404s and `ignoreRoutes` are skipped. Called with the
+     * request's span, so the logger can attach to it.
+     *
+     * @example
+     * logger: () => console
+     */
+    logger?: (span: Span) => WebhookLogger;
 }
 /**
  * `around` and `onEvent` that put each request in a server span and record

package/dist/otel.js

@@ -9,6 +9,25 @@ import {
   summarizeEvent
 } from "hono-webhooks";
 var UNMATCHED_ROUTE = "__unmatched__";
+var metricAttributes = {
+  route: "string",
+  status: ["success", "failed"]
+};
+var webhookMetrics = [
+  {
+    name: "webhook_request_total",
+    kind: "counter",
+    description: "HTTP webhook requests by route template and status",
+    attributes: metricAttributes
+  },
+  {
+    name: "webhook_request_duration_ms",
+    kind: "histogram",
+    unit: "ms",
+    description: "HTTP webhook handler duration by route template and status",
+    attributes: metricAttributes
+  }
+];
 function otelWebhooks(options = {}) {
   const tracer = options.tracer ?? trace.getTracer("webhooks");
   const ignored = new Set(options.ignoreRoutes);
@@ -30,8 +49,13 @@ function otelWebhooks(options = {}) {
       });
     },
     onEvent: (event) => {
-      const call = summarizeEvent(event);
-      const success = call.status < 400;
+      const summary = summarizeEvent(event);
+      const success = summary.status < 400;
+      const call = {
+        ...summary,
+        level: summary.status >= 500 ? "error" : success ? "info" : "warn",
+        outcome: summary.validation ? "validation_failed" : success ? "success" : "failed"
+      };
       const span = spans.get(event.c);
       span?.setAttributes({
         "http.status_code": call.status,
@@ -47,7 +71,8 @@ function otelWebhooks(options = {}) {
       span?.setStatus({
         code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
       });
-      if (call.route === null || !ignored.has(call.route)) {
+      const isIgnored = call.route !== null && ignored.has(call.route);
+      if (!isIgnored) {
         instruments ??= createInstruments(options.meter ?? metrics.getMeter("webhooks"));
         const attributes = {
           route: call.route ?? UNMATCHED_ROUTE,
@@ -56,22 +81,35 @@ function otelWebhooks(options = {}) {
         instruments.total.add(1, attributes);
         instruments.duration.record(event.durationMs, attributes);
       }
+      if (span && options.logger && call.route !== null && !isIgnored) {
+        options.logger(span)[call.level]("webhook.completed", {
+          event: "webhook.completed",
+          route: call.route,
+          method: call.method,
+          status_code: call.status,
+          duration_ms: call.durationMs,
+          status: call.outcome,
+          ...call.error && { error_type: call.error.name }
+        });
+      }
       return options.onWebhookCall?.(call, event);
     }
   };
 }
 function createInstruments(meter) {
+  const [total, duration] = webhookMetrics;
   return {
-    total: meter.createCounter("webhook_request_total", {
-      description: "HTTP webhook requests by route template and status"
+    total: meter.createCounter(total.name, {
+      description: total.description
     }),
-    duration: meter.createHistogram("webhook_request_duration_ms", {
-      unit: "ms",
-      description: "HTTP webhook handler duration by route template and status"
+    duration: meter.createHistogram(duration.name, {
+      unit: duration.unit,
+      description: duration.description
     })
   };
 }
 export {
   UNMATCHED_ROUTE,
-  otelWebhooks
+  otelWebhooks,
+  webhookMetrics
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -88,7 +88,7 @@
     "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@types/bun": "^1.4.2",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "hanzio": "^3.1.0",
+    "hanzio": "^3.3.0",
     "hono": "^4.13.10",
     "husky": "^9.1.7",
     "typescript": "^7.0.2",

package/src/cli-commands.ts

@@ -2,7 +2,13 @@ import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { CliError, type CliWriter, defineCli, defineCommand } from 'hanzio/cli'
+import {
+	CliError,
+	CliUsageError,
+	type CommandContext,
+	defineCli,
+	defineCommand
+} from 'hanzio/cli'
 import { z } from 'zod'
 import {
 	createWebhooks,
@@ -78,193 +84,201 @@ const BUN_ONLY_ERRORS = new Set([
 /**
  * Under Node, a Bun project's TypeScript (extensionless imports, for one)
  * fails to load. Rerun the same command under Bun when it is installed and
- * return its exit code.
+ * exit with its code.
  */
-function rerunUnderBun(error: unknown, stderr: CliWriter): number {
+function rerunUnderBun(error: unknown): never {
 	const code = (error as { code?: string }).code
 	if (process.versions.bun || !code || !BUN_ONLY_ERRORS.has(code)) throw error
-	stderr.write(`Node can't load the module (${code}), trying Bun\n`)
+	process.stderr.write(`Node can't load the module (${code}), trying Bun\n`)
 	const run = spawnSync('bun', process.argv.slice(1), { stdio: 'inherit' })
 	if (run.error) {
 		throw new CliError(
 			'Bun is not installed either. Run the CLI with a runtime that can load your code, e.g. bunx --bun hono-webhooks ...'
 		)
 	}
-	return run.status ?? 1
+	process.exit(run.status ?? 1)
 }
 
-// One command with <module> <command> positionals: hanzio/cli reads command
-// names first, so it can't put the module before them.
-export const cli = defineCli({
-	name: 'hono-webhooks',
-	commands: defineCommand({
-		description: `<module> exports a createWebhooks() app or an array of webhooks, as default
-or named export.
+type Ctx = CommandContext<WebhooksApp>
 
-Commands:
-  list                  List the webhooks
-  schema <path>         Print the JSON Schemas of the webhooks at <path>
-  test <method> <path>  Send a request through the webhooks app
+const print = (ctx: Ctx, line: string) => ctx.stdout.write(`${line}\n`)
 
-Examples:
-  hono-webhooks ./src/webhooks.ts list
-  hono-webhooks ./src/webhooks.ts schema /orders/:id
-  hono-webhooks ./src/webhooks.ts test POST /orders/42 -b '{"total":10}'
-  hono-webhooks ./src/webhooks.ts test POST /shopify -b '{"id":1}' \\
-    -r ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET`,
-		input: z.object({
-			module: z
-				.string()
-				.optional()
-				.meta({ positional: true, description: 'Module with the webhooks' }),
-			command: z
-				.enum(['list', 'schema', 'test'])
-				.optional()
-				.meta({ positional: true, description: 'list, schema or test' }),
-			args: z.array(z.string()).meta({
-				positional: true,
-				description: 'schema: <path>, test: <method> <path>'
-			}),
-			preload: z.array(z.string()).meta({
-				alias: 'r',
-				description: 'Import a module first (e.g. to load secrets), repeatable'
-			}),
-			body: z.string().optional().meta({
-				alias: 'b',
-				description:
-					'test: request body (JSON sets content-type: application/json)'
-			}),
-			query: z.string().optional().meta({
-				alias: 'q',
-				description: 'test: query string, e.g. "a=1&b=2"'
-			}),
-			header: z.array(z.string()).meta({
-				alias: 'H',
-				description: 'test: request header "name: value", repeatable'
-			}),
-			sign: z
-				.string()
-				.optional()
-				.meta({
-					alias: 's',
-					description: `test: sign the body with ${Object.keys(schemes).join(', ')}`
-				}),
-			secretEnv: z.string().optional().meta({
-				alias: 'e',
-				description: 'test: environment variable holding the signing secret'
-			})
-		}),
-		async run(input, ctx) {
-			const print = (line: string) => ctx.stdout.write(`${line}\n`)
-			if (!input.module || !input.command) {
-				ctx.exitCode = await cli.run(['--help'], ctx)
-				return
-			}
-			let app: WebhooksApp
-			try {
-				for (const preload of input.preload) await importModule(preload)
-				app = await loadApp(input.module)
-			} catch (error) {
-				ctx.exitCode = rerunUnderBun(error, ctx.stderr)
-				return
-			}
+const list = defineCommand({
+	description: 'List the webhooks',
+	examples: ['hono-webhooks ./src/webhooks.ts list'],
+	run(_, ctx: Ctx) {
+		for (const { config } of ctx.context.webhooks) {
+			const validates = [
+				...(['params', 'query', 'headers', 'body'] as const).filter(
+					(key) => config[key]
+				),
+				...(config.verify ? ['signature'] : [])
+			].join(', ')
+			print(
+				ctx,
+				`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
+			)
+			if (validates) print(ctx, `        validates ${validates}`)
+		}
+	}
+})
 
-			if (input.command === 'list') {
-				for (const { config } of app.webhooks) {
-					const validates = [
-						...(['params', 'query', 'headers', 'body'] as const).filter(
-							(key) => config[key]
-						),
-						...(config.verify ? ['signature'] : [])
-					].join(', ')
-					print(
-						`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
-					)
-					if (validates) print(`        validates ${validates}`)
-				}
-				return
+const schema = defineCommand({
+	description: 'Print the JSON Schemas of the webhooks at <path>',
+	examples: ['hono-webhooks ./src/webhooks.ts schema /orders/:id'],
+	input: z.object({
+		path: z.string().meta({ positional: true, description: 'Webhook path' })
+	}),
+	run({ path }, ctx: Ctx) {
+		const app = ctx.context
+		const descriptions = describeWebhooks(app)
+		const indexes = app.webhooks.flatMap((w, i) =>
+			w.config.path === path ? [i] : []
+		)
+		if (!indexes.length) throw new CliError(`No webhook at ${path}`)
+		for (const i of indexes) {
+			const { config } = app.webhooks[i]!
+			print(ctx, `${config.method} ${config.path}`)
+			for (const part of [
+				'params',
+				'query',
+				'headers',
+				'body',
+				'response'
+			] as const) {
+				if (!config[part]) continue
+				const schema = descriptions[i]!.jsonSchema[part]
+				print(
+					ctx,
+					`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
+				)
 			}
+		}
+	}
+})
 
-			if (input.command === 'schema') {
-				const [path] = input.args
-				const descriptions = describeWebhooks(app)
-				const indexes = app.webhooks.flatMap((w, i) =>
-					w.config.path === path ? [i] : []
+const testCommand = defineCommand({
+	description: 'Send a request through the webhooks app',
+	examples: [
+		`hono-webhooks ./src/webhooks.ts test POST /orders/42 -b '{"total":10}'`,
+		`hono-webhooks ./src/webhooks.ts test POST /shopify -b '{"id":1}' \\
+    -r ./src/secrets.ts --sign shopify --secret-env SHOPIFY_WEBHOOK_SECRET`
+	],
+	input: z.object({
+		method: z
+			.string()
+			.meta({ positional: true, description: 'HTTP method, e.g. POST' }),
+		path: z.string().meta({ positional: true, description: 'Request path' }),
+		body: z.string().optional().meta({
+			alias: 'b',
+			description: 'Request body (JSON sets content-type: application/json)'
+		}),
+		query: z.string().optional().meta({
+			alias: 'q',
+			description: 'Query string, e.g. "a=1&b=2"'
+		}),
+		header: z.array(z.string()).meta({
+			alias: 'H',
+			description: 'Request header "name: value", repeatable'
+		}),
+		sign: z
+			.string()
+			.optional()
+			.meta({
+				alias: 's',
+				description: `Sign the body: ${Object.keys(schemes).join(', ')}`
+			}),
+		secretEnv: z.string().optional().meta({
+			alias: 'e',
+			description: 'Environment variable holding the signing secret'
+		})
+	}),
+	async run(input, ctx: Ctx) {
+		const { method, path } = input
+		const headers = new Headers()
+		for (const header of input.header) {
+			const at = header.indexOf(':')
+			if (at < 1) {
+				throw new CliError(
+					`Header must look like "name: value", got "${header}"`
 				)
-				if (!indexes.length) throw new CliError(`No webhook at ${path}`)
-				for (const i of indexes) {
-					const { config } = app.webhooks[i]!
-					print(`${config.method} ${config.path}`)
-					for (const part of [
-						'params',
-						'query',
-						'headers',
-						'body',
-						'response'
-					] as const) {
-						if (!config[part]) continue
-						const schema = descriptions[i]!.jsonSchema[part]
-						print(
-							`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
-						)
-					}
-				}
-				return
 			}
-
-			const [method, path] = input.args
-			if (!method || !path) throw new CliError('Usage: test <method> <path>')
-			const headers = new Headers()
-			for (const header of input.header) {
-				const at = header.indexOf(':')
-				if (at < 1) {
-					throw new CliError(
-						`Header must look like "name: value", got "${header}"`
-					)
-				}
-				headers.set(header.slice(0, at).trim(), header.slice(at + 1).trim())
+			headers.set(header.slice(0, at).trim(), header.slice(at + 1).trim())
+		}
+		if (input.body && !headers.has('content-type')) {
+			try {
+				JSON.parse(input.body)
+				headers.set('content-type', 'application/json')
+			} catch {
+				headers.set('content-type', 'text/plain')
 			}
-			if (input.body && !headers.has('content-type')) {
-				try {
-					JSON.parse(input.body)
-					headers.set('content-type', 'application/json')
-				} catch {
-					headers.set('content-type', 'text/plain')
-				}
+		}
+		if (input.sign) {
+			const scheme = schemes[input.sign]
+			if (!scheme) {
+				throw new CliError(
+					`Unknown scheme "${input.sign}", use one of: ${Object.keys(schemes).join(', ')}`
+				)
 			}
-			if (input.sign) {
-				const scheme = schemes[input.sign]
-				if (!scheme) {
-					throw new CliError(
-						`Unknown scheme "${input.sign}", use one of: ${Object.keys(schemes).join(', ')}`
-					)
-				}
-				const name = input.secretEnv
-				if (!name) throw new CliError('--sign needs --secret-env <name>')
-				const secret = ctx.env[name]
-				if (secret === undefined) throw new CliError(`${name} is not set`)
-				for (const [key, value] of Object.entries(
-					await scheme.sign(input.body ?? '', secret)
-				)) {
-					headers.set(key, value)
-				}
+			const name = input.secretEnv
+			if (!name) throw new CliError('--sign needs --secret-env <name>')
+			const secret = ctx.env[name]
+			if (secret === undefined) throw new CliError(`${name} is not set`)
+			for (const [key, value] of Object.entries(
+				await scheme.sign(input.body ?? '', secret)
+			)) {
+				headers.set(key, value)
 			}
+		}
 
-			const url = `${path.startsWith('/') ? path : `/${path}`}${input.query ? `?${input.query}` : ''}`
-			const start = performance.now()
-			const res = await app.request(url, {
-				method: method.toUpperCase(),
-				headers,
-				body: input.body
-			})
-			const text = await res.text()
-			let body = text
-			try {
-				body = JSON.stringify(JSON.parse(text), null, 2)
-			} catch {}
-			print(`${res.status} (${(performance.now() - start).toFixed(1)}ms)`)
-			if (body) print(body)
-			if (!res.ok) ctx.exitCode = 1
+		const url = `${path.startsWith('/') ? path : `/${path}`}${input.query ? `?${input.query}` : ''}`
+		const start = performance.now()
+		const res = await ctx.context.request(url, {
+			method: method.toUpperCase(),
+			headers,
+			body: input.body
+		})
+		const text = await res.text()
+		let body = text
+		try {
+			body = JSON.stringify(JSON.parse(text), null, 2)
+		} catch {}
+		print(ctx, `${res.status} (${(performance.now() - start).toFixed(1)}ms)`)
+		if (body) print(ctx, body)
+		if (!res.ok) ctx.exitCode = 1
+	}
+})
+
+export const cli = defineCli({
+	name: 'hono-webhooks',
+	description: `<module> exports a createWebhooks() app or an array of webhooks, as default
+or named export.`,
+	globals: z.object({
+		module: z
+			.string()
+			.meta({ positional: true, description: 'Module with the webhooks' }),
+		preload: z.array(z.string()).meta({
+			alias: 'r',
+			description: 'Import a module first (e.g. to load secrets), repeatable'
+		})
+	}),
+	async context({ module, preload }) {
+		try {
+			for (const specifier of preload) await importModule(specifier)
+			return await loadApp(module)
+		} catch (error) {
+			return rerunUnderBun(error)
 		}
-	})
+	},
+	commands: { list, schema, test: testCommand },
+	onError(error, io) {
+		// No module or command: print help and succeed, as `--help` does.
+		if (error instanceof CliUsageError && error.kind === 'missing-command') {
+			io.stdout.write(error.help)
+			return 0
+		}
+		// Bad arguments exit 1 like every other failure.
+		const code = io.print()
+		return code === 2 ? 1 : code
+	}
 })

package/src/cli.ts

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
 import { cli } from './cli-commands'
 
-// hanzio/cli exits 2 on bad arguments; this CLI has always exited 1.
-const code = await cli.run()
-process.exitCode = code === 2 ? 1 : code
+process.exitCode = await cli.run()