@unofficialbox/box-open-sdk 0.2.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle @ Unofficial Box
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@
 
 [![npm](https://img.shields.io/npm/v/@unofficialbox/box-open-sdk.svg)](https://www.npmjs.com/package/@unofficialbox/box-open-sdk)
 
-A **community, unofficial** Box API client for TypeScript — fully typed models
+An **open source, community-built** Box API client for TypeScript — fully typed models
 for the whole Box surface, one manager per API area behind a single `Client`,
 and a `fetch`-based runtime with retry, backoff, and token refresh. Ships as a
 **dual ESM/CJS** package with bundled `.d.ts` declarations; no runtime

package/dist/cjs/chunked_upload.js

@@ -0,0 +1,108 @@
+"use strict";
+// Code generated by box-gantry. DO NOT EDIT.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChunkedUpload = void 0;
+/**
+ * ChunkedUpload orchestrates a Box chunked (multipart) upload over a Client: it
+ * creates an upload session, uploads the content's parts with bounded
+ * concurrency, and commits — for a new file (upload) or a new version of an
+ * existing file (uploadVersion). Box requires chunked upload for files at or
+ * above its minimum session size; smaller files use the single-shot endpoints.
+ */
+class ChunkedUpload {
+    client;
+    /** Bounds parts in flight, capping peak memory. */
+    maxConcurrent = 4;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Upload content as a new file named fileName into folderId. */
+    async upload(content, fileName, folderId) {
+        const session = await this.client.chunkedUploads.createFileUploadSession({
+            folder_id: folderId,
+            file_size: content.length,
+            file_name: fileName,
+        });
+        return this.finish(session, content);
+    }
+    /** Upload content as a new version of the existing file fileId. */
+    async uploadVersion(content, fileName, fileId) {
+        const session = await this.client.chunkedUploads.createFileVersionUploadSession(fileId, {
+            file_size: content.length,
+            file_name: fileName,
+        });
+        return this.finish(session, content);
+    }
+    async finish(session, content) {
+        if (session.id === undefined) {
+            throw new Error('gantry: upload session returned no id');
+        }
+        if (session.part_size === undefined || session.part_size <= 0) {
+            throw new Error('gantry: upload session returned a non-positive part_size');
+        }
+        const id = session.id;
+        const partSize = session.part_size;
+        const total = content.length;
+        const offsets = [];
+        for (let off = 0; off < total; off += partSize) {
+            offsets.push(off);
+        }
+        const parts = new Array(offsets.length);
+        // A bounded worker pool: each of maxConcurrent workers claims the next
+        // offset (the `next++` read is atomic between awaits on a single thread).
+        // Once any part fails, `failed` stops the others from starting new parts,
+        // so a failure early in a large upload doesn't push every remaining part.
+        let next = 0;
+        let failed = false;
+        const worker = async () => {
+            for (;;) {
+                if (failed) {
+                    return;
+                }
+                const i = next++;
+                if (i >= offsets.length) {
+                    return;
+                }
+                const start = offsets[i];
+                const end = Math.min(start + partSize, total);
+                try {
+                    parts[i] = await this.uploadPart(id, content, start, end, total);
+                }
+                catch (err) {
+                    failed = true;
+                    throw err;
+                }
+            }
+        };
+        const workerCount = Math.min(this.maxConcurrent, offsets.length);
+        await Promise.all(Array.from({ length: workerCount }, () => worker()));
+        const digest = 'sha=' + (await sha1Base64(content));
+        return this.client.chunkedUploads.commitFileUploadSession(id, digest, { parts });
+    }
+    async uploadPart(id, content, start, end, total) {
+        const slice = content.subarray(start, end);
+        const digest = 'sha=' + (await sha1Base64(slice));
+        const contentRange = `bytes ${start}-${end - 1}/${total}`;
+        // The `as BlobPart` cast bridges the `Uint8Array<ArrayBufferLike>` vs
+        // `BufferSource` (ArrayBuffer-only) generic gap in the DOM lib, exactly as
+        // the runtime casts its `fetch` body; a plain `Uint8Array` is a valid part.
+        const uploaded = await this.client.chunkedUploads.updateFileUploadSession(id, digest, contentRange, new Blob([slice]));
+        if (uploaded.part === undefined) {
+            throw new Error('gantry: upload part returned no part');
+        }
+        return uploaded.part;
+    }
+}
+exports.ChunkedUpload = ChunkedUpload;
+/** Base64 of the SHA-1 of data — the Box `Digest: sha=…` header value. Uses Web
+ *  Crypto (browser and Node 18+), so it adds no dependency. */
+async function sha1Base64(data) {
+    // `as BufferSource` bridges the `Uint8Array<ArrayBufferLike>` vs ArrayBuffer-only
+    // generic gap in the DOM lib (as the runtime does for its `fetch` body).
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-1', data));
+    let binary = '';
+    for (const byte of digest) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}

package/dist/cjs/index.js

@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildinfo = exports.auth = exports.runtime = exports.managers = exports.models = exports.Client = void 0;
+exports.ChunkedUpload = exports.buildinfo = exports.auth = exports.runtime = exports.managers = exports.models = exports.Client = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_js_1.Client; } });
 exports.models = __importStar(require("./models/index.js"));
