From 7d17768c68882ef845b76c4172f33e5d53c86020 Mon Sep 17 00:00:00 2001
From: Oksamies <asko.soisalo@gmail.com>
Date: Wed, 19 Nov 2025 14:39:17 +0200
Subject: [PATCH] Add tests for ApiError and user-facing error mapping

---
 .../src/__tests__/errors.test.ts              |  44 +++++++
 .../src/__tests__/userFacingError.test.ts     | 108 ++++++++++++++++++
 2 files changed, 152 insertions(+)
 create mode 100644 packages/thunderstore-api/src/__tests__/errors.test.ts
 create mode 100644 packages/thunderstore-api/src/__tests__/userFacingError.test.ts

diff --git a/packages/thunderstore-api/src/__tests__/errors.test.ts b/packages/thunderstore-api/src/__tests__/errors.test.ts
new file mode 100644
index 000000000..ce18de47d
--- /dev/null
+++ b/packages/thunderstore-api/src/__tests__/errors.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "../errors";
+
+describe("ApiError", () => {
+  it("includes stale session guidance for unauthorized responses", async () => {
+    const response = new Response(
+      JSON.stringify({ detail: "Session token is no longer valid." }),
+      {
+        status: 401,
+        statusText: "Unauthorized",
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+
+    const error = await ApiError.createFromResponse(response, {
+      sessionWasUsed: true,
+    });
+
+    expect(error.message).toContain(
+      "Your session has expired. Please sign in again."
+    );
+    expect(error.message).toContain("Session token is no longer valid.");
+    expect(error.message).toContain("(401 Unauthorized)");
+  });
+
+  it("surfaces validation issue details when available", async () => {
+    const response = new Response(
+      JSON.stringify({ errors: { field: ["Missing value", "Invalid state"] } }),
+      {
+        status: 422,
+        statusText: "Unprocessable Entity",
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+
+    const error = await ApiError.createFromResponse(response);
+
+    expect(error.message).toContain(
+      "The server could not process the request due to validation errors."
+    );
+    expect(error.message).toContain("Missing value");
+    expect(error.message).toContain("(422 Unprocessable Entity)");
+  });
+});
diff --git a/packages/thunderstore-api/src/__tests__/userFacingError.test.ts b/packages/thunderstore-api/src/__tests__/userFacingError.test.ts
new file mode 100644
index 000000000..e93ef28a1
--- /dev/null
+++ b/packages/thunderstore-api/src/__tests__/userFacingError.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  ApiError,
+  RequestBodyParseError,
+  createResourceNotFoundError,
+  mapApiErrorToUserFacingError,
+  UserFacingError,
+} from "../index";
+
+describe("mapApiErrorToUserFacingError", () => {
+  it("categorises stale session responses as auth errors", async () => {
+    const response = new Response(
+      JSON.stringify({ detail: "Session token is no longer valid." }),
+      {
+        status: 401,
+        statusText: "Unauthorized",
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+
+    const apiError = await ApiError.createFromResponse(response, {
+      sessionWasUsed: true,
+    });
+
+    const userFacing = mapApiErrorToUserFacingError(apiError);
+
+    expect(userFacing).toBeInstanceOf(UserFacingError);
+    expect(userFacing.category).toBe("auth");
+    expect(userFacing.status).toBe(401);
+    expect(userFacing.headline).toContain("session has expired");
+    expect(userFacing.description).toContain(
+      "Session token is no longer valid."
+    );
+    expect(userFacing.context?.sessionWasUsed).toBe(true);
+  });
+
+  it("maps request validation issues to validation category", () => {
+    const schema = z.object({ field: z.string().min(1) });
+    const result = schema.safeParse({ field: "" });
+
+    expect(result.success).toBe(false);
+
+    const zodError = result.success ? undefined : result.error;
+    const validationError = new RequestBodyParseError(zodError!);
+
+    const userFacing = mapApiErrorToUserFacingError(validationError);
+
+    expect(userFacing.category).toBe("validation");
+    expect(userFacing.headline).toContain("Invalid request data");
+  });
+
+  it("falls back to network category for fetch issues", () => {
+    const networkError = new TypeError("Failed to fetch");
+
+    const userFacing = mapApiErrorToUserFacingError(networkError, {
+      fallbackHeadline: "Network issue detected.",
+      fallbackDescription: "Check your connection and retry.",
+    });
+
+    expect(userFacing.category).toBe("network");
+    expect(userFacing.headline).toBe("Network issue detected.");
+    expect(userFacing.description).toBe("Check your connection and retry.");
+  });
+
+  it("creates a consistent not found user-facing error", async () => {
+    const response = new Response(JSON.stringify({ detail: "Not found." }), {
+      status: 404,
+      statusText: "Not Found",
+      headers: { "Content-Type": "application/json" },
+    });
+
+    const apiError = await ApiError.createFromResponse(response);
+
+    const userFacing = createResourceNotFoundError({
+      resourceName: "team",
+      identifier: "alpha",
+      originalError: apiError,
+    });
+
+    expect(userFacing).toBeInstanceOf(UserFacingError);
+    expect(userFacing.headline).toBe("Team not found.");
+    expect(userFacing.description).toBe('We could not find the team "alpha".');
+    expect(userFacing.status).toBe(404);
+    expect(userFacing.category).toBe("not_found");
+    expect(userFacing.context?.resource).toBe("team");
+    expect(userFacing.context?.identifier).toBe("alpha");
+  });
+
+  it("falls back to generic copy when identifier absent", async () => {
+    const response = new Response("Not found.", {
+      status: 404,
+      statusText: "Not Found",
+    });
+
+    const apiError = await ApiError.createFromResponse(response);
+
+    const userFacing = createResourceNotFoundError({
+      resourceName: "team",
+      originalError: apiError,
+    });
+
+    expect(userFacing.description).toBe(
+      "We could not find the requested team."
+    );
+    expect(userFacing.context?.identifier).toBeUndefined();
+  });
+});