@rpcbase/api 0.148.0 → 0.150.0

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+import { ErrorRequestHandler, Request, RequestHandler, Response } from 'express';
+export declare const API_REQUEST_ID_HEADER = "x-request-id";
+export type ApiErrorFields = Record<string, string[]>;
+export type ApiErrorResponse = {
+    success: false;
+    error: string;
+    message?: string;
+    fields?: ApiErrorFields;
+    requestId: string;
+};
+export type ApiHttpErrorOptions = {
+    message?: string;
+    fields?: ApiErrorFields;
+    cause?: unknown;
+};
+export declare const isApiErrorCode: (value: unknown) => value is string;
+export declare class ApiHttpError extends Error {
+    readonly __rpcbaseApiHttpError = true;
+    readonly status: number;
+    readonly code: string;
+    readonly publicMessage?: string;
+    readonly fields?: ApiErrorFields;
+    constructor(status: number, code: string, options?: ApiHttpErrorOptions);
+}
+type ApiHttpErrorLike = Error & {
+    __rpcbaseApiHttpError: true;
+    status: number;
+    code: string;
+    publicMessage?: string;
+    fields?: ApiErrorFields;
+};
+export declare const isApiHttpError: (error: unknown) => error is ApiHttpErrorLike;
+export declare const getApiRequestId: (res: Response) => string;
+export declare const apiRequestIdMiddleware: RequestHandler;
+export declare const toApiErrorResponse: (error: Pick<ApiHttpErrorLike, "code" | "publicMessage" | "fields">, requestId: string) => ApiErrorResponse;
+export declare const sendApiHttpError: (res: Response, error: ApiHttpErrorLike) => void;
+export type ApiErrorMiddlewareContext = {
+    requestId: string;
+    req: Request;
+};
+export type ApiErrorMiddlewareOptions = {
+    internalMessage?: string;
+    onError?: (error: unknown, context: ApiErrorMiddlewareContext) => void | Promise<void>;
+};
+export declare const createApiErrorMiddleware: (options?: ApiErrorMiddlewareOptions) => ErrorRequestHandler;
+export declare const apiErrorMiddleware: ErrorRequestHandler<import('express-serve-static-core').ParamsDictionary, any, any, import('qs').ParsedQs, Record<string, any>>;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAGrF,eAAO,MAAM,qBAAqB,iBAAiB,CAAA;AAKnD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;AAErD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,KAAK,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACQ,CAAA;AAEjE,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,qBAAqB,QAAO;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAA;gBAEpB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB;CAgB5E;AAED,KAAK,gBAAgB,GAAG,KAAK,GAAG;IAC9B,qBAAqB,EAAE,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,gBAWxD,CAAA;AAqCD,eAAO,MAAM,eAAe,GAAI,KAAK,QAAQ,KAAG,MAuB/C,CAAA;AAED,eAAO,MAAM,sBAAsB,EAAE,cAGpC,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC7B,OAAO,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,eAAe,GAAG,QAAQ,CAAC,EAClE,WAAW,MAAM,KAChB,gBAMD,CAAA;AAEF,eAAO,MAAM,gBAAgB,GAAI,KAAK,QAAQ,EAAE,OAAO,gBAAgB,KAAG,IAGzE,CAAA;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,OAAO,CAAA;CACb,CAAA;AAED,MAAM,MAAM,yBAAyB,GAAG;IACtC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvF,CAAA;AA6BD,eAAO,MAAM,wBAAwB,GACnC,UAAS,yBAA8B,KACtC,mBA6BF,CAAA;AAED,eAAO,MAAM,kBAAkB,iIAA6B,CAAA"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types';
 export * from './initApi';
+export * from './errors';
 export * from './pagination';
 export * from './agentApiCatalog';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,mBAAmB,CAAA"}

package/dist/index.js

@@ -17,6 +17,7 @@ import * as m$3 from "node:querystring";
 import * as m$2 from "node:buffer";
 import * as m$1 from "node:net";
 import * as m from "util";
