@unofficialbox/box-open-sdk 0.6.1 → 0.7.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.isPreconditionFailed = isPreconditionFailed;
 exports.apiErrorFromResponse = apiErrorFromResponse;
 /**
  * A runtime error: a failed request, auth acquisition, or body decode. The
@@ -31,6 +32,12 @@ class BoxApiError extends Error {
     }
 }
 exports.BoxApiError = BoxApiError;
+/** Whether `err` is Box's 412 Precondition Failed: an `If-Match` write whose
+ * etag no longer matches, because the item changed since it was read. Re-read
+ * the item and retry with its new etag. */
+function isPreconditionFailed(err) {
+    return err instanceof BoxApiError && err.status === 412;
+}
 /** 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

package/dist/cjs/managers/files.js

@@ -65,6 +65,19 @@ class FilesManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getIfModified(fileId, etag, opts) {
+        try {
+            return await this.get(fileId, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async update(fileId, body, opts) {
         let url = this.session.baseUrl("api");
         url += "/files";

package/dist/cjs/managers/folders.js

@@ -74,6 +74,19 @@ class FoldersManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getIfModified(folderId, etag, opts) {
+        try {
+            return await this.get(folderId, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async update(folderId, body, opts) {
         let url = this.session.baseUrl("api");
         url += "/folders";

package/dist/cjs/managers/shared_links_files.js

@@ -59,6 +59,19 @@ class SharedLinksFilesManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `getSharedItems` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getSharedItemsIfModified(boxapi, etag, opts) {
+        try {
+            return await this.getSharedItems(boxapi, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async getFileGetSharedLink(fileId, fields) {
         let url = this.session.baseUrl("api");
         url += "/files";

package/dist/cjs/managers/shared_links_folders.js

@@ -59,6 +59,19 @@ class SharedLinksFoldersManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `getSharedItemsFolders` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getSharedItemsIfModifiedFolders(boxapi, etag, opts) {
+        try {
+            return await this.getSharedItemsFolders(boxapi, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async getFolderGetSharedLink(folderId, fields) {
         let url = this.session.baseUrl("api");
         url += "/folders";

package/dist/cjs/managers/shared_links_web_links.js

@@ -59,6 +59,19 @@ class SharedLinksWebLinksManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `getSharedItemsWebLinks` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getSharedItemsIfModifiedWebLinks(boxapi, etag, opts) {
+        try {
+            return await this.getSharedItemsWebLinks(boxapi, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async getWebLinkGetSharedLink(webLinkId, fields) {
         let url = this.session.baseUrl("api");
         url += "/web_links";

package/dist/cjs/runtime.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Client = exports.Stream = exports.Response = exports.Request = exports.BoxApiError = void 0;
+exports.Client = exports.Stream = exports.Response = exports.Request = exports.isPreconditionFailed = exports.BoxApiError = void 0;
 exports.withHeader = withHeader;
 exports.withQuery = withQuery;
 exports.withJsonBody = withJsonBody;
@@ -29,6 +29,7 @@ exports.statusCode = statusCode;
 const errors_js_1 = require("./errors.js");
 var errors_js_2 = require("./errors.js");
 Object.defineProperty(exports, "BoxApiError", { enumerable: true, get: function () { return errors_js_2.BoxApiError; } });
+Object.defineProperty(exports, "isPreconditionFailed", { enumerable: true, get: function () { return errors_js_2.isPreconditionFailed; } });
 __exportStar(require("./auth.js"), exports);
 /** The default base URLs for the D-106 URL classes. */
 const DEFAULT_BASE_URLS = {

package/dist/esm/errors.js

@@ -26,6 +26,12 @@ export class BoxApiError extends Error {
         this.body = options.body;
     }
 }
