wispjs 2.4.0 → 3.0.1

package/dist/wisp_socket/ws_adapter.js

@@ -0,0 +1,130 @@
+import WebSocket from "ws";
+import { EventEmitter } from "node:events";
+/**
+ * A thin adapter that exposes a Socket.IO-like event API over a plain `ws`
+ * WebSocket.
+ *
+ * The new backend speaks a simple JSON envelope rather than the Socket.IO /
+ * Engine.IO framing:
+ *
+ * ```json
+ * { "event": "console output", "args": ["...line..."] }
+ * ```
+ *
+ * `args` is omitted entirely when an event carries no payload
+ * (e.g. `{ "event": "auth success" }`).
+ *
+ * This class translates between that envelope and the `.on/.once/.off/.emit`
+ * surface the rest of the codebase already uses, so the calling code barely
+ * changes.
+ *
+ * @remarks
+ * We *compose* an EventEmitter instead of extending one on purpose: extending
+ * it would mean overriding `emit()`, which EventEmitter also calls internally
+ * (e.g. the `newListener` event) — so every `.on()` would try to send a frame
+ * to the server. Composition keeps "emit to the wire" and "fire local
+ * listeners" cleanly separate.
+ *
+ * @internal
+ */
+export class WispWebSocket {
+    constructor(url, opts = {}) {
+        this.emitter = new EventEmitter();
+        this.url = url;
+        this.origin = opts.origin;
+        // The pool registers a handful of listeners per worker; silence the
+        // default 10-listener warning.
+        this.emitter.setMaxListeners(0);
+    }
+    /**
+     * Opens the underlying WebSocket and wires up frame translation.
+     */
+    connect() {
+        const ws = new WebSocket(this.url, this.origin ? { origin: this.origin } : undefined);
+        this.ws = ws;
+        // Map ws lifecycle onto the Socket.IO-style events the pool listens for
+        ws.on("open", () => this.emitter.emit("connect"));
+        ws.on("close", (code, reason) => {
+            this.emitter.emit("disconnect", reason?.toString() || `code ${code}`);
+        });
+        ws.on("error", (err) => this.emitter.emit("connect_error", err));
+        ws.on("message", (data, isBinary) => {
+            if (isBinary)
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(data.toString());
+            }
+            catch {
+                return; // ignore anything that isn't our JSON envelope
+            }
+            const event = frame.event;
+            if (!event)
+                return;
+            const args = frame.args ?? [];
+            // EventEmitter throws if "error" is emitted with no listener; guard it.
+            if (event === "error" && this.emitter.listenerCount("error") === 0) {
+                console.error("[ws] server error frame:", ...args);
+                return;
+            }
+            this.emitter.emit(event, ...args);
+        });
+        return this;
+    }
+    /**
+     * Sends an event to the server as a `{ event, args }` JSON frame.
+     *
+     * @remarks
+     * Unlike EventEmitter.emit, this does NOT fire local listeners — it writes
+     * to the socket. Incoming frames fire local listeners via the internal
+     * emitter.
+     */
+    emit(event, ...args) {
+        this.outgoingListener?.(event, ...args);
+        const frame = JSON.stringify(args.length ? { event, args } : { event });
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.ws.send(frame);
+        }
+        else {
+            console.error(`[ws] dropped outgoing "${event}" — socket not open`);
+        }
+        return true;
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+        return this;
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+        return this;
+    }
+    /**
+     * Removes a specific listener, or — matching Socket.IO's behaviour — all
+     * listeners for an event when no listener is given.
+     */
+    off(event, listener) {
+        if (listener) {
+            this.emitter.off(event, listener);
+        }
+        else {
+            this.emitter.removeAllListeners(event);
+        }
+        return this;
+    }
+    removeAllListeners(event) {
+        this.emitter.removeAllListeners(event);
+        return this;
+    }
+    /**
+     * Registers a callback invoked for every outgoing emit (parity with
+     * Socket.IO's `onAnyOutgoing`, used for logging).
+     */
+    onAnyOutgoing(listener) {
+        this.outgoingListener = listener;
+        return this;
+    }
+    disconnect() {
+        this.ws?.close();
+        return this;
+    }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "wispjs",
-  "version": "2.4.0",
+  "version": "3.0.1",
   "type": "module",
   "description": "A package for interacting with Wisp-based server panels",
   "main": "dist/wisp.js",
   "types": "dist/wisp.d.ts",
   "scripts": {
     "build": "tsc",
-    "build-docs": "typedoc wisp.ts wisp_api/index.ts wisp_socket/index.ts wisp_api/apis/*"
+    "build-docs": "typedoc wisp.ts wisp_api/index.ts wisp_socket/index.ts wisp_socket/git.ts wisp_socket/filesystem.ts wisp_api/apis/*"
   },
   "repository": {
     "type": "git",
@@ -20,11 +20,12 @@
   },
   "homepage": "https://github.com/CFC-Servers/WispJS#readme",
   "dependencies": {
-    "socket.io-client": "^4.7.2",
-    "strip-ansi": "^7.1.0"
+    "strip-ansi": "^7.1.0",
+    "ws": "^8.21.0"
   },
   "devDependencies": {
     "@types/node": "^20.5.4",
+    "@types/ws": "^8.18.1",
     "typedoc": "^0.25.4",
     "typescript": "^5.3.3"
   }

