hono-webhooks 0.1.1 → 0.3.0

package/src/cli.ts

@@ -1,37 +1,68 @@
 #!/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 type { StandardJSONSchemaV1 } from '@standard-schema/spec'
-import type { WebhooksApp } from './index'
+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
+}
 
 const HELP = `Usage: hono-webhooks <module> <command> [options]
 
-<module> exports the result of createWebhooks(), as default or named export.
+<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 }
+		header: { type: 'string', short: 'H', multiple: true },
+		sign: { type: 'string', short: 's' },
+		'secret-env': { type: 'string', short: 'e' }
 	}
 })
 
@@ -42,6 +73,14 @@ function fail(message: string): never {
 	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' &&
@@ -51,19 +90,66 @@ function isWebhooksApp(value: unknown): value is WebhooksApp {
 	)
 }
 
-async function loadApp(path: string) {
-	const mod = await import(pathToFileURL(resolve(path)).href)
-	const app = [mod.default, ...Object.values(mod)].find(isWebhooksApp)
-	return app ?? fail(`${path} does not export a createWebhooks() app`)
+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'
+		)
+	)
 }
 
-function jsonSchemaOf(schema: unknown) {
-	const props = (schema as Partial<StandardJSONSchemaV1>)['~standard']
-	try {
-		return props?.jsonSchema?.input({ target: 'draft-2020-12' })
-	} catch {
-		return undefined
+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() {
@@ -71,13 +157,22 @@ async function main() {
 		console.log(HELP)
 		return
 	}
-	const app = await loadApp(modulePath)
+	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])
-				.join(', ')
+			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}` : ''}`
 			)
@@ -88,21 +183,25 @@ async function main() {
 
 	if (command === 'schema') {
 		const [path] = args
-		const matches = app.webhooks.filter((w) => w.config.path === path)
-		if (!matches.length) fail(`No webhook at ${path}`)
-		for (const { config } of matches) {
+		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 key of [
+			for (const part of [
 				'params',
 				'query',
 				'headers',
 				'body',
 				'response'
 			] as const) {
-				if (!config[key]) continue
-				const json = jsonSchemaOf(config[key])
+				if (!config[part]) continue
+				const schema = descriptions[i]!.jsonSchema[part]
 				console.log(
-					`  ${key}: ${json ? JSON.stringify(json, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
+					`  ${part}: ${schema ? JSON.stringify(schema, null, 2).replaceAll('\n', '\n  ') : '(no JSON Schema support)'}`
 				)
 			}
 		}
@@ -126,6 +225,11 @@ async function main() {
 				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()