@inweb/client 25.12.0 → 26.1.0

package/src/Api/Client.ts

@@ -33,6 +33,9 @@ import { Job } from "./Job";
 import { Project } from "./Project";
 import { User } from "./User";
 import { OAuthClient } from "./OAuthClient";
+import { ISharedLinkPermissions } from "./ISharedLink";
+import { SharedLink } from "./SharedLink";
+import { SharedFile } from "./SharedFile";
 import { parseArgs } from "./Utils";
 
 /**
@@ -47,7 +50,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
 
   /**
    * @param params - An object containing client configuration parameters.
-   * @param params.serverUrl - Open Cloud Server REST API base URL.
+   * @param params.serverUrl - Open Cloud REST API server URL.
    * @param params.url - Deprecated since `25.8`. Use `serverUrl` instead.
    */
   constructor(params: { serverUrl?: string; url?: string } = {}) {
@@ -56,7 +59,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
   }
 
   /**
-   * Open Cloud REST API server base URL. Use {@link configure | configure()} to change server URL.
+   * Open Cloud REST API server URL. Use {@link configure | configure()} to change server URL.
    *
    * @readonly
    */
@@ -124,7 +127,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * After changing the parameters, you must re-login.
    *
    * @param params - An object containing new parameters.
-   * @param params.serverUrl - Open Cloud Server REST API base URL.
+   * @param params.serverUrl - Open Cloud REST API server URL.
    */
   configure(params: { serverUrl?: string }): this {
     this._serverUrl = (params.serverUrl || "").replace(/\/+$/, "");
@@ -203,7 +206,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
   async signInWithEmail(email: string, password: string): Promise<User> {
     const credentials = btoa(unescape(encodeURIComponent(email + ":" + password)));
-    this.httpClient.headers = { Authorization: "Basic " + credentials };
+    this.httpClient.headers["Authorization"] = "Basic " + credentials;
     const response = await this.httpClient.get("/token");
     const data = await response.json();
     return this.setCurrentUser(data);
@@ -215,17 +218,27 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @param token - An access token for authentication request. See {@link User.token} for more details.
    */
   async signInWithToken(token: string): Promise<User> {
-    this.httpClient.headers = { Authorization: token };
+    this.httpClient.headers["Authorization"] = token;
     const response = await this.httpClient.get("/user");
     const data = await response.json();
     return this.setCurrentUser(data);
   }
 
+  /**
+   * Log out.
+   *
+   * You must log in again using {@link signInWithEmail} or {@link signInWithToken} to continue
+   * making requests to the server
+   */
+  signOut(): void {
+    this.clearCurrentUser();
+  }
+
   // Save the current logged in user information for internal use.
 
   private setCurrentUser(data: any): User {
     this._user = new User(data, this.httpClient);
-    this.httpClient.headers = { Authorization: data.tokenInfo.token };
+    this.httpClient.headers["Authorization"] = data.tokenInfo.token;
     this.httpClient.signInUserId = this._user.id;
     this.httpClient.signInUserIsAdmin = this._user.isAdmin;
     return this._user;
@@ -233,7 +246,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
 
   private clearCurrentUser(): void {
     this._user = null;
-    this.httpClient.headers = {};
+    delete this.httpClient.headers["Authorization"];
     this.httpClient.signInUserId = "";
     this.httpClient.signInUserIsAdmin = false;
   }
@@ -520,6 +533,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @param sortByDesc - Allows to specify the descending order of the result. By default,
    *   files are sorted by name in ascending order.
    * @param sortField - Allows to specify sort field.
+   * @param shared - Returns shared files only.
    */
   getFiles(
     start?: number,
@@ -528,7 +542,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
     ext?: string | string[],
     ids?: string | string[],
     sortByDesc?: boolean,
-    sortField?: string
+    sortField?: string,
+    shared?: boolean
   ): Promise<{
     result: File[];
     start: number;
@@ -551,6 +566,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
     }
     if (sortByDesc !== undefined) searchParams.set("sortBy", sortByDesc ? "desc" : "asc");
     if (sortField) searchParams.set("sortField", sortField);
+    if (shared) searchParams.set("shared", "true");
 
     let queryString = searchParams.toString();
     if (queryString) queryString = "?" + queryString;
@@ -668,7 +684,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
    */
   downloadFile(fileId: string, onProgress?: (progress: number) => void, signal?: AbortSignal): Promise<ArrayBuffer> {
     return this.httpClient
-      .downloadFile(`/files/${fileId}/downloads`, onProgress, signal)
+      .downloadFile(`/files/${fileId}/downloads`, onProgress, { signal })
       .then((response) => response.arrayBuffer());
   }
 
@@ -1038,4 +1054,67 @@ export class Client extends EventEmitter2<ClientEventMap> {
         }
       });
   }
