hono-webhooks 0.4.0 → 0.5.0

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.0",
+  "version": "0.5.0",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -59,7 +59,8 @@
   },
   "scripts": {
     "build": "rm -rf dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/signatures.ts ./src/otel.ts ./src/cli.ts --outdir ./dist --target node --packages external",
+    "build:js": "bun build ./src/index.ts ./src/signatures.ts ./src/otel.ts --outdir ./dist --target node --packages external && bun run build:cli",
+    "build:cli": "bun build ./src/cli.ts --outdir ./dist --target node --external hono --external @standard-schema/spec",
     "build:types": "tsgo -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "test": "bun test",
@@ -87,6 +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",
     "hono": "^4.13.10",
     "husky": "^9.1.7",
     "typescript": "^7.0.2",

package/src/cli-commands.ts

@@ -0,0 +1,270 @@
+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 { z } from 'zod'
+import {
+	createWebhooks,
+	describeWebhooks,
+	type Webhook,
+	type WebhooksApp
+} from './index'
+import {
+	github,
+	type SignatureScheme,
+	shopify,
+	stripe,
+	svix
+} from './signatures'
+
+const schemes: Record<string, SignatureScheme<any, any>> = {
+	github,
+	shopify,
+	stripe,
+	svix
+}
+
+/** A file path relative to the cwd, or a package name. */
+const importModule = (specifier: string) =>
+	import(
+		existsSync(resolve(specifier))
+			? pathToFileURL(resolve(specifier)).href
+			: specifier
+	)
+
+function isWebhooksApp(value: unknown): value is WebhooksApp {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		Array.isArray((value as WebhooksApp).webhooks) &&
+		typeof (value as WebhooksApp).request === 'function'
+	)
+}
+
+function isWebhookArray(value: unknown): value is Webhook[] {
+	return (
+		Array.isArray(value) &&
+		value.length > 0 &&
+		value.every(
+			(item) =>
+				typeof item?.config?.path === 'string' &&
+				typeof item?.handler === 'function'
+		)
+	)
+}
+
+async function loadApp(path: string): Promise<WebhooksApp> {
+	const mod = await importModule(path)
+	const candidates = [mod.default, ...Object.values(mod)]
+	const app = candidates.find(isWebhooksApp)
+	if (app) return app
+	const webhooks = candidates.find(isWebhookArray)
+	if (webhooks) return createWebhooks(webhooks)
+	throw new CliError(
+		`${path} exports neither a createWebhooks() app nor an array of webhooks`
+	)
+}
+
+/** Errors Node gives for TypeScript it can't load but Bun can. */
+const BUN_ONLY_ERRORS = new Set([
+	'ERR_MODULE_NOT_FOUND',
+	'ERR_UNKNOWN_FILE_EXTENSION',
+	'ERR_UNSUPPORTED_DIR_IMPORT',
+	'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX',
+	'ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING'
+])
+
+/**
+ * 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.
+ */
+function rerunUnderBun(error: unknown, stderr: CliWriter): number {
+	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`)
+	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
+}
+
+// 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.
+
+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
+
+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
+			}
+
+			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
+			}
+
+			if (input.command === 'schema') {
+				const [path] = input.args
+				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(`${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())
+			}
+			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(', ')}`
+					)
+				}
+				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
+		}
+	})
+})