Box

Box via the official typed SDK. Translates virtual keys into nested folders under a configurable rootFolderId.

Installation

box-typescript-sdk-gen is an optional peer dependency of files-sdk - install alongside the SDK so the adapter's imports resolve at runtime.

npm install files-sdk box-typescript-sdk-gen

Box via the official box-typescript-sdk-gen SDK. Box files live by ID, not by path, so the adapter walks rootFolderId and translates virtual keys (docs/a.txt) into nested Box subfolders, auto-creating intermediate folders on upload(). Five auth shapes (pre-built client, developer token, OAuth refresh-token, Client Credentials Grant, JWT server auth) cover scripts, user apps, and enterprise installs - token lifecycle is handled by the SDK's built-in Authentication classes.

import { Files } from "files-sdk";import { box } from "files-sdk/box";// Server-side: Client Credentials Grant (recommended for backend services).// The SDK manages access-token lifetime internally - no manual refresh// bookkeeping in the adapter.const files = new Files({  adapter: box({    ccg: {      clientId: process.env.BOX_CLIENT_ID!,      clientSecret: process.env.BOX_CLIENT_SECRET!,      enterpriseId: process.env.BOX_ENTERPRISE_ID!,    },    rootFolderId: process.env.BOX_ROOT_FOLDER_ID, // defaults to "0" (account root)    // publicByDefault: true → upload() also calls addShareLinkToFile and    //                       url() returns the link's download_url.  }),});// Other auth shapes the adapter accepts://   developerToken: process.env.BOX_DEVELOPER_TOKEN  // dev-console token//   oauth: { clientId, clientSecret, refreshToken } // user-app flow//   jwt:   { configJsonString }                     // JWT server auth//   client: yourBoxClient                           // pre-built escape hatch

Options

Limitations

signedUploadUrl() throws - Box uploads require a multipart POST with both an attributes JSON part and the file bytes part, which fits neither the SDK's PUT-with-headers nor POST-with-form-fields shape. Use upload() server-side, or Box's UI Elements / Content Uploader for browser flows. Direct upload() handles up to Box's 50 MB single-call limit; larger bodies switch to chunkedUploads.uploadBigFile. Stream bodies are buffered up-front because the SDK's upload manager takes a Node Readable rather than a Web stream. list() returns immediate-children files only at rootFolderId - no recursion, subfolders are filtered out, and prefix is matched client-side within the page; for deep enumeration drop to raw.folders.getFolderItems and recurse manually. responseContentDisposition always throws - Box's getDownloadFileUrl and shared-link URLs have no Content-Disposition override. User metadata and cacheControl on upload() throw - Box exposes file metadata via classifications and metadata templates; drop to raw.fileMetadata.* if you need it. Box doesn't store user-supplied content types on file content, so head() and list() return a type inferred from the filename extension.