+
+  /**
+   * Returns information about the specified file shared link.
+   *
+   * @param token - Shared link token.
+   */
+  getSharedLink(token: string): Promise<SharedLink> {
+    return this.httpClient
+      .get(`/shares/${token}`)
+      .then((response) => response.json())
+      .then((data) => new SharedLink(data, this.httpClient));
+  }
+
+  /**
+   * Creates a shared link for the specified file.
+   *
+   * @param fileId - File ID.
+   * @param permissions - Share permissions.
+   */
+  createSharedLink(fileId: string, permissions?: ISharedLinkPermissions): Promise<SharedLink> {
+    return this.httpClient
+      .post("/shares", {
+        fileId,
+        permissions,
+      })
+      .then((response) => response.json())
+      .then((data) => new SharedLink(data, this.httpClient));
+  }
+
+  /**
+   * Deletes the specified shared link.
+   *
+   * Only file owner can delete shared link. If the current logged in user is not a file owner,
+   * an exception will be thrown.
+   *
+   * @param token - Shared link token.
+   * @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}.
+   */
+  deleteSharedLink(token: string): Promise<any> {
+    return this.httpClient.delete(`/shares/${token}`).then((response) => response.json());
+  }
+
+  /**
+   * Returns information about a file from a shared link.
+   *
+   * Some file features are not available via shared link:
+   *
+   * - Updating file properties, preview, and viewpoints
+   * - Running file jobs
+   * - Managing file permissions
+   * - Managing file versions
+   * - Deleting file
+   *
+   * @param token - Shared link token.
+   * @param password - Password to get access to the file.
+   */
+  getSharedFile(token: string, password?: string): Promise<File> {
+    return this.httpClient
+      .get(`/shares/${token}/info`, { headers: { "InWeb-Password": password } })
+      .then((response) => response.json())
+      .then((data) => new SharedFile(data, password, this.httpClient));
+  }
 }

package/src/Api/Endpoint.ts

