(thunderstore-api) Implement user-facing error handling improvements and update tests for authentication errors

Author: Oksamies

packages/thunderstore-api/src/apiFetch.ts

@@ -44,36 +44,41 @@ function sleep(delay: number) {
   return new Promise((resolve) => setTimeout(resolve, delay));
 }
 
-export type apiFetchArgs<B, QP> = {
+type SchemaOrUndefined<Schema extends z.ZodSchema | undefined> =
+  Schema extends z.ZodSchema ? z.infer<Schema> : undefined;
+
+type apiFetchArgs<
+  RequestSchema extends z.ZodSchema | undefined,
+  QueryParamsSchema extends z.ZodSchema | undefined,
+  ResponseSchema extends z.ZodSchema | undefined,
+> = {
   config: () => RequestConfig;
   path: string;
-  queryParams?: QP;
+  queryParams?: SchemaOrUndefined<QueryParamsSchema>;
   request?: Omit<RequestInit, "headers" | "body"> & { body?: string };
   useSession?: boolean;
-  bodyRaw?: B;
+  bodyRaw?: SchemaOrUndefined<RequestSchema>;
+  requestSchema: RequestSchema;
+  queryParamsSchema: QueryParamsSchema;
+  responseSchema: ResponseSchema;
 };
 
-type schemaOrUndefined<A> = A extends z.ZodSchema
-  ? z.infer<A>
-  : never | undefined;
-
-export async function apiFetch(props: {
-  args: apiFetchArgs<
-    schemaOrUndefined<typeof props.requestSchema>,
-    schemaOrUndefined<typeof props.queryParamsSchema>
-  >;
-  requestSchema: z.ZodSchema | undefined;
-  queryParamsSchema: z.ZodSchema | undefined;
-  responseSchema: z.ZodSchema | undefined;
-}): Promise<schemaOrUndefined<typeof props.responseSchema>> {
-  const { args, requestSchema, queryParamsSchema, responseSchema } = props;
+export async function apiFetch<
+  RequestSchema extends z.ZodSchema | undefined,
+  QueryParamsSchema extends z.ZodSchema | undefined,
+  ResponseSchema extends z.ZodSchema | undefined,
+>(
+  args: apiFetchArgs<RequestSchema, QueryParamsSchema, ResponseSchema>
+): Promise<SchemaOrUndefined<ResponseSchema>> {
+  const { requestSchema, queryParamsSchema, responseSchema } = args;
 
   if (requestSchema && args.bodyRaw) {
     const parsedRequestBody = requestSchema.safeParse(args.bodyRaw);
     if (!parsedRequestBody.success) {
       throw new RequestBodyParseError(parsedRequestBody.error);
     }
   }
+
   if (queryParamsSchema && args.queryParams) {
     const parsedQueryParams = queryParamsSchema.safeParse(args.queryParams);
     if (!parsedQueryParams.success) {
@@ -88,8 +93,7 @@ export async function apiFetch(props: {
         apiHost: config().apiHost,
         sessionId: undefined,
       };
-  // TODO: Query params have stronger types, but they are not just shown here.
-  // Look into furthering the ensuring of passing proper query params.
+  const sessionWasUsed = Boolean(usedConfig.sessionId);
   const url = getUrl(usedConfig, path, queryParams);
 
   const response = await fetchRetry(url, {
@@ -101,17 +105,21 @@ export async function apiFetch(props: {
   });
 
   if (!response.ok) {
-    throw await ApiError.createFromResponse(response);
+    throw await ApiError.createFromResponse(response, {
+      sessionWasUsed,
+    });
   }
 
-  if (responseSchema === undefined) return undefined;
+  if (responseSchema === undefined) {
+    return undefined as SchemaOrUndefined<ResponseSchema>;
+  }
 
   const parsed = responseSchema.safeParse(await response.json());
   if (!parsed.success) {
     throw new ParseError(parsed.error);
-  } else {
-    return parsed.data;
   }
+
+  return parsed.data;
 }
 
 function getAuthHeaders(config: RequestConfig): RequestInit["headers"] {

packages/thunderstore-api/src/errors.ts

@@ -1,11 +1,30 @@
 import { z } from "zod";
 
+import { sanitizeServerDetail } from "./errors/sanitizeServerDetail";
+import { formatErrorMessage } from "./utils";
+
 type JSONValue =
   | string
   | number
   | boolean
   | { [x: string]: JSONValue }
-  | JSONValue[];
+  | JSONValue[]
+  | null;
+
+type ApiErrorContext = {
+  sessionWasUsed?: boolean;
+};
+
+const JSON_MESSAGE_PRIORITY_KEYS = [
+  "detail",
+  "message",
+  "error",
+  "errors",
+  "non_field_errors",
+  "root",
+  "__all__",
+  "title",
+];
 
 export function isApiError(e: Error | ApiError | unknown): e is ApiError {
   return e instanceof ApiError;
@@ -14,69 +33,173 @@ export function isApiError(e: Error | ApiError | unknown): e is ApiError {
 export class ApiError extends Error {
   response: Response;
   responseJson?: JSONValue;
+  responseText?: string;
+  context?: ApiErrorContext;
+  responseSummary?: string;
 
   constructor(args: {
     message: string;
     response: Response;
     responseJson?: JSONValue;
+    responseText?: string;
+    context?: ApiErrorContext;
+    responseSummary?: string;
   }) {
     super(args.message);
     this.responseJson = args.responseJson;
     this.response = args.response;
+    this.responseText = args.responseText;
+    this.context = args.context;
+    this.responseSummary = args.responseSummary;
   }
 
-  static async createFromResponse(response: Response): Promise<ApiError> {
+  static async createFromResponse(
+    response: Response,
+    context: ApiErrorContext = {}
+  ): Promise<ApiError> {
+    let responseText: string | undefined;
     let responseJson: JSONValue | undefined;
     try {
-      responseJson = await response.json();
+      responseText = await response.clone().text();
+    } catch {
+      responseText = undefined;
+    }
+    try {
+      responseJson = responseText
+        ? JSON.parse(responseText)
+        : await response.json();
       // eslint-disable-next-line @typescript-eslint/no-unused-vars
     } catch (e) {
       responseJson = undefined;
     }
 
+    const responseSummary = extractMessage(responseJson ?? responseText);
+
     return new ApiError({
-      message: `${response.status}: ${response.statusText}`,
+      message: buildApiErrorMessage({ response, responseJson }),
       response: response,
       responseJson: responseJson,
+      responseText,
+      context,
+      responseSummary,
     });
   }
 
   getFieldErrors(): { [key: string | "root"]: string[] } {
-    if (typeof this.responseJson !== "object")
+    if (!this.responseJson || typeof this.responseJson !== "object")
       return { root: ["Unknown error occurred"] };
     if (Array.isArray(this.responseJson)) {
       return {
-        root: this.responseJson.map((x) => x.toString()),
+        root: this.responseJson.map((x) => String(x)),
       };
     } else {
       return Object.fromEntries(
         Object.entries(this.responseJson).map(([key, val]) => {
           return [
             key,
-            Array.isArray(val)
-              ? val.map((x) => x.toString())
-              : [val.toString()],
+            Array.isArray(val) ? val.map((x) => String(x)) : [String(val)],
           ];
         })
       );
     }
   }
+
+  get statusCode(): number {
+    return this.response.status;
+  }
+
+  get statusText(): string {
+    return this.response.statusText;
+  }
 }
 
+/**
+ * Raised when a request body fails validation against its Zod schema.
+ */
 export class RequestBodyParseError extends Error {
   constructor(public error: z.ZodError) {
-    super(error.message);
+    super(formatErrorMessage(error));
   }
 }
 
+/**
+ * Raised when query parameters fail validation against their Zod schema.
+ */
 export class RequestQueryParamsParseError extends Error {
   constructor(public error: z.ZodError) {
-    super(error.message);
+    super(formatErrorMessage(error));
   }
 }
 
+/**
+ * Raised when response payloads fail validation against their expected Zod schema.
+ */
 export class ParseError extends Error {
   constructor(public error: z.ZodError) {
-    super(error.message);
+    super(formatErrorMessage(error));
+  }
+}
+
+function buildApiErrorMessage(args: {
+  response: Response;
+  responseJson?: JSONValue;
+}): string {
+  const { response, responseJson } = args;
+  const statusLabel = getStatusLabel(response);
+  const detailMessage = extractMessage(responseJson);
+
+  if (detailMessage) {
+    return `${detailMessage} (${statusLabel})`;
+  }
+
+  return statusLabel;
+}
+
+function extractMessage(value: JSONValue | undefined): string | undefined {
+  if (value === undefined || value === null) return undefined;
+
+  if (typeof value === "string") {
+    return sanitizeServerDetail(value);
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return sanitizeServerDetail(String(value));
+  }
+
+  if (Array.isArray(value)) {
+    const parts = value
+      .map((item) => extractMessage(item))
+      .filter((item): item is string => Boolean(item));
+
+    if (parts.length > 0) {
+      return sanitizeServerDetail(parts.join(" "));
+    }
+
+    return undefined;
   }
+
+  const objectValue = value as { [x: string]: JSONValue };
+
+  for (const key of JSON_MESSAGE_PRIORITY_KEYS) {
+    if (key in objectValue) {
+      const message = extractMessage(objectValue[key]);
+      if (message) {
+        return sanitizeServerDetail(message);
+      }
+    }
+  }
+
+  for (const entry of Object.values(objectValue)) {
+    const message = extractMessage(entry);
+    if (message) {
+      return message;
+    }
+  }
+
+  return undefined;
+}
+
+function getStatusLabel(response: Response): string {
+  const statusText = response.statusText?.trim() || "Error";
+  return `${response.status} ${statusText}`.trim();
 }

packages/thunderstore-api/src/get/__tests__/teamMembers.test.ts

@@ -11,5 +11,5 @@ it("ensures accessing team members requires authentication", async () => {
       data: {},
       queryParams: {},
     })
-  ).rejects.toThrowError("401: Unauthorized");
+  ).rejects.toThrowError("Authentication required. Please sign in.");
 });

packages/thunderstore-api/src/get/__tests__/teamServiceAccounts.test.ts

@@ -11,5 +11,5 @@ it("ensures accessing team members requires authentication", async () => {
       data: {},
       queryParams: {},
     })
-  ).rejects.toThrowError("401: Unauthorized");
+  ).rejects.toThrowError("Authentication required. Please sign in.");
 });