Build on the live match.

Quick start

From install to synchronized state.

Create the client, subscribe before startup, and render the complete lifecycle from one immediate store.

npm install @w3booster/sdk

import { createClient } from '@w3booster/sdk';

const lifetime = new AbortController();
const client = createClient({
  clientId: 'your_app_id',
  signal: lifetime.signal
});

client.lifecycle.subscribe(snapshot => {
  renderConnection(snapshot.status);
  if (snapshot.state) renderMatch(snapshot.state);
}, { signal: lifetime.signal });

await client.start();

// Component or page teardown:
lifetime.abort();

start() resolves after the current connection has a synchronized state. Application code does not choose a WebSocket, carry credentials, apply patches, or implement reconnection.

Develop without W3Booster

Demo mode loads a representative fixture on demand and keeps demo code out of normal production startup.

const client = createClient({
  clientId: 'your_app_id',
  demo: true
});

await client.start();

Pass demo: { interval: 0, settings: { … } } for a deterministic fixture, or provide a complete demo state for focused UI tests.

Application model

One app. Up to three surfaces.

Every W3Booster app is a remotely hosted web application. Configure only the surfaces the product needs; hosting it yourself or through W3Booster does not change the SDK.

1. Enable Developer ModeUse the account menu in W3Booster, then open Apps → Developer.
2. Create a private appAdd its name, public client ID binding, requested scopes, and at least one HTTPS surface.
3. Build and testUse demo data for UI work and an owner-only local session for real match data.
4. Invite testersPrivate invitation codes grant discovery; each tester still installs and enables the app.

Local development

Use real data without deploying.

Run Vite, Angular, or any web server on localhost. In your app’s developer page, choose Test locally and add the local URLs for the surfaces you are working on.

The session installs and enables the app only for its owner and temporarily replaces only the chosen surfaces. Published metadata and other users do not change. Return to the published version at any time.

// Normal application code stays environment-free.
const client = createClient({ clientId: 'your_app_id' });

// Only platform developers normally force a backend.
const local = createClient({
  clientId: 'your_app_id',
  backend: 'local'
});

Cloud is the default. W3Booster may add ?backend=local or ?backend=cloud to a platform launch, and the SDK honors it automatically. Use backend: 'auto' only when intentionally trying local before cloud.

Frontend lifecycle

Render connection, freshness, and state together.

client.lifecycle is the preferred UI boundary. Its snapshot contains status, state, isSynchronized, and the current connection error. It publishes immediately and after every transition.

const client = createClient({
  clientId: 'your_app_id',
  retry: true,
  signal
});

client.lifecycle.subscribe(({ status, state, isSynchronized, error }) => {
  render({ status, state, fresh: isSynchronized, error });
}, { signal });

await client.start({ signal });

Automatic reconnect preserves hydrated state for visual continuity but sets isSynchronized to false until a fresh snapshot arrives. State is recursively immutable and structurally shared, so unchanged branches preserve identity.

State and scopes

One hydrated, capability-aware match model.

The platform filters data before serialization. A scope expresses which branch an app may read; it is not a subscription tier. state.capabilities is the final runtime answer after the app’s granted scopes, account plan, and match context have been applied. Individual optional values can still be absent when the live source does not provide them.

client.state.subscribe(state => {
  if (!state) return;

  const resources = state.capabilities.includes('resources')
    ? state.players[0]?.resources
    : undefined;

  renderResources(resources);
});

Complete API data model

Everything W3Booster delivers.

This is the full hydrated MatchState<TSettings> exposed by @w3booster/sdk. The SDK validates it at runtime, freezes it recursively, and maintains it from snapshots and patches.

Events and selectors

Observe the view model you need.

Use state subscriptions for complete rendering, watch() for one derived value, and domain events for meaningful changes after the initial snapshot.

const stopClock = client.state.watch(
  state => state?.match.gameTime ?? null,
  seconds => drawClock(seconds)
);

client.on('match.started', ({ match }) => showMatch(match));
client.on('player.resources.changed', ({ player, resources }) => {
  updateEconomy(player.id, resources);
});
client.on('hero.inventory.changed', ({ player, inventory }) => {
  updateInventory(player.id, inventory);
});

The initial snapshot emits state.ready and state.changed. It does not synthesize match.started for a match that was already running.

Pure selectors

import {
  broadcasterPlayer,
  groupPlayersByTeam,
  matchScore,
  playerRelationship
} from '@w3booster/sdk/selectors';

const broadcaster = broadcasterPlayer(state.match, state.players);
const teams = groupPlayersByTeam(state.players);
const score = matchScore(state);

Selectors are framework-free and never mutate state. The namespace also includes stable fallbacks, identity helpers, broadcaster-first teams, relationships, inventory, resources, upgrades, and overlay runtime.

Standard-game data and assets

Import only the Warcraft knowledge you use.

