fix: add comprehensive error handling for JSON parsing failures

- Add url field to ApiError class for better debugging context
- Add try/catch blocks around all response.json() calls in success paths
- Include original error messages in JSON parsing error details
- Update ApiErrorType to include optional url field

Previously, if a server returned a successful status (200) but invalid JSON
(e.g., HTML error pages, malformed responses), the hooks would throw generic
parse errors. Now they throw structured ApiError instances with context about
what went wrong and which URL failed.

Author: AliceR

src/hooks/useCollection.ts

@@ -27,9 +27,18 @@ function useCollection(collectionId: string): StacCollectionHook {
         detail = await response.text();
       }
 
-      throw new ApiError(response.statusText, response.status, detail);
+      throw new ApiError(response.statusText, response.status, detail, response.url);
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      throw new ApiError(
+        'Invalid JSON Response',
+        response.status,
+        `Response is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        response.url
+      );
     }
-    return await response.json();
   };
 
   const {

src/hooks/useCollections.ts

@@ -27,9 +27,18 @@ function useCollections(): StacCollectionsHook {
         detail = await response.text();
       }
 
-      throw new ApiError(response.statusText, response.status, detail);
+      throw new ApiError(response.statusText, response.status, detail, response.url);
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      throw new ApiError(
+        'Invalid JSON Response',
+        response.status,
+        `Response is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        response.url
+      );
     }
-    return await response.json();
   };
 
   const {

src/hooks/useItem.ts

@@ -27,9 +27,18 @@ function useItem(url: string): ItemHook {
         detail = await response.text();
       }
 
-      throw new ApiError(response.statusText, response.status, detail);
+      throw new ApiError(response.statusText, response.status, detail, response.url);
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      throw new ApiError(
+        'Invalid JSON Response',
+        response.status,
+        `Response is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        response.url
+      );
     }
-    return await response.json();
   };
 
   const {

src/hooks/useStacApi.ts

@@ -22,7 +22,14 @@ function useStacApi(url: string, options?: GenericObject): StacApiHook {
         },
       });
       const baseUrl = response.url;
-      const json = await response.json();
+      let json;
+      try {
+        json = await response.json();
+      } catch (error) {
+        throw new Error(
+          `Invalid JSON response from STAC API: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
       const doesPost = json.links?.find(
         ({ rel, method }: Link) => rel === 'search' && method === 'POST'
       );

src/hooks/useStacSearch.ts

@@ -125,9 +125,18 @@ function useStacSearch(): StacSearchHook {
         detail = await response.text();
       }
 
-      throw new ApiError(response.statusText, response.status, detail);
+      throw new ApiError(response.statusText, response.status, detail, response.url);
+    }
+    try {
+      return await response.json();
+    } catch (error) {
+      throw new ApiError(
+        'Invalid JSON Response',
+        response.status,
+        `Response is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        response.url
+      );
     }
-    return await response.json();
   };
 
   /**

src/types/index.d.ts

@@ -6,4 +6,5 @@ export type ApiErrorType = {
   detail?: GenericObject | string;
   status: number;
   statusText: string;
+  url?: string;
 };

src/utils/ApiError.ts

@@ -8,13 +8,15 @@ export class ApiError extends Error {
   status: number;
   statusText: string;
   detail?: GenericObject | string;
+  url?: string;
 
-  constructor(statusText: string, status: number, detail?: GenericObject | string) {
+  constructor(statusText: string, status: number, detail?: GenericObject | string, url?: string) {
     super(statusText);
     this.name = 'ApiError';
     this.status = status;
     this.statusText = statusText;
     this.detail = detail;
+    this.url = url;
 
     // Maintains proper stack trace for where our error was thrown
     // Note: Error.captureStackTrace is a V8-only feature (Node.js, Chrome)