task: standardize API error envelope

Author: omosvico

src/errors/AppError.ts

@@ -0,0 +1,31 @@
+import { ErrorCodes } from "./codes";
+
+export interface AppErrorDetails {
+  [key: string]: unknown;
+}
+
+export class AppError extends Error {
+  public readonly code: string;
+  public readonly status: number;
+  public readonly details?: AppErrorDetails;
+
+  constructor(code: string, message: string, status: number = 500, details?: AppErrorDetails) {
+    super(message);
+    this.name = "AppError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+
+  static notFound(message = "Resource not found"): AppError {
+    return new AppError(ErrorCodes.NOT_FOUND, message, 404);
+  }
+
+  static internal(message = "Internal error"): AppError {
+    return new AppError(ErrorCodes.INTERNAL_ERROR, message, 500);
+  }
+
+  static validation(details?: AppErrorDetails): AppError {
+    return new AppError(ErrorCodes.VALIDATION_ERROR, "Validation failed", 400, details);
+  }
+}

src/errors/codes.ts

@@ -0,0 +1,8 @@
+export const ErrorCodes = {
+  INTERNAL_ERROR: "internal_error",
+  NOT_FOUND: "not_found",
+  VALIDATION_ERROR: "validation_error",
+  REQUEST_FAILED: "request_failed",
+} as const;
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];

src/errors/index.ts

@@ -0,0 +1,4 @@
+export { AppError } from "./AppError";
+export type { AppErrorDetails } from "./AppError";
+export { ErrorCodes } from "./codes";
+export type { ErrorCode } from "./codes";

src/middleware/errorHandler.ts

@@ -1,10 +1,49 @@
 import type { NextFunction, Request, Response } from "express";
+import { ZodError } from "zod";
 import { logger } from "../config/logger";
+import { AppError, ErrorCodes } from "../errors";
+
+function getRequestId(req: Request): string {
+  const id = (req as { id?: unknown }).id;
+  if (id == null) return "";
+  return String(id);
+}
 
 export function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction) {
-  logger.error({ err, path: req.path, method: req.method }, "request_failed");
-  const status = (err as { status?: number }).status ?? 500;
-  res.status(status).json({
-    error: { code: status === 500 ? "internal_error" : "request_failed" },
+  const requestId = getRequestId(req);
+
+  if (err instanceof AppError) {
+    logger.warn({ err, requestId, path: req.path, method: req.method }, err.message);
+    res.status(err.status).json({
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.details ? { details: err.details } : {}),
+        requestId,
+      },
+    });
+    return;
+  }
+
+  if (err instanceof ZodError) {
+    logger.warn({ err, requestId, path: req.path, method: req.method }, "validation_error");
+    res.status(400).json({
+      error: {
+        code: ErrorCodes.VALIDATION_ERROR,
+        message: "Validation failed",
+        details: err.issues,
+        requestId,
+      },
+    });
+    return;
+  }
+
+  logger.error({ err, requestId, path: req.path, method: req.method }, "unhandled_error");
+  res.status(500).json({
+    error: {
+      code: ErrorCodes.INTERNAL_ERROR,
+      message: "Internal error",
+      requestId,
+    },
   });
 }

src/routes/markets.ts

@@ -1,5 +1,6 @@
 import { Router } from "express";
 import { listMarkets, getMarketById } from "../services/marketService";
+import { AppError } from "../errors";
 
 export const marketsRouter = Router();
 