@@ -0,0 +1,130 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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.
+///////////////////////////////////////////////////////////////////////////////
+
+import { IHttpClient } from "./IHttpClient";
+
+/**
+ * Base class for the REST API endpoints.
+ */
+export class Endpoint {
+  /**
+   * Endpoint API path relative to the REST API server URL.
+   */
+  public path: string;
+
+  /**
+   * Endpoint-specific HTTP headers for the `GET`, `POST`, `PUT` and `DELETE` requests. You can
+   * add custom headers at any time.
+   */
+  public headers: HeadersInit;
+
+  public httpClient: IHttpClient;
+  private _useVersion: number | undefined;
+
+  /**
+   * @ignore
+   * @param path - The API path of the endpoint relative to the REST API server URL of the
+   *   specified HTTP client.
+   * @param httpClient - HTTP client instance used to send requests to the REST API server.
+   * @param headers - Endpoint-specific HTTP headers.
+   */
+  constructor(path: string, httpClient: IHttpClient, headers = {}) {
+    this.path = path;
+    this.httpClient = httpClient;
+    this.headers = headers;
+  }
+
+  appendVersionParam(relativePath: string): string {
+    if (this._useVersion === undefined) return relativePath;
+    const delimiter = relativePath.includes("?") ? "&" : "?";
+    return `${relativePath}${delimiter}version=${this._useVersion}`;
+  }
+
+  /**
+   * Returns the endpoint API path.
+   *
+   * @ignore
+   * @param relativePath - Nested endpoint relative path.
+   */
+  getEndpointPath(relativePath: string): string {
+    return this.appendVersionParam(`${this.path}${relativePath}`);
+  }
+
+  /**
+   * Sends the `GET` request to the endpoint.
+   *
+   * @ignore
+   * @param relativePath - Nested endpoint relative path.
+   * @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.
+   */
+  get(relativePath: string, signal?: AbortSignal): Promise<Response> {
+    return this.httpClient.get(this.getEndpointPath(relativePath), { signal, headers: this.headers });
+  }
+
+  /**
+   * Sends the `POST` request to the endpoint.
+   *
+   * @ignore
+   * @param relativePath - Nested 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> {
+    return this.httpClient.post(this.getEndpointPath(relativePath), body, { headers: this.headers });
+  }
+
+  /**
+   * Sends the `PUT` request to the endpoint.
+   *
+   * @ignore
+   * @param relativePath - Nested 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> {
+    return this.httpClient.put(this.getEndpointPath(relativePath), body, { headers: this.headers });
+  }
+
+  /**
+   * Sends the `DELETE` request to the endpoint.
+   *
+   * @ignore
+   * @param relativePath - Nested endpoint relative path.
+   */
+  delete(relativePath: string): Promise<Response> {
+    return this.httpClient.delete(this.getEndpointPath(relativePath), { headers: this.headers });
+  }
+
+  // Internal: append the `version` param to the endpoint requests.
+
+  useVersion(version?: number): this {
+    this._useVersion = version;
+    return this;
+  }
+}

package/src/Api/Fetch.ts

@@ -47,38 +47,38 @@ function handleFetchError(response: Response): Promise<Response> {
 
 export function $fetch(
   url: string,
-  params: {
-    method: "GET" | "POST" | "PUT" | "DELETE";
+  init: {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "HEAD";
     headers?: HeadersInit;
-    body?: BodyInit | object;
+    body?: BodyInit | object | null;
     signal?: AbortSignal;
   } = { method: "GET" }
 ): Promise<Response> {
-  const headers = { ...params.headers };
+  const headers = { ...init.headers };
   delete headers["Content-Type"];
 
+  Object.keys(headers)
+    .filter((x) => headers[x] === undefined)
+    .forEach((x) => delete headers[x]);
+
   let body: FormData | string | undefined = undefined;
-  if (params.method === "POST" || params.method === "PUT") {
-    if (params.body instanceof FormData) {
-      body = params.body;
-    } else if (params.body instanceof Blob) {
+  if (init.method === "POST" || init.method === "PUT") {
+    if (init.body instanceof FormData) {
+      body = init.body;
+    } else if (init.body instanceof Blob) {
       body = new FormData();
-      body.append("file", params.body);
-    } else if (params.body instanceof ArrayBuffer) {
+      body.append("file", init.body);
+    } else if (init.body instanceof ArrayBuffer) {
       body = new FormData();
-      body.append("file", new Blob([params.body]));
-    } else if (typeof params.body === "object") {
-      body = JSON.stringify(params.body);
+      body.append("file", new Blob([init.body]));
+    } else if (typeof init.body === "object") {
+      body = JSON.stringify(init.body);
       headers["Content-Type"] = "application/json";
-    } else if (typeof params.body === "string") {
-      body = params.body;
+    } else if (typeof init.body === "string") {
+      body = init.body;
       headers["Content-Type"] = "text/plain";
     }
   }
 
-  const init: RequestInit = { method: params.method, headers };
-  if (body) init.body = body;
-  if (params.signal) init.signal = params.signal;
-
-  return fetch(url, init).then(handleFetchError);
+  return fetch(url, { ...init, headers, body }).then(handleFetchError);
 }