@dimcool/sdk 0.1.0-beta.1

package/README.md

@@ -0,0 +1,3028 @@
+# Dim SDK
+
+A TypeScript SDK for interacting with the Dim API. The SDK provides a clean, type-safe interface organized by feature modules.
+
+Canonical docs:
+
+- https://docs.dim.cool/capabilities/api-admin-operations
+- https://docs.dim.cool/quickstart/sdk-node
+- https://docs.dim.cool/api-reference/overview
+
+## Installation
+
+```bash
+npm install @dimcool/sdk
+# or
+bun add @dimcool/sdk
+```
+
+## Quick Start
+
+### Browser
+
+```typescript
+import { SDK, BrowserLocalStorage } from '@dimcool/sdk';
+
+const sdk = new SDK({
+  appId: 'dim',
+  baseUrl: 'https://api.example.com',
+  storage: new BrowserLocalStorage(),
+});
+
+// Authenticate
+await sdk.auth.login('user@example.com', 'password');
+
+// Check authentication status
+if (sdk.auth.isAuthenticated()) {
+  // Use SDK methods
+  const users = await sdk.users.getUsers();
+  const flags = await sdk.featureFlags.getFeatureFlags();
+}
+```
+
+### Node.js
+
+```typescript
+import { SDK, NodeStorage } from '@dimcool/sdk';
+
+const sdk = new SDK({
+  appId: 'dim-bots',
+  baseUrl: 'https://api.dim.cool',
+  storage: new NodeStorage(),
+});
+
+await sdk.auth.login('user@example.com', 'password');
+```
+
+### Agent Usage (Wallet Auth)
+
+AI agents authenticate using a Solana keypair — no email or browser needed. Use `appId: 'dim-agents'` to identify agent traffic.
+
+```typescript
+import { SDK, NodeStorage } from '@dimcool/sdk';
+import { Keypair } from '@solana/web3.js';
+import bs58 from 'bs58';
+import nacl from 'tweetnacl';
+
+const sdk = new SDK({
+  appId: 'dim-agents',
+  baseUrl: 'https://api.dim.cool',
+  storage: new NodeStorage(),
+});
+
+// Wallet auth
+const keypair = Keypair.fromSecretKey(bs58.decode(process.env.PRIVATE_KEY!));
+const walletAddress = keypair.publicKey.toBase58();
+sdk.wallet.setSigner({
+  address: walletAddress,
+  signMessage: async (message: string) => {
+    const messageBytes = new TextEncoder().encode(message);
+    const signature = nacl.sign.detached(messageBytes, keypair.secretKey);
+    return Buffer.from(signature).toString('base64');
+  },
+  signTransaction: async (transaction) => {
+    transaction.partialSign(keypair);
+    return transaction;
+  },
+});
+
+const { access_token, user } = await sdk.auth.loginWithWallet({
+  referralCode: 'optional-referral-code',
+  walletMeta: { type: 'keypair' },
+});
+
+// WebSocket (for games and chat)
+sdk.wsTransport.setAccessToken(access_token);
+await sdk.ensureWebSocketConnected(10000);
+
+// Now use any SDK module
+const balance = await sdk.wallet.getBalances();
+const referrals = await sdk.referrals.getSummary();
+```
+
+**MCP alternative:** For MCP-compatible agents (Claude, Cursor, OpenClaw), use [`@dimcool/mcp`](../dim-mcp/README.md) instead — it wraps this SDK into MCP tools automatically.
+
+## Configuration
+
+The SDK constructor accepts a configuration object:
+
+```typescript
+interface SDKConfig {
+  appId: string; // Required: identifies the app (e.g. 'dim', 'dim-admin')
+  baseUrl?: string; // Default: 'http://localhost:3000'
+  storage: IStorage; // Required: Storage implementation
+  httpClient?: IHttpClient; // Optional: injectable HTTP client for testing
+  wsTransport?: WsTransport; // Optional: injectable WS transport
+  logger?: ILogger; // Optional: logger instance
+}
+```
+
+### appId
+
+Every SDK instance must provide an `appId` that identifies which app is making requests. The API validates this against its [app registry](../../apps/api/src/config/apps.config.ts) and rejects unknown app IDs.
+
+The `appId` is:
+
+- Sent as `X-App-Id` header on all HTTP requests
+- Included in the Socket.IO auth handshake for WebSocket connections
+- Stored on user records (`signupAppId`, `lastLoginAppId`) and sessions
+
+## Storage
+
+The SDK requires a storage implementation to persist authentication tokens. Two implementations are provided:
+
+- **`BrowserLocalStorage`**: Uses browser's `localStorage` API (browser only)
+- **`NodeStorage`**: Uses in-memory storage for Node.js environments
+
+### Custom Storage
+
+You can implement your own storage by creating a class that implements the `IStorage` interface:
+
+```typescript
+import { IStorage } from '@dimcool/sdk';
+
+class CustomStorage implements IStorage {
+  set(key: string, value: string): void {
+    // Your implementation
+  }
+
+  get(key: string): string | null {
+    // Your implementation
+  }
+
+  delete(key: string): void {
+    // Your implementation
+  }
+}
+```
+
+## API Reference
+
+The SDK is organized into modules accessible via properties on the SDK instance:
+
+- `sdk.auth` - Authentication methods
+- `sdk.admin` - Platform-wide admin operations
+- `sdk.users` - User management and social features
+- `sdk.featureFlags` - Feature flag management
+- `sdk.lobbies` - Game lobby management
+- `sdk.games` - Game type management
+- `sdk.chat` - Generic chat system (lobbies, games, DMs)
+- `sdk.challenges` - Create and accept game challenges (standalone; global chat `/challenge` is a shorthand)
+- `sdk.notifications` - App notifications (admin only)
+- `sdk.wallet` - Solana wallet management and transaction signing
+- `sdk.escrow` - Escrow and deposit management for game lobbies
+- `sdk.activity` - Global activity feed (signups, wins, lobbies, games)
+- `sdk.leaderboards` - Leaderboard data (global, per-game, friends)
+- `sdk.reports` - User reports (create reports, admin management)
+- `sdk.support` - Support tickets (create tickets, messages, track issues)
+- `sdk.markets` - Prediction market trading (buy/sell shares, positions, redemption)
+
+---
+
+## Authentication (`sdk.auth`)
+
+### `login(email: string, password: string): Promise<LoginResponse>`
+
+Authenticate a user and store the access token.
+
+```typescript
+const response = await sdk.auth.login('user@example.com', 'password');
+// response: { access_token: string, user: { id, email, username, isAdmin, chessElo, points } }
+```
+
+### `logout(): void`
+
+Clear the authentication token and log out the user.
+
+```typescript
+sdk.auth.logout();
+```
+
+### `isAuthenticated(): boolean`
+
+Check if the user is currently authenticated.
+
+```typescript
+if (sdk.auth.isAuthenticated()) {
+  // User is logged in
+}
+```
+
+### `loginWithWallet(options?: { referralCode?: string; walletMeta?: WalletMeta }): Promise<LoginResponse>`
+
+Authenticate with a configured wallet signer. The SDK handles handshake generation and message-signature verification flow internally.
+
+```typescript
+const response = await sdk.auth.loginWithWallet({
+  referralCode: 'optional-referral-code',
+  walletMeta: { type: 'keypair' },
+});
+// response: { access_token: string, user: { id, email, username, isAdmin, chessElo, points } }
+```
+
+**Complete Wallet Login Flow:**
+
+```typescript
+import { SDK, BrowserLocalStorage } from '@dimcool/sdk';
+import { Keypair } from '@solana/web3.js';
+import * as nacl from 'tweetnacl';
+
+const sdk = new SDK({
+  appId: 'dim',
+  baseUrl: 'https://api.example.com',
+  storage: new BrowserLocalStorage(),
+});
+
+// 1. Get the user's wallet address (from their wallet provider)
+const walletAddress = '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU';
+
+// 2. Register signer (SDK handles handshake + signing orchestration)
+sdk.wallet.setSigner({
+  address: walletAddress,
+  signMessage: async (message: string) => {
+    const messageBytes = new TextEncoder().encode(message);
+    const signature = nacl.sign.detached(messageBytes, keypair.secretKey);
+    return Buffer.from(signature).toString('base64');
+  },
+  signTransaction: async (transaction) => transaction,
+});
+
+// 3. Login with wallet
+const response = await sdk.auth.loginWithWallet();
+console.log('Logged in as:', response.user.id);
+```
+
+**Note:** In a real application, signer methods are typically provided by wallet providers (Phantom, Solflare, Keypair, etc.). `sdk.auth.loginWithWallet` handles the backend auth flow once signer is configured.
+
+---
+
+## Users (`sdk.users`)
+
+### Admin Methods
+
+#### `getUsers(page?: number, limit?: number, username?: string): Promise<PaginatedUsers>`
+
+Get a paginated list of users. Admin only. Optionally filter by username prefix.
+
+```typescript
+const result = await sdk.users.getUsers(1, 10, 'john');
+// result: { users: User[], total: number, page: number, limit: number, totalPages: number }
+```
+
+#### `getUserById(id: string): Promise<User>`
+
+Get user details by ID.
+
+```typescript
+const user = await sdk.users.getUserById('user-id');
+```
+
+### Username Management
+
+#### `isUsernameAvailable(username: string): Promise<UsernameAvailabilityResponse>`
+
+Check if a username is valid and available.
+
+```typescript
+const result = await sdk.users.isUsernameAvailable('myusername');
+// result: { valid: boolean, available: boolean }
+```
+
+#### `updateUsername(username: string): Promise<User>`
+
+Update the current user's username. Username must be:
+
+- Alphanumeric only
+- 3-20 characters
+- Unique
+
+```typescript
+const availability = await sdk.users.isUsernameAvailable('myusername');
+if (availability.valid && availability.available) {
+  const updatedUser = await sdk.users.updateUsername('myusername');
+}
+```
+
+#### `getPublicUserByUsername(username: string): Promise<PublicUser>`
+
+Get public user profile by username. Returns user info with `friendsCount`, `chessElo`, `points`, and optional `isFriend` (if authenticated).
+
+```typescript
+const publicUser = await sdk.users.getPublicUserByUsername('someuser');
+console.log(`Friends count: ${publicUser.friendsCount}`);
+console.log(`Is friend: ${publicUser.isFriend}`);
+```
+
+#### `searchUsers(username: string, page?: number, limit?: number): Promise<PaginatedSearchUsers>`
+
+Search users by username prefix.
+
+```typescript
+const results = await sdk.users.searchUsers('john', 1, 10);
+// results: { users: SearchUser[], total: number, page: number, limit: number, totalPages: number }
+```
+
+### Friends
+
+#### `getFriends(userId: string, page?: number, limit?: number, search?: string): Promise<PaginatedFriends>`
+
+Get paginated friends list for a user. Requires authentication. Users can only view their own friends; admins can view any user's friends.
+
+```typescript
+const friends = await sdk.users.getFriends('user-id', 1, 10, 'search-term');
+// friends: { friends: PublicUser[], total: number, page: number, limit: number, totalPages: number }
+```
+
+#### `addFriend(userId: string): Promise<{ message: string }>`
+
+Add a user as a friend.
+
+```typescript
+await sdk.users.addFriend('user-id');
+```
+
+#### `removeFriend(userId: string): Promise<{ message: string }>`
+
+Remove a user from friends.
+
+```typescript
+await sdk.users.removeFriend('user-id');
+```
+
+#### `isFriend(userId: string): Promise<boolean>`
+
+Check if a user is a friend. Note: This is a helper method that may require additional API calls. For better performance, use `getPublicUserByUsername()` which includes `isFriend` in the response.
+
+```typescript
+const isFriend = await sdk.users.isFriend('user-id');
+```
+
+### Profile Management
+
+#### `updateProfile(data: { name?: string, bio?: string, username?: string }): Promise<User>`
+
+Update the current user's profile. All fields are optional.
+
+```typescript
+const updatedUser = await sdk.users.updateProfile({
+  name: 'John Doe',
+  bio: 'Gaming enthusiast',
+  username: 'johndoe',
+});
+```
+
+#### `uploadAvatar(file: File): Promise<User>`
+
+Upload an avatar image for the current user. The file must be:
+
+- An image (JPEG, PNG, WebP, or GIF)
+- Maximum 5MB in size
+
+```typescript
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+const updatedUser = await sdk.users.uploadAvatar(file);
+```
+
+#### `uploadCoverImage(file: File): Promise<User>`
+
+Upload a cover image for the current user. The file must be:
+
+- An image (JPEG, PNG, WebP, or GIF)
+- Maximum 5MB in size
+
+```typescript
+const fileInput = document.querySelector('input[type="file"]');
+const file = fileInput.files[0];
+const updatedUser = await sdk.users.uploadCoverImage(file);
+```
+
+#### `removeAvatar(): Promise<User>`
+
+Remove the current user's avatar.
+
+```typescript
+const updatedUser = await sdk.users.removeAvatar();
+```
+
+#### `removeCoverImage(): Promise<User>`
+
+Remove the current user's cover image.
+
+```typescript
+const updatedUser = await sdk.users.removeCoverImage();
+```
+
+#### `getCurrentGame(userId: string): Promise<CurrentGame | null>`
+
+Get the current active game for a user (if they are a player in one). Returns `{ gameId, gameType, status }` or `null`. Used for profile "Playing X" banner and spectate link.
+
+```typescript
+const current = await sdk.users.getCurrentGame('user-id');
+if (current) {
+  console.log(`User is in game ${current.gameId} (${current.gameType})`);
+}
+```
+
+#### `getUserActivity(userId: string): Promise<UserActivity>`
+
+Get a user's current activity for the **spectate-user** flow: whether they are in a game, in a lobby, or idle. Use this when building a "Watch [username]" experience: poll every few seconds while showing a waiting room; when `status === 'in_game'`, redirect to the game with `gameType` and `gameId`.
+
+```typescript
+const activity = await sdk.users.getUserActivity('user-id');
+// activity: { status: 'in_game' | 'in_lobby' | 'idle', gameId?, gameType?, lobbyId?, lobbyStatus? }
+if (activity.status === 'in_game' && activity.gameId && activity.gameType) {
+  // Navigate to /game/${activity.gameType}/${activity.gameId}
+}
+```
+
+- **Resolving username to userId:** call `getPublicUserByUsername(username)` first to get the user's `id`, then call `getUserActivity(id)`.
+- **Polling:** when showing a waiting room (user idle or in lobby), poll every 3–5 seconds until they enter a game or the viewer leaves.
+- For listing and joining live games by game ID, see **Games** → `getLiveGames()` and **Spectating** in the docs.
+
+#### `getGameHistory(userId: string): Promise<GameHistoryItem[]>`
+
+Get game history for a user. Returns the last 10 games played by the specified user. Any logged-in user can query game history for any player.
+
+```typescript
+const history = await sdk.users.getGameHistory('user-id');
+// history: GameHistoryItem[]
+// Each item includes: id, gameType, gameName, gameImage, result, betAmount, winnings, opponent, playedAt
+```
+
+**Response format:**
+
+```typescript
+interface GameHistoryItem {
+  id: string;
+  gameType: string;
+  gameName: string;
+  gameImage?: string;
+  result: 'win' | 'loss' | 'draw';
+  betAmount: number;
+  winnings?: number;
+  opponent?: {
+    id: string;
+    username?: string;
+    avatar?: string;
+  };
+  playedAt: string;
+}
+```
+
+#### `getUserStats(userId: string): Promise<UserStats>`
+
+Get aggregated game statistics for a user. Returns aggregated stats including games played, wins, losses, total earned, and total lost. Any logged-in user can query stats for any player.
+
+```typescript
+const stats = await sdk.users.getUserStats('user-id');
+// stats: UserStats
+// Includes: gamesPlayed, wins, losses, totalEarned, totalLost, totalFeesPaid, referralEarned, chessElo, points
+```
+
+**Response format:**
+
+```typescript
+interface UserStats {
+  gamesPlayed: number; // Total count of all games where user is in playerIds
+  wins: number; // Count of games where user won
+  losses: number; // Count of games where user lost
+  totalEarned: number; // Sum of wonAmount for all games won
+  referralEarned: number; // Sum of referral rewards
+  totalLost: number; // Sum of betAmount for all games lost
+  totalFeesPaid: number; // Sum of platform fees paid
+  chessElo: number; // Current chess Elo rating
+  points: number; // Accumulated engagement points (10 pts per $0.01 of fee)
+}
+```
+
+**Example:**
+
+```typescript
+const stats = await sdk.users.getUserStats('user-id');
+console.log(`Games played: ${stats.gamesPlayed}`);
+console.log(`Wins: ${stats.wins}, Losses: ${stats.losses}`);
+console.log(`Total earned: $${stats.totalEarned}`);
+console.log(`Total lost: $${stats.totalLost}`);
+console.log(`Chess Elo: ${stats.chessElo}`);
+console.log(`Points: ${stats.points}`);
+```
+
+**Notes:**
+
+- Draws (`winnerId === null`) are counted in `gamesPlayed` but not in `wins`, `losses`, `totalEarned`, or `totalLost`
+- Returns all zeros if the user has no game history
+- `totalEarned` and `totalLost` default to 0 if `wonAmount` or `betAmount` are null
+
+## Admin (`sdk.admin`)
+
+### `getStats(): Promise<AdminStats>`
+
+Get platform-wide aggregated statistics. Admin only. Returns total games played, total fees generated, and total users.
+
+```typescript
+const stats = await sdk.admin.getStats();
+// stats: AdminStats
+// Includes: totalGamesPlayed, totalFeesGenerated, totalUsers
+```
+
+**Response format:**
+
+```typescript
+interface AdminStats {
+  totalGamesPlayed: number; // Total count of all games in GameHistory
+  totalFeesGenerated: number; // Sum of 1% of betAmount for all games (where betAmount is not null)
+  totalUsers: number; // Total count of users in User table
+}
+```
+
+**Example:**
+
+```typescript
+const stats = await sdk.admin.getStats();
+console.log(`Total games: ${stats.totalGamesPlayed}`);
+console.log(`Total fees: $${stats.totalFeesGenerated.toFixed(2)}`);
+console.log(`Total users: ${stats.totalUsers}`);
+```
+
+**Notes:**
+
+- **Admin only**: Requires admin authentication. Non-admin users will receive a 403 Forbidden error
+
+### User Banning (Admin)
+
+### `banUser(userId: string, reason?: string): Promise<User>`
+
+Ban a user (admin only). Banned users cannot log in or access the API.
+
+```typescript
+const user = await sdk.admin.banUser(
+  'user-id',
+  'Violation of terms of service',
+);
+console.log(`User banned: ${user.banned}`);
+```
+
+**Parameters:**
+
+- `userId: string` - The ID of the user to ban
+- `reason?: string` - Optional reason for the ban
+
+**Returns:** Updated user object with `banned: true`, `bannedAt`, and `bannedReason` fields.
+
+### `unbanUser(userId: string): Promise<User>`
+
+Unban a user (admin only). Restores the user's access to the platform.
+
+```typescript
+const user = await sdk.admin.unbanUser('user-id');
+console.log(`User unbanned: ${!user.banned}`);
+```
+
+**Parameters:**
+
+- `userId: string` - The ID of the user to unban
+
+**Returns:** Updated user object with `banned: false`.
+
+**Notes:**
+
+- Banned users receive a 403 Forbidden error with code `ACCOUNT_BANNED` when trying to log in or access any authenticated endpoint
+- Banned users are directed to contact support@dim.gg to appeal their ban
+
+---
+
+## Reports (`sdk.reports`)
+
+The reports module allows users to report other users and admins to manage reports.
+
+### User Methods
+
+#### `create(reportedUserId: string, reason: string): Promise<Report>`
+
+Create a report against another user. Rate limited to 5 reports per hour.
+
+```typescript
+const report = await sdk.reports.create(
+  'user-id',
+  'Inappropriate behavior in chat',
+);
+console.log(`Report created: ${report.id}`);
+```
+
+**Parameters:**
+
+- `reportedUserId: string` - The ID of the user being reported
+- `reason: string` - The reason for the report (max 300 characters)
+
+**Notes:**
+
+- Users cannot report themselves
+- Rate limited to 5 reports per hour per user
+- Returns 429 Too Many Requests when rate limit is exceeded
+
+### Admin Methods
+
+#### `list(options?: GetReportsOptions): Promise<PaginatedReports>`
+
+Get all reports (admin only, paginated).
+
+```typescript
+const reports = await sdk.reports.list({
+  page: 1,
+  limit: 10,
+  status: 'PENDING',
+});
+console.log(`Found ${reports.total} reports`);
+```
+
+**Parameters:**
+
+- `options.page?: number` - Page number (default: 1)
+- `options.limit?: number` - Results per page (default: 10)
+- `options.status?: ReportStatus` - Filter by status (PENDING, READ, RESOLVED, DISMISSED)
+
+#### `getById(id: string): Promise<Report>`
+
+Get a single report by ID (admin only).
+
+```typescript
+const report = await sdk.reports.getById('report-id');
+```
+
+#### `getByUser(userId: string): Promise<Report[]>`
+
+Get all reports for a specific user (admin only).
+
+```typescript
+const reports = await sdk.reports.getByUser('user-id');
+console.log(`User has ${reports.length} reports`);
+```
+
+#### `getCountByUser(userId: string): Promise<ReportCount>`
+
+Get report count for a specific user (admin only).
+
+```typescript
+const count = await sdk.reports.getCountByUser('user-id');
+console.log(`User has ${count.count} reports`);
+```
+
+#### `getPendingCount(): Promise<{ count: number }>`
+
+Get count of pending reports (admin only).
+
+```typescript
+const { count } = await sdk.reports.getPendingCount();
+console.log(`${count} pending reports`);
+```
+
+#### `update(id: string, data: UpdateReportData): Promise<Report>`
+
+Update a report status/notes (admin only).
+
+```typescript
+const report = await sdk.reports.update('report-id', {
+  status: 'RESOLVED',
+  adminNotes: 'Reviewed and user has been warned',
+});
+```
+
+**Parameters:**
+
+- `id: string` - The report ID
+- `data.status?: ReportStatus` - New status (PENDING, READ, RESOLVED, DISMISSED)
+- `data.adminNotes?: string` - Admin notes
+
+#### `delete(id: string): Promise<void>`
+
+Delete a report (admin only).
+
+```typescript
+await sdk.reports.delete('report-id');
+```
+
+### Report Types
+
+```typescript
+type ReportStatus = 'PENDING' | 'READ' | 'RESOLVED' | 'DISMISSED';
+
+interface Report {
+  id: string;
+  reporterId: string;
+  reportedUserId: string;
+  reason: string;
+  status: ReportStatus;
+  adminNotes?: string;
+  createdAt: string;
+  updatedAt: string;
+  reporter?: ReportUser;
+  reportedUser?: ReportUser;
+}
+
+interface ReportUser {
+  id: string;
+  username?: string;
+  avatar?: string;
+}
+```
+
+---
+
+## Support Tickets (`sdk.support`)
+
+Built-in support ticket system for communicating with the DIM team. Users and agents can create tickets, add follow-up messages, and track resolution. Admin methods are also available for managing all tickets.
+
+### `create(data): Promise<SupportTicket>`
+
+Create a new support ticket. Rate limited to 5 per hour.
+
+```typescript
+const ticket = await sdk.support.create({
+  message: 'I cannot withdraw my USDC balance',
+  category: 'PAYMENT', // optional, default: OTHER
+  subject: 'Withdrawal Issue', // optional, auto-generated from category
+  email: 'me@example.com', // optional contact email
+});
+console.log(`Ticket #${ticket.id}: ${ticket.subject} [${ticket.status}]`);
+```
+
+### `getMyTickets(options?): Promise<PaginatedSupportTickets>`
+
+List your own tickets with optional filters.
+
+```typescript
+const { tickets, total } = await sdk.support.getMyTickets({
+  status: 'OPEN', // optional
+  category: 'BUG', // optional
+  page: 1,
+  limit: 10,
+});
+```
+
+### `getMyTicketById(ticketId): Promise<SupportTicket>`
+
+Get a specific ticket with all messages.
+
+```typescript
+const ticket = await sdk.support.getMyTicketById('ticket-uuid');
+ticket.messages?.forEach((msg) => {
+  console.log(`[${msg.senderRole}] ${msg.content}`);
+});
+```
+
+### `addMessage(ticketId, message): Promise<SupportMessage>`
+
+Add a follow-up message to your ticket.
+
+```typescript
+await sdk.support.addMessage('ticket-uuid', 'Here is more detail...');
+```
+
+### `closeTicket(ticketId): Promise<SupportTicket>`
+
+Close a ticket when your issue is resolved.
+
+```typescript
+await sdk.support.closeTicket('ticket-uuid');
+```
+
+### Admin Methods
+
+```typescript
+// List all tickets (admin only)
+const all = await sdk.support.list({ status: 'OPEN', page: 1, limit: 10 });
+
+// Get open ticket count (admin only)
+const { count } = await sdk.support.getOpenCount();
+
+// Get any ticket by ID (admin only)
+const ticket = await sdk.support.getById('ticket-uuid');
+
+// Update status/priority (admin only)
+await sdk.support.update('ticket-uuid', {
+  status: 'IN_PROGRESS',
+  priority: 'HIGH',
+});
+
+// Reply to a ticket (admin only)
+await sdk.support.reply('ticket-uuid', 'We are looking into this.');
+
+// Delete a ticket (admin only)
+await sdk.support.delete('ticket-uuid');
+```
+
+### Support Types
+
+```typescript
+type SupportTicketStatus =
+  | 'OPEN'
+  | 'IN_PROGRESS'
+  | 'WAITING_REPLY'
+  | 'RESOLVED'
+  | 'CLOSED';
+type SupportTicketCategory =
+  | 'BUG'
+  | 'FEATURE_REQUEST'
+  | 'QUESTION'
+  | 'ACCOUNT'
+  | 'PAYMENT'
+  | 'GAME'
+  | 'TECHNICAL'
+  | 'OTHER';
+type SupportTicketPriority = 'LOW' | 'NORMAL' | 'HIGH' | 'URGENT';
+type SupportMessageSenderRole = 'USER' | 'ADMIN';
+
+interface SupportTicket {
+  id: string;
+  userId: string;
+  subject: string;
+  category: SupportTicketCategory;
+  status: SupportTicketStatus;
+  priority: SupportTicketPriority;
+  createdAt: string;
+  updatedAt: string;
+  user?: SupportTicketUser;
+  messages?: SupportMessage[];
+  messageCount?: number;
+}
+
+interface SupportMessage {
+  id: string;
+  ticketId: string;
+  senderId: string;
+  senderRole: SupportMessageSenderRole;
+  content: string;
+  createdAt: string;
+  sender?: SupportTicketUser;
+}
+```
+
+---
+
+## Challenges (`sdk.challenges`)
+
+Standalone API for creating and accepting game challenges. Any user can challenge any other user (by id or username). Global chat `/challenge` is a shorthand that uses the same backend; use `sdk.challenges` when you want to create or accept challenges outside of chat (e.g. from a profile page or notifications).
+
+**Game fees:** Accepted challenges create a lobby with the chosen amount. Game fees apply: 1% per player, minimum 1 cent per player.
+
+### `create(dto: CreateChallengeRequest): Promise<CreateChallengeResponse>`
+
+Create a challenge.
+
+```typescript
+const result = await sdk.challenges.create({
+  gameType: 'rock-paper-scissors',
+  amount: 500_000, // USDC minor units; min $0.10 (100_000), no max
+  targetUserId: 'user-id', // or use targetUsername
+  targetUsername: 'alice',
+});
+// result: { challengeId, challengerId, targetUserId, gameType, amountMinor, challengerUsername? }
+```
+
+- **amount:** USDC minor units (6 decimals). Minimum $0.10 (100_000), no maximum.
+- **targetUserId** or **targetUsername:** The user to challenge (username can include or omit `@`).
+
+### `accept(challengeId: string): Promise<AcceptChallengeResponse>`
+
+Accept a challenge. Only the challenged user can accept. Creates a lobby with the challenge amount and adds both users.
+
+```typescript
+const result = await sdk.challenges.accept('challenge-id');
+// result: { lobbyId, gameId?, status }
+```
+
+---
+
+## Wallet Module
+
+The wallet module provides functionality for managing Solana wallets, checking balances, and signing transactions. **Transfers and tips** incur a 1 cent fee per transfer/tip; the fee is shown before you confirm. The SDK uses a **pluggable signer interface** that allows different signing implementations (e.g., Phantom wallet, Keypair for bots) to be used.
+
+### WalletSigner Interface
+
+The SDK exposes a `WalletSigner` interface for transaction and message signing:
+
+```typescript
+interface WalletSigner {
+  signMessage: (message: string) => Promise<Uint8Array | string>;
+  signTransaction: (transaction: Transaction) => Promise<Transaction>;
+}
+```
+
+This allows the SDK to remain agnostic about how signing is implemented - you can use Phantom wallet for browser apps, or a Keypair for bot applications.
+
+If you're building agents, you can use `@dimcool/wallet` and pass `wallet.getSigner()` directly:
+
+```typescript
+import { Wallet } from '@dimcool/wallet';
+
+const wallet = new Wallet({
+  enabledNetworks: ['solana'],
+  fromPrivateKey: process.env.DIM_WALLET_PRIVATE_KEY!,
+});
+
+sdk.wallet.setSigner(wallet.getSigner());
+```
+
+### `setSigner(signer: WalletSigner): void`
+
+Configure the wallet signer. This must be called before any signing operations.
+
+```typescript
+// Example: Using Phantom wallet (in apps/web)
+import { useSolana } from '@phantom/react-sdk';
+
+const { solana } = useSolana();
+
+sdk.wallet.setSigner({
+  signMessage: async (message: string) => {
+    return solana.signMessage(new TextEncoder().encode(message));
+  },
+  signTransaction: async (transaction: Transaction) => {
+    return solana.signTransaction(transaction);
+  },
+});
+```
+
+```typescript
+// Example: Using a Keypair (for bots/Node.js)
+import { Keypair } from '@solana/web3.js';
+import * as nacl from 'tweetnacl';
+
+const keypair = Keypair.fromSecretKey(/* ... */);
+
+sdk.wallet.setSigner({
+  signMessage: async (message: string) => {
+    const messageBytes = new TextEncoder().encode(message);
+    return nacl.sign.detached(messageBytes, keypair.secretKey);
+  },
+  signTransaction: async (transaction: Transaction) => {
+    transaction.partialSign(keypair);
+    return transaction;
+  },
+});
+```
+
+### `hasSigner(): boolean`
+
+Check if a signer has been configured.
+
+```typescript
+if (!sdk.wallet.hasSigner()) {
+  // Configure signer before signing operations
+  sdk.wallet.setSigner(mySigner);
+}
+```
+
+### `loadWallet(): Promise<WalletResponse>`
+
+Load the user's wallet data from the API.
+
+```typescript
+const wallet = await sdk.wallet.loadWallet();
+// wallet: { publicKey: string }
+```
+
+**Response format:**
+
+```typescript
+interface WalletResponse {
+  publicKey: string; // Base58 encoded Solana public key
+}
+```
+
+**Example:**
+
+```typescript
+const wallet = await sdk.wallet.loadWallet();
+console.log(`Public key: ${wallet.publicKey}`);
+```
+
+### `getBalances(): Promise<BalanceResponse>`
+
+Get the SOL and USDC balances for the user's wallet.
+
+```typescript
+const balances = await sdk.wallet.getBalances();
+// balances: { sol: number, usdc: number, publicKey: string }
+```
+
+**Response format:**
+
+```typescript
+interface BalanceResponse {
+  sol: number; // SOL balance
+  usdc: number; // USDC balance (6 decimals)
+  publicKey: string; // Wallet public key
+}
+```
+
+**Example:**
+
+```typescript
+const balances = await sdk.wallet.getBalances();
+console.log(`SOL: ${balances.sol}`);
+console.log(`USDC: ${balances.usdc}`);
+```
+
+### `signMessage(message: string): Promise<Uint8Array | string>`
+
+Sign a message using the configured signer.
+
+```typescript
+const signature = await sdk.wallet.signMessage('Hello, world!');
+```
+
+**Parameters:**
+
+- `message: string` - The message to sign
+
+**Returns:**
+
+- `Promise<Uint8Array | string>` - The signature
+
+**Note:** A signer must be configured first using `setSigner()`.
+
+### `signTransaction(transaction: Transaction): Promise<Transaction>`
+
+Sign a Solana transaction using the configured signer.
+
+```typescript
+import { Transaction } from '@solana/web3.js';
+
+const unsignedTransaction = Transaction.from(/* ... */);
+const signedTransaction = await sdk.wallet.signTransaction(unsignedTransaction);
+```
+
+**Parameters:**
+
+- `transaction: Transaction` - The unsigned Solana transaction to sign
+
+**Returns:**
+
+- `Promise<Transaction>` - The signed transaction
+
+**Example:**
+
+```typescript
+// Transaction should be prepared by the backend first
+const { unsignedTransaction } = await sdk.http.post(
+  '/transactions/prepare-deposit',
+  {
+    lobbyId: 'lobby-id',
+    amount: 100,
+  },
+);
+
+const tx = Transaction.from(Buffer.from(unsignedTransaction, 'base64'));
+const signedTx = await sdk.wallet.signTransaction(tx);
+```
+
+**Note:** A signer must be configured first using `setSigner()`.
+
+### `send(recipient, amount, token?)`
+
+One-call transfer flow. This method prepares, signs (with configured signer), and submits the transaction internally.
+
+```typescript
+const result = await sdk.wallet.send('alice.sol', 1_000_000, 'USDC');
+// result: { signature, status, recipientAddress, fee, totalAmount, token }
+```
+
+- `recipient`: DIM username, `.sol` domain, or Solana address
+- `amount`: minor units (USDC) or lamports (SOL)
+- `token`: `'USDC' | 'SOL'` (default `'USDC'`)
+
+**Note:** `setSigner(...)` must be configured before calling `send(...)`.
+
+### Transfer recipient formats
+
+Wallet send (`sdk.wallet.send(...)`) accepts:
+
+- DIM username (e.g. `alice`)
+- Solana address (base58)
+- `.sol` domain (e.g. `alice.sol`)
+
+For `.sol` recipients, the API resolves the SNS domain to its current owner address during the prepare step and returns the resolved `recipientAddress` in the response.
+
+### `getAdminActivity(params?): Promise<AdminWalletActivityResponse>` (Admin only)
+
+Get paginated wallet activity across all users. Admin only. Optional filters: by kind (DEPOSIT, REFUND, PAYOUT, TRANSFER), by userId; sort by date (asc/desc).
+
+```typescript
+const result = await sdk.wallet.getAdminActivity({
+  limit: 20,
+  cursor: 'optional-cursor-from-previous-page',
+  kinds: ['DEPOSIT', 'TRANSFER'],
+  userId: 'user-id',
+  sortOrder: 'desc',
+});
+// result: { items: AdminWalletActivityItem[], nextCursor?: string }
+```
+
+**Parameters:**
+
+- `params.limit?` - Page size (default 20, max 100)
+- `params.cursor?` - Opaque cursor for next page
+- `params.kinds?` - Filter by activity kinds (array)
+- `params.userId?` - Filter to transactions involving this user (from or to)
+- `params.sortOrder?` - `'asc'` or `'desc'` (default newest first)
+
+**Response:** `AdminWalletActivityResponse` with `items` (each item includes `fromUserId`, `toUserId`, `fromUsername`, `toUsername`, plus standard activity fields) and optional `nextCursor`.
+
+---
+
+## Tips Module (`sdk.tips`)
+
+### `send(recipientUsername, amount)`
+
+One-call tip flow: prepares tip transaction, signs + submits transfer via configured wallet signer, then broadcasts the tip to global chat.
+
+```typescript
+const tip = await sdk.tips.send('bob', 1_000_000); // $1.00
+// tip: { signature, status, recipientAddress, recipientUserId, recipientUsername, amount, fee, totalAmount, message }
+```
+
+### Low-level methods (optional)
+
+- `prepare({ recipientUsername, amount })`
+- `broadcast({ recipientUserId, amount })`
+
+Use these only when you explicitly need manual control of signing/submission.
+
+## Escrow Module (`sdk.escrow`)
+
+The escrow module provides functionality for managing deposits, checking deposit status, and handling the escrow flow for game lobbies. This module works in conjunction with the wallet module to enable secure, blockchain-based deposits.
+
+### `startDeposits(lobbyId: string): Promise<void>`
+
+Start the deposit flow for a lobby. This transitions the lobby from `waiting` to `preparing` state and initializes deposit tracking for all players.
+
+```typescript
+await sdk.escrow.startDeposits('lobby-id');
+```
+
+**Requirements:**
+
+- User must be a member of the lobby
+- Lobby must be in `waiting` state
+- Lobby must have a `betAmount` configured
+- Lobby must be full (all players joined)
+
+**Behavior:**
+
+- Transitions lobby status to `preparing`
+- Initializes deposit status tracking for all players
+- Emits WebSocket event `lobby:updated`
+
+**Example:**
+
+```typescript
+// Start deposits when lobby is ready
+await sdk.escrow.startDeposits(lobbyId);
+console.log('Deposit flow started');
+```
+
+### `prepareDepositTransaction(lobbyId: string): Promise<PrepareDepositResponse>`
+
+Prepare an unsigned deposit transaction for the current user. The transaction must be signed by the user's wallet before submission.
+
+```typescript
+const response = await sdk.escrow.prepareDepositTransaction('lobby-id');
+// response: { transaction: string, message: string }
+```
+
+**Response format:**
+
+```typescript
+interface PrepareDepositResponse {
+  transaction: string; // Base64-encoded unsigned Solana transaction
+  message: string; // Human-readable message about the transaction
+}
+```
+
+**Example:**
+
+```typescript
+// Prepare the deposit transaction
+const { transaction, message } =
+  await sdk.escrow.prepareDepositTransaction(lobbyId);
+
+// Decode and sign the transaction
+const binaryString = atob(transaction);
+const bytes = new Uint8Array(binaryString.length);
+for (let i = 0; i < binaryString.length; i++) {
+  bytes[i] = binaryString.charCodeAt(i);
+}
+const unsignedTx = Transaction.from(bytes);
+const signedTx = await sdk.wallet.signTransaction(unsignedTx);
+```
+
+**Note:** The transaction amount is automatically set to match the lobby's `betAmount`. The transaction is partially signed by the fee payer (server) and requires the user's signature.
+
+### `submitDepositAndJoinQueue(lobbyId: string, signedTransaction: string, lobbies: Lobbies): Promise<Lobby>`
+
+Submit a signed deposit transaction and automatically join the queue when the deposit is confirmed. This is a convenience method that combines deposit submission, confirmation waiting, and queue joining.
+
+```typescript
+const finalLobby = await sdk.escrow.submitDepositAndJoinQueue(
+  lobbyId,
+  signedTxBase64,
+  sdk.lobbies,
+);
+```
+
+**Parameters:**
+
+- `lobbyId: string` - The lobby ID
+- `signedTransaction: string` - The signed transaction (base64 encoded)
+- `lobbies: Lobbies` - The lobbies service instance (from `sdk.lobbies`)
+
+**Returns:**
+
+- `Promise<Lobby>` - The lobby with updated status (will be 'queued' or 'active' if full)
+
+**Behavior:**
+
+1. Submits the signed deposit transaction to the Solana network
+2. Polls deposit status until all deposits are confirmed (max 30 seconds)
+3. Automatically joins the matchmaking queue when deposits are confirmed
+4. Returns the updated lobby
+
+**Example:**
+
+```typescript
+// After signing the transaction from playAgain()
+const signedTxBase64 = signedTx.serialize().toString('base64');
+const finalLobby = await sdk.escrow.submitDepositAndJoinQueue(
+  lobby.id,
+  signedTxBase64,
+  sdk.lobbies,
+);
+
+// Lobby is now in queue or active if full
+console.log(`Lobby status: ${finalLobby.status}`);
+```
+
+**Error Handling:**
+
+- Throws an error if deposit confirmation times out (30 seconds)
+- Throws an error if deposit submission fails
+- Throws an error if queue joining fails
+
+**Note:** This method is typically used after `playAgain()` to complete the "Play Again" flow in one call.
+
+### `submitDeposit(lobbyId: string, signedTransaction: string): Promise<SubmitDepositResponse>`
+
+Submit a signed deposit transaction to the Solana network. The transaction will be confirmed before the method returns.
+
+```typescript
+const signedTxBase64 = signedTx.serialize().toString('base64');
+const response = await sdk.escrow.submitDeposit(lobbyId, signedTxBase64);
+// response: { signature: string, status: string }
+```
+
+**Response format:**
+
+```typescript
+interface SubmitDepositResponse {
+  signature: string; // Solana transaction signature
+  status: string; // Transaction status ('confirmed' on success)
+}
+```
+
+**Example:**
+
+```typescript
+// Sign the transaction
+const signedTx = await sdk.wallet.signTransaction(unsignedTx);
+
+// Serialize and submit
+const signedTxBase64 = signedTx.serialize().toString('base64');
+const { signature, status } = await sdk.escrow.submitDeposit(
+  lobbyId,
+  signedTxBase64,
+);
+
+console.log(`Deposit confirmed: ${signature}`);
+```
+
+**Behavior:**
+
+- Submits transaction to Solana network
+- Waits for transaction confirmation
+- Updates deposit status to `confirmed` on success
+- Automatically transitions lobby to `queued` when all deposits are confirmed
+- Marks deposit as `failed` on error
+
+### `getDepositStatus(lobbyId: string): Promise<DepositStatusResponse>`
+
+Get the deposit status for all players in a lobby.
+
+```typescript
+const status = await sdk.escrow.getDepositStatus('lobby-id');
+// status: DepositStatusResponse
+```
+
+**Response format:**
+
+```typescript
+interface DepositStatusResponse {
+  deposits: Array<{
+    userId: string;
+    status: 'pending' | 'signed' | 'confirmed' | 'failed';
+    transactionHash?: string;
+    signedAt?: string;
+    confirmedAt?: string;
+    errorMessage?: string;
+  }>;
+  allConfirmed: boolean; // True if all deposits are confirmed
+  canProceedToQueue: boolean; // True if lobby can proceed to queue
+}
+```
+
+**Example:**
+
+```typescript
+const status = await sdk.escrow.getDepositStatus(lobbyId);
+
+// Check if all deposits are confirmed
+if (status.allConfirmed) {
+  console.log('All deposits confirmed!');
+}
+
+// Check individual player status
+status.deposits.forEach((deposit) => {
+  console.log(`Player ${deposit.userId}: ${deposit.status}`);
+  if (deposit.transactionHash) {
+    console.log(`  Transaction: ${deposit.transactionHash}`);
+  }
+});
+```
+
+**Deposit Status Values:**
+
+- `pending` - Deposit not yet prepared or signed
+- `signed` - Transaction signed but not yet confirmed on-chain
+- `confirmed` - Transaction confirmed on Solana network
+- `failed` - Transaction failed or timed out
+
+### Complete Deposit Flow Example
+
+```typescript
+import { SDK, BrowserLocalStorage } from '@dimcool/sdk';
+import { Transaction } from '@solana/web3.js';
+
+const sdk = new SDK({
+  appId: 'dim',
+  baseUrl: 'https://api.example.com',
+  storage: new BrowserLocalStorage(),
+});
+
+// 1. Authenticate
+await sdk.auth.login('user@example.com', 'password');
+
+// 2. Load wallet
+await sdk.wallet.loadWallet();
+
+// 3. Start deposit flow (lobby creator only)
+await sdk.escrow.startDeposits(lobbyId);
+
+// 4. Prepare deposit transaction
+const { transaction } = await sdk.escrow.prepareDepositTransaction(lobbyId);
+
+// 5. Decode and sign transaction
+const binaryString = atob(transaction);
+const bytes = new Uint8Array(binaryString.length);
+for (let i = 0; i < binaryString.length; i++) {
+  bytes[i] = binaryString.charCodeAt(i);
+}
+const unsignedTx = Transaction.from(bytes);
+const signedTx = await sdk.wallet.signTransaction(unsignedTx);
+
+// 6. Submit signed transaction
+const signedTxBase64 = signedTx.serialize().toString('base64');
+const { signature } = await sdk.escrow.submitDeposit(lobbyId, signedTxBase64);
+
+console.log(`Deposit confirmed: ${signature}`);
+
+// 7. Check status (optional, for polling)
+const status = await sdk.escrow.getDepositStatus(lobbyId);
+if (status.allConfirmed) {
+  console.log('All players have confirmed deposits!');
+}
+```
+
+**Notes:**
+
+- Deposits are automatically refunded if the deposit flow times out (5 minutes)
+- If any deposit fails, confirmed deposits are automatically refunded
+- The lobby automatically transitions to `queued` when all deposits are confirmed
+- Transaction hashes are stored in `GameHistory` for permanent records
+
+---
+
+## Feature Flags (`sdk.featureFlags`)
+
+### `getFeatureFlags(): Promise<FeatureFlag[]>`
+
+Get all feature flags. Flags are cached locally after the first call.
+
+```typescript
+const flags = await sdk.featureFlags.getFeatureFlags();
+// flags: [{ id: string, name: string, enabled: boolean, createdAt: string, updatedAt: string }]
+```
+
+### `isEnabledFlag(name: string): boolean`
+
+Check if a feature flag is enabled. Returns `false` if the flag doesn't exist or hasn't been loaded yet.
+
+```typescript
+if (sdk.featureFlags.isEnabledFlag('enable-rock-paper-scissors')) {
+  // Feature is enabled
+}
+```
+
+### `isLoaded(): boolean`
+
+Check if feature flags have been loaded.
+
+```typescript
+if (sdk.featureFlags.isLoaded()) {
+  // Flags are available
+}
+```
+
+### `updateFeatureFlag(name: string, enabled: boolean): Promise<FeatureFlag>`
+
+Update a feature flag. Admin only.
+
+```typescript
+const updatedFlag = await sdk.featureFlags.updateFeatureFlag('my-flag', true);
+```
+
+### `createFeatureFlag(name: string, enabled: boolean): Promise<FeatureFlag>`
+
+Create a new feature flag. Admin only.
+
+```typescript
+const newFlag = await sdk.featureFlags.createFeatureFlag('new-feature', false);
+```
+
+---
+
+## Lobbies (`sdk.lobbies`)
+
+### `createLobby(gameType: string): Promise<Lobby>`
+
+Create a new game lobby.
+
+```typescript
+const lobby = await sdk.lobbies.createLobby('rock-paper-scissors');
+// lobby: { id, gameType, status, creatorId, maxPlayers, players: [...], ... }
+```
+
+### `getLobby(lobbyId: string): Promise<Lobby>`
+
+Get lobby details. Only accessible to lobby members. The returned `Lobby` includes `players[].usdcBalance` (optional, USDC in minor units, cached) for displaying balances and gating Start Game when a player has insufficient funds.
+
+```typescript
+const lobby = await sdk.lobbies.getLobby('lobby-id');
+```
+
+### `inviteFriend(lobbyId: string, friendId: string): Promise<{ message: string }>`
+
+Invite a friend to a lobby. Creator only.
+
+```typescript
+await sdk.lobbies.inviteFriend('lobby-id', 'friend-user-id');
+```
+
+### `joinLobby(lobbyId: string): Promise<Lobby>`
+
+Join a lobby without requiring an invitation. Any authenticated user can join a lobby if:
+
+- The lobby is in `waiting` status
+- The lobby is not full
+- The user is not already in the lobby
+
+```typescript
+const lobby = await sdk.lobbies.joinLobby('lobby-id');
+```
+
+**Behavior:**
+
+- Adds the user to the lobby
+- Emits `lobby:player:joined` WebSocket event
+- Returns updated lobby with the new player
+
+**Note:** This is different from `acceptInvite()` which is used when accepting a friend invitation. `joinLobby()` allows direct joining via shared lobby URLs.
+
+### `acceptInvite(lobbyId: string): Promise<Lobby>`
+
+Accept a lobby invitation.
+
+```typescript
+const lobby = await sdk.lobbies.acceptInvite('lobby-id');
+```
+
+### `getLobby(lobbyId: string): Promise<Lobby>`
+
+Get lobby details. Any authenticated user can view lobby details, even if not a member. This allows users to see lobby info before deciding to join.
+
+The returned `Lobby` includes `players[].usdcBalance` (optional, number, USDC in minor units, cached) so the app can display each player's balance and gate "Start Game" when a player has insufficient funds.
+
+```typescript
+const lobby = await sdk.lobbies.getLobby('lobby-id');
+```
+
+### `removePlayer(lobbyId: string, userId: string): Promise<{ message: string }>`
+
+Remove a player from a lobby. Can be used by the player to leave or by the creator to kick.
+
+```typescript
+await sdk.lobbies.removePlayer('lobby-id', 'user-id');
+```
+
+### `kickPlayer(lobbyId: string, userId: string): Promise<{ message: string }>`
+
+Kick a player from a lobby. Creator only. The creator can kick any player except themselves.
+
+```typescript
+await sdk.lobbies.kickPlayer('lobby-id', 'user-id');
+```
+
+**Behavior:**
+
+- Removes the player from the lobby
+- Emits `lobby:player:left` WebSocket event
+- If the lobby was in queue, the queue is automatically cancelled
+- Kicked users can rejoin the lobby using `joinLobby()`
+
+### `leaveLobby(lobbyId: string): Promise<{ message: string }>`
+
+Leave a lobby. Alias for removing yourself. If the lobby is in queue, it will be automatically cancelled.
+
+```typescript
+await sdk.lobbies.leaveLobby('lobby-id');
+```
+
+### Queue Management
+
+#### `joinQueue(lobbyId: string): Promise<Lobby>`
+
+Join the matchmaking queue for a lobby, or start the game immediately if the lobby is full. The lobby must be in `waiting` state.
+
+```typescript
+const lobby = await sdk.lobbies.joinQueue('lobby-id');
+// If full: lobby.status will be 'active'
+// If not full: lobby.status will be 'queued'
+```
+
+**Requirements:**
+
+- Lobby must be in `waiting` state
+- User must be a member of the lobby
+  **WebSocket connection is required** - User must be connected via the realtime transport
+  - If not connected, the call will fail with a `BadRequestException`
+  - Preferred: `await sdk.ensureWebSocketConnected()` or `sdk.wsTransport.connect()`
+  - Join the lobby room: `socket.emit('join-lobby', lobbyId)`
+
+**Note on Lobby Creation vs Queue:**
+
+- Lobbies can be created via HTTP (no WebSocket required) - useful for programmatic/admin creation
+- However, to join the matchmaking queue, a WebSocket connection to the root namespace is required
+- This ensures only connected users can enter matchmaking, preventing orphaned queue entries
+
+**Behavior:**
+
+- **If lobby is full** (`players.length === maxPlayers`):
+  - Game starts immediately
+  - Lobby status changes to `active`
+  - `gameId` is created and assigned
+  - WebSocket event `lobby:matched` is emitted (with single lobby in `matchedLobbies`)
+  - Returns lobby with `status: 'active'`
+
+- **If lobby is not full**:
+  - Lobby status changes to `queued`
+  - Lobby is added to Redis queue for matching
+  - WebSocket event `lobby:queue:joined` is emitted
+  - System attempts to find a match immediately
+  - Returns lobby with `status: 'queued'`
+
+**Note**: The same endpoint works for both scenarios. The system automatically determines whether to start the game immediately or join the queue based on lobby capacity. The lobby creator clicks "Start Game" and the system handles the rest.
+
+#### `cancelQueue(lobbyId: string): Promise<Lobby>`
+
+Cancel the queue for a lobby. The lobby must be in `queued` state.
+
+```typescript
+const lobby = await sdk.lobbies.cancelQueue('lobby-id');
+// lobby.status will be 'waiting'
+```
+
+**Requirements:**
+
+- Lobby must be in `queued` state
+- User must be a member of the lobby
+
+**Behavior:**
+
+- Lobby is removed from Redis queue
+- Lobby status changes back to `waiting`
+- WebSocket event `lobby:queue:cancelled` is emitted
+
+**Note:** The queue is automatically cancelled if any player leaves the lobby while it's in queue.
+
+#### `playAgain(gameType: string, betAmount: number, escrow: Escrow): Promise<{ lobby: Lobby; unsignedTransaction: string }>`
+
+Create a new lobby, start deposits, and prepare a deposit transaction for playing again with the same bet amount. This is a convenience method that combines lobby creation, deposit initialization, and transaction preparation.
+
+```typescript
+const { lobby, unsignedTransaction } = await sdk.lobbies.playAgain(
+  'rock-paper-scissors',
+  25,
+  sdk.escrow,
+);
+```
+
+**Parameters:**
+
+- `gameType: string` - The game type to play again (e.g., 'rock-paper-scissors')
+- `betAmount: number` - The bet amount (same as previous game)
+- `escrow: Escrow` - The escrow service instance (from `sdk.escrow`)
+
+**Returns:**
+
+- `Promise<{ lobby: Lobby; unsignedTransaction: string }>` - The created lobby and unsigned transaction (base64 encoded) that needs to be signed
+
+**Behavior:**
+
+1. Creates a new lobby with the specified game type and bet amount
+2. Starts the deposit flow (transitions lobby to 'preparing' state)
+3. Prepares the deposit transaction
+4. Returns the lobby and unsigned transaction
+
+**Example:**
+
+```typescript
+// Play again with same bet amount
+const { lobby, unsignedTransaction } = await sdk.lobbies.playAgain(
+  'rock-paper-scissors',
+  25,
+  sdk.escrow,
+);
+
+// Decode and sign the transaction
+const binaryString = atob(unsignedTransaction);
+const bytes = new Uint8Array(binaryString.length);
+for (let i = 0; i < binaryString.length; i++) {
+  bytes[i] = binaryString.charCodeAt(i);
+}
+const unsignedTx = Transaction.from(bytes);
+const signedTx = await sdk.wallet.signTransaction(unsignedTx);
+
+// Submit deposit and join queue
+const signedTxBase64 = signedTx.serialize().toString('base64');
+const finalLobby = await sdk.escrow.submitDepositAndJoinQueue(
+  lobby.id,
+  signedTxBase64,
+  sdk.lobbies,
+);
+```
+
+**Note:** After signing the transaction, use `submitDepositAndJoinQueue()` to complete the flow and automatically join the matchmaking queue.
+
+### Admin Methods
+
+#### `getActiveLobbies(): Promise<Lobby[]>` (Admin Only)
+
+Get all active lobbies. Admin only.
+
+```typescript
+const activeLobbies = await sdk.lobbies.getActiveLobbies();
+```
+
+#### `getQueueStats(): Promise<QueueStats>` (Admin Only)
+
+Get queue statistics for the admin dashboard. Admin only.
+
+```typescript
+const stats = await sdk.lobbies.getQueueStats();
+// stats: {
+//   totalPlayersInQueue: number,
+//   queueSizes: Record<string, number>, // Key: 'queue:gameType:requiredPlayers', Value: count
+//   totalQueuedLobbies: number
+// }
+```
+
+---
+
+## Chat (`sdk.chat`)
+
+The chat system is a unified, generic chat service that supports multiple contexts: lobbies, games, and direct messages (DMs). All chat operations use the generic chat endpoints.
+
+### Context Types
+
+- `lobby` - Chat within a lobby
+- `game` - Chat within a game
+- `dm` - Direct message between two users (contextId is the other user's ID)
+- `global` - App-wide chat; single room for all authenticated users (contextId is `global`)
+
+### Global chat
+
+Global chat uses the same API with context `{ type: 'global', id: 'global' }`.
+
+- **Subscribe:** Call `chatStore.joinContext({ type: 'global', id: 'global' })` (or use a hook that does this on mount). Room name: `chat:global:global`.
+- **Unsubscribe:** Call the function returned from `joinContext`, or unmount the component that subscribes.
+- **Load snapshot:** `getChatHistory` / `getChatHistoryPaginated({ type: 'global', id: 'global' }, limit)` returns the last N messages; `getChatHistoryPaginated` returns `{ messages, nextCursor: null }` (no cursor pagination for global).
+- **Send:** `sendMessage({ type: 'global', id: 'global' }, message, replyTo?, gifUrl?, clientMessageId?)`. If the message starts with `/`, the server may interpret it as a command (e.g. `/help`, `/challenge`, `/tip`). See API docs for command syntax.
+- **Reactions:** Same as other contexts — `addReaction` / `removeReaction` with context `{ type: 'global', id: 'global' }` and `messageId`.
+- **Global-only methods:** `acceptGlobalChallenge(challengeId)` to accept a challenge from chat; `broadcastGlobalTip(recipientUserId, amount)` to broadcast a tip message after the user has signed and submitted the transfer.
+
+### `sendMessage(context: ChatContext, message: string, replyTo?: ChatMessageReply, gifUrl?: string): Promise<ChatMessage>`
+
+Send a chat message to any context.
+
+```typescript
+// Send to lobby
+const message = await sdk.chat.sendMessage(
+  { type: 'lobby', id: 'lobby-id' },
+  'Hello, everyone!',
+);
+
+// Send with reply
+const reply = await sdk.chat.sendMessage(
+  { type: 'lobby', id: 'lobby-id' },
+  'This is a reply',
+  {
+    id: originalMessage.id,
+    userId: originalMessage.userId,
+    username: originalMessage.username,
+    message: originalMessage.message,
+  },
+);
+
+// Send with GIF
+const gifMessage = await sdk.chat.sendMessage(
+  { type: 'lobby', id: 'lobby-id' },
+  '',
+  undefined,
+  'https://media.giphy.com/test.gif',
+);
+```
+
+**Parameters:**
+
+- `context` - Chat context (`{ type: 'lobby' | 'game' | 'dm' | 'global', id: string }`)
+- `message` - Message text (1-500 characters, or empty if gifUrl provided)
+- `replyTo` - Optional. Reference to the message being replied to
+- `gifUrl` - Optional. Giphy GIF URL
+
+**Returns:** `ChatMessage` object
+
+### `getChatHistory(context: ChatContext, limit?: number): Promise<ChatMessage[]>`
+
+Get chat history for any context.
+
+```typescript
+// Get lobby chat history
+const history = await sdk.chat.getChatHistory(
+  { type: 'lobby', id: 'lobby-id' },
+  50,
+);
+
+// Get game chat history
+const gameHistory = await sdk.chat.getChatHistory(
+  { type: 'game', id: 'game-id' },
+  100,
+);
+```
+
+**Parameters:**
+
+- `context` - Chat context
+- `limit` - Optional. Maximum number of messages (default: 50)
+
+**Returns:** Array of `ChatMessage` objects in chronological order (oldest first)
+
+### `addReaction(context: ChatContext, messageId: string, emoji: string): Promise<ChatMessage>`
+
+Add a reaction to a message.
+
+```typescript
+const updated = await sdk.chat.addReaction(
+  { type: 'lobby', id: 'lobby-id' },
+  'message-id',
+  '👍',
+);
+```
+
+**Returns:** Updated `ChatMessage` object with the new reaction
+
+### `removeReaction(context: ChatContext, messageId: string, emoji: string): Promise<ChatMessage>`
+
+Remove a reaction from a message.
+
+```typescript
+const updated = await sdk.chat.removeReaction(
+  { type: 'lobby', id: 'lobby-id' },
+  'message-id',
+  '👍',
+);
+```
+
+**Returns:** Updated `ChatMessage` object with the reaction removed
+
+### `markAsRead(context: ChatContext, messageId: string): Promise<ChatMessage>`
+
+Mark a message as read.
+
+```typescript
+const updated = await sdk.chat.markAsRead(
+  { type: 'lobby', id: 'lobby-id' },
+  'message-id',
+);
+```
+
+**Returns:** Updated `ChatMessage` object with read receipt
+
+---
+
+## Notifications (`sdk.notifications`)
+
+The notifications module provides methods for listing and managing the current user's app notifications (friend requests, game invites, achievements, etc.), plus admin-only broadcast/send.
+
+### `list(params?: { page?, limit? }): Promise<PaginatedNotificationsResponse>`
+
+List notifications for the current user (paginated).
+
+```typescript
+const res = await sdk.notifications.list({ page: 1, limit: 20 });
+// res.notifications, res.total, res.page, res.limit, res.unreadCount
+```
+
+### `markAsRead(id: string): Promise<AppNotification>`
+
+Mark a single notification as read.
+
+### `markAllAsRead(): Promise<void>`
+
+Mark all notifications as read.
+
+### `dismiss(id: string): Promise<void>`
+
+Dismiss (delete) a notification.
+
+### `broadcastNotification(message: string): Promise<void>`
+
+Broadcast a notification to all connected users (admin only).
+
+```typescript
+await sdk.notifications.broadcastNotification(
+  'Server maintenance in 10 minutes',
+);
+```
+
+**Parameters:**
+
+- `message` - Notification message (1-500 characters)
+
+**Note:** This endpoint requires admin authentication. The notification will be sent to all users currently connected to the application via the root WebSocket namespace.
+
+### `sendToUser(userId: string, message: string): Promise<void>`
+
+Send a notification to a specific user (admin only).
+
+```typescript
+await sdk.notifications.sendToUser('user-id', 'You have a new game invite!');
+```
+
+**Parameters:**
+
+- `userId` - Target user ID
+- `message` - Notification message (1-500 characters)
+
+**Note:** This endpoint requires admin authentication. The notification will be sent to the specified user if they are currently connected.
+
+### WebSocket Notifications Channel
+
+Subscribe via the event bus to receive real-time notification events:
+
+```typescript
+sdk.wsTransport.connect();
+
+// Listen for notification events
+sdk.events.subscribe('notification', (event) => {
+  console.log('Notification received:', event);
+  // event: { title: string, body?: string, icon?: string, tag?: string, data?: any }
+});
+```
+
+**Notification Event Structure:** When the server sends an app notification (e.g. friend request, game invite, achievement), the payload may include the full list-item shape so the client can render the panel without an extra fetch:
+
+```typescript
+// Generic toast shape
+interface NotificationEvent {
+  title: string;
+  body?: string;
+  icon?: string;
+  tag?: string;
+  data?: any;
+  timestamp?: string;
+}
+// App notification payload (when present) also includes:
+// id: string, type: AppNotificationType, message: string, read: boolean,
+// createdAt: string, actionPayload?: object, fromUserId?, fromUsername?, avatar?
+```
+
+**Note:** The notifications WebSocket channel requires authentication. Users must be authenticated to receive notifications. The client should check if notifications are enabled and browser permissions are granted before showing browser notifications. All WebSocket features (lobbies, games, chat, notifications) share a single connection to the root namespace for better performance.
+
+---
+
+## Achievements (`sdk.achievements`)
+
+Methods for listing achievement definitions and a user's unlocked achievements (e.g. for profile badges).
+
+### `list(): Promise<Achievement[]>`
+
+List all achievement definitions (code, name, description, category, icon).
+
+```typescript
+const all = await sdk.achievements.list();
+```
+
+### `getMyAchievements(): Promise<UserAchievement[]>`
+
+Get the current user's unlocked achievements (code, name, description, icon, unlockedAt). Requires authentication.
+
+### `getForUser(userId: string): Promise<UserAchievement[]>`
+
+Get unlocked achievements for a given user (e.g. for public profile).
+
+```typescript
+const badges = await sdk.achievements.getForUser('user-id');
+```
+
+---
+
+## Activity Feed (`sdk.activity`)
+
+### `getFeed(limit?: number): Promise<ActivityFeedResponse>`
+
+Fetch the global activity feed (new user signups, wins, lobbies created, and
+games starting). Results are cached server-side for 15 minutes.
+
+```typescript
+const feed = await sdk.activity.getFeed(15);
+feed.items.forEach((item) => {
+  console.log(item.type, item.user.username, item.game);
+});
+```
+
+---
+
+## Leaderboards (`sdk.leaderboards`)
+
+Fetch leaderboard data for global, per-game, or friends leaderboards with
+date-range filtering. Friends leaderboard requires authentication.
+
+### `getGlobalLeaderboard(query?: { startDate?: string; endDate?: string; limit?: number })`
+
+```typescript
+const global = await sdk.leaderboards.getGlobalLeaderboard({
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+  limit: 20,
+});
+```
+
+### `getGameLeaderboard(gameType: string, query?: { startDate?: string; endDate?: string; limit?: number })`
+
+```typescript
+const game = await sdk.leaderboards.getGameLeaderboard('rock-paper-scissors', {
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+});
+```
+
+### `getFriendsLeaderboard(query?: { startDate?: string; endDate?: string; limit?: number })`
+
+```typescript
+const friends = await sdk.leaderboards.getFriendsLeaderboard({
+  startDate: '2024-01-01',
+  endDate: '2024-01-31',
+});
+```
+
+**Leaderboard entry fields:** `gameEarnings`, `referralEarnings`, `earnings`, `wins`, `losses`, `winRate`
+
+---
+
+### ChatMessage Interface
+
+```typescript
+interface ChatMessage {
+  id: string;
+  lobbyId: string; // Empty string for game/DM contexts
+  userId?: string; // Optional for system messages
+  username?: string; // Optional for system messages
+  message: string;
+  type: 'user' | 'system';
+  systemType?: 'player_joined' | 'player_left' | 'bet_changed';
+  replyTo?: {
+    id: string;
+    userId?: string;
+    username?: string;
+    message: string;
+  };
+  reactions?: Array<{
+    emoji: string;
+    userId: string;
+    username?: string;
+    createdAt: string;
+  }>;
+  readBy?: Array<{
+    userId: string;
+    readAt: string;
+  }>;
+  metadata?: Record<string, any>; // e.g., { gifUrl: string } or { betAmount: number }
+  createdAt: string;
+}
+```
+
+### WebSocket Chat Events
+
+All WebSocket features use a single connection to the root namespace. The namespace parameter is kept for backward compatibility but is ignored - all events come from the same connection.
+
+Connect to the root namespace to receive real-time chat events (all features share a single connection):
+
+**Preferred:** use `sdk.chatStore` for updates. The following direct WebSocket examples are legacy.
+
+```typescript
+sdk.wsTransport.connect();
+
+// Listen for new messages
+sdk.events.subscribe('chat:message', (message: ChatMessage) => {
+  console.log('New message:', message);
+});
+
+// Listen for reaction updates
+sdk.events.subscribe('chat:reaction', (message: ChatMessage) => {
+  console.log('Reaction updated:', message);
+});
+
+// Listen for read receipts
+sdk.events.subscribe('chat:read', (data) => {
+  console.log('Message read:', data.messageId, 'by', data.userId);
+});
+
+// Listen for typing indicators
+sdk.events.subscribe('chat:typing', (data) => {
+  if (data.typing) {
+    console.log(`${data.username} is typing...`);
+  } else {
+    console.log(`${data.username} stopped typing`);
+  }
+});
+```
+
+**Events:**
+
+- `chat:message` - New message received (user or system)
+- `chat:reaction` - Reaction added or removed
+- `chat:read` - Message marked as read
+- `chat:typing` - User started/stopped typing
+
+### Examples
+
+```typescript
+// Send a message to a lobby
+const message = await sdk.chat.sendMessage(
+  { type: 'lobby', id: 'lobby-id' },
+  'Hello!',
+);
+
+// Reply to a message
+const reply = await sdk.chat.sendMessage(
+  { type: 'lobby', id: 'lobby-id' },
+  'This is a reply',
+  {
+    id: message.id,
+    userId: message.userId,
+    username: message.username,
+    message: message.message,
+  },
+);
+
+// Add a reaction
+await sdk.chat.addReaction({ type: 'lobby', id: 'lobby-id' }, message.id, '👍');
+
+// Get chat history
+const history = await sdk.chat.getChatHistory(
+  { type: 'lobby', id: 'lobby-id' },
+  50,
+);
+
+// Mark as read
+await sdk.chat.markAsRead({ type: 'lobby', id: 'lobby-id' }, message.id);
+```
+
+---
+
+## Referrals (`sdk.referrals`)
+
+DIM has a 3-level referral system that pays passive income in USDC. Commission rates: Level 1 = 30%, Level 2 = 3%, Level 3 = 2% of game fees.
+
+### `getSummary(): Promise<ReferralSummary>`
+
+Get your referral summary including code, link, totals per level, and earnings.
+
+```typescript
+const summary = await sdk.referrals.getSummary();
+// {
+//   code: 'my-username',
+//   link: 'https://dim.cool/?ref=my-username',
+//   totals: { level1: 15, level2: 3, level3: 1 },
+//   earnings: { pending: 500000, claimed: 2000000 }
+// }
+```
+
+### `getTree(params?): Promise<ReferralTreeResponse>`
+
+Get your referral tree at a specific level.
+
+```typescript
+const tree = await sdk.referrals.getTree({ level: 1, limit: 50 });
+// { level: 1, items: [{ id, username, createdAt }], nextCursor?: string }
+
+// Paginate
+const nextPage = await sdk.referrals.getTree({
+  level: 1,
+  limit: 50,
+  cursor: tree.nextCursor,
+});
+```
+
+**Parameters:**
+
+| Name     | Type          | Description                      |
+| -------- | ------------- | -------------------------------- |
+| `level`  | `1 \| 2 \| 3` | Referral level to view           |
+| `limit`  | `number`      | Max results (1-200, default: 50) |
+| `cursor` | `string`      | Pagination cursor                |
+
+### `getRewards(params?): Promise<ReferralRewardsResponse>`
+
+Get referral reward history with optional status filter.
+
+```typescript
+// Get pending rewards
+const rewards = await sdk.referrals.getRewards({ status: 'PENDING' });
+// { items: [{ id, referredUserId, referredUsername, level, amount, status, createdAt }], nextCursor? }
+
+// Get all rewards
+const all = await sdk.referrals.getRewards({ limit: 100 });
+```
+
+**Parameters:**
+
+| Name     | Type                                    | Description         |
+| -------- | --------------------------------------- | ------------------- |
+| `status` | `'PENDING' \| 'CLAIMED' \| 'CANCELLED'` | Filter by status    |
+| `limit`  | `number`                                | Max results (1-200) |
+| `cursor` | `string`                                | Pagination cursor   |
+
+### `claimRewards(): Promise<ClaimReferralRewardsResponse>`
+
+Claim all pending referral rewards. USDC is transferred from escrow to your wallet.
+
+```typescript
+const result = await sdk.referrals.claimRewards();
+// { claimedCount: 5, claimedAmount: 1500000, walletTransactionSignature: '5xY...' }
+console.log(`Claimed $${(result.claimedAmount / 1_000_000).toFixed(2)} USDC`);
+```
+
+---
+
+## Games (`sdk.games`)
+
+### `getAvailableGames(): Promise<GameType[]>`
+
+Get all available game types. Only returns game types that are enabled via feature flags.
+
+```typescript
+const games = await sdk.games.getAvailableGames();
+// games: [{ id: string, name: string, maxPlayers: number, minPlayers: number, description?: string }]
+```
+
+**Example:**
+
+```typescript
+const availableGames = await sdk.games.getAvailableGames();
+console.log('Available games:', availableGames);
+// Output: [{ id: 'rock-paper-scissors', name: 'Rock Paper Scissors', maxPlayers: 2, minPlayers: 2, ... }]
+
+// Use game type when creating a lobby
+if (availableGames.length > 0) {
+  const lobby = await sdk.lobbies.createLobby(availableGames[0].id);
+}
+```
+
+**Note:** Game types are feature-flagged. A game type will only appear in this list if its corresponding feature flag (e.g., `enable-rock-paper-scissors`) is enabled.
+
+### `getGame(gameId: string): Promise<Game>`
+
+Get game details by game ID. Returns game information including players, status, and associated lobbies.
+
+```typescript
+const game = await sdk.games.getGame('game-123');
+// game: { gameId: string, gameType: string, status: 'active' | 'completed' | 'abandoned', createdAt: string, players: GamePlayer[], lobbyIds: string[] }
+```
+
+**Example:**
+
+```typescript
+try {
+  const game = await sdk.games.getGame('game-123');
+  console.log('Game:', game.gameType, game.status);
+  console.log(
+    'Players:',
+    game.players.map((p) => p.username),
+  );
+  console.log('Lobbies:', game.lobbyIds);
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Game not found:', error.message);
+  }
+}
+```
+
+**GamePlayer interface:**
+
+```typescript
+interface GamePlayer {
+  userId: string;
+  username: string;
+  name: string;
+}
+```
+
+### `getLiveGames(): Promise<Game[]>`
+
+Get list of currently active (live) games for spectating. Public endpoint; no auth required.
+
+```typescript
+const liveGames = await sdk.games.getLiveGames();
+// liveGames: Game[] - same shape as getGame()
+```
+
+## Spectate (`sdk.spectate`)
+
+Spectate discovery — finding who to watch.
+
+### `sdk.spectate.getLivePlayers(options?): Promise<LivePlayersPage>`
+
+Get list of players currently in an active game, **paginated and sorted by newest**. Samples a limited number of games per page (default 10) so the API stays fast with many active games. Returns **one entry per unique player** in the sample (no duplicates). Use for "Live now" and "Who to watch" UI; link to `/spectate/:username` for each player.
+
+**Parameters (all optional):**
+
+| Option   | Type   | Description                                                                |
+| -------- | ------ | -------------------------------------------------------------------------- |
+| `limit`  | number | Number of games to sample per page (1–20, default 10).                     |
+| `cursor` | string | Opaque cursor from the previous response’s `nextCursor` for the next page. |
+
+**Returns:** `Promise<LivePlayersPage>` with `items: LivePlayer[]` and `nextCursor: string | null` (non-null when there are more games to page).
+
+```typescript
+const page = await sdk.spectate.getLivePlayers({ limit: 10 });
+// page: { items: LivePlayer[], nextCursor: string | null }
+// Next page: sdk.spectate.getLivePlayers({ limit: 10, cursor: page.nextCursor })
+```
+
+**LivePlayer and LivePlayersPage:**
+
+```typescript
+interface LivePlayer {
+  userId: string;
+  username: string;
+  avatar?: string;
+  gameId: string;
+  gameType: string;
+  spectatorCount: number; // unique users currently watching this player
+}
+
+interface LivePlayersPage {
+  items: LivePlayer[];
+  nextCursor: string | null;
+}
+```
+
+> **Note:** `spectatorCount` is the number of **unique users currently watching this player** (connected to the spectate channel for that user). It is not a per-game counter.
+
+### Spectate channel (WebSocket)
+
+When on the spectate page (e.g. `/spectate/:username`), the client should:
+
+1. **Join the game room** (for game events, chat, and pot): `gameStore.joinGame(gameId)`.
+2. **Join the spectate channel** (to be counted as a viewer of that user): `gameStore.joinSpectateChannel(spectatedUserId)`.
+
+Both use the same existing socket connection (no new connection). The spectate channel is reference-counted: calling `joinSpectateChannel` returns a leave function. Call it (or disconnect) to stop being counted. If you switch from spectating UserA to UserB, the server automatically leaves UserA's channel first.
+
+```typescript
+// On spectate page mount
+const leaveGame = sdk.gameStore.joinGame(gameId);
+const leaveSpectate = sdk.gameStore.joinSpectateChannel(spectatedUserId);
+
+// On spectate page unmount
+leaveSpectate();
+leaveGame();
+```
+
+#### Real-time spectator count
+
+The server emits `spectator:count:updated` events whenever a viewer joins or leaves. The SDK `gameStore` tracks these counts automatically:
+
+```typescript
+// Read from the store (snapshot)
+const count = sdk.gameStore.getSpectatorCount(userId);
+
+// Subscribe reactively (in React — see useSpectatorCount hook in react-sdk)
+const { count } = useSpectatorCount({
+  userId: spectatedUserId,
+  joinChannel: true,
+});
+```
+
+#### REST spectator count
+
+```typescript
+// Get the game-level spectator count (union of all players' viewers)
+const { count } = await sdk.games.getGameSpectatorCount(gameId);
+```
+
+- **Chat**: Spectators can send and receive messages in game chat. Join the chat room: `chat:join` with `{ type: 'game', id: gameId }`. Messages from non-players have `metadata.role = 'spectator'`.
+- **Pot (donations)**: Spectators can donate via `POST /games/:gameId/donate` (same as players). The amount is added to the spectator pot.
+
+### Spectator donations
+
+#### `prepareGameDonation(gameId: string, amountMinor: number): Promise<{ transaction, escrowAddress, amountMinor }>`
+
+Prepare a USDC transfer to the game pot (escrow). Returns an unsigned transaction for the client to sign. Minimum 10 cents (100,000 minor units). Call `donateToGame` with the signed transaction after signing.
+
+#### `donateToGame(gameId: string, amountMinor: number, signedTransaction: string): Promise<{ signature, status }>`
+
+Submit a signed game donation. The amount is added to the spectator pot; the winner receives player pot + spectator donations minus 1% fee. A system message is posted in game chat.
+
+### Game Action Methods
+
+#### `submitAction(gameId: string, action: ValidAction): Promise<void>`
+
+Submit a typed action for the current game. Only game players can submit actions.
+
+```typescript
+await sdk.games.submitAction('game-id', {
+  gameType: 'rock-paper-scissors',
+  action: 'play',
+  payload: { action: 'rock' },
+});
+```
+
+```typescript
+// Chess move
+await sdk.games.submitAction('game-id', {
+  gameType: 'chess',
+  action: 'move',
+  payload: { from: 'e2', to: 'e4' },
+});
+```
+
+**Requirements:**
+
+- User must be a player in the game
+- Game must be active
+- RPS: round must be in selection phase and not yet submitted
+- Other games: validation depends on the game engine
+
+**Behavior:**
+
+- Action is stored in game state
+- WebSocket event `game:rps:action:received` is emitted to all players
+- If both players act before timer expires, timer cuts short and reveal phase starts immediately
+- If timer expires before action, random action is chosen automatically
+
+**Example:**
+
+```typescript
+// Submit action during selection phase
+try {
+  await sdk.games.submitAction('game-id', {
+    gameType: 'rock-paper-scissors',
+    action: 'play',
+    payload: { action: 'paper' },
+  });
+  console.log('Action submitted successfully');
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Failed to submit action:', error.message);
+  }
+}
+```
+
+#### `getGameState(gameId: string): Promise<GameStateResponse>`
+
+Get current game state with timer information, round details, scores, and actions. Works for both **players and spectators** (same endpoint and response shape); only players can submit actions.
+
+```typescript
+const state = await sdk.games.getGameState('game-id');
+// state: GameStateResponse
+```
+
+**Returns:** Current game state including:
+
+- Round information (current round, max rounds, phase)
+- Timer information (time remaining in milliseconds)
+- Actions (your action visible, opponent's action hidden until reveal)
+- Scores (wins per player)
+- Winner ID (if game completed)
+
+**GameStateResponse interface:**
+
+```typescript
+type GameStateResponse =
+  | RpsGameState
+  | ChessGameState
+  | NimGameState
+  | DotsAndBoxesGameState
+  | TicTacToeGameState;
+```
+
+**Example:**
+
+```typescript
+const state = await sdk.games.getGameState('game-id');
+
+console.log(`Round ${state.currentRound} of ${state.maxRounds}`);
+console.log(`Phase: ${state.roundState.phase}`);
+console.log(
+  `Time remaining: ${Math.ceil(state.roundState.timeRemaining / 1000)}s`,
+);
+console.log(`Scores:`, state.scores);
+
+// Check if you can submit an action
+if (state.roundState.phase === 'selection') {
+  const myAction = state.roundState.actions[userId];
+  if (!myAction.submitted) {
+    // Submit action
+    await sdk.games.submitAction('game-id', {
+      gameType: 'rock-paper-scissors',
+      action: 'play',
+      payload: { action: 'rock' },
+    });
+  }
+}
+```
+
+### WebSocket Game Events
+
+**Preferred:** use `sdk.gameStore` / `sdk.gameActionsStore` for updates. Use the event bus for raw event streams.
+
+#### `game:move` (Chess)
+
+Emitted when a chess move is applied.
+
+```typescript
+sdk.events.subscribe('game:move', (data) => {
+  if (data.gameType === 'chess') {
+    console.log(`${data.playerId} moved ${data.move.san}`);
+  }
+});
+```
+
+#### `game:rps:round:started`
+
+Emitted when a new round begins.
+
+```typescript
+sdk.events.subscribe('game:rps:round:started', (data) => {
+  console.log(`Round ${data.roundNumber} started`);
+  console.log(`Selection ends at: ${data.selectionEndsAt}`);
+  console.log(`Time remaining: ${data.timeRemaining}ms`);
+});
+```
+
+#### `game:rps:action:received`
+
+Emitted when a player has submitted (choice is not revealed until `game:rps:round:reveal`). Payload: `gameId`, `roundNumber`, `playerId`, `submittedAt` (no `action`).
+
+```typescript
+sdk.events.subscribe('game:rps:action:received', (data) => {
+  console.log(`Player ${data.playerId} submitted`);
+});
+```
+
+#### `game:rps:timer:cutoff`
+
+Emitted when timer is cut short because both players acted early.
+
+```typescript
+sdk.events.subscribe('game:rps:timer:cutoff', (data) => {
+  console.log('Timer cut short, reveal phase starting');
+});
+```
+
+#### `game:rps:round:reveal`
+
+Emitted when reveal phase starts (both actions are known).
+
+```typescript
+sdk.events.subscribe('game:rps:round:reveal', (data) => {
+  console.log('Actions revealed:', data.actions);
+  // data.actions: { [userId]: 'rock' | 'paper' | 'scissors' }
+});
+```
+
+#### `game:rps:round:completed`
+
+Emitted when a round finishes.
+
+```typescript
+sdk.events.subscribe('game:rps:round:completed', (data) => {
+  console.log(`Round ${data.roundNumber} winner: ${data.winnerId || 'Tie'}`);
+  console.log('Scores:', data.scores);
+});
+```
+
+#### `game:rps:timeout`
+
+Emitted when timer expires and random action is chosen.
+
+```typescript
+sdk.events.subscribe('game:rps:timeout', (data) => {
+  console.log(
+    `Player ${data.playerId} timed out, random action: ${data.action}`,
+  );
+});
+```
+
+#### `game:completed`
+
+Emitted when the match finishes.
+
+```typescript
+sdk.events.subscribe('game:completed', (data) => {
+  if (data.isDraw) {
+    console.log('Game ended in a draw');
+  } else {
+    console.log(`Game winner: ${data.winnerId}`);
+  }
+  if (data.gameType === 'rock-paper-scissors') {
+    console.log(`Final scores:`, data.finalScores);
+    console.log(`Rounds:`, data.rounds);
+  }
+  console.log(`Won amount: $${data.wonAmount}`);
+});
+```
+
+---
+
+## Prediction Markets (`sdk.markets`)
+
+The markets module provides functionality for prediction market trading on games. Uses a Constant Product Market Maker (CPMM) for instant execution — no order matching needed. Users can buy and sell outcome shares, view positions with P&L, and redeem winnings after resolution. Admin methods provide aggregate analytics.
+
+### `getMarket(gameId: string): Promise<MarketState>`
+
+Get the prediction market state for a game. Returns prices, volume, collateral, and resolution status.
+
+```typescript
+const market = await sdk.markets.getMarket('game-id');
+console.log(market.prices); // { playerAId: 0.6, playerBId: 0.4 }
+console.log(market.totalVolume); // "5000000"
+console.log(market.status); // "OPEN" or "RESOLVED"
+```
+
+### `getMyPositions(gameId: string): Promise<MarketPosition[]>`
+
+Get the authenticated user's positions for a game. Returns shares held, average cost, current value, and unrealized P&L.
+
+```typescript
+const positions = await sdk.markets.getMyPositions('game-id');
+positions.forEach((pos) => {
+  console.log(`Outcome: ${pos.outcomeId}`);
+  console.log(`Shares: ${pos.shares}`);
+  console.log(`Current value: ${pos.currentValue}`);
+  console.log(`Unrealized P&L: ${pos.unrealizedPnl}`);
+});
+```
+
+### `prepareBuyOrder(gameId: string, outcomeId: string, amountMinor: number): Promise<{ transaction: string }>`
+
+Prepare a buy order deposit transaction (unsigned, for client signing).
+
+```typescript
+const { transaction } = await sdk.markets.prepareBuyOrder(
+  'game-id',
+  'player-a-id',
+  1_000_000,
+);
+// ... sign transaction with wallet ...
+```
+
+### `submitBuyOrder(gameId: string, signedTransaction: string, outcomeId: string, amountMinor: number): Promise<MarketBuyResult>`
+
+Submit a signed buy order and execute the trade. Shares are received instantly via the AMM pool.
+
+```typescript
+const result = await sdk.markets.submitBuyOrder(
+  'game-id',
+  signedTxBase64,
+  'player-a-id',
+  1_000_000,
+);
+console.log(
+  `Received ${result.sharesReceived} shares at ${result.costPerShare} per share`,
+);
+console.log('New prices:', result.newPrices);
+```
+
+**Parameters:**
+
+- `gameId: string` - The game ID
+- `signedTransaction: string` - Base64-encoded signed Solana transaction
+- `outcomeId: string` - The outcome to buy (typically a player ID)
+- `amountMinor: number` - Amount to spend in USDC minor units
+
+### `sellShares(gameId: string, outcomeId: string, shares: number): Promise<MarketSellResult>`
+
+Sell shares back to the AMM pool. Returns USDC based on current pool state.
+
+```typescript
+const result = await sdk.markets.sellShares('game-id', 'player-a-id', 500);
+console.log(
+  `Received ${result.amountReceived} USDC at ${result.pricePerShare} per share`,
+);
+console.log('New prices:', result.newPrices);
+```
+
+**Parameters:**
+
+- `gameId: string` - The game ID
+- `outcomeId: string` - The outcome to sell
+- `shares: number` - Number of shares to sell (in minor units)
+
+### `redeemShares(gameId: string): Promise<RedeemResult>`
+
+Redeem winning shares after a market is resolved. Returns payout, fee, net payout, and profit.
+
+```typescript
+const result = await sdk.markets.redeemShares('game-id');
+console.log(`Payout: ${result.payout}`);
+console.log(`Fee: ${result.fee}`);
+console.log(`Net payout: ${result.netPayout}`);
+console.log(`Profit: ${result.profit}`);
+```
+
+### Admin Methods
+
+#### `getAdminStats(): Promise<AdminMarketStats>`
+
+Get aggregate prediction market statistics. Admin only.
+
+```typescript
+const stats = await sdk.markets.getAdminStats();
+console.log(`Total markets: ${stats.totalMarkets}`);
+console.log(`Open: ${stats.openMarkets}, Resolved: ${stats.resolvedMarkets}`);
+console.log(`Total volume: ${stats.totalVolume}`);
+console.log(`Unique traders: ${stats.uniqueTraders}`);
+```
+
+#### `getAdminDailyStats(days?: number): Promise<AdminMarketDailyStats>`
+
+Get daily prediction market stats breakdown. Admin only. Defaults to 30 days.
+
+```typescript
+const daily = await sdk.markets.getAdminDailyStats(7);
+daily.days.forEach((day) => {
+  console.log(
+    `${day.date}: ${day.tradesExecuted} trades, volume ${day.volume}`,
+  );
+});
+```
+
+#### `getAdminMarkets(page?: number, limit?: number): Promise<{ markets: AdminMarketDetail[]; total: number }>`
+
+List all prediction markets with order and position counts. Admin only.
+
+```typescript
+const { markets, total } = await sdk.markets.getAdminMarkets(1, 20);
+console.log(`${total} total markets`);
+markets.forEach((m) => {
+  console.log(`${m.id}: ${m.status}, ${m.positionCount} positions`);
+});
+```
+
+### Prediction Market Types
+
+```typescript
+interface MarketState {
+  marketId: string;
+  gameId: string;
+  status: string;
+  outcomes: string[];
+  prices: Record<string, number>;
+  totalCollateral: string;
+  totalVolume: string;
+  totalFees: string;
+  resolvedOutcome: string | null;
+}
+
+interface MarketPosition {
+  outcomeId: string;
+  shares: string;
+  avgCostPerShare: string;
+  totalCost: string;
+  currentPrice: number;
+  currentValue: string;
+  unrealizedPnl: string;
+}
+
+interface MarketBuyResult {
+  tradeId: string;
+  sharesReceived: string;
+  costPerShare: string;
+  newPrices: Record<string, number>;
+}
+
+interface MarketSellResult {
+  tradeId: string;
+  amountReceived: string;
+  pricePerShare: string;
+  newPrices: Record<string, number>;
+}
+
+interface RedeemResult {
+  status: string;
+  payout: string;
+  fee: string;
+  netPayout: string;
+  profit: string;
+}
+
+interface AdminMarketStats {
+  totalMarkets: number;
+  openMarkets: number;
+  resolvedMarkets: number;
+  totalVolume: string;
+  totalFees: string;
+  uniqueTraders: number;
+}
+
+interface AdminMarketDailyStats {
+  days: AdminMarketDailyStatsItem[];
+}
+
+interface AdminMarketDailyStatsItem {
+  date: string;
+  marketsOpened: number;
+  marketsResolved: number;
+  tradesExecuted: number;
+  volume: string;
+  fees: string;
+}
+
+interface AdminMarketDetail {
+  id: string;
+  gameId: string;
+  status: string;
+  outcomes: string[];
+  resolvedOutcome: string | null;
+  totalCollateral: string;
+  totalVolume: string;
+  totalFees: string;
+  createdAt: string;
+  resolvedAt: string | null;
+  positionCount: number;
+}
+```
+
+### Complete Prediction Market Flow Example
+
+```typescript
+import { SDK, BrowserLocalStorage } from '@dimcool/sdk';
+
+const sdk = new SDK({
+  appId: 'dim',
+  baseUrl: 'https://api.example.com',
+  storage: new BrowserLocalStorage(),
+});
+
+// 1. Authenticate
+await sdk.auth.login('user@example.com', 'password');
+
+// 2. Get market state for a game
+const market = await sdk.markets.getMarket('game-id');
+console.log('Prices:', market.prices);
+console.log('Volume:', market.totalVolume);
+
+// 3. Buy shares of an outcome (two-step: prepare + sign + submit)
+const { transaction } = await sdk.markets.prepareBuyOrder(
+  'game-id',
+  'player-a-id',
+  1_000_000,
+);
+// ... sign transaction with wallet ...
+const buyResult = await sdk.markets.submitBuyOrder(
+  'game-id',
+  signedTxBase64,
+  'player-a-id',
+  1_000_000,
+);
+console.log(`Bought: ${buyResult.sharesReceived} shares`);
+
+// 4. Check positions
+const positions = await sdk.markets.getMyPositions('game-id');
+positions.forEach((pos) => {
+  console.log(
+    `${pos.outcomeId}: ${pos.shares} shares, P&L: ${pos.unrealizedPnl}`,
+  );
+});
+
+// 5. Sell shares back to the AMM pool
+const sellResult = await sdk.markets.sellShares('game-id', 'player-a-id', 250);
+console.log(`Received: ${sellResult.amountReceived} USDC`);
+
+// 6. After game resolves, redeem winning shares
+const redeem = await sdk.markets.redeemShares('game-id');
+console.log(`Net payout: ${redeem.netPayout}, Profit: ${redeem.profit}`);
+```
+
+---
+
+## Realtime Transport & Stores
+
+The SDK now exposes a transport abstraction and Zustand vanilla stores for real-time
+state. This is the preferred API for new integrations.
+
+### Transport (`sdk.wsTransport`)
+
+The transport owns the realtime connection. Use `SharedWorkerTransport` in browsers
+or `StandaloneWsTransport` in Node/unsupported environments.
+
+```typescript
+import { SharedWorkerTransport } from '@dimcool/sdk';
+
+const workerUrl = new URL('path/to/shared-worker.js', import.meta.url);
+const wsTransport = new SharedWorkerTransport(workerUrl.toString(), baseUrl);
+
+const sdk = new SDK({
+  appId: 'dim',
+  baseUrl,
+  storage,
+  wsTransport,
+});
+```
+
+### Stores
+
+- `sdk.lobbyStore`, `sdk.gameStore`, `sdk.gameActionsStore`
+- `sdk.chatStore`, `sdk.dmThreadsStore`, `sdk.notificationsStore`
+
+These stores are updated by the `WsRouter` and are the single source of truth for
+realtime UI. Room membership is ref-counted and mapped to backend join/leave emits.
+
+### Event Bus (low-level)
+
+If you need raw event streams, use `sdk.events.subscribe(eventName, handler)`.
+
+## Type Definitions
+
+The SDK exports TypeScript types for all API responses:
+
+```typescript
+import type {
+  User,
+  PublicUser,
+  PaginatedUsers,
+  PaginatedFriends,
+  PaginatedSearchUsers,
+  FeatureFlag,
+  LoginResponse,
+  GenerateHandshakeResponse,
+  UsernameAvailabilityResponse,
+  Lobby,
+  LobbyPlayer,
+  QueueStats,
+  GameType,
+  Game,
+  GamePlayer,
+  MarketState,
+  MarketPosition,
+  MarketOrderResult,
+  RedeemResult,
+  AdminMarketStats,
+  AdminMarketDailyStats,
+  AdminMarketDetail,
+  WebSocketEventMap,
+  ConnectionState,
+} from '@dimcool/sdk';
+```
+
+---
+
+## Error Handling
+
+The SDK throws errors for failed API requests. Always wrap SDK calls in try-catch blocks:
+
+```typescript
+try {
+  await sdk.auth.login('user@example.com', 'password');
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Login failed:', error.message);
+  }
+}
+```
+
+---
+
+## Examples
+
+### Complete Authentication Flow
+
+```typescript
+import { SDK, BrowserLocalStorage } from '@dimcool/sdk';
+
+const sdk = new SDK({
+  appId: 'dim',
+  baseUrl: 'https://api.example.com',
+  storage: new BrowserLocalStorage(),
+});
+
+// Login
+try {
+  const response = await sdk.auth.login('user@example.com', 'password');
+  console.log('Logged in as:', response.user.email);
+} catch (error) {
+  console.error('Login failed:', error);
+}
+
+// Check authentication
+if (sdk.auth.isAuthenticated()) {
+  // Fetch user data
+  const user = await sdk.users.getUserById(response.user.id);
+}
+
+// Logout
+sdk.auth.logout();
+```
+
+### Lobby Management
+
+```typescript
+// Create a lobby
+const lobby = await sdk.lobbies.createLobby('rock-paper-scissors');
+
+// Invite a friend
+await sdk.lobbies.inviteFriend(lobby.id, 'friend-user-id');
+
+// Get lobby status
+const updatedLobby = await sdk.lobbies.getLobby(lobby.id);
+
+// Leave lobby
+await sdk.lobbies.leaveLobby(lobby.id);
+```
+
+### Feature Flag Checking
+
+```typescript
+// Load feature flags
+await sdk.featureFlags.getFeatureFlags();
+
+// Check if feature is enabled
+if (sdk.featureFlags.isEnabledFlag('enable-rock-paper-scissors')) {
+  // Show game UI
+}
+```
+
+### Getting Available Games
+
+```typescript
+// Get available game types (filtered by feature flags)
+const games = await sdk.games.getAvailableGames();
+
+// Display games to user
+games.forEach((game) => {
+  console.log(`${game.name}: ${game.minPlayers}-${game.maxPlayers} players`);
+});
+
+// Create lobby with validated game type
+if (games.length > 0) {
+  const lobby = await sdk.lobbies.createLobby(games[0].id);
+}
+```
+
+---
+
+## License
+
+MIT