リクエストエラーからステータスコード・URL・原因を参照できるようにする

README.md

@@ -711,6 +711,41 @@ type UploadMediaRequest =
 function uploadMedia(params: UploadMediaRequest): Promise<{ url: string }>;
 ```
 
+## エラーハンドリング
+
+microCMS APIへのリクエストに失敗した場合は、`isMicroCMSRequestError`を使用して、HTTPステータスコード、リクエスト先URL、元のネットワークエラーを参照できます。
+
+```typescript
+import { createClient, isMicroCMSRequestError } from 'microcms-js-sdk';
+
+const client = createClient({
+  serviceDomain: 'serviceDomain',
+  apiKey: 'apiKey',
+});
+
+try {
+  await client.getList({ endpoint: 'blog' });
+} catch (error) {
+  if (isMicroCMSRequestError(error)) {
+    console.log(error.status);
+    console.log(error.url);
+    console.log(error.originalError);
+  }
+}
+```
+
+| プロパティ      | HTTPエラー                    | ネットワークエラー          |
+| --------------- | ----------------------------- | --------------------------- |
+| `status`        | HTTPステータスコード          | `undefined`                 |
+| `url`           | リクエスト先URL               | リクエスト先URL             |
+| `originalError` | `undefined`                   | `fetch`が投げた元の値       |
+
+`url`に`draftKey`が含まれる場合、その値は`***`にマスクされます。リクエストヘッダー、リクエストボディ、`Response`オブジェクトはエラーへ追加されません。
+
+`originalError`の内容はNode.js、ブラウザ、Edge Runtimeなどの実行環境によって異なり、SDKとして形式を保証しません。
+
+追加されるプロパティは非列挙です。そのため、既存の`message`、`toString()`、`Object.keys()`、`JSON.stringify()`の結果には影響しません。
+
 ## ヒント
 
 ### 読み取り用と書き込み用で別々のAPIキーを使用する

README_en.md

@@ -711,6 +711,41 @@ type UploadMediaRequest =
 function uploadMedia(params: UploadMediaRequest): Promise<{ url: string }>;
 ```
 
+## Error handling
+
+When a request to the microCMS API fails, use `isMicroCMSRequestError` to access the HTTP status code, request URL, and original network error.
+
+```typescript
+import { createClient, isMicroCMSRequestError } from 'microcms-js-sdk';
+
+const client = createClient({
+  serviceDomain: 'serviceDomain',
+  apiKey: 'apiKey',
+});
+
+try {
+  await client.getList({ endpoint: 'blog' });
+} catch (error) {
+  if (isMicroCMSRequestError(error)) {
+    console.log(error.status);
+    console.log(error.url);
+    console.log(error.originalError);
+  }
+}
+```
+
+| Property        | HTTP error       | Network error                  |
+| --------------- | ---------------- | ------------------------------ |
+| `status`        | HTTP status code | `undefined`                    |
+| `url`           | Request URL      | Request URL                    |
+| `originalError` | `undefined`      | Original value thrown by `fetch` |
+
+If `url` contains a `draftKey`, its value is masked as `***`. Request headers, request bodies, and the `Response` object are not added to the error.
+
+The contents of `originalError` depend on the runtime environment, such as Node.js, browsers, or Edge Runtime, and are not guaranteed by this SDK.
+
+The additional properties are non-enumerable, so they do not affect the existing `message`, `toString()`, `Object.keys()`, or `JSON.stringify()` results.
+
 ## Tips
 
 ### Separate API keys for read and write

src/createClient.ts

@@ -3,6 +3,7 @@
  * https://github.com/microcmsio/microcms-js-sdk
  */
 import retry from 'async-retry';
