imposterwords-sdk

TypeScript/JavaScript WebSocket SDK for the ImposterWords online mode. It wraps the live gateway at wss://ws.imposterwords.com/ws so you can create rooms, join rooms, start games, and react to server events with typed helpers.

• Zero dependencies, ESM-first, ships .d.ts
• Works in browsers (uses WebSocket) and Node (pass a ws-style implementation)
• Small helper methods for the core actions: create/join/start/vote/ready/play-again

Want to see the game? Play online on ImposterWords.com.

Install

npm install imposterwords-sdk
# or
yarn add imposterwords-sdk

Quickstart

import { ImposterWordsClient } from "imposterwords-sdk";

const client = new ImposterWordsClient({ autoConnect: true });

client.on("ROOM_CREATED", ({ roomId }) => {
  console.log("room ready", roomId);
});

client.on("GAME_STARTED", ({ role, word }) => {
  console.log("my role", role, "my word", word);
});

client.on("GAME_OVER", ({ winner }) => {
  console.log("winner side", winner);
});

client.createRoom({
  nickname: "Alice",
  avatar: "cat",
  config: {
    wordPack: "default",
    impostorCount: 1,
    mrWhiteCount: 0,
    playerCount: 10,
    impostorAwareness: false,
  },
});

For Node usage, pass a WebSocket implementation (for example from the ws package):

import WebSocket from "ws";
import { ImposterWordsClient } from "imposterwords-sdk";

const client = new ImposterWordsClient({
  WebSocketImpl: WebSocket,
});

await client.connect();
client.joinRoom({ roomId: "ABC123", nickname: "bot" });

Client methods

• connect() — open the socket (also auto-called when sending if closed)
• close(code?, reason?) — close the socket
• on(event, handler) — subscribe to any server event (ROOM_CREATED, GAME_STARTED, GAME_OVER, ERROR, etc.) or lifecycle (open, close, error)
• createRoom({ nickname, avatar?, config? })
• joinRoom({ roomId, nickname, avatar? })
• startGame(config?) — send START_GAME with optional config override
• setReady(isReady) — toggle ready status
• votePlayer(targetId) — send a vote
• playAgain() — ask host to reset

Server events

• ROOM_CREATED / JOINED_ROOM / PLAYER_JOINED — lobby snapshots and your player object
• ROOM_UPDATED / PLAYER_LEFT — lobby state changes
• GAME_STARTED — includes your secret role, word, and public players map
• VOTE_UPDATE / ROUND_END — vote progress and round transitions
• GAME_OVER — final state with winners
• ERROR — message with payload.message

Links

• Live game: https://www.imposterwords.com/
• How to play: https://www.imposterwords.com/how-to-play

License

MIT