hono-webhooks 0.1.1 → 0.3.0

package/src/index.ts

@@ -1,7 +1,11 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type {
+	StandardJSONSchemaV1,
+	StandardSchemaV1
+} from '@standard-schema/spec'
 import { type Context, type Env, Hono } from 'hono'
 import { HTTPException } from 'hono/http-exception'
-import type { ParamKeys, ParamKeyToRecord } from 'hono/types'
+import { basePath } from 'hono/route'
+import type { ParamKeys } from 'hono/types'
 
 export type { StandardSchemaV1 }
 
@@ -27,6 +31,7 @@ export type ValidationTarget =
 	| 'params'
 	| 'query'
 	| 'headers'
+	| 'signature'
 	| 'body'
 	| 'response'
 
@@ -43,13 +48,31 @@ type UnionToIntersection<U> = (
 	? I
 	: never
 
+type ParamRecord<K extends string> = K extends `${infer Name}?`
+	? { [N in Name]?: string }
+	: { [N in K]: string }
+
 /**
  * Params typed from the path string: `/users/:id` gives `{ id: string }`,
- * `/files/:name?` gives `{ name: string | undefined }`.
+ * `/files/:name?` gives `{ name?: string }`.
  */
 export type PathParams<P extends string> = [ParamKeys<P>] extends [never]
 	? Record<string, never>
-	: UnionToIntersection<ParamKeyToRecord<ParamKeys<P>>>
+	: UnionToIntersection<ParamRecord<ParamKeys<P>>>
+
+/** What a `verify` function gets: the request before its body is parsed. */
+export interface VerifyInput<E extends Env = any> {
+	c: Context<E>
+	/** The body exactly as received. */
+	rawBody: string
+	/** All request headers, lower-case names, not schema-validated. */
+	headers: Record<string, string>
+}
+
+/** Checks a request's signature. `hono-webhooks/signatures` has ready-made ones. */
+export type Verify<E extends Env = any> = (
+	input: VerifyInput<E>
+) => MaybePromise<boolean>
 
 export interface WebhookConfig<
 	P extends string = string,
@@ -57,7 +80,8 @@ export interface WebhookConfig<
 	TQuery extends Schema | undefined = Schema | undefined,
 	THeaders extends Schema | undefined = Schema | undefined,
 	TBody extends Schema | undefined = Schema | undefined,
-	TResponse extends Schema | undefined = Schema | undefined
+	TResponse extends Schema | undefined = Schema | undefined,
+	E extends Env = any
 > {
 	method: WebhookMethod
 	/** Hono path pattern, relative to where the webhooks are mounted. */
@@ -67,6 +91,13 @@ export interface WebhookConfig<
 	/** Header names are lower-case. */
 	headers?: THeaders
 	body?: TBody
+	/**
+	 * Checks the signature right after routing, before anything is validated
+	 * or parsed. Returning `false` answers `401 { error: 'Invalid signature' }`.
+	 *
+	 * @example verify: shopify.verify((c) => c.env.SHOPIFY_SECRET)
+	 */
+	verify?: Verify<E>
 	/**
 	 * Checks what the handler returns. A mismatch is reported on
 	 * `WebhookEvent.validation` and the response is still sent.
@@ -114,7 +145,7 @@ export interface Webhook<
 	TBody extends Schema | undefined = any,
 	TResponse extends Schema | undefined = any
 > {
-	config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse>
+	config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse, E>
 	// Method syntax keeps the parameter bivariant, so any webhook fits Webhook<E>[].
 	handler(
 		input: WebhookInput<E, P, TParams, TQuery, THeaders, TBody>
@@ -127,14 +158,21 @@ export interface WebhookEvent<E extends Env = any> {
 	/** The matched path pattern, e.g. `/users/:id`. `undefined` for a 404. */
 	route: string | undefined
 	method: string
-	/** The requested path. */
+	/**
+	 * The requested path relative to the mount point, e.g. `/orders/42`. The
+	 * full path is `c.req.path`.
+	 */
 	path: string
 	status: number
+	/** Fractional milliseconds from `performance.now()`. */
 	durationMs: number
-	/** Each part is set once it has been validated. */
-	params?: unknown
-	query?: unknown
-	headers?: unknown
+	/**
+	 * Each part is set once it has been validated: the schema's output, or
+	 * the raw string record when there is no schema.
+	 */
+	params?: Record<string, unknown>
+	query?: Record<string, unknown>
+	headers?: Record<string, unknown>
 	body?: unknown
 	rawBody?: string
 	/** What the handler returned, unless it returned a `Response`. */
@@ -148,11 +186,31 @@ export interface WebhookEvent<E extends Env = any> {
 	}
 }
 
+/** What `around` knows about a request before it is handled. */
+export interface WebhookRequestInfo<E extends Env = any> {
+	c: Context<E>
+	/** The matched path pattern, e.g. `/users/:id`. `undefined` for a 404. */
+	route: string | undefined
+	method: string
+}
+
 export interface WebhooksOptions<E extends Env = any> {
 	/**
-	 * Called after every request: log it, store it, record metrics. Not
-	 * awaited; a returned promise is handed to `executionCtx.waitUntil` when
-	 * the runtime has one, and its rejection is logged.
+	 * Wraps each request, 404s and 405s included, with the route already
+	 * known: start a span, set up `AsyncLocalStorage`, time it. Call `next()`
+	 * to handle the request (which also runs `onEvent`) and return its
+	 * response.
+	 */
+	around?: (
+		info: WebhookRequestInfo<E>,
+		next: () => Promise<Response>
+	) => Promise<Response>
+	/**
+	 * Called after every request: log it, store it, record metrics. Runs
+	 * inside the request's async context (and inside `around`), so the active
+	 * span and `AsyncLocalStorage` values are available. Not awaited; a
+	 * returned promise is handed to `executionCtx.waitUntil` when the runtime
+	 * has one, and its rejection is logged.
 	 */
 	onEvent?: (event: WebhookEvent<E>) => MaybePromise<void>
 	/**
@@ -161,6 +219,12 @@ export interface WebhooksOptions<E extends Env = any> {
 	 * and `500 { error: 'Internal Server Error' }` for anything else.
 	 */
 	onError?: (error: unknown, c: Context<E>) => MaybePromise<Response | void>
+	/**
+	 * Log unexpected errors with `console.error` when the default 500
+	 * response is used. Turn off when `onEvent` already logs them.
+	 * @default true
+	 */
+	logErrors?: boolean
 }
 
 export type WebhooksApp<E extends Env = any> = Hono<E> & {
@@ -168,13 +232,18 @@ export type WebhooksApp<E extends Env = any> = Hono<E> & {
 	readonly webhooks: readonly Webhook<E>[]
 }
 
-/** Thrown when a request part fails its schema. Answers 400 by default. */
+/**
+ * Thrown when a request part fails its schema (400) or the signature check
+ * fails (401).
+ */
 export class WebhookValidationError extends HTTPException {
 	constructor(
 		readonly target: Exclude<ValidationTarget, 'response'>,
 		readonly issues: readonly StandardSchemaV1.Issue[]
 	) {
-		super(400, { message: `Invalid ${target}` })
+		super(target === 'signature' ? 401 : 400, {
+			message: `Invalid ${target}`
+		})
 		this.name = 'WebhookValidationError'
 	}
 }
@@ -188,7 +257,7 @@ function makeDefineWebhook<E extends Env>() {
 		TBody extends Schema | undefined = undefined,
 		TResponse extends Schema | undefined = undefined
 	>(
-		config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse>,
+		config: WebhookConfig<P, TParams, TQuery, THeaders, TBody, TResponse, E>,
 		handler: (
 			input: WebhookInput<E, P, TParams, TQuery, THeaders, TBody>
 		) => WebhookResult<TResponse>
@@ -229,7 +298,7 @@ async function parse(
 
 function defaultErrorResponse(error: unknown, c: Context, log: boolean) {
 	if (error instanceof WebhookValidationError) {
-		return c.json({ error: error.message, issues: error.issues }, 400)
+		return c.json({ error: error.message, issues: error.issues }, error.status)
 	}
 	if (error instanceof HTTPException) {
 		return error.res ?? c.json({ error: error.message }, error.status)
@@ -275,13 +344,15 @@ function makeCreateWebhooks<E extends Env>() {
 
 		type Run = (c: Context<E>, event: WebhookEvent<E>) => Promise<Response>
 		const handle = (route: string | undefined, run: Run) => {
-			return async (c: Context<E>) => {
+			const execute = async (c: Context<E>) => {
 				const start = performance.now()
+				const base = basePath(c)
 				const event: WebhookEvent<E> = {
 					c,
 					route,
 					method: c.req.method,
-					path: c.req.path,
+					path:
+						base === '/' ? c.req.path : c.req.path.slice(base.length) || '/',
 					status: 0,
 					durationMs: 0
 				}
@@ -295,13 +366,18 @@ function makeCreateWebhooks<E extends Env>() {
 					}
 					res =
 						(await options.onError?.(error, c)) ??
-						defaultErrorResponse(error, c as Context, !options.onError)
+						defaultErrorResponse(error, c as Context, options.logErrors ?? true)
 				}
 				event.status = res.status
 				event.durationMs = performance.now() - start
 				if (options.onEvent) report(c as Context, options.onEvent(event))
 				return res
 			}
+			const { around } = options
+			return (c: Context<E>) =>
+				around
+					? around({ c, route, method: c.req.method }, () => execute(c))
+					: execute(c)
 		}
 
 		// Hono tries handlers in registration order, so static paths go first
@@ -316,10 +392,37 @@ function makeCreateWebhooks<E extends Env>() {
 				config.method,
 				config.path,
 				handle(config.path, async (c, event) => {
-					event.params = await parse(config.params, c.req.param(), 'params')
-					event.query = await parse(config.query, c.req.query(), 'query')
-					event.headers = await parse(config.headers, c.req.header(), 'headers')
+					// The signature is checked first, so unauthenticated callers only
+					// ever see 401, never a description of the schemas.
 					event.rawBody = await c.req.text()
+					if (
+						config.verify &&
+						!(await config.verify({
+							c,
+							rawBody: event.rawBody,
+							headers: c.req.header()
+						}))
+					) {
+						throw new WebhookValidationError('signature', [
+							{ message: 'Signature does not match' }
+						])
+					}
+					type Parts = Record<string, unknown>
+					event.params = (await parse(
+						config.params,
+						c.req.param(),
+						'params'
+					)) as Parts
+					event.query = (await parse(
+						config.query,
+						c.req.query(),
+						'query'
+					)) as Parts
+					event.headers = (await parse(
+						config.headers,
+						c.req.header(),
+						'headers'
+					)) as Parts
 					event.body = await parse(
 						config.body,
 						parseBody(
@@ -416,3 +519,242 @@ export function createWebhookFactory<E extends Env = any>() {
 		createWebhooks: makeCreateWebhooks<E>()
 	}
 }
+
+/**
+ * Validation issues as one line: `total: Expected number; items.0.id: Required`.
+ */
+export function formatIssues(issues: readonly StandardSchemaV1.Issue[]) {
+	return issues
+		.map((issue) => {
+			const path = issuePath(issue)
+			return path ? `${path}: ${issue.message}` : issue.message
+		})
+		.join('; ')
+}
+
+function issuePath(issue: StandardSchemaV1.Issue) {
+	const path = issue.path
+		?.map((segment) =>
+			String(typeof segment === 'object' ? segment.key : segment)
+		)
+		.join('.')
+	return path || null
+}
+
+/** A flat, JSON-safe record of a `WebhookEvent`, ready to log or store. */
+export interface WebhookEventSummary {
+	route: string | null
+	method: string
+	/** Relative to the mount point. */
+	path: string
+	status: number
+	/** Rounded to two decimals. */
+	durationMs: number
+	/** From `x-forwarded-for`, `x-real-ip` or `cf-connecting-ip`; clients can spoof these. */
+	ip: string | null
+	userAgent: string | null
+	params: Record<string, unknown> | null
+	query: Record<string, unknown> | null
+	body: unknown
+	response: unknown
+	/** `null` for validation failures, which `validation` describes. */
+	error: { name: string; message: string; stack: string | null } | null
+	validation: {
+		target: ValidationTarget
+		/** `formatIssues(issues)` */
+		message: string
+		issues: { message: string; path: string | null }[]
+	} | null
+}
+
+/**
+ * Flattens an event for logging or storage. Request headers are left out on
+ * purpose: they carry signatures and credentials.
+ *
+ * @example
+ * onEvent: (e) => db.insert(webhookCalls).values(summarizeEvent(e))
+ */
+export function summarizeEvent(event: WebhookEvent): WebhookEventSummary {
+	const { c, error, validation } = event
+	return {
+		route: event.route ?? null,
+		method: event.method,
+		path: event.path,
+		status: event.status,
+		durationMs: Math.round(event.durationMs * 100) / 100,
+		ip:
+			c.req.header('x-forwarded-for')?.split(',')[0]?.trim() ||
+			c.req.header('x-real-ip') ||
+			c.req.header('cf-connecting-ip') ||
+			null,
+		userAgent: c.req.header('user-agent') ?? null,
+		params: event.params ?? null,
+		query: event.query ?? null,
+		body: event.body ?? null,
+		response: event.response ?? null,
+		// A validation failure is described by `validation`; its error adds only
+		// a library stack trace.
+		error:
+			error === undefined || error instanceof WebhookValidationError
+				? null
+				: error instanceof Error
+					? {
+							name: error.name,
+							message: error.message,
+							stack: error.stack ?? null
+						}
+					: { name: 'Error', message: String(error), stack: null },
+		validation: validation
+			? {
+					target: validation.target,
+					message: formatIssues(validation.issues),
+					issues: validation.issues.map((issue) => ({
+						message: issue.message,
+						path: issuePath(issue)
+					}))
+				}
+			: null
+	}
+}
+
+export interface WebhookDescription {
+	method: WebhookMethod
+	path: string
+	description: string | null
+	/** Whether the webhook has a `verify` function. */
+	verified: boolean
+	bodyType: BodyType
+	/**
+	 * JSON Schema per part: the input side for request parts, the output side
+	 * for `response`. `null` when the part has no schema or its library
+	 * doesn't implement Standard JSON Schema.
+	 */
+	jsonSchema: Record<
+		'params' | 'query' | 'headers' | 'body' | 'response',
+		Record<string, unknown> | null
+	>
+}
+
+function toJsonSchema(
+	schema: Schema | undefined,
+	side: 'input' | 'output',
+	target: StandardJSONSchemaV1.Target
+) {
+	const props = (schema as Partial<StandardJSONSchemaV1> | undefined)?.[
+		'~standard'
+	]
+	try {
+		return props?.jsonSchema?.[side]({ target }) ?? null
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Describes webhooks for docs, admin pages or OpenAPI, with JSON Schemas from
+ * any library that implements Standard JSON Schema (Zod 4.2+, for example).
+ */
+export function describeWebhooks(
+	source: WebhooksApp | readonly Webhook[],
+	{ target = 'draft-2020-12' }: { target?: StandardJSONSchemaV1.Target } = {}
+): WebhookDescription[] {
+	const webhooks = 'webhooks' in source ? source.webhooks : source
+	return webhooks.map(({ config }) => ({
+		method: config.method,
+		path: config.path,
+		description: config.description ?? null,
+		verified: Boolean(config.verify),
+		bodyType: config.bodyType ?? 'auto',
+		jsonSchema: {
+			params: toJsonSchema(config.params, 'input', target),
+			query: toJsonSchema(config.query, 'input', target),
+			headers: toJsonSchema(config.headers, 'input', target),
+			body: toJsonSchema(config.body, 'input', target),
+			response: toJsonSchema(config.response, 'output', target)
+		}
+	}))
+}
+
+type In<S, Fallback> = S extends Schema
+	? StandardSchemaV1.InferInput<S>
+	: Fallback
+
+/** What `testWebhook` sends, typed from the webhook's schemas. */
+export type TestWebhookInput<W> =
+	W extends Webhook<infer E, infer P, infer TParams, any, any, infer TBody>
+		? {
+				/** Filled into the path pattern. */
+				params?: In<TParams, PathParams<P>>
+				/** Overrides the path, e.g. for wildcard patterns. */
+				path?: string
+				query?: Record<string, string>
+				headers?: Record<string, string>
+				/**
+				 * A string is sent as is (`text/plain` unless you set a content
+				 * type). Anything else is sent as JSON, or url-encoded when the
+				 * webhook's `bodyType` is `'form'`.
+				 */
+				body?: In<TBody, unknown> | string
+				/** Headers computed from the raw body, e.g. `(raw) => shopify.sign(raw, secret)`. */
+				sign?: (rawBody: string) => MaybePromise<Record<string, string>>
+				/** Bindings, available as `c.env`. */
+				env?: E extends { Bindings: infer B } ? B : unknown
+				/** `onEvent`, `onError` and so on, as for `createWebhooks`. */
+				options?: WebhooksOptions<E>
+			}
+		: never
+
+function fillPath(pattern: string, params: Record<string, unknown>) {
+	return pattern.replace(/\/:(\w+)(?:\{[^}]*\})?\??/g, (_, name: string) => {
+		const value = params[name]
+		return value === undefined ? '' : `/${encodeURIComponent(String(value))}`
+	})
+}
+
+/**
+ * Sends one request through a single webhook, with routing, signature check,
+ * validation and response handling, and returns the `Response`.
+ *
+ * @example
+ * const res = await testWebhook(orderPaid, {
+ *   params: { orderId: '42' },
+ *   body: { amount: 10, currency: 'DKK' }
+ * })
+ */
+export async function testWebhook<W extends Webhook>(
+	webhook: W,
+	input: TestWebhookInput<W> = {} as TestWebhookInput<W>
+): Promise<Response> {
+	const { config } = webhook
+	const { body, sign, env, options } = input as TestWebhookInput<Webhook>
+	const headers = new Headers(input.headers)
+	let rawBody: string | undefined
+	if (typeof body === 'string') {
+		rawBody = body
+		if (!headers.has('content-type')) headers.set('content-type', 'text/plain')
+	} else if (body !== undefined && config.bodyType === 'form') {
+		rawBody = new URLSearchParams(body as Record<string, string>).toString()
+		if (!headers.has('content-type')) {
+			headers.set('content-type', 'application/x-www-form-urlencoded')
+		}
+	} else if (body !== undefined) {
+		rawBody = JSON.stringify(body)
+		if (!headers.has('content-type')) {
+			headers.set('content-type', 'application/json')
+		}
+	}
+	for (const [name, value] of Object.entries(
+		(await sign?.(rawBody ?? '')) ?? {}
+	)) {
+		headers.set(name, value)
+	}
+	const path =
+		input.path ??
+		fillPath(config.path, (input.params ?? {}) as Record<string, unknown>)
+	const query = new URLSearchParams(input.query).toString()
+	return createWebhooks([webhook], options).request(
+		`${path || '/'}${query ? `?${query}` : ''}`,
+		{ method: config.method, headers, body: rawBody },
+		env as object | undefined
+	)
+}