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

pnpm add files-sdk box-typescript-sdk-gen

yarn add files-sdk box-typescript-sdk-gen

bun add 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

PropType

rootFolderId?string

Logical "bucket root" — virtual keys live under this Box folder ID. Use `"0"` (the default) to anchor at the user's root folder. The folder must already exist; intermediate subfolders are auto-created on upload.

Typestring

publicByDefault?boolean

When `true`, `upload()` also creates a public shared link (anyone with the link can preview/download) and `url()` returns that link's `download_url` (or `url` if `download_url` is absent — typical for non-binary previews). When `false` (default), `url()` mints a short-lived signed download URL via `getDownloadFileUrl`. **Plan/policy note:** public shared links may be restricted on Box Business or Enterprise plans; the adapter surfaces Box's `access_denied_insufficient_permissions` error unmodified in that case.

Typeboolean

publicBaseUrl?string

Origin used to build URLs from `url()`. When set, `url(key)` returns `${publicBaseUrl}/${key}` and skips both signing and shared-link resolution. Useful when a CDN or vanity domain sits in front of pre-shared Box links.

Typestring

defaultUrlExpiresIn?number

Default expiry, in seconds, used when `url()` mints a signed download URL via `getDownloadFileUrl`. Box does not document a hard maximum for these URLs (they are short-lived by API design); the adapter passes the value through. Defaults to 3600.

Typenumber

client?BoxClient

Pre-built `BoxClient` — escape hatch for callers that already wire auth themselves (e.g. with custom `NetworkSession`, proxy config, or downscoped tokens).

TypeBoxClient

developerToken?string

Static developer token from the Box developer console. Useful for scripts and trying the adapter; production apps should use OAuth, CCG, or JWT instead. Falls back to env `BOX_DEVELOPER_TOKEN`.

Typestring

oauth?BoxOAuthOptions

OAuth2 user-app flow seeded with a refresh token.

TypeBoxOAuthOptions

ccg?BoxCcgOptions

Server-side Client Credentials Grant.

TypeBoxCcgOptions

jwt?BoxJwtOptions

JWT Server Authentication, configured via the JSON blob from Box's developer console.

TypeBoxJwtOptions

Limitations

list() is not recursive - it returns immediate-children files only at rootFolderId. For deep enumeration, drop to raw.folders.getFolderItems and recurse manually.

Compatibility

Method	Status	Notes
`upload`	⚠️	Two-stage: walks/creates parent folders by ID under `rootFolderId`, then `uploads.uploadFile` (≤50 MB) or `chunkedUploads.uploadBigFile` (>50 MB). Re-uploads against existing leaf names route through `uploadFileVersion` (overwrite). Stream bodies are buffered up-front - Box’s upload manager takes a Node `Readable`, not a Web stream. User `metadata` and `cacheControl` throw - Box exposes file metadata via classifications and metadata templates; drop to `raw.fileMetadata.*` if you need it. Pause/resume via `control` is in-process only — the chunked-upload commit needs a whole-file digest, so a token cannot resume in a new process.
`download`	⚠️	Resolves the file ID, then fetches `getDownloadFileUrl` for both buffered and streaming reads - the SDK’s native `downloadFile` returns a Node `Readable` that’s awkward to expose isomorphically, so the adapter routes through standard HTTP, which gives a `ReadableStream` body.
`delete`	✅
`list`	⚠️	Returns immediate-children files only at `rootFolderId` - no recursion, and subfolders are filtered out. `prefix` is filename-prefix only (matched client-side within the page). Pagination uses Box’s offset, encoded as a numeric cursor string.
`search`	⚠️	Built on `listAll` — inherits this adapter’s `list` behavior above. Client-side key match (glob, regex, substring, exact).
`head`	⚠️	Box doesn’t store user-supplied content types on file content - `head()` returns a type inferred from the filename extension (or `application/octet-stream` when unknown). `size`, `etag`, and `lastModified` come from `getFileById`.
`exists`	✅
`copy`	✅
`url`	⚠️	Default mints a signed download URL via `getDownloadFileUrl` - Box controls the TTL server-side, so `expiresIn` is accepted for API symmetry but is not honoured. With `publicByDefault: true`, `upload()` calls `addShareLinkToFile` (open access) and `url()` returns the link’s `download_url`. With `publicBaseUrl`, returns `<publicBaseUrl>/<key>`. `responseContentDisposition` always throws - Box’s URLs have no Content-Disposition override.
`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 S3-style POST-with-form-fields shape. Use `upload()` server-side, or Box’s UI Elements / Content Uploader for browser flows.

Box

Installation

Usage

Options

Limitations

Compatibility