@unofficialbox/box-open-sdk 0.6.0 → 0.7.0

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/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/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/docs/errors.md

@@ -12,10 +12,40 @@ and the raw `body`; transport and decode failures carry the underlying
 ```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, err.code, err.boxMessage, err.requestId, err.body, 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** — 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: read it again, reapply your change, retry. `If-Match` can't block a move.
+
+```ts
+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
+  }
 }
 ```

package/package.json

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