@inweb/client 26.9.1 → 26.9.3

package/lib/Api/Assembly.d.ts

@@ -250,11 +250,11 @@ export declare class Assembly extends Endpoint {
      * descriptions, or geometry data.
      *
      * @param dataId - Resource file name.
+     * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
+     *   the server request. If specified, server-side caching may not work.
      * @param ranges - A ranges of resource file contents to download. See
      *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
      *   more details.
-     * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
-     *   the server request. If specified, server-side caching may not work.
      * @param onProgress - Download progress callback.
      * @param signal - An
      *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows

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

@@ -375,11 +375,11 @@ export declare class File extends Endpoint {
      * contain model scene descriptions, or geometry data, or exported files.
      *
      * @param dataId - Resource file name.
+     * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
+     *   the server request. If specified, server-side caching may not work.
      * @param ranges - A ranges of resource file contents to download. See
      *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
      *   more details.
-     * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
-     *   the server request. If specified, server-side caching may not work.
      * @param onProgress - Download progress callback.
      * @param signal - An
      *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows
@@ -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/Model.d.ts

@@ -146,11 +146,11 @@ export declare class Model extends Endpoint {
      * or geometry data.
      *
      * @param dataId - Resource file name.
+     * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
+     *   the server request. If specified, server-side caching may not work.
      * @param ranges - A ranges of resource file contents to download. See
      *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
      *   more details.
-     * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
-     *   the server request. If specified, server-side caching may not work.
      * @param onProgress - Download progress callback.
      * @param signal - An
      *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows

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.1",
+  "version": "26.9.3",
   "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.1"
+    "@inweb/eventemitter2": "~26.9.3"
+  },
+  "devDependencies": {
+    "fflate": "^0.8.2"
   }
 }

package/src/Api/Assembly.ts

@@ -435,11 +435,11 @@ export class Assembly extends Endpoint {
    * descriptions, or geometry data.
    *
    * @param dataId - Resource file name.
+   * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
+   *   the server request. If specified, server-side caching may not work.
    * @param ranges - A ranges of resource file contents to download. See
    *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
    *   more details.
-   * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
-   *   the server request. If specified, server-side caching may not work.
    * @param onProgress - Download progress callback.
    * @param signal - An
    *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows

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";
 
 /**
@@ -168,7 +169,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
       .post("/register", {
         email,
         password,
-        userName: userName ?? (email + "").split("@").at(0),
+        userName: userName ?? (email + "").split("@").shift(),
       })
       .then((response) => response.json());
   }
@@ -469,7 +470,7 @@ export class Client extends EventEmitter2<ClientEventMap> {
         userBrief: {
           ...rest,
           email,
-          userName: userName ?? (email + "").split("@").at(0),
+          userName: userName ?? (email + "").split("@").shift(),
         },
         password,
       })
@@ -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

@@ -606,11 +606,11 @@ export class File extends Endpoint {
    * contain model scene descriptions, or geometry data, or exported files.
    *
    * @param dataId - Resource file name.
+   * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
+   *   the server request. If specified, server-side caching may not work.
    * @param ranges - A ranges of resource file contents to download. See
    *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
    *   more details.
-   * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
-   *   the server request. If specified, server-side caching may not work.
    * @param onProgress - Download progress callback.
    * @param signal - An
    *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows
@@ -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/Model.ts

@@ -253,11 +253,11 @@ export class Model extends Endpoint {
    * or geometry data.
    *
    * @param dataId - Resource file name.
+   * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
+   *   the server request. If specified, server-side caching may not work.
    * @param ranges - A ranges of resource file contents to download. See
    *   {@link https://developer.mozilla.org/docs/Web/HTTP/Guides/Range_requests | HTTP range requests} for
    *   more details.
-   * @param requestId - Specify a non-empty `requestId` to append the `?requestId=` search parameter to
-   *   the server request. If specified, server-side caching may not work.
    * @param onProgress - Download progress callback.
    * @param signal - An
    *   {@link https://developer.mozilla.org/docs/Web/API/AbortController | AbortController} signal. Allows