hono-webhooks 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hono-webhooks",
-  "version": "0.4.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",
@@ -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
+		}
+	})
+})

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