@znyash/tosu-api

This is a typed wrapper for Tosu WebSocket and HTTP APIs.

Why

Instead of needing to manually opening WebSockets, parsing JSON and dealing with reconnect and weird payload shapes, you can use this package to make your life easier.

Install

bun add @znyash/tosu-api

or

npm install @znyash/tosu-api

Usage

Requires Tosu running locally to work.

import { TosuWrapper } from "@znyash/tosu-api";

const client = new TosuWrapper({
  host: "127.0.0.1:24050", // Where tosu is running.
});

const connection = client.connectV2((data => {
  console.log(data.beatmap.title);
});

// disconnect later
connection.close();

Auto reconnect

Reconnect is enabled by default.

Default behavior:

• enabled
• 1000ms delay
• unlimited attempts

You can override it per connection:

const connection = client.connectV2(
  (data) => {
    console.log(data);
  },
  {
    reconnect: {
      enabled: true,
      delayMs: 2000,
      maxAttempts: 5,
    },
  }
);

HTTP example — calculate pp

const result = await client.calculatePp({
  acc: 98.5,
  mods: 64, // DT
});

console.log(result.performance.pp);

---

WebSocket endpoints

Method	Path	Type
connectV1()	/ws	TosuPayloadV1
connectV2()	/websocket/v2	TosuPayloadV2
connectV2Precise()	/websocket/v2/precise	TosuPayloadV2Precise
connectCommands()	/websocket/commands	TosuCommandMessage

HTTP endpoints

Method	Path	Return
calculatePp()	/api/calculate/pp	CalculatePpResponse

Scripts

bun run build

bun run typecheck

bun test

---

Notes

This package follows the real Tosu payloads.

Because of that, some fields may differ from older documentation.

Real payloads > old docs.

Also this package is indeed a remake inspired by the socket.js they provide on their wiki.