From 8ac860a3e3ba34a6e1256c45b3977b7133d07c26 Mon Sep 17 00:00:00 2001
From: Aaron Coburn <aaronc@inrupt.com>
Date: Mon, 19 Aug 2024 15:56:17 -0500
Subject: [PATCH] Add usage examples

---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 76 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 114c06f..da78ea9 100644
--- a/README.md
+++ b/README.md
@@ -57,17 +57,91 @@ forum is a good place to meet the rest of the community.
 ## Bugs and Feature Requests
 
 - For public feedback, bug reports, and feature requests please file an issue
-  via [GitHub](https://github.com/inrupt/solid-client-access-grants-js/issues/).
+  via [GitHub](https://github.com/inrupt/solid-client-errors-js/issues/).
 - For non-public feedback or support inquiries please use the
   [Inrupt Service Desk](https://inrupt.atlassian.net/servicedesk).
 
+## Examples
+
+Integrators of this library will generally use the following pattern to throw
+a subclass of `ClientHttpError`, corresponding to the response status.
+
+```javascript
+
+import { handleErrorResponse } from "@inrupt/solid-client-errors";
+
+const response = await fetch(url, options);
+
+if (response.status !== 200) {
+  const responseBody = await response.text();
+  throw handleErrorResponse(
+    response,
+    responseBody,
+    "application error message"
+  );
+}
+```
+
+The specific error type corresponds to the HTTP status code in the response, each of
+which implements the `WithProblemDetails` type.
+
+* 400: `BadRequestError`
+* 401: `UnauthorizedError`
+* 403: `ForbiddenError`
+* 404: `NotFoundError`
+* 405: `MethodNotAllowedError`
+* 406: `NotAcceptableError`
+* 409: `ConflictError`
+* 410: `GoneError`
+* 412: `PreconditionFailedError`
+* 415: `UnsupportedMediaTypeError`
+* 429: `TooManyRequestsError`
+* 500: `InternalServerError`
+
+Each error includes a `problemDetails` field with the following properties:
+
+* `type: URL`: The specific error type. By default, this is `about:blank`.
+* `title: string`: A short description of the problem.
+* `status: number`: The error response status code.
+* `detail?: string`: A longer description of the problem.
+* `instance?: URL`: A unique URL identifying the problem occurrence.
+
+Consumers of these errors may handle the `ProblemDetails` data in the following way:
+
+```
+
+const res = await getFile(url, options).catch((err) => {
+
+  const problems = err.problemDetails;
+  const header = document.createElement("h2")
+  header.appendChild(document.createTextNode(`${ problems.status } ${ problems.title }`));
+
+  const el = document.getElementById("error");
+  el.appendChild(header);
+
+  if (problems.detail) {
+    const message = document.createElement("p");
+    message.appendChild(document.createTextNode(problems.detail));
+    el.appendChild(message);
+  }
+
+  if (problems.instance) {
+    const instance = document.createElement("p");
+    instance.appendChild(document.createTextNode(problem.instance));
+    el.appendChild(instance);
+  }
+
+});
+
+```
+
 ## Documentation
 
 - [Inrupt Solid Javascript Client Libraries](https://docs.inrupt.com/developer-tools/javascript/client-libraries/)
 - [Homepage](https://docs.inrupt.com/)
-- [Examples](./examples)
 - [Security policy and vulnerability reporting](./SECURITY.md)
 
+
 # Changelog
 
 See [the release notes](https://github.com/inrupt/solid-client-js/blob/main/CHANGELOG.md).