@inweb/client 25.12.0 → 26.1.0

package/src/Api/File.ts

@@ -22,22 +22,22 @@
 ///////////////////////////////////////////////////////////////////////////////
 
 import { IHttpClient } from "./IHttpClient";
+import { Endpoint } from "./Endpoint";
 import { ICdaNode, IFileStatus, IFileReferences, IFileVersionInfo, IGrantedTo } from "./IFile";
 import { IShortUserDesc } from "./IUser";
 import { Model } from "./Model";
 import { Permission } from "./Permission";
 import { Job } from "./Job";
+import { SharedLink } from "./SharedLink";
+import { ISharedLinkPermissions } from "./ISharedLink";
 import { waitFor, parseArgs, userFullName, userInitials } from "./Utils";
 
 /**
  * Provides properties and methods for obtaining information about a file on the Open Cloud
  * Server and managing its data and versions.
  */
-export class File {
+export class File extends Endpoint {
   private _data: any;
-  private _useVersion: number | undefined;
-  public httpClient: IHttpClient;
-  public path: string;
 
   /**
    * @param data - Raw file data received from the server. For more information, see
@@ -45,37 +45,10 @@ export class File {
    * @param httpClient - HTTP client instance used to send requests to the REST API server.
    */
   constructor(data: any, httpClient: IHttpClient) {
-    this.path = `/files/${data.id}`;
-    this.httpClient = httpClient;
+    super(`/files/${data.id}`, httpClient);
     this.data = data;
   }
 
-  private appendVersionParam(relativePath: string): string {
-    if (this._useVersion === undefined) return relativePath;
-    const delimiter = relativePath.includes("?") ? "&" : "?";
-    return `${relativePath}${delimiter}version=${this._useVersion}`;
-  }
-
-  private internalGet(relativePath: string, signal?: AbortSignal): Promise<Response> {
-    relativePath = this.appendVersionParam(relativePath);
-    return this.httpClient.get(`${this.path}${relativePath}`, signal);
-  }
-
-  private internalPost(relativePath: string, body?: BodyInit | object): Promise<Response> {
-    relativePath = this.appendVersionParam(relativePath);
-    return this.httpClient.post(`${this.path}${relativePath}`, body);
-  }
-
-  private internalPut(relativePath: string, body?: BodyInit | object): Promise<Response> {
-    relativePath = this.appendVersionParam(relativePath);
-    return this.httpClient.put(`${this.path}${relativePath}`, body);
-  }
-
-  private internalDelete(relativePath: string): Promise<Response> {
-    relativePath = this.appendVersionParam(relativePath);
-    return this.httpClient.delete(`${this.path}${relativePath}`);
-  }
-
   /**
    * Active version number of the file.
    *
@@ -97,8 +70,6 @@ export class File {
 
   /**
    * File custom fields object, to store custom data.
-   *
-   * @readonly
    */
   get customFields(): any {
     return this.data.customFields;
@@ -118,7 +89,7 @@ export class File {
     return this._data;
   }
 
-  private set data(value: any) {
+  set data(value: any) {
     this._data = value;
     this._data.previewUrl = value.preview
       ? `${this.httpClient.serverUrl}${this.path}/preview?updated=${value.updatedAt}`
@@ -145,6 +116,8 @@ export class File {
     this._data.status.geometryGltf ??= { state: "none" };
     // isFileDeleted since 25.7
     this._data.isFileDeleted ??= false;
+    // sharedLinkToken since 26.0
+    this._data.sharedLinkToken ??= null;
   }
 
   /**
@@ -154,6 +127,8 @@ export class File {
    * {@link createJob | createJob()}. To download exported file use
    * {@link downloadResource | downloadResource()}.
    *
+   * For an example of exporting files to other formats, see the {@link downloadResource} help.
+   *
    * @readonly
    */
   get exports(): string[] {
@@ -253,6 +228,15 @@ export class File {
     return this.data.sizeTotal;
   }
 
+  /**
+   * File shared link token or `null` if file is not shared yet.
+   *
+   * @readonly
+   */
+  get sharedLinkToken(): string {
+    return this.data.sharedLinkToken;
+  }
+
   /**
    * Data status of the active version of the file. Contains:
    *
@@ -321,7 +305,7 @@ export class File {
    * Reloads file data from the server.
    */
   async checkout(): Promise<this> {
-    const response = await this.internalGet("");
+    const response = await this.get("");
     this.data = await response.json();
     return this;
   }
@@ -333,7 +317,7 @@ export class File {
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
    */
   async update(data: any): Promise<this> {
-    const response = await this.internalPut("", data);
+    const response = await this.put("", data);
     this.data = await response.json();
     return this;
   }
@@ -347,8 +331,8 @@ export class File {
    * @returns Returns the raw data of a deleted file. For more information, see
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
    */
-  delete(): Promise<any> {
-    return this.internalDelete("").then((response) => response.json());
+  override delete(): Promise<any> {
+    return super.delete("").then((response) => response.json());
   }
 
   /**
@@ -374,7 +358,7 @@ export class File {
     if (!image) {
       await this.deletePreview();
     } else {
-      const response = await this.internalPost("/preview", image);
+      const response = await this.post("/preview", image);
       this.data = await response.json();
     }
     return this;
@@ -384,7 +368,7 @@ export class File {
    * Removes the file preview.
    */
   async deletePreview(): Promise<this> {
-    const response = await this.internalDelete("/preview");
+    const response = await super.delete("/preview");
     this.data = await response.json();
     return this;
   }
@@ -393,7 +377,7 @@ export class File {
    * Returns a list of models of the active version of the file.
    */
   getModels(): Promise<Model[]> {
-    return this.internalGet("/geometry")
+    return this.get("/geometry")
       .then((response) => response.json())
       .then((array) => array.map((data) => new Model(data, this)));
   }
@@ -425,7 +409,7 @@ export class File {
    */
   getProperties(handles?: string | string[]): Promise<any[]> {
     const relativePath = handles !== undefined ? `/properties?handles=${handles}` : "/properties";
-    return this.internalGet(relativePath).then((response) => response.json());
+    return this.get(relativePath).then((response) => response.json());
   }
 
   /**
@@ -473,14 +457,14 @@ export class File {
    */
 
   searchProperties(searchPattern: any): Promise<any[]> {
-    return this.internalPost("/properties/search", searchPattern).then((response) => response.json());
+    return this.post("/properties/search", searchPattern).then((response) => response.json());
   }
 
   /**
    * Returns the CDA tree for an active version of the file.
    */
   getCdaTree(): Promise<ICdaNode[]> {
-    return this.internalGet(`/properties/tree`).then((response) => response.json());
+    return this.get(`/properties/tree`).then((response) => response.json());
   }
 
   /**
@@ -488,7 +472,7 @@ export class File {
    * {@link https://cloud.opendesign.com/docs//pages/server/api.html#FileViewpoints | Open Cloud File Viewpoints API}.
    */
   getViewpoints(): Promise<any[]> {
-    return this.internalGet("/viewpoints")
+    return this.get("/viewpoints")
       .then((response) => response.json())
       .then((viewpoints) => viewpoints.result);
   }
@@ -500,7 +484,7 @@ export class File {
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#FileViewpoints | Open Cloud File Viewpoints API}.
    */
   saveViewpoint(viewpoint: any): Promise<any> {
-    return this.internalPost("/viewpoints", viewpoint).then((response) => response.json());
+    return this.post("/viewpoints", viewpoint).then((response) => response.json());
   }
 
   /**
@@ -511,7 +495,7 @@ export class File {
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#FileViewpoints | Open Cloud File Viewpoints API}.
    */
   deleteViewpoint(guid: string): Promise<any> {
-    return this.internalDelete(`/viewpoints/${guid}`).then((response) => response.json());
+    return super.delete(`/viewpoints/${guid}`).then((response) => response.json());
   }
 
   /**
@@ -521,7 +505,7 @@ export class File {
    * @param guid - Viewpoint GUID.
    */
   getSnapshot(guid: string): Promise<string> {
-    return this.internalGet(`/viewpoints/${guid}/snapshot`).then((response) => response.text());
+    return this.get(`/viewpoints/${guid}/snapshot`).then((response) => response.text());
   }
 
   /**
@@ -531,7 +515,7 @@ export class File {
    * @param bitmapGuid - Bitmap GUID.
    */
   getSnapshotData(guid: string, bitmapGuid: string): Promise<string> {
-    return this.internalGet(`/viewpoints/${guid}/bitmaps/${bitmapGuid}`).then((response) => response.text());
+    return this.get(`/viewpoints/${guid}/bitmaps/${bitmapGuid}`).then((response) => response.text());
   }
 
   /**
@@ -543,9 +527,8 @@ export class File {
    *   signal. Allows to communicate with a fetch request and abort it if desired.
    */
   download(onProgress?: (progress: number) => void, signal?: AbortSignal): Promise<ArrayBuffer> {
-    const relativePath = this.appendVersionParam("/downloads");
     return this.httpClient
-      .downloadFile(`${this.path}${relativePath}`, onProgress, signal)
+      .downloadFile(this.getEndpointPath("/downloads"), onProgress, { signal, headers: this.headers })
       .then((response) => response.arrayBuffer());
   }
 
@@ -559,7 +542,7 @@ export class File {
    *   const dwgFileName = file.exports.find((x) => x.endsWith(".dwg"));
    *   const arrayBuffer = await file.downloadResource(dwgFileName);
    *   const blob = new Blob([arrayBuffer]);
-   *   const fileName = file.name.replace(/\.[^.]+$/, "") + ".dwg";
+   *   const fileName = file.name + ".dwg";
    *   FileSaver.saveAs(blob, fileName);
    *
    * @param dataId - Resource file name.
@@ -573,9 +556,8 @@ export class File {
     onProgress?: (progress: number, chunk: Uint8Array) => void,
     signal?: AbortSignal
   ): Promise<ArrayBuffer> {
-    const relativePath = this.appendVersionParam(`/downloads/${dataId}`);
     return this.httpClient
-      .downloadFile(`${this.path}${relativePath}`, onProgress, signal)
+      .downloadFile(this.getEndpointPath(`/downloads/${dataId}`), onProgress, { signal, headers: this.headers })
       .then((response) => response.arrayBuffer());
   }
 
@@ -598,9 +580,14 @@ export class File {
     onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void,
     signal?: AbortSignal
   ): Promise<ArrayBuffer> {
-    const relativePath = this.appendVersionParam(`/downloads/${dataId}?requestId=${requestId}`);
     return this.httpClient
-      .downloadFileRange(`${this.path}${relativePath}`, requestId, ranges, onProgress, signal)
+      .downloadFileRange(
+        this.getEndpointPath(`/downloads/${dataId}?requestId=${requestId}`),
+        requestId,
+        ranges,
+        onProgress,
+        { signal, headers: this.headers }
+      )
       .then((response) => response.arrayBuffer());
   }
 
@@ -645,7 +632,7 @@ export class File {
    *   signal, which can be used to abort waiting as desired.
    */
   getReferences(signal?: AbortSignal): Promise<IFileReferences> {
-    return this.internalGet("/references", signal).then((response) => response.json());
+    return this.get("/references", signal).then((response) => response.json());
   }
 
   /**
@@ -657,7 +644,7 @@ export class File {
    * @param references - File references.
    */
   setReferences(references: IFileReferences): Promise<IFileReferences> {
-    return this.internalPut("/references", references).then((response) => response.json());
+    return this.put("/references", references).then((response) => response.json());
   }
 
   /**
@@ -679,9 +666,9 @@ export class File {
    *   for the File Converter tool in form `--arg=value`.
    */
   createJob(outputFormat: string, parameters?: string | object): Promise<Job> {
-    const relativePath = this.appendVersionParam("/jobs");
-    return this.httpClient
-      .post(relativePath, {
+    const jobs = new Endpoint("/jobs", this.httpClient, this.headers);
+    return jobs
+      .post(this.appendVersionParam(""), {
         fileId: this.id,
         outputFormat,
         parameters: parseArgs(parameters),
@@ -780,7 +767,7 @@ export class File {
    * Returns a list of file permissions.
    */
   getPermissions(): Promise<Permission[]> {
-    return this.internalGet("/permissions")
+    return this.get("/permissions")
       .then((response) => response.json())
       .then((array) => array.map((data) => new Permission(data, this.id, this.httpClient)));
   }
@@ -791,7 +778,7 @@ export class File {
    * @param permissionId - Permission ID.
    */
   getPermission(permissionId: string): Promise<Permission> {
-    return this.internalGet(`/permissions/${permissionId}`)
+    return this.get(`/permissions/${permissionId}`)
       .then((response) => response.json())
       .then((data) => new Permission(data, this.id, this.httpClient));
   }
@@ -812,7 +799,7 @@ export class File {
    * @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.
-   *   - `readSourceFile` - The ability to read source file.
+   *   - `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.
@@ -821,7 +808,7 @@ export class File {
    * @param _public - Specifies whether all users have access to the file or not.
    */
   createPermission(actions: string | string[], grantedTo: IGrantedTo[], _public: boolean): Promise<Permission> {
-    return this.internalPost("/permissions", {
+    return this.post("/permissions", {
       actions: Array.isArray(actions) ? actions : [actions],
       grantedTo,
       public: _public,
@@ -838,7 +825,7 @@ export class File {
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Permission | Open Cloud File Permissions API}.
    */
   deletePermission(permissionId: string): Promise<any> {
-    return this.internalDelete(`/permissions/${permissionId}`).then((response) => response.json());
+    return super.delete(`/permissions/${permissionId}`).then((response) => response.json());
   }
 
   /**
@@ -879,7 +866,9 @@ export class File {
     }
   ): Promise<File> {
     const result = await this.httpClient
-      .uploadFile(`${this.path}/versions`, file, (progress) => params.onProgress?.(progress, file))
+      .uploadFile(this.getEndpointPath("/versions"), file, (progress) => params.onProgress?.(progress, file), {
+        headers: this.headers,
+      })
       .then((xhr: XMLHttpRequest) => JSON.parse(xhr.responseText))
       .then((data) => new File(data, this.httpClient));
 
@@ -907,7 +896,7 @@ export class File {
    * Returns a list of version files.
    */
   getVersions(): Promise<File[]> {
-    return this.internalGet("/versions")
+    return this.get("/versions")
       .then((response) => response.json())
       .then((files) => files.map((data) => new File(data, this.httpClient)))
       .then((files) => files.map((file) => (file.id == file.originalFileId ? file.useVersion(0) : file)));
@@ -919,7 +908,7 @@ export class File {
    * @param version - Desired version.
    */
   getVersion(version: number): Promise<File> {
-    return this.internalGet(`/versions/${version}`)
+    return this.get(`/versions/${version}`)
       .then((response) => response.json())
       .then((data) => new File(data, this.httpClient))
       .then((file) => (file.id == file.originalFileId ? file.useVersion(0) : file));
@@ -933,7 +922,7 @@ export class File {
    *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Files | Open Cloud Files API}.
    */
   async deleteVersion(version: number): Promise<any> {
-    const response = await this.internalDelete(`/versions/${version}`);
+    const response = await super.delete(`/versions/${version}`);
     const data = await response.json();
     await this.checkout();
     return data;
@@ -974,17 +963,54 @@ export class File {
    * You need to reload the file data using {@link checkout | checkout()} to match the size and
    * status fields to the version you selected.
    */
-  useVersion(version?: number): this {
-    this._useVersion = version;
-    return this;
+  override useVersion(version?: number): this {
+    return super.useVersion(version);
   }
 
   /**
    * Deletes the source file of the active file version from the server.
    */
   async deleteSource(): Promise<this> {
-    const response = await this.internalDelete("/source");
+    const response = await super.delete("/source");
     this.data = await response.json();
     return this;
   }
+
+  /**
+   * Creates a file shared link.
+   *
+   * @param permissions - Share permissions.
+   */
+  async createSharedLink(permissions?: ISharedLinkPermissions): Promise<SharedLink> {
+    const shares = new Endpoint("/shares", this.httpClient, this.headers);
+    const response = await shares.post("", { fileId: this.id, permissions });
+    const data = await response.json();
+    await this.checkout();
+    return new SharedLink(data, this.httpClient);
+  }
+
+  /**
+   * Returns information about the file shared link or `undefined` if file is not shared.
+   */
+  async getSharedLink(): Promise<SharedLink> {
+    if (!this.sharedLinkToken) return Promise.resolve(undefined);
+    const shares = new Endpoint("/shares", this.httpClient, this.headers);
+    const response = await shares.get(`/${this.sharedLinkToken}`);
+    const data = await response.json();
+    return new SharedLink(data, this.httpClient);
+  }
+
+  /**
+   * Deletes the file shared link.
+   *
+   * @returns Returns the raw data of a deleted shared link. For more information, see
+   *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#ShareLinks | Open Cloud SharedLinks API}.
+   */
+  async deleteSharedLink(): Promise<any> {
+    const shares = new Endpoint("/shares", this.httpClient, this.headers);
+    const response = await shares.delete(`/${this.sharedLinkToken}`);
+    const data = await response.json();
+    await this.checkout();
+    return data;
+  }
 }

package/src/Api/HttpClient.ts

@@ -35,28 +35,51 @@ export class HttpClient implements IHttpClient {
     this.serverUrl = serverUrl;
   }
 
-  get(relativePath: string, signal?: AbortSignal): Promise<Response> {
-    return $fetch(`${this.serverUrl}${relativePath}`, { method: "GET", headers: this.headers, signal });
+  get(relativePath: string, init: RequestInit = {}): Promise<Response> {
+    return $fetch(`${this.serverUrl}${relativePath}`, {
+      ...init,
+      method: "GET",
+      headers: { ...this.headers, ...init.headers },
+    });
   }
 
-  post(relativePath: string, body?: BodyInit | object): Promise<Response> {
-    return $fetch(`${this.serverUrl}${relativePath}`, { method: "POST", headers: this.headers, body });
+  post(relativePath: string, body?: BodyInit | object, init: RequestInit = {}): Promise<Response> {
+    return $fetch(`${this.serverUrl}${relativePath}`, {
+      ...init,
+      method: "POST",
+      headers: { ...this.headers, ...init.headers },
+      body,
+    });
   }
 
-  put(relativePath: string, body?: BodyInit | object): Promise<Response> {
-    return $fetch(`${this.serverUrl}${relativePath}`, { method: "PUT", headers: this.headers, body });
+  put(relativePath: string, body?: BodyInit | object, init: RequestInit = {}): Promise<Response> {
+    return $fetch(`${this.serverUrl}${relativePath}`, {
+      ...init,
+      method: "PUT",
+      headers: { ...this.headers, ...init.headers },
+      body,
+    });
   }
 
-  delete(relativePath: string): Promise<Response> {
-    return $fetch(`${this.serverUrl}${relativePath}`, { method: "DELETE", headers: this.headers });
+  delete(relativePath: string, init: RequestInit = {}): Promise<Response> {
+    return $fetch(`${this.serverUrl}${relativePath}`, {
+      ...init,
+      method: "DELETE",
+      headers: { ...this.headers, ...init.headers },
+    });
   }
 
-  uploadFile(relativePath: string, file: File, onProgress?: (progress: number) => void): Promise<XMLHttpRequest> {
+  uploadFile(
+    relativePath: string,
+    file: File,
+    onProgress?: (progress: number) => void,
+    init: RequestInit = {}
+  ): Promise<XMLHttpRequest> {
     const data = new FormData();
     data.append("file", file);
     return $xmlhttp(`${this.serverUrl}${relativePath}`, {
       method: "POST",
-      headers: this.headers,
+      headers: { ...this.headers, ...init.headers },
       body: data,
       uploadProgress: onProgress,
     });
@@ -65,9 +88,9 @@ export class HttpClient implements IHttpClient {
   // async downloadFile(
   //   relativePath: string,
   //   onProgress?: (progress: number, chunk: Uint8Array) => void,
-  //   signal?: AbortSignal
+  //   init: RequestInit = {}
   // ): Promise<Response> {
-  //   const response = await this.get(relativePath, signal);
+  //   const response = await this.get(relativePath, init);
   //   const teedOff = response.body.tee();
   //   if (onProgress) {
   //     const contentLength = response.headers.get("Content-Length");
@@ -87,9 +110,9 @@ export class HttpClient implements IHttpClient {
   async downloadFile(
     relativePath: string,
     onProgress?: (progress: number, chunk: Uint8Array) => void,
-    signal?: AbortSignal
+    init: RequestInit = {}
   ): Promise<Response> {
-    const response = await this.get(relativePath, signal);
+    const response = await this.get(relativePath, init);
     const contentLength = response.headers.get("Content-Length");
     const total = parseInt(contentLength || "", 10) || 1;
     return new Response(
@@ -115,11 +138,11 @@ export class HttpClient implements IHttpClient {
     reserved: number,
     ranges: Array<{ begin: number; end: number; requestId: number }>,
     onProgress?: (progress: number, chunk: Uint8Array, requestId: number) => void,
-    signal?: AbortSignal
+    init: RequestInit = {}
   ): Promise<Response> {
-    const headers = { ...this.headers };
+    const headers = { ...init.headers };
     headers["Range"] = "bytes=" + ranges.map((x) => `${x.begin}-${x.end}`).join(",");
-    const response = await $fetch(`${this.serverUrl}${relativePath}`, { method: "GET", headers, signal });
+    const response = await this.get(relativePath, { ...init, headers });
     const contentLength = response.headers.get("content-length");
     const total = parseInt(contentLength || "", 10) || 1;
     return new Response(

package/src/Api/IFile.ts

@@ -129,7 +129,7 @@ export interface IFileVersionInfo {
 }
 
 /**
- * Defines the user, project, or group that will have access to the {@link File | file}.
+ * Defines the user, project, or group that will have access to the file.
  */
 export interface IGrantedTo {
   /**