@unofficialbox/box-open-sdk 0.8.0 → 0.9.0

package/dist/cjs/client.js

@@ -181,10 +181,13 @@ class Client {
     webhooks;
     workflows;
     zipDownloads;
+    #session;
     /** Build a client for an authentication flow; `options` configures the
-     * runtime session (retries, `fetch`, default headers, base URLs). */
+     * runtime session (retries, `fetch`, default headers, base URLs). An
+     * already configured runtime session is used as is. */
     constructor(auth, options = {}) {
-        const session = new runtime_js_1.Client(auth, options);
+        const session = auth instanceof runtime_js_1.Client ? auth : new runtime_js_1.Client(auth, options);
+        this.#session = session;
         this.ai = new ai_js_1.AiManager(session);
         this.aiStudio = new ai_studio_js_1.AiStudioManager(session);
         this.appItemAssociations = new app_item_associations_js_1.AppItemAssociationsManager(session);
@@ -274,5 +277,11 @@ class Client {
         this.workflows = new workflows_js_1.WorkflowsManager(session);
         this.zipDownloads = new zip_downloads_js_1.ZipDownloadsManager(session);
     }
+    /** A new client whose every API call acts as the user `userId` (Box's
+     * `As-User` header). It shares this client's auth and configuration;
+     * this client is unchanged. */
+    withAsUserHeader(userId) {
+        return new Client(this.#session.withAsUserHeader(userId));
+    }
 }
 exports.Client = Client;

package/dist/cjs/errors.js

@@ -57,8 +57,9 @@ function apiErrorFromResponse(status, body) {
         const value = payload[key];
         return typeof value === 'string' ? value : undefined;
     };
-    const code = field('code');
-    const boxMessage = field('message');
+    // A Box error object, or from the token endpoint an OAuth 2.0 error.
+    const code = field('code') ?? field('error');
+    const boxMessage = field('message') ?? field('error_description');
     const requestId = field('request_id');
     let message = `box: status ${status}`;
     if (code !== undefined) {

package/dist/cjs/managers/authorization.js

@@ -145,5 +145,20 @@ class AuthorizationManager {
         req = runtime.withFormBody(req, new TextEncoder().encode((0, internal_js_1.formEncode)(form)));
         await this.session.fetch(req);
     }
+    /** Exchange the session's current access token for one limited to `scopes`
+     * and, when given, to one item (`resource`: its API URL, e.g.
+     * `https://api.box.com/2.0/files/123`) or a shared link. The result is a plain
+     * access token with no refresh token: build a client from it with
+     * `auth.developerToken`. */
+    async downscopeToken(scopes, resource, sharedLink) {
+        return this.createOauth2Token({
+            grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+            subject_token: await this.session.accessToken(),
+            subject_token_type: "urn:ietf:params:oauth:token-type:access_token",
+            scope: scopes.join(' '),
+            ...(resource === undefined ? {} : { resource: resource }),
+            ...(sharedLink === undefined ? {} : { box_shared_link: sharedLink }),
+        });
+    }
 }
 exports.AuthorizationManager = AuthorizationManager;

package/dist/cjs/runtime.js

@@ -104,6 +104,20 @@ class Client {
         this.fetchImpl = options.fetch ?? fetch;
         this.defaultHeaders = { ...(options.headers ?? {}) };
     }
+    /** A new client that sends `As-User: userId` with every API request, so Box
+     * acts as that user (an admin, or a service account whose app may "make API
+     * calls using the as-user header"). It shares this client's auth flow and
+     * token cache, `fetch`, base URLs, and retry policy; this client is
+     * unchanged. Token requests never carry the header. */
+    withAsUserHeader(userId) {
+        const headers = Object.fromEntries(Object.entries(this.defaultHeaders).filter(([name]) => name.toLowerCase() !== 'as-user'));
+        return new Client(this.auth, {
+            maxRetries: this.maxRetries,
+            baseUrls: this.baseUrls,
+            fetch: this.fetchImpl,
+            headers: { ...headers, 'As-User': userId },
+        });
+    }
     /** The configured base URL for a D-106 class, without a trailing slash. */
     baseUrl(name) {
         return this.baseUrls[name] ?? '';

package/dist/esm/client.js

@@ -178,10 +178,13 @@ export class Client {
     webhooks;
     workflows;
     zipDownloads;
+    #session;
     /** Build a client for an authentication flow; `options` configures the
-     * runtime session (retries, `fetch`, default headers, base URLs). */
+     * runtime session (retries, `fetch`, default headers, base URLs). An
+     * already configured runtime session is used as is. */
     constructor(auth, options = {}) {
-        const session = new Session(auth, options);
+        const session = auth instanceof Session ? auth : new Session(auth, options);
+        this.#session = session;
         this.ai = new AiManager(session);
         this.aiStudio = new AiStudioManager(session);
         this.appItemAssociations = new AppItemAssociationsManager(session);
@@ -271,4 +274,10 @@ export class Client {
         this.workflows = new WorkflowsManager(session);
         this.zipDownloads = new ZipDownloadsManager(session);
     }
+    /** A new client whose every API call acts as the user `userId` (Box's
+     * `As-User` header). It shares this client's auth and configuration;
+     * this client is unchanged. */
+    withAsUserHeader(userId) {
+        return new Client(this.#session.withAsUserHeader(userId));
+    }
 }

package/dist/esm/errors.js

@@ -51,8 +51,9 @@ export function apiErrorFromResponse(status, body) {
         const value = payload[key];
         return typeof value === 'string' ? value : undefined;
     };
-    const code = field('code');
-    const boxMessage = field('message');
+    // A Box error object, or from the token endpoint an OAuth 2.0 error.
+    const code = field('code') ?? field('error');
+    const boxMessage = field('message') ?? field('error_description');
     const requestId = field('request_id');
     let message = `box: status ${status}`;
     if (code !== undefined) {

package/dist/esm/managers/authorization.js

@@ -109,4 +109,19 @@ export class AuthorizationManager {
         req = runtime.withFormBody(req, new TextEncoder().encode(formEncode(form)));
         await this.session.fetch(req);
     }
+    /** Exchange the session's current access token for one limited to `scopes`
+     * and, when given, to one item (`resource`: its API URL, e.g.
+     * `https://api.box.com/2.0/files/123`) or a shared link. The result is a plain
+     * access token with no refresh token: build a client from it with
+     * `auth.developerToken`. */
+    async downscopeToken(scopes, resource, sharedLink) {
+        return this.createOauth2Token({
+            grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+            subject_token: await this.session.accessToken(),
+            subject_token_type: "urn:ietf:params:oauth:token-type:access_token",
+            scope: scopes.join(' '),
+            ...(resource === undefined ? {} : { resource: resource }),
+            ...(sharedLink === undefined ? {} : { box_shared_link: sharedLink }),
+        });
+    }
 }

package/dist/esm/runtime.js

@@ -69,6 +69,20 @@ export class Client {
         this.fetchImpl = options.fetch ?? fetch;
         this.defaultHeaders = { ...(options.headers ?? {}) };
     }
+    /** A new client that sends `As-User: userId` with every API request, so Box
+     * acts as that user (an admin, or a service account whose app may "make API
+     * calls using the as-user header"). It shares this client's auth flow and
+     * token cache, `fetch`, base URLs, and retry policy; this client is
+     * unchanged. Token requests never carry the header. */
+    withAsUserHeader(userId) {
+        const headers = Object.fromEntries(Object.entries(this.defaultHeaders).filter(([name]) => name.toLowerCase() !== 'as-user'));
+        return new Client(this.auth, {
+            maxRetries: this.maxRetries,
+            baseUrls: this.baseUrls,
+            fetch: this.fetchImpl,
+            headers: { ...headers, 'As-User': userId },
+        });
+    }
     /** The configured base URL for a D-106 class, without a trailing slash. */
     baseUrl(name) {
         return this.baseUrls[name] ?? '';

package/dist/types/client.d.ts

@@ -1,4 +1,4 @@
-import { Auth, ClientOptions } from './runtime.js';
+import { Auth, Client as Session, ClientOptions } from './runtime.js';
 import { AiManager } from './managers/ai.js';
 import { AiStudioManager } from './managers/ai_studio.js';
 import { AppItemAssociationsManager } from './managers/app_item_associations.js';
@@ -89,6 +89,7 @@ import { WorkflowsManager } from './managers/workflows.js';
 import { ZipDownloadsManager } from './managers/zip_downloads.js';
 /** The Box SDK client: one manager per API area over a shared session. */
 export declare class Client {
+    #private;
     readonly ai: AiManager;
     readonly aiStudio: AiStudioManager;
     readonly appItemAssociations: AppItemAssociationsManager;
@@ -178,6 +179,11 @@ export declare class Client {
     readonly workflows: WorkflowsManager;
     readonly zipDownloads: ZipDownloadsManager;
     /** Build a client for an authentication flow; `options` configures the
-     * runtime session (retries, `fetch`, default headers, base URLs). */
-    constructor(auth: Auth, options?: ClientOptions);
+     * runtime session (retries, `fetch`, default headers, base URLs). An
+     * already configured runtime session is used as is. */
+    constructor(auth: Auth | Session, options?: ClientOptions);
+    /** A new client whose every API call acts as the user `userId` (Box's
+     * `As-User` header). It shares this client's auth and configuration;
+     * this client is unchanged. */
+    withAsUserHeader(userId: string): Client;
 }

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

@@ -14,4 +14,10 @@ export declare class AuthorizationManager {
     createOauth2Token(body: models.schemas.PostOAuth2Token): Promise<models.schemas.AccessToken>;
     createOauth2TokenRefresh(body: models.schemas.PostOAuth2TokenRefreshAccessToken): Promise<models.schemas.AccessToken>;
     revokeOauth2(body: models.schemas.PostOAuth2Revoke): Promise<void>;
+    /** Exchange the session's current access token for one limited to `scopes`
+     * and, when given, to one item (`resource`: its API URL, e.g.
+     * `https://api.box.com/2.0/files/123`) or a shared link. The result is a plain
+     * access token with no refresh token: build a client from it with
+     * `auth.developerToken`. */
+    downscopeToken(scopes: readonly string[], resource?: string, sharedLink?: string): Promise<models.schemas.AccessToken>;
 }

package/dist/types/runtime.d.ts

@@ -53,6 +53,12 @@ export declare class Client {
     private readonly fetchImpl;
     private readonly defaultHeaders;
     constructor(auth: Auth, options?: ClientOptions);
+    /** A new client that sends `As-User: userId` with every API request, so Box
+     * acts as that user (an admin, or a service account whose app may "make API
+     * calls using the as-user header"). It shares this client's auth flow and
+     * token cache, `fetch`, base URLs, and retry policy; this client is
+     * unchanged. Token requests never carry the header. */
+    withAsUserHeader(userId: string): Client;
     /** The configured base URL for a D-106 class, without a trailing slash. */
     baseUrl(name: string): string;
     /** A valid access token for the configured auth flow. The `signal` is

package/docs/auth.md

@@ -23,9 +23,9 @@ to act as a managed user:
 ```ts
 import { auth } from '@unofficialbox/box-open-sdk';
 const client = new Client(auth.clientCredentials({
-clientId: 'CLIENT_ID',
-clientSecret: 'CLIENT_SECRET',
-enterpriseId: 'ENTERPRISE_ID',
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+  enterpriseId: 'ENTERPRISE_ID',
 }));
 ```
 
@@ -38,11 +38,11 @@ imported from the runtime's `./jwt` entry point and returns a promise:
 ```ts
 import { jwtAuth } from '@unofficialbox/box-open-sdk/jwt';
 const auth = await jwtAuth({
-clientId: 'CLIENT_ID',
-clientSecret: 'CLIENT_SECRET',
-publicKeyId: 'PUBLIC_KEY_ID',
-privateKeyPem: privateKeyPem, // optionally encrypted; set passphrase
-enterpriseId: 'ENTERPRISE_ID',
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+  publicKeyId: 'PUBLIC_KEY_ID',
+  privateKeyPem: privateKeyPem, // optionally encrypted; set passphrase
+  enterpriseId: 'ENTERPRISE_ID',
 });
 const client = new Client(auth);
 ```
@@ -58,3 +58,30 @@ import { auth } from '@unofficialbox/box-open-sdk';
 const source = auth.oauth({ clientId: 'CLIENT_ID', clientSecret: 'CLIENT_SECRET' }, storedRefreshToken);
 const client = new Client(source);
 ```
+
+## Acting as another user
+
+An admin, or a service account whose app may *make API calls using the as-user
+header*, can act as another user. `withAsUserHeader` returns a new client whose
+every call sends Box's `As-User` header; it shares the original's auth (and
+token cache) and configuration, and the original is unchanged:
+
+```ts
+const userClient = client.withAsUserHeader('USER_ID');
+const me = await userClient.users.getMe(); // the user USER_ID
+```
+
+## Downscoping a token
+
+Exchange the session's access token for one limited to `scopes` and,
+optionally, to one item (its API URL) or shared link — e.g. to hand a
+browser-side preview a narrow token. The result has no refresh token; build
+a client from it as a developer token:
+
+```ts
+const down = await client.authorization.downscopeToken(
+  ['item_preview'],
+  'https://api.box.com/2.0/files/123',
+);
+const preview = new Client(auth.developerToken(down.access_token!));
+```

package/docs/pagination.md

@@ -7,7 +7,7 @@ that yields one entry at a time, threading the cursor for you — the list metho
 
 ```ts
 for await (const item of client.folders.listItems(folderId)) {
-// use item
+  // use item
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Box API client for TypeScript (open source, community, punk rock) — typed models, async managers, and a fetch runtime with retry, backoff, and token refresh.",
   "keywords": ["box", "box-api", "sdk", "api-client", "typescript", "unofficial"],
   "license": "MIT",