@watchtower-sdk/core 0.2.0

package/README.md

@@ -0,0 +1,336 @@
+# @watchtower/sdk
+
+Simple game backend SDK - cloud saves, multiplayer rooms, automatic state sync.
+
+## Installation
+
+```bash
+npm install @watchtower/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Watchtower } from '@watchtower/sdk'
+
+const wt = new Watchtower({
+  gameId: 'my-game',
+  apiKey: 'wt_live_...' // Get from dashboard
+})
+
+// Cloud saves
+await wt.save('progress', { level: 5, coins: 100 })
+const data = await wt.load('progress')
+
+// Multiplayer
+const room = await wt.createRoom()
+console.log('Share this code:', room.code) // e.g., "ABCD"
+```
+
+## Cloud Saves
+
+Simple key-value storage per player. Works across devices.
+
+```typescript
+// Save anything JSON-serializable
+await wt.save('progress', { level: 5, coins: 100 })
+await wt.save('settings', { music: true, sfx: true })
+await wt.save('inventory', ['sword', 'shield', 'potion'])
+
+// Load it back
+const progress = await wt.load('progress')
+const settings = await wt.load('settings')
+
+// List all save keys
+const keys = await wt.listSaves() // ['progress', 'settings', 'inventory']
+
+// Delete a save
+await wt.deleteSave('inventory')
+```
+
+## Multiplayer Rooms
+
+Create rooms with 4-letter codes. Share with friends to play together.
+
+```typescript
+// Create a room (you become the host)
+const room = await wt.createRoom()
+console.log('Room code:', room.code)
+
+// Join an existing room
+const room = await wt.joinRoom('ABCD')
+
+// Check room properties
+room.isHost      // true if you're the host
+room.hostId      // current host's player ID
+room.playerId    // your player ID
+room.playerCount // number of players
+room.players     // all players' states
+```
+
+## Player State Sync
+
+Automatically sync your player's position/state to all other players.
+
+```typescript
+// Set your player state (automatically synced at 20Hz)
+room.player.set({
+  x: 100,
+  y: 200,
+  sprite: 'running',
+  health: 100
+})
+
+// State is merged, so you can update individual fields
+room.player.set({ x: 150 }) // keeps y, sprite, health
+
+// Force immediate sync
+room.player.sync()
+
+// See all players' states
+room.on('players', (players) => {
+  for (const [playerId, state] of Object.entries(players)) {
+    if (playerId !== room.playerId) {
+      // Update other player's sprite
+      updateOtherPlayer(playerId, state.x, state.y, state.sprite)
+    }
+  }
+})
+```
+
+## Game State (Host-Controlled)
+
+Shared state for things like game phase, scores, round number. Only the host can modify it.
+
+```typescript
+// Host sets game state
+if (room.isHost) {
+  room.state.set({
+    phase: 'lobby',
+    round: 0,
+    scores: {}
+  })
+  
+  // Start the game
+  room.state.set({ phase: 'playing', round: 1 })
+}
+
+// Everyone receives state updates
+room.on('state', (state) => {
+  if (state.phase === 'playing') {
+    startGame()
+  }
+  if (state.phase === 'gameover') {
+    showWinner(state.winner)
+  }
+})
+
+// Read current state anytime
+const currentState = room.state.get()
+```
+
+## Broadcast Messages
+
+For one-off events that don't need persistent state.
+
+```typescript
+// Broadcast to all players
+room.broadcast({ type: 'explosion', x: 50, y: 50 })
+room.broadcast({ type: 'chat', message: 'gg!' })
+
+// Send to specific player
+room.sendTo(playerId, { type: 'private_message', text: 'hey' })
+
+// Receive messages
+room.on('message', (from, data) => {
+  if (data.type === 'explosion') {
+    createExplosion(data.x, data.y)
+  }
+  if (data.type === 'chat') {
+    showChat(from, data.message)
+  }
+})
+```
+
+## Room Events
+
+```typescript
+// Connection established
+room.on('connected', ({ playerId, room }) => {
+  console.log('Connected as', playerId)
+  console.log('Host is', room.hostId)
+})
+
+// Player joined
+room.on('playerJoined', (playerId, playerCount) => {
+  console.log(`${playerId} joined (${playerCount} players)`)
+  spawnPlayer(playerId)
+})
+
+// Player left
+room.on('playerLeft', (playerId, playerCount) => {
+  console.log(`${playerId} left (${playerCount} players)`)
+  removePlayer(playerId)
+})
+
+// Host changed (automatic migration when host leaves)
+room.on('hostChanged', (newHostId) => {
+  console.log('New host:', newHostId)
+  if (newHostId === room.playerId) {
+    console.log("I'm the host now!")
+  }
+})
+
+// Disconnected
+room.on('disconnected', () => {
+  console.log('Lost connection')
+})
+
+// Error
+room.on('error', (error) => {
+  console.error('Room error:', error)
+})
+```
+
+## Host Transfer
+
+```typescript
+// Host can transfer to another player
+if (room.isHost) {
+  room.transferHost(otherPlayerId)
+}
+```
+
+## Full Example: Simple Multiplayer Game
+
+```typescript
+import { Watchtower } from '@watchtower/sdk'
+
+const wt = new Watchtower({ gameId: 'my-game', apiKey: 'wt_...' })
+
+// Join or create room
+async function joinGame(code?: string) {
+  const room = code 
+    ? await wt.joinRoom(code)
+    : await wt.createRoom()
+  
+  console.log('Room:', room.code)
+  
+  // Game loop - update player position
+  function gameLoop() {
+    room.player.set({
+      x: myPlayer.x,
+      y: myPlayer.y,
+      animation: myPlayer.currentAnim
+    })
+    requestAnimationFrame(gameLoop)
+  }
+  gameLoop()
+  
+  // Render other players
+  const otherPlayers: Record<string, Sprite> = {}
+  
+  room.on('players', (players) => {
+    for (const [id, state] of Object.entries(players)) {
+      if (id === room.playerId) continue
+      
+      // Create sprite if new player
+      if (!otherPlayers[id]) {
+        otherPlayers[id] = createSprite()
+      }
+      
+      // Update position
+      otherPlayers[id].x = state.x as number
+      otherPlayers[id].y = state.y as number
+      otherPlayers[id].play(state.animation as string)
+    }
+  })
+  
+  // Clean up when players leave
+  room.on('playerLeft', (id) => {
+    otherPlayers[id]?.destroy()
+    delete otherPlayers[id]
+  })
+  
+  // Handle game events
+  room.on('message', (from, data: any) => {
+    if (data.type === 'shoot') {
+      createBullet(data.x, data.y, data.dir)
+    }
+  })
+  
+  // Game state (host manages rounds, scores)
+  room.on('state', (state: any) => {
+    if (state.phase === 'playing') {
+      showRound(state.round)
+    }
+    if (state.phase === 'gameover') {
+      showWinner(state.winner)
+    }
+  })
+  
+  // If we're host, start game when 2 players join
+  room.on('playerJoined', (_, count) => {
+    if (room.isHost && count >= 2) {
+      room.state.set({ phase: 'playing', round: 1 })
+    }
+  })
+  
+  return room
+}
+```
+
+## API Reference
+
+### Watchtower
+
+```typescript
+const wt = new Watchtower(config)
+```
+
+| Config | Type | Description |
+|--------|------|-------------|
+| `gameId` | `string` | Your game's unique identifier |
+| `apiKey` | `string` | API key from dashboard |
+| `playerId` | `string?` | Custom player ID (auto-generated if not provided) |
+| `apiUrl` | `string?` | Custom API URL (default: Watchtower API) |
+
+### Room
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `code` | `string` | 4-letter room code |
+| `isHost` | `boolean` | True if you're the host |
+| `hostId` | `string` | Current host's player ID |
+| `playerId` | `string` | Your player ID |
+| `playerCount` | `number` | Number of players |
+| `players` | `PlayersState` | All players' states |
+| `connected` | `boolean` | Connection status |
+
+| Method | Description |
+|--------|-------------|
+| `player.set(state)` | Set your player state (auto-synced) |
+| `player.get()` | Get your current player state |
+| `player.sync()` | Force immediate sync |
+| `state.set(state)` | Set game state (host only) |
+| `state.get()` | Get current game state |
+| `broadcast(data)` | Send to all players |
+| `sendTo(id, data)` | Send to specific player |
+| `transferHost(id)` | Transfer host (host only) |
+| `disconnect()` | Leave the room |
+
+| Event | Callback | Description |
+|-------|----------|-------------|
+| `connected` | `({playerId, room}) => void` | Connected to room |
+| `players` | `(players) => void` | Player states updated |
+| `state` | `(state) => void` | Game state updated |
+| `playerJoined` | `(id, count) => void` | Player joined |
+| `playerLeft` | `(id, count) => void` | Player left |
+| `hostChanged` | `(newHostId) => void` | Host changed |
+| `message` | `(from, data) => void` | Received broadcast |
+| `disconnected` | `() => void` | Lost connection |
+| `error` | `(error) => void` | Error occurred |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,296 @@
+/**
+ * Watchtower SDK
+ * Simple game backend - saves, multiplayer rooms, and more
+ *
+ * @example
+ * ```ts
+ * import { Watchtower } from '@watchtower/sdk'
+ *
+ * const wt = new Watchtower({ gameId: 'my-game', apiKey: 'wt_...' })
+ *
+ * // Cloud saves
+ * await wt.save('progress', { level: 5, coins: 100 })
+ * const data = await wt.load('progress')
+ *
+ * // Multiplayer
+ * const room = await wt.createRoom()
+ * console.log('Room code:', room.code) // e.g., "ABCD"
+ *
+ * // Player state (auto-synced to others)
+ * room.player.set({ x: 100, y: 200, sprite: 'idle' })
+ *
+ * // See other players
+ * room.on('players', (players) => {
+ *   for (const [id, state] of Object.entries(players)) {
+ *     updatePlayer(id, state)
+ *   }
+ * })
+ *
+ * // Shared game state (host-controlled)
+ * if (room.isHost) {
+ *   room.state.set({ phase: 'playing', round: 1 })
+ * }
+ * room.on('state', (state) => updateGameState(state))
+ *
+ * // One-off events
+ * room.broadcast({ type: 'explosion', x: 50, y: 50 })
+ * room.on('message', (from, data) => handleEvent(from, data))
+ * ```
+ */
+interface WatchtowerConfig {
+    /** Your game's unique identifier */
+    gameId: string;
+    /** Player ID (auto-generated if not provided) */
+    playerId?: string;
+    /** API base URL (default: https://watchtower-api.watchtower-host.workers.dev) */
+    apiUrl?: string;
+    /** API key for authenticated requests (optional for now) */
+    apiKey?: string;
+}
+interface SaveData<T = unknown> {
+    key: string;
+    data: T;
+}
+interface PlayerInfo {
+    id: string;
+    joinedAt: number;
+}
+interface RoomInfo {
+    code: string;
+    gameId: string;
+    hostId: string;
+    players: PlayerInfo[];
+    playerCount: number;
+}
+/** Game-wide stats */
+interface GameStats {
+    /** Players currently online */
+    online: number;
+    /** Unique players today (DAU) */
+    today: number;
+    /** Unique players this month (MAU) */
+    monthly: number;
+    /** Total unique players all time */
+    total: number;
+    /** Currently active rooms */
+    rooms: number;
+    /** Players currently in multiplayer rooms */
+    inRooms: number;
+    /** Average session length in seconds */
+    avgSession: number;
+    /** Average players per room */
+    avgRoomSize: number;
+    /** Last update timestamp */
+    updatedAt: number | null;
+}
+/** Current player's stats */
+interface PlayerStats {
+    /** When the player first connected */
+    firstSeen: string | null;
+    /** When the player last connected */
+    lastSeen: string | null;
+    /** Total sessions */
+    sessions: number;
+    /** Total playtime in seconds */
+    playtime: number;
+}
+/** Player state - position, animation, custom data */
+type PlayerState = Record<string, unknown>;
+/** All players' states indexed by player ID */
+type PlayersState = Record<string, PlayerState>;
+/** Shared game state - host controlled */
+type GameState = Record<string, unknown>;
+type RoomEventMap = {
+    /** Fired when connected to room */
+    connected: (info: {
+        playerId: string;
+        room: RoomInfo;
+    }) => void;
+    /** Fired when a player joins */
+    playerJoined: (playerId: string, playerCount: number) => void;
+    /** Fired when a player leaves */
+    playerLeft: (playerId: string, playerCount: number) => void;
+    /** Fired when players' states update (includes all players) */
+    players: (players: PlayersState) => void;
+    /** Fired when shared game state updates */
+    state: (state: GameState) => void;
+    /** Fired when host changes */
+    hostChanged: (newHostId: string) => void;
+    /** Fired when receiving a broadcast message */
+    message: (from: string, data: unknown) => void;
+    /** Fired on disconnect */
+    disconnected: () => void;
+    /** Fired on error */
+    error: (error: Error) => void;
+};
+declare class PlayerStateManager {
+    private room;
+    private _state;
+    private syncInterval;
+    private dirty;
+    private syncRateMs;
+    constructor(room: Room, syncRateMs?: number);
+    /** Set player state (merged with existing) */
+    set(state: PlayerState): void;
+    /** Replace entire player state */
+    replace(state: PlayerState): void;
+    /** Get current player state */
+    get(): PlayerState;
+    /** Clear player state */
+    clear(): void;
+    /** Start automatic sync */
+    startSync(): void;
+    /** Stop automatic sync */
+    stopSync(): void;
+    /** Force immediate sync */
+    sync(): void;
+}
+declare class GameStateManager {
+    private room;
+    private _state;
+    constructor(room: Room);
+    /** Set game state (host only, merged with existing) */
+    set(state: GameState): void;
+    /** Replace entire game state (host only) */
+    replace(state: GameState): void;
+    /** Get current game state */
+    get(): GameState;
+    /** Update internal state (called on sync from server) */
+    _update(state: GameState): void;
+}
+declare class Room {
+    readonly code: string;
+    private ws;
+    private listeners;
+    private config;
+    /** Player state manager - set your position/state here */
+    readonly player: PlayerStateManager;
+    /** Game state manager - shared state (host-controlled) */
+    readonly state: GameStateManager;
+    /** All players' current states */
+    private _players;
+    /** Current host ID */
+    private _hostId;
+    /** Room info from initial connection */
+    private _roomInfo;
+    constructor(code: string, config: Required<WatchtowerConfig>);
+    /** Get the current host ID */
+    get hostId(): string;
+    /** Check if current player is the host */
+    get isHost(): boolean;
+    /** Get current player's ID */
+    get playerId(): string;
+    /** Get all players' states */
+    get players(): PlayersState;
+    /** Get player count */
+    get playerCount(): number;
+    /** Connect to the room via WebSocket */
+    connect(): Promise<void>;
+    private handleMessage;
+    /** Subscribe to room events */
+    on<K extends keyof RoomEventMap>(event: K, callback: RoomEventMap[K]): void;
+    /** Unsubscribe from room events */
+    off<K extends keyof RoomEventMap>(event: K, callback: RoomEventMap[K]): void;
+    private emit;
+    /** Broadcast data to all players in the room (for one-off events) */
+    broadcast(data: unknown, excludeSelf?: boolean): void;
+    /** Send data to a specific player */
+    sendTo(playerId: string, data: unknown): void;
+    /** Send a ping to measure latency */
+    ping(): void;
+    /** Request host transfer (host only) */
+    transferHost(newHostId: string): void;
+    private send;
+    /** Disconnect from the room */
+    disconnect(): void;
+    /** Check if connected */
+    get connected(): boolean;
+}
+declare class Watchtower {
+    /** @internal - Config is non-enumerable to prevent accidental API key exposure */
+    private readonly config;
+    constructor(config: WatchtowerConfig);
+    private generatePlayerId;
+    /** Get the current player ID */
+    get playerId(): string;
+    /** Get the game ID */
+    get gameId(): string;
+    private fetch;
+    /**
+     * Save data to the cloud
+     * @param key - Save slot name (e.g., "progress", "settings")
+     * @param data - Any JSON-serializable data
+     */
+    save(key: string, data: unknown): Promise<void>;
+    /**
+     * Load data from the cloud
+     * @param key - Save slot name
+     * @returns The saved data, or null if not found
+     */
+    load<T = unknown>(key: string): Promise<T | null>;
+    /**
+     * List all save keys for this player
+     */
+    listSaves(): Promise<string[]>;
+    /**
+     * Delete a save
+     * @param key - Save slot name
+     */
+    deleteSave(key: string): Promise<void>;
+    /**
+     * Create a new multiplayer room
+     * @returns A Room instance (already connected)
+     */
+    createRoom(): Promise<Room>;
+    /**
+     * Join an existing room by code
+     * @param code - The 4-letter room code
+     * @returns A Room instance (already connected)
+     */
+    joinRoom(code: string): Promise<Room>;
+    /**
+     * Get info about a room without joining
+     * @param code - The 4-letter room code
+     */
+    getRoomInfo(code: string): Promise<RoomInfo>;
+    /**
+     * Get game-wide stats
+     * @returns Stats like online players, DAU, rooms active, etc.
+     *
+     * @example
+     * ```ts
+     * const stats = await wt.getStats()
+     * console.log(`${stats.online} players online`)
+     * console.log(`${stats.rooms} active rooms`)
+     * ```
+     */
+    getStats(): Promise<GameStats>;
+    /**
+     * Get the current player's stats
+     * @returns Player's firstSeen, sessions count, playtime
+     *
+     * @example
+     * ```ts
+     * const me = await wt.getPlayerStats()
+     * console.log(`You've played ${Math.floor(me.playtime / 3600)} hours`)
+     * console.log(`Member since ${new Date(me.firstSeen).toLocaleDateString()}`)
+     * ```
+     */
+    getPlayerStats(): Promise<PlayerStats>;
+    /**
+     * Track a session start (call on game load)
+     * This is called automatically if you use createRoom/joinRoom
+     */
+    trackSessionStart(): Promise<void>;
+    /**
+     * Track a session end (call on game close)
+     */
+    trackSessionEnd(): Promise<void>;
+    /**
+     * Convenience getter for stats (same as getStats but as property style)
+     * Note: This returns a promise, use `await wt.stats` or `wt.getStats()`
+     */
+    get stats(): Promise<GameStats>;
+}
+
+export { type GameState, type GameStats, type PlayerInfo, type PlayerState, type PlayerStats, type PlayersState, Room, type RoomEventMap, type RoomInfo, type SaveData, Watchtower, type WatchtowerConfig, Watchtower as default };