From 46b5f2fd41ef6d2ac23653ca302d6ba7e5559c02 Mon Sep 17 00:00:00 2001
From: Dariusz Porowski <3431813+DariuszPorowski@users.noreply.github.com>
Date: Tue, 20 Jun 2023 16:47:30 -0700
Subject: [PATCH] feat: add RequestError support (#2465)

---
 README.md                   | 32 +++++++++++++++++++++++++++++++-
 package-lock.json           |  1 +
 package.json                |  3 ++-
 src/index.ts                |  2 +-
 src/octokit.ts              |  2 ++
 test/smoke.test.ts          | 14 +++++++++++++-
 test/typescript-validate.ts | 12 +++++++++++-
 7 files changed, 61 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index e54007066e..4a93810e4e 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ The `octokit` package integrates the three main Octokit libraries
 2. **App client** (GitHub App & installations, Webhooks, OAuth)
 3. **Action client** (Pre-authenticated API client for single repository)
 
-## Table of contents
+## Table of contents <!-- omit in toc -->
 
 <!-- toc -->
 
@@ -23,6 +23,7 @@ The `octokit` package integrates the three main Octokit libraries
     - [`octokit.request()`](#octokitrequest)
     - [Pagination](#pagination)
     - [Media Type previews and formats](#media-type-previews-and-formats)
+    - [Request error handling](#request-error-handling)
   - [GraphQL API queries](#graphql-api-queries)
     - [Schema previews](#schema-previews)
 - [App client](#app-client)
@@ -549,6 +550,35 @@ console.log("topics on octocat/hello-world: %j", data.topics);
 
 Learn more about [Media type formats](https://docs.github.com/en/rest/overview/media-types) and [previews](https://docs.github.com/en/enterprise-server@3.2/rest/overview/api-previews) used on GitHub Enterprise Server.
 
+#### Request error handling
+
+**Standalone module:** [`@octokit/request-error`](https://github.com/octokit/request-error.js/#readme)
+
+For request error handling, import `RequestError` and use `try...catch` statement.
+
+```typescript
+import { RequestError } from "octokit";
+```
+
+```typescript
+try {
+  // your code here that sends at least one Octokit request
+  await octokit.request("GET /");
+} catch (error) {
+  // Octokit errors always have a `error.status` property which is the http response code nad it's instance of RequestError
+  if (error instanceof RequestError) {
+    // handle Octokit error
+    // error.message; // Oops
+    // error.status; // 500
+    // error.request; // { method, url, headers, body }
+    // error.response; // { url, status, headers, data }
+  } else {
+    // handle all other errors
+    throw error;
+  }
+}
+```
+
 ### GraphQL API queries
 
 Octokit also supports GitHub's GraphQL API directly -- you can use the same queries shown in the documentation and available in the GraphQL explorer in your calls with `octokit.graphql`.
diff --git a/package-lock.json b/package-lock.json
index e4c5b73d21..b7721d04f5 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,6 +16,7 @@
         "@octokit/plugin-rest-endpoint-methods": "^7.1.1",
         "@octokit/plugin-retry": "^4.1.3",
         "@octokit/plugin-throttling": "^5.2.2",
+        "@octokit/request-error": "^v3.0.3",
         "@octokit/types": "^9.2.2"
       },
       "devDependencies": {
diff --git a/package.json b/package.json
index 8e771d2ce5..be336e41fa 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,8 @@
     "@octokit/plugin-rest-endpoint-methods": "^7.1.1",
     "@octokit/plugin-retry": "^4.1.3",
     "@octokit/plugin-throttling": "^5.2.2",
-    "@octokit/types": "^9.2.2"
+    "@octokit/types": "^9.2.2",
+    "@octokit/request-error": "^v3.0.3"
   },
   "devDependencies": {
     "@octokit/tsconfig": "^2.0.0",
diff --git a/src/index.ts b/src/index.ts
index a5c7e1ed7d..0f6f6e6066 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,2 +1,2 @@
-export { Octokit } from "./octokit";
+export { Octokit, RequestError } from "./octokit";
 export { App, OAuthApp, createNodeMiddleware } from "./app";
diff --git a/src/octokit.ts b/src/octokit.ts
index 39a3acb235..378a11ca61 100644
--- a/src/octokit.ts
+++ b/src/octokit.ts
@@ -6,6 +6,8 @@ import { throttling } from "@octokit/plugin-throttling";
 
 import { VERSION } from "./version";
 
+export { RequestError } from "@octokit/request-error";
+
 export const Octokit = OctokitCore.plugin(
   restEndpointMethods,
   paginateRest,
diff --git a/test/smoke.test.ts b/test/smoke.test.ts
index 2d83369af4..bd5ded4650 100644
--- a/test/smoke.test.ts
+++ b/test/smoke.test.ts
@@ -1,4 +1,4 @@
-import { Octokit, App, OAuthApp } from "../src";
+import { Octokit, App, OAuthApp, RequestError } from "../src";
 
 describe("Smoke tests", () => {
   it("Octokit is a function", () => {
@@ -53,4 +53,16 @@ describe("Smoke tests", () => {
 
     expect(app.octokit.request).toBeInstanceOf(Function);
   });
+
+  it("RequestError inherits from Error", () => {
+    const error = new RequestError("test", 123, {
+      request: {
+        method: "GET",
+        url: "https://api.github.com/",
+        headers: {},
+      },
+    });
+
+    expect(error).toBeInstanceOf(RequestError);
+  });
 });
diff --git a/test/typescript-validate.ts b/test/typescript-validate.ts
index b548bca11d..856cb01ad6 100644
--- a/test/typescript-validate.ts
+++ b/test/typescript-validate.ts
@@ -2,7 +2,7 @@
 // THIS CODE IS NOT EXECUTED. IT IS JUST FOR TYPECHECKING
 // ************************************************************
 
-import { App, OAuthApp, Octokit } from "../src";
+import { App, OAuthApp, Octokit, RequestError } from "../src";
 
 function expect<T>(what: T) {}
 
@@ -30,4 +30,14 @@ export async function OctokitTest() {
     }
   );
   expect<number>(issues[0].id);
+
+  const error = new RequestError("test", 123, {
+    request: {
+      method: "GET",
+      url: "https://api.github.com/",
+      headers: {},
+    },
+  });
+
+  expect<RequestError>(error);
 }