Rules, icons, and cooldown metadata have separate entry points. This keeps lightweight apps small while preserving a combined objects namespace for compatibility.

import * as game from '@w3booster/sdk/standard-game';
import * as icons from '@w3booster/sdk/standard-game/icons';
import * as cooldowns from '@w3booster/sdk/standard-game/cooldowns';

const heroIcon = icons.heroIconUrl(hero, {
  graphics: state.match.isReforged ? 'reforged' : 'classic'
});
const cooldown = cooldowns.abilityCooldown(ability, state.match.gameTime);
const clock = game.formatGameTime(state.match.gameTime);
const progress = game.heroExperienceState(hero.experience);

The standard-game namespace covers race labels, modes, player colors, statistics selection, game-time formatting, day/night state, hero progression, health/mana ratios, observer ordering, and presentation colors. Hosted Classic and Reforged icons resolve from the versioned static asset catalog; artwork is not bundled with npm.

Typed settings

Define settings once. Keep UI and types together.

Build the schema in W3Booster and let the client render consistent controls. The SDK can generate a checked-in TypeScript binding with the exact schema, defaults, scopes, client ID, and a managed application runtime.

npx w3booster-settings init app_your_id
npm run w3booster:sync
npm run w3booster:check

Commit src/w3booster.generated.ts. This keeps editor types and offline builds deterministic while making schema changes visible in code review.

import { w3boosterApp } from './w3booster.generated';

const runtime = w3boosterApp.createRuntime({ retry: true });

runtime.lifecycle.subscribe(snapshot => {
  renderMatch(snapshot.state, { fresh: snapshot.isSynchronized });
  renderSettings(snapshot.settings);
  renderHostActions(snapshot.host);
});

await runtime.start();
await runtime.stop();

The managed runtime resolves partial user settings over database defaults and publishes settings atomically with state and host capabilities. Lower-level tools remain available from @w3booster/sdk/settings.

Host actions

Ask the workspace. Await the result.

Embedded app surfaces can open or close windows, change Match Vision scores, persist typed settings, report their height, and issue app-specific commands. Every asynchronous action waits for a host acknowledgement.

import { canUseHostCapability } from '@w3booster/sdk';

client.host.lifecycle.subscribe(host => {
  setCompactEnabled(canUseHostCapability(host, 'window:open'));
});

await client.host.openWindow({
  path: '?view=compact',
  width: 520,
  height: 620
});

const saved = await client.host.setSetting(
  'observer.layout',
  'wide',
  { signal, timeout: 3000 }
);

Use host.can(capability) for imperative code or the reactive host lifecycle for UI. Capability discovery distinguishes pending, known, legacy, and unavailable hosts. Action cancellation raises AbortError; rejected execution raises HostActionError; missing or timed-out hosts raise ConnectionError.

Framework integration

Use the store your framework already understands.

The SDK has no frontend framework dependency. Its immediate stores map directly to Angular signals and RxJS; a small React subpath implements the complete useSyncExternalStore contract.

const store = createReactStore(client.lifecycle, {
  getServerSnapshot: () => ({
    status: 'idle', state: null,
    isSynchronized: false, error: null
  })
});

const snapshot = useSyncExternalStore(
  store.subscribe,
  store.getSnapshot,
  store.getServerSnapshot
);

const lifecycle = signal(client.lifecycle.get());

client.lifecycle.subscribe(
  snapshot => lifecycle.set(snapshot),
  { signal: lifetime.signal }
);

Errors and diagnostics

Separate startup failure from runtime issues.

Catch permanent startup errors around start(). Subscribe to structured issue events for recoverable connection, protocol, recorder, and listener problems that should not turn healthy match data into a failed UI.

import {
  classifyW3BoosterError,
  createClient
} from '@w3booster/sdk';

const client = createClient({ clientId: 'your_app_id' });

client.on('issue', issue => {
  console.warn(issue.source, issue.recoverable, issue.error);
});

try {
  await client.start();
} catch (error) {
  const info = classifyW3BoosterError(error);
  switch (info.kind) {
    case 'permission': showOpenFromW3Booster(); break;
    case 'connection': showOffline(info.code); break;
    case 'abort': break;
    default: report(info.error);
  }
}

Publish

Private first. Reviewed before discovery.

1. Complete the store listingAdd a clear description, surfaces, screenshots, source or homepage links, and requested scopes.
2. Test every surfaceCheck application, stream, and in-game behavior; disabled states; reconnects; and missing optional data.
3. Request reviewW3Booster reviews the record, hosted behavior, scope use, and user experience.
4. Make it publicAfter approval, users can discover and install it from the App Store. Metadata edits do not require another review.

Installation and enabling are separate platform states. Disabling preserves the app in the user’s library; uninstalling removes the grant. Revocation closes affected streams immediately.

Package reference

Focused entry points, one compatibility policy.