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.

$3

- 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:///account/security
`
_(while logged in)_ and generate a new Token.




In general, your WispJS code will start like this:
`js
import { WispInterface } from "wispjs"

const domain = ""

// You still need to provide this even if you're not doing anything server-specific (this will be improved)
const uuid = ""

const token = ""

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




$3

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:
`js
import { WispInterface } from "wispjs"

...

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

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

$3


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:
`js

const ghPAT = ""

(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.

$3

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:
`js
(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" )
})()
`

$3

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.

$3

- disconnect

$3

_Manage all IP allocations_
- List
- Update

$3

_Used to review Audit Logs_
- List

$3

_Manage Server backups_
- List
- Create
- ToggleLock
- Deploy
- GetDownloadURL
- Delete

$3

_Manage Databases_
- List
- Delete
- RotatePassword

$3

_Sync FastDL for a Server_
- Sync

$3

_Interact with the Filesystem_
- GetDirectoryContents
- CreateDirectory
- ReadFile
- WriteFile
- CopyFile
- DeleteFiles
- GetFileDownloadURL
- RenameFile
- CompressFiles
- DecompressFile

$3

_Use the "Mods" feature_
- List
- ToggleInstall

$3

_Manage Schedules_
- List
- GetDetails
- Create
- Update
- Trigger
- Delete
- CreateTask
- UpdateTask
- DeleteTask

$3

_A set of functions to manage a specific server_
- SendCommand
- GetWebsocketDetails
- SetName
- GetDetails
- GetResources
- PowerRequest

$3

_Get and adjust server Startup params (default map, tickrate, etc.)_
- Get
- Update

$3

_Create, List, Update, Delete Subusers_
- List
- GetDetails
- GetAllPermissions
- Create
- Update
- Delete

$3

_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"