@inweb/client 25.9.3 → 25.9.5

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;
   }
 

package/src/Api/Permission.ts

@@ -22,6 +22,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { IHttpClient } from "./IHttpClient";
+import { IGrantedTo } from "./IFile";
 
 /**
  * Provides properties and methods for obtaining information about {@link File | file} actions
@@ -35,7 +36,7 @@ export 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) {
     this.httpClient = httpClient;
@@ -95,26 +96,13 @@ export class Permission {
   }
 
   /**
-   * 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 entities that will get access to the file.
    */
-
-  /**
-   * A list of principials that will get access to the file.
-   */
-  get grantedTo(): any[] {
+  get grantedTo(): IGrantedTo[] {
     return this.data.grantedTo;
   }
 
-  set grantedTo(value: any[]) {
+  set grantedTo(value: IGrantedTo[]) {
     this.data.grantedTo = value;
   }
 
@@ -141,6 +129,17 @@ export 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.
    */
   async update(data: any): Promise<this> {

package/src/Api/Project.ts

@@ -22,14 +22,16 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 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";
 import { userFullName, userInitials } from "./Utils";
 
 /**
- * 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 class Project {
   private _data: any;
@@ -37,7 +39,7 @@ export class Project {
 
   /**
    * @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) {
     this.httpClient = httpClient;
@@ -182,17 +184,9 @@ export 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 {
     return this.data.owner;
   }
 
@@ -351,10 +345,9 @@ export 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> {
     return this.internalPost("/roles", {
       name,
       description,
@@ -395,10 +388,10 @@ export class Project {
   }
 
   /**
-   * 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> {
     return this.internalPost("/members", { userId, role })
@@ -407,7 +400,7 @@ export class Project {
   }
 
   /**
-   * 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.
@@ -430,8 +423,11 @@ export class Project {
    */
 
   /**
-   * 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[]> {
     return this.httpClient
@@ -485,4 +481,70 @@ export class Project {
         return items;
       });
   }
+
+  /**
+   * Returns a list of project models.
+   */
+  getModels(): Promise<File[]> {
+    return this.getFilesInformation()
+      .then((filesInformation) => filesInformation.map((item) => item.file.reference))
+      .then((ids) => {
+        const searchParams = new URLSearchParams();
+        searchParams.set("id", ids.join("|"));
+        return this.httpClient.get(`/files?${searchParams.toString()}`);
+      })
+      .then((response) => response.json())
+      .then((files) => files.result.map((data) => new File(data, this.httpClient)));
+  }
+
+  /**
+   * 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.
+   */
+  async addModel(fileId: string, actions: string | string[], _public: boolean): Promise<File> {
+    const file = await this.httpClient
+      .get(`/files/${fileId}`)
+      .then((response) => response.json())
+      .then((data) => new File(data, this.httpClient));
+
+    const grantedTo = [{ project: { id: this.id, name: this.name } }];
+    await file.createPermission(actions, grantedTo, _public);
+
+    return file;
+  }
+
+  /**
+   * Removes the specified file from a project.
+   *
+   * @param fileId - File ID.
+   * @returns Returns a file instance removed from the project.
+   */
+  async removeModel(fileId: string): Promise<File> {
+    const file = await this.httpClient
+      .get(`/files/${fileId}`)
+      .then((response) => response.json())
+      .then((data) => new File(data, this.httpClient));
+
+    const permissions = await file.getPermissions();
+    await Promise.allSettled(
+      permissions
+        .filter((permission) => permission.grantedTo.some((x) => x.project?.id === this.id))
+        .map((permission) => permission.delete())
+    );
+
+    return file;
+  }
 }

package/src/Api/Role.ts

@@ -22,6 +22,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { IHttpClient } from "./IHttpClient";
+import { IRoleActions } from "./IRole";
 
 /**
  * A role determines what actions allowed to be performed by {@link User | users} on a
@@ -35,7 +36,7 @@ export 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) {
     this.httpClient = httpClient;
@@ -92,26 +93,12 @@ export class Role {
 
   /**
    * 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 {
+  get permissions(): IRoleActions {
     return this.data.permissions;
   }
 
-  set permissions(value: any) {
+  set permissions(value: IRoleActions) {
     this.data.permissions = value || {};
   }
 

package/src/Api/User.ts

@@ -26,7 +26,8 @@ import { FetchError } from "./FetchError";
 import { userFullName, userInitials } from "./Utils";
 
 /**
- * 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 class User {
   private _data: any;
@@ -34,7 +35,7 @@ export class User {
 
   /**
    * @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) {
     this.httpClient = httpClient;

package/src/index.ts

@@ -28,7 +28,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";