feat: Expose method for making custom HTTP requests, convert FetchOptions into a class (box/box-codegen#610) (#431)

Author: box-sdk-build

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "1c0a1c0", "specHash": "544d370", "version": "1.7.0" }
+{ "engineHash": "35ca680", "specHash": "544d370", "version": "1.7.0" }

docs/client.md

@@ -6,7 +6,10 @@ divided across resource managers.
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
-- [Client](#client)
+- [Make custom HTTP request](#make-custom-http-request)
+  - [JSON request](#json-request)
+  - [Multi-part request](#multi-part-request)
+  - [Binary response](#binary-response)
 - [Additional headers](#additional-headers)
   - [As-User header](#as-user-header)
   - [Suppress notifications](#suppress-notifications)
@@ -18,6 +21,51 @@ divided across resource managers.
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
+# Make custom HTTP request
+
+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.
+
+## JSON request
+
+The following example demonstrates how to make a custom POST request to create a new folder in the root folder.
+
+```js
+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"))
+```
+
+## Multi-part request
+
+The following example demonstrates how to make a custom multipart request that uploads a file to a folder.
+
+```js
+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)
+```
+
+## Binary response
+
+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".
+
+```js
+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);
+```
+
 # Additional headers
 
 BoxClient provides a convenient methods, which allow passing additional headers, which will be included

src/client.generated.ts

@@ -1,5 +1,6 @@
 import { serializeBaseUrls } from './networking/baseUrls.generated.js';
 import { deserializeBaseUrls } from './networking/baseUrls.generated.js';
+import { FetchOptionsInput } from './networking/fetchOptions.generated.js';
 import { BaseUrlsInput } from './networking/baseUrls.generated.js';
 import { AuthorizationManager } from './managers/authorization.generated.js';
 import { FilesManager } from './managers/files.generated.js';
@@ -77,6 +78,9 @@ import { BaseUrls } from './networking/baseUrls.generated.js';
 import { ProxyConfig } from './networking/proxyConfig.generated.js';
 import { AgentOptions } from './internal/utils.js';
 import { Interceptor } from './networking/interceptors.generated.js';
+import { FetchOptions } from './networking/fetchOptions.generated.js';
+import { FetchResponse } from './networking/fetchResponse.generated.js';
+import { fetch } from './networking/fetch.js';
 import { SerializedData } from './serialization/json.js';
 import { sdIsEmpty } from './serialization/json.js';
 import { sdIsBoolean } from './serialization/json.js';
@@ -233,6 +237,7 @@ export class BoxClient {
       | 'integrationMappings'
       | 'ai'
       | 'networkSession'
+      | 'makeRequest'
       | 'withAsUserHeader'
       | 'withSuppressedNotifications'
       | 'withExtraHeaders'
@@ -536,6 +541,49 @@ export class BoxClient {
       networkSession: this.networkSession,
     });
   }
+  /**
+   * Make a custom http request using the client authentication and network session.
+   * @param {FetchOptionsInput} fetchOptionsInput Options to be passed to the fetch call
+   * @returns {Promise<FetchResponse>}
+   */
+  async makeRequest(
+    fetchOptionsInput: FetchOptionsInput,
+  ): Promise<FetchResponse> {
+    const fetchOptions: FetchOptions = new FetchOptions({
+      url: fetchOptionsInput.url,
+      method: fetchOptionsInput.method,
+      params: fetchOptionsInput.params,
+      headers: fetchOptionsInput.headers,
+      data: fetchOptionsInput.data,
+      fileStream: fetchOptionsInput.fileStream,
+      multipartData: fetchOptionsInput.multipartData,
+      contentType: fetchOptionsInput.contentType,
+      responseFormat: fetchOptionsInput.responseFormat,
+      auth: fetchOptionsInput.auth,
+      networkSession: fetchOptionsInput.networkSession,
+      cancellationToken: fetchOptionsInput.cancellationToken,
+    });
+    const auth: Authentication =
+      fetchOptions.auth == void 0 ? this.auth : fetchOptions.auth!;
+    const networkSession: NetworkSession =
+      fetchOptions.networkSession == void 0
+        ? this.networkSession
+        : fetchOptions.networkSession!;
+    const enrichedFetchOptions: FetchOptions = new FetchOptions({
+      auth: auth,
+      networkSession: networkSession,
+      url: fetchOptions.url,
+      method: fetchOptions.method,
+      params: fetchOptions.params,
+      headers: fetchOptions.headers,
+      data: fetchOptions.data,
+      fileStream: fetchOptions.fileStream,
+      multipartData: fetchOptions.multipartData,
+      contentType: fetchOptions.contentType,
+      responseFormat: fetchOptions.responseFormat,
+    });
+    return (await fetch(enrichedFetchOptions)) as FetchResponse;
+  }
   /**
    * Create 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.
    * @param {string} userId ID of an user to impersonate

src/internal/utils.ts

@@ -2,6 +2,7 @@ import { Buffer } from 'buffer';
 import type { Readable } from 'stream';
 import { v4 as uuidv4 } from 'uuid';
 import { SignJWT, importPKCS8 } from 'jose';
+import { sdIsMap, SerializedData } from '../serialization/json';
 
 export function isBrowser() {
   return (

src/managers/ai.generated.ts

@@ -16,6 +16,7 @@ import { serializeAiExtractResponse } from '../schemas/aiExtractResponse.generat
 import { deserializeAiExtractResponse } from '../schemas/aiExtractResponse.generated.js';
 import { serializeAiExtractStructured } from '../schemas/aiExtractStructured.generated.js';
 import { deserializeAiExtractStructured } from '../schemas/aiExtractStructured.generated.js';
+import { ResponseFormat } from '../networking/fetchOptions.generated.js';
 import { AiResponseFull } from '../schemas/aiResponseFull.generated.js';
 import { ClientError } from '../schemas/clientError.generated.js';
 import { AiAsk } from '../schemas/aiAsk.generated.js';
@@ -31,8 +32,8 @@ import { prepareParams } from '../internal/utils.js';
 import { toString } from '../internal/utils.js';
 import { ByteStream } from '../internal/utils.js';
 import { CancellationToken } from '../internal/utils.js';
-import { FetchOptions } from '../networking/fetch.js';
-import { FetchResponse } from '../networking/fetch.js';
+import { FetchOptions } from '../networking/fetchOptions.generated.js';
+import { FetchResponse } from '../networking/fetchResponse.generated.js';
 import { fetch } from '../networking/fetch.js';
 import { SerializedData } from '../serialization/json.js';
 import { sdToJson } from '../serialization/json.js';
@@ -331,23 +332,25 @@ export class AiManager {
     const headersMap: {
       readonly [key: string]: string;
     } = prepareParams({ ...{}, ...headers.extraHeaders });
-    const response: FetchResponse = (await fetch({
-      url: ''.concat(
-        this.networkSession.baseUrls.baseUrl,
-        '/2.0/ai/ask',
-      ) as string,
-      method: 'POST',
-      headers: headersMap,
-      data: serializeAiAsk(requestBody),
-      contentType: 'application/json',
-      responseFormat: 'json',
-      auth: this.auth,
-      networkSession: this.networkSession,
-      cancellationToken: cancellationToken,
-    } satisfies FetchOptions)) as FetchResponse;
+    const response: FetchResponse = (await fetch(
+      new FetchOptions({
+        url: ''.concat(
+          this.networkSession.baseUrls.baseUrl,
+          '/2.0/ai/ask',
+        ) as string,
+        method: 'POST',
+        headers: headersMap,
+        data: serializeAiAsk(requestBody),
+        contentType: 'application/json',
+        responseFormat: 'json' as ResponseFormat,
+        auth: this.auth,
+        networkSession: this.networkSession,
+        cancellationToken: cancellationToken,
+      }),
+    )) as FetchResponse;
     return {
-      ...deserializeAiResponseFull(response.data),
-      rawData: response.data,
+      ...deserializeAiResponseFull(response.data!),
+      rawData: response.data!,
     };
   }
   /**
@@ -369,23 +372,25 @@ export class AiManager {
     const headersMap: {
       readonly [key: string]: string;
     } = prepareParams({ ...{}, ...headers.extraHeaders });
-    const response: FetchResponse = (await fetch({
-      url: ''.concat(
-        this.networkSession.baseUrls.baseUrl,
-        '/2.0/ai/text_gen',
-      ) as string,
-      method: 'POST',
-      headers: headersMap,
-      data: serializeAiTextGen(requestBody),
-      contentType: 'application/json',
-      responseFormat: 'json',
-      auth: this.auth,
-      networkSession: this.networkSession,
-      cancellationToken: cancellationToken,
-    } satisfies FetchOptions)) as FetchResponse;
+    const response: FetchResponse = (await fetch(
+      new FetchOptions({
+        url: ''.concat(
+          this.networkSession.baseUrls.baseUrl,
+          '/2.0/ai/text_gen',
+        ) as string,
+        method: 'POST',
+        headers: headersMap,
+        data: serializeAiTextGen(requestBody),
+        contentType: 'application/json',
+        responseFormat: 'json' as ResponseFormat,
+        auth: this.auth,
+        networkSession: this.networkSession,
+        cancellationToken: cancellationToken,
+      }),
+    )) as FetchResponse;
     return {
-      ...deserializeAiResponse(response.data),
-      rawData: response.data,
+      ...deserializeAiResponse(response.data!),
+      rawData: response.data!,
     };
   }
   /**
@@ -415,24 +420,26 @@ export class AiManager {
     const headersMap: {
       readonly [key: string]: string;
     } = prepareParams({ ...{}, ...headers.extraHeaders });
-    const response: FetchResponse = (await fetch({
-      url: ''.concat(
-        this.networkSession.baseUrls.baseUrl,
-        '/2.0/ai_agent_default',
-      ) as string,
-      method: 'GET',
-      params: queryParamsMap,
-      headers: headersMap,
-      responseFormat: 'json',
-      auth: this.auth,
-      networkSession: this.networkSession,
-      cancellationToken: cancellationToken,
-    } satisfies FetchOptions)) as FetchResponse;
+    const response: FetchResponse = (await fetch(
+      new FetchOptions({
+        url: ''.concat(
+          this.networkSession.baseUrls.baseUrl,
+          '/2.0/ai_agent_default',
+        ) as string,
+        method: 'GET',
+        params: queryParamsMap,
+        headers: headersMap,
+        responseFormat: 'json' as ResponseFormat,
+        auth: this.auth,
+        networkSession: this.networkSession,
+        cancellationToken: cancellationToken,
+      }),
+    )) as FetchResponse;
     return {
       ...deserializeAiAgentAskOrAiAgentExtractOrAiAgentExtractStructuredOrAiAgentTextGen(
-        response.data,
+        response.data!,
       ),
-      rawData: response.data,
+      rawData: response.data!,
     };
   }
   /**
@@ -455,23 +462,25 @@ export class AiManager {
     const headersMap: {
       readonly [key: string]: string;
     } = prepareParams({ ...{}, ...headers.extraHeaders });
-    const response: FetchResponse = (await fetch({
-      url: ''.concat(
-        this.networkSession.baseUrls.baseUrl,
-        '/2.0/ai/extract',
-      ) as string,
-      method: 'POST',
-      headers: headersMap,
-      data: serializeAiExtract(requestBody),
-      contentType: 'application/json',
-      responseFormat: 'json',
-      auth: this.auth,
-      networkSession: this.networkSession,
-      cancellationToken: cancellationToken,
-    } satisfies FetchOptions)) as FetchResponse;
+    const response: FetchResponse = (await fetch(
+      new FetchOptions({
+        url: ''.concat(
+          this.networkSession.baseUrls.baseUrl,
+          '/2.0/ai/extract',
+        ) as string,
+        method: 'POST',
+        headers: headersMap,
+        data: serializeAiExtract(requestBody),
+        contentType: 'application/json',
+        responseFormat: 'json' as ResponseFormat,
+        auth: this.auth,
+        networkSession: this.networkSession,
+        cancellationToken: cancellationToken,
+      }),
+    )) as FetchResponse;
     return {
-      ...deserializeAiResponse(response.data),
-      rawData: response.data,
+      ...deserializeAiResponse(response.data!),
+      rawData: response.data!,
     };
   }
   /**
@@ -497,23 +506,25 @@ export class AiManager {
     const headersMap: {
       readonly [key: string]: string;
     } = prepareParams({ ...{}, ...headers.extraHeaders });
-    const response: FetchResponse = (await fetch({
-      url: ''.concat(
-        this.networkSession.baseUrls.baseUrl,
-        '/2.0/ai/extract_structured',
-      ) as string,
-      method: 'POST',
-      headers: headersMap,
-      data: serializeAiExtractStructured(requestBody),
-      contentType: 'application/json',
-      responseFormat: 'json',
-      auth: this.auth,
-      networkSession: this.networkSession,
-      cancellationToken: cancellationToken,
-    } satisfies FetchOptions)) as FetchResponse;
+    const response: FetchResponse = (await fetch(
+      new FetchOptions({
+        url: ''.concat(
+          this.networkSession.baseUrls.baseUrl,
+          '/2.0/ai/extract_structured',
+        ) as string,
+        method: 'POST',
+        headers: headersMap,
+        data: serializeAiExtractStructured(requestBody),
+        contentType: 'application/json',
+        responseFormat: 'json' as ResponseFormat,
+        auth: this.auth,
+        networkSession: this.networkSession,
+        cancellationToken: cancellationToken,
+      }),
+    )) as FetchResponse;
     return {
-      ...deserializeAiExtractResponse(response.data),
-      rawData: response.data,
+      ...deserializeAiExtractResponse(response.data!),
+      rawData: response.data!,
     };
   }
 }