@inweb/client 25.9.3 → 25.9.5

package/lib/Api/Project.d.ts

@@ -1,17 +1,19 @@
 import { IHttpClient } from "./IHttpClient";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 import { Role } from "./Role";
+import { IRoleActions } from "./IRole";
 import { Member } from "./Member";
+import { File } from "./File";
 /**
- * Provides properties and methods for obtaining information about a project on the server and
- * managing its {@link Role | roles}, {@link Member | members} and models.
+ * Provides properties and methods for obtaining information about a project on the Open Cloud
+ * Server and managing its {@link Role | roles}, {@link Member | members} and models.
  */
 export declare class Project {
     private _data;
     httpClient: IHttpClient;
     /**
      * @param data - Raw project 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(relativePath: string): Promise<Response>;
@@ -89,17 +91,9 @@ export declare class Project {
     /**
      * Project 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;
     /**
      * Project preview image URL or empty string if the project does not have a preview. Use
      * {@link Project.setPreview | setPreview()} to change preview image.
@@ -184,10 +178,9 @@ export declare class Project {
      *
      * @param name - Role name.
      * @param description - Role description.
-     * @param permissions - Actions are allowed to be performed. See {@link Role.permissions} for
-     *   more details.
+     * @param permissions - Actions are allowed to be performed for the role.
      */
-    createRole(name: string, description: string, permissions: any): Promise<Role>;
+    createRole(name: string, description: string, permissions: IRoleActions): Promise<Role>;
     /**
      * Deletes the specified project role.
      *
@@ -206,14 +199,14 @@ export declare class Project {
      */
     getMember(memberId: string): Promise<Member>;
     /**
-     * Add a user to the project to become a member and have permission to perform actions.
+     * Adds a user to the project to become a member and have permission to perform actions.
      *
      * @param userId - User ID.
-     * @param role - Role name from the list of project roles.
+     * @param role - Role name from the list of project {@link getRoles | roles}.
      */
     addMember(userId: string, role: string): Promise<Member>;
     /**
-     * Remove the specified member from a project.
+     * Removes the specified member from a project.
      *
      * @param memberId - Member ID.
      * @returns Returns the raw data of a deleted member.
@@ -232,8 +225,40 @@ export declare class Project {
      * @property {string} file.reference - File ID.
      */
     /**
-     * Returns a list of project files. To add a file to this list, create a `project` permission
-     * on the file using {@link File.createPermission | File.createPermission()}.
+     * Returns a list of project files.
+     *
+     * This list contains all files that the project has access to. To add a file to this list,
+     * create a {@link IGrantedTo.project | project} permission on the file using
+     * {@link File.createPermission | File.createPermission()}.
      */
     getFilesInformation(): Promise<any[]>;
+    /**
+     * Returns a list of project models.
+     */
+    getModels(): Promise<File[]>;
+    /**
+     * Adds a file to the project with specified permissions.
+     *
+     * To change file permissions for the project use {@link Permission.update | Permissions.update()}.
+     *
+     * @param fileId - File ID.
+     * @param actions - Actions are allowed to be performed on a file:
+     *
+     *   - `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 _public - Specifies whether all users have access to the file or not.
+     * @returns Returns a file instance added to the project.
+     */
+    addModel(fileId: string, actions: string | string[], _public: boolean): Promise<File>;
+    /**
+     * Removes the specified file from a project.
+     *
+     * @param fileId - File ID.
+     * @returns Returns a file instance removed from the project.
+     */
+    removeModel(fileId: string): Promise<File>;
 }

package/lib/Api/Role.d.ts

@@ -1,4 +1,5 @@
 import { IHttpClient } from "./IHttpClient";
+import { IRoleActions } from "./IRole";
 /**
  * A role determines what actions allowed to be performed by {@link User | users} on a
  * {@link Project | project}.
@@ -10,7 +11,7 @@ export declare class Role {
     /**
      * @param data - Raw role 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;
@@ -35,23 +36,9 @@ export declare class Role {
     set name(value: string);
     /**
      * Role actions are allowed to be performed.
-     *
-     * @property {string[]} projectActions - Actions are allowed to be performed at the project
-     *   level: `update`, `createTopic`, `createDocument`.
-     * @property {string[]} topicActions - Actions are allowed to be performed at the topic
-     *   level: `update`, `updateBimSnippet`, `updateRelatedTopics`, `updateDocumentReferences`,
-     *   `updateFiles`, `createComment`, `createViewpoint`, `delete`.
-     * @property {string[]} commentActions - Actions are allowed to be performed at the comment
-     *   level: `update`, `delete`.
-     * @property {string[]} viewpointActions - Actions are allowed to be performed at the
-     *   viewpoint level: `delete`.
-     * @property {string[]} odaGroupActions - Actions are allowed to be performed at the members
-     *   level: `update`, `delete`.
-     * @property {string[]} odaRoleActions - Actions are allowed to be performed at the roles
-     *   level: `update`, `delete`.
      */
-    get permissions(): any;
-    set permissions(value: any);
+    get permissions(): IRoleActions;
+    set permissions(value: IRoleActions);
     /**
      * Reloads role data from the server.
      */