package/.github/workflows/release.yml

@@ -1,77 +0,0 @@
-name: Deploy
-
-on:
-  workflow_dispatch:
-    inputs:
-      version_tag:
-        description: "Version tag for the package"
-        required: true
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 18
-
-      - name: Update package version
-        run: |
-          version=${{ inputs.version_tag }}
-          npm version $version --no-git-tag-version
-
-      - name: Install packages
-        run: |
-          npm ci
-
-      - name: Build
-        run: |
-          npm run build
-
-      - name: Generate Docs
-        run: |
-          npm run build-docs
-          mv docs ../docs_wip
-
-      - name: Remove Non-distributables
-        run: |
-          rm .gitignore
-          rm tsconfig.json
-          rm wisp.ts
-          rm -rf wisp_api wisp_socket .github
-
-      - name: Publish
-        uses: JS-DevTools/npm-publish@v3
-        with:
-          token: ${{ secrets.NPM_PUBLISH_TOKEN }}
-
-      - name: Configure Git User
-        run: |
-          git config user.name github-actions
-          git config user.email github-actions@github.com
-
-      - name: Push package version change
-        run: |
-          git add package.json
-          git add package-lock.json
-          git commit -m "Update package.json version to: ${{ inputs.version_tag }}" && \
-            git push --force-with-lease origin main || \
-            echo "Version tag unchanaged"
-
-      - name: Push new tag
-        run: |
-          git tag "${{ inputs.version_tag }}"
-          git push --tags
-
-      - name: Publish Docs
-        run: |
-          # Delete everything except .git
-          find . -mindepth 1 -maxdepth 1 ! -name '.git' -exec rm -rf {} +
-
-          # Move the docs back and commit only them
-          mv ../docs_wip docs
-          git add .
-          git commit -m "Update Docs for version: ${{ inputs.version_tag }}"
-          git push --force origin HEAD:docs

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-
-    "outDir": "./dist/",
-    "declaration": true,
-
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-
-    "strict": true,
-    "skipLibCheck": true,
-    "moduleResolution": "node"
-  },
-  "include": ["*.ts"],
-  "exclude": ["node_modules"]
-}
-

package/wisp.ts

@@ -1,43 +0,0 @@
-import { WispAPI } from "./wisp_api/index.js";
-import { WispSocket } from "./wisp_socket/index.js";
-
-export interface WispInterface {
-  socket: WispSocket;
-  api: WispAPI;
-  logger: any;
-}
-
-/**
- * The primary Wisp Interface, exposing interactions with both the HTTP and Websockets API
- *
- * @param domain The Domain of the Pterodactyl/Wisp panel (e.g. `my.gamepanel.gg`)
- * @param uuid The UUID of the server to reference in all API requests
- * @param token The panel API token to use for authorization
- * @param ghPAT The Github Personal Access Token used for Cloning/Pulling of private repositories. This may be omitted if you do not need to interact with private repositories
- *
- * @public
- */
-export class WispInterface {
-  constructor(domain: string, uuid: string, token: string, ghPAT?: string) {
-    this.logger = {
-      info: (msg: any) => {
-        console.log(msg);
-      },
-      error: (msg: string) => {
-        console.error(msg);
-      }
-    };
-
-    this.api = new WispAPI(domain, uuid, token, this.logger);
-    this.socket = new WispSocket(this.logger, this.api, ghPAT);
-  }
-
-  /**
-   * Manually disconnects from the Websocket connection(s)
-   *
-   * @public
-   */
-  async disconnect() {
-    await this.socket.disconnect();
-  }
-}

package/wisp_api/apis/allocations.ts

