wispjs 2.3.6 → 3.0.0

package/README.md

@@ -1,7 +1,7 @@
 # WispJS
 <p align="left">
     <a href="https://discord.gg/5JUqZjzmYJ" alt="Discord Invite"><img src="https://img.shields.io/discord/981394195812085770?label=Support&logo=discord&logoColor=white" /></a>
-    <a href="https://www.npmjs.com/package/wispjs" alt="NPM Package Link"><img src="https://img.shields.io/npm/v/%40cfc-servers%2Fwispjs?label=NPM&logo=npm" /></a>
+    <a href="https://www.npmjs.com/package/wispjs" alt="NPM Package Link"><img src="https://img.shields.io/npm/v/wispjs?label=NPM&logo=npm" /></a>
     <a href="https://docs.wispjs.com" alt="Docs Link"><img src="https://img.shields.io/badge/Docs-docs.wispjs.com-blue?logo=readthedocs" /></a>
 </p>
 

package/dist/wisp_api/index.d.ts

@@ -36,4 +36,10 @@ export declare class WispAPI {
      * @internal
      */
     constructor(domain: string, uuid: string, token: string, logger: any);
+    /**
+     * The panel domain these API calls target.
+     *
+     * @public
+     */
+    get domain(): string;
 }

package/dist/wisp_api/index.js

@@ -38,4 +38,12 @@ export class WispAPI {
         this.Startup = new StartupAPI(this.core);
         this.Subusers = new SubusersAPI(this.core);
     }
+    /**
+     * The panel domain these API calls target.
+     *
+     * @public
+     */
+    get domain() {
+        return this.core.domain;
+    }
 }

package/dist/wisp_socket/filesystem.d.ts

@@ -0,0 +1,60 @@
+import type { WispSocket } from "./index.js";
+import type { ListOptions, ListResult, FilesearchResults, FsOkResult, ConflictsResult } from "./pool.js";
+/**
+ * Filesystem operations exposed over the Websocket.
+ *
+ * `list` runs through the correlated `fs:request` protocol (see
+ * {@link WispSocket.request}); `search` uses the dedicated `filesearch start`/
+ * `filesearch results` events.
+ *
+ * @remarks
+ * The new backend also serves plain file read/write/delete/rename over
+ * `fs:request`, but those op shapes haven't been captured yet. Until typed
+ * wrappers exist here, they're reachable via {@link WispSocket.request}, and
+ * the existing HTTP `Filesystem` API covers them too.
+ *
+ * @public
+ */
+export declare class FilesystemSocket {
+    private socket;
+    constructor(socket: WispSocket);
+    /**
+     * Lists the contents of a directory (paginated).
+     *
+     * @param dir The directory to list
+     * @param opts Search, pagination, and sort options
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    list(dir: string, opts?: ListOptions, timeout?: number): Promise<ListResult>;
+    /**
+     * Creates a directory named `name` under `root`.
+     *
+     * @param root The parent directory the new directory is created in
+     * @param name The name of the new directory
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    createDirectory(root: string, name: string, timeout?: number): Promise<FsOkResult>;
+    /**
+     * Checks which of the given paths already exist / would conflict.
+     *
+     * @param paths The paths to check
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    conflicts(paths: string[], timeout?: number): Promise<ConflictsResult>;
+    /**
+     * Searches file contents under a root directory for the given query.
+     *
+     * @param query The query string to search for
+     * @param root The directory to search under
+     * @param timeout How long to wait (in ms) for results before timing out
+     *
+     * @public
+     */
+    search(query: string, root?: string, timeout?: number): Promise<FilesearchResults>;
+}

package/dist/wisp_socket/filesystem.js