+import { randomUUID } from "node:crypto";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -27367,10 +27368,162 @@ var require_lib = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	})();
 }));
 //#endregion
-//#region src/initApi.ts
+//#region src/errors.ts
 var import_bluebird = /* @__PURE__ */ __toESM(require_bluebird(), 1);
 var import_express = require_express();
 var import_lib = /* @__PURE__ */ __toESM(require_lib(), 1);
+var API_REQUEST_ID_HEADER = "x-request-id";
+var API_REQUEST_ID_LOCAL = "rpcbaseApiRequestId";
+var API_ERROR_CODE_PATTERN = /^[a-z][A-Za-z0-9_.:-]*$/u;
+var isApiErrorCode = (value) => typeof value === "string" && API_ERROR_CODE_PATTERN.test(value);
+var ApiHttpError = class extends Error {
+	__rpcbaseApiHttpError = true;
+	status;
+	code;
+	publicMessage;
+	fields;
+	constructor(status, code, options = {}) {
+		if (!Number.isInteger(status) || status < 400 || status > 599) throw new RangeError("ApiHttpError status must be an integer between 400 and 599");
+		if (!isApiErrorCode(code)) throw new TypeError("ApiHttpError code must start with a lowercase letter and contain only letters, numbers, '.', ':', '_' or '-'");
+		super(options.message ?? code, { cause: options.cause });
+		this.name = "ApiHttpError";
+		this.status = status;
+		this.code = code;
+		this.publicMessage = options.message;
+		this.fields = options.fields;
+	}
+};
+var isApiHttpError = (error) => {
+	if (error instanceof ApiHttpError) return true;
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	return candidate.__rpcbaseApiHttpError === true && Number.isInteger(candidate.status) && typeof candidate.status === "number" && candidate.status >= 400 && candidate.status <= 599 && isApiErrorCode(candidate.code);
+};
+var getExposedApiHttpError = (error) => {
+	if (!error || typeof error !== "object") return null;
+	const candidate = error;
+	if (candidate.expose !== true) return null;
+	const status = [candidate.status, candidate.statusCode].find((value) => typeof value === "number" && Number.isInteger(value) && value >= 400 && value < 500);
+	if (typeof status !== "number") return null;
+	const code = isApiErrorCode(candidate.type) ? candidate.type : isApiErrorCode(candidate.code) ? candidate.code : "http_error";
+	const message = typeof candidate.message === "string" && candidate.message.trim() ? candidate.message.trim() : void 0;
+	return new ApiHttpError(status, code, {
+		...message ? { message } : {},
+		cause: error
+	});
+};
+var getApiRequestId = (res) => {
+	res.locals ??= {};
+	const existing = res.locals[API_REQUEST_ID_LOCAL];
+	if (typeof existing === "string" && existing.trim()) {
+		const requestId = existing.trim();
+		res.locals[API_REQUEST_ID_LOCAL] = requestId;
+		if (!res.headersSent) res.setHeader(API_REQUEST_ID_HEADER, requestId);
+		return requestId;
+	}
+	const existingHeader = res.getHeader(API_REQUEST_ID_HEADER);
+	if (typeof existingHeader === "string" && existingHeader.trim()) {
+		const requestId = existingHeader.trim();
+		res.locals[API_REQUEST_ID_LOCAL] = requestId;
+		if (!res.headersSent) res.setHeader(API_REQUEST_ID_HEADER, requestId);
+		return requestId;
+	}
+	const requestId = randomUUID();
+	res.locals[API_REQUEST_ID_LOCAL] = requestId;
+	if (!res.headersSent) res.setHeader(API_REQUEST_ID_HEADER, requestId);
+	return requestId;
+};
+var apiRequestIdMiddleware = (_req, res, next) => {
+	getApiRequestId(res);
+	next();
+};
+var toApiErrorResponse = (error, requestId) => ({
+	success: false,
+	error: error.code,
+	...error.publicMessage ? { message: error.publicMessage } : {},
+	...error.fields ? { fields: error.fields } : {},
+	requestId
+});
+var sendApiHttpError = (res, error) => {
+	const requestId = getApiRequestId(res);
+	res.status(error.status).json(toApiErrorResponse(error, requestId));
+};
+var reportApiError = (error, context, onError) => {
+	if (onError) {
+		try {
+			const reportingResult = onError(error, context);
+			if (reportingResult && typeof reportingResult.then === "function") reportingResult.catch((reportingError) => {
+				console.error("[rpcbase/api] error reporter failed", reportingError);
+			});
+		} catch (reportingError) {
+			console.error("[rpcbase/api] error reporter failed", reportingError);
+		}
+		return;
+	}
+	console.error("[rpcbase/api] API error", {
+		requestId: context.requestId,
+		method: context.req.method,
+		path: context.req.originalUrl,
+		error
+	});
+};
+var createApiErrorMiddleware = (options = {}) => (error, req, res, next) => {
+	if (res.headersSent) {
+		next(error);
+		return;
+	}
+	const requestId = getApiRequestId(res);
+	const context = {
+		requestId,
+		req
+	};
+	if (isApiHttpError(error)) {
+		if (error.status >= 500) reportApiError(error, context, options.onError);
+		sendApiHttpError(res, error);
+		return;
+	}
+	const exposedError = getExposedApiHttpError(error);
+	if (exposedError) {
+		sendApiHttpError(res, exposedError);
+		return;
+	}
+	reportApiError(error, context, options.onError);
+	res.status(500).json({
+		success: false,
+		error: "internal_error",
+		...options.internalMessage ? { message: options.internalMessage } : {},
+		requestId
+	});
+};
+var apiErrorMiddleware = createApiErrorMiddleware();
+//#endregion
+//#region src/requestValidation.ts
+var getErrorFields = (issues) => {
+	const fields = {};
+	for (const issue of issues) {
+		const path = issue.path.map(String).join(".");
+		if (!path) continue;
+		const messages = fields[path] ?? [];
+		messages.push(issue.message);
+		fields[path] = messages;
+	}
+	return Object.keys(fields).length > 0 ? fields : void 0;
+};
+var getApiRoutePath = (route) => {
+	if (typeof route === "string") return route;
+	return "ROUTE" in route ? route.ROUTE : route.Route;
+};
+var parseApiRequest = (schema, input) => {
+	const result = schema.safeParse(input);
+	if (result.success) return result.data;
+	throw new ApiHttpError(400, "invalid_request", {
+		message: "Invalid request payload.",
+		fields: getErrorFields(result.error.issues),
+		cause: result.error
+	});
+};
+//#endregion
+//#region src/initApi.ts
 var loadInitApiClient = async () => {
 	return (await import("@rpcbase/client")).initApiClient;
 };
