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

nub add files-sdk box-typescript-sdk-gen

aube 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, for the signed download URLs `url()` mints via `getDownloadFileUrl`. Accepted for API symmetry but not honoured: `getDownloadFileUrl` takes no expiry, so Box controls the TTL server-side (the URLs are short-lived by API design). 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 lists one folder: the one the prefix points into (the part up to its last /, resolved under 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 upload a new version (overwrite) through `uploadFileVersion`, or a chunked upload session for the existing file above 50 MB. 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`	⚠️	Lists one folder, no recursion: the folder the `prefix` points into (the part up to its last `/`, resolved under `rootFolderId` - `photos/` lists `photos`), with the rest of the prefix matched client-side against child names within the page. Keys come back in full (`photos/cover.jpg`). Without a delimiter, subfolders are skipped; with `delimiter: '/'` they come back as `prefixes` (`photos/2024/`) that you can pass back as the next `prefix`. A prefix into a missing folder lists nothing. Pagination uses Box’s marker-based paging (the opaque marker is the cursor), so large folders page past Box’s 10,000-item offset cap.
`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>`. Both of those modes return a permanent link, so `capabilities.signedUrl.supported` is `false` in them. `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