Client API

createSimulatorClient() returns the v0.2 resource-based client.

import { createSimulatorClient } from '@my-swu/simulator-client'

const simulatorClient = createSimulatorClient({
  // HTTP origin for `/health` and `/api/*` routes.
  baseUrl: 'http://127.0.0.1:4000',
})

Options

Option	Required	Description
baseUrl	yes	HTTP origin of the simulator server. Trailing slash optional.
fetch	no	Custom fetch implementation. Defaults to global fetch.
webSocketFactory	no	Custom browser-style WebSocket factory used by match sessions.

system

// System checks are useful for startup gates and diagnostics.
const health = await simulatorClient.system.health()
const stats = await simulatorClient.system.stats()

console.log(health.status, stats.covered, stats.total)

• health() calls /health.
• stats() returns card coverage and runtime statistics.

cards

// Card ids are loaded by the simulator server.
// 46102 = Leia Organa - Someone Who Loves You; 308 = Echo Base.
const requestedCardMetadata = await simulatorClient.cards.get([46102, 308])
const coveredCards = await simulatorClient.cards.covered()
const krennicCardId = await simulatorClient.cards.resolveId({
  setCode: 'SOR',
  cardNumber: 1,
  cardTypes: ['leader'],
})
const importedDeck = await simulatorClient.cards.convertDeckJson({
  leader: { id: 'SOR_001', count: 1 },
  base: { id: 'SOR_025', count: 1 },
  deck: [{ id: 'SOR_010', count: 3 }],
})

console.log(requestedCardMetadata[0], coveredCards.length, krennicCardId, importedDeck.cards.length)

• get(ids) returns canonical card metadata loaded from the server cache.
• covered() returns cards with dedicated simulator coverage.
• resolveId(reference) converts one set code plus printed card number into a card id. Pass cardTypes when the set number is ambiguous.
• resolveIds(references) performs the same lookup in batches and returns not-found or ambiguous match details.
• convertDeckJson(deckJson) converts my-swu JSON deck exports from SET_001 references into simulator DeckInput.

matches

// Deck payloads are validated before a match or seat is created.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
}

const premierGuestDeck = {
  leader: 46107, // Darth Vader - Unstoppable
  base: 309, // Tarkintown
  cards: Array.from({ length: 50 }, () => 35), // TIE/ln Fighter
}

const hostAccess = await simulatorClient.matches.create({ hostDeck: premierHostDeck })
// `join()` accepts the host access object and extracts the public match id.
const guestAccess = await simulatorClient.matches.join(hostAccess, { deck: premierGuestDeck })
const publicMatchSnapshot = await simulatorClient.matches.get(hostAccess)
// Sessions own socket state for one private seat.
const matchSession = simulatorClient.session.create(hostAccess)
await matchSession.connect()

// Format events handle out-of-game flows such as readiness between games.
await simulatorClient.matches.applyFormatEvent(hostAccess, { type: 'readyNextGame' })
console.log(guestAccess.seat, publicMatchSnapshot.status, matchSession.connectionState)

Match access objects returned by create() and join() can be passed directly to join(), get(), applyFormatEvent(), and session.create().

session

const matchSession = simulatorClient.session.create(hostAccess)

matchSession.on('change', sessionState => {
  console.log(sessionState.connectionState, sessionState.seat)
})

await matchSession.connect()
matchSession.ready()

Sessions keep private access out of renderable state while exposing connectionState, seat, snapshot, events, and errorMessages.

limitedEvents

// Limited Events create draft or sealed pools before you create a match.
const draftEventAccess = await simulatorClient.limitedEvents.create({
  kind: 'draft',
  setCode: 'SOR',
  playerCount: 4,
  seed: 7,
})

const draftSeatAccess = await simulatorClient.limitedEvents.join(draftEventAccess)
// Passing seat access includes viewer-private draft state.
const limitedEventSnapshot = await simulatorClient.limitedEvents.get(draftSeatAccess)
const nextLimitedEventSnapshot = await simulatorClient.limitedEvents.applyCommand(
  draftSeatAccess,
  { type: 'readyForNextDraft' },
)

console.log(limitedEventSnapshot.status, nextLimitedEventSnapshot.status)

Limited Event snapshots expose public pod state plus viewer-private pack, pick, and completed pool details when a valid seat token is supplied.