hono-webhooks 0.3.0 → 0.4.1

package/dist/otel.d.ts

@@ -0,0 +1,31 @@
+import { type Meter, 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__";
+export interface OtelWebhooksOptions<E extends Env = any> {
+    /** @default trace.getTracer('webhooks') */
+    tracer?: Tracer;
+    /** @default metrics.getMeter('webhooks'), resolved on the first request */
+    meter?: Meter;
+    /** Routes that get a span but no metrics, e.g. `['/health']`. */
+    ignoreRoutes?: readonly string[];
+    /**
+     * Called after every request, ignored routes included, with the span
+     * still active: log it, store it. A returned promise is handled like
+     * `onEvent`'s.
+     */
+    onWebhookCall?: (call: WebhookEventSummary, event: WebhookEvent<E>) => void | Promise<void>;
+}
+/**
+ * `around` and `onEvent` that put each request in a server span and record
+ * `webhook_request_total` and `webhook_request_duration_ms` by route and
+ * outcome.
+ *
+ * With `createWebhookFactory<AppEnv>()`, call `otelWebhooks<AppEnv>(...)`
+ * so `onWebhookCall` gets a typed context.
+ *
+ * @example
+ * createWebhooks(webhooks, { ...otelWebhooks({ ignoreRoutes: ['/health'] }), logErrors: false })
+ */
+export declare function otelWebhooks<E extends Env = any>(options?: OtelWebhooksOptions<E>): Required<Pick<WebhooksOptions<E>, 'around' | 'onEvent'>>;

package/dist/otel.js

@@ -0,0 +1,77 @@
+// src/otel.ts
+import {
+  metrics,
+  SpanKind,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+import {
+  summarizeEvent
+} from "hono-webhooks";
+var UNMATCHED_ROUTE = "__unmatched__";
+function otelWebhooks(options = {}) {
+  const tracer = options.tracer ?? trace.getTracer("webhooks");
+  const ignored = new Set(options.ignoreRoutes);
+  const spans = new WeakMap;
+  let instruments;
+  return {
+    around: ({ c, route, method }, next) => {
+      const label = route ?? UNMATCHED_ROUTE;
+      return tracer.startActiveSpan(`webhook: ${method} ${label}`, {
+        kind: SpanKind.SERVER,
+        attributes: { "http.method": method, "http.route": label }
+      }, async (span) => {
+        spans.set(c, span);
+        try {
+          return await next();
+        } finally {
+          span.end();
+        }
+      });
+    },
+    onEvent: (event) => {
+      const call = summarizeEvent(event);
+      const success = call.status < 400;
+      const span = spans.get(event.c);
+      span?.setAttributes({
+        "http.status_code": call.status,
+        "webhook.duration_ms": call.durationMs,
+        "webhook.success": success
+      });
+      if (call.validation) {
+        span?.setAttribute("webhook.validation_error", call.validation.message);
+      }
+      if (event.error instanceof Error && call.status >= 500) {
+        span?.recordException(event.error);
+      }
+      span?.setStatus({
+        code: success ? SpanStatusCode.OK : SpanStatusCode.ERROR
+      });
+      if (call.route === null || !ignored.has(call.route)) {
+        instruments ??= createInstruments(options.meter ?? metrics.getMeter("webhooks"));
+        const attributes = {
+          route: call.route ?? UNMATCHED_ROUTE,
+          status: success ? "success" : "failed"
+        };
+        instruments.total.add(1, attributes);
+        instruments.duration.record(event.durationMs, attributes);
+      }
+      return options.onWebhookCall?.(call, event);
+    }
+  };
+}
+function createInstruments(meter) {
+  return {
+    total: meter.createCounter("webhook_request_total", {
+      description: "HTTP webhook requests by route template and status"
+    }),
+    duration: meter.createHistogram("webhook_request_duration_ms", {
+      unit: "ms",
+      description: "HTTP webhook handler duration by route template and status"
+    })
+  };
+}
+export {
+  UNMATCHED_ROUTE,
+  otelWebhooks
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Type-safe webhook routes for Hono, validated with any Standard Schema library (Zod, Valibot, ArkType)",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,8 @@
     "valibot",
     "arktype",
     "typescript",
-    "type-safe"
+    "type-safe",
+    "opentelemetry"
   ],
   "files": [
     "src/**/*.ts",
@@ -48,11 +49,18 @@
       "bun": "./src/signatures.ts",
       "import": "./dist/signatures.js",
       "default": "./dist/signatures.js"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "bun": "./src/otel.ts",
+      "import": "./dist/otel.js",
+      "default": "./dist/otel.js"
     }
   },
   "scripts": {
     "build": "rm -rf dist && bun run build:js && bun run build:types",
-    "build:js": "bun build ./src/index.ts ./src/signatures.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",
@@ -65,12 +73,22 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "peerDependencies": {
-    "hono": "^4.8.0"
+    "hono": "^4.8.0",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-metrics": "^2.12.0",
+    "@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
+		}
+	})
+})

package/src/cli.ts

@@ -1,255 +1,6 @@
 #!/usr/bin/env node
-import { spawnSync } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-import { parseArgs } from 'node:util'
-import {
-	createWebhooks,
-	describeWebhooks,
-	type Webhook,
-	type WebhooksApp
-} from './index'
-import {
-	github,
-	type SignatureScheme,
-	shopify,
-	stripe,
-	svix
-} from './signatures'
+import { cli } from './cli-commands'
 