@@ -12,7 +13,7 @@ marketsRouter.get("/", async (_req, res, next) => {
 marketsRouter.get("/:id", async (req, res, next) => {
   try {
     const market = await getMarketById(req.params.id);
-    if (!market) return res.status(404).json({ error: { code: "not_found" } });
+    if (!market) return next(AppError.notFound("Market not found"));
     res.json({ data: market });
   } catch (e) { next(e); }
 });

tests/errorHandler.test.ts

@@ -0,0 +1,116 @@
+process.env.DATABASE_URL = "postgres://test:test@localhost:5432/test";
+process.env.JWT_SECRET = "a".repeat(32);
+process.env.SOROBAN_RPC_URL = "https://rpc.testnet.stellar.org";
+process.env.HORIZON_URL = "https://horizon.testnet.stellar.org";
+process.env.PREDICTIFY_CONTRACT_ID = "CABC...";
+
+import request from "supertest";
+import { ZodError, z } from "zod";
+import express from "express";
+import { AppError, ErrorCodes } from "../src/errors";
+
+describe("AppError", () => {
+  it("creates an error with code, message, status", () => {
+    const err = new AppError("my_code", "my message", 400);
+    expect(err).toBeInstanceOf(Error);
+    expect(err.code).toBe("my_code");
+    expect(err.message).toBe("my message");
+    expect(err.status).toBe(400);
+    expect(err.details).toBeUndefined();
+  });
+
+  it("creates an error with details", () => {
+    const err = new AppError("my_code", "my message", 422, { field: "name" });
+    expect(err.details).toEqual({ field: "name" });
+  });
+
+  it("defaults to 500", () => {
+    const err = new AppError("my_code", "msg");
+    expect(err.status).toBe(500);
+  });
+
+  describe("static factories", () => {
+    it("notFound creates 404", () => {
+      const err = AppError.notFound("X not found");
+      expect(err.code).toBe(ErrorCodes.NOT_FOUND);
+      expect(err.status).toBe(404);
+      expect(err.message).toBe("X not found");
+    });
+
+    it("internal creates 500", () => {
+      const err = AppError.internal("Boom");
+      expect(err.code).toBe(ErrorCodes.INTERNAL_ERROR);
+      expect(err.status).toBe(500);
+      expect(err.message).toBe("Boom");
+    });
+
+    it("validation creates 400", () => {
+      const err = AppError.validation({ fields: ["email"] });
+      expect(err.code).toBe(ErrorCodes.VALIDATION_ERROR);
+      expect(err.status).toBe(400);
+      expect(err.details).toEqual({ fields: ["email"] });
+    });
+  });
+});
+
+describe("GET /api/markets/:id", () => {
+  it("returns 404 with standard envelope for unknown market", async () => {
+    const { createApp } = await import("../src/index");
+    const res = await request(createApp()).get("/api/markets/nonexistent");
+    expect(res.status).toBe(404);
+    expect(res.body.error).toBeDefined();
+    expect(res.body.error.code).toBe("not_found");
+    expect(res.body.error.message).toBe("Market not found");
+    expect(res.body.error.requestId).toEqual(expect.any(String));
+  });
+});
+
+describe("errorHandler", () => {
+  function createAppWithError(err: unknown): express.Express {
+    const app = express();
+    app.use(express.json());
+    app.get("/error", () => { throw err; });
+    const { errorHandler } = require("../src/middleware/errorHandler");
+    app.use(errorHandler);
+    return app;
+  }
+
+  it("handles AppError with correct envelope", async () => {
+    const app = createAppWithError(new AppError("custom_code", "custom msg", 418));
+    const res = await request(app).get("/error");
+    expect(res.status).toBe(418);
+    expect(res.body.error.code).toBe("custom_code");
+    expect(res.body.error.message).toBe("custom msg");
+    expect(res.body.error.requestId).toEqual(expect.any(String));
+  });
+
+  it("handles ZodError with validation envelope", async () => {
+    const schema = z.object({ name: z.string().min(1) });
+    let zodErr: ZodError | null = null;
+    try { schema.parse({ name: "" }); } catch (e) { zodErr = e as ZodError; }
+
+    const app = createAppWithError(zodErr!);
+    const res = await request(app).get("/error");
+    expect(res.status).toBe(400);
+    expect(res.body.error.code).toBe(ErrorCodes.VALIDATION_ERROR);
+    expect(res.body.error.message).toBe("Validation failed");
+    expect(res.body.error.details).toBeInstanceOf(Array);
+    expect(res.body.error.requestId).toEqual(expect.any(String));
+  });
+
+  it("handles unknown error with 500 envelope", async () => {
+    const app = createAppWithError(new Error("unexpected"));
+    const res = await request(app).get("/error");
+    expect(res.status).toBe(500);
+    expect(res.body.error.code).toBe(ErrorCodes.INTERNAL_ERROR);
+    expect(res.body.error.message).toBe("Internal error");
+    expect(res.body.error.requestId).toEqual(expect.any(String));
+  });
+
+  it("does not leak stack traces", async () => {
+    const app = createAppWithError(new Error("hidden"));
+    const res = await request(app).get("/error");
+    expect(res.body.error.stack).toBeUndefined();
+    expect(res.text).not.toContain("Error: hidden");
+  });
+});

tests/health.test.ts

@@ -1,3 +1,9 @@
+process.env.DATABASE_URL = "postgres://test:test@localhost:5432/test";
+process.env.JWT_SECRET = "a".repeat(32);
+process.env.SOROBAN_RPC_URL = "https://rpc.testnet.stellar.org";
+process.env.HORIZON_URL = "https://horizon.testnet.stellar.org";
+process.env.PREDICTIFY_CONTRACT_ID = "CABC...";
+
 import request from "supertest";
 import { createApp } from "../src/index";