@inweb/client 27.1.9 → 27.2.0

package/src/Api/Client.ts

@@ -113,7 +113,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @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. this to `undefined` to use
+   * @param userName - User name. Cannot be empty or blank if defined. Specify `undefined` to use
    *   `username` from email.
    */
   registerUser(email: string, password: string, userName?: string): Promise<any> {
@@ -475,8 +475,12 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns a list of files that the current logged in user has uploaded to the server or has access to
-   * through a project.
+   * Returns a list of files from the server.
+   *
+   * You cannot list other users' files unless they have explicitly granted you `read` access or you are
+   * an administrator. To list these files, you must use the file ID filter.
+   *
+   * You cannot list files shared with you via shared links.
    *
    * @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.
@@ -484,11 +488,10 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @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 file
    *   type extension.
-   * @param ids - List of file IDs to return. The list can include files that the user has access to
-   *   through a project. If not specified, only files uploaded by the current user are returned.
+   * @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 sortField - Allows to specify sort field.
+   * @param sortField - Allows to specify sort field. Can be `name`, `size`, `created`, or `updatedAt`.
    * @param shared - Returns shared files only.
    */
   getFiles(
@@ -538,8 +541,10 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns information about the specified file that the current logged in user has uploaded or has
-   * access to through a project.
+   * Returns information about the specified file.
+   *
+   * You cannot retrieve other users' files unless they have explicitly granted you `read` access or you
+   * are an administrator.
    *
    * @param fileId - File ID.
    */
@@ -561,14 +566,15 @@ export class Client extends EventEmitter2<ClientEventMap> {
    *   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 - Run File Converter job to convert geometry data after uploading the file.
-   *   Can be one of:
+   * @param params.geometry - Create the File Converter job to convert geometry data after uploading the
+   *   file. Can be one of:
    *
    *   - `true` - Convert file geometry data to `VSFX` format for opening in `VisualizeJS` 3D viewer.
    *   - `vsfx` - Convert file geometry data to `VSFX` format for opening in `VisualizeJS` 3D viewer.
    *   - `gltf` - Convert file geometry data to `glTF` format for opening in `Three.js` 3D viewer.
    *
-   * @param params.properties - Run File Converter job to extract properties after uploading the file.
+   * @param params.properties - Create the File Converter job to extract properties after uploading the
+   *   file.
    * @param params.jobParameters - Parameters for the File Converter jobs. Use this to specify additional
    *   parameters for retrieving the geometry and properties of uploaded file. Can be given as command
    *   line arguments in form `--arg=value`.
@@ -628,8 +634,10 @@ export class Client extends EventEmitter2<ClientEventMap> {
   /**
    * 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()}.
+   * You cannot delete other users' files unless you are an administrator.
+   *
+   * You cannot delete a version file, 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. For more information, see
@@ -642,6 +650,9 @@ export class Client extends EventEmitter2<ClientEventMap> {
   /**
    * Downloads the specified file from the server.
    *
+   * You cannot download other users' files unless they have explicitly granted you `readSourceFile`
+   * access or you are an administrator.
+   *
    * @param fileId - File ID.
    * @param onProgress - Download progress callback.
    * @param signal - An
@@ -666,14 +677,17 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
 
   /**
-   * Returns a list of jobs started by the current logged in user.
+   * Returns a list of jobs from the server.
    *
-   * @param status - Filter the jobs by status. Status can be `waiting`, `inpogress`, `done` or `failed`.
+   * You cannot list other users' jobs unless you are an administrator.
+   *
+   * @param status - Filter the jobs by status. Status can be `waiting`, `inprogress`, `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 are
    *   sorted by creation time in ascending order.
-   * @param {boolean} sortField - Allows to specify sort field.
+   * @param sortField - Allows to specify sort field. Can be `createdAt`, `startedAt`, or `lastUpdate`.
    */
   getJobs(
     status?: string | string[],
@@ -713,6 +727,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
   /**
    * Returns information about the specified job.
    *
+   * You cannot retrieve other users' jobs unless you are an administrator.
+   *
    * @param jobId - Job ID.
    */
   getJob(jobId: string): Promise<Job> {
@@ -723,7 +739,10 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Runs a new job on the server for the specified file.
+   * Creates a new job on the server for the specified file.
+   *
+   * You cannot create jobs for other users' files unless they have explicitly granted you `createJob`
+   * access or you are an administrator.
    *
    * @param fileId - File ID.
    * @param outputFormat - The job type. Can be one of:
@@ -733,7 +752,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    *   - `properties` - Extract file properties.
    *   - `validation` - Validate the IFC file.
    *   - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the specified format.
-   *   - Other custom job name. Custom job must be registered in the job templates before running.
+   *   - Other custom job name. Custom job must be registered in the job templates.
    *
    * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
    *   object or command line arguments in form `--arg=value`.
@@ -750,8 +769,13 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Deletes the specified job from the server job list. Jobs that are in progress or have already been
-   * completed cannot be deleted.
+   * Deletes the specified job from the server.
+   *
+   * You cannot delete other users' jobs unless you are an administrator.
+   *
+   * You can only delete jobs that are in the `waiting` status (jobs that have been created but not yet
+   * started). Jobs that are currently running (`inprogress`) or have already completed (`done` or
+   * `failed`) cannot be deleted.
    *
    * @param jobId - Job ID.
    * @returns Returns the raw data of a deleted job. For more information, see
@@ -782,7 +806,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @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.
+   * @param sortField - Allows to specify sort field. Can be `name` or `created`.
    */
   getAssemblies(
     start?: number,
@@ -916,13 +940,16 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @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.
+   * @param sortField - Allows to specify sort field. Can be `name`, `createdAt`, `updatedAt`,
+   *   `startDate`, or `endDate`.
    */
   getProjects(
     start?: number,
     limit?: number,
     name?: string,
     ids?: string | string[],
-    sortByDesc?: boolean
+    sortByDesc?: boolean,
+    sortField?: string
   ): Promise<{
     result: Project[];
     start: number;
@@ -939,6 +966,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
       if (ids) searchParams.set("id", ids);
     }
     if (sortByDesc !== undefined) searchParams.set("sortBy", sortByDesc ? "desc" : "asc");
+    if (sortField) searchParams.set("sortField", sortField);
 
     let queryString = searchParams.toString();
     if (queryString) queryString = "?" + queryString;
@@ -1044,7 +1072,10 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Creates a shared link for the specified file.
+   * Creates a file shared link.
+   *
+   * Only file owner can create shared link. If the current logged in user is not a file owner, an
+   * exception will be thrown.
    *
    * @param fileId - File ID.
    * @param permissions - Share permissions.
@@ -1060,7 +1091,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Deletes the specified shared link.
+   * Deletes the specified file shared link.
    *
    * Only file owner can delete shared link. If the current logged in user is not a file owner, an
    * exception will be thrown.
@@ -1074,12 +1105,12 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Returns information about a file from a shared link.
+   * Returns information about a file for specified shared link token.
    *
    * Some file features are not available via shared link:
    *
    * - Updating file properties, preview, and viewpoints
-   * - Running file jobs
+   * - Creating file jobs
    * - Managing file permissions
    * - Managing file versions
    * - Deleting file
@@ -1110,8 +1141,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
   /**
    * Returns information about the specified plugin.
    *
-   * Only administrators can get plugins. If the current logged in user is not an administrator, they can
-   * only get themselves, otherwise an exception will be thrown.
+   * Only administrators can list plugins. If the current logged in user is not an administrator, an
+   * exception will be thrown.
    *
    * @param name - Plugin name.
    * @param version - Plugin version.
@@ -1164,8 +1195,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
   /**
    * Downloads the specified plugin package from the server.
    *
-   * Only administrators can download plugins. If the current logged in user is not an administrator, an
-   * exception will be thrown.
+   * Only administrators can download plugin packages. If the current logged in user is not an
+   * administrator, an exception will be thrown.
    *
    * @param name - Plugin name.
    * @param version - Plugin version.

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 run the File Converter job using
+   * To export file to one of the supported formats create the File Converter job using
    * {@link createJob | createJob()}. For an example, see the {@link downloadResource} help.
    *
    * @readonly
@@ -189,7 +189,7 @@ export class File extends Endpoint {
   }
 
   /**
-   * File owner information.
+   * File owner (the user who uploaded the file to the server).
    *
    * @readonly
    */
@@ -248,7 +248,7 @@ export class File extends Endpoint {
    *
    * Each status entity is a record with properties:
    *
-   * - `state` - Job state. Can be `none`, `waiting`, `inprogress`, `done` or `failed`.
+   * - `state` - Job state. Can be `none`, `waiting`, `inprogress`, `done`, or `failed`.
    * - `jobId` - Unique ID of the job.
    *
    * @readonly
@@ -314,6 +314,9 @@ export class File extends Endpoint {
   /**
    * Updates file data on the server.
    *
+   * You cannot update other users' files unless they have explicitly granted you `write` access or you
+   * are an administrator.
+   *
    * @param data - Raw file data. For more information, see
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
    */
@@ -326,8 +329,10 @@ export class File extends Endpoint {
   /**
    * 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()}.
+   * You cannot delete other users' files unless you are an administrator.
+   *
+   * You cannot delete a version file, only the original file. To delete a version file use
+   * {@link deleteVersion | deleteVersion()}.
    *
    * @returns Returns the raw data of a deleted file. For more information, see
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
@@ -421,7 +426,7 @@ export class File extends Endpoint {
    *   });
    *   ```
    *
-   *   or when running the {@link extractProperties | extract file properties} job:
+   *   or when creating the {@link extractProperties | extract file properties} job:
    *
    *   ```javascript
    *   await file.extractProperties("--properties_group");
@@ -557,7 +562,10 @@ export class File extends Endpoint {
   }
 
   /**
-   * Downloads the source file of active version of the file from the server.
+   * Downloads the active version of the file from the server.
+   *
+   * You cannot download other users' files unless they have explicitly granted you `readSourceFile`
+   * access or you are an administrator.
    *
    * @param onProgress - Download progress callback.
    * @param signal - An
@@ -574,6 +582,9 @@ 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.
    *
+   * You cannot download resources of other users' files unless they have explicitly granted you `read`
+   * access or you are an administrator.
+   *
    * @example Export file to PDF.
    *
    * ```javascript
@@ -662,7 +673,10 @@ export class File extends Endpoint {
   }
 
   /**
-   * Runs a new job on the server for the active version of the file.
+   * Creates a new job on the server for the active version of the file.
+   *
+   * You cannot create jobs for other users' files unless they have explicitly granted you `createJob`
+   * access or you are an administrator.
    *
    * @param outputFormat - The job type. Can be one of:
    *
@@ -673,7 +687,7 @@ export class File extends Endpoint {
    *   - `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 must be registered in the job templates before running.
+   *   - Other custom job name. Custom job must be registered in the job templates.
    *
    * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
    *   object or command line arguments in form `--arg=value`.
@@ -691,7 +705,7 @@ export class File extends Endpoint {
   }
 
   /**
-   * Runs a File Converter job to convert geometry data of active version of the file to the specified
+   * Creates 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:
@@ -707,8 +721,8 @@ export class File extends Endpoint {
   }
 
   /**
-   * Runs a File Converter job to extract properties of the active version of the file. This is alias to
-   * {@link createJob | createJob("properties")}.
+   * Creates 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 File Converter job. Can be given as command line arguments in
    *   form `--arg=value`.
@@ -718,7 +732,7 @@ export class File extends Endpoint {
   }
 
   /**
-   * Runs an IFC validator job to validate the active version of the file. This is alias to
+   * Creates 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")}.
@@ -798,12 +812,12 @@ export class File extends Endpoint {
   }
 
   /**
-   * Creates a new file permission for a user, project, or group.
+   * Grants specified file permissions to user, project, group, or all users.
    *
-   * @example Grant the specified user permission to "update" the file.
+   * @example Grant the specified user permission to "read" the file.
    *
    * ```javascript
-   * const action = "update";
+   * const action = "read";
    * const grantedTo = { user: { id: myUser.id, email: myUser.email } };
    * await file.createPermission(action, grantedTo);
    * ```
@@ -816,15 +830,16 @@ export class File extends Endpoint {
    * await file.createPermission(actions, grantedTo);
    * ```
    *
-   * @param actions - Actions are allowed to be performed on a file with this permission:
+   * @param actions - A single action or list of actions allowed for this permission:
    *
    *   - `read` - The ability to read file description, geometry data and properties.
    *   - `readSourceFile` - The ability to download 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.
+   *   - `createViewpoint` - The ability to create new file viewpoints.
+   *   - `deleteViewpoint` - The ability to delete existing file viewpoints.
    *
-   * @param grantedTo - An entity or a list of entities that will get access to the file.
+   * @param grantedTo - A user, project, or group that will get access to the file.
    * @param _public - Specifies whether all users have access to the file or not.
    */
   createPermission(
@@ -842,7 +857,7 @@ export class File extends Endpoint {
   }
 
   /**
-   * Removes the specified permission from the file.
+   * Revokes specified file permission.
    *
    * @param permissionId - Permission ID.
    * @returns Returns the raw data of a deleted permission. For more information, see
@@ -938,7 +953,7 @@ export class File extends Endpoint {
   }
 
   /**
-   * Deletes the specified version file.
+   * Deletes the specified file version.
    *
    * @param version - Version to delete.
    * @returns Returns the raw data of a deleted version file. For more information, see
@@ -1013,7 +1028,7 @@ export class File extends Endpoint {
   }
 
   /**
-   * Returns information about the file shared link or `undefined` if file is not shared.
+   * Returns information about the file shared link or `undefined` if file is not shared yet.
    */
   async getSharedLink(): Promise<SharedLink> {
     if (!this.sharedLinkToken) return Promise.resolve(undefined);

package/src/Api/IFile.ts

@@ -26,7 +26,7 @@
  */
 export interface IFileDataStatus {
   /**
-   * Data state. Can be `none`, `waiting`, `inprogress`, `done` or `failed`.
+   * Data state. Can be `none`, `waiting`, `inprogress`, `done`, or `failed`.
    */
   state: string;
 

package/src/Api/Job.ts

@@ -51,7 +51,8 @@ export class Job extends Endpoint {
   }
 
   /**
-   * Job creator ID. Use {@link Client.getUser | Client.getUser()} to obtain detailed creator information.
+   * Job owner ID (the user who created the job). Use {@link Client.getUser | Client.getUser()} to obtain
+   * detailed user information.
    *
    * @readonly
    */
@@ -148,7 +149,7 @@ export class Job extends Endpoint {
   }
 
   /**
-   * Job status. Can be `waiting`, `inprogress`, `done` or `failed`.
+   * Job status. Can be `waiting`, `inprogress`, `done`, or `failed`.
    *
    * @readonly
    */
@@ -200,8 +201,13 @@ export class Job extends Endpoint {
   }
 
   /**
-   * Deletes a job from the server job list. Jobs that are in progress or have already been completed
-   * cannot be deleted.
+   * Deletes a job from the server.
+   *
+   * You cannot delete other users' jobs unless you are an administrator.
+   *
+   * You can only delete jobs that are in the `waiting` status (jobs that have been created but not yet
+   * started). Jobs that are currently running (`inprogress`) or have already completed (`done` or
+   * `failed`) cannot be deleted.
    *
    * @returns Returns the raw data of a deleted job. For more information, see
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Jobs | Open Cloud Jobs API}.
@@ -222,8 +228,8 @@ export class Job extends Endpoint {
    * 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 jobs is not
-   *   done during this time, the `TimeoutError` exception will be thrown.
+   * @param params.timeout - The time, in milliseconds that the function should wait for the job. If the
+   *   job is not done during this time, the `TimeoutError` exception will be thrown.
    * @param params.interval - The time, in milliseconds, the function should delay in between checking
    *   job status.
    * @param params.signal - An

package/src/Api/Permission.ts

@@ -51,8 +51,9 @@ export class Permission extends Endpoint {
    * - `write` - The ability to modify file name, description and references.
    * - `readViewpoint` - The ability to read file viewpoints.
    * - `createViewpoint` - The ability to create file viewpoints.
+   * - `deleteViewpoint` - The ability to delete file viewpoints.
    *
-   * @example Change file permissions for the the specified project.
+   * @example Change file permissions for the specified project.
    *
    * ```javascript
    * const myFile = client.getFile(myFileId);
@@ -60,7 +61,7 @@ export class Permission extends Endpoint {
    * const projectPermissions = permissions.filter((permission) =>
    *   permission.grantedTo.some((x) => x.project?.id === myProjectId)
    * );
-   * const newActions = ["read", "readSourceFile", "update"];
+   * const newActions = ["read", "readSourceFile"];
    * await Promise.all(
    *   projectPermissions.map((permission) => {
    *     permission.actions = newActions;

package/src/Api/Project.ts

@@ -168,7 +168,7 @@ export class Project extends Endpoint {
   }
 
   /**
-   * Project owner information.
+   * Project owner (the user who created the project).
    *
    * @readonly
    */
@@ -501,11 +501,11 @@ export class Project extends Endpoint {
    *   - `write` - The ability to modify file name, description and references.
    *   - `readViewpoint` - The ability to read file viewpoints.
    *   - `createViewpoint` - The ability to create file viewpoints.
+   *   - `deleteViewpoint` - The ability to delete file viewpoints.
    *
-   * @param _public - Specifies whether all users have access to the file or not.
    * @returns Returns a file instance added to the project.
    */
-  async addModel(fileId: string, actions: string | string[], _public: boolean): Promise<File> {
+  async addModel(fileId: string, actions: string | string[]): Promise<File> {
     const files = new Endpoint("/files", this.httpClient, this.headers);
     const file = await files
       .get(`/${fileId}`)
@@ -513,7 +513,7 @@ export class Project extends Endpoint {
       .then((data) => new File(data, this.httpClient));
 
     const grantedTo = [{ project: { id: this.id, name: this.name } }];
-    await file.createPermission(actions, grantedTo, _public);
+    await file.createPermission(actions, grantedTo);
 
     return file;
   }

package/src/Api/User.ts

@@ -233,7 +233,7 @@ export class User extends Endpoint {
   }
 
   /**
-   * The identity provider used to create the account. Can be `ldap`, `oauth`, `saml` or empty for local
+   * The identity provider used to create the account. Can be `ldap`, `oauth`, `saml`, or empty for local
    * accounts.
    *
    * @readonly