-const schemes: Record<string, SignatureScheme<any, any>> = {
-	github,
-	shopify,
-	stripe,
-	svix
-}
-
-const HELP = `Usage: hono-webhooks <module> <command> [options]
-
-<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
-
-Options:
-  -r, --preload <module>    Import a module first (e.g. to load secrets), repeatable
-
-Options for test:
-  -b, --body <text>         Request body (JSON sets content-type: application/json)
-  -q, --query <params>      Query string, e.g. "a=1&b=2"
-  -H, --header <k: v>       Request header, repeatable
-  -s, --sign <scheme>       Sign the body: ${Object.keys(schemes).join(', ')}
-  -e, --secret-env <name>   Environment variable holding the signing secret
-
-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
-`
-
-const { values, positionals } = parseArgs({
-	allowPositionals: true,
-	options: {
-		help: { type: 'boolean', short: 'h' },
-		preload: { type: 'string', short: 'r', multiple: true },
-		body: { type: 'string', short: 'b' },
-		query: { type: 'string', short: 'q' },
-		header: { type: 'string', short: 'H', multiple: true },
-		sign: { type: 'string', short: 's' },
-		'secret-env': { type: 'string', short: 'e' }
-	}
-})
-
-const [modulePath, command, ...args] = positionals
-
-function fail(message: string): never {
-	console.error(message)
-	process.exit(1)
-}
-
-/** 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)
-	return fail(
-		`${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.
- */
-function rerunUnderBun(error: unknown): never {
-	const code = (error as { code?: string }).code
-	if (process.versions.bun || !code || !BUN_ONLY_ERRORS.has(code)) throw error
-	console.error(`Node can't load the module (${code}), trying Bun`)
-	const run = spawnSync('bun', process.argv.slice(1), { stdio: 'inherit' })
-	if (run.error) {
-		fail(
-			'Bun is not installed either. Run the CLI with a runtime that can load your code, e.g. bunx --bun hono-webhooks ...'
-		)
-	}
-	process.exit(run.status ?? 1)
-}
-
-async function signatureHeaders(rawBody: string) {
-	if (!values.sign) return {}
-	const scheme =
-		schemes[values.sign] ??
-		fail(
-			`Unknown scheme "${values.sign}", use one of: ${Object.keys(schemes).join(', ')}`
-		)
-	const name = values['secret-env'] ?? fail('--sign needs --secret-env <name>')
-	const secret = process.env[name] ?? fail(`${name} is not set`)
-	return scheme.sign(rawBody, secret)
-}
-
-async function main() {
-	if (values.help || !modulePath || !command) {
-		console.log(HELP)
-		return
-	}
-	let app: WebhooksApp
-	try {
-		for (const preload of values.preload ?? []) await importModule(preload)
-		app = await loadApp(modulePath)
-	} catch (error) {
-		rerunUnderBun(error)
-	}
-
-	if (command === 'list') {
-		for (const { config } of app.webhooks) {
-			const validates = [
-				...(['params', 'query', 'headers', 'body'] as const).filter(
-					(key) => config[key]
-				),
-				...(config.verify ? ['signature'] : [])
-			].join(', ')
-			console.log(
-				`${config.method.padEnd(7)} ${config.path}${config.description ? `  ${config.description}` : ''}`
-			)
-			if (validates) console.log(`        validates ${validates}`)
-		}
-		return
-	}
-
-	if (command === 'schema') {
-		const [path] = args
-		const descriptions = describeWebhooks(app)
-		const indexes = app.webhooks.flatMap((w, i) =>
-			w.config.path === path ? [i] : []
-		)
-		if (!indexes.length) fail(`No webhook at ${path}`)
-		for (const i of indexes) {
-			const { config } = app.webhooks[i]!
-			console.log(`${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]
-				console.log(
-					`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
-				)
-			}
-		}
-		return
-	}
-
-	if (command === 'test') {
-		const [method, path] = args
-		if (!method || !path) fail('Usage: test <method> <path>')
-		const headers = new Headers()
-		for (const header of values.header ?? []) {
-			const at = header.indexOf(':')
-			if (at < 1) fail(`Header must look like "name: value", got "${header}"`)
-			headers.set(header.slice(0, at).trim(), header.slice(at + 1).trim())
-		}
-		if (values.body && !headers.has('content-type')) {
-			try {
-				JSON.parse(values.body)
-				headers.set('content-type', 'application/json')
-			} catch {
-				headers.set('content-type', 'text/plain')
-			}
-		}
-		for (const [name, value] of Object.entries(
-			await signatureHeaders(values.body ?? '')
-		)) {
-			headers.set(name, value)
-		}
-
-		const url = `${path.startsWith('/') ? path : `/${path}`}${values.query ? `?${values.query}` : ''}`
-		const start = performance.now()
-		const res = await app.request(url, {
-			method: method.toUpperCase(),
-			headers,
-			body: values.body
-		})
-		const text = await res.text()
-		let body = text
-		try {
-			body = JSON.stringify(JSON.parse(text), null, 2)
-		} catch {}
-		console.log(`${res.status} (${(performance.now() - start).toFixed(1)}ms)`)
-		if (body) console.log(body)
-		if (!res.ok) process.exitCode = 1
-		return
-	}
-
-	fail(`Unknown command: ${command}\n\n${HELP}`)
-}
-
-await main()
+// hanzio/cli exits 2 on bad arguments; this CLI has always exited 1.
+const code = await cli.run()
+process.exitCode = code === 2 ? 1 : code