@inweb/client 25.8.16 → 25.8.19

package/src/Api/Client.ts

@@ -35,19 +35,18 @@ import { User } from "./User";
 import { parseArgs } from "./Utils";
 
 /**
- * The `Client.js` library class that provides methods to access the
- * {@link https://cloud.opendesign.com/docs/index.html#/opencloud_server | Open Cloud Server}
- * resources like Projects, Files, Issues etc.
+ * Provides methods for managing server resources such as users, files, assemblies, jobs, projects, etc.
  */
 export class Client extends EventEmitter2<ClientEventMap> {
   private _serverUrl = "";
-  public httpClient: IHttpClient = new HttpClient("");
+  private _httpClient: IHttpClient = new HttpClient("");
   private _user: User | null = null;
   public eventEmitter: EventEmitter2 = this;
 
   /**
    * @param params - An object containing client configuration parameters.
-   * @param params.serverUrl - Open Cloud Server URL.
+   * @param params.serverUrl - Open Cloud Server REST API base URL.
+   * @param params.url - Deprecated since `25.8`. Use `serverUrl` instead.
    */
   constructor(params: { serverUrl?: string; url?: string } = {}) {
     super();
@@ -55,7 +54,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Open Cloud Server URL. Use {@link configure | configure()} to change server URL.
+   * Open Cloud Server REST API base URL. Use {@link configure | configure()} to change server URL.
    *
    * @readonly
    */
@@ -64,7 +63,16 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Deprecated since `25.3`. Use `Viewer.options()` instead to change Viewer parameters.
+   * HTTP client instance used to send REST API requests and receive responses from the server.
+   *
+   * @readonly
+   */
+  get httpClient(): IHttpClient {
+    return this._httpClient;
+  }
+
+  /**
+   * Deprecated since `25.3`. Use `Viewer.options()` instead to change `Viewer` parameters.
    *
    * @deprecated
    */
@@ -109,15 +117,16 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Change the client configuration parameters.
+   * Changes the client parameters.
+   *
+   * After changing the parameters, you must re-login.
    *
-   * @param params - An object containing new configuration parameters.
-   * @param params.serverUrl - Open Cloud Server URL.
-   * @returns Returns a reference to the `Client`.
+   * @param params - An object containing new parameters.
+   * @param params.serverUrl - Open Cloud Server REST API base URL.
    */
   configure(params: { serverUrl?: string }): this {
     this._serverUrl = (params.serverUrl || "").replace(/\/+$/, "");
-    this.httpClient = new HttpClient(this.serverUrl);
+    this._httpClient = new HttpClient(this.serverUrl);
     this._user = null;
     return this;
   }
@@ -131,7 +140,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns server version.
+   * Returns client and server versions.
    */
   version(): Promise<any> {
     return this.httpClient
@@ -145,13 +154,13 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Register a new user with the specified email and password.
+   * Registers a new user on the server.
    *
-   * @param email - User email. Cannot be empty.
+   * @param email - User email. Cannot be empty. Must be unique within the server.
    * @param password - User password. Cannot be empty. Password can only contain letters (a-z,
    *   A-Z), numbers (0-9), and special characters (~!@#$%^&*()_-+={}[]<>|/'":;.,?).
-   * @param userName - User name. Cannot be empty or blank if defined. Leave undefined to use
-   *   `username` from email.
+   * @param userName - User name. Cannot be empty or blank if defined. this to `undefined` to
+   *   use `username` from email.
    */
   registerUser(email: string, password: string, userName?: string): Promise<any> {
     return this.httpClient
@@ -164,7 +173,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Resend the Confirmation Email to new user. If the user's email is already confirmed, an
+   * Resends a Confirmation Email to the new user. If the user's email is already confirmed, an
    * exception will be thrown.
    *
    * @param email - User email.
@@ -177,7 +186,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Confirm the user's email. If the user's email is already confirmed, an exception will be thrown.
+   * Marks the user's email address as confirmed. If the user's email is already confirmed, an
+   * exception will be thrown.
    *
    * @param emailConfirmationId - Confirmation code from the Confirmation Email.
    */
@@ -231,8 +241,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns the current logged in user information. Returns `null` if the user is not logged
-   * in or the logged in user has deleted himself.
+   * Returns the current logged in user. Returns `null` if the user is not logged in or the
+   * logged in user has deleted themself.
    */
   getCurrentUser(): User | null {
     if (this._user && !this.httpClient.signInUserId) this._user = null;
@@ -240,13 +250,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Get the list of server indentity providers.
-   *
-   * To sign in with the provider in your web application:
-   *
-   * - Open the `provider.url` link using `window.open()`.
-   * - Add a `/oauth` path (server-defined) handler to the router. In this handler, show an error
-   *   message if the `error` search parameter is present, or log in with the `token` search parameter.
+   * Returns the list of server enabled indentity providers.
    */
   getIdentityProviders(): Promise<any> {
     return this.httpClient.get("/identity").then((response) => response.json());
@@ -260,7 +264,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Change server settings.
+   * Changes the server settings.
    *
    * Only administrators can change server settings. If the current logged in user is not an
    * administrator, an exception will be thrown.
@@ -270,7 +274,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns a list of server users.
+   * Returns the list of server users.
    *
    * Only administrators can get a list of users. If the current logged in user is not an
    * administrator, an exception will be thrown.
@@ -284,7 +288,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns the user information.
+   * Returns information about the specified user.
    *
    * Only administrators can get other users. If the current logged in user is not an
    * administrator, they can only get themselves, otherwise an exception will be thrown.
@@ -310,18 +314,18 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Create a new user.
+   * Creates a new user on the server.
    *
    * Only administrators can create users. If the current logged in user is not an
    * administrator, an exception will be thrown.
    *
-   * @param email - User email. Cannot be empty.
+   * @param email - User email. Cannot be empty. Must be unique within the server.
    * @param password - User password. Cannot be empty. Password can only contain latin letters
    *   (a-z, A-Z), numbers (0-9), and special characters (~!@#$%^&*()_-+={}[]<>|/'":;.,?).
    * @param params - Additional user data.
    * @param params.isAdmin - `true` if user is an administrator.
-   * @param params.userName - User name. Cannot be empty or blank if defined. Leave undefined
-   *   to use `username` from email.
+   * @param params.userName - User name. Cannot be empty or blank if defined. Specify
+   *   `undefined` to use `username` from email.
    * @param params.firstName - First name.
    * @param params.lastName - Last name.
    * @param params.canCreateProject - `true` if user is allowed to create a project.
@@ -358,7 +362,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Delete a user from the server.
+   * Deletes the specified user from the server.
    *
    * Only administrators can delete users. If the current logged in user is not an
    * administrator, an exception will be thrown.
@@ -366,7 +370,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * Administrators can delete themselves or other administrators. An administrator can only
    * delete themself if they is not the last administrator.
    *
-   * You need to re-login to continue working after deleting the current logged in user.
+   * You need to re-login after deleting the current logged in user.
    *
    * @param userId - User ID.
    * @returns Returns the raw data of a deleted user.
@@ -399,17 +403,15 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns a list of files the user has access to.
+   * Returns a list of files that the current logged in user has uploaded to the server or has access to.
    *
    * @param start - The starting index in the file list. Used for paging.
    * @param limit - The maximum number of files that should be returned per request. Used for paging.
-   * @param name - Filter the files by part of the name.
+   * @param name - Filter the files by part of the name. Case sensitive.
    * @param ext - Filter the files by extension. Extension can be `dgn`, `dwf`, `dwg`, `dxf`,
    *   `ifc`, `ifczip`, `nwc`, `nwd`, `obj`, `rcs`, `rfa`, `rvt`, `step`, `stl`, `stp`, `vsf`,
-   *   or any other drawing or reference file type extension. You can specify multiple
-   *   extensions on one string by separating them with a `|`.
-   * @param ids - List of file IDs to return. You can specify multiple IDs on one `string` by
-   *   separating them with a `|`.
+   *   or any other file type extension.
+   * @param ids - List of file IDs to return.
    * @param sortByDesc - Allows to specify the descending order of the result. By default,
    *   files are sorted by name in ascending order.
    * @param {string} sortField - Allows to specify sort field.
@@ -454,7 +456,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns the file information.
+   * Returns information about the specified file.
    *
    * @param fileId - File ID.
    */
@@ -472,16 +474,16 @@ export class Client extends EventEmitter2<ClientEventMap> {
    *
    * - {@link UploadProgressEvent | uploadprogress}
    *
-   * @param file - Web API {@link https://developer.mozilla.org/docs/Web/API/File | File} object
+   * @param file - {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object
    *   are generally retrieved from a
    *   {@link https://developer.mozilla.org/docs/Web/API/FileList | FileList} object returned as
    *   a result of a user selecting files using the HTML `<input>` element.
    * @param params - An object containing upload parameters.
-   * @param params.geometry - Create job to extract file geometry data. Can be:
+   * @param params.geometry - Create job to convert file geometry data. Can be:
    *
-   *   - `true` - Extract file geometry data into `VSFX` to open the file in `VisualizeJS` viewer.
-   *   - `vsfx` - Extract file geometry data into `VSFX` to open the file in `VisualizeJS` viewer.
-   *   - `gltf` - Extract file geometry data into `glTF` to open the file in `Three.js` viewer.
+   *   - `true` - Convert file geometry data to `VSFX` format to open the file in `VisualizeJS` viewer.
+   *   - `vsfx` - Convert file geometry data to `VSFX` format to open the file in `VisualizeJS` viewer.
+   *   - `gltf` - Convert file geometry data to `glTF` format to open the file in `Three.js` viewer.
    *
    * @param params.properties - Create job to extract file properties.
    * @param params.waitForDone - Wait for geometry and properties jobs to complete.
@@ -490,7 +492,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @param params.interval - The time, in milliseconds, the function should delay in between
    *   checking jobs status.
    * @param params.signal - An
-   *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} *
+   *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
    *   signal, which can be used to abort waiting as desired.
    * @param params.onProgress - Upload progress callback.
    */
@@ -531,7 +533,10 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Delete the drawing or reference file from the server.
+   * Deletes the specified file and all its versions from the server.
+   *
+   * You cannot delete a version file using `deleteFile()`, only the original file. To delete a
+   * version file use {@link File.deleteVersion | File.deleteVersion()}.
    *
    * @param fileId - File ID.
    * @returns Returns the raw data of a deleted file.
@@ -541,7 +546,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Download the drawing or reference file.
+   * Downloads the specified file from the server.
    *
    * @param fileId - File ID.
    * @param onProgress - Download progress callback.
@@ -567,10 +572,9 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns a list of jobs created by current user.
+   * Returns a list of jobs started by the current logged in user.
    *
-   * @param status - Filter the jobs by status. Status can be `waiting`, `inpogress`, `done` or
-   *   `failed`. You can specify multiple statuses on one `string` by separating them with a "|".
+   * @param status - Filter the jobs by status. Status can be `waiting`, `inpogress`, `done` or `failed`.
    * @param limit - The maximum number of jobs that should be returned per request. Used for paging.
    * @param start - The starting index in the job list. Used for paging.
    * @param sortByDesc - Allows to specify the descending order of the result. By default, jobs
@@ -608,7 +612,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns the job information.
+   * Returns information about the specified job.
    *
    * @param jobId - Job ID.
    */
@@ -620,15 +624,15 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Create a new job.
+   * Runs a new job on the server for the sepecified file.
    *
    * @param fileId - File ID.
    * @param outputFormat - The job type. Can be one of:
    *
-   *   - `geometry` - Extract file geometry data into `VSFX`.
-   *   - `geometryGltf` - Extract file geometry data into `glTF`.
+   *   - `geometry` - Convert file geometry data to `VSFX` format suitable for `VisualizeJS` viewer.
+   *   - `geometryGltf` - Convert file geometry data to `glTF` format suitable for `Three.js` viewer.
    *   - `properties` - Extract file properties.
-   *   - `validation` - Validate the file. Only for `IFC`.
+   *   - `validation` - Validate the file. Only for `IFC` files.
    *   - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the one of the supported format.
    *   - Other custom job name. Custom job runner must be registered in the job templates table
    *       before creating a job.
@@ -648,8 +652,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Remove a job from the server job list. The method does not delete or stop jobs that are
-   * already being executed.
+   * Deletes the specified job from the server job list. Jobs that are in progress or have
+   * already been completed cannot be deleted.
    *
    * @param jobId - Job ID.
    * @returns Returns the raw data of a deleted job.
@@ -670,14 +674,13 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns a list of assemblies the user has access to.
+   * Returns a list of assemblies created by the current logged in user.
    *
    * @param start - The starting index in the assembly list. Used for paging.
    * @param limit - The maximum number of assemblies that should be returned per request. Used
    *   for paging.
-   * @param name - Filter the assemblies by part of the name.
-   * @param ids - List of assembly IDs to return. You can specify multiple IDs on one `string`
-   *   by separating them with a "|".
+   * @param name - Filter the assemblies by part of the name. Case sensitive.
+   * @param ids - List of assembly IDs to return.
    * @param sortByDesc - Allows to specify the descending order of the result. By default
    *   assemblies are sorted by name in ascending order.
    * @param sortField - Allows to specify sort field.
@@ -717,7 +720,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Get assembly information.
+   * Returns information about the specified assembly.
    *
    * @param assemblyId - Assembly ID.
    */
@@ -729,12 +732,21 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Create a new assembly.
+   * Creates a new assembly on the server.
    *
    * @param files - List of file IDs.
    * @param name - Assembly name.
-   * @param params - An object containing upload parameters.
+   * @param params - Additional assembly creating parameters.
    * @param params.waitForDone - Wait for assembly to be created.
+   * @param params.timeout - The time, in milliseconds, that the function should wait for the
+   *   assembly to be created. If the assembly is not created within this time, a TimeoutError
+   *   exception will be thrown.
+   * @param params.interval - The time, in milliseconds, the function should delay in between
+   *   checking assembly status.
+   * @param params.signal - An
+   *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
+   *   signal, which can be used to abort waiting as desired.
+   * @param params.onCheckout - Waiting progress callback. Return `true` to cancel waiting.
    */
   createAssembly(
     files: string[],
@@ -744,6 +756,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
       timeout?: number;
       interval?: number;
       signal?: AbortSignal;
+      onCheckout?: (assembly: Assembly, ready: boolean) => boolean;
     }
   ): Promise<Assembly> {
     const { waitForDone } = params ?? {};
@@ -755,7 +768,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Delete the assembly from the server.
+   * Deletes the specified assembly from the server.
    *
    * @param assemblyId - Assembly ID.
    * @returns Returns the raw data of a deleted assembly.
@@ -776,13 +789,12 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns a list of projects the user has access to.
+   * Returns a list of projects that the currently logged in user has created or has access to.
    *
    * @param start - The starting index in the project list. Used for paging.
    * @param limit - The maximum number of projects that should be returned per request. Used for paging.
-   * @param name - Filter the projects by part of the name.
-   * @param ids - List of project IDs to return. You can specify multiple IDs on one `string`
-   *   by separating them with a "|".
+   * @param name - Filter the projects by part of the name. Case sensitive.
+   * @param ids - List of project IDs to return.
    * @param sortByDesc - Allows to specify the descending order of the result. By default
    *   projects are sorted by name in ascending order.
    */
@@ -838,7 +850,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns the project information.
+   * Returns information about the specified project.
    *
    * @param projectId - Project ID.
    */
@@ -850,7 +862,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Create a new project.
+   * Creates a new project on the server.
    *
    * @param name - Project name.
    * @param description - Project description.
@@ -875,7 +887,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Delete the project from the server.
+   * Deletes the specified project from the server.
    *
    * @param projectId - Project ID.
    * @returns Returns the raw data of a deleted project.

package/src/Api/ClientEvents.ts

@@ -15,7 +15,7 @@ export interface UploadProgressEvent {
   data: number;
 
   /**
-   * File object to upload.
+   * {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object to upload.
    */
   file: globalThis.File;
 }