TypeScript SDK Documentation

The VIIPER TypeScript SDK provides a modern, type-safe Node.js client library for interacting with VIIPER servers and controlling virtual devices.

Overview

The TypeScript SDK features:

Type-safe API: Structured request/response types with proper TypeScript definitions
Event-driven: EventEmitter-based output handling for device feedback (LEDs, rumble)
Auto-generated: Generated from server code with device-specific Input/Output classes
Modern Node.js: Targets Node.js 18+ with ES modules
Zero external dependencies: Uses only built-in Node.js libraries

License

The TypeScript SDK is licensed under the MIT License, providing maximum flexibility for integration into your projects.
The core VIIPER server remains under its original license.

Installation

1. Using the Published NPM Package (Recommended)

Install the SDK from the public npm registry:

npm install viiperclient

Or with pnpm / yarn:

pnpm add viiperclient
# or
yarn add viiperclient

The latest stable version is tagged as latest.

Pre-release / snapshot builds are not published to npm. They are only available as GitHub Release artifacts (e.g. dev-latest) or by building from source.

To use a snapshot artifact from GitHub:

Download viiperclient-typescript-sdk-Snapshot.tgz (or a versioned tarball) from the appropriate Release.
Install it directly:

npm install ./viiperclient-typescript-sdk-Snapshot.tgz

Package page: npm: viiperclient

2. Local Project Reference (For Development Against Source)

If you are actively modifying VIIPER or the code generator, link directly:

{
  "dependencies": {
    "viiperclient": "file:../../clients/typescript"
  }
}

Then build locally after regeneration:

cd clients/typescript
npm install
npm run build

3. Generating from Source (Advanced / Contributors)

This is only required if you are contributing to VIIPER or adding device types. Normal users should use the npm package.

cd viiper
go run ./cmd/viiper codegen --lang=typescript
cd ../clients/typescript
npm install
npm run build

Quick Start

import { ViiperClient, Keyboard } from "viiperclient";

const { KeyboardInput, Key, Mod } = Keyboard;

// Connect to management API
const client = new ViiperClient("localhost", 3242);

// Find or create a bus
const busesResp = await client.buslist();
let busID: number;
if (busesResp.buses.length === 0) {
  const resp = await client.buscreate("my-bus");
  busID = resp.busId;
} else {
  busID = busesResp.buses[0];
}

// Add device and connect
const { device, response } = await client.addDeviceAndConnect(busID, "keyboard");
const deviceId = response.id.split('-')[1]; // Extract device ID from "busId-devId"

console.log(`Connected to device ${response.id}`);

// Send keyboard input
const input = new KeyboardInput({
  Modifiers: Mod.LeftShift,
  Count: 1,
  Keys: [Key.H]
});
await device.send(input);

// Cleanup
await client.busdeviceremove(busID, deviceId);

Device Stream API

Creating a Device Stream

The simplest way to add a device and connect:

const { device, response } = await client.addDeviceAndConnect(busID, "xbox360");
const deviceId = response.id.split('-')[1];

Or connect to an existing device:

const device = await client.connectDevice(busId, deviceId);

Sending Input

Device input is sent using generated classes:

import { Xbox360 } from "viiperclient";

const { Xbox360Input, Button } = Xbox360;

const input = new Xbox360Input({
  Buttons: Button.A,
  Lt: 255,
  Rt: 0,
  Lx: -32768,  // Left stick left
  Ly: 32767,   // Left stick up
  Rx: 0,
  Ry: 0
});
await device.send(input);

Receiving Output (Events)

For devices that send feedback (rumble, LEDs), subscribe to the output event:

import { Keyboard } from "viiperclient";

const { LED } = Keyboard;

device.on("output", (data: Buffer) => {
  if (data.length < 1) return;
  const leds = data.readUInt8(0);

  console.log(`LEDs: ` +
    `Num=${(leds & LED.NumLock) !== 0} ` +
    `Caps=${(leds & LED.CapsLock) !== 0} ` +
    `Scroll=${(leds & LED.ScrollLock) !== 0}`);
});

For Xbox360 rumble:

device.on("output", (data: Buffer) => {
  if (data.length < 2) return;
  const leftMotor = data.readUInt8(0);
  const rightMotor = data.readUInt8(1);
  console.log(`Rumble: Left=${leftMotor} Right=${rightMotor}`);
});

Closing a Device

device.close();

Error Handling and Events

Device streams emit error and end events that should be handled:

device.on("error", async (err: Error) => {
  console.error(`Stream error: ${err}`);
  // Handle error and cleanup
});

device.on("end", async () => {
  console.log("Stream ended by server");
  // Handle disconnection and cleanup
});

For long-running applications with intervals or timers, stop them before cleanup:

let running = true;
const interval = setInterval(async () => {
  if (!running) return;

  try {
    await device.send(input);
  } catch (err) {
    console.error(`Send error: ${err}`);
    running = false;
    clearInterval(interval);
    // Cleanup...
  }
}, 16);

// Handle Ctrl+C gracefully
process.on("SIGINT", async () => {
  console.log("Stopping...");
  running = false;
  clearInterval(interval);
  device.close();
  await client.busdeviceremove(busId, deviceId);
  process.exit(0);
});

Generated Constants and Maps

The TypeScript SDK automatically generates enums and helper maps for each device type.

Keyboard Constants

Key Enum:

import { Keyboard } from "viiperclient";

const { Key } = Keyboard;

const key = Key.A;               // 0x04
const f1 = Key.F1;               // 0x3A
const enter = Key.Enter;         // 0x28

Modifier Flags:

import { Keyboard } from "viiperclient";

const { Mod } = Keyboard;

const mods = Mod.LeftShift | Mod.LeftCtrl;  // 0x03

LED Flags:

import { Keyboard } from "viiperclient";

const { LED } = Keyboard;

const { LED } = Keyboard;

const numLock = (leds & LED.NumLock) !== 0;
const capsLock = (leds & LED.CapsLock) !== 0;

Helper Maps

The SDK generates useful lookup maps for working with keyboard input:

CharToKey Map - Convert ASCII characters to key codes:

import { Keyboard } from "viiperclient";

const { CharToKeyGet } = Keyboard;

const key = CharToKeyGet('A'.codePointAt(0)!);
if (key !== undefined) {
  console.log(`'A' maps to ${key}`);  // Key.A
}

KeyName Map - Get human-readable key names:

import { Keyboard } from "viiperclient";

const { KeyNameGet } = Keyboard;

const name = KeyNameGet(Key.F1);
if (name !== undefined) {
  console.log(`Key name: ${name}`);  // "F1"
}

ShiftChars Map - Check if a character requires shift:

import { Keyboard } from "viiperclient";

const { ShiftCharsHas } = Keyboard;

const needsShift = ShiftCharsHas('A'.codePointAt(0)!);  // true for uppercase

Practical Example: Typing Text

Using the generated maps to type a string:

import { ViiperDevice, Keyboard } from "viiperclient";

const { KeyboardInput, CharToKeyGet, ShiftCharsHas, Mod } = Keyboard;

async function typeString(device: ViiperDevice, text: string): Promise<void> {
  for (const ch of text) {
    const cp = ch.codePointAt(0)!;
    const key = CharToKeyGet(cp);
    if (key === undefined) continue;

    const mods = ShiftCharsHas(cp) ? Mod.LeftShift : 0;

    // Press
    await device.send(new KeyboardInput({
      Modifiers: mods,
      Count: 1,
      Keys: [key]
    }));
    await new Promise(r => setTimeout(r, 50));

    // Release
    await device.send(new KeyboardInput({
      Modifiers: 0,
      Count: 0,
      Keys: []
    }));
    await new Promise(r => setTimeout(r, 50));
  }
}

// Usage
await typeString(device, "Hello, World!");

Device-Specific Wire Formats

Keyboard Input

interface KeyboardInput {
  Modifiers: number;    // Modifier flags (Ctrl, Shift, Alt, GUI)
  Count: number;        // Number of keys in Keys array
  Keys: number[];       // Key codes (max 6 for HID compliance)
}

Wire format: 1 byte modifiers + 1 byte count + N bytes keys (variable-length)

Keyboard Output (LEDs)

// Single byte with LED flags
const leds = data.readUInt8(0);
const numLock = (leds & LED.NumLock) !== 0;

Xbox360 Input

interface Xbox360Input {
  Buttons: number;     // Button flags
  Lt: number;          // Left trigger (0-255)
  Rt: number;          // Right trigger (0-255)
  Lx: number;          // Left stick X (-32768 to 32767)
  Ly: number;          // Left stick Y (-32768 to 32767)
  Rx: number;          // Right stick X (-32768 to 32767)
  Ry: number;          // Right stick Y (-32768 to 32767)
}

Wire format: Fixed 14 bytes, packed structure

Xbox360 Output (Rumble)

// Two bytes: left motor + right motor (0-255 each)
const leftMotor = data.readUInt8(0);
const rightMotor = data.readUInt8(1);

Mouse Input

interface MouseInput {
  Buttons: number;  // Button flags
  Dx: number;       // Relative X movement (-32768 to 32767)
  Dy: number;       // Relative Y movement (-32768 to 32767)
  Wheel: number;    // Vertical scroll (-128 to 127)
  Pan: number;      // Horizontal scroll (-128 to 127)
}

Wire format: Fixed 8 bytes, packed structure

Configuration and Advanced Usage

Custom Port

const client = new ViiperClient("localhost", 3242);

Default port is 3242 if not specified.

Error Handling

The server returns errors as JSON. The client throws exceptions:

try {
  await client.buscreate("invalid-bus-id");
} catch (err) {
  console.error(`Request failed: ${err}`);
}

Stream errors are surfaced through the EventEmitter error event:

device.on('error', (err) => {
  console.error(`Stream error: ${err}`);
});

Resource Management

Always close devices when done:

try {
  const device = await client.connectDevice(busId, deviceId);
  // ... use device ...
} finally {
  device.close();
}

Examples

Full working examples are available in the repository:

Virtual Keyboard: examples/typescript/virtual_keyboard.ts
Types "Hello!" every 5 seconds using generated maps
Displays LED feedback in console
Virtual Mouse: examples/typescript/virtual_mouse.ts
Moves cursor diagonally
Demonstrates button clicks and scroll wheel
Virtual Xbox360 Controller: examples/typescript/virtual_x360_pad.ts
Runs at 60fps with cycling buttons and animated triggers
Handles rumble feedback

Running Examples

cd examples/typescript
npm install
npm run build

node dist/virtual_keyboard.js localhost:3242

Troubleshooting

TODO