cred402/lib/gateway/errors.ts
2026-06-16 02:50:52 +03:00

86 lines
2.3 KiB
TypeScript

/**
* Typed API errors + consistent response envelope (p2 §7.1, patterns.md).
*
* Every response — success or failure — uses one envelope shape, and every
* error maps to an HTTP status + stable machine code. Internal details (stack
* traces, DB errors) are logged server-side, never leaked to clients.
*/
export interface ApiSuccess<T> {
success: true;
data: T;
request_id: string;
}
export interface ApiFailure {
success: false;
error: { code: string; message: string };
request_id: string;
}
export type ApiResponse<T> = ApiSuccess<T> | ApiFailure;
export function ok<T>(data: T, request_id: string): ApiSuccess<T> {
return { success: true, data, request_id };
}
export function fail(code: string, message: string, request_id: string): ApiFailure {
return { success: false, error: { code, message }, request_id };
}
/** Base class for errors that are safe to surface to clients with a status. */
export class ApiError extends Error {
constructor(
readonly status: number,
readonly code: string,
message: string,
) {
super(message);
this.name = new.target.name;
}
}
export class ValidationError extends ApiError {
constructor(message: string) {
super(400, "validation_error", message);
}
}
export class UnauthorizedError extends ApiError {
constructor(message = "missing or invalid API key") {
super(401, "unauthorized", message);
}
}
export class ForbiddenError extends ApiError {
constructor(message = "insufficient scope") {
super(403, "forbidden", message);
}
}
export class NotFoundError extends ApiError {
constructor(message = "resource not found") {
super(404, "not_found", message);
}
}
export class ConflictError extends ApiError {
constructor(message: string) {
super(409, "conflict", message);
}
}
export class RateLimitError extends ApiError {
constructor(readonly retryAfterMs: number) {
super(429, "rate_limited", "rate limit exceeded");
}
}
/** Map any thrown value to a client-safe { status, code, message }. */
export function toApiError(err: unknown): ApiError {
if (err instanceof ApiError) return err;
// Domain invariant violations from the ledger surface as 422, message-only.
if (err instanceof Error) return new ApiError(422, "unprocessable", err.message);
return new ApiError(500, "internal_error", "internal server error");
}