@@ -42,3 +42,5 @@ exports.managers = __importStar(require("./managers/index.js"));
 exports.runtime = __importStar(require("./runtime.js"));
 exports.auth = __importStar(require("./auth.js"));
 exports.buildinfo = __importStar(require("./buildinfo.js"));
+var chunked_upload_js_1 = require("./chunked_upload.js");
+Object.defineProperty(exports, "ChunkedUpload", { enumerable: true, get: function () { return chunked_upload_js_1.ChunkedUpload; } });

package/dist/cjs/managers/chunked_uploads.js

@@ -43,7 +43,7 @@ class ChunkedUploadsManager {
     constructor(session) {
         this.session = session;
     }
-    async createFileUploadSessions(body) {
+    async createFileUploadSession(body) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += "/upload_sessions";
@@ -54,7 +54,7 @@ class ChunkedUploadsManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
-    async createFileByIdUploadSessions(fileId, body) {
+    async createFileVersionUploadSession(fileId, body) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += '/' + (0, internal_js_1.pathEscape)(fileId);
@@ -84,8 +84,8 @@ class ChunkedUploadsManager {
         let req = this.session.newRequest("PUT", url);
         req = runtime.withHeader(req, "digest", digest);
         req = runtime.withHeader(req, "content-range", contentRange);
-        void body;
-        req = runtime.withStreamBody(req, runtime.Stream.empty(), 'application/octet-stream');
+        const fileBytes = new Uint8Array(await body.arrayBuffer());
+        req = runtime.withStreamBody(req, new runtime.Stream(fileBytes), 'application/octet-stream');
         const resp = await this.session.fetch(req);
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));

package/dist/esm/chunked_upload.js

@@ -0,0 +1,104 @@
+// Code generated by box-gantry. DO NOT EDIT.
+/**
+ * ChunkedUpload orchestrates a Box chunked (multipart) upload over a Client: it
+ * creates an upload session, uploads the content's parts with bounded
+ * concurrency, and commits — for a new file (upload) or a new version of an
+ * existing file (uploadVersion). Box requires chunked upload for files at or
+ * above its minimum session size; smaller files use the single-shot endpoints.
+ */
+export class ChunkedUpload {
+    client;
+    /** Bounds parts in flight, capping peak memory. */
+    maxConcurrent = 4;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Upload content as a new file named fileName into folderId. */
+    async upload(content, fileName, folderId) {
+        const session = await this.client.chunkedUploads.createFileUploadSession({
+            folder_id: folderId,
+            file_size: content.length,
+            file_name: fileName,
+        });
+        return this.finish(session, content);
+    }
+    /** Upload content as a new version of the existing file fileId. */
+    async uploadVersion(content, fileName, fileId) {
+        const session = await this.client.chunkedUploads.createFileVersionUploadSession(fileId, {
+            file_size: content.length,
+            file_name: fileName,
+        });
+        return this.finish(session, content);
+    }
+    async finish(session, content) {
+        if (session.id === undefined) {
+            throw new Error('gantry: upload session returned no id');
+        }
+        if (session.part_size === undefined || session.part_size <= 0) {
+            throw new Error('gantry: upload session returned a non-positive part_size');
+        }
+        const id = session.id;
+        const partSize = session.part_size;
+        const total = content.length;
+        const offsets = [];
+        for (let off = 0; off < total; off += partSize) {
+            offsets.push(off);
+        }
+        const parts = new Array(offsets.length);
+        // A bounded worker pool: each of maxConcurrent workers claims the next
+        // offset (the `next++` read is atomic between awaits on a single thread).
+        // Once any part fails, `failed` stops the others from starting new parts,
+        // so a failure early in a large upload doesn't push every remaining part.
+        let next = 0;
+        let failed = false;
+        const worker = async () => {
+            for (;;) {
+                if (failed) {
+                    return;
+                }
+                const i = next++;
+                if (i >= offsets.length) {
+                    return;
+                }
+                const start = offsets[i];
+                const end = Math.min(start + partSize, total);
+                try {
+                    parts[i] = await this.uploadPart(id, content, start, end, total);
+                }
+                catch (err) {
+                    failed = true;
+                    throw err;
+                }
+            }
+        };
+        const workerCount = Math.min(this.maxConcurrent, offsets.length);
+        await Promise.all(Array.from({ length: workerCount }, () => worker()));
+        const digest = 'sha=' + (await sha1Base64(content));
+        return this.client.chunkedUploads.commitFileUploadSession(id, digest, { parts });
+    }
+    async uploadPart(id, content, start, end, total) {
+        const slice = content.subarray(start, end);
+        const digest = 'sha=' + (await sha1Base64(slice));
+        const contentRange = `bytes ${start}-${end - 1}/${total}`;
+        // The `as BlobPart` cast bridges the `Uint8Array<ArrayBufferLike>` vs
+        // `BufferSource` (ArrayBuffer-only) generic gap in the DOM lib, exactly as
+        // the runtime casts its `fetch` body; a plain `Uint8Array` is a valid part.
+        const uploaded = await this.client.chunkedUploads.updateFileUploadSession(id, digest, contentRange, new Blob([slice]));
+        if (uploaded.part === undefined) {
+            throw new Error('gantry: upload part returned no part');
+        }
+        return uploaded.part;
+    }
+}
+/** Base64 of the SHA-1 of data — the Box `Digest: sha=…` header value. Uses Web
+ *  Crypto (browser and Node 18+), so it adds no dependency. */
+async function sha1Base64(data) {
+    // `as BufferSource` bridges the `Uint8Array<ArrayBufferLike>` vs ArrayBuffer-only
+    // generic gap in the DOM lib (as the runtime does for its `fetch` body).
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-1', data));
+    let binary = '';
+    for (const byte of digest) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}

package/dist/esm/index.js

@@ -5,3 +5,4 @@ export * as managers from './managers/index.js';
 export * as runtime from './runtime.js';
 export * as auth from './auth.js';
 export * as buildinfo from './buildinfo.js';
+export { ChunkedUpload } from './chunked_upload.js';

package/dist/esm/managers/chunked_uploads.js

@@ -7,7 +7,7 @@ export class ChunkedUploadsManager {
     constructor(session) {
         this.session = session;
     }
-    async createFileUploadSessions(body) {
+    async createFileUploadSession(body) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += "/upload_sessions";
@@ -18,7 +18,7 @@ export class ChunkedUploadsManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
-    async createFileByIdUploadSessions(fileId, body) {
+    async createFileVersionUploadSession(fileId, body) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += '/' + pathEscape(fileId);
@@ -48,8 +48,8 @@ export class ChunkedUploadsManager {
         let req = this.session.newRequest("PUT", url);
         req = runtime.withHeader(req, "digest", digest);
         req = runtime.withHeader(req, "content-range", contentRange);
-        void body;
-        req = runtime.withStreamBody(req, runtime.Stream.empty(), 'application/octet-stream');
+        const fileBytes = new Uint8Array(await body.arrayBuffer());
+        req = runtime.withStreamBody(req, new runtime.Stream(fileBytes), 'application/octet-stream');
         const resp = await this.session.fetch(req);
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));

package/dist/types/chunked_upload.d.ts

@@ -0,0 +1,21 @@
+import type { Client } from './client.js';
+import type * as models from './models/index.js';
+/**
+ * ChunkedUpload orchestrates a Box chunked (multipart) upload over a Client: it
+ * creates an upload session, uploads the content's parts with bounded
+ * concurrency, and commits — for a new file (upload) or a new version of an
+ * existing file (uploadVersion). Box requires chunked upload for files at or
+ * above its minimum session size; smaller files use the single-shot endpoints.
+ */
+export declare class ChunkedUpload {
+    private readonly client;
+    /** Bounds parts in flight, capping peak memory. */
+    private readonly maxConcurrent;
+    constructor(client: Client);
+    /** Upload content as a new file named fileName into folderId. */
+    upload(content: Uint8Array, fileName: string, folderId: string): Promise<models.schemas.Files>;
+    /** Upload content as a new version of the existing file fileId. */
+    uploadVersion(content: Uint8Array, fileName: string, fileId: string): Promise<models.schemas.Files>;
+    private finish;
+    private uploadPart;
+}

package/dist/types/index.d.ts

@@ -4,3 +4,4 @@ export * as managers from './managers/index.js';
 export * as runtime from './runtime.js';
 export * as auth from './auth.js';
 export * as buildinfo from './buildinfo.js';
+export { ChunkedUpload } from './chunked_upload.js';

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

@@ -14,8 +14,8 @@ export interface ChunkedUploadsManagerCommitFileUploadSessionOptions {
 export declare class ChunkedUploadsManager {
     private readonly session;
     constructor(session: runtime.Client);
-    createFileUploadSessions(body: models.schemas.FileUploadSessionsCreateRequest): Promise<models.schemas.UploadSession>;
-    createFileByIdUploadSessions(fileId: string, body: models.schemas.FileIdUploadSessionsCreateRequest): Promise<models.schemas.UploadSession>;
+    createFileUploadSession(body: models.schemas.FileUploadSessionCreateRequest): Promise<models.schemas.UploadSession>;
+    createFileVersionUploadSession(fileId: string, body: models.schemas.FileVersionUploadSessionCreateRequest): Promise<models.schemas.UploadSession>;
     getFileUploadSession(uploadSessionId: string): Promise<models.schemas.UploadSession>;
     updateFileUploadSession(uploadSessionId: string, digest: string, contentRange: string, body: Blob): Promise<models.schemas.UploadedPart>;
     deleteFileUploadSession(uploadSessionId: string): Promise<void>;

package/dist/types/models/schemas.d.ts

@@ -3059,12 +3059,12 @@ export interface OptionFileContentRequest {
     size?: number;
     parent?: PostFileIdParent;
 }
-export interface FileUploadSessionsCreateRequest {
+export interface FileUploadSessionCreateRequest {
     folder_id: string;
     file_size: number;
     file_name: string;
 }
-export interface FileIdUploadSessionsCreateRequest {
+export interface FileVersionUploadSessionCreateRequest {
     file_size: number;
     file_name?: string;
 }

package/docs/managers/chunked_uploads.md

@@ -3,21 +3,21 @@
 
 Reach these methods through the `chunkedUploads` field on `Client`.
 
-## createFileUploadSessions
+## createFileUploadSession
 
 `POST /files/upload_sessions`
 
-**Request body** (`application/json`): `FileUploadSessionsCreateRequest`
+**Request body** (`application/json`): `FileUploadSessionCreateRequest`
 
 **Returns:** `UploadSession`
 
 **Example**
 
 ```ts
-const result = await client.chunkedUploads.createFileUploadSessions({ /* … */ });
+const result = await client.chunkedUploads.createFileUploadSession({ /* … */ });
 ```
 
-## createFileByIdUploadSessions
+## createFileVersionUploadSession
 
 `POST /files/{file_id}/upload_sessions`
 
@@ -25,14 +25,14 @@ const result = await client.chunkedUploads.createFileUploadSessions({ /* … */
 |---|---|---|---|
 | `file_id` | path | `string` | yes |
 
-**Request body** (`application/json`): `FileIdUploadSessionsCreateRequest`
+**Request body** (`application/json`): `FileVersionUploadSessionCreateRequest`
 
 **Returns:** `UploadSession`
 
 **Example**
 
 ```ts
-const result = await client.chunkedUploads.createFileByIdUploadSessions("FILE_ID", { /* … */ });
+const result = await client.chunkedUploads.createFileVersionUploadSession("FILE_ID", { /* … */ });
 ```
 
 ## getFileUploadSession

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@unofficialbox/box-open-sdk",
-  "version": "0.2.0",
-  "description": "Community, unofficial Box API client for TypeScript — typed models, async managers, and a fetch runtime with retry, backoff, and token refresh.",
+  "version": "0.3.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",
-  "repository": { "type": "git", "url": "git+https://github.com/unofficialbox/box-open-ts-sdk.git" },
+  "repository": { "type": "git", "url": "git+https://github.com/unofficialbox/box-gantry.git" },
   "homepage": "https://github.com/unofficialbox/box-open-ts-sdk",
   "type": "module",
   "sideEffects": false,