@@ -1,71 +0,0 @@
-import { WispAPICore } from "./index";
-import type { PaginationData } from "./index";
-
-/**
- * An Allocation object
- *
- * @internal
- */
-export interface Allocation {
-  object: "allocation";
-  attributes: {
-    id: number;
-    /** Whether or not this Allocation is the primary one for the Server */
-    primary: boolean;
-    ip: string;
-    port: number;
-  }
-}
-
-/**
- * The response object from the GetAllocations call
- *
- * @remarks
- * Used in {@link AllocationsAPI.List}
- *
- * @public
- */
-export interface GetAllocationsResponse {
-  object: "list";
-  data: Allocation[];
-  meta: {
-    pagination: PaginationData;
-  }
-}
-
-/**
- * Handles the listing and updating of a Server's IP/Port Allocations
- *
- * @public
- */
-export class AllocationsAPI {
-  constructor(private core: WispAPICore) {}
-
-
-  /**
-   * Lists all Allocations for the Server
-   *
-   * @public
-   */
-  async List(): Promise<GetAllocationsResponse> {
-    const response = await this.core.makeRequest("GET", "allocations");
-    const data: GetAllocationsResponse = await response.json()
-
-    return data;
-  }
-
-
-  /**
-   * Sets the new primary Allocation for the server
-   *
-   * @param id Allocation ID of the new primary allocation
-   *
-   * @public
-   */
-  async Update(id: string): Promise<Allocation> {
-    const response = await this.core.makeRequest("PUT", `allocations/${id}`);
-    const data: Allocation = await response.json()
-
-    return data;
-  }
-}

package/wisp_api/apis/audit_log.ts

@@ -1,81 +0,0 @@
-import { WispAPICore } from "./index";
-import type { PaginationData } from "./index";
-
-/**
- * Device information
- *
- * @example
- * ```json
- * {
- *    "city_name": "Seattle",
- *    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:120.0) Gecko/20100101 Firefox/120.0",
- *    "country_name": "US",
- *    "country_iso_code": "US"
- * }
- * ```
- *
- * @internal
- */
-export interface Device {
-  city_name: string;
-  user_agent: string;
-  country_name: string;
-  country_iso_code: string;
-}
-
-// TODO: Fully define the audit log type
-/**
- * An Audit Log struct
- *
- * @internal
- */
-export interface AuditLog {
-  object: "audit_log";
-  attributes: {
-    action: string;
-    subaction: string;
-    device: Device | undefined;
-    metadata: any;
-    created_at: string;
-  }
-}
-
-/**
- * The respones object from the GetAuditLogs call
- *
- * @remarks
- * Used in {@link AuditLogsAPI.List}
- *
- * @public
- */
-export interface GetAuditLogsResponse {
-  object: "list";
-  data: AuditLog[];
-  meta: {
-    pagination: PaginationData;
-  }
-}
-
-
-/**
- * Interface that handles Listing of all Audit Logs
- *
- * @public
- */
-export class AuditLogsAPI {
-  constructor(private core: WispAPICore) {}
-
-
-  // TODO: Handle pagination
-  /**
-   * List all Audit Log events for the server
-   *
-   * @public
-   */
-  async List(): Promise<GetAuditLogsResponse> {
-    const response = await this.core.makeRequest("GET", "audit-logs");
-    const data: GetAuditLogsResponse = await response.json();
-
-    return data;
-  }
-}

package/wisp_api/apis/backups.ts