@@ -0,0 +1,97 @@
+/**
+ * Filesystem operations exposed over the Websocket.
+ *
+ * `list` runs through the correlated `fs:request` protocol (see
+ * {@link WispSocket.request}); `search` uses the dedicated `filesearch start`/
+ * `filesearch results` events.
+ *
+ * @remarks
+ * The new backend also serves plain file read/write/delete/rename over
+ * `fs:request`, but those op shapes haven't been captured yet. Until typed
+ * wrappers exist here, they're reachable via {@link WispSocket.request}, and
+ * the existing HTTP `Filesystem` API covers them too.
+ *
+ * @public
+ */
+export class FilesystemSocket {
+    constructor(socket) {
+        this.socket = socket;
+    }
+    /**
+     * Lists the contents of a directory (paginated).
+     *
+     * @param dir The directory to list
+     * @param opts Search, pagination, and sort options
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    async list(dir, opts = {}, timeout = 10000) {
+        const params = {
+            directory: dir,
+            search: opts.search ?? "",
+            page: opts.page ?? 1,
+            per_page: opts.perPage ?? 100,
+            sort: opts.sort ?? "name",
+            sort_dir: opts.sortDir ?? "asc",
+        };
+        return await this.socket.request("list", params, timeout);
+    }
+    /**
+     * Creates a directory named `name` under `root`.
+     *
+     * @param root The parent directory the new directory is created in
+     * @param name The name of the new directory
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    async createDirectory(root, name, timeout = 10000) {
+        return await this.socket.request("mkdir", { root, name }, timeout);
+    }
+    /**
+     * Checks which of the given paths already exist / would conflict.
+     *
+     * @param paths The paths to check
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    async conflicts(paths, timeout = 10000) {
+        return await this.socket.request("conflicts", { paths }, timeout);
+    }
+    /**
+     * Searches file contents under a root directory for the given query.
+     *
+     * @param query The query string to search for
+     * @param root The directory to search under
+     * @param timeout How long to wait (in ms) for results before timing out
+     *
+     * @public
+     */
+    async search(query, root = "/garrysmod", timeout = 10000) {
+        return await this.socket.runWorker((worker) => {
+            const socket = worker.socket;
+            const logger = worker.logger;
+            logger.log("Running filesearch:", query, root);
+            return new Promise((resolve, reject) => {
+                const timeoutObj = setTimeout(() => {
+                    socket.off("filesearch results");
+                    logger.error("Rejected filesearch: 'Timeout'");
+                    reject(new Error("Timeout"));
+                }, timeout);
+                socket.once("filesearch results", (raw) => {
+                    clearTimeout(timeoutObj);
+                    try {
+                        resolve(JSON.parse(raw));
+                    }
+                    catch (e) {
+                        logger.error("Failed to parse filesearch results", raw);
+                        reject(e);
+                    }
+                });
+                socket.emit("filesearch start", JSON.stringify({ query, root }));
+            });
+        });
+    }
+}

package/dist/wisp_socket/git.d.ts