+import { createMicroCMSRequestError } from './lib/error';
 import { generateFetchClient } from './lib/fetch';
 import {
   CreateRequest,
@@ -96,10 +97,13 @@ export const createClient = ({
             const message = await getMessageFromResponse(response);
 
             return bail(
-              new Error(
-                `fetch API response status: ${response.status}${
-                  message ? `\n  message is \`${message}\`` : ''
-                }`,
+              createMicroCMSRequestError(
+                new Error(
+                  `fetch API response status: ${response.status}${
+                    message ? `\n  message is \`${message}\`` : ''
+                  }`,
+                ),
+                { status: response.status, url },
               ),
             );
           }
@@ -109,10 +113,13 @@ export const createClient = ({
             const message = await getMessageFromResponse(response);
 
             return Promise.reject(
-              new Error(
-                `fetch API response status: ${response.status}${
-                  message ? `\n  message is \`${message}\`` : ''
-                }`,
+              createMicroCMSRequestError(
+                new Error(
+                  `fetch API response status: ${response.status}${
+                    message ? `\n  message is \`${message}\`` : ''
+                  }`,
+                ),
+                { status: response.status, url },
               ),
             );
           }
@@ -130,7 +137,10 @@ export const createClient = ({
           }
 
           return Promise.reject(
-            new Error(`Network Error.\n  Details: ${error.message ?? ''}`),
+            createMicroCMSRequestError(
+              new Error(`Network Error.\n  Details: ${error.message ?? ''}`),
+              { url, originalError: error },
+            ),
           );
         }
       },

src/createManagementClient.ts

@@ -1,3 +1,4 @@
+import { createMicroCMSRequestError } from './lib/error';
 import { generateFetchClient } from './lib/fetch';
 import { MicroCMSManagementClient, UploadMediaRequest } from './types';
 import {
@@ -72,7 +73,10 @@ export const createManagementClient = ({
       }
 
       return Promise.reject(
-        new Error(`Network Error.\n  Details: ${error.message ?? ''}`),
+        createMicroCMSRequestError(
+          new Error(`Network Error.\n  Details: ${error.message ?? ''}`),
+          { url, originalError: error },
+        ),
       );
     }
 
@@ -81,10 +85,13 @@ export const createManagementClient = ({
       const message = await getMessageFromResponse(response);
 
       return Promise.reject(
-        new Error(
-          `fetch API response status: ${response.status}${
-            message ? `\n  message is \`${message}\`` : ''
-          }`,
+        createMicroCMSRequestError(
+          new Error(
+            `fetch API response status: ${response.status}${
+              message ? `\n  message is \`${message}\`` : ''
+            }`,
+          ),
+          { status: response.status, url },
         ),
       );
     }

src/index.ts

@@ -1,3 +1,4 @@
 export { createClient } from './createClient';
 export { createManagementClient } from './createManagementClient';
+export { isMicroCMSRequestError } from './lib/error';
 export * from './types';

src/lib/error.ts

@@ -0,0 +1,59 @@
+import { MicroCMSRequestError } from '../types';
+
+interface CreateMicroCMSRequestErrorOptions {
+  status?: number;
+  url: string;
+  originalError?: unknown;
+}
+
+const maskDraftKey = (url: string): string => {
+  return url.replace(/([?&]draftKey=)[^&#]*/g, '$1***');
+};
+
+export const createMicroCMSRequestError = (
+  error: Error,
+  { status, url, originalError }: CreateMicroCMSRequestErrorOptions,
+): MicroCMSRequestError => {
+  // Errorとしての実行時の同一性と既存のログ出力を維持するため、独自クラスは生成せず、
+  // 既存のErrorに追加情報を付与する。独自のErrorクラスは将来のメジャーリリースで再検討できる。
+  // 設計背景: https://github.com/microcmsio/microcms-js-sdk/pull/109
+  const microCMSRequestError = error as MicroCMSRequestError;
+
+  Object.defineProperties(microCMSRequestError, {
+    status: {
+      value: status,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    },
+    url: {
+      value: maskDraftKey(url),
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    },
+    originalError: {
+      value: originalError,
+      enumerable: false,
+      configurable: true,
+      writable: true,
+    },
+  });
+
+  return microCMSRequestError;
+};
+
+export const isMicroCMSRequestError = (
+  error: unknown,
+): error is MicroCMSRequestError => {
+  if (!(error instanceof Error)) return false;
+
+  return (
+    Object.prototype.hasOwnProperty.call(error, 'status') &&
+    (typeof (error as MicroCMSRequestError).status === 'number' ||
+      typeof (error as MicroCMSRequestError).status === 'undefined') &&
+    Object.prototype.hasOwnProperty.call(error, 'url') &&
+    typeof (error as MicroCMSRequestError).url === 'string' &&
+    Object.prototype.hasOwnProperty.call(error, 'originalError')
+  );
+};

src/types.ts

@@ -1,5 +1,14 @@
 export type Fetch = typeof fetch;
 
+/**
+ * Error returned when a microCMS API request fails.
+ */
+export type MicroCMSRequestError = Error & {
+  status: number | undefined;
+  url: string;
+  originalError: unknown | undefined;
+};
+
 /**
  * microCMS createClient params
  */

tests/createClient.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { createClient } from '../src/createClient';
+import { createClient, isMicroCMSRequestError } from '../src';
 import { testBaseUrl } from './mocks/handlers';
 import { server } from './mocks/server';
 
@@ -81,6 +81,30 @@ describe('createClient', () => {
         new Error('fetch API response status: 404'),
       );
     });
+
+    test('Returns structured error details and masks draftKey', async () => {
+      server.use(
+        http.get(`${testBaseUrl}/list-type`, async () => {
+          return new HttpResponse(null, { status: 404 });
+        }),
+      );
+      const client = createClient({
+        serviceDomain: 'serviceDomain',
+        apiKey: 'apiKey',
+      });
+
+      const error = await client
+        .get({
+          endpoint: 'list-type',
+          queries: { draftKey: 'secret', fields: 'id' },
+        })
+        .catch((error) => error);
+
+      expect(isMicroCMSRequestError(error)).toBe(true);
+      expect(error.status).toBe(404);
+      expect(error.url).toBe(`${testBaseUrl}/list-type?draftKey=***&fields=id`);
+      expect(error.originalError).toBeUndefined();
+    });
   });
 
   test('Throws an error in the event of a network error.', () => {
@@ -99,6 +123,53 @@ describe('createClient', () => {
     );
   });
 
+  test('Keeps the original error in the event of a network error', async () => {
+    const originalError = new TypeError('fetch failed') as TypeError & {
+      cause: unknown;
+    };
+    originalError.cause = { code: 'ENOTFOUND' };
+    const fetchMock = jest
+      .spyOn(global, 'fetch')
+      .mockRejectedValueOnce(originalError);
+    const client = createClient({
+      serviceDomain: 'serviceDomain',
+      apiKey: 'apiKey',
+    });
+
+    const error = await client
+      .get({ endpoint: 'list-type' })
+      .catch((error) => error);
+
+    fetchMock.mockRestore();
+
+    expect(isMicroCMSRequestError(error)).toBe(true);
+    expect(error.status).toBeUndefined();
+    expect(error.url).toBe(`${testBaseUrl}/list-type`);
+    expect(error.originalError).toBe(originalError);
+  });
+
+  test('Does not convert a response body parsing error', async () => {
+    server.use(
+      http.get(`${testBaseUrl}/list-type`, async () => {
+        return new HttpResponse('invalid json', {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }),
+    );
+    const client = createClient({
+      serviceDomain: 'serviceDomain',
+      apiKey: 'apiKey',
+    });
+
+    const error = await client
+      .get({ endpoint: 'list-type' })
+      .catch((error) => error);
+
+    expect(error.name).toBe('SyntaxError');
+    expect(isMicroCMSRequestError(error)).toBe(false);
+  });
+
   describe('Retry option is true', () => {
     const retryableClient = createClient({
       serviceDomain: 'serviceDomain',
@@ -118,9 +189,16 @@ describe('createClient', () => {
         }),
       );
 
-      await expect(retryableClient.get({ endpoint: '500' })).rejects.toThrow(
-        new Error('fetch API response status: 500'),
-      );
+      const error = await retryableClient
+        .get({ endpoint: '500' })
+        .catch((error) => error);
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.message).toBe('fetch API response status: 500');
+      expect(isMicroCMSRequestError(error)).toBe(true);
+      expect(error.status).toBe(500);
+      expect(error.url).toBe(`${testBaseUrl}/500`);
+      expect(error.originalError).toBeUndefined();
       expect(apiCallCount).toBe(3);
     }, 30000);