@unofficialbox/box-open-sdk 0.5.0 → 0.6.1

package/dist/cjs/errors.js

@@ -2,6 +2,7 @@
 // Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/errors.ts). DO NOT EDIT.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BoxApiError = void 0;
+exports.apiErrorFromResponse = apiErrorFromResponse;
 /**
  * A runtime error: a failed request, auth acquisition, or body decode. The
  * generated SDK's exceptions model (TR-TS.3) surfaces every failure as a thrown
@@ -11,10 +12,56 @@ exports.BoxApiError = void 0;
 class BoxApiError extends Error {
     /** The HTTP status, when the error carries a response. */
     status;
+    /** Box's error `code` (e.g. `not_found`), when the body was a Box error. */
+    code;
+    /** Box's error `message`, when the body was a Box error. */
+    boxMessage;
+    /** Box's `request_id`, when the body was a Box error. */
+    requestId;
+    /** The raw response body of a non-2xx response. */
+    body;
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = 'BoxApiError';
         this.status = options.status;
+        this.code = options.code;
+        this.boxMessage = options.boxMessage;
+        this.requestId = options.requestId;
+        this.body = options.body;
     }
 }
 exports.BoxApiError = BoxApiError;
+/** The error for a non-2xx response: `Client.fetch` throws it once the retry
+ * budget and the single 401 refresh are spent, so a caller never mistakes an
+ * error body for a result. Box's error fields are read from the body when it
+ * is a Box error object; the raw body is kept either way. */
+function apiErrorFromResponse(status, body) {
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch {
+        payload = undefined;
+    }
+    const field = (key) => {
+        if (typeof payload !== 'object' || payload === null) {
+            return undefined;
+        }
+        const value = payload[key];
+        return typeof value === 'string' ? value : undefined;
+    };
+    const code = field('code');
+    const boxMessage = field('message');
+    const requestId = field('request_id');
+    let message = `box: status ${status}`;
+    if (code !== undefined) {
+        message += ` ${code}`;
+    }
+    if (boxMessage !== undefined) {
+        message += `: ${boxMessage}`;
+    }
+    if (requestId !== undefined) {
+        message += ` (request_id ${requestId})`;
+    }
+    return new BoxApiError(message, { status, code, boxMessage, requestId, body });
+}

package/dist/cjs/runtime.js

@@ -168,6 +168,9 @@ class Client {
                 await sleep(retryDelay(response, attempt), signal);
                 continue;
             }
