@inweb/client 25.9.2 → 25.9.4

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 { 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.2",
+  "version": "25.9.4",
   "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.2"
+    "@inweb/eventemitter2": "~25.9.4"
   }
 }

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/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;
   }
 
@@ -808,6 +792,16 @@ export class File {
   /**
    * Creates a new file permission.
    *
+   * @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:
    *
    *   - `read` - The ability to read file description, geometry data and properties.
@@ -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

@@ -72,3 +72,38 @@ export interface IFileVersionInfo {
   size: number;
   ownerId: string;
 }
+
+/**
+ * Defines the entity, that will have access to the file.
+ */
+export interface IGrantedTo {
+  /**
+   * The user entry that has access to the file.
+   */
+  user?: {
+    /**
+     * User ID.
+     */
+    id: string;
+
+    /**
+     * User email.
+     */
+    email: string;
+  };
+
+  /**
+   * The project entry that has access to the file.
+   */
+  project?: {
+    /**
+     * Project ID.
+     */
+    id: string;
+
+    /**
+     * Project 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

package/src/Api/IRole.ts

@@ -0,0 +1,88 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2024, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2024 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
+/**
+ * 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/src/Api/IUser.ts

@@ -21,13 +21,49 @@
 // acknowledge and accept the above terms.
 ///////////////////////////////////////////////////////////////////////////////
 
-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/src/Api/Job.ts

@@ -25,7 +25,7 @@ import { IHttpClient } from "./IHttpClient";
 import { waitFor } from "./Utils";
 
 /**
- * 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 class Job {
   private _data: any;
@@ -33,7 +33,7 @@ export class Job {
 
   /**
    * @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) {
     this.httpClient = httpClient;

package/src/Api/Member.ts

@@ -22,7 +22,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { IHttpClient } from "./IHttpClient";
-import { IShortUserDescription } from "./IUser";
+import { IShortUserDesc } from "./IUser";
 import { userFullName, userInitials } from "./Utils";
 
 /**
@@ -37,7 +37,7 @@ export 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) {
     this.httpClient = httpClient;
@@ -83,7 +83,8 @@ export class Member {
   }
 
   /**
-   * 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 {
     return this.data.role;
@@ -105,17 +106,9 @@ export 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 {
     return this.data.user;
   }