@inweb/client 26.9.0 → 26.9.2

package/lib/Api/Client.d.ts

@@ -9,6 +9,7 @@ import { User } from "./User";
 import { OAuthClient } from "./OAuthClient";
 import { ISharedLinkPermissions } from "./ISharedLink";
 import { SharedLink } from "./SharedLink";
+import { Plugin } from "./Plugin";
 /**
  * Provides methods for managing Open Cloud Server resources such as users, files, assemblies, jobs,
  * projects, etc.
@@ -413,8 +414,8 @@ export declare class Client extends EventEmitter2<ClientEventMap> {
      *   - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the specified format.
      *   - Other custom job name. Custom job must be registered in the job templates before running.
      *
-     * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as command
-     *   line arguments in form `--arg=value`.
+     * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
+     *   object or command line arguments in form `--arg=value`.
      */
     createJob(fileId: string, outputFormat: string, parameters?: string | object): Promise<Job>;
     /**
@@ -468,8 +469,8 @@ export declare class Client extends EventEmitter2<ClientEventMap> {
      * @param name - Assembly name.
      * @param params - Additional assembly creating parameters.
      * @param params.jobParameters - Parameters for the File Converter jobs. Use this to specify aditional
-     *   parameters for generating the geometry and properties of the new assembly. Can be given as command
-     *   line arguments in form `--arg=value`.
+     *   parameters for generating the geometry and properties of the new assembly. Can be given as JSON
+     *   object or command line arguments in form `--arg=value`.
      * @param params.waitForDone - Wait for assembly to be created.
      * @param params.timeout - The time, in milliseconds, that the function should wait for the assembly to
      *   be created. If the assembly is not created within this time, a TimeoutError exception will be
@@ -589,4 +590,71 @@ export declare class Client extends EventEmitter2<ClientEventMap> {
      * @param password - Password to get access to the file.
      */
     getSharedFile(token: string, password?: string): Promise<File>;
+    /**
+     * Returns the list of installed plugins.
+     *
+     * Only administrators can get a list of plugins. If the current logged in user is not an
+     * administrator, an exception will be thrown.
+     */
+    getPlugins(): Promise<Plugin[]>;
+    /**
+     * Returns information about the specified plugin.
+     *
+     * Only administrators can get plugins. If the current logged in user is not an administrator, they can
+     * only get themselves, otherwise an exception will be thrown.
+     *
+     * @param name - Plugin name.
+     * @param version - Plugin version.
+     */
+    getPlugin(name: string, version: string): Promise<Plugin>;
+    /**
+     * Uploads and install a plugin package to the server. The package must be a ZIP file and undergoes
+     * verification, scanning, and health checks during installation.
+     *
+     * Only administrators can upload plugins. If the current logged in user is not an administrator, an
+     * exception will be thrown.
+     *
+     * @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.
+     */
+    uploadPlugin(file: globalThis.File, onProgress?: (progress: number, file: globalThis.File) => void): Promise<Plugin>;
+    /**
+     * Uninstalls and deletes the specified plugin from the server.
+     *
+     * Only administrators can delete plugins. If the current logged in user is not an administrator, an
+     * exception will be thrown.
+     *
+     * @param name - Plugin name.
+     * @param version - Plugin version.
+     */
+    deletePlugin(name: string, version: string): Promise<Plugin>;
+    /**
+     * Downloads the specified plugin package from the server.
+     *
+     * Only administrators can download plugins. If the current logged in user is not an administrator, an
+     * exception will be thrown.
+     *
+     * @param name - Plugin name.
+     * @param version - Plugin version.
+     * @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.
+     */
+    downloadPlugin(name: string, version: string, onProgress?: (progress: number) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
+    /**
+     * Executes a plugin command.
+     *
+     * If you have multiple versions of a plugin installed and want to run the command for the latest
+     * version of the plugin, specify `undefined` or empty string for the `version` parameter.
+     *
+     * @param name - Plugin name.
+     * @param version - Plugin version. Specify `undefined` or empty string to run the command for the
+     *   latest version of the plugin.
+     * @param command - Command to execute.
+     * @param parameters - Command parameters. Command-dependent.
+     */
+    executePluginCommand(name: string, version: string, command: string, parameters?: BodyInit | object): Promise<any>;
 }

package/lib/Api/File.d.ts

