This is the central entrypoint for all SDK interaction. The BoxClient houses all the API endpoints divided across resource managers.
You can make custom HTTP requests using the client.makeRequest() method.
This method allows you to make any HTTP request to the Box API. It will automatically use authentication and
network configuration settings from the client.
The method accepts a FetchOptions object as an argument and returns a FetchResponse object.
The following example demonstrates how to make a custom POST request to create a new folder in the root folder.
const response: FetchResponse = await client.makeRequest(
{ method: "POST",
url: "https://api.box.com/2.0/folders",
data: {name: newFolderName, parent: {id: "0"}}
} satisfies FetchOptionsInput
);
console.log('Received status code: ', response.status)
console.log('Created folder name: ', getSdValueByKey(response.content, "name"))
The following example demonstrates how to make a custom multipart request that uploads a file to a folder.
const multipartAttributes = {name: "newFileName", parent: { id: "0" }};
const uploadFileResponse: FetchResponse = await client.makeRequest({ method: "POST", url: "https://upload.box.com/api/2.0/files/content", contentType: "multipart/form-data", multipartData: [{ partName: "attributes", data: multipartAttributes } satisfies MultipartItem, { partName: "file", fileStream: fileContentStream } satisfies MultipartItem] } satisfies FetchOptionsInput);
console.log('Received status code: ', response.status)
The following example demonstrates how to make a custom request that expects a binary response.
It is required to specify the responseFormat parameter in the FetchOptions object to “binary”.
const response: FetchResponse = await client.makeRequest({ method: "GET", url: "".concat("https://api.box.com/2.0/files/", uploadedFile.id, "/content") as string, responseFormat: "binary" as ResponseFormat } satisfies FetchOptionsInput);
console.log('Received status code: ', response.status)
const fileWriteStream = fs.createWriteStream('file.pdf');
response.content.pipe(fileWriteStream);
BoxClient provides a convenient methods, which allow passing additional headers, which will be included in every API call made by the client.
The As-User header is used by enterprise admins to make API calls on behalf of their enterprise’s users. This requires the API request to pass an As-User: USER-ID header. For more details see the documentation on As-User.
The following example assume that the client has been instantiated with an access token belonging to an admin-level user or Service Account with appropriate privileges to make As-User calls.
Calling the client.withAsUserHeader() method creates a new client to impersonate user with the provided ID.
All calls made with the new client will be made in context of the impersonated user, leaving the original client unmodified.
const userClient = client.withAsUserHeader('1234567');
If you are making administrative API calls (that is, your application has “Manage an Enterprise” scope, and the user signing in is a co-admin with the correct “Edit settings for your company” permission) then you can suppress both email and webhook notifications. This can be used, for example, for a virus-scanning tool to download copies of everyone’s files in an enterprise, without every collaborator on the file getting an email. All actions will still appear in users’ updates feed and audit logs.
Note: This functionality is only available for approved applications.
Calling the client.withSuppressedNotifications() method creates a new client.
For all calls made with the new client the notifications will be suppressed.
const newClient = client.withSuppressedNotifications();
You can also specify the custom set of headers, which will be included in every API call made by client.
Calling the client.withExtraHeaders() method creates a new client, leaving the original client unmodified.
const newClient = client.withExtraHeaders({ ['customHeader']: 'customValue' });
You can also specify the custom base URLs, which will be used for API calls made by client.
Calling the client.withCustomBaseUrls() method creates a new client, leaving the original client unmodified.
const newClient = client.withCustomBaseUrls({
baseUrl: 'https://api.box.com',
uploadUrl: 'https://upload.box.com/api',
oauth2Url: 'https://account.box.com/api/oauth2',
});
You can also specify the custom agent options, which will be used for API calls made by client.
Calling the client.withCustomAgentOptions() method creates a new client, leaving the original client unmodified.
const options: AgentOptions = {};
const newClient = client.withCustomAgentOptions(options);
You can specify custom interceptors - methods that will be called just before making a request and right after receiving a response from the server. Using these function allows you to modify the request payload and response. Interceptor interface accepts two methods with the following signatures:
beforeRequest(options: FetchOptions): FetchOptions;
afterRequest(response: FetchResponse): FetchResponse;
You can apply more than one interceptor to the client by passing a list of interceptors to apply.
Calling the client.withInterceptors() method creates a new client, leaving the original client unmodified.
function beforeRequest(options: FetchOptions): FetchOptions {
return {
method: options.method,
headers: options.headers,
params: { ...options.params, ...{ ['fields']: 'role' } },
data: options.data,
fileStream: options.fileStream,
multipartData: options.multipartData,
contentType: options.contentType,
responseFormat: options.responseFormat,
auth: options.auth,
networkSession: options.networkSession,
cancellationToken: options.cancellationToken,
};
}
function emptyAfterRequest(response: FetchResponse): FetchResponse {
return response;
}
const clientWithInterceptor: BoxClient = client.withInterceptors([
{
beforeRequest: beforeRequest,
afterRequest: emptyAfterRequest,
},
]);
In order to configure timeout for API calls, call client.withTimeouts(config) to create a new client with timeout settings, leaving the original client unmodified.
timeoutMs is in milliseconds and is applied to each request attempt.
const newClient = client.withTimeouts({
timeoutMs: 30000,
});
If timeoutMs is not provided or is less than or equal to 0, no SDK timeout is applied.
In order to use a proxy for API calls, calling the client.withProxy(proxyConfig) method creates a new client, leaving the original client unmodified, with the username and password being optional.
If both custom agent options and proxy are provided, the proxy will take precedence.
Note: We are only supporting http/s proxies with basic authentication. NTLM and other authentication methods are not supported.
newClient = client.withProxy({
url: 'http://127.0.0.1:1234/',
username: 'user',
password: 'password',
});