(chore) Add FetchError interface for more granular error annotation (#…

…1230)

This PR adds a `FetchError` interface to the framework that can be used to annotate errors that occur during fetch requests. It also amends the `OpenmrsFetchError` class to implement the `FetchError` interface.

Presently, the openmrsFetch hook throws a custom `OpenmrsFetchError` class that includes the response status code and status text if a request fails. This is not always the most helpful message, and it's not always clear what the underlying error was.

The REST API returns a more useful message in the responseBody, and it would be preferable to show this message instead of the status code and status text. With this change, we can then use the FetchError interface further down the line in SWR hooks to annotate errors.

packages/framework/esm-api/src/openmrs-fetch.ts

@@ -300,7 +300,7 @@ export function openmrsObservableFetch<T>(url: string, fetchInit: FetchConfig =
   });
 }
 
-export class OpenmrsFetchError extends Error {
+export class OpenmrsFetchError extends Error implements FetchError {
   constructor(url: string, response: Response, responseBody: ResponseBody | null, requestStacktrace: Error) {
     super();
     this.message = `Server responded with ${response.status} (${response.statusText}) for url ${url}. Check err.responseBody or network tab in dev tools for more info`;
@@ -331,3 +331,8 @@ interface FetchBody {
 export interface FetchResponseJson {
   [key: string]: any;
 }
+
+export interface FetchError {
+  response: Response;
+  responseBody: ResponseBody | null;
+}

packages/framework/esm-framework/docs/classes/OpenmrsFetchError.md

@@ -8,6 +8,10 @@
 
   ↳ **`OpenmrsFetchError`**
 
+## Implements
+
+- [`FetchError`](../interfaces/FetchError.md)
+
 ## Table of contents
 
 ### API Constructors
@@ -61,6 +65,10 @@ Error.constructor
 
 • **response**: `Response`
 
+#### Implementation of
+
+[FetchError](../interfaces/FetchError.md).[response](../interfaces/FetchError.md#response)
+
 #### Defined in
 
 [packages/framework/esm-api/src/openmrs-fetch.ts:312](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L312)
@@ -71,6 +79,10 @@ ___
 
 • **responseBody**: ``null`` \| `string` \| [`FetchResponseJson`](../interfaces/FetchResponseJson.md)
 
+#### Implementation of
+
+[FetchError](../interfaces/FetchError.md).[responseBody](../interfaces/FetchError.md#responsebody)
+
 #### Defined in
 
 [packages/framework/esm-api/src/openmrs-fetch.ts:313](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L313)

packages/framework/esm-framework/docs/interfaces/FetchError.md

@@ -0,0 +1,34 @@
+[@openmrs/esm-framework](../API.md) / FetchError
+
+# Interface: FetchError
+
+## Implemented by
+
+- [`OpenmrsFetchError`](../classes/OpenmrsFetchError.md)
+
+## Table of contents
+
+### API Properties
+
+- [response](FetchError.md#response)
+- [responseBody](FetchError.md#responsebody)
+
+## API Properties
+
+### response
+
+• **response**: `Response`
+
+#### Defined in
+
+[packages/framework/esm-api/src/openmrs-fetch.ts:328](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L328)
+
+___
+
+### responseBody
+
+• **responseBody**: ``null`` \| `ResponseBody`
+
+#### Defined in
+
+[packages/framework/esm-api/src/openmrs-fetch.ts:329](https://github.com/openmrs/openmrs-esm-core/blob/main/packages/framework/esm-api/src/openmrs-fetch.ts#L329)