@inweb/client 25.8.16 → 25.8.19

package/src/Api/File.ts

@@ -30,7 +30,8 @@ import { Job } from "./Job";
 import { waitFor, parseArgs, userFullName, userInitials } from "./Utils";
 
 /**
- * The class representing a `file` entity.
+ * Provides properties and methods for obtaining information about a file on the server and
+ * managing its data and versions.
  */
 export class File {
   private _data: any;
@@ -39,8 +40,8 @@ export class File {
   public path: string;
 
   /**
-   * @param data - An object that implements file data storage.
-   * @param httpClient - Http client for API.
+   * @param data - Raw file data received from the server.
+   * @param httpClient - HTTP client instance used to send REST API requests to the server.
    */
   constructor(data: any, httpClient: IHttpClient) {
     this.path = `/files/${data.id}`;
@@ -145,8 +146,9 @@ export class File {
   }
 
   /**
-   * Returns a list of files in different formats in which the active version of the file was
-   * exported. To export file to one of the supported formats create File Converter job using
+   * Returns a list of file formats in which the active version of the file was exported.
+   *
+   * To export file to one of the supported formats create File Converter job using
    * {@link createJob | createJob()}. To download exported file use
    * {@link downloadResource | downloadResource()}.
    *
@@ -159,10 +161,10 @@ export class File {
   /**
    * Geometry data type of the active file version. Can be one of:
    *
-   * - `vsfx` - `VSFX`, file can be opened in `VisualizeJS` viewer.
-   * - `gltf` - `glTF`, file can be opened in `Three.js` viewer.
+   * - `vsfx` - `VSFX` format, file can be opened in `VisualizeJS` viewer.
+   * - `gltf` - `glTF` format, file can be opened in `Three.js` viewer.
    *
-   * Returns an empty string if geometry data has not yet been extracted. A files without
+   * Returns an empty string if geometry data has not yet been converted. A files without
    * geometry data can be exported to other formas, but cannot be opened in viewer.
    */
   get geometryType(): string {
@@ -181,7 +183,10 @@ export class File {
   }
 
   /**
-   * Returns `true` if source of the active file version has been deleted.
+   * Returns `true` if the source file of the active file version has been deleted.
+   *
+   * A files with deleted source file can be opened in the viewer, but cannot be exported to
+   * other formats.
    *
    * @readonly
    */
@@ -246,7 +251,7 @@ export class File {
   }
 
   /**
-   * Total size of all versions of the file in the storage in bytes.
+   * Total size of all versions of the file in bytes.
    *
    * @readonly
    */
@@ -257,8 +262,8 @@ export class File {
   /**
    * Data status of the active version of the file. Contains:
    *
-   * - `geometry` - status of geometry data of `VSFX` type.
-   * - `geometryGltf` - status of geometry data of `glTF` type.
+   * - `geometry` - status of geometry data of `vsfx` type.
+   * - `geometryGltf` - status of geometry data of `gltf` type.
    * - `properties` - status of properties.
    * - `validation` - status of validation.
    *
@@ -327,7 +332,7 @@ export class File {
   }
 
   /**
-   * Refresh file data.
+   * Reloads file data from the server.
    */
   async checkout(): Promise<this> {
     const response = await this.internalGet("");
@@ -336,7 +341,7 @@ export class File {
   }
 
   /**
-   * Update file data on the server.
+   * Updates file data on the server.
    *
    * @param data - Raw file data.
    */
@@ -347,7 +352,10 @@ export class File {
   }
 
   /**
-   * Delete the file and all its versions from the server.
+   * Deletes a file and all its versions from the server.
+   *
+   * You cannot delete a version file using `delete()`, only the original file. To delete a
+   * version file use {@link deleteVersion | deleteVersion()}.
    *
    * @returns Returns the raw data of a deleted file.
    */
@@ -356,23 +364,23 @@ export class File {
   }
 
   /**
-   * Save file data changes to the server. Call this method to update file data on the server
-   * after any changes.
+   * Saves file properties changes to the server. Call this method to update file data on the
+   * server after any property changes.
    */
   save(): Promise<this> {
     return this.update(this.data);
   }
 
   /**
-   * Set or remove the file preview.
+   * Sets or removes the file preview.
    *
-   * @param image - Preview image.Can be a
+   * @param image - Preview image. Can be a
    *   {@link https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/Data_URIs | Data URL}
    *   string,
    *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
-   *   {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob} or Web API
-   *   {@link https://developer.mozilla.org/docs/Web/API/File | File} object. Setting the
-   *   `image` to `null` will remove the preview.
+   *   {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob} or
+   *   {@link https://developer.mozilla.org/docs/Web/API/File | Web API File} object. Setting
+   *   the `image` to `null` will remove the preview.
    */
   async setPreview(image?: BodyInit | null): Promise<this> {
     if (!image) {
@@ -385,7 +393,7 @@ export class File {
   }
 
   /**
-   * Remove the file preview.
+   * Removes the file preview.
    */
   async deletePreview(): Promise<this> {
     const response = await this.internalDelete("/preview");
@@ -424,8 +432,8 @@ export class File {
   /**
    * Returns the properties for an objects in the active version of the file.
    *
-   * @param handles - Object original handle or handles array. Leave this parameter `undefined`
-   *   to get properties for all objects in the file.
+   * @param handles - Object original handle or handles array. Specify `undefined` to get
+   *   properties for all objects in the file.
    */
   getProperties(handles?: string | string[]): Promise<any[]> {
     const relativePath = handles !== undefined ? `/properties?handles=${handles}` : "/properties";
@@ -471,7 +479,7 @@ export class File {
    *     ],
    *   };
    *
-   * @param {SearchPattern | QueryOperator} searchPattern - Search pattern or combination of
+   * @param {SeacrhPattern | QueryOperator} searchPattern - Search pattern or combination of
    *   the patterns, see example below.
    * @returns {Promise<Properties[]>}
    */
@@ -481,7 +489,7 @@ export class File {
   }
 
   /**
-   * Returns the cda.json for an active version of the file.
+   * Returns the CDA tree for an active version of the file.
    */
   getCdaTree(): Promise<any[]> {
     return this.internalGet(`/properties/tree`).then((response) => response.json());
@@ -497,7 +505,7 @@ export class File {
   }
 
   /**
-   * Add new file viewpoint. To create a viewpoint use `Viewer.createViewpoint()`.
+   * Adds a new viewpoint to the file. To create a viewpoint use `Viewer.createViewpoint()`.
    *
    * @param viewpoint - Viewpoint.
    */
@@ -506,7 +514,7 @@ export class File {
   }
 
   /**
-   * Delete file viewpoint.
+   * Deletes the specified file viewpoint.
    *
    * @param guid - Viewpoint GUID.
    * @returns Returns the raw data of a deleted viewpoint.
@@ -536,7 +544,7 @@ export class File {
   }
 
   /**
-   * Download source of active version of the file.
+   * Downloads the source file of active version of the file from the server.
    *
    * @param onProgress - Download progress callback.
    * @param signal - An
@@ -551,7 +559,7 @@ export class File {
   }
 
   /**
-   * Download a resource file of the active version of the file. Resource files are files that
+   * Downloads a resource file of the active version of the file. Resource files are files that
    * contain model scene descriptions, or geometry data, or exported files.
    *
    * @example <caption>Export file to DWG.</caption>
@@ -581,7 +589,7 @@ export class File {
   }
 
   /**
-   * Download a part of resource file of the active version of the file. Resource files are
+   * Downloads a part of resource file of the active version of the file. Resource files are
    * files that contain model scene descriptions, or geometry data, or exported files.
    *
    * @param dataId - Resource file name.
@@ -637,7 +645,9 @@ export class File {
   }
 
   /**
-   * Returns a list of references to files used to correct rendering of the current file.
+   * Returns a list of file references.
+   *
+   * References are images, fonts, or any other files to correct rendering of the file.
    *
    * @param signal - An
    *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
@@ -648,7 +658,10 @@ export class File {
   }
 
   /**
-   * Set the file references.
+   * Sets the file references.
+   *
+   * References are images, fonts, or any other files to correct rendering of the file.
+   * Reference files must be uploaded to the server before they can be assigned to the current file.
    *
    * @param references - File references.
    */
@@ -657,14 +670,14 @@ export class File {
   }
 
   /**
-   * Create a new job for the active version of the file.
+   * Runs a new job on the server for the active version of the file.
    *
    * @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. Use {@link exports | exports()} to get the list of completed file
    *       exports. Use {@link downloadResource | downloadResource()} to download the exported file.
@@ -687,13 +700,13 @@ export class File {
   }
 
   /**
-   * Create job to extract geometry data of active version of the file. This is alias to
+   * Runs a job to convert geometry data of active version of the file. This is alias to
    * {@link createJob | createJob("geometry")}.
    *
    * @param type - Geometry data type. Can be one of:
    *
-   *   - `vsfx` - `VSFX` (default), for opening a file in `VisualizeJS` viewer.
-   *   - `gltf` - `glTF`, for opening a file in `Three.js` viewer.
+   *   - `vsfx` - `VSFX` format (default), for opening a file in `VisualizeJS` viewer.
+   *   - `gltf` - `glTF` format, for opening a file in `Three.js` viewer.
    *
    * @param parameters - Parameters for the job runner. Can be given as command line arguments
    *   for the File Converter tool in form `--arg=value`.
@@ -703,7 +716,7 @@ export class File {
   }
 
   /**
-   * Create job to extract properties of the active version of the file. This is alias to
+   * Runs a job to extract properties of the active version of the file. This is alias to
    * {@link createJob | createJob("properties")}.
    *
    * @param parameters - Parameters for the job runner. Can be given as command line arguments
@@ -714,7 +727,7 @@ export class File {
   }
 
   /**
-   * Create a job to validate the active version of the file. This is alias to
+   * Runs a job to validate the active version of the file. This is alias to
    * {@link createJob | createJob("validation")}.
    *
    * To get validation report use {@link downloadResource | downloadResource("validation_report.json")}.
@@ -727,8 +740,8 @@ export class File {
   }
 
   /**
-   * Wait for jobs of the active version of the file to be done. Job is done when it changes to
-   * `none`, `done` or `failed` status.
+   * Waits for jobs of the active version of the file to be done. Job is done when it changes
+   * to `none`, `done` or `failed` status.
    *
    * @param jobs - Job or job array to wait on. Can be `geometry`, `geometryGltf`,
    *   `properties`, `validation`, `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` or custom
@@ -782,7 +795,7 @@ export class File {
   }
 
   /**
-   * Returns the permission information.
+   * Returns information about specified file permission.
    *
    * @param permissionId - Permission ID.
    */
@@ -793,10 +806,16 @@ export class File {
   }
 
   /**
-   * Create a new file permission.
+   * Creates a new file permission.
+   *
+   * @param actions - Actions are allowed to be performed on a file with this permission:
+   *
+   *   - `read` - The ability to read file description, geometry data and properties.
+   *   - `readSourceFile` - The ability to read source file.
+   *   - `write` - The ability to modify file name, description and references.
+   *   - `readViewpoint` - The ability to read file viewpoints.
+   *   - `createViewpoint` - The ability to create file viewpoints.
    *
-   * @param actions - Actions are allowed to be performed on a file with this permission. See
-   *   {@link Permission.actions} for more details.
    * @param grantedTo - A collection of principials that will get access to the file.
    * @param _public - Specifies whether all users have access to the file or not.
    */
@@ -811,7 +830,7 @@ export class File {
   }
 
   /**
-   * Delete file permission.
+   * Removes the specified permission from the file.
    *
    * @param permissionId - Permission ID.
    * @returns Returns the raw data of a deleted permission.
@@ -821,14 +840,15 @@ export class File {
   }
 
   /**
-   * Upload the new version of the file to the server and extract the geometry and properties as needed.
+   * Uploads the new version of the file to the server, convert the geometry data and extract
+   * properties as needed.
    *
-   * @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. The geometry data type
+   * @param params.geometry - Create job to convert file geometry data. The geometry data type
    *   is the same as the original file.
    * @param params.properties - Create job to extract file properties.
    * @param params.waitForDone - Wait for geometry and properties jobs to complete.
@@ -892,7 +912,7 @@ export class File {
   }
 
   /**
-   * Returns the version file.
+   * Returns information about the specified version file.
    *
    * @param version - Desired version.
    */
@@ -904,7 +924,7 @@ export class File {
   }
 
   /**
-   * Delete version file.
+   * Deletes the specified version file.
    *
    * @param version - Version to delete.
    */
@@ -916,7 +936,7 @@ export class File {
   }
 
   /**
-   * Replace the active version of the file with the selected version.
+   * Replaces the active version of the file with the selected version.
    *
    * @param version - Desired active version.
    */
@@ -926,27 +946,29 @@ export class File {
   }
 
   /**
-   * Use given version instead of active version for current file on client side. This version
-   * change will affect the result:
+   * Makes the given version active on client side. Does not change the active file version on
+   * the server.
+   *
+   * This version change will affect the result:
    *
-   * - getModels()
-   * - getProperties()
-   * - searchProperties()
-   * - getCdaTree()
-   * - download()
-   * - downloadResource()
-   * - createJob()
-   * - extractGeometry()
-   * - extractProperties()
-   * - validate()
-   * - waitForDone()
+   * - {@link getModels | getModels()}
+   * - {@link getProperties | getProperties()}
+   * - {@link searchProperties | searchProperties()}
+   * - {@link getCdaTree | getCdaTree()}
+   * - {@link download | download()}
+   * - {@link downloadResource | downloadResource()}
+   * - {@link createJob | createJob()}
+   * - {@link extractGeometry | extractGeometry()}
+   * - {@link extractProperties | extractProperties()}
+   * - {@link validate | validate()}
+   * - {@link waitForDone | waitForDone()}
    * - Viewer.open()
    *
    * Other clients will still continue to use the current active version of the file. Use
    * `undefined` to revert back to the active version.
    *
-   * Note. You need to update the file data using {@link checkout | checkout()} to match the
-   * size and status fields to the version you selected.
+   * You need to reload the file data using {@link checkout | checkout()} to match the size and
+   * status fields to the version you selected.
    */
   useVersion(version?: number): this {
     this._useVersion = version;
@@ -954,7 +976,7 @@ export class File {
   }
 
   /**
-   * Delete the source of the active file version.
+   * Deletes the source file of the active file version from the server.
    */
   async deleteSource(): Promise<this> {
     const response = await this.internalDelete("/source");

package/src/Api/IAssembly.ts

@@ -35,3 +35,30 @@ export interface IAssemblyVersionInfo {
   createdAt: string;
   ownerId: string;
 }
+
+/**
+ * Model transformation matrix.
+ */
+export interface IModelTransformMatrix {
+  /**
+   * Translation part, move by specified offset along the X, Y, Z axes.
+   */
+  translate: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  /**
+   * Rotation part, rotate by the specified angle, around the specified vector.
+   */
+  rotation: {
+    x: number;
+    y: number;
+    z: number;
+    angle: number;
+  };
+  /**
+   * Scaling part, scale with multiplier, from center of extends.
+   */
+  scale: number;
+}

package/src/Api/Job.ts

@@ -25,16 +25,15 @@ import { IHttpClient } from "./IHttpClient";
 import { waitFor } from "./Utils";
 
 /**
- * The class representing a `job` entity describes the process of converting a file from one
- * format to another, to obtain geometric data, validate the file, or run a clash test.
+ * Provides properties and methods for obtaining information about a job on the server.
  */
 export class Job {
   private _data: any;
   public httpClient: IHttpClient;
 
   /**
-   * @param data - An object that implements job data storage.
-   * @param httpClient - Http client.
+   * @param data - Raw job data received from the server.
+   * @param httpClient - HTTP client instance used to send REST API requests to the server.
    */
   constructor(data: any, httpClient: IHttpClient) {
     this.httpClient = httpClient;
@@ -179,7 +178,7 @@ export class Job {
   }
 
   /**
-   * Refresh job data.
+   * Reloads job data from the server.
    */
   async checkout(): Promise<this> {
     const response = await this.internalGet();
@@ -188,7 +187,7 @@ export class Job {
   }
 
   /**
-   * Update job data on the server.
+   * Updates job data on the server.
    *
    * Only administrators can update job data. If the current logged in user is not an
    * administrator, an exception will be thrown.
@@ -202,7 +201,7 @@ export class Job {
   }
 
   /**
-   * Remove a job from the server job list. Jobs that are in progress or have already been
+   * Deletes a job from the server job list. Jobs that are in progress or have already been
    * completed cannot be deleted.
    *
    * @returns Returns the raw data of a deleted job.
@@ -212,18 +211,15 @@ export class Job {
   }
 
   // /**
-  //  * Save job data changes to the server. Call this method to update job data on the server
-  //  * after any changes.
-  //  *
-  //  *
-  //  * @returns {Promise<Job>}
+  //  * Save job properties changes to the server. Call this method to update job data on the server
+  //  * after any property changes.
   //  */
   // save() {
   //   return this.update(this.data);
   // }
 
   /**
-   * Wait for job to be done. Job is done when it changes to `done` or `failed` status.
+   * Waits for job to be done. Job is done when it changes to `done` or `failed` status.
    *
    * @param params - An object containing waiting parameters.
    * @param params.timeout - The time, in milliseconds that the function should wait job. If

package/src/Api/Member.ts

@@ -26,7 +26,8 @@ import { IShortUserDescription } from "./IUser";
 import { userFullName, userInitials } from "./Utils";
 
 /**
- * Members are the {@link User | users} who have access to the {@link Project | project}.
+ * Provides properties and methods for obtaining information about a {@link User | user} who has
+ * access to the {@link Project | project}.
  */
 export class Member {
   private _data: any;
@@ -34,9 +35,9 @@ export class Member {
   public httpClient: IHttpClient;
 
   /**
-   * @param data - An object that implements member data storage.
+   * @param data - Raw member data received from the server.
    * @param projectId - Owner project ID.
-   * @param httpClient - Http client.
+   * @param httpClient - HTTP client instance used to send REST API requests to the server.
    */
   constructor(data: any, projectId: string, httpClient: IHttpClient) {
     this.httpClient = httpClient;
@@ -119,7 +120,7 @@ export class Member {
   }
 
   /**
-   * Refresh member data.
+   * Reloads member data from the server.
    */
   async checkout(): Promise<this> {
     const response = await this.internalGet();
@@ -128,7 +129,7 @@ export class Member {
   }
 
   /**
-   * Update member data on the server.
+   * Updates member data on the server.
    *
    * @param data - Raw member data.
    */
@@ -139,7 +140,7 @@ export class Member {
   }
 
   /**
-   * Remove a member from a project.
+   * Removes a member from the project.
    *
    * @returns Returns the raw data of a deleted member.
    */
@@ -148,8 +149,8 @@ export class Member {
   }
 
   /**
-   * Save member data changes to the server. Call this method to update member data on the
-   * server after any changes.
+   * Saves member properties changes to the server. Call this method to update member data on
+   * the server after any property changes.
    */
   save(): Promise<this> {
     return this.update(this.data);