+            if (response.status < 200 || response.status >= 300) {
+                throw (0, errors_js_1.apiErrorFromResponse)(response.status, bodyBytes);
+            }
             return response;
         }
         throw new errors_js_1.BoxApiError(`request failed after ${this.maxRetries + 1} attempts`, {

package/dist/esm/errors.js

@@ -8,9 +8,55 @@
 export class BoxApiError extends Error {
     /** The HTTP status, when the error carries a response. */
     status;
+    /** Box's error `code` (e.g. `not_found`), when the body was a Box error. */
+    code;
+    /** Box's error `message`, when the body was a Box error. */
+    boxMessage;
+    /** Box's `request_id`, when the body was a Box error. */
+    requestId;
+    /** The raw response body of a non-2xx response. */
+    body;
     constructor(message, options = {}) {
         super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
         this.name = 'BoxApiError';
         this.status = options.status;
+        this.code = options.code;
+        this.boxMessage = options.boxMessage;
+        this.requestId = options.requestId;
+        this.body = options.body;
     }
 }
+/** The error for a non-2xx response: `Client.fetch` throws it once the retry
+ * budget and the single 401 refresh are spent, so a caller never mistakes an
+ * error body for a result. Box's error fields are read from the body when it
+ * is a Box error object; the raw body is kept either way. */
+export function apiErrorFromResponse(status, body) {
+    let payload;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch {
+        payload = undefined;
+    }
+    const field = (key) => {
+        if (typeof payload !== 'object' || payload === null) {
+            return undefined;
+        }
+        const value = payload[key];
+        return typeof value === 'string' ? value : undefined;
+    };
+    const code = field('code');
+    const boxMessage = field('message');
+    const requestId = field('request_id');
+    let message = `box: status ${status}`;
+    if (code !== undefined) {
+        message += ` ${code}`;
+    }
+    if (boxMessage !== undefined) {
+        message += `: ${boxMessage}`;
+    }
+    if (requestId !== undefined) {
+        message += ` (request_id ${requestId})`;
+    }
+    return new BoxApiError(message, { status, code, boxMessage, requestId, body });
+}

package/dist/esm/runtime.js

@@ -1,5 +1,5 @@
 // Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/runtime.ts). DO NOT EDIT.
-import { BoxApiError } from './errors.js';
+import { BoxApiError, apiErrorFromResponse } from './errors.js';
 export { BoxApiError } from './errors.js';
 export * from './auth.js';
 /** The default base URLs for the D-106 URL classes. */
@@ -137,6 +137,9 @@ export class Client {
                 await sleep(retryDelay(response, attempt), signal);
                 continue;
             }
+            if (response.status < 200 || response.status >= 300) {
+                throw apiErrorFromResponse(response.status, bodyBytes);
+            }
             return response;
         }
         throw new BoxApiError(`request failed after ${this.maxRetries + 1} attempts`, {

package/dist/types/errors.d.ts

@@ -2,6 +2,14 @@
 export interface BoxApiErrorOptions {
     /** The HTTP status, when the error carries a response. */
     status?: number;
+    /** Box's error `code` (e.g. `not_found`), from a Box error body. */
+    code?: string;
+    /** Box's error `message`, from a Box error body. */
+    boxMessage?: string;
+    /** Box's `request_id`, from a Box error body — quote it to Box support. */
+    requestId?: string;
+    /** The raw response body of a non-2xx response. */
+    body?: Uint8Array;
     /** The underlying failure (a transport error, a decode error), preserved for
      * diagnostics. */
     cause?: unknown;
@@ -15,5 +23,18 @@ export interface BoxApiErrorOptions {
 export declare class BoxApiError extends Error {
     /** The HTTP status, when the error carries a response. */
     readonly status?: number;
+    /** Box's error `code` (e.g. `not_found`), when the body was a Box error. */
+    readonly code?: string;
+    /** Box's error `message`, when the body was a Box error. */
+    readonly boxMessage?: string;
+    /** Box's `request_id`, when the body was a Box error. */
+    readonly requestId?: string;
+    /** The raw response body of a non-2xx response. */
+    readonly body?: Uint8Array;
     constructor(message: string, options?: BoxApiErrorOptions);
 }
+/** The error for a non-2xx response: `Client.fetch` throws it once the retry
+ * budget and the single 401 refresh are spent, so a caller never mistakes an
+ * error body for a result. Box's error fields are read from the body when it
+ * is a Box error object; the raw body is kept either way. */
+export declare function apiErrorFromResponse(status: number, body: Uint8Array): BoxApiError;

package/docs/errors.md

@@ -4,17 +4,50 @@
 Methods are `async` and surface failure by throwing — the return type only
 describes the success value. A thrown `BoxApiError` is either a transport
 failure or a non-2xx response after the network layer's retries (exponential
-backoff + jitter, `401` refresh, `Retry-After`). It carries the HTTP `status`
-when the failure came with a response, and the underlying `cause` for
-transport or decode failures:
+backoff + jitter, `401` refresh, `Retry-After`). For a non-2xx response it
+carries the HTTP `status`, Box's error `code`, `boxMessage`, and `requestId`,
+and the raw `body`; transport and decode failures carry the underlying
+`cause` instead:
 
 ```ts
 import { runtime } from '@unofficialbox/box-open-sdk';
 try {
-await client.files.getFileById(fileId);
+  await client.files.get(fileId);
 } catch (err) {
-if (err instanceof runtime.BoxApiError) {
-// err.status (number | undefined), err.cause
+  if (err instanceof runtime.BoxApiError) {
+    // err.status, err.code, err.boxMessage, err.requestId, err.body, err.cause
+  }
 }
+```
+
+## Etags: `If-None-Match` and `If-Match`
+
+Files and folders carry an `etag`. Send it back to stay in sync with Box
+(Box's [Ensure consistency](https://developer.box.com/guides/api-calls/ensure-consistency/)
+guide):
+
+- **Reads** — pass the stored etag as `if-none-match` on a file or folder
+  `get` (or a shared-item lookup). Box answers `304 Not Modified` when
+  nothing changed, and the SDK raises it as the error above with status
+  `304`: keep your cached copy.
+- **Writes** — pass it as `if-match` on a file or folder update or delete,
+  or a new file version upload. Box answers `412 Precondition Failed`
+  (code `precondition_failed`) when the item changed since you read it:
+  read it again, reapply your change, retry. `If-Match` can't block a move.
+
+```ts
+try {
+  await client.files.get(fileId, { 'if-none-match': etag });
+} catch (err) {
+  if (err instanceof runtime.BoxApiError && err.status === 304) {
+    // unchanged since etag
+  }
+}
+try {
+  await client.files.update(fileId, body, { 'if-match': etag });
+} catch (err) {
+  if (err instanceof runtime.BoxApiError && err.status === 412) {
+    // changed since etag: re-read and retry
+  }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Box API client for TypeScript (open source, community, punk rock) — typed models, async managers, and a fetch runtime with retry, backoff, and token refresh.",
   "keywords": ["box", "box-api", "sdk", "api-client", "typescript", "unofficial"],
   "license": "MIT",