Box TypeScript SDK Gen

1.19.1 verified Sat Apr 25 auth: no javascript

Official Box TypeScript SDK generated from the Box OpenAPI specification. Current stable version is 1.19.1, with frequent releases (multiple per month) as part of an auto-generation pipeline. It provides full coverage of the Box API, including AI, classification, chunk uploads, webhooks, and sign requests. Supports both ESM and CJS, includes TypeScript types, and offers built-in retries with exponential backoff, authentication, and request cancellation. Key differentiators vs older Box SDKs: rapid API updates (days vs months), embedded documentation via JSDoc, and generated code consistency across languages. Requires Node.js >=16.

Common errors

error Cannot find module 'box-typescript-sdk-gen' ↓

cause Package not installed or wrong import path.

fix

Run 'npm install box-typescript-sdk-gen' and ensure your Node.js version is >=16.

error TypeError: BoxClient is not a constructor ↓

cause Default import used instead of named import (or wrong import style).

fix

Use 'import { BoxClient } from 'box-typescript-sdk-gen'' (curly braces).

error Uncaught TypeError: Cannot read properties of undefined (reading 'getUserById') ↓

cause BoxClient not properly initialized due to missing auth or invalid token.

fix

Ensure authentication is set up correctly, e.g., new BoxDeveloperTokenAuth({ token: process.env.BOX_DEV_TOKEN }) and pass to BoxClient.

error Error: connect ECONNREFUSED 127.0.0.1:443 ↓

cause Network issue; the SDK cannot reach Box API endpoints.

fix

Check network connectivity and proxy settings. Ensure the environment allows outbound HTTPS requests.

Warnings

gotcha ESM imports must use named exports; default import is not available. ↓

fix Use import { BoxClient } from 'box-typescript-sdk-gen' instead of import BoxClient from 'box-typescript-sdk-gen'.

deprecated Old Box TypeScript SDK (non-generated) is deprecated; migrate to this SDK. ↓

fix Replace old import paths with new generated SDK.

breaking Constructor arguments for auth classes changed to object parameter in v1.0.0. ↓

fix Pass auth config as an object: new BoxDeveloperTokenAuth({ token: '...' }).

gotcha Node.js >=16 required; the SDK does not work in older Node versions due to fetch and other modern APIs. ↓

fix Upgrade Node.js to version 16 or later.

deprecated CJS require() works but is not recommended; ESM is preferred for tree-shaking and type safety. ↓

fix Use ESM imports (import ... from ...).

breaking In v1.18.0, form-data was bumped to 4.0.4, which may cause issues with older Node.js fetch implementations. ↓

fix Update to v1.19.1 or later which fixes ESM build.

gotcha Webhook signature verification changed in v1.16.0: body is now escaped before signing. ↓

fix Use the updated verifySignature method which handles both escaped and unescaped bodies.

Install

npm install box-typescript-sdk-gen

yarn add box-typescript-sdk-gen

pnpm add box-typescript-sdk-gen

Imports

BoxClient
wrong
```
import BoxClient from 'box-typescript-sdk-gen'
```
correct
```
import { BoxClient } from 'box-typescript-sdk-gen'
```
BoxClient is a named export, not default. ESM import is required for tree-shaking; CJS require is also valid.

BoxDeveloperTokenAuth

wrong

import { DeveloperTokenAuth } from 'box-typescript-sdk-gen'

correct

import { BoxDeveloperTokenAuth } from 'box-typescript-sdk-gen'

Class name includes 'Box' prefix, consistent with other auth types like BoxJWT, BoxCCG.

BoxOAuth

wrong

const BoxOAuth = require('box-typescript-sdk-gen').BoxOAuth

correct

import { BoxOAuth } from 'box-typescript-sdk-gen'

Both ESM and CJS work, but TypeScript expects named import for type inference.

Quickstart

Authenticate with a developer token and retrieve current user info and root folder contents.

import { BoxClient, BoxDeveloperTokenAuth } from 'box-typescript-sdk-gen';

const auth = new BoxDeveloperTokenAuth({ token: process.env.BOX_DEV_TOKEN ?? '' });
const client = new BoxClient({ auth });

async function main() {
  const me = await client.users.getUserById({ userId: 'me' });
  console.log(`Logged in as ${me.name} (${me.login})`);

  const items = await client.folders.getFolderItems({ folderId: '0' });
  for (const item of items.entries) {
    console.log(`${item.type}: ${item.name}`);
  }
}

main().catch(console.error);