@inweb/client 26.5.3 → 26.5.5

package/src/Api/File.ts

@@ -123,7 +123,7 @@ export class File extends Endpoint {
   /**
    * 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
+   * To export file to one of the supported formats run the File Converter job using
    * {@link createJob | createJob()}. To download exported file use
    * {@link downloadResource | downloadResource()}.
    *
@@ -138,8 +138,8 @@ export class File extends Endpoint {
   /**
    * Geometry data type of the active file version. Can be one of:
    *
-   * - `vsfx` - `VSFX` format, file can be opened in `VisualizeJS` viewer.
-   * - `gltf` - `glTF` format, file can be opened in `Three.js` viewer.
+   * - `vsfx` - `VSFX` format, file can be opened in `VisualizeJS` 3D viewer.
+   * - `gltf` - `glTF` format, file can be opened in `Three.js` 3D viewer.
    *
    * 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.
@@ -397,7 +397,7 @@ export class File extends Endpoint {
    *
    * @typedef {any} Properties
    * @property {string} handle - Object original handle.
-   * @property {string | any} - Object property. Can be `any` for nested properties.
+   * @property {string | any} * - Object property. Can be `any` for nested group properties.
    */
 
   /**
@@ -405,10 +405,42 @@ export class File extends Endpoint {
    *
    * @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";
-    return this.get(relativePath).then((response) => response.json());
+   * @param group - If the `group` parameter is `true`, properties are returned grouped by category. By
+   *   default, or if `group` is set to `false`, properties are returned ungrouped.
+   *
+   *   To get grouped properties, the `--properties_group` command line argument must be specified for the
+   *   `properties` File Converter job when {@link Client.uploadFile | uploading the file}:
+   *
+   *   ```javascript
+   *   await client.uploadFile(file, {
+   *     geometry: true,
+   *     properties: true,
+   *     jobParameters: { properties: "--properties_group" },
+   *     waitForDone: true,
+   *   });
+   *   ```
+   *
+   *   or when running the {@link extractProperties | extract file properties} job:
+   *
+   *   ```javascript
+   *   await file.extractProperties("--properties_group");
+   *   ```
+   *
+   *   Otherwise, the properties will be returned ungrouped, even if the `group` is `true`.
+   */
+  getProperties(handles?: string | string[], group = false): Promise<any[]> {
+    const searchParams = new URLSearchParams();
+    if (handles) {
+      if (Array.isArray(handles)) handles = handles.join(",");
+      if (typeof handles === "string") handles = handles.trim();
+      if (handles) searchParams.set("handles", handles);
+    }
+    if (group) searchParams.set("group", "true");
+
+    let queryString = searchParams.toString();
+    if (queryString) queryString = "?" + queryString;
+
+    return this.get(`/properties${queryString}`).then((response) => response.json());
   }
 
   /**
@@ -541,15 +573,15 @@ export class File extends Endpoint {
    * 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 Export file to DWG.
+   * @example Export file to PDF.
    *
    * ```javascript
-   * const job = await file.crateJob("dwg");
+   * const job = await file.createJob("pdf");
    * await job.waitForDone();
-   * const dwgFileName = file.exports.find((x) => x.endsWith(".dwg"));
-   * const arrayBuffer = await file.downloadResource(dwgFileName);
+   * const pdfResourceName = file.exports.find((x) => x.endsWith(".pdf"));
+   * const arrayBuffer = await file.downloadResource(pdfResourceName);
    * const blob = new Blob([arrayBuffer]);
-   * const fileName = file.name + ".dwg";
+   * const fileName = file.name + ".pdf";
    * FileSaver.saveAs(blob, fileName);
    * ```
    *
@@ -658,20 +690,19 @@ export class File extends Endpoint {
   /**
    * Runs a new job on the server for the active version of the file.
    *
-   * @param outputFormat - The job type. Can be one of:
+   * @param outputFormat - The job type. Can be:
    *
-   *   - `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.
+   *   - `geometry` - Convert file geometry data to `VSFX` format for opening in `VisualizeJS` 3D viewer.
+   *   - `geometryGltf` - Convert file geometry data to `glTF` format for opening in `Three.js` 3D viewer.
    *   - `properties` - Extract file properties.
-   *   - `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
+   *   - `validation` - Validate the IFC file.
+   *   - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the specified format. Use
+   *       {@link exports} to get the list of completed file exports. Use
    *       {@link downloadResource | downloadResource()} to download the exported file.
-   *   - Other custom job name. Custom job runner must be registered in the job templates before creating a
-   *       job.
+   *   - Other custom job name. Custom job must be registered in the job templates before running.
    *
-   * @param parameters - Parameters for the job runner. Can be given as command line arguments for the
-   *   File Converter tool in form `--arg=value`.
+   * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as command
+   *   line arguments in form `--arg=value`.
    */
   createJob(outputFormat: string, parameters?: string | object): Promise<Job> {
     const jobs = new Endpoint("/jobs", this.httpClient, this.headers);
@@ -686,40 +717,40 @@ export class File extends Endpoint {
   }
 
   /**
-   * Runs a job to convert geometry data of active version of the file. This is alias to
-   * {@link createJob | createJob("geometry")}.
+   * Runs a File Converter job to convert geometry data of active version of the file to the specified
+   * format. This is alias to {@link createJob | createJob("geometry")}.
    *
    * @param type - Geometry data type. Can be one of:
    *
-   *   - `vsfx` - `VSFX` format (default), for opening a file in `VisualizeJS` viewer.
-   *   - `gltf` - `glTF` format, for opening a file in `Three.js` viewer.
+   *   - `vsfx` - `VSFX` format (default), for opening a file in `VisualizeJS` 3D viewer.
+   *   - `gltf` - `glTF` format, for opening a file in `Three.js` 3D viewer.
    *
-   * @param parameters - Parameters for the job runner. Can be given as command line arguments for the
-   *   File Converter tool in form `--arg=value`.
+   * @param parameters - Parameters for the File Converter job. Can be given as command line arguments in
+   *   form `--arg=value`.
    */
   extractGeometry(type?: string, parameters?: string | object): Promise<Job> {
     return this.createJob(type === "gltf" ? "geometryGltf" : "geometry", parameters);
   }
 
   /**
-   * Runs a job to extract properties of the active version of the file. This is alias to
+   * Runs a File Converter 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 for the
-   *   File Converter tool in form `--arg=value`.
+   * @param parameters - Parameters for the File Converter job. Can be given as command line arguments in
+   *   form `--arg=value`.
    */
   extractProperties(parameters?: string | object): Promise<Job> {
     return this.createJob("properties", parameters);
   }
 
   /**
-   * Runs a job to validate the active version of the file. This is alias to
+   * Runs an IFC validator 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")}.
    *
-   * @param parameters - Parameters for the job runner. Can be given as command line arguments for the
-   *   File Converter tool in form `--arg=value`.
+   * @param parameters - Parameters for the IFC validator tool. Can be given as command line arguments in
+   *   form `--arg=value`.
    */
   validate(parameters?: string | object): Promise<Job> {
     return this.createJob("validation", parameters);
@@ -729,8 +760,9 @@ export class File extends Endpoint {
    * 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 job name.
+   * @param jobs - Job name or array of job names to wait on. Can be `geometry`, `geometryGltf`,
+   *   `properties`, `validation`, `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` or custom job
+   *   name.
    * @param waitAll - If this parameter is `true`, the function returns when all the specified jobs have
    *   done. If `false`, the function returns when any one of the jobs are done.
    * @param params - An object containing waiting parameters.

package/src/Api/Job.ts

@@ -121,8 +121,15 @@ export class Job extends Endpoint {
   }
 
   /**
-   * Job type. Can be `properties`, `geomerty`, `geomertyGltf`, `validation`, `clash`, `dwg`, `obj`,
-   * `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` or custom job name.
+   * Job type. Can be:
+   *
+   * - `geometry` - Convert file geometry data to `VSFX` format.
+   * - `geometryGltf` - Convert file geometry data to `glTF` format.
+   * - `properties` - Extract file properties.
+   * - `validation` - Validate the IFC file.
+   * - `clash` - Create the clash detection report.
+   * - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the specified format.
+   * - Other custom job name.
    *
    * @readonly
    */
@@ -131,7 +138,7 @@ export class Job extends Endpoint {
   }
 
   /**
-   * Parameters with which the job runner was started. For more information, see
+   * Parameters with which the job was started. For more information, see
    * {@link https://cloud.opendesign.com/docs//pages/server/api.html#Jobs | Open Cloud Jobs API}.
    *
    * @readonly