@okay-e9g/hono-config 0.0.0

package/package.json

@@ -0,0 +1,47 @@
+{
+	"dependencies": {},
+	"description": "Shared Hono config for Okay Engineering",
+	"devDependencies": {
+		"@cloudflare/workers-types": "5.20260705.1",
+		"@hono/zod-openapi": "1.4.0",
+		"@okay-e9g/biome-config": "workspace:*",
+		"@okay-e9g/tsconfig": "workspace:*",
+		"@types/bun": "1.3.14",
+		"@types/node": "26.1.0",
+		"hono": "4.12.27",
+		"superjson": "2.2.6",
+		"typescript": "6.0.3",
+		"zod": "4.4.3"
+	},
+	"exports": {
+		".": "./src/index.ts",
+		"./openapi-factory": "./src/helpers/factory.openapi.ts"
+	},
+	"files": [
+		"./src"
+	],
+	"homepage": "https://okay.engineering",
+	"license": "MIT",
+	"name": "@okay-e9g/hono-config",
+	"peerDependencies": {
+		"@hono/zod-openapi": "^1.4.0",
+		"hono": "^4.12.27",
+		"superjson": "^2.2.6",
+		"zod": "^4.4.3"
+	},
+	"peerDependenciesMeta": {
+		"@hono/zod-openapi": {
+			"optional": true
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": false,
+		"registry": "https://registry.npmjs.org"
+	},
+	"scripts": {
+		"prepublishOnly": "bun run typecheck && bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"version": "0.0.0"
+}

package/src/handlers/not-found.ts

@@ -0,0 +1,25 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { Env, NotFoundHandler } from 'hono/types';
+
+import type { ResponseEnv } from '../middlewares/ensure-rt';
+import { statusText } from '../schemas';
+
+/**
+ * Creates the shared 404 handler used by the configured Hono factories.
+ *
+ * @internal
+ */
+export const notFound = <T extends Env>(): NotFoundHandler<T> => {
+	return (c) => {
+		const { response } = c.var as ResponseEnv['Variables'];
+
+		if (response.type === 'api') {
+			return c.json(response.error(404), 404);
+		}
+
+		return c.json(response.error(statusText[404]));
+	};
+};

package/src/handlers/on-error.ts

@@ -0,0 +1,47 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { HTTPException } from 'hono/http-exception';
+import type { Env, ErrorHandler } from 'hono/types';
+import { z } from 'zod';
+
+import type { ResponseEnv } from '../middlewares/ensure-rt';
+import { type ClientErrorStatusCode, type ServerErrorStatusCode, type StatusCode, statusText } from '../schemas';
+
+/**
+ * Creates the shared error handler used by the configured Hono factories.
+ *
+ * @internal
+ */
+export const onError = <T extends Env>(): ErrorHandler<T> => {
+	return (err, c) => {
+		const { response } = c.var as ResponseEnv['Variables'];
+
+		if (err instanceof z.ZodError) {
+			if (response.type === 'api') {
+				return c.json(response.error(400, z.flattenError(err)), 400);
+			}
+
+			return c.json(response.error(z.flattenError(err)));
+		}
+
+		if (err instanceof HTTPException) {
+			const { message, status } = err;
+
+			if (response.type === 'api') {
+				return c.json(response.error(status as ClientErrorStatusCode | ServerErrorStatusCode, message), status);
+			}
+
+			return c.json(response.error(message === '' ? statusText[status as StatusCode] : message));
+		}
+
+		const errMessage = err instanceof Error ? err.message : err;
+
+		if (response.type === 'api') {
+			return c.json(response.error(500, errMessage), 500);
+		}
+
+		return c.json(response.error(errMessage === '' ? statusText[500] : errMessage));
+	};
+};

package/src/helpers/factory.openapi.ts

@@ -0,0 +1,72 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { OpenAPIHono } from '@hono/zod-openapi';
+import type { Factory } from 'hono/factory';
+import type { HonoOptions } from 'hono/hono-base';
+import type { Env } from 'hono/types';
+
+import { notFound } from '../handlers/not-found';
+import { onError } from '../handlers/on-error';
+import { ensureResponseType } from '../middlewares/ensure-rt';
+import { superjson } from '../middlewares/superjson';
+import { type CreateHonoFactoryOpts, createHonoFactory } from './factory';
+
+/**
+ * Hono factory whose apps expose OpenAPI route helpers.
+ *
+ * @typeParam T - Hono environment type for bindings and variables.
+ */
+export type OpenAPIHonoFactory<T extends Env> = Omit<Factory<T>, 'createApp'> & {
+	/**
+	 * Creates an `OpenAPIHono` app configured with the shared defaults.
+	 */
+	createApp: (opts?: HonoOptions<T>) => OpenAPIHono<T>;
+};
+
+/**
+ * Creates a Hono factory that produces `OpenAPIHono` apps with shared defaults.
+ *
+ * The generated apps use non-strict routing, throw validation failures from the
+ * OpenAPI default hook, install the shared not-found and error handlers, enable
+ * SuperJSON response serialization, apply any provided application middleware,
+ * and finish with the response-type guard.
+ *
+ * Include exactly one response-type middleware, such as `apiResponseType()` or
+ * `rpcResponseType()`, in `appMiddlewares` so the shared handlers can build the
+ * correct response envelope.
+ *
+ * @typeParam T - Hono environment type for bindings and variables.
+ * @param opts - Optional overrides for middleware and default handlers.
+ * @returns A Hono factory whose `createApp` method returns an `OpenAPIHono`.
+ */
+export const createOpenAPIHonoFactory = <T extends Env>({
+	appMiddlewares = [],
+	notFoundHandler = notFound,
+	onErrorHandler = onError,
+}: Partial<CreateHonoFactoryOpts<T>> = {}): OpenAPIHonoFactory<T> => {
+	return {
+		...createHonoFactory<T>(),
+		createApp: (opts) => {
+			const app = new OpenAPIHono<T>({
+				...(opts as HonoOptions<Env>),
+				defaultHook: (result) => {
+					if (!result.success) {
+						throw result.error;
+					}
+				},
+				strict: false,
+			});
+
+			app.notFound(notFoundHandler());
+			app.onError(onErrorHandler());
+
+			app.use(superjson());
+			app.use(...appMiddlewares);
+			app.use(ensureResponseType());
+
+			return app;
+		},
+	};
+};

package/src/helpers/factory.ts

@@ -0,0 +1,68 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { createFactory, type Factory } from 'hono/factory';
+import type { Env, ErrorHandler, MiddlewareHandler, NotFoundHandler } from 'hono/types';
+
+import { notFound } from '../handlers/not-found';
+import { onError } from '../handlers/on-error';
+import { ensureResponseType } from '../middlewares/ensure-rt';
+import { superjson } from '../middlewares/superjson';
+
+/**
+ * Options used to customize the shared Hono application factory.
+ *
+ * @typeParam T - Hono environment type for bindings and variables.
+ */
+export type CreateHonoFactoryOpts<T extends Env> = {
+	/**
+	 * Application-level middleware installed between SuperJSON serialization and
+	 * the final response-type guard.
+	 */
+	appMiddlewares: MiddlewareHandler<T>[];
+	/**
+	 * Factory for the default 404 handler.
+	 */
+	notFoundHandler: () => NotFoundHandler<T>;
+	/**
+	 * Factory for the default error handler.
+	 */
+	onErrorHandler: () => ErrorHandler<T>;
+};
+
+/**
+ * Creates a Hono factory configured with Okay Engineering defaults.
+ *
+ * The generated apps use non-strict routing, the shared not-found and error
+ * handlers, SuperJSON response serialization, any provided application
+ * middleware, and the response-type guard used by `apiResponseType` and
+ * `rpcResponseType`.
+ *
+ * Include exactly one response-type middleware, such as `apiResponseType()` or
+ * `rpcResponseType()`, in `appMiddlewares` so the shared handlers can build the
+ * correct response envelope.
+ *
+ * @typeParam T - Hono environment type for bindings and variables.
+ * @param opts - Optional overrides for middleware and default handlers.
+ * @returns A Hono factory ready to create configured apps and middleware.
+ */
+export const createHonoFactory = <T extends Env>({
+	appMiddlewares = [],
+	notFoundHandler = notFound,
+	onErrorHandler = onError,
+}: Partial<CreateHonoFactoryOpts<T>> = {}): Factory<T> => {
+	return createFactory<T>({
+		defaultAppOptions: {
+			strict: false,
+		},
+		initApp: (app) => {
+			app.notFound(notFoundHandler());
+			app.onError(onErrorHandler());
+
+			app.use(superjson());
+			app.use(...appMiddlewares);
+			app.use(ensureResponseType());
+		},
+	});
+};

package/src/helpers/index.ts

@@ -0,0 +1,5 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './factory';

package/src/index.ts

@@ -0,0 +1,7 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './helpers';
+export * from './middlewares';
+export * from './schemas';

package/src/middlewares/ensure-rt.ts

@@ -0,0 +1,37 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { createMiddleware } from 'hono/factory';
+import type { Env, MiddlewareHandler } from 'hono/types';
+
+import type { ApiResponseEnv, RpcResponseEnv } from './response';
+
+/**
+ * Hono environment contract required by the response-type guard.
+ *
+ * @internal
+ */
+export interface ResponseEnv extends Env {
+	Variables: {
+		response: ApiResponseEnv['Variables']['response'] | RpcResponseEnv['Variables']['response'];
+	};
+}
+
+/**
+ * Verifies that an API or RPC response helper was installed before a request
+ * reaches route handlers.
+ *
+ * @internal
+ */
+export const ensureResponseType = (): MiddlewareHandler<ResponseEnv> => {
+	return createMiddleware(async (c, next) => {
+		const response = (c.var as Partial<ResponseEnv['Variables']>).response;
+
+		if (response?.type !== 'api' && response?.type !== 'rpc') {
+			throw new Error('Response type middleware not initialized.');
+		}
+
+		await next();
+	});
+};

package/src/middlewares/index.ts

@@ -0,0 +1,5 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './response';

package/src/middlewares/response.ts

@@ -0,0 +1,159 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { createMiddleware } from 'hono/factory';
+import type { Env, MiddlewareHandler } from 'hono/types';
+
+import {
+	type ApiError,
+	type ApiResult,
+	apiError,
+	apiResult,
+	type ClientErrorStatusCode,
+	type JsonRpc,
+	type RpcError,
+	type RpcResult,
+	rpcError,
+	rpcResult,
+	type ServerErrorStatusCode,
+	type SuccessStatusCode,
+	statusText,
+} from '../schemas';
+
+interface TypedApiError<T = unknown> extends ApiError {
+	error?: T;
+}
+
+interface TypedApiResult<T = unknown> extends ApiResult {
+	result?: T;
+}
+
+type ErrorStatusCode = ClientErrorStatusCode | ServerErrorStatusCode;
+
+type ResultStatusCode = Exclude<SuccessStatusCode, 204 | 205>;
+
+const assertResponseTypeNotInitialized = (response: unknown): void => {
+	if (response !== undefined) {
+		throw new Error('Response type middleware already initialized.');
+	}
+};
+
+/**
+ * Hono environment contract added by `apiResponseType`.
+ */
+export interface ApiResponseEnv extends Env {
+	Variables: {
+		/**
+		 * Helpers for building the package's standard success and error response
+		 * envelopes.
+		 */
+		response: {
+			/**
+			 * Builds an API error envelope and fills an empty error with the HTTP
+			 * status text for the provided status code.
+			 */
+			error: <T, U extends ErrorStatusCode>(status: U, error?: T) => TypedApiError<T>;
+			/**
+			 * Builds an API result envelope and fills an empty result with the HTTP
+			 * status text for the provided status code.
+			 */
+			result: <T, U extends ResultStatusCode>(status: U, result?: T) => TypedApiResult<T>;
+			/**
+			 * Discriminator used by shared error handlers and response guards.
+			 */
+			type: 'api';
+		};
+	};
+}
+
+/**
+ * Installs `c.var.response` helpers for conventional HTTP API responses.
+ *
+ * The helpers produce `{ success: false, error }` and `{ success: true, result }`
+ * envelopes validated by the exported API schemas.
+ *
+ * @returns Hono middleware that adds the API response helper contract.
+ */
+export const apiResponseType = (): MiddlewareHandler<ApiResponseEnv> => {
+	return createMiddleware(async (c, next) => {
+		assertResponseTypeNotInitialized(c.var.response);
+
+		c.set('response', {
+			error: <T, U extends ErrorStatusCode>(status: U, error?: T) => {
+				return apiError.parse({
+					error: error === undefined || error === '' ? statusText[status] : error,
+					success: false,
+				}) as TypedApiError<T>;
+			},
+			result: <T, U extends ResultStatusCode>(status: U, result?: T) => {
+				return apiResult.parse({
+					result: result === undefined || result === '' ? statusText[status] : result,
+					success: true,
+				}) as TypedApiResult<T>;
+			},
+			type: 'api',
+		});
+
+		await next();
+	});
+};
+
+interface TypedRpcError<T = unknown> extends RpcError {
+	error?: T;
+}
+
+interface TypedRpcResult<T = unknown> extends RpcResult {
+	result?: T;
+}
+
+/**
+ * Hono environment contract added by `rpcResponseType`.
+ */
+export interface RpcResponseEnv extends Env {
+	Variables: {
+		/**
+		 * Helpers for building JSON-RPC 2.0 response envelopes.
+		 */
+		response: {
+			/**
+			 * Builds a JSON-RPC error response envelope for the provided request id.
+			 */
+			error: <T>(error?: T, id?: JsonRpc['id']) => TypedRpcError<T>;
+			/**
+			 * Builds a JSON-RPC result response envelope for the provided request id.
+			 */
+			result: <T>(result?: T, id?: JsonRpc['id']) => TypedRpcResult<T>;
+			/**
+			 * Discriminator used by shared error handlers and response guards.
+			 */
+			type: 'rpc';
+		};
+	};
+}
+
+/**
+ * Installs `c.var.response` helpers for JSON-RPC 2.0 responses.
+ *
+ * The helpers produce `error` and `result` envelopes validated by the exported
+ * JSON-RPC schemas and default missing ids to the schema default.
+ *
+ * @returns Hono middleware that adds the RPC response helper contract.
+ */
+export const rpcResponseType = (): MiddlewareHandler<RpcResponseEnv> => {
+	return createMiddleware(async (c, next) => {
+		assertResponseTypeNotInitialized(c.var.response);
+
+		c.set('response', {
+			error: <T>(error?: T, id?: JsonRpc['id']) => {
+				return rpcError.parse({ error, id }) as TypedRpcError<T>;
+			},
+			result: <T>(result?: T, id?: JsonRpc['id']) => {
+				return rpcResult.parse({ id, result }) as TypedRpcResult<T>;
+			},
+			type: 'rpc',
+		});
+
+		await next();
+	});
+};

package/src/middlewares/superjson.ts

@@ -0,0 +1,25 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { createMiddleware } from 'hono/factory';
+import type { Env, MiddlewareHandler } from 'hono/types';
+import { serialize } from 'superjson';
+
+/**
+ * Serializes every `c.json` response body through SuperJSON before Hono writes
+ * the response.
+ *
+ * @internal
+ */
+export const superjson = (): MiddlewareHandler<Env> => {
+	return createMiddleware(async (c, next) => {
+		const json = c.json.bind(c);
+
+		c.json = (...[object, ...args]: Parameters<typeof json>) => {
+			return json(serialize(object).json, ...args);
+		};
+
+		await next();
+	});
+};

package/src/schemas/api.ts

@@ -0,0 +1,41 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { z } from 'zod';
+
+/**
+ * Zod schema for the standard API error envelope.
+ */
+export const apiError = z.object({
+	error: z.unknown().optional(),
+	success: z.literal(false),
+});
+
+/**
+ * TypeScript type inferred from `apiError`.
+ */
+export type ApiError = z.infer<typeof apiError>;
+
+/**
+ * Zod schema for the standard API success envelope.
+ */
+export const apiResult = z.object({
+	result: z.unknown().optional(),
+	success: z.literal(true),
+});
+
+/**
+ * TypeScript type inferred from `apiResult`.
+ */
+export type ApiResult = z.infer<typeof apiResult>;
+
+/**
+ * Zod union schema for either standard API response envelope.
+ */
+export const apiResponse = z.union([apiError, apiResult]);
+
+/**
+ * TypeScript type inferred from `apiResponse`.
+ */
+export type ApiResponse = z.infer<typeof apiResponse>;

package/src/schemas/http-status.ts

@@ -0,0 +1,209 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { ContentlessStatusCode } from 'hono/utils/http-status';
+import { z } from 'zod';
+
+/**
+ * Zod schema for informational HTTP status codes.
+ */
+export const infoStatusCode = z.union([z.literal(100), z.literal(101), z.literal(102), z.literal(103)]);
+
+/**
+ * TypeScript union of informational HTTP status codes.
+ */
+export type InfoStatusCode = z.infer<typeof infoStatusCode>;
+
+/**
+ * Zod schema for successful HTTP status codes.
+ */
+export const successStatusCode = z.union([
+	z.literal(200),
+	z.literal(201),
+	z.literal(202),
+	z.literal(203),
+	z.literal(204),
+	z.literal(205),
+	z.literal(206),
+	z.literal(207),
+	z.literal(208),
+	z.literal(226),
+]);
+
+/**
+ * TypeScript union of successful HTTP status codes.
+ */
+export type SuccessStatusCode = z.infer<typeof successStatusCode>;
+
+/**
+ * Zod schema for redirection HTTP status codes.
+ */
+export const redirectStatusCode = z.union([
+	z.literal(300),
+	z.literal(301),
+	z.literal(302),
+	z.literal(303),
+	z.literal(304),
+	z.literal(305),
+	z.literal(306),
+	z.literal(307),
+	z.literal(308),
+]);
+
+/**
+ * TypeScript union of redirection HTTP status codes.
+ */
+export type RedirectStatusCode = z.infer<typeof redirectStatusCode>;
+
+/**
+ * Zod schema for client error HTTP status codes.
+ */
+export const clientErrorStatusCode = z.union([
+	z.literal(400),
+	z.literal(401),
+	z.literal(402),
+	z.literal(403),
+	z.literal(404),
+	z.literal(405),
+	z.literal(406),
+	z.literal(407),
+	z.literal(408),
+	z.literal(409),
+	z.literal(410),
+	z.literal(411),
+	z.literal(412),
+	z.literal(413),
+	z.literal(414),
+	z.literal(415),
+	z.literal(416),
+	z.literal(417),
+	z.literal(418),
+	z.literal(421),
+	z.literal(422),
+	z.literal(423),
+	z.literal(424),
+	z.literal(425),
+	z.literal(426),
+	z.literal(428),
+	z.literal(429),
+	z.literal(431),
+	z.literal(451),
+]);
+
+/**
+ * TypeScript union of client error HTTP status codes.
+ */
+export type ClientErrorStatusCode = z.infer<typeof clientErrorStatusCode>;
+
+/**
+ * Zod schema for server error HTTP status codes.
+ */
+export const serverErrorStatusCode = z.union([
+	z.literal(500),
+	z.literal(501),
+	z.literal(502),
+	z.literal(503),
+	z.literal(504),
+	z.literal(505),
+	z.literal(506),
+	z.literal(507),
+	z.literal(508),
+	z.literal(510),
+	z.literal(511),
+]);
+
+/**
+ * TypeScript union of server error HTTP status codes.
+ */
+export type ServerErrorStatusCode = z.infer<typeof serverErrorStatusCode>;
+
+/**
+ * Zod schema for every HTTP status code supported by this package.
+ */
+export const statusCode = z.union([
+	infoStatusCode,
+	successStatusCode,
+	redirectStatusCode,
+	clientErrorStatusCode,
+	serverErrorStatusCode,
+]);
+
+/**
+ * TypeScript union of every HTTP status code supported by this package.
+ */
+export type StatusCode = z.infer<typeof statusCode>;
+
+/**
+ * HTTP status codes that can carry a response body.
+ */
+export type ContentfulStatusCode = Exclude<StatusCode, ContentlessStatusCode>;
+
+/**
+ * Default reason phrases keyed by supported HTTP status code.
+ */
+export const statusText: Record<StatusCode, string> = {
+	100: 'Continue',
+	101: 'Switching Protocols',
+	102: 'Processing',
+	103: 'Early Hints',
+	200: 'OK',
+	201: 'Created',
+	202: 'Accepted',
+	203: 'Non-Authoritative Information',
+	204: 'No Content',
+	205: 'Reset Content',
+	206: 'Partial Content',
+	207: 'Multi-Status',
+	208: 'Already Reported',
+	226: 'IM Used',
+	300: 'Multiple Choices',
+	301: 'Moved Permanently',
+	302: 'Found',
+	303: 'See Other',
+	304: 'Not Modified',
+	305: 'Use Proxy',
+	306: 'Unused',
+	307: 'Temporary Redirect',
+	308: 'Permanent Redirect',
+	400: 'Bad Request',
+	401: 'Unauthorized',
+	402: 'Payment Required',
+	403: 'Forbidden',
+	404: 'Not Found',
+	405: 'Method Not Allowed',
+	406: 'Not Acceptable',
+	407: 'Proxy Authentication Required',
+	408: 'Request Timeout',
+	409: 'Conflict',
+	410: 'Gone',
+	411: 'Length Required',
+	412: 'Precondition Failed',
+	413: 'Payload Too Large',
+	414: 'URI Too Long',
+	415: 'Unsupported Media Type',
+	416: 'Range Not Satisfiable',
+	417: 'Expectation Failed',
+	418: "I'm a Teapot",
+	421: 'Misdirected Request',
+	422: 'Unprocessable Content',
+	423: 'Locked',
+	424: 'Failed Dependency',
+	425: 'Too Early',
+	426: 'Upgrade Required',
+	428: 'Precondition Required',
+	429: 'Too Many Requests',
+	431: 'Request Header Fields Too Large',
+	451: 'Unavailable For Legal Reasons',
+	500: 'Internal Server Error',
+	501: 'Not Implemented',
+	502: 'Bad Gateway',
+	503: 'Service Unavailable',
+	504: 'Gateway Timeout',
+	505: 'HTTP Version Not Supported',
+	506: 'Variant Also Negotiates',
+	507: 'Insufficient Storage',
+	508: 'Loop Detected',
+	510: 'Not Extended',
+	511: 'Network Authentication Required',
+};

package/src/schemas/index.ts

@@ -0,0 +1,7 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './api';
+export * from './http-status';
+export * from './rpc';

package/src/schemas/rpc.ts

@@ -0,0 +1,88 @@
+/*
+ * SPDX-License-Identifier: MIT
+ */
+
+import { z } from 'zod';
+
+/**
+ * Zod schema for JSON-RPC 2.0 fields shared by requests and responses.
+ */
+export const jsonRpc = z.object({
+	id: z.union([z.number(), z.string()]).default(1),
+	jsonrpc: z.literal('2.0').default('2.0'),
+});
+
+/**
+ * TypeScript type inferred from `jsonRpc`.
+ */
+export type JsonRpc = z.infer<typeof jsonRpc>;
+
+/**
+ * Zod schema for a single JSON-RPC 2.0 request.
+ */
+export const rpcRequest = z.object({
+	...jsonRpc.shape,
+	method: z.string(),
+	params: z.unknown().optional(),
+});
+
+/**
+ * TypeScript type inferred from `rpcRequest`.
+ */
+export type RpcRequest = z.infer<typeof rpcRequest>;
+
+/**
+ * Zod schema for a JSON-RPC 2.0 request batch.
+ */
+export const rpcRequests = z.array(rpcRequest);
+
+/**
+ * TypeScript type inferred from `rpcRequests`.
+ */
+export type RpcRequests = z.infer<typeof rpcRequests>;
+
+/**
+ * Zod schema for a JSON-RPC 2.0 error response.
+ */
+export const rpcError = z.object({
+	...jsonRpc.shape,
+	error: z.unknown().optional(),
+}).strict();
+
+/**
+ * TypeScript type inferred from `rpcError`.
+ */
+export type RpcError = z.infer<typeof rpcError>;
+
+/**
+ * Zod schema for a JSON-RPC 2.0 result response.
+ */
+export const rpcResult = z.object({
+	...jsonRpc.shape,
+	result: z.unknown().optional(),
+}).strict();
+
+/**
+ * TypeScript type inferred from `rpcResult`.
+ */
+export type RpcResult = z.infer<typeof rpcResult>;
+
+/**
+ * Zod union schema for either JSON-RPC 2.0 response envelope.
+ */
+export const rpcResponse = z.union([rpcError, rpcResult]);
+
+/**
+ * TypeScript type inferred from `rpcResponse`.
+ */
+export type RpcResponse = z.infer<typeof rpcResponse>;
+
+/**
+ * Zod schema for a JSON-RPC 2.0 response batch.
+ */
+export const rpcResponses = z.array(rpcResponse);
+
+/**
+ * TypeScript type inferred from `rpcResponses`.
+ */
+export type RpcResponses = z.infer<typeof rpcResponses>;