WispJS

JS Library for interacting with Wisp instances.

The entire Wisp API is implemented and documented to the best of our abilities.

We also added a lot of documentation (i.e. response codes, special notes about weird behavior, response types, etc.) that is absent from the official docs.

Compatability Notes

This library is confirmed working for Physgun-based instances
This almost certainly (but remains unconfirmed) works with wisp.gg instances
This may also work for Pterodactyl servers, but we haven't been able to confirm this yet

We're always looking for notes about what this does/doesn't work for! Please leave a note in a Discussion or Issue if you learn something

Installation

npm i wispjs@v2

What can I do with this?

Well.. anything!

Everything you normally do in your Wisp panel is fully replicable using this library.

Here are some ideas:

Automatic GMod addon updater
- Using the gitClone/gitPull/filesearch methods. You can even compare commits to generate a diff with the github api
- We use a custom (public, but not documented) GitHub action to automatically update Git addons on all of our servers
Remote log storage/analyzing
- Using the console callbacks on the socket interface, you can run a callback any time anything is printed to the console.
- At CFC, we use this to send our server logs to Datadog
- You could also use this to respond to engine messages that you couldn't see in-game. For example, we used to use this to delete entities that would spam "ignoring unreasonable position" messages. We also used this to detect game exploits and respond to them in ways we couldn't from in-game.
- CFC also uses this feature to save full console output to log files (which isn't otherwise possible on panels like Physgun at the moment)
Backups
- You can use the Backups interface to run a normal backup, or you can use the Filesystem interface to manually compress/download specific files of your choosing. This gives you the freedom to make smaller backups and store them anywhere you want - all automatically
Remote Control
- Using the socket and Servers interfaces, you can issue commands to the server in the same way as typing commands in your server's console on the web interface
- This is very powerful (and dangerous, be careful about who has access to these tools!)
- CFC uses this to issue admin commands from a discord command, as well as relaying chat messages from Discord -> In-game

Usage

(Full docs available at: https://docs.wispjs.com)

For essentially all use-cases, you will need a Wisp API Token. To generate one, visit:

https://<your.wisp.domain>/account/security

(while logged in) and generate a new Token.

In general, your WispJS code will start like this:

import { WispInterface } from "wispjs"

const domain = "<your.wisp.domain>"

// You still need to provide this even if you're not doing anything server-specific (this will be improved)
const uuid = "<the uuid of the server you'll be messing with>"

const token = "<your wisp token>"

const wisp = new WispInterface(domain, uuid, token)

The HTTP API vs. the WebSocket API

In Wisp exists both an HTTP API and a WebSocket API. They do different things, but both are needed for full functionality.

In general, the Wisp Socket is used for interacting with a server instance. Things like issuing console commands, watching console output, and more.

For almost everything else in the Wisp panel, you use the HTTP API. Databases, subusers, filesystem - it's all through the HTTP API.

In WispJS, you access each of these as you might expect:

import { WispInterface } from "wispjs"

...

(async () => {
    const wisp = new WispInterface(domain, uuid, token)

    const api = wisp.api
    const socket = wisp.socket
})()

Git Pulling / Cloning private repositories

If you need to interact with private repositories, you'll need to generate a new access token. On GitHub, these are called Personal Access Tokens (Fine Grained probably works too). Once you generate one, you just need to pass it to your WispInterface:

const ghPAT = "<your personal access token>"

(async () => {
    const wisp = new WispInterface(domain, uuid, token, ghPAT)
    const socket = wisp.socket
})()

If you don't provide this and end up needing it, WispJS will produce an error the next time it gets a Git authentication failure.

Server-specific functions

When creating a new WispInterface instance, you give it a Server UUID. All future functions that operate on a specific server will operate on that server.

You can make multiple WispInterface instances to manage multiple servers, or change the server UUID at runtime:

(async () => {
    const wisp = new WispInterface(domain, uuid, token)
    const api = wisp.api

    // Sends to the the `uuid` server
    await api.Servers.SendCommand( "some_concmd" )

    // Update the UUID and send to the next server
    api.core.setUUID( "newUUID" )
    await api.Servers.SendCommand( "some_concmd" )
})()

Cloud Hosting

This library runs just fine on GitHub Actions, Cloudflare Workers, and I'm sure many others.

Special note about Cloudflare Workers

Almost all Wisp Websockets are hosted on a different port, usually :8080. Cloudflare doesn't allow us to make requests to nonstandard HTTP ports.

At CFC, we host a dead-simple Nginx instance that proxies the requests through our dedicated server. If you get stuck on this, please make an Issue and we'll try to provide a more robust solution.

API

This is a general rundown of the functions you can use. Please consult the docs for types, parameters, and everything you'd need to actually use them.

WispInterface

disconnect

WispInterface.api.Allocations

Manage all IP allocations

List
Update

WispInterface.api.AuditLogs

Used to review Audit Logs

List

WispInterface.api.Backups

Manage Server backups

List
Create
ToggleLock
Deploy
GetDownloadURL
Delete

WispInterface.api.Databases

Manage Databases

List
Delete
RotatePassword

WispInterface.api.FastDL

Sync FastDL for a Server

Sync

WispInterface.api.Filesystem

Interact with the Filesystem

GetDirectoryContents
CreateDirectory
ReadFile
WriteFile
CopyFile
DeleteFiles
GetFileDownloadURL
RenameFile
CompressFiles
DecompressFile

WispInterface.api.Mods

Use the "Mods" feature

List
ToggleInstall

WispInterface.api.Schedules

Manage Schedules

List
GetDetails
Create
Update
Trigger
Delete
CreateTask
UpdateTask
DeleteTask

WispInterface.api.Servers

A set of functions to manage a specific server

SendCommand
GetWebsocketDetails
SetName
GetDetails
GetResources
PowerRequest

WispInterface.api.Startup

Get and adjust server Startup params (default map, tickrate, etc.)

Get
Update

WispInterface.api.Subusers

Create, List, Update, Delete Subusers

List
GetDetails
GetAllPermissions
Create
Update
Delete

WispInterface.socket

Interact with the realtime websocket for a Server

setWebsocketDetailsPreprocessor
- Allows you to modify the reeturned websocket details (i.e. for setting up a proxy)
filesearch
- Performs the same file search as when you use the "Search" box in the Web File Browser
gitPull
- Pulls an existing git repo
gitClone
- Clones a git repo
addConsoleListener
- Adds a callback that gets called every time a new console message is received from the server
removeConsoleListener
sendCommandNonce
- Sends a command with a "nonce"

CFC-Servers/WispJS