package/lib/Api/User.d.ts

@@ -1,13 +1,14 @@
 import { IHttpClient } from "./IHttpClient";
 /**
- * Provides properties and methods for obtaining information about a server user and manage its data.
+ * Provides properties and methods for obtaining information about a Open Cloud Server user and
+ * manage its data.
  */
 export declare class User {
     private _data;
     httpClient: IHttpClient;
     /**
      * @param data - Raw user 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);
     /**

package/lib/index.d.ts

@@ -5,7 +5,11 @@ export * from "./Api/ClientEvents";
 export { File } from "./Api/File";
 export { FetchError, statusText } from "./Api/FetchError";
 export { Job } from "./Api/Job";
+export { IHttpClient } from "./Api/IHttpClient";
 export { IModelTransformMatrix } from "./Api/IAssembly";
+export { IFileDataStatus, IFileReference, IFileReferences, IFileStatus, IGrantedTo } from "./Api/IFile";
+export { IRoleActions } from "./Api/IRole";
+export { IShortUserDesc } from "./Api/IUser";
 export { Member } from "./Api/Member";
 export { Model } from "./Api/Model";
 export { Permission } from "./Api/Permission";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/client",
-  "version": "25.9.3",
+  "version": "25.9.5",
   "description": "JavaScript REST API client for the Open Cloud Server",
   "homepage": "https://cloud.opendesign.com/docs/index.html",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,6 +26,6 @@
     "docs": "typedoc"
   },
   "dependencies": {
-    "@inweb/eventemitter2": "~25.9.3"
+    "@inweb/eventemitter2": "~25.9.5"
   }
 }

package/src/Api/Assembly.ts

@@ -24,14 +24,14 @@
 import { IHttpClient } from "./IHttpClient";
 import { FetchError } from "./FetchError";
 import { IAssociatedFileData, IAssemblyVersionInfo, IModelTransformMatrix } from "./IAssembly";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 import { Model } from "./Model";
 import { ClashTest } from "./ClashTest";
 import { waitFor, userFullName, userInitials } from "./Utils";
 
 /**
- * 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 class Assembly {
   private _data: any;
@@ -41,7 +41,7 @@ export class Assembly {
 
   /**
    * @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) {
     this.path = `/assemblies/${data.id}`;
@@ -168,17 +168,9 @@ export 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 {
     return this.data.owner;
   }
 

package/src/Api/ClashTest.ts

@@ -22,7 +22,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { IHttpClient } from "./IHttpClient";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 import { waitFor, userFullName, userInitials } from "./Utils";
 
 /**
@@ -36,7 +36,7 @@ export 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) {
     this.httpClient = httpClient;
@@ -129,17 +129,9 @@ export 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 {
     return this.data.owner;
   }
 

package/src/Api/Client.ts

@@ -35,7 +35,8 @@ import { User } from "./User";
 import { parseArgs } from "./Utils";
 
 /**
- * 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 class Client extends EventEmitter2<ClientEventMap> {
   private _serverUrl = "";
@@ -54,7 +55,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * 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
    */
@@ -63,7 +64,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * 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/src/Api/FetchError.ts

@@ -106,8 +106,15 @@ export function error400(text: string, _default = "400"): string {
  */
 
 export 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.
+   */
+  public status: number;
+
+  /**
+   * Status message corresponding to the {@link status | status code}.
+   */
+  public statusText: string;
 
   /**
    * @property status - The

package/src/Api/File.ts

@@ -22,16 +22,16 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 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";
 import { waitFor, parseArgs, userFullName, userInitials } from "./Utils";
 
 /**
- * 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 class File {
   private _data: any;
@@ -41,7 +41,7 @@ export class File {
 
   /**
    * @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) {
     this.path = `/files/${data.id}`;
@@ -217,17 +217,9 @@ export 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 {
     return this.data.owner;
   }
 
@@ -300,17 +292,9 @@ export 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 {
     return this.data.updatedBy;
   }
 
@@ -806,7 +790,17 @@ export class File {
   }
 
   /**
-   * 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:
    *
@@ -816,10 +810,10 @@ export 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> {
     return this.internalPost("/permissions", {
       actions: Array.isArray(actions) ? actions : [actions],
       grantedTo,

package/src/Api/HttpClient.ts

@@ -112,7 +112,7 @@ export class HttpClient implements IHttpClient {
 
   async downloadFileRange(
     relativePath: string,
-    requestId: number,
+    reserved: number,
     ranges: Array<{ begin: number; end: number; requestId: number }>,
     onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void,
     signal?: AbortSignal

package/src/Api/IFile.ts

@@ -21,16 +21,45 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * 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;
 }
 
@@ -72,3 +101,58 @@ 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/src/Api/IHttpClient.ts

@@ -21,35 +21,119 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
+/**
+ * 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>;
 
+  /**
+   * 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,
-    requestId: number,
+    reserved: number,
     ranges: Array<{ begin: number; end: number; requestId: number }>,
     onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void,
     signal?: AbortSignal