+/** Whether `err` is Box's 412 Precondition Failed: an `If-Match` write whose
+ * etag no longer matches, because the item changed since it was read. Re-read
+ * the item and retry with its new etag. */
+export function isPreconditionFailed(err) {
+    return err instanceof BoxApiError && err.status === 412;
+}
 /** 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

package/dist/esm/managers/files.js

@@ -29,6 +29,19 @@ export class FilesManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getIfModified(fileId, etag, opts) {
+        try {
+            return await this.get(fileId, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async update(fileId, body, opts) {
         let url = this.session.baseUrl("api");
         url += "/files";

package/dist/esm/managers/folders.js

@@ -38,6 +38,19 @@ export class FoldersManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getIfModified(folderId, etag, opts) {
+        try {
+            return await this.get(folderId, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async update(folderId, body, opts) {
         let url = this.session.baseUrl("api");
         url += "/folders";

package/dist/esm/managers/shared_links_files.js

@@ -23,6 +23,19 @@ export class SharedLinksFilesManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `getSharedItems` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getSharedItemsIfModified(boxapi, etag, opts) {
+        try {
+            return await this.getSharedItems(boxapi, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async getFileGetSharedLink(fileId, fields) {
         let url = this.session.baseUrl("api");
         url += "/files";

package/dist/esm/managers/shared_links_folders.js

@@ -23,6 +23,19 @@ export class SharedLinksFoldersManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `getSharedItemsFolders` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getSharedItemsIfModifiedFolders(boxapi, etag, opts) {
+        try {
+            return await this.getSharedItemsFolders(boxapi, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async getFolderGetSharedLink(folderId, fields) {
         let url = this.session.baseUrl("api");
         url += "/folders";

package/dist/esm/managers/shared_links_web_links.js

@@ -23,6 +23,19 @@ export class SharedLinksWebLinksManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
+    /** `getSharedItemsWebLinks` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    async getSharedItemsIfModifiedWebLinks(boxapi, etag, opts) {
+        try {
+            return await this.getSharedItemsWebLinks(boxapi, { ...opts, "if-none-match": etag });
+        }
+        catch (err) {
+            if (err instanceof runtime.BoxApiError && err.status === 304) {
+                return undefined;
+            }
+            throw err;
+        }
+    }
     async getWebLinkGetSharedLink(webLinkId, fields) {
         let url = this.session.baseUrl("api");
         url += "/web_links";

package/dist/esm/runtime.js

@@ -1,6 +1,6 @@
 // Code generated by box-gantry (vendored from runtimes/typescript/gantryruntime/src/runtime.ts). DO NOT EDIT.
 import { BoxApiError, apiErrorFromResponse } from './errors.js';
-export { BoxApiError } from './errors.js';
+export { BoxApiError, isPreconditionFailed } from './errors.js';
 export * from './auth.js';
 /** The default base URLs for the D-106 URL classes. */
 const DEFAULT_BASE_URLS = {

package/dist/types/errors.d.ts

@@ -33,6 +33,10 @@ export declare class BoxApiError extends Error {
     readonly body?: Uint8Array;
     constructor(message: string, options?: BoxApiErrorOptions);
 }
+/** Whether `err` is Box's 412 Precondition Failed: an `If-Match` write whose
+ * etag no longer matches, because the item changed since it was read. Re-read
+ * the item and retry with its new etag. */
+export declare function isPreconditionFailed(err: unknown): err is 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

package/dist/types/managers/files.d.ts

@@ -32,6 +32,9 @@ export declare class FilesManager {
     private readonly session;
     constructor(session: runtime.Client);
     get(fileId: string, opts?: FilesManagerGetOptions): Promise<models.schemas.FileFull>;
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    getIfModified(fileId: string, etag: string, opts?: FilesManagerGetOptions): Promise<models.schemas.FileFull | undefined>;
     update(fileId: string, body: models.schemas.UpdateFileRequest, opts?: FilesManagerUpdateOptions): Promise<models.schemas.FileFull>;
     delete_(fileId: string, opts?: FilesManagerDeleteOptions): Promise<void>;
     copy(fileId: string, body: models.schemas.CopyFileRequest, opts?: FilesManagerCopyOptions): Promise<models.schemas.FileFull>;

package/dist/types/managers/folders.d.ts

@@ -44,6 +44,9 @@ export declare class FoldersManager {
     private readonly session;
     constructor(session: runtime.Client);
     get(folderId: string, opts?: FoldersManagerGetOptions): Promise<models.schemas.FolderFull>;
+    /** `get` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    getIfModified(folderId: string, etag: string, opts?: FoldersManagerGetOptions): Promise<models.schemas.FolderFull | undefined>;
     update(folderId: string, body: models.schemas.UpdateFolderRequest, opts?: FoldersManagerUpdateOptions): Promise<models.schemas.FolderFull>;
     delete_(folderId: string, opts?: FoldersManagerDeleteOptions): Promise<void>;
     /** Iterate every `models.schemas.Item` across pages, threading the marker cursor. */

package/dist/types/managers/shared_links_files.d.ts

@@ -10,6 +10,9 @@ export declare class SharedLinksFilesManager {
     private readonly session;
     constructor(session: runtime.Client);
     getSharedItems(boxapi: string, opts?: SharedLinksFilesManagerGetSharedItemsOptions): Promise<models.schemas.FileFull>;
+    /** `getSharedItems` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    getSharedItemsIfModified(boxapi: string, etag: string, opts?: SharedLinksFilesManagerGetSharedItemsOptions): Promise<models.schemas.FileFull | undefined>;
     getFileGetSharedLink(fileId: string, fields: string): Promise<models.schemas.FileFull>;
     updateFileAddSharedLink(fileId: string, fields: string, body: models.schemas.UpdateFileAddSharedLinkRequest): Promise<models.schemas.FileFull>;
     updateFileUpdateSharedLink(fileId: string, fields: string, body: models.schemas.UpdateFileAddSharedLinkRequest): Promise<models.schemas.FileFull>;

package/dist/types/managers/shared_links_folders.d.ts

@@ -10,6 +10,9 @@ export declare class SharedLinksFoldersManager {
     private readonly session;
     constructor(session: runtime.Client);
     getSharedItemsFolders(boxapi: string, opts?: SharedLinksFoldersManagerGetSharedItemsFoldersOptions): Promise<models.schemas.FolderFull>;
+    /** `getSharedItemsFolders` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    getSharedItemsIfModifiedFolders(boxapi: string, etag: string, opts?: SharedLinksFoldersManagerGetSharedItemsFoldersOptions): Promise<models.schemas.FolderFull | undefined>;
     getFolderGetSharedLink(folderId: string, fields: string): Promise<models.schemas.FolderFull>;
     updateFolderAddSharedLink(folderId: string, fields: string, body: models.schemas.UpdateFileAddSharedLinkRequest): Promise<models.schemas.FolderFull>;
     updateFolderUpdateSharedLink(folderId: string, fields: string, body: models.schemas.UpdateFolderUpdateSharedLinkRequest): Promise<models.schemas.FolderFull>;

package/dist/types/managers/shared_links_web_links.d.ts

@@ -10,6 +10,9 @@ export declare class SharedLinksWebLinksManager {
     private readonly session;
     constructor(session: runtime.Client);
     getSharedItemsWebLinks(boxapi: string, opts?: SharedLinksWebLinksManagerGetSharedItemsWebLinksOptions): Promise<models.schemas.WebLink>;
+    /** `getSharedItemsWebLinks` with `If-None-Match` set to `etag`: resolves `undefined` when
+     * the item is unchanged since `etag` (Box answers 304 Not Modified). */
+    getSharedItemsIfModifiedWebLinks(boxapi: string, etag: string, opts?: SharedLinksWebLinksManagerGetSharedItemsWebLinksOptions): Promise<models.schemas.WebLink | undefined>;
     getWebLinkGetSharedLink(webLinkId: string, fields: string): Promise<models.schemas.WebLink>;
     updateWebLinkAddSharedLink(webLinkId: string, fields: string, body: models.schemas.UpdateFileAddSharedLinkRequest): Promise<models.schemas.WebLink>;
     updateWebLinkUpdateSharedLink(webLinkId: string, fields: string, body: models.schemas.UpdateFileAddSharedLinkRequest): Promise<models.schemas.WebLink>;

package/dist/types/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { Auth } from './auth.js';
-export { BoxApiError } from './errors.js';
+export { BoxApiError, isPreconditionFailed } from './errors.js';
 export * from './auth.js';
 /** The runtime-owned HTTP request envelope, assembled by the `with*` builders
  * before `fetch` executes it. */

package/docs/errors.md

@@ -26,28 +26,32 @@ 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.
+- **Reads** — a file or folder `get`, and each shared-item lookup, has an
+  `…IfModified` variant that takes the stored etag, sends it as
+  `If-None-Match`, and returns `undefined` when Box answers `304 Not Modified`:
+  keep your cached copy. (The plain method surfaces that 304 as the error
+  above if you set `if-none-match` on it yourself.)
+- **Writes** — pass the etag 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, and `runtime.isPreconditionFailed(err)` reports 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
-  }
+const file = await client.files.getIfModified(fileId, etag);
+if (file === undefined) {
+  // 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
+
+// Re-read and retry: the update lands only on the version it was made from.
+for (let attempt = 1; ; attempt++) {
+  try {
+    await client.files.update(fileId, body, { 'if-match': etag });
+    break;
+  } catch (err) {
+    if (!runtime.isPreconditionFailed(err) || attempt === 3) throw err;
+    const current = await client.files.get(fileId);
+    etag = current.etag ?? undefined; // reapply your change to current here
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-sdk",
-  "version": "0.6.1",
+  "version": "0.7.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",