@@ -0,0 +1,57 @@
+import type { WispSocket } from "./index.js";
+import type { GitPullResult, GitCloneResult, GitStatusResult } from "./pool.js";
+/**
+ * Git operations exposed over the Websocket.
+ *
+ * These run through the backend's correlated `fs:request` protocol (see
+ * {@link WispSocket.request}).
+ *
+ * Authentication: SSH remotes are authenticated server-side via a deploy key
+ * configured in the panel. HTTPS remotes can additionally use the GitHub token
+ * (`ghToken`) passed to {@link WispInterface} — {@link pull} and {@link clone}
+ * automatically retry with it when the remote reports `auth_required`.
+ *
+ * @public
+ */
+export declare class GitSocket {
+    private socket;
+    constructor(socket: WispSocket);
+    /**
+     * Runs a git op, retrying once with the configured GitHub token as
+     * `authkey` if the remote reports `auth_required` (an HTTPS remote with no
+     * credentials). SSH auth is handled server-side, so we only retry this
+     * specific case.
+     *
+     * @internal
+     */
+    private withAuthRetry;
+    /**
+     * Gets the git status of a directory (branch, commit, ahead/behind, dirty).
+     *
+     * @param dir The full directory path of the repository
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    status(dir: string, timeout?: number): Promise<GitStatusResult>;
+    /**
+     * Performs a git pull on the given repository directory.
+     *
+     * @param dir The full directory path to pull
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    pull(dir: string, timeout?: number): Promise<GitPullResult>;
+    /**
+     * Clones a repository into the given parent directory.
+     *
+     * @param url The repository URL to clone
+     * @param directory The parent directory to clone into
+     * @param branch The branch to clone (optional)
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    clone(url: string, directory: string, branch?: string, timeout?: number): Promise<GitCloneResult>;
+}

package/dist/wisp_socket/git.js

@@ -0,0 +1,76 @@
+/**
+ * Git operations exposed over the Websocket.
+ *
+ * These run through the backend's correlated `fs:request` protocol (see
+ * {@link WispSocket.request}).
+ *
+ * Authentication: SSH remotes are authenticated server-side via a deploy key
+ * configured in the panel. HTTPS remotes can additionally use the GitHub token
+ * (`ghToken`) passed to {@link WispInterface} — {@link pull} and {@link clone}
+ * automatically retry with it when the remote reports `auth_required`.
+ *
+ * @public
+ */
+export class GitSocket {
+    constructor(socket) {
+        this.socket = socket;
+    }
+    /**
+     * Runs a git op, retrying once with the configured GitHub token as
+     * `authkey` if the remote reports `auth_required` (an HTTPS remote with no
+     * credentials). SSH auth is handled server-side, so we only retry this
+     * specific case.
+     *
+     * @internal
+     */
+    async withAuthRetry(op, params, timeout) {
+        try {
+            return await this.socket.request(op, params, timeout);
+        }
+        catch (e) {
+            if (e?.code === "auth_required" && this.socket.ghToken) {
+                return await this.socket.request(op, { ...params, authkey: this.socket.ghToken }, timeout);
+            }
+            throw e;
+        }
+    }
+    /**
+     * Gets the git status of a directory (branch, commit, ahead/behind, dirty).
+     *
+     * @param dir The full directory path of the repository
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    async status(dir, timeout = 10000) {
+        return await this.socket.request("git-status", { directory: dir }, timeout);
+    }
+    /**
+     * Performs a git pull on the given repository directory.
+     *
+     * @param dir The full directory path to pull
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    async pull(dir, timeout = 10000) {
+        return await this.withAuthRetry("git-pull", { directory: dir }, timeout);
+    }
+    /**
+     * Clones a repository into the given parent directory.
+     *
+     * @param url The repository URL to clone
+     * @param directory The parent directory to clone into
+     * @param branch The branch to clone (optional)
+     * @param timeout In milliseconds, how long to wait before timing out
+     *
+     * @public
+     */
+    async clone(url, directory, branch, timeout = 20000) {
+        const params = { directory, url };
+        if (branch) {
+            params.branch = branch;
+        }
+        return await this.withAuthRetry("git-clone", params, timeout);
+    }
+}

package/dist/wisp_socket/index.d.ts

@@ -1,5 +1,7 @@
 import { WebsocketPool } from "./pool.js";
-import { FilesearchResults } from "./pool";
+import { SocketWorker } from "./pool.js";
+import { GitSocket } from "./git.js";
+import { FilesystemSocket } from "./filesystem.js";
 import type { WispAPI } from "../wisp_api/index.js";
 /**
  * The Websocket information returned from the API
@@ -23,6 +25,8 @@ export interface WispSocket {
     ghToken: string | undefined;
     consoleCallbacks: ((message: string) => void)[];
     detailsPreprocessor: WebsocketDetailsPreprocessor | undefined;
+    Git: GitSocket;
+    Filesystem: FilesystemSocket;
 }
 /**
  * The primary interface to the Websocket API
@@ -76,34 +80,49 @@ export declare class WispSocket {
      */
     verifyPool(): Promise<void>;
     /**
-     * Searches all file contents for the given query
+     * Runs a job on an available pool worker, handing it the worker's socket
+     * and logger. Used for event-based flows (e.g. file search) that don't fit
+     * the {@link request} request/response protocol.
      *
-     * @param query The query string to search for
-     * @param timeout How long to wait (in ms) for results before timing out
+     * @param work The job to run; receives the worker and returns a Promise
      *
-     * @public
+     * @internal
      */
-    filesearch(query: string, timeout?: number): Promise<FilesearchResults>;
+    runWorker<T>(work: (worker: SocketWorker) => Promise<T>): Promise<T>;
     /**
-     * Performs a git pull operation on the given directory
-     *
-     * @param dir The full directory path to perform a pull on
-     * @param timeout In milliseconds, how long to wait before timing out
+     * Generates a short, unique request id for {@link request} correlation.
      *
-     * @public
+     * @internal
      */
-    gitPull(dir: string, useAuth?: boolean, timeout?: number): Promise<any>;
+    private generateReqId;
     /**
-     * Clones a new Repo to the given directory
+     * Issues a correlated `fs:request` to the backend and awaits its outcome.
+     *
+     * This is the low-level entry point for the git/filesystem protocol. The
+     * client emits `fs:request` with a JSON-string payload (`{ req, op, ...params }`),
+     * and the backend replies with one of three events, all correlated by `req`
+     * and all carrying a JSON-string `args[0]`:
+     *
+     *   - `fs:result`   — success; resolves with the parsed `data`
+     *   - `fs:error`    — failure; rejects with an {@link FsError} (plus collected `output`)
+     *   - `fs:progress` — streaming stdout/stderr/progress lines (collected for error context)
+     *
+     * Typed convenience wrappers live on {@link GitSocket} ({@link WispSocket.Git})
+     * and {@link FilesystemSocket} ({@link WispSocket.Filesystem}); call this
+     * directly for ops that don't have a typed wrapper yet.
+     *
+     * @example
+     * ```js
+     * const status = await wisp.socket.request("git-status", { directory: "/garrysmod/addons/acf-3" })
+     * ```
      *
-     * @param url The HTTPS URL of the repository
-     * @param dir The full path of the directory to clone the repository to
-     * @param branch The branch of the repository to clone
-     * @param timeout In milliseconds, how long to wait before timing out
+     * @param op The operation name (e.g. `git-pull`, `list`)
+     * @param params Additional payload fields merged into the request (e.g. `{ directory }`)
+     * @param timeout In milliseconds, how long to wait for the result
      *
      * @public
      */
-    gitClone(url: string, dir: string, branch: string, timeout?: number): Promise<any>;
+    request<T = any>(op: string, params?: Record<string, any>, timeout?: number): Promise<T>;
     /**
      * Sets up the console listener worker
      *