@@ -1,168 +0,0 @@
-import { WispAPICore } from "./index";
-import type { PaginationData } from "./index";
-import type { DownloadFileResponse } from "./filesystem";
-
-/**
- * A Backup Object
- * @example
- * ```json
- * {
- *     "object": "backup",
- *     "attributes": {
- *         "uuid": "26adeafc-74af-43fd-93a5-9afa0486b21b",
- *         "uuid_short": "26adeafc",
- *         "name": "test-1",
- *         "sha256_hash": "56d2965e9167c785647878a391dfe24460c3aa5e1111b385708094bd8837b487",
- *         "bytes": 3266448936,
- *         "locked": false,
- *         "creating": false,
- *         "created_at": "2023-11-28T08:37:39.000000Z"
- *     }
- * }
- * ```
- *
- * @internal
- */
-export interface Backup {
-    object: "backup";
-    attributes: {
-        uuid: string;
-        uuid_short: string;
-        name: string;
-        /** The hash of the Backup. May be null if the Backup is still being created. */
-        sha256_hash: string | null;
-        bytes: number;
-        locked: boolean;
-        creating: boolean;
-        created_at: string;
-    }
-}
-
-/**
- * Response object used in the GetBackups call
- *
- * @remarks
- * Used in {@link BackupsAPI.List}
- *
- * @internal
- */
-export interface GetBackupsResponse {
-    object: "list";
-    data: Backup[];
-    meta: {
-        pagination: PaginationData;
-    }
-}
-
-export type BackupErrorCode = "server.backups.creation_would_exceed_limit";
-export interface BackupError {
-    code: BackupErrorCode;
-    data: any;
-}
-export interface CreateBackupFailure {
-    errors: BackupError[] | undefined
-}
-export type CreateBackupResponse = Backup | CreateBackupFailure;
-
-/**
- * Handles basic server backup tasks, such as creating, restoring, and deleting backups
- */
-export class BackupsAPI {
-    constructor(private core: WispAPICore) {}
-
-    /**
-     * Lists all current backups for the server
-     *
-     * @public
-     */
-    async List(): Promise<GetBackupsResponse> {
-        const response = await this.core.makeRequest("GET", "backups");
-        const data: GetBackupsResponse = await response.json();
-
-        return data;
-    }
-
-    /**
-     * Creates a new backup for the server
-     *
-     * @remarks
-     * ⚠️  This can fail to create a Backup even if the function completes successfully
-     * For example, if the backup would exceed the size limit (and the limit is not 0), the system wouldn't know it failed until it hit the limit.
-     *
-     * ⚠️  "It is recomended to stop your server before starting a backup. Backups created while the server is on can contain corupted data."
-     *
-     * Multiple Backups can exist with the same name.
-     *
-     * @param name The name of the Backup
-     *
-     * @throws {@link BackupErrorCode} 
-     * If the server returns an error code, it will be thrown verbatim here
-     *
-     * @public
-     */
-    async Create(name: string): Promise<CreateBackupResponse> {
-        const response = await this.core.makeRequest("POST", "backups", { name: name });
-        const data: CreateBackupResponse = await response.json()
-
-        if ("errors" in data && data.errors) {
-            throw new Error(data.errors[0].code);
-        }
-
-        return data
-    }
-
-    /**
-     * Toggles the "Locked" status of the Backup
-     *
-     * @param id The ID of the Backup
-     *
-     * @public
-     */
-    async ToggleLock(id: string): Promise<Backup> {
-        const response = await this.core.makeRequest("POST", `backups/${id}/locked`);
-        const data: Backup = await response.json();
-
-        return data;
-    }
-
-    /**
-     * Deploys the Backup to the Server
-     *
-     * @remarks
-     * **⚠️  This can be dangerous!**
-     * The Backup will overwrite the entire Server, erasing any new data since the Backup's creation
-     *
-     * @param id The ID of the Backup
-     *
-     * @public
-     */
-    async Deploy(id: string): Promise<Response> {
-        return await this.core.makeRequest("POST", `backups/${id}/deploy`);
-    }
-
-    /**
-     * Retrieves a URL from which the Backup can be downloaded
-     *
-     * @param id The ID of the Backup
-     * @returns The download URL
-     *
-     * @public
-     */
-    async GetDownloadURL(id: string): Promise<string> {
-        const response = await this.core.makeRequest("GET", `backups/${id}/download`);
-        const data: DownloadFileResponse = await response.json();
-
-        return data.url;
-    }
-
-    /**
-     * Deletes the Backup
-     *
-     * @param id The ID of the Backup
-     *
-     * @public
-     */
-    async Delete(id: string): Promise<void> {
-        await this.core.makeRequest("DELETE", `backups/${id}`);
-    }
-}

package/wisp_api/apis/databases.ts

@@ -1,80 +0,0 @@
-import { WispAPICore } from "./index";
-import type { PaginationData } from "./index";
-
-export interface DatabaseRelationship {
-  object: "database_host";
-  attributes: {
-    id: number;
-    name: string;
-    host: string;
-    port: number;
-    phpmyadmin_url: string | null;
-  }
-}
-
-export interface Database {
-  object: "database";
-  attributes: {
-    id: number;
-    name: string;
-    remote: string;
-    username: string;
-    password: string;
-    relationships: DatabaseRelationship[];
-  }
-}
-export interface GetDatabasesResponse {
-  object: "list";
-  data: Database[];
-  meta: {
-    pagination: PaginationData;
-  }
-}
-
-/**
- * Handles Creating, Listing, Updating, and Deleting of Databases for the Server
- *
- * @public
- */
-export class DatabasesAPI {
-  constructor(private core: WispAPICore) {}
-
-  // TODO: Handle Pagination
-  /**
-   * Lists all Databases associated with the Server
-   *
-   * @public
-   */
-  async List(): Promise<GetDatabasesResponse> {
-    const response = await this.core.makeRequest("GET", "databases", { include: "hosts" });
-    const data: GetDatabasesResponse = await response.json();
-
-    return data;
-  }
-
-
-  // TODO: verify response
-  /**
-   * Deletes the Database from the Server
-   *
-   * @param id The ID of the Backup
-   *
-   * @public
-   */
-  async Delete(id: string): Promise<Response> {
-    return await this.core.makeRequest("DELETE", `databases/${id}`);
-  }
-
-
-  // TODO: Verify response
-  /**
-   * Rotates the password for the Backup
-   *
-   * @param id The ID of the Backup
-   *
-   * @public
-   */
-  async RotatePassword(id: string): Promise<Response> {
-    return await this.core.makeRequest("POST", `databases/${id}`);
-  }
-}