Client API

import { PlayMeshError } from '@playmesh/client';

try {
  await client.connect();
} catch (error) {
  if (error instanceof PlayMeshError && error.code === 'VERSION_MISMATCH') showUpdatePrompt();
  if (error instanceof PlayMeshError && error.code === 'APP_ONLY') showDownloadApp(); // server-defined code
}

await client.requestTo('world/shop', 'shop:buy', { itemId }).catch(error => {
  if (error.code === 'NOT_ENOUGH_COINS') openCoinShop();
});

// Static token
const client = new PlayMeshClient({
  url: 'https://game.example.com',
  auth: { token: localStorage.getItem('jwt') },
});

// Dynamic - refreshed on each reconnect
const client = new PlayMeshClient({
  url: 'https://game.example.com',
  auth: async () => ({ token: await authService.getToken() }),
});

await client.join('world/vip-lounge'); // rejects with the server's denial message
await client.leave('world/vip-lounge'); // always honored

client.onLeave(path => world.unload(path));
client.onJoin(path => world.load(path, client.stateOf(path))); // state is already seeded

client.stateOf('world/city');      // public state replica
client.userStateOf('world/city');  // your private state (only you receive it)
client.onStateChange(change => {
  // change.scope: 'public' | 'user' ('user' marks your private state)
  // change.revision: monotonic per-scope revision
});

client.presenceOf('world/city');   // { count, users }
client.onPresence(event => {
  // { instance, type: 'join' | 'leave', userId, sessionId, count }
});

client.chat('hello everyone');                 // every room you are in
client.chatTo('minigames/race-42', 'Ready!');  // exactly one room
client.onChat(message => console.log(`[${message.instance}] ${message.userId}: ${message.text}`));
client.onKick((reason, code) => console.log('Kicked:', code, reason));

type ClientEvents = { 'player:move': { x: number; y: number } };
type ServerEvents = { 'player:update': { x: number; y: number; by: string } };
type Requests = {
  'shop:buy': { request: { itemId: string }; response: { success: boolean; balance: number } };
};

const client = new PlayMeshClient<ClientEvents, ServerEvents, Requests>({ url });
client.emit('player:move', { x: 1, y: 2 }); // payload type-checked
const result = await client.requestTo('shop/main', 'shop:buy', { itemId: 'sword' }); // typed response

type Unsubscribe = () => void;  // returned by every listener API

interface SessionInfo {
  id: string;
  userId: string;
  roles: string[];      // kept current by live role updates
  instances: string[];  // "domainId/instanceId" paths
}

interface ServerError {
  scope: 'connection' | 'event' | 'join' | 'chat';
  code: string;         // e.g. 'RATE_LIMITED', 'ROLE_REQUIRED', or an app code
  event?: string;
  instance?: string;    // set for join errors and per-instance chat rejections
  message: string;
}

interface ChatMessage {
  instance: string;
  sessionId: string;
  userId: string;
  text: string;
  at: number;           // server timestamp (epoch ms)
}

interface PresenceEvent {
  instance: string;
  type: 'join' | 'leave';
  sessionId: string;
  userId: string;
  count: number;        // cluster-wide, after this change
}

interface PresenceInfo {
  count: number;
  users: string[];      // unique user ids currently in the instance
}

interface StateChange {
  instance: string;
  scope: 'public' | 'user';  // 'user' marks your private per-user state
  revision?: number;    // monotonic per-scope revision
  key?: string;         // absent for a clear or a batch
  value?: unknown;      // absent on delete
  cleared?: boolean;
  patch?: Record<string, unknown>;  // batch: keys set
  deleted?: string[];               // batch: keys removed
}

class PlayMeshError extends Error {
  code: string;
}

type Serialization = 'json' | 'msgpack';