@unofficialbox/box-open-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,91 @@
-<!-- Generated by box-gantry. DO NOT EDIT. -->
-# Box SDK
+<!-- Generated by box-gantry. DO NOT EDIT — regenerate from the specs instead. -->
+![Box Open SDK for TypeScript](assets/banner.svg)
 
-A generated TypeScript SDK for the Box API — a dual ESM/CJS package with
-shipped type declarations.
+# @unofficialbox/box-open-sdk
+
+[![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
+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
+dependencies.
+
+> **Not affiliated with, authorized, or endorsed by Box, Inc.** "Box" is a
+> trademark of Box, Inc. This is an independent, generated client.
+
+## Install
+
+```sh
+npm install @unofficialbox/box-open-sdk
+```
+
+## Quickstart
+
+Authenticate, look up the current user, create a folder, upload a file, extract
+its fields with Box AI, tag it with metadata, and query for it — end to end:
 
 ```ts
-import { Client, runtime } from '@unofficialbox/box-open-sdk';
-const client = new Client(runtime.developerToken('DEVELOPER_TOKEN'));
+import { Client, auth } from '@unofficialbox/box-open-sdk';
+
+// Client Credentials Grant (server-to-server); developer token, OAuth, and JWT
+// also live in the `auth` namespace.
+const client = new Client(auth.clientCredentials({
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+  enterpriseId: 'ENTERPRISE_ID',
+}));
+
+// The current user.
+const me = await client.users.getMe();
+console.log(`authenticated as ${me.id}`);
+
+// Create a folder at the account root ("0").
+const folder = await client.folders.create({
+  name: 'Invoices',
+  parent: { id: '0' },
+});
+
+// Upload a file into it.
+const uploaded = await client.uploads.uploadFile({
+  attributes: { name: 'invoice.pdf', parent: { id: folder.id } },
+  file: new Blob(['<file bytes>']),
+});
+const fileId = uploaded.entries![0].id;
+
+// Extract fields from the file with Box AI.
+const answer = await client.ai.extract({
+  prompt: 'Extract the invoice number and total amount.',
+  items: [{ id: fileId, type: 'file' }],
+});
+console.log(answer);
+
+// Attach that metadata to the file (an enterprise template).
+await client.fileMetadata.createFileMetadata(fileId, 'enterprise', 'invoiceData', {
+  invoiceNumber: 'INV-0042',
+  total: 1250,
+});
+
+// Query for files carrying that metadata.
+const results = await client.search.queryByMetadata({
+  from: 'enterprise_0.invoiceData',
+  ancestor_folder_id: folder.id,
+});
+console.log(results);
 ```
 
-See [`docs/`](./docs/README.md) for the manager reference and the
+## Authentication
+
+The runtime implements Box's four auth flows — **developer token**, **client
+credentials (CCG)**, **OAuth 2.0** (with a pluggable refresh-token store), and
+**JWT** (server auth, exposed as the Node-only `./jwt` subpath). See
+[`docs/auth.md`](./docs/auth.md).
+
+## Documentation
+
+The [`docs/`](./docs/README.md) tree carries the per-manager reference and the
 authentication, pagination, and errors guides.
+
+## License
+
+MIT. Generated by [box-gantry](https://github.com/unofficialbox/box-gantry).

package/dist/cjs/index.js

@@ -34,10 +34,11 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildinfo = exports.runtime = exports.managers = exports.models = exports.Client = void 0;
+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"));
 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"));

package/dist/cjs/managers/search.js

@@ -43,7 +43,7 @@ class SearchManager {
     constructor(session) {
         this.session = session;
     }
-    async createMetadataQueryExecuteRead(body) {
+    async queryByMetadata(body) {
         let url = this.session.baseUrl("api");
         url += "/metadata_queries";
         url += "/execute_read";

package/dist/cjs/managers/transfer.js

@@ -43,7 +43,7 @@ class TransferManager {
     constructor(session) {
         this.session = session;
     }
-    async updateUserFolder0(userId, body, opts) {
+    async transferFolders(userId, body, opts) {
         let url = this.session.baseUrl("api");
         url += "/users";
         url += '/' + (0, internal_js_1.pathEscape)(userId);

package/dist/cjs/managers/uploads.js

@@ -43,7 +43,7 @@ class UploadsManager {
     constructor(session) {
         this.session = session;
     }
-    async createFileContent(fileId, body, opts) {
+    async uploadFileVersion(fileId, body, opts) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += '/' + (0, internal_js_1.pathEscape)(fileId);
@@ -65,7 +65,7 @@ class UploadsManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
-    async createFileContent2(body, opts) {
+    async uploadFile(body, opts) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += "/content";

package/dist/esm/index.js

@@ -3,4 +3,5 @@ export { Client } from './client.js';
 export * as models from './models/index.js';
 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';

package/dist/esm/managers/search.js

@@ -7,7 +7,7 @@ export class SearchManager {
     constructor(session) {
         this.session = session;
     }
-    async createMetadataQueryExecuteRead(body) {
+    async queryByMetadata(body) {
         let url = this.session.baseUrl("api");
         url += "/metadata_queries";
         url += "/execute_read";

package/dist/esm/managers/transfer.js

@@ -7,7 +7,7 @@ export class TransferManager {
     constructor(session) {
         this.session = session;
     }
-    async updateUserFolder0(userId, body, opts) {
+    async transferFolders(userId, body, opts) {
         let url = this.session.baseUrl("api");
         url += "/users";
         url += '/' + pathEscape(userId);

package/dist/esm/managers/uploads.js

@@ -7,7 +7,7 @@ export class UploadsManager {
     constructor(session) {
         this.session = session;
     }
-    async createFileContent(fileId, body, opts) {
+    async uploadFileVersion(fileId, body, opts) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += '/' + pathEscape(fileId);
@@ -29,7 +29,7 @@ export class UploadsManager {
         const data = runtime.responseBytes(resp);
         return JSON.parse(new TextDecoder().decode(data));
     }
-    async createFileContent2(body, opts) {
+    async uploadFile(body, opts) {
         let url = this.session.baseUrl("upload");
         url += "/files";
         url += "/content";

package/dist/types/index.d.ts

@@ -2,4 +2,5 @@ export { Client } from './client.js';
 export * as models from './models/index.js';
 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';

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

@@ -28,6 +28,6 @@ export interface SearchManagerGetOptions {
 export declare class SearchManager {
     private readonly session;
     constructor(session: runtime.Client);
-    createMetadataQueryExecuteRead(body: models.schemas.MetadataQuery): Promise<models.schemas.MetadataQueryResults>;
+    queryByMetadata(body: models.schemas.MetadataQuery): Promise<models.schemas.MetadataQueryResults>;
     get(opts?: SearchManagerGetOptions): Promise<models.schemas.SearchResultsResponse>;
 }

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

@@ -1,7 +1,7 @@
 import * as runtime from '../runtime.js';
 import type * as models from '../models/index.js';
-/** Optional parameters for TransferManager.updateUserFolder0. */
-export interface TransferManagerUpdateUserFolder0Options {
+/** Optional parameters for TransferManager.transferFolders. */
+export interface TransferManagerTransferFoldersOptions {
     fields?: Array<string>;
     notify?: boolean;
 }
@@ -9,5 +9,5 @@ export interface TransferManagerUpdateUserFolder0Options {
 export declare class TransferManager {
     private readonly session;
     constructor(session: runtime.Client);
-    updateUserFolder0(userId: string, body: models.schemas.UserFolder0UpdateRequest, opts?: TransferManagerUpdateUserFolder0Options): Promise<models.schemas.FolderFull>;
+    transferFolders(userId: string, body: models.schemas.UserFolder0UpdateRequest, opts?: TransferManagerTransferFoldersOptions): Promise<models.schemas.FolderFull>;
 }

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

@@ -1,13 +1,13 @@
 import * as runtime from '../runtime.js';
 import type * as models from '../models/index.js';
-/** Optional parameters for UploadsManager.createFileContent. */
-export interface UploadsManagerCreateFileContentOptions {
+/** Optional parameters for UploadsManager.uploadFileVersion. */
+export interface UploadsManagerUploadFileVersionOptions {
     "if-match"?: string;
     fields?: Array<string>;
     "content-md5"?: string;
 }
-/** Optional parameters for UploadsManager.createFileContent2. */
-export interface UploadsManagerCreateFileContent2Options {
+/** Optional parameters for UploadsManager.uploadFile. */
+export interface UploadsManagerUploadFileOptions {
     fields?: Array<string>;
     "content-md5"?: string;
 }
@@ -15,7 +15,7 @@ export interface UploadsManagerCreateFileContent2Options {
 export declare class UploadsManager {
     private readonly session;
     constructor(session: runtime.Client);
-    createFileContent(fileId: string, body: models.schemas.FileIdContentCreateRequest, opts?: UploadsManagerCreateFileContentOptions): Promise<models.schemas.Files>;
-    createFileContent2(body: models.schemas.FileContentCreateRequest, opts?: UploadsManagerCreateFileContent2Options): Promise<models.schemas.Files>;
+    uploadFileVersion(fileId: string, body: models.schemas.FileIdContentCreateRequest, opts?: UploadsManagerUploadFileVersionOptions): Promise<models.schemas.Files>;
+    uploadFile(body: models.schemas.FileContentCreateRequest, opts?: UploadsManagerUploadFileOptions): Promise<models.schemas.Files>;
     optionFileContent(body: models.schemas.OptionFileContentRequest): Promise<models.schemas.UploadUrl>;
 }

package/docs/auth.md

@@ -3,16 +3,16 @@
 
 Build a `Client` from one of the four Box auth flows. Each flow is an `Auth`
 the runtime uses to fetch a bearer token; the network layer refreshes on a
-`401` and retries once. The flow builders live in the runtime package and are
-passed straight to `new Client(...)`.
+`401` and retries once. The flow builders live in the `auth` namespace (JWT on
+the Node-only `./jwt` subpath) and are passed straight to `new Client(...)`.
 
 ## Developer Token
 
 A fixed token from the Developer Console, for quick local testing:
 
 ```ts
-import { developerToken } from 'box-gantry-runtime';
-const client = new Client(developerToken('DEVELOPER_TOKEN'));
+import { auth } from '@unofficialbox/box-open-sdk';
+const client = new Client(auth.developerToken('DEVELOPER_TOKEN'));
 ```
 
 ## Client Credentials Grant (server auth, no key)
@@ -21,8 +21,8 @@ Set exactly one subject — `enterpriseId` for the service account, or `userId`
 to act as a managed user:
 
 ```ts
-import { clientCredentials } from 'box-gantry-runtime';
-const client = new Client(clientCredentials({
+import { auth } from '@unofficialbox/box-open-sdk';
+const client = new Client(auth.clientCredentials({
 clientId: 'CLIENT_ID',
 clientSecret: 'CLIENT_SECRET',
 enterpriseId: 'ENTERPRISE_ID',
@@ -36,7 +36,7 @@ loudly at construction. It reaches `node:crypto`, so it is a Node-only leaf
 imported from the runtime's `./jwt` entry point and returns a promise:
 
 ```ts
-import { jwtAuth } from 'box-gantry-runtime/jwt';
+import { jwtAuth } from '@unofficialbox/box-open-sdk/jwt';
 const auth = await jwtAuth({
 clientId: 'CLIENT_ID',
 clientSecret: 'CLIENT_SECRET',
@@ -53,8 +53,8 @@ Redirect the user to the authorize URL, exchange the returned code, then reuse
 the rotated refresh token on later runs (persist it via `onRefresh`):
 
 ```ts
-import { oauth } from 'box-gantry-runtime';
+import { auth } from '@unofficialbox/box-open-sdk';
 // later runs: resume from the stored refresh token.
-const auth = oauth({ clientId: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET' }, storedRefreshToken);
-const client = new Client(auth);
+const source = auth.oauth({ clientId: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET' }, storedRefreshToken);
+const client = new Client(source);
 ```

package/docs/errors.md

@@ -9,11 +9,11 @@ when the failure came with a response, and the underlying `cause` for
 transport or decode failures:
 
 ```ts
-import { BoxApiError } from 'box-gantry-runtime';
+import { runtime } from '@unofficialbox/box-open-sdk';
 try {
 await client.files.getFileById(fileId);
 } catch (err) {
-if (err instanceof BoxApiError) {
+if (err instanceof runtime.BoxApiError) {
 // err.status (number | undefined), err.cause
 }
 }

package/docs/managers/ai.md

@@ -11,6 +11,12 @@ Reach these methods through the `ai` field on `Client`.
 
 **Returns:** `AiResponseFull`
 
+**Example**
+
+```ts
+const result = await client.ai.ask({ /* … */ });
+```
+
 ## createTextGen
 
 `POST /ai/text_gen`
@@ -19,6 +25,12 @@ Reach these methods through the `ai` field on `Client`.
 
 **Returns:** `AiResponse`
 
+**Example**
+
+```ts
+const result = await client.ai.createTextGen({ /* … */ });
+```
+
 ## getAgentDefault
 
 `GET /ai_agent_default`
@@ -31,6 +43,12 @@ Reach these methods through the `ai` field on `Client`.
 
 **Returns:** `AiAgent`
 
+**Example**
+
+```ts
+const result = await client.ai.getAgentDefault("...");
+```
+
 ## extract
 
 `POST /ai/extract`
@@ -39,6 +57,12 @@ Reach these methods through the `ai` field on `Client`.
 
 **Returns:** `AiResponse`
 
+**Example**
+
+```ts
+const result = await client.ai.extract({ /* … */ });
+```
+
 ## createExtractStructured
 
 `POST /ai/extract_structured`
@@ -47,3 +71,9 @@ Reach these methods through the `ai` field on `Client`.
 
 **Returns:** `AiExtractStructuredResponse`
 
+**Example**
+
+```ts
+const result = await client.ai.createExtractStructured({ /* … */ });
+```
+

package/docs/managers/ai_studio.md

@@ -18,6 +18,14 @@ Reach these methods through the `aiStudio` field on `Client`.
 
 **Returns:** `AiMultipleAgentResponse`
 
+**Example**
+
+```ts
+for await (const item of client.aiStudio.listAiAgents()) {
+  // use item
+}
+```
+
 Paginated — `listAiAgents(...)` is an async iterable that yields each entry across pages (`for await (const item of ...)`), threading the cursor for you. See the [pagination guide](../pagination.md).
 
 ## createAiAgents
@@ -28,6 +36,12 @@ Paginated — `listAiAgents(...)` is an async iterable that yields each entry ac
 
 **Returns:** `AiSingleAgentResponseFull`
 
+**Example**
+
+```ts
+const result = await client.aiStudio.createAiAgents({ /* … */ });
+```
+
 ## getAiAgent
 
 `GET /ai_agents/{agent_id}`
@@ -39,6 +53,12 @@ Paginated — `listAiAgents(...)` is an async iterable that yields each entry ac
 
 **Returns:** `AiSingleAgentResponseFull`
 
+**Example**
+
+```ts
+const result = await client.aiStudio.getAiAgent("AGENT_ID");
+```
+
 ## updateAiAgent
 
 `PUT /ai_agents/{agent_id}`
@@ -51,6 +71,12 @@ Paginated — `listAiAgents(...)` is an async iterable that yields each entry ac
 
 **Returns:** `AiSingleAgentResponseFull`
 
+**Example**
+
+```ts
+const result = await client.aiStudio.updateAiAgent("AGENT_ID", { /* … */ });
+```
+
 ## deleteAiAgent
 
 `DELETE /ai_agents/{agent_id}`
@@ -61,3 +87,9 @@ Paginated — `listAiAgents(...)` is an async iterable that yields each entry ac
 
 **Returns:** `void`
 
+**Example**
+
+```ts
+await client.aiStudio.deleteAiAgent("AGENT_ID");
+```
+

package/docs/managers/app_item_associations.md

@@ -16,6 +16,14 @@ Reach these methods through the `appItemAssociations` field on `Client`.
 
 **Returns:** `AppItemAssociations`
 
+**Example**
+
+```ts
+for await (const item of client.appItemAssociations.listFile("FILE_ID")) {
+  // use item
+}
+```
+
 Paginated — `listFile(...)` is an async iterable that yields each entry across pages (`for await (const item of ...)`), threading the cursor for you. See the [pagination guide](../pagination.md).
 
 ## listFolder
@@ -31,5 +39,13 @@ Paginated — `listFile(...)` is an async iterable that yields each entry across
 
 **Returns:** `AppItemAssociations`
 
+**Example**
+
+```ts
+for await (const item of client.appItemAssociations.listFolder("FOLDER_ID")) {
+  // use item
+}
+```
+
 Paginated — `listFolder(...)` is an async iterable that yields each entry across pages (`for await (const item of ...)`), threading the cursor for you. See the [pagination guide](../pagination.md).
 

package/docs/managers/archives.md

@@ -14,6 +14,14 @@ Reach these methods through the `archives` field on `Client`.
 
 **Returns:** `Archives`
 
+**Example**
+
+```ts
+for await (const item of client.archives.list()) {
+  // use item
+}
+```
+
 Paginated — `list(...)` is an async iterable that yields each entry across pages (`for await (const item of ...)`), threading the cursor for you. See the [pagination guide](../pagination.md).
 
 ## create
@@ -24,6 +32,12 @@ Paginated — `list(...)` is an async iterable that yields each entry across pag
 
 **Returns:** `Archive`
 
+**Example**
+
+```ts
+const result = await client.archives.create({ /* … */ });
+```
+
 ## update
 
 `PUT /archives/{archive_id}`
@@ -36,6 +50,12 @@ Paginated — `list(...)` is an async iterable that yields each entry across pag
 
 **Returns:** `Archive`
 
+**Example**
+
+```ts
+const result = await client.archives.update("ARCHIVE_ID", { /* … */ });
+```
+
 ## delete_
 
 `DELETE /archives/{archive_id}`
@@ -46,3 +66,9 @@ Paginated — `list(...)` is an async iterable that yields each entry across pag
 
 **Returns:** `void`
 
+**Example**
+
+```ts
+await client.archives.delete_("ARCHIVE_ID");
+```
+

package/docs/managers/authorization.md

@@ -17,6 +17,12 @@ Reach these methods through the `authorization` field on `Client`.
 
 **Returns:** text (`string`)
 
+**Example**
+
+```ts
+const result = await client.authorization.authorize("...", "CLIENT_ID");
+```
+
 ## createOauth2Token
 
 `POST /oauth2/token`
@@ -25,6 +31,12 @@ Reach these methods through the `authorization` field on `Client`.
 
 **Returns:** `AccessToken`
 
+**Example**
+
+```ts
+const result = await client.authorization.createOauth2Token({ /* … */ });
+```
+
 ## createOauth2TokenRefresh
 
 `POST /oauth2/token`
@@ -33,6 +45,12 @@ Reach these methods through the `authorization` field on `Client`.
 
 **Returns:** `AccessToken`
 
+**Example**
+
+```ts
+const result = await client.authorization.createOauth2TokenRefresh({ /* … */ });
+```
+
 ## revokeOauth2
 
 `POST /oauth2/revoke`
@@ -41,3 +59,9 @@ Reach these methods through the `authorization` field on `Client`.
 
 **Returns:** `void`
 
+**Example**
+
+```ts
+await client.authorization.revokeOauth2({ /* … */ });
+```
+

package/docs/managers/automate_workflows.md

@@ -15,6 +15,14 @@ Reach these methods through the `automateWorkflows` field on `Client`.
 
 **Returns:** `AutomateWorkflows`
 
+**Example**
+
+```ts
+for await (const item of client.automateWorkflows.list("FOLDER_ID")) {
+  // use item
+}
+```
+
 Paginated — `list(...)` is an async iterable that yields each entry across pages (`for await (const item of ...)`), threading the cursor for you. See the [pagination guide](../pagination.md).
 
 ## start
@@ -29,3 +37,9 @@ Paginated — `list(...)` is an async iterable that yields each entry across pag
 
 **Returns:** `void`
 
+**Example**
+
+```ts
+await client.automateWorkflows.start("WORKFLOW_ID", { /* … */ });
+```
+

package/docs/managers/avatars.md

@@ -13,6 +13,12 @@ Reach these methods through the `avatars` field on `Client`.
 
 **Returns:** a binary stream (`runtime.Stream`)
 
+**Example**
+
+```ts
+const result = await client.avatars.getUserAvatar("USER_ID");
+```
+
 ## createUserAvatar
 
 `POST /users/{user_id}/avatar`
@@ -25,6 +31,12 @@ Reach these methods through the `avatars` field on `Client`.
 
 **Returns:** `UserAvatar`
 
+**Example**
+
+```ts
+const result = await client.avatars.createUserAvatar("USER_ID", { /* … */ });
+```
+
 ## deleteUserAvatar
 
 `DELETE /users/{user_id}/avatar`
@@ -35,3 +47,9 @@ Reach these methods through the `avatars` field on `Client`.
 
 **Returns:** `void`
 
+**Example**
+
+```ts
+await client.avatars.deleteUserAvatar("USER_ID");
+```
+