docs: External User Deletion API (box/box-openapi#542)

.codegen.json

@@ -1 +1 @@
-{ "engineHash": "41bba7c", "specHash": "5bf3652", "version": "1.17.1" }
+{ "engineHash": "41bba7c", "specHash": "a99f38b", "version": "1.17.1" }

docs/README.md

@@ -23,6 +23,7 @@ the SDK are available by topic:
 - [Downloads](downloads.md)
 - [Email aliases](emailAliases.md)
 - [Events](events.md)
+- [External users](externalUsers.md)
 - [File classifications](fileClassifications.md)
 - [File metadata](fileMetadata.md)
 - [File requests](fileRequests.md)

docs/externalUsers.md

@@ -0,0 +1,25 @@
+# ExternalUsersManager
+
+- [Submit job to delete external users](#submit-job-to-delete-external-users)
+
+## Submit job to delete external users
+
+Delete external users from current user enterprise. This will remove each
+external user from all invited collaborations within the current enterprise.
+
+This operation is performed by calling function `createExternalUserSubmitDeleteJobV2025R0`.
+
+See the endpoint docs at
+[API Reference](https://developer.box.com/reference/v2025.0/post-external-users-submit-delete-job/).
+
+_Currently we don't have an example for calling `createExternalUserSubmitDeleteJobV2025R0` in integration tests_
+
+### Arguments
+
+- requestBody `ExternalUsersSubmitDeleteJobRequestV2025R0`
+  - Request body of createExternalUserSubmitDeleteJobV2025R0 method
+- optionalsInput `CreateExternalUserSubmitDeleteJobV2025R0OptionalsInput`
+
+### Returns
+
+This function returns a value of type `ExternalUsersSubmitDeleteJobResponseV2025R0`.

src/client.generated.ts

@@ -81,6 +81,7 @@ import { HubCollaborationsManager } from './managers/hubCollaborations.generated
 import { HubItemsManager } from './managers/hubItems.generated.js';
 import { ShieldListsManager } from './managers/shieldLists.generated.js';
 import { ArchivesManager } from './managers/archives.generated.js';
+import { ExternalUsersManager } from './managers/externalUsers.generated.js';
 import { Authentication } from './networking/auth.generated.js';
 import { NetworkSession } from './networking/network.generated.js';
 import { BoxSdkError } from './box/errors.js';
@@ -181,6 +182,7 @@ export class BoxClient {
   readonly hubItems: HubItemsManager;
   readonly shieldLists: ShieldListsManager;
   readonly archives: ArchivesManager;
+  readonly externalUsers: ExternalUsersManager;
   constructor(
     fields: Omit<
       BoxClient,
@@ -263,6 +265,7 @@ export class BoxClient {
       | 'hubItems'
       | 'shieldLists'
       | 'archives'
+      | 'externalUsers'
       | 'networkSession'
       | 'makeRequest'
       | 'withAsUserHeader'
@@ -603,6 +606,10 @@ export class BoxClient {
       auth: this.auth,
       networkSession: this.networkSession,
     });
+    this.externalUsers = new ExternalUsersManager({
+      auth: this.auth,
+      networkSession: this.networkSession,
+    });
   }
   /**
    * Make a custom http request using the client authentication and network session.

src/managers/externalUsers.generated.ts

@@ -0,0 +1,170 @@
+import { serializeExternalUsersSubmitDeleteJobResponseV2025R0 } from '../schemas/v2025R0/externalUsersSubmitDeleteJobResponseV2025R0.generated.js';
+import { deserializeExternalUsersSubmitDeleteJobResponseV2025R0 } from '../schemas/v2025R0/externalUsersSubmitDeleteJobResponseV2025R0.generated.js';
+import { serializeClientErrorV2025R0 } from '../schemas/v2025R0/clientErrorV2025R0.generated.js';
+import { deserializeClientErrorV2025R0 } from '../schemas/v2025R0/clientErrorV2025R0.generated.js';
+import { serializeBoxVersionHeaderV2025R0 } from '../parameters/v2025R0/boxVersionHeaderV2025R0.generated.js';
+import { deserializeBoxVersionHeaderV2025R0 } from '../parameters/v2025R0/boxVersionHeaderV2025R0.generated.js';
+import { serializeExternalUsersSubmitDeleteJobRequestV2025R0 } from '../schemas/v2025R0/externalUsersSubmitDeleteJobRequestV2025R0.generated.js';
+import { deserializeExternalUsersSubmitDeleteJobRequestV2025R0 } from '../schemas/v2025R0/externalUsersSubmitDeleteJobRequestV2025R0.generated.js';
+import { ResponseFormat } from '../networking/fetchOptions.generated.js';
+import { ExternalUsersSubmitDeleteJobResponseV2025R0 } from '../schemas/v2025R0/externalUsersSubmitDeleteJobResponseV2025R0.generated.js';
+import { ClientErrorV2025R0 } from '../schemas/v2025R0/clientErrorV2025R0.generated.js';
+import { BoxVersionHeaderV2025R0 } from '../parameters/v2025R0/boxVersionHeaderV2025R0.generated.js';
+import { ExternalUsersSubmitDeleteJobRequestV2025R0 } from '../schemas/v2025R0/externalUsersSubmitDeleteJobRequestV2025R0.generated.js';
+import { BoxSdkError } from '../box/errors.js';
+import { Authentication } from '../networking/auth.generated.js';
+import { NetworkSession } from '../networking/network.generated.js';
+import { FetchOptions } from '../networking/fetchOptions.generated.js';
+import { FetchResponse } from '../networking/fetchResponse.generated.js';
+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 { sdToJson } from '../serialization/json.js';
+import { SerializedData } from '../serialization/json.js';
+import { sdIsEmpty } from '../serialization/json.js';
+import { sdIsBoolean } from '../serialization/json.js';
+import { sdIsNumber } from '../serialization/json.js';
+import { sdIsString } from '../serialization/json.js';
+import { sdIsList } from '../serialization/json.js';
+import { sdIsMap } from '../serialization/json.js';
+export class CreateExternalUserSubmitDeleteJobV2025R0Optionals {
+  readonly headers: CreateExternalUserSubmitDeleteJobV2025R0Headers =
+    new CreateExternalUserSubmitDeleteJobV2025R0Headers({});
+  readonly cancellationToken?: CancellationToken = void 0;
+  constructor(
+    fields: Omit<
+      CreateExternalUserSubmitDeleteJobV2025R0Optionals,
+      'headers' | 'cancellationToken'
+    > &
+      Partial<
+        Pick<
+          CreateExternalUserSubmitDeleteJobV2025R0Optionals,
+          'headers' | 'cancellationToken'
+        >
+      >,
+  ) {
+    if (fields.headers !== undefined) {
+      this.headers = fields.headers;
+    }
+    if (fields.cancellationToken !== undefined) {
+      this.cancellationToken = fields.cancellationToken;
+    }
+  }
+}
+export interface CreateExternalUserSubmitDeleteJobV2025R0OptionalsInput {
+  readonly headers?: CreateExternalUserSubmitDeleteJobV2025R0Headers;
+  readonly cancellationToken?: undefined | CancellationToken;
+}
+export class CreateExternalUserSubmitDeleteJobV2025R0Headers {
+  /**
+   * Version header. */
+  readonly boxVersion: BoxVersionHeaderV2025R0 =
+    '2025.0' as BoxVersionHeaderV2025R0;
+  /**
+   * Extra headers that will be included in the HTTP request. */
+  readonly extraHeaders?: {
+    readonly [key: string]: undefined | string;
+  } = {};
+  constructor(
+    fields: Omit<
+      CreateExternalUserSubmitDeleteJobV2025R0Headers,
+      'boxVersion' | 'extraHeaders'
+    > &
+      Partial<
+        Pick<
+          CreateExternalUserSubmitDeleteJobV2025R0Headers,
+          'boxVersion' | 'extraHeaders'
+        >
+      >,
+  ) {
+    if (fields.boxVersion !== undefined) {
+      this.boxVersion = fields.boxVersion;
+    }
+    if (fields.extraHeaders !== undefined) {
+      this.extraHeaders = fields.extraHeaders;
+    }
+  }
+}
+export interface CreateExternalUserSubmitDeleteJobV2025R0HeadersInput {
+  /**
+   * Version header. */
+  readonly boxVersion?: BoxVersionHeaderV2025R0;
+  /**
+   * Extra headers that will be included in the HTTP request. */
+  readonly extraHeaders?:
+    | undefined
+    | {
+        readonly [key: string]: undefined | string;
+      };
+}
+export class ExternalUsersManager {
+  readonly auth?: Authentication;
+  readonly networkSession: NetworkSession = new NetworkSession({});
+  constructor(
+    fields: Omit<
+      ExternalUsersManager,
+      'networkSession' | 'createExternalUserSubmitDeleteJobV2025R0'
+    > &
+      Partial<Pick<ExternalUsersManager, 'networkSession'>>,
+  ) {
+    if (fields.auth !== undefined) {
+      this.auth = fields.auth;
+    }
+    if (fields.networkSession !== undefined) {
+      this.networkSession = fields.networkSession;
+    }
+  }
+  /**
+   * Delete external users from current user enterprise. This will remove each
+   * external user from all invited collaborations within the current enterprise.
+   * @param {ExternalUsersSubmitDeleteJobRequestV2025R0} requestBody Request body of createExternalUserSubmitDeleteJobV2025R0 method
+   * @param {CreateExternalUserSubmitDeleteJobV2025R0OptionalsInput} optionalsInput
+   * @returns {Promise<ExternalUsersSubmitDeleteJobResponseV2025R0>}
+   */
+  async createExternalUserSubmitDeleteJobV2025R0(
+    requestBody: ExternalUsersSubmitDeleteJobRequestV2025R0,
+    optionalsInput: CreateExternalUserSubmitDeleteJobV2025R0OptionalsInput = {},
+  ): Promise<ExternalUsersSubmitDeleteJobResponseV2025R0> {
+    const optionals: CreateExternalUserSubmitDeleteJobV2025R0Optionals =
+      new CreateExternalUserSubmitDeleteJobV2025R0Optionals({
+        headers: optionalsInput.headers,
+        cancellationToken: optionalsInput.cancellationToken,
+      });
+    const headers: any = optionals.headers;
+    const cancellationToken: any = optionals.cancellationToken;
+    const headersMap: {
+      readonly [key: string]: string;
+    } = prepareParams({
+      ...{ ['box-version']: toString(headers.boxVersion) as string },
+      ...headers.extraHeaders,
+    });
+    const response: FetchResponse =
+      await this.networkSession.networkClient.fetch(
+        new FetchOptions({
+          url: ''.concat(
+            this.networkSession.baseUrls.baseUrl,
+            '/2.0/external_users/submit_delete_job',
+          ) as string,
+          method: 'POST',
+          headers: headersMap,
+          data: serializeExternalUsersSubmitDeleteJobRequestV2025R0(
+            requestBody,
+          ),
+          contentType: 'application/json',
+          responseFormat: 'json' as ResponseFormat,
+          auth: this.auth,
+          networkSession: this.networkSession,
+          cancellationToken: cancellationToken,
+        }),
+      );
+    return {
+      ...deserializeExternalUsersSubmitDeleteJobResponseV2025R0(response.data!),
+      rawData: response.data!,
+    };
+  }
+}
+export interface ExternalUsersManagerInput {
+  readonly auth?: Authentication;
+  readonly networkSession?: NetworkSession;
+}

src/schemas/v2025R0/externalUserDeletionResultV2025R0.generated.ts

@@ -0,0 +1,76 @@
+import { BoxSdkError } from '../../box/errors.js';
+import { SerializedData } from '../../serialization/json.js';
+import { sdIsEmpty } from '../../serialization/json.js';
+import { sdIsBoolean } from '../../serialization/json.js';
+import { sdIsNumber } from '../../serialization/json.js';
+import { sdIsString } from '../../serialization/json.js';
+import { sdIsList } from '../../serialization/json.js';
+import { sdIsMap } from '../../serialization/json.js';
+export interface ExternalUserDeletionResultV2025R0 {
+  /**
+   * The ID of the external user. */
+  readonly userId: string;
+  /**
+   * HTTP status code for a specific user's deletion request. */
+  readonly status: number;
+  /**
+   * Deletion request status details. */
+  readonly detail?: string;
+  readonly rawData?: SerializedData;
+}
+export function serializeExternalUserDeletionResultV2025R0(
+  val: ExternalUserDeletionResultV2025R0,
+): SerializedData {
+  return {
+    ['user_id']: val.userId,
+    ['status']: val.status,
+    ['detail']: val.detail,
+  };
+}
+export function deserializeExternalUserDeletionResultV2025R0(
+  val: SerializedData,
+): ExternalUserDeletionResultV2025R0 {
+  if (!sdIsMap(val)) {
+    throw new BoxSdkError({
+      message: 'Expecting a map for "ExternalUserDeletionResultV2025R0"',
+    });
+  }
+  if (val.user_id == void 0) {
+    throw new BoxSdkError({
+      message:
+        'Expecting "user_id" of type "ExternalUserDeletionResultV2025R0" to be defined',
+    });
+  }
+  if (!sdIsString(val.user_id)) {
+    throw new BoxSdkError({
+      message:
+        'Expecting string for "user_id" of type "ExternalUserDeletionResultV2025R0"',
+    });
+  }
+  const userId: string = val.user_id;
+  if (val.status == void 0) {
+    throw new BoxSdkError({
+      message:
+        'Expecting "status" of type "ExternalUserDeletionResultV2025R0" to be defined',
+    });
+  }
+  if (!sdIsNumber(val.status)) {
+    throw new BoxSdkError({
+      message:
+        'Expecting number for "status" of type "ExternalUserDeletionResultV2025R0"',
+    });
+  }
+  const status: number = val.status;
+  if (!(val.detail == void 0) && !sdIsString(val.detail)) {
+    throw new BoxSdkError({
+      message:
+        'Expecting string for "detail" of type "ExternalUserDeletionResultV2025R0"',
+    });
+  }
+  const detail: undefined | string = val.detail == void 0 ? void 0 : val.detail;
+  return {
+    userId: userId,
+    status: status,
+    detail: detail,
+  } satisfies ExternalUserDeletionResultV2025R0;
+}

src/schemas/v2025R0/externalUsersSubmitDeleteJobRequestV2025R0.generated.ts

@@ -0,0 +1,62 @@
+import { serializeUserReferenceV2025R0 } from './userReferenceV2025R0.generated.js';
+import { deserializeUserReferenceV2025R0 } from './userReferenceV2025R0.generated.js';
+import { UserReferenceV2025R0 } from './userReferenceV2025R0.generated.js';
+import { BoxSdkError } from '../../box/errors.js';
+import { SerializedData } from '../../serialization/json.js';
+import { sdIsEmpty } from '../../serialization/json.js';
+import { sdIsBoolean } from '../../serialization/json.js';
+import { sdIsNumber } from '../../serialization/json.js';
+import { sdIsString } from '../../serialization/json.js';
+import { sdIsList } from '../../serialization/json.js';
+import { sdIsMap } from '../../serialization/json.js';
+export interface ExternalUsersSubmitDeleteJobRequestV2025R0 {
+  /**
+   * List of external users to delete. */
+  readonly externalUsers: readonly UserReferenceV2025R0[];
+  readonly rawData?: SerializedData;
+}
+export function serializeExternalUsersSubmitDeleteJobRequestV2025R0(
+  val: ExternalUsersSubmitDeleteJobRequestV2025R0,
+): SerializedData {
+  return {
+    ['external_users']: val.externalUsers.map(function (
+      item: UserReferenceV2025R0,
+    ): SerializedData {
+      return serializeUserReferenceV2025R0(item);
+    }) as readonly any[],
+  };
+}
+export function deserializeExternalUsersSubmitDeleteJobRequestV2025R0(
+  val: SerializedData,
+): ExternalUsersSubmitDeleteJobRequestV2025R0 {
+  if (!sdIsMap(val)) {
+    throw new BoxSdkError({
+      message:
+        'Expecting a map for "ExternalUsersSubmitDeleteJobRequestV2025R0"',
+    });
+  }
+  if (val.external_users == void 0) {
+    throw new BoxSdkError({
+      message:
+        'Expecting "external_users" of type "ExternalUsersSubmitDeleteJobRequestV2025R0" to be defined',
+    });
+  }
+  if (!sdIsList(val.external_users)) {
+    throw new BoxSdkError({
+      message:
+        'Expecting array for "external_users" of type "ExternalUsersSubmitDeleteJobRequestV2025R0"',
+    });
+  }
+  const externalUsers: readonly UserReferenceV2025R0[] = sdIsList(
+    val.external_users,
+  )
+    ? (val.external_users.map(function (
+        itm: SerializedData,
+      ): UserReferenceV2025R0 {
+        return deserializeUserReferenceV2025R0(itm);
+      }) as readonly any[])
+    : [];
+  return {
+    externalUsers: externalUsers,
+  } satisfies ExternalUsersSubmitDeleteJobRequestV2025R0;
+}