@inweb/client 25.9.3 → 25.9.5

package/lib/Api/Assembly.d.ts

@@ -1,11 +1,11 @@
 import { IHttpClient } from "./IHttpClient";
 import { IAssociatedFileData, IAssemblyVersionInfo, IModelTransformMatrix } from "./IAssembly";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 import { Model } from "./Model";
 import { ClashTest } from "./ClashTest";
 /**
- * Provides properties and methods for obtaining information about an assembly on the server
- * and managing its data.
+ * Provides properties and methods for obtaining information about an assembly on the Open
+ * Cloud Server and managing its data.
  */
 export declare class Assembly {
     private _data;
@@ -14,7 +14,7 @@ export declare class Assembly {
     path: string;
     /**
      * @param data - Raw assembly data received from the server.
-     * @param httpClient - HTTP client instance used to send REST API requests to the server.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server..
      */
     constructor(data: any, httpClient: IHttpClient);
     appendVersionParam(relativePath: string): string;
@@ -72,17 +72,9 @@ export declare class Assembly {
     /**
      * Assembly owner information.
      *
-     * @property {string} userId - User ID.
-     * @property {string} userName - User name.
-     * @property {string} name - First name.
-     * @property {string} lastName - Last name.
-     * @property {string} fullName - Full name.
-     * @property {string} initials - Initials.
-     * @property {string} email - User email.
-     * @property {string} avatarUrl - User avatar image URL.
      * @readonly
      */
-    get owner(): IShortUserDescription;
+    get owner(): IShortUserDesc;
     get previewUrl(): string;
     /**
      * List of assembly related job IDs.

package/lib/Api/ClashTest.d.ts

@@ -1,5 +1,5 @@
 import { IHttpClient } from "./IHttpClient";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 /**
  * Provides properties and methods for obtaining information about a file/assembly clash detection test.
  */
@@ -10,7 +10,7 @@ export declare class ClashTest {
     /**
      * @param data - Raw test data received from the server.
      * @param basePath - The clash test API base path of the file/assembly that owns the test.
-     * @param httpClient - HTTP client instance used to send REST API requests to the server.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server.
      */
     constructor(data: any, basePath: string, httpClient: IHttpClient);
     protected internalGet(relativePath: string): Promise<Response>;
@@ -62,17 +62,9 @@ export declare class ClashTest {
     /**
      * Test owner information.
      *
-     * @property {string} userId - User ID.
-     * @property {string} userName - User name.
-     * @property {string} name - First name.
-     * @property {string} lastName - Last name.
-     * @property {string} fullName - Full name.
-     * @property {string} initials - Initials.
-     * @property {string} email - User email.
-     * @property {string} avatarUrl - User avatar image URL.
      * @readonly
      */
-    get owner(): IShortUserDescription;
+    get owner(): IShortUserDesc;
     /**
      * First selection set for clash detection. Objects from `selectionSetA` will be tested
      * against each others by objects from the `selectionSetB` during the test.

package/lib/Api/Client.d.ts

@@ -7,7 +7,8 @@ import { Job } from "./Job";
 import { Project } from "./Project";
 import { User } from "./User";
 /**
- * Provides methods for managing server resources such as users, files, assemblies, jobs, projects, etc.
+ * Provides methods for managing Open Cloud Server resources such as users, files, assemblies,
+ * jobs, projects, etc.
  */
 export declare class Client extends EventEmitter2<ClientEventMap> {
     private _serverUrl;
@@ -24,13 +25,13 @@ export declare class Client extends EventEmitter2<ClientEventMap> {
         url?: string;
     });
     /**
-     * Open Cloud Server REST API base URL. Use {@link configure | configure()} to change server URL.
+     * Open Cloud REST API server base URL. Use {@link configure | configure()} to change server URL.
      *
      * @readonly
      */
     get serverUrl(): string;
     /**
-     * HTTP client instance used to send REST API requests and receive responses from the server.
+     * HTTP client instance used to send requests to the REST API server.
      *
      * @readonly
      */

package/lib/Api/FetchError.d.ts

@@ -6,8 +6,14 @@ export declare function error400(text: string, _default?: string): string;
  * occurs, access denied, or object not found.
  */
 export declare class FetchError extends Error {
-    protected status: number;
-    protected statusText: string;
+    /**
+     * {@link https://developer.mozilla.org/docs/Web/HTTP/Status | HTTP status code} of the response.
+     */
+    status: number;
+    /**
+     * Status message corresponding to the {@link status | status code}.
+     */
+    statusText: string;
     /**
      * @property status - The
      *   {@link https://developer.mozilla.org/docs/Web/HTTP/Status | HTTP status code} of the response.

package/lib/Api/File.d.ts

@@ -1,12 +1,12 @@
 import { IHttpClient } from "./IHttpClient";
-import { IFileStatus, IFileReferences, IFileVersionInfo } from "./IFile";
-import { IShortUserDescription } from "./IUser";
+import { IFileStatus, IFileReferences, IFileVersionInfo, IGrantedTo } from "./IFile";
+import { IShortUserDesc } from "./IUser";
 import { Model } from "./Model";
 import { Permission } from "./Permission";
 import { Job } from "./Job";
 /**
- * Provides properties and methods for obtaining information about a file on the server and
- * managing its data and versions.
+ * Provides properties and methods for obtaining information about a file on the Open Cloud
+ * Server and managing its data and versions.
  */
 export declare class File {
     private _data;
@@ -15,7 +15,7 @@ export declare class File {
     path: string;
     /**
      * @param data - Raw file data received from the server.
-     * @param httpClient - HTTP client instance used to send REST API requests to the server.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server.
      */
     constructor(data: any, httpClient: IHttpClient);
     private appendVersionParam;
@@ -99,17 +99,9 @@ export declare class File {
     /**
      * File owner information.
      *
-     * @property {string} userId - User ID.
-     * @property {string} userName - User name.
-     * @property {string} name - First name.
-     * @property {string} lastName - Last name.
-     * @property {string} fullName - Full name.
-     * @property {string} initials - Initials.
-     * @property {string} email - User email.
-     * @property {string} avatarUrl - User avatar image URL.
      * @readonly
      */
-    get owner(): IShortUserDescription;
+    get owner(): IShortUserDesc;
     /**
      * File preview image URL or empty string if the file does not have a preview. Use
      * {@link setPreview | setPreview()} to change preview image.
@@ -161,17 +153,9 @@ export declare class File {
     /**
      * Information about the user who made the last update.
      *
-     * @property {string} userId - User ID.
-     * @property {string} userName - User name.
-     * @property {string} name - First name.
-     * @property {string} lastName - Last name.
-     * @property {string} fullName - Full name.
-     * @property {string} initials - Initials.
-     * @property {string} email - User email.
-     * @property {string} avatarUrl - User avatar image URL.
      * @readonly
      */
-    get updatedBy(): IShortUserDescription;
+    get updatedBy(): IShortUserDesc;
     /**
      * Zero-based file version number for version files. The original file has version `0`.
      */
@@ -482,7 +466,17 @@ export declare class File {
      */
     getPermission(permissionId: string): Promise<Permission>;
     /**
-     * Creates a new file permission.
+     * Creates a new file permission for a user, project, or group.
+     *
+     * @example <caption>Grant the specified user permission to "update" the file.</caption>
+     *   const action = "update";
+     *   const grantedTo = [{ user: { id: myUser.id, email: myUser.email } }];
+     *   await file.createPermission(action, grantedTo);
+     *
+     * @example <caption>Add a file to the specified project in `read-only` mode.</caption>
+     *   const actions = ["read", "readSourceFile"];
+     *   const grantedTo = [{ project: { id: myProject.id, name: myProject.name } }];
+     *   await file.createPermission(actions, grantedTo);
      *
      * @param actions - Actions are allowed to be performed on a file with this permission:
      *
@@ -492,10 +486,10 @@ export declare class File {
      *   - `readViewpoint` - The ability to read file viewpoints.
      *   - `createViewpoint` - The ability to create file viewpoints.
      *
-     * @param grantedTo - A list of principials that will get access to the file.
+     * @param grantedTo - A list of entities that will get access to the file.
      * @param _public - Specifies whether all users have access to the file or not.
      */
-    createPermission(actions: string | string[], grantedTo: any[], _public: boolean): Promise<Permission>;
+    createPermission(actions: string | string[], grantedTo: IGrantedTo[], _public: boolean): Promise<Permission>;
     /**
      * Removes the specified permission from the file.
      *

package/lib/Api/HttpClient.d.ts

@@ -11,7 +11,7 @@ export declare class HttpClient implements IHttpClient {
     delete(relativePath: string): Promise<Response>;
     uploadFile(relativePath: string, file: File, onProgress?: (progress: number) => void): Promise<XMLHttpRequest>;
     downloadFile(relativePath: string, onProgress?: (progress: number, chunk: Uint8Array) => void, signal?: AbortSignal): Promise<Response>;
-    downloadFileRange(relativePath: string, requestId: number, ranges: Array<{
+    downloadFileRange(relativePath: string, reserved: number, ranges: Array<{
         begin: number;
         end: number;
         requestId: number;

package/lib/Api/IFile.d.ts

@@ -1,12 +1,36 @@
+/**
+ * Defines the data status.
+ */
 export interface IFileDataStatus {
+    /**
+     * Data state. Can be `none`, `waiting`, `inprogress`, `done` or `failed`.
+     */
     state: string;
+    /**
+     * Unique ID of the data job.
+     */
     jobId?: string;
     jobUrl?: string;
 }
+/**
+ * Defines the file status.
+ */
 export interface IFileStatus {
+    /**
+     * Status of geometry data of `vsfx` type.
+     */
     geometry: IFileDataStatus;
+    /**
+     * Status of geometry data of `gltf` type.
+     */
     geometryGltf: IFileDataStatus;
+    /**
+     * Status of the properties.
+     */
     properties: IFileDataStatus;
+    /**
+     * Status of the validation.
+     */
     validation: IFileDataStatus;
 }
 /**
@@ -43,3 +67,51 @@ export interface IFileVersionInfo {
     size: number;
     ownerId: string;
 }
+/**
+ * Defines the entity, that will have access to the {@link File | file}.
+ */
+export interface IGrantedTo {
+    /**
+     * The user that has access to the file.
+     */
+    user?: {
+        /**
+         * User ID.
+         */
+        id: string;
+        /**
+         * User email.
+         */
+        email: string;
+    };
+    /**
+     * The project that has access to the file.
+     */
+    project?: {
+        /**
+         * Project ID.
+         */
+        id: string;
+        /**
+         * Project name.
+         */
+        name: string;
+    };
+    /**
+     * The group that has access to the file.
+     */
+    group?: {
+        /**
+         * Project ID.
+         */
+        projectId: string;
+        /**
+         * Group ID.
+         */
+        groupId: string;
+        /**
+         * Group name.
+         */
+        name: string;
+    };
+}

package/lib/Api/IHttpClient.d.ts

@@ -1,15 +1,96 @@
+/**
+ * Defines the HTTP client used to send requests to the REST API server.
+ */
 export interface IHttpClient {
+    /**
+     * REST API server base URL.
+     */
     serverUrl: string;
+    /**
+     * Request HTTP headers. You can add specific headers after user log in.
+     *
+     * The following headers are added automatically:
+     *
+     * - `Authorization`- Added after user log in.
+     * - `Content-Type` - Added before sending `POST` and `PUT` request according the request body.
+     */
     headers: HeadersInit;
+    /**
+     * Current logged in user ID.
+     */
     signInUserId: string;
+    /**
+     * `True` if the current logged in user is and administrator.
+     */
     signInUserIsAdmin: boolean;
+    /**
+     * Sends the GET request to the specified endpoint.
+     *
+     * @param relativePath - Endpoint relative path.
+     * @param signal - An
+     *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
+     *   signal, which can be used to abort waiting as desired.
+     */
     get(relativePath: string, signal?: AbortSignal): Promise<Response>;
+    /**
+     * Sends the POST request to the specified endpoint.
+     *
+     * @param relativePath - Endpoint relative path.
+     * @param body - Request body. Can be
+     *   {@link https://developer.mozilla.org/docs/Web/API/FormData | FormData},
+     *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
+     *   {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob}, JSON object or plain text.
+     */
     post(relativePath: string, body?: BodyInit | object): Promise<Response>;
+    /**
+     * Sends the PUT request to the specified endpoint.
+     *
+     * @param relativePath - Endpoint relative path.
+     * @param body - Request body. Can be
+     *   {@link https://developer.mozilla.org/docs/Web/API/FormData | FormData},
+     *   {@link https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer | ArrayBuffer},
+     *   {@link https://developer.mozilla.org/docs/Web/API/Blob/Blob | Blob}, JSON object or plain text.
+     */
     put(relativePath: string, body?: BodyInit | object): Promise<Response>;
+    /**
+     * Sends the DELETE request to the specified endpoint.
+     *
+     * @param relativePath - Endpoint relative path.
+     */
     delete(relativePath: string): Promise<Response>;
+    /**
+     * Upload a file to the server.
+     *
+     * @param relativePath - File relative path.
+     * @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 onProgress - Upload progress callback.
+     */
     uploadFile(relativePath: string, file: globalThis.File, onProgress?: (progress: number) => void): Promise<XMLHttpRequest>;
+    /**
+     * Downloads the specified file from the server.
+     *
+     * @param relativePath - File relative path.
+     * @param onProgress - Download progress callback.
+     * @param signal - An
+     *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
+     *   signal. Allows to communicate with a fetch request and abort it if desired.
+     */
     downloadFile(relativePath: string, onProgress?: (progress: number, chunk: Uint8Array) => void, signal?: AbortSignal): Promise<Response>;
-    downloadFileRange(relativePath: string, requestId: number, ranges: Array<{
+    /**
+     * Downloads a part of file from the server.
+     *
+     * @param relativePath - File relative path.
+     * @param reserved - Reserved, do not use.
+     * @param ranges - A range of resource file contents to download.
+     * @param onProgress - Download progress callback.
+     * @param signal - An
+     *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController}
+     *   signal. Allows to communicate with a fetch request and abort it if desired.
+     */
+    downloadFileRange(relativePath: string, reserved: number, ranges: Array<{
         begin: number;
         end: number;
         requestId: number;

package/lib/Api/IRole.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Defines the {@link Role | role} actions are allowed to be performed.
+ */
+export interface IRoleActions {
+    /**
+     * Defines what actions are allowed to be performed at the project level. The available
+     * actions include:
+     *
+     * - `update` - The ability to update the project details.
+     * - `createTopic` - The ability to create a new topic.
+     * - `createDocument` - The ability to create a new document.
+     */
+    projectActions?: string[];
+    /**
+     * Defines what actions are allowed to be performed at the topic level. The available actions include:
+     *
+     * - `update` - The ability to update the topic.
+     * - `updateBimSnippet` - The ability to update the BIM snippet for topics.
+     * - `updateRelatedTopics` - The ability to update the collection of related topics.
+     * - `updateDocumentReferences` - The ability to update the collection of document references.
+     * - `updateFiles` - The ability to update the file header.
+     * - `createComment` - The ability to create a comment.
+     * - `createViewpoint` - The ability to create a new viewpoint.
+     */
+    topicActions?: string[];
+    /**
+     * Defines what actions are allowed to be performed at the comment level. The available
+     * actions include:
+     *
+     * - `update` - The ability to update the comment.
+     * - `delete` - The ability to delete the comment.
+     */
+    commentActions?: string[];
+    /**
+     * Defines what actions are allowed to be performed at the viewpoint level. The available
+     * actions include:
+     *
+     * - `update` - The ability to update the viewpoint.
+     * - `delete` - The ability to delete the viewpoint.
+     */
+    viewpointActions?: string[];
+    /**
+     * Defines what actions are allowed to be performed at the groups level. The available actions include:
+     *
+     * - `create` - The ability to create the group.
+     * - `update` - The ability to update the group.
+     * - `updateUser` - The ability to add users to the group.
+     * - `delete` - The ability to delete the group.
+     */
+    odaGroupActions?: string[];
+    /**
+     * Defines what actions are allowed to be performed at the roles level. The available actions include:
+     *
+     * - `create` - The ability to create the role.
+     * - `update` - The ability to update the role.
+     * - `delete` - The ability to delete the role.
+     */
+    odaRoleActions?: string[];
+}

package/lib/Api/IUser.d.ts

@@ -1,10 +1,39 @@
-export interface IShortUserDescription {
+/**
+ * Defines brief user information.
+ */
+export interface IShortUserDesc {
+    /**
+     * Unique user ID.
+     */
     userId: string;
+    /**
+     * User name.
+     */
     userName: string;
+    /**
+     * First name.
+     */
     name: string;
+    /**
+     * Last name.
+     */
     lastName: string;
+    /**
+     * User email.
+     */
     email: string;
+    /**
+     * User avatar image URL or empty string if the user does not have an avatar.
+     */
     avatarUrl?: string;
+    /**
+     * User full name. Contains the user's first and last name. If first name and last names are
+     * empty, contains the user name.
+     */
     fullName?: string;
+    /**
+     * User initials. Contains a first letters of the user's first and last names. If first name
+     * and last names are empty, contains the first letter of the user name.
+     */
     initials?: string;
 }

package/lib/Api/Job.d.ts

@@ -1,13 +1,13 @@
 import { IHttpClient } from "./IHttpClient";
 /**
- * Provides properties and methods for obtaining information about a job on the server.
+ * Provides properties and methods for obtaining information about a job on the Open Cloud Server.
  */
 export declare class Job {
     private _data;
     httpClient: IHttpClient;
     /**
      * @param data - Raw job data received from the server.
-     * @param httpClient - HTTP client instance used to send REST API requests to the server.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server.
      */
     constructor(data: any, httpClient: IHttpClient);
     protected internalGet(): Promise<Response>;

package/lib/Api/Member.d.ts

@@ -1,5 +1,5 @@
 import { IHttpClient } from "./IHttpClient";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 /**
  * Provides properties and methods for obtaining information about a {@link User | user} who has
  * access to the {@link Project | project}.
@@ -11,7 +11,7 @@ export declare class Member {
     /**
      * @param data - Raw member data received from the server.
      * @param projectId - Owner project ID.
-     * @param httpClient - HTTP client instance used to send REST API requests to the server.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server.
      */
     constructor(data: any, projectId: string, httpClient: IHttpClient);
     private internalGet;
@@ -31,7 +31,8 @@ export declare class Member {
      */
     get id(): string;
     /**
-     * Member role. See {@link Project.getRoles | Project.getRoles()} for more details.
+     * Member role name in the project. See {@link Project.getRoles | Project.getRoles()} for list
+     * of project roles.
      */
     get role(): string;
     set role(value: string);
@@ -44,17 +45,9 @@ export declare class Member {
     /**
      * User information.
      *
-     * @property {string} userId - User ID.
-     * @property {string} userName - User name.
-     * @property {string} name - First name.
-     * @property {string} lastName - Last name.
-     * @property {string} fullName - Full name.
-     * @property {string} initials - Initials.
-     * @property {string} email - User email.
-     * @property {string} avatarUrl - User avatar image URL.
      * @readonly
      */
-    get user(): IShortUserDescription;
+    get user(): IShortUserDesc;
     /**
      * Reloads member data from the server.
      */

package/lib/Api/Permission.d.ts

@@ -1,4 +1,5 @@
 import { IHttpClient } from "./IHttpClient";
+import { IGrantedTo } from "./IFile";
 /**
  * Provides properties and methods for obtaining information about {@link File | file} actions
  * granted to a specific {@link User | users}, or project {@link Member | member}.
@@ -10,7 +11,7 @@ export declare class Permission {
     /**
      * @param data - Raw permission data received from the server.
      * @param fileId - Owner file ID.
-     * @param httpClient - HTTP client instance used to send REST API requests to the server.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server.
      */
     constructor(data: any, fileId: string, httpClient: IHttpClient);
     private internalGet;
@@ -41,22 +42,10 @@ export declare class Permission {
      */
     get id(): string;
     /**
-     * Principials are any entity that can be authenticated by the server, such as a any user or
-     * project that will get access to the file.
-     *
-     * @typedef {any} Principial
-     * @property {any} user - The user entry that get access to the file.
-     * @property {string} user.id - User ID.
-     * @property {string} user.name - User name.
-     * @property {any} project - The project entry that get access to the file.
-     * @property {string} project.id - Project ID.
-     * @property {string} project.name - Project name.
-     */
-    /**
-     * A list of principials that will get access to the file.
+     * A list of entities that will get access to the file.
      */
-    get grantedTo(): any[];
-    set grantedTo(value: any[]);
+    get grantedTo(): IGrantedTo[];
+    set grantedTo(value: IGrantedTo[]);
     /**
      * Specifies whether all users have access to the file or not.
      */
@@ -69,6 +58,17 @@ export declare class Permission {
     /**
      * Updates permission data on the server.
      *
+     * @example <caption>Update file permissions for the the specified project.</caption>
+     *   const myFile = client.getFile(myFileId);
+     *   const permissions = await myFile.getPermissions();
+     *   const projectPermissions = permissions.filter((permission) =>
+     *     permission.grantedTo.some((x) => x.project?.id === myProjectId)
+     *   );
+     *   const newActions = ["read", "readSourceFile", "update"];
+     *   await Promise.allSettled(
+     *     projectPermissions.map((permission) => permission.update({ newActions }))
+     *   );
+     *
      * @param data - Raw permission data.
      */
     update(data: any): Promise<this>;