@inweb/client/src/Api/Permission.ts

JavaScript REST API client for the Open Cloud Server

///////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2002-2025, 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-2025 by Open Design Alliance.
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

import { IHttpClient } from "./IHttpClient";
import { Endpoint } from "./Endpoint";
import { IGrantedTo } from "./IFile";

/**
 * Provides properties and methods for obtaining information about {@link File | file} actions granted to
 * a specific user, project, or group.
 */
export class Permission extends Endpoint {
  private _data: any;

  /**
   * @param data - Raw permission data received from the server. For more information, see
   *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Permission | Open Cloud Permissions API}.
   * @param fileId - Owner file ID.
   * @param httpClient - HTTP client instance used to send requests to the REST API server.
   */
  constructor(data: any, fileId: string, httpClient: IHttpClient) {
    super(`/files/${fileId}/permissions/${data.id}`, httpClient);
    this.data = data;
  }

  /**
   * Defines what actions are allowed to be performed on a file with this permission:
   *
   * - `read` - The ability to read file description, geometry data and properties.
   * - `readSourceFile` - The ability to download source file.
   * - `write` - The ability to modify file name, description and references.
   * - `readViewpoint` - The ability to read file viewpoints.
   * - `createViewpoint` - The ability to create file viewpoints.
   *
   * @example Change file permissions for the the specified project.
   *
   * ```javascript
   * 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.all(
   *   projectPermissions.map((permission) => {
   *     permission.actions = newActions;
   *     return permission.save();
   *   })
   * );
   * ```
   */
  get actions(): string[] {
    return this.data.actions;
  }

  set actions(value: string[]) {
    this._data.actions = value;
  }

  /**
   * Raw permission data received from the server. For more information, see
   * {@link https://cloud.opendesign.com/docs//pages/server/api.html#Permission | Open Cloud Permissions API}.
   *
   * @readonly
   */
  get data(): any {
    return this._data;
  }

  private set data(value: any) {
    this._data = value;
  }

  /**
   * Unique permission ID.
   *
   * @readonly
   */
  get id(): string {
    return this.data.id;
  }

  /**
   * A list of users, projects, or groups that will get access to the file.
   */
  get grantedTo(): IGrantedTo[] {
    return this.data.grantedTo;
  }

  set grantedTo(value: IGrantedTo[]) {
    this.data.grantedTo = value;
  }

  /**
   * Specifies whether all users have access to the file or not.
   */
  get public(): boolean {
    return this.data.public;
  }

  set public(value: boolean) {
    this.data.public = value;
  }

  /**
   * Reloads permission data from the server.
   */
  async checkout(): Promise<this> {
    const response = await this.get("");
    this.data = await response.json();
    return this;
  }

  /**
   * Updates permission data on the server.
   *
   * @param data - Raw permission data. For more information, see
   *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Permission | Open Cloud Permissions API}.
   */
  async update(data: any): Promise<this> {
    const response = await this.put("", data);
    this.data = await response.json();
    return this;
  }

  /**
   * Removes a permission from the file.
   *
   * @returns Returns the raw data of a deleted permission. For more information, see
   *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Permission | Open Cloud Permissions API}.
   */
  override delete(): Promise<any> {
    return super.delete("").then((response) => response.json());
  }

  /**
   * Saves permission properties changes to the server. Call this method to update permission data on the
   * server after any property changes.
   */
  save(): Promise<this> {
    return this.update(this.data);
  }
}