HTTP Client

This page maps the namespaced SDK resource methods to HTTP routes. Most apps should import createSimulatorClient() and use the resource API directly.

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

const simulatorClient = createSimulatorClient({
  // Base URL is the HTTP origin; resource methods append their route paths.
  baseUrl: 'http://127.0.0.1:4000',
})

Routes

SDK method	HTTP route	Response
simulatorClient.system.health()	GET /health	HealthResponse
simulatorClient.system.stats()	GET /api/stats	StatsResponse
simulatorClient.cards.get(ids)	GET /api/cards?ids=...	CardMetadata[]
simulatorClient.cards.resolveIds(references)	POST /api/cards/resolve	CardIdResolution[]
simulatorClient.cards.covered()	GET /api/cards/covered	CoveredCard[]
simulatorClient.matches.create(request)	POST /api/matches	MatchAccessResponse
simulatorClient.matches.join(match, request)	POST /api/matches/{matchId}/join	MatchAccessResponse
simulatorClient.matches.get(match)	GET /api/matches/{matchId}	GameState
simulatorClient.matches.applyFormatEvent(access, command)	POST /api/matches/{matchId}/format-events	GameState
simulatorClient.limitedEvents.create(request)	POST /api/limited-events	LimitedEventAccessResponse
simulatorClient.limitedEvents.join(event, request?)	POST /api/limited-events/{eventId}/join	LimitedEventAccessResponse
simulatorClient.limitedEvents.get(event)	GET /api/limited-events/{eventId}	LimitedEventSnapshot
simulatorClient.limitedEvents.applyCommand(access, command)	POST /api/limited-events/{eventId}/commands	LimitedEventSnapshot

Request validation

The SDK validates every request body before sending it:

// The SDK validates this request body before network I/O.
const premierHostDeck = {
  leader: 46102, // Leia Organa - Someone Who Loves You
  base: 308, // Echo Base
  cards: Array.from({ length: 50 }, () => 45), // Alliance X-Wing
}

await simulatorClient.matches.create({
  hostDeck: premierHostDeck,
})

Malformed bodies throw SdkValidationError before network I/O.

Response validation

Successful responses are validated against generated JSON schemas before they resolve. Schema drift or malformed response JSON throws SdkValidationError.

HTTP errors

Non-2xx responses throw EngineHttpError:

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

try {
  // Missing resources reject with EngineHttpError instead of returning null.
  await simulatorClient.matches.get('missing-match')
}
catch (error) {
  if (error instanceof EngineHttpError) {
    // Log stable fields that help route UI handling and diagnostics.
    console.warn(error.status, error.code, error.method, error.url)
  }
}

When the server returns a valid engine error payload, code and message come from that payload. If the body is empty, not JSON, or not shaped like api-error-response, the error still includes status, method, url, and the raw responseText when present.