archipelago

TypeScript client library for the Archipelago multi-game randomizer platform. Provides a dual client — WebSocket for real-time events and WebHost for REST API access — with zero production dependencies.

Installation

npm install archipelago-client

Requires Node.js 24+ (uses built-in WebSocket and fetch).

Quick Start

import {
  ArchipelagoClient,
  PrintJSONType,
  Version,
} from 'archipelago-client';

const client = new ArchipelagoClient({
  url: new URL('wss://archipelago.gg:38281'),
});

client.printJson.on(PrintJSONType.ItemSend, (event) => {
  console.log(`Slot ${event.receiving} received item ${event.item.item}`);
});

await client.connect();
await client.authenticate({
  name: 'MyBot',
  game: 'Hollow Knight',
  version: new Version('0.6.4'),
});

Examples

| Example | Description | |---------|-------------| | WebSocket events | Connect, authenticate, listen to ItemSend and other events | | DeathLink | Send and receive DeathLink events via bounce packets | | WebHost REST | Query room_status, tracker, and datapackage endpoints |

Run any example with npx tsx examples/<name>.ts (server configuration at the top of each file).

Cache: The WebSocket example demonstrates optional client-side caching (useCache: true) to persist game datapackages between sessions.

Testing

The project uses archipelago.gg for E2E testing. Test infrastructure lives in the sibling test-archi/ directory.

Setting Up a Test Room

cd ../test-archi
npm run generate    # Generate a seed on archipelago.gg
npm run host        # Host the game server

This generates a test seed on archipelago.gg and saves room information to test-archi/.room-info.json.

Running Tests

npm test              # Run the full test suite (Vitest)
npm run test:e2e      # Run E2E tests (requires a hosted room on archipelago.gg)

Note: E2E tests require a room to be hosted on archipelago.gg. Set one up with cd ../test-archi && npm run generate && npm run host.

For detailed setup, see the Test Infrastructure Documentation.

API Overview

| Class | Description | Events | |-------|-------------|--------| | ArchipelagoClient | WebSocket client for real-time multiworld communication | Connected, RoomUpdate, DataPackage, Bounced, error, deathlink, reconnecting/reconnected, … (PrintJSON events are on client.printJson) | | WebHostClient | REST client for the Archipelago WebHost API | — | | EventManager | Generic typed event emitter | Extensible | | PrintJSONManager | High-level PrintJSON event router | 15 PrintJSONType events | | Game | Game identifier (extends Tagged) | — | | Player | Network player representation | — | | Item | Network item representation | — | | Hint | Hint data structure | — |

Error Classes

| Class | Description | |-------|-------------| | ArchipelagoError | Base error class | | ArchipelagoConnectionError | WebSocket connection failures | | ArchipelagoAuthError | Authentication errors | | ArchipelagoPacketError | Packet parsing errors | | ArchipelagoWebHostError | Base WebHost error | | ArchipelagoWebHostNotFoundError | 404 responses | | ArchipelagoWebHostRateLimitError | 429 rate limit responses | | ArchipelagoWebHostServerError | 5xx server errors |

For the complete API reference, see the TypeDoc documentation.

Contribuer

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to dist/ | | npm test | Run the test suite (Vitest) | | npm run lint | Lint with Biome | | npm run docs | Generate TypeDoc HTML in docs/ |

Conventions

• Commits : Conventional Commits (enforced by commitlint + husky).
• Suffixes de fichiers : .class.ts, .enum.ts, .interface.ts, .type.ts pour une lisibilité immédiate.
• Zéro dépendance production : la library ne dépend que des APIs natives Node.js 23+ (WebSocket, fetch, node:fs, node:crypto).