@@ -27379,14 +27532,24 @@ process.env = {
 	...__rb_env__,
 	...process.env
 };
-var initApi = async ({ app, routes, cors: corsOptions }) => {
+var withApiRequestIdExposed = (options) => {
+	const configured = options?.exposedHeaders;
+	const exposedHeaders = Array.isArray(configured) ? [...configured] : configured ? [configured] : [];
+	if (!exposedHeaders.some((header) => header.toLowerCase() === "x-request-id")) exposedHeaders.push(API_REQUEST_ID_HEADER);
+	return {
+		...options,
+		exposedHeaders
+	};
+};
+var initApi = async ({ app, routes, cors: corsOptions, errors }) => {
 	await (await loadInitApiClient())({ app });
-	const registerHandler = (method, path, handler) => {
+	const registerHandler = (method, route, handler) => {
+		const path = getApiRoutePath(route);
 		assert(path.startsWith("/api"), "API routes must start with /api");
 		app[method](path, async (req, res, next) => {
-			const payload = method === "get" ? req.query : req.body ?? {};
+			const requestPayload = method === "get" ? req.query : req.body ?? {};
 			try {
-				const result = await handler(payload, {
+				const result = await handler(typeof route === "string" ? requestPayload : parseApiRequest(route.requestSchema, requestPayload), {
 					req,
 					res
 				});
@@ -27398,28 +27561,24 @@ var initApi = async ({ app, routes, cors: corsOptions }) => {
 			}
 		});
 	};
+	const createApiMethod = (method) => ((route, handler) => {
+		registerHandler(method, route, handler);
+	});
 	const api = {
 		use: (path, middleware) => {
 			app.use(path, middleware);
 		},
-		get: (path, handler) => {
-			registerHandler("get", path, handler);
-		},
-		post: (path, handler) => {
-			registerHandler("post", path, handler);
-		},
-		put: (path, handler) => {
-			registerHandler("put", path, handler);
-		},
-		delete: (path, handler) => {
-			registerHandler("delete", path, handler);
-		}
+		get: createApiMethod("get"),
+		post: createApiMethod("post"),
+		put: createApiMethod("put"),
+		delete: createApiMethod("delete")
 	};
-	app.use("/api", (0, import_lib.default)(corsOptions));
+	app.use("/api", (0, import_lib.default)(withApiRequestIdExposed(corsOptions)));
 	app.use("/api", (0, import_express.json)({ limit: "8mb" }));
 	app.use("/api", function __FIRST_API_MIDDLEWARE__(_req, _res, next) {
 		next();
 	});
+	app.use("/api", apiRequestIdMiddleware);
 	const routeEntries = Object.entries(routes);
 	const totalRoutes = routeEntries.length;
 	const loadedModules = /* @__PURE__ */ new Map();
@@ -27443,19 +27602,33 @@ var initApi = async ({ app, routes, cors: corsOptions }) => {
 	}
 	console.log("Done loading routes");
 	app.use("/api", (req, res) => {
-		res.status(404).json({ error: `Not Found: ${req.method}:${req.originalUrl}` });
+		const requestId = getApiRequestId(res);
+		res.status(404).json(toApiErrorResponse(new ApiHttpError(404, "not_found", { message: `Not Found: ${req.method}:${req.originalUrl}` }), requestId));
 	});
 	app.use("/api", (err, _req, res, next) => {
 		if (res.headersSent) return next(err);
+		if (isApiHttpError(err)) {
+			next(err);
+			return;
+		}
 		const errLike = err;
 		const code = typeof errLike?.code === "string" ? errLike.code : null;
 		const statusCode = typeof errLike?.statusCode === "number" ? errLike.statusCode : typeof errLike?.status === "number" ? errLike.status : null;
 		if (code === "invalid_pagination") {
-			res.status(statusCode ?? 400).json({ error: code });
+			next(new ApiHttpError(statusCode && Number.isInteger(statusCode) && statusCode >= 400 && statusCode <= 599 ? statusCode : 400, code));
+			return;
+		}
+		if (errLike.type === "entity.parse.failed") {
+			next(new ApiHttpError(400, "invalid_json", { message: "Request body must contain valid JSON." }));
+			return;
+		}
+		if (errLike.type === "entity.too.large") {
+			next(new ApiHttpError(413, "payload_too_large", { message: "Request body is too large." }));
 			return;
 		}
 		next(err);
 	});
+	app.use("/api", createApiErrorMiddleware(errors));
 };
 //#endregion
 //#region src/agentApiCatalog.ts
@@ -27471,6 +27644,6 @@ var AGENT_API_BLOCKED_REASONS = [
 	"other"
 ];
 //#endregion
-export { AGENT_API_BLOCKED_REASONS, MOCK_TYPE, initApi };
+export { AGENT_API_BLOCKED_REASONS, API_REQUEST_ID_HEADER, ApiHttpError, MOCK_TYPE, apiErrorMiddleware, apiRequestIdMiddleware, createApiErrorMiddleware, getApiRequestId, initApi, isApiErrorCode, isApiHttpError, sendApiHttpError, toApiErrorResponse };
 
 //# sourceMappingURL=index.js.map