@@ -435,8 +435,8 @@ export declare class File extends Endpoint {
      *       {@link downloadResource | downloadResource()} to download the exported file.
      *   - Other custom job name. Custom job must be registered in the job templates before running.
      *
-     * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as command
-     *   line arguments in form `--arg=value`.
+     * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
+     *   object or command line arguments in form `--arg=value`.
      */
     createJob(outputFormat: string, parameters?: string | object): Promise<Job>;
     /**

package/lib/Api/Plugin.d.ts

@@ -0,0 +1,141 @@
+import { IHttpClient } from "./IHttpClient";
+import { Endpoint } from "./Endpoint";
+/**
+ * Provides properties and methods for obtaining information about a server plugin on the Open Cloud
+ * Server and managing its data.
+ */
+export declare class Plugin extends Endpoint {
+    private _data;
+    /**
+     * @param data - Raw plugin data received from the server. For more information, see
+     *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Plugin | Open Cloud Plugins API}.
+     * @param httpClient - HTTP client instance used to send requests to the REST API server.
+     */
+    constructor(data: any, httpClient: IHttpClient);
+    /**
+     * Plugin author information. The `author` is an object with a `name` field and optionally `url` and
+     * `email`. Or it can be shorten that all into a single string.
+     *
+     * @readonly
+     */
+    get author(): any;
+    /**
+     * Raw plugin data received from the server. For more information, see
+     * {@link https://cloud.opendesign.com/docs//pages/server/api.html#Plugin | Open Cloud Plugins API}.
+     */
+    get data(): any;
+    set data(value: any);
+    /**
+     * Short description of the plugin.
+     *
+     * @readonly
+     */
+    get description(): string;
+    /**
+     * Plugin state.
+     *
+     * @readonly
+     */
+    get enabled(): boolean;
+    /**
+     * The URL to the plugin homepage.
+     *
+     * @readonly
+     */
+    get homepage(): string;
+    /**
+     * Unique plugin ID.
+     *
+     * @readonly
+     */
+    get id(): string;
+    /**
+     * A license for the plugin.
+     *
+     * @readonly
+     */
+    get license(): string;
+    /**
+     * Plugin name.
+     *
+     * @readonly
+     */
+    get name(): string;
+    /**
+     * API permissions required.
+     *
+     * @readonly
+     */
+    get permissions(): string[];
+    /**
+     * Plugin type. Can be set of:
+     *
+     * - `app` - Viewer plugin, the client‑side web app that the server hosts and serves as static content.
+     * - `server` - Binary dll that extends server functionality.
+     * - `jobrunner` - Binary dll that adds a new Job Runner on the server.
+     *
+     * @readonly
+     */
+    get pluginType(): string[];
+    /**
+     * {@link https://semver.org/ | SemVer} compatible version of the plugin.
+     *
+     * @readonly
+     */
+    get version(): number;
+    /**
+     * Reloads plugin data from the server.
+     */
+    checkout(): Promise<this>;
+    /**
+     * Uninstalls and deletes a plugin from the server.
+     *
+     * @returns Returns the raw data of a deleted plugin. For more information, see
+     *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Plugin | Open Cloud Plugins API}.
+     */
+    delete(): Promise<any>;
+    /**
+     * Enables a plugin.
+     */
+    enable(): Promise<this>;
+    /**
+     * Disables a plugin.
+     */
+    disable(): Promise<this>;
+    /**
+     * Downloads the plugins package from the server.
+     *
+     * @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.
+     */
+    download(onProgress?: (progress: number) => void, signal?: AbortSignal): Promise<ArrayBuffer>;
+    /**
+     * Returns a plugin manfest.
+     */
+    getManifest(): Promise<any>;
+    /**
+     * Returns the plugin settings.
+     *
+     * @returns Returns an object with plugin settings.
+     */
+    getSettings(): Promise<any>;
+    /**
+     * Changes the plugin settings.
+     *
+     * @param settings - An object with the new plugin settings or part of the settings.
+     * @returns Returns an object with updated plugin settings.
+     */
+    updateSettings(settings: any): Promise<any>;
+    /**
+     * Executes a plugin command.
+     *
+     * This method executes the command for the current version of the plugin. To execute a command for the
+     * latest installed version of the plugin, use the {@link Client.executePluginCommand}.
+     *
+     * @param command - Command to execute.
+     * @param parameters - Command parameters. Command-dependent.
+     */
+    executeCommand(command: string, parameters?: BodyInit | object): Promise<any>;
+}

package/lib/index.d.ts

@@ -18,6 +18,7 @@ export { Permission } from "./Api/Permission";
 export { Project } from "./Api/Project";
 export * from "./Api/Endpoint";
 export { Role } from "./Api/Role";
+export * from "./Api/Plugin";
 export * from "./Api/SharedLink";
 export * from "./Api/SharedFile";
 export { User } from "./Api/User";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inweb/client",
-  "version": "26.9.0",
+  "version": "26.9.2",
   "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,9 @@
     "docs": "typedoc"
   },
   "dependencies": {
-    "@inweb/eventemitter2": "~26.9.0"
+    "@inweb/eventemitter2": "~26.9.2"
+  },
+  "devDependencies": {
+    "fflate": "^0.8.2"
   }
 }

package/src/Api/Client.ts

@@ -36,6 +36,7 @@ import { OAuthClient } from "./OAuthClient";
 import { ISharedLinkPermissions } from "./ISharedLink";
 import { SharedLink } from "./SharedLink";
 import { SharedFile } from "./SharedFile";
+import { Plugin } from "./Plugin";
 import { parseArgs } from "./Utils";
 
 /**
@@ -778,8 +779,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
    *   - `dwg`, `obj`, `gltf`, `glb`, `vsf`, `pdf`, `3dpdf` - Export file to the specified format.
    *   - Other custom job name. Custom job must be registered in the job templates before running.
    *
-   * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as command
-   *   line arguments in form `--arg=value`.
+   * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
+   *   object or command line arguments in form `--arg=value`.
    */
   createJob(fileId: string, outputFormat: string, parameters?: string | object): Promise<Job> {
     return this.httpClient
@@ -886,8 +887,8 @@ export class Client extends EventEmitter2<ClientEventMap> {
    * @param name - Assembly name.
    * @param params - Additional assembly creating parameters.
    * @param params.jobParameters - Parameters for the File Converter jobs. Use this to specify aditional
-   *   parameters for generating the geometry and properties of the new assembly. Can be given as command
-   *   line arguments in form `--arg=value`.
+   *   parameters for generating the geometry and properties of the new assembly. Can be given as JSON
+   *   object or command line arguments in form `--arg=value`.
    * @param params.waitForDone - Wait for assembly to be created.
    * @param params.timeout - The time, in milliseconds, that the function should wait for the assembly to
    *   be created. If the assembly is not created within this time, a TimeoutError exception will be
@@ -1138,4 +1139,118 @@ export class Client extends EventEmitter2<ClientEventMap> {
       .then((response) => response.json())
       .then((data) => new SharedFile(data, password, this.httpClient));
   }
+
+  /**
+   * Returns the list of installed plugins.
+   *
+   * Only administrators can get a list of plugins. If the current logged in user is not an
+   * administrator, an exception will be thrown.
+   */
+  getPlugins(): Promise<Plugin[]> {
+    return this.httpClient
+      .get("/plugins")
+      .then((response) => response.json())
+      .then((array) => array.map((data) => new Plugin(data, this.httpClient)));
+  }
+
+  /**
+   * Returns information about the specified plugin.
+   *
+   * Only administrators can get plugins. If the current logged in user is not an administrator, they can
+   * only get themselves, otherwise an exception will be thrown.
+   *
+   * @param name - Plugin name.
+   * @param version - Plugin version.
+   */
+  getPlugin(name: string, version: string): Promise<Plugin> {
+    return this.httpClient
+      .get(`/plugins/${name}/${version}`)
+      .then((response) => response.json())
+      .then((data) => new Plugin(data, this.httpClient));
+  }
+
+  /**
+   * Uploads and install a plugin package to the server. The package must be a ZIP file and undergoes
+   * verification, scanning, and health checks during installation.
+   *
+   * Only administrators can upload plugins. If the current logged in user is not an administrator, an
+   * exception will be thrown.
+   *
+   * @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.
+   */
+  async uploadPlugin(
+    file: globalThis.File,
+    onProgress?: (progress: number, file: globalThis.File) => void
+  ): Promise<Plugin> {
+    return await this.httpClient
+      .uploadFile("/plugins", file, (progress) => {
+        this.emitEvent({ type: "uploadprogress", data: progress, file });
+        if (onProgress) onProgress(progress, file);
+      })
+      .then((xhr: XMLHttpRequest) => JSON.parse(xhr.responseText))
+      .then((data) => new Plugin(data, this.httpClient));
+  }
+
+  /**
+   * Uninstalls and deletes the specified plugin from the server.
+   *
+   * Only administrators can delete plugins. If the current logged in user is not an administrator, an
+   * exception will be thrown.
+   *
+   * @param name - Plugin name.
+   * @param version - Plugin version.
+   */
+  deletePlugin(name: string, version: string): Promise<Plugin> {
+    return this.httpClient.delete(`/plugins/${name}/${version}`).then((response) => response.json());
+  }
+
+  /**
+   * Downloads the specified plugin package from the server.
+   *
+   * Only administrators can download plugins. If the current logged in user is not an administrator, an
+   * exception will be thrown.
+   *
+   * @param name - Plugin name.
+   * @param version - Plugin version.
+   * @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.
+   */
+  downloadPlugin(
+    name: string,
+    version: string,
+    onProgress?: (progress: number) => void,
+    signal?: AbortSignal
+  ): Promise<ArrayBuffer> {
+    return this.httpClient
+      .downloadFile(`/plugins/${name}/${version}/download`, onProgress, { signal })
+      .then((response) => response.arrayBuffer());
+  }
+
+  /**
+   * Executes a plugin command.
+   *
+   * If you have multiple versions of a plugin installed and want to run the command for the latest
+   * version of the plugin, specify `undefined` or empty string for the `version` parameter.
+   *
+   * @param name - Plugin name.
+   * @param version - Plugin version. Specify `undefined` or empty string to run the command for the
+   *   latest version of the plugin.
+   * @param command - Command to execute.
+   * @param parameters - Command parameters. Command-dependent.
+   */
+  executePluginCommand(name: string, version: string, command: string, parameters?: BodyInit | object): Promise<any> {
+    const searchParams = new URLSearchParams();
+    if (version) searchParams.set("version", version);
+
+    let queryString = searchParams.toString();
+    if (queryString) queryString = "?" + queryString;
+    return this.httpClient
+      .post(`/plugins/${name}/commands/${command}${queryString}`, parameters)
+      .then((response) => response.json());
+  }
 }

package/src/Api/File.ts

@@ -704,8 +704,8 @@ export class File extends Endpoint {
    *       {@link downloadResource | downloadResource()} to download the exported file.
    *   - Other custom job name. Custom job must be registered in the job templates before running.
    *
-   * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as command
-   *   line arguments in form `--arg=value`.
+   * @param parameters - Parameters for the File Converter jobs or custom job. Can be given as JSON
+   *   object or command line arguments in form `--arg=value`.
    */
   createJob(outputFormat: string, parameters?: string | object): Promise<Job> {
     const jobs = new Endpoint("/jobs", this.httpClient, this.headers);

package/src/Api/Plugin.ts

@@ -0,0 +1,241 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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";
+
+/**
+ * Provides properties and methods for obtaining information about a server plugin on the Open Cloud
+ * Server and managing its data.
+ */
+export class Plugin extends Endpoint {
+  private _data: any;
+
+  /**
+   * @param data - Raw plugin data received from the server. For more information, see
+   *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Plugin | Open Cloud Plugins API}.
+   * @param httpClient - HTTP client instance used to send requests to the REST API server.
+   */
+  constructor(data: any, httpClient: IHttpClient) {
+    super(`/plugins/${data.name}/${data.version}`, httpClient);
+    this.data = data;
+  }
+
+  /**
+   * Plugin author information. The `author` is an object with a `name` field and optionally `url` and
+   * `email`. Or it can be shorten that all into a single string.
+   *
+   * @readonly
+   */
+  get author(): any {
+    return this.data.author;
+  }
+
+  /**
+   * Raw plugin data received from the server. For more information, see
+   * {@link https://cloud.opendesign.com/docs//pages/server/api.html#Plugin | Open Cloud Plugins API}.
+   */
+  get data(): any {
+    return this._data;
+  }
+
+  set data(value: any) {
+    this._data = value;
+  }
+
+  /**
+   * Short description of the plugin.
+   *
+   * @readonly
+   */
+  get description(): string {
+    return this.data.description;
+  }
+
+  /**
+   * Plugin state.
+   *
+   * @readonly
+   */
+  get enabled(): boolean {
+    return this.data.enabled;
+  }
+
+  /**
+   * The URL to the plugin homepage.
+   *
+   * @readonly
+   */
+  get homepage(): string {
+    return this.data.homepage;
+  }
+
+  /**
+   * Unique plugin ID.
+   *
+   * @readonly
+   */
+  get id(): string {
+    return this.data.id;
+  }
+
+  /**
+   * A license for the plugin.
+   *
+   * @readonly
+   */
+  get license(): string {
+    return this.data.license;
+  }
+
+  /**
+   * Plugin name.
+   *
+   * @readonly
+   */
+  get name(): string {
+    return this.data.name;
+  }
+
+  /**
+   * API permissions required.
+   *
+   * @readonly
+   */
+  get permissions(): string[] {
+    return this.data.permissions;
+  }
+
+  /**
+   * Plugin type. Can be set of:
+   *
+   * - `app` - Viewer plugin, the client‑side web app that the server hosts and serves as static content.
+   * - `server` - Binary dll that extends server functionality.
+   * - `jobrunner` - Binary dll that adds a new Job Runner on the server.
+   *
+   * @readonly
+   */
+  get pluginType(): string[] {
+    return this.data.pluginType;
+  }
+
+  /**
+   * {@link https://semver.org/ | SemVer} compatible version of the plugin.
+   *
+   * @readonly
+   */
+  get version(): number {
+    return this.data.version;
+  }
+
+  /**
+   * Reloads plugin data from the server.
+   */
+  async checkout(): Promise<this> {
+    const response = await this.get("");
+    this.data = await response.json();
+    return this;
+  }
+
+  /**
+   * Uninstalls and deletes a plugin from the server.
+   *
+   * @returns Returns the raw data of a deleted plugin. For more information, see
+   *   {@link https://cloud.opendesign.com/docs//pages/server/api.html#Plugin | Open Cloud Plugins API}.
+   */
+  override delete(): Promise<any> {
+    return super.delete("").then((response) => response.json());
+  }
+
+  /**
+   * Enables a plugin.
+   */
+  async enable(): Promise<this> {
+    const response = await this.put("/enable");
+    this.data = await response.json();
+    return this;
+  }
+
+  /**
+   * Disables a plugin.
+   */
+  async disable(): Promise<this> {
+    const response = await this.put("/disable");
+    this.data = await response.json();
+    return this;
+  }
+
+  /**
+   * Downloads the plugins package from the server.
+   *
+   * @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.
+   */
+  download(onProgress?: (progress: number) => void, signal?: AbortSignal): Promise<ArrayBuffer> {
+    return this.httpClient
+      .downloadFile(this.getEndpointPath("/download"), onProgress, { signal, headers: this.headers })
+      .then((response) => response.arrayBuffer());
+  }
+
+  /**
+   * Returns a plugin manfest.
+   */
+  getManifest(): Promise<any> {
+    return this.get("/manifest").then((response) => response.json());
+  }
+
+  /**
+   * Returns the plugin settings.
+   *
+   * @returns Returns an object with plugin settings.
+   */
+  getSettings(): Promise<any> {
+    return this.get("/settings").then((response) => response.json());
+  }
+
+  /**
+   * Changes the plugin settings.
+   *
+   * @param settings - An object with the new plugin settings or part of the settings.
+   * @returns Returns an object with updated plugin settings.
+   */
+  updateSettings(settings: any): Promise<any> {
+    return this.post("/settings", settings).then((response) => response.json());
+  }
+
+  /**
+   * Executes a plugin command.
+   *
+   * This method executes the command for the current version of the plugin. To execute a command for the
+   * latest installed version of the plugin, use the {@link Client.executePluginCommand}.
+   *
+   * @param command - Command to execute.
+   * @param parameters - Command parameters. Command-dependent.
+   */
+  executeCommand(command: string, parameters?: BodyInit | object): Promise<any> {
+    const commands = new Endpoint(`/plugins/${this.name}/commands`, this.httpClient, this.headers);
+    return commands.post(`/${command}?version=${this.version}`, parameters).then((response) => response.json());
+  }
+}