connectbase-client 0.1.0

package/README.md

@@ -0,0 +1,565 @@
+# @connect-base/client
+
+Connect Base JavaScript/TypeScript SDK for building real-time multiplayer games and applications.
+
+## Installation
+
+```bash
+npm install @connect-base/client
+# or
+pnpm add @connect-base/client
+# or
+yarn add @connect-base/client
+```
+
+## Quick Start
+
+```typescript
+import { ConnectBase } from '@connect-base/client'
+
+// Initialize the SDK
+const cb = new ConnectBase({
+  apiKey: 'your-api-key'
+})
+
+// Create a game room client
+const gameClient = cb.game.createClient({
+  clientId: 'player-123'
+})
+
+// Set up event handlers
+gameClient
+  .on('onConnect', () => console.log('Connected!'))
+  .on('onStateUpdate', (state) => console.log('State:', state))
+  .on('onPlayerJoined', (player) => console.log('Player joined:', player))
+  .on('onPlayerLeft', (player) => console.log('Player left:', player))
+
+// Connect and create a room
+await gameClient.connect()
+const state = await gameClient.createRoom({
+  maxPlayers: 4,
+  tickRate: 64
+})
+```
+
+## Features
+
+- **Real-time Game Server**: WebSocket-based multiplayer game state synchronization
+- **Authentication**: OAuth2, email/password, and social login support
+- **Database**: JSON-based NoSQL database with real-time queries
+- **Storage**: File storage with CDN support
+- **Push Notifications**: Cross-platform push notification support
+- **WebRTC**: Real-time audio/video communication
+- **Payments**: Subscription and one-time payment support
+
+## API Reference
+
+### Game Server
+
+#### GameRoom
+
+The main class for real-time game communication.
+
+```typescript
+const gameClient = cb.game.createClient({
+  clientId: 'unique-player-id',    // Required: Unique identifier for this player
+  gameServerUrl: 'wss://...',      // Optional: Custom game server URL
+  autoReconnect: true,             // Optional: Auto-reconnect on disconnect (default: true)
+  maxReconnectAttempts: 5,         // Optional: Max reconnect attempts (default: 5)
+  reconnectInterval: 1000,         // Optional: Base reconnect interval in ms (default: 1000)
+  connectionTimeout: 10000,        // Optional: Connection timeout in ms (default: 10000)
+})
+```
+
+##### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `roomId` | `string \| null` | Current room ID |
+| `state` | `GameState \| null` | Current game state |
+| `isConnected` | `boolean` | Connection status |
+| `isOfflineMode` | `boolean` | Offline mode status |
+| `latency` | `number` | Current latency in ms |
+| `connectionState` | `ConnectionState` | Detailed connection state |
+
+##### Methods
+
+**connect(roomId?: string): Promise\<void>**
+
+Connect to the game server. Optionally specify a room ID to join immediately.
+
+```typescript
+await gameClient.connect()
+// or
+await gameClient.connect('existing-room-id')
+```
+
+**disconnect(): void**
+
+Disconnect from the game server.
+
+```typescript
+gameClient.disconnect()
+```
+
+**createRoom(config?: GameRoomConfig): Promise\<GameState>**
+
+Create a new game room.
+
+```typescript
+const state = await gameClient.createRoom({
+  roomId: 'my-custom-room',        // Optional: Custom room ID
+  categoryId: 'battle-royale',     // Optional: Room category
+  maxPlayers: 100,                 // Optional: Max players (default: 10)
+  tickRate: 64,                    // Optional: Server tick rate (default: 64)
+  metadata: { map: 'forest' }      // Optional: Custom metadata
+})
+```
+
+**joinRoom(roomId: string, metadata?: Record\<string, string>): Promise\<GameState>**
+
+Join an existing room.
+
+```typescript
+const state = await gameClient.joinRoom('room-id', {
+  team: 'blue',
+  displayName: 'Player1'
+})
+```
+
+**leaveRoom(): Promise\<void>**
+
+Leave the current room.
+
+```typescript
+await gameClient.leaveRoom()
+```
+
+**sendAction(action: GameAction): void**
+
+Send a game action to the server.
+
+```typescript
+gameClient.sendAction({
+  type: 'move',
+  data: { x: 100, y: 200 }
+})
+
+gameClient.sendAction({
+  type: 'attack',
+  data: { targetId: 'enemy-1', damage: 50 }
+})
+```
+
+**sendChat(message: string): void**
+
+Send a chat message to the room.
+
+```typescript
+gameClient.sendChat('Hello everyone!')
+```
+
+**requestState(): Promise\<GameState>**
+
+Request the full current state from the server.
+
+```typescript
+const state = await gameClient.requestState()
+```
+
+**listRooms(): Promise\<GameRoomInfo[]>**
+
+List all available rooms.
+
+```typescript
+const rooms = await gameClient.listRooms()
+rooms.forEach(room => {
+  console.log(`${room.id}: ${room.playerCount}/${room.maxPlayers}`)
+})
+```
+
+**ping(): Promise\<number>**
+
+Measure round-trip time to the server.
+
+```typescript
+const rtt = await gameClient.ping()
+console.log(`Latency: ${rtt}ms`)
+```
+
+##### Event Handlers
+
+```typescript
+gameClient
+  .on('onConnect', () => {
+    // Called when connected to the server
+  })
+  .on('onDisconnect', (event: CloseEvent) => {
+    // Called when disconnected
+  })
+  .on('onStateUpdate', (state: GameState) => {
+    // Called when full state is received
+  })
+  .on('onDelta', (delta: GameDelta) => {
+    // Called for incremental state updates
+    // Use this for efficient state synchronization
+  })
+  .on('onPlayerJoined', (player: GamePlayer) => {
+    // Called when a player joins the room
+  })
+  .on('onPlayerLeft', (player: GamePlayer) => {
+    // Called when a player leaves the room
+  })
+  .on('onChat', (message: ChatMessage) => {
+    // Called when a chat message is received
+  })
+  .on('onError', (error: ErrorMessage) => {
+    // Called on errors
+  })
+  .on('onPong', (pong: PongMessage) => {
+    // Called when pong is received
+  })
+```
+
+#### Offline Mode
+
+Test your game logic locally without a server connection.
+
+```typescript
+// Enable offline mode
+gameClient.enableOfflineMode({
+  tickRate: 64,
+  initialState: {
+    players: {},
+    objects: []
+  },
+  simulatedPlayers: [
+    { clientId: 'bot-1', joinedAt: Date.now(), metadata: { isBot: 'true' } }
+  ]
+})
+
+// Update state directly
+gameClient.setOfflineState('players.player-1.position', { x: 100, y: 200 })
+
+// Add/remove simulated players
+gameClient.addSimulatedPlayer({
+  clientId: 'bot-2',
+  joinedAt: Date.now(),
+  metadata: {}
+})
+gameClient.removeSimulatedPlayer('bot-2')
+
+// Disable offline mode
+gameClient.disableOfflineMode()
+```
+
+### Authentication
+
+```typescript
+// Email/Password login
+const session = await cb.auth.signIn({
+  email: 'user@example.com',
+  password: 'password123'
+})
+
+// OAuth login
+const oauthUrl = await cb.oauth.getGoogleAuthUrl()
+// Redirect user to oauthUrl
+
+// Get current user
+const user = await cb.auth.getCurrentUser()
+
+// Sign out
+await cb.auth.signOut()
+```
+
+### Database
+
+```typescript
+// Query data
+const { data } = await cb.database.from('users').select().where({ active: true }).limit(10)
+
+// Insert data
+await cb.database.from('users').insert({
+  name: 'John',
+  email: 'john@example.com'
+})
+
+// Update data
+await cb.database.from('users').update({ active: false }).where({ id: 'user-1' })
+
+// Delete data
+await cb.database.from('users').delete().where({ id: 'user-1' })
+```
+
+### Storage
+
+```typescript
+// Upload file
+const { url } = await cb.storage.upload('avatars/user-1.png', file)
+
+// Download file
+const data = await cb.storage.download('avatars/user-1.png')
+
+// Delete file
+await cb.storage.delete('avatars/user-1.png')
+
+// List files
+const files = await cb.storage.list('avatars/')
+```
+
+### Realtime
+
+```typescript
+// Subscribe to a channel
+const channel = cb.realtime.channel('chat-room-1')
+
+channel.on('message', (data) => {
+  console.log('New message:', data)
+})
+
+await channel.subscribe()
+
+// Publish message
+channel.publish('message', { text: 'Hello!' })
+
+// Unsubscribe
+await channel.unsubscribe()
+```
+
+### Push Notifications
+
+```typescript
+// Register for push notifications
+await cb.push.register({
+  token: 'fcm-token-or-apns-token',
+  platform: 'android' // or 'ios', 'web'
+})
+
+// Subscribe to topics
+await cb.push.subscribeToTopic('news')
+
+// Unsubscribe from topic
+await cb.push.unsubscribeFromTopic('news')
+```
+
+### WebRTC
+
+```typescript
+// Create a broadcast
+const broadcast = cb.webrtc.createBroadcast({
+  roomId: 'live-stream-1'
+})
+
+await broadcast.start()
+
+// Join as viewer
+const viewer = cb.webrtc.createViewer({
+  roomId: 'live-stream-1'
+})
+
+viewer.on('stream', (stream) => {
+  videoElement.srcObject = stream
+})
+
+await viewer.join()
+```
+
+### Payments & Subscriptions
+
+```typescript
+// Create a subscription
+const subscription = await cb.subscription.create({
+  planId: 'premium-monthly',
+  billingKeyId: 'billing-key-1'
+})
+
+// Check subscription status
+const status = await cb.subscription.getStatus()
+
+// Cancel subscription
+await cb.subscription.cancel()
+```
+
+## Types
+
+### GameState
+
+```typescript
+interface GameState {
+  roomId: string
+  state: Record<string, unknown>  // Your game state
+  version: number
+  serverTime: number
+  tickRate: number
+  players: GamePlayer[]
+}
+```
+
+### GameDelta
+
+```typescript
+interface GameDelta {
+  fromVersion: number
+  toVersion: number
+  changes: Array<{
+    path: string
+    operation: 'set' | 'delete'
+    value?: unknown
+  }>
+  tick: number
+}
+```
+
+### GamePlayer
+
+```typescript
+interface GamePlayer {
+  clientId: string
+  joinedAt: number
+  metadata?: Record<string, string>
+}
+```
+
+### ConnectionState
+
+```typescript
+interface ConnectionState {
+  status: 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'error' | 'offline'
+  reconnectAttempt: number
+  lastError?: Error
+  latency: number
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  await gameClient.connect()
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Connection failed:', error.message)
+  }
+}
+
+// Or use event handlers
+gameClient.on('onError', (error) => {
+  console.error('Game error:', error.message)
+})
+```
+
+## Best Practices
+
+### State Synchronization
+
+Use delta updates for efficient state synchronization:
+
+```typescript
+gameClient.on('onDelta', (delta) => {
+  // Apply only the changes instead of replacing entire state
+  for (const change of delta.changes) {
+    applyChange(localState, change.path, change.operation, change.value)
+  }
+})
+```
+
+### Reconnection Handling
+
+```typescript
+gameClient.on('onDisconnect', (event) => {
+  if (event.code !== 1000) {
+    // Show reconnecting UI
+    showReconnectingMessage()
+  }
+})
+
+gameClient.on('onConnect', () => {
+  // Reconnected - request full state
+  gameClient.requestState()
+  hideReconnectingMessage()
+})
+```
+
+### Latency Compensation
+
+```typescript
+// Measure latency periodically
+setInterval(async () => {
+  const rtt = await gameClient.ping()
+  // Adjust client-side prediction based on latency
+  updatePredictionOffset(rtt / 2)
+}, 5000)
+```
+
+## Examples
+
+### Simple Multiplayer Game
+
+```typescript
+import { ConnectBase } from '@connect-base/client'
+
+const cb = new ConnectBase({ apiKey: 'your-api-key' })
+const game = cb.game.createClient({ clientId: `player-${Date.now()}` })
+
+// Local player state
+let localPlayer = { x: 0, y: 0 }
+
+game
+  .on('onConnect', () => console.log('Connected'))
+  .on('onStateUpdate', (state) => {
+    // Render all players
+    renderPlayers(state.state.players)
+  })
+  .on('onDelta', (delta) => {
+    // Efficient incremental updates
+    for (const change of delta.changes) {
+      updatePlayer(change.path, change.value)
+    }
+  })
+
+// Connect and create room
+await game.connect()
+await game.createRoom({ maxPlayers: 8 })
+
+// Game loop
+function gameLoop() {
+  // Read input
+  const input = getPlayerInput()
+
+  // Send action
+  if (input.moved) {
+    game.sendAction({
+      type: 'move',
+      data: { x: input.x, y: input.y }
+    })
+  }
+
+  requestAnimationFrame(gameLoop)
+}
+
+gameLoop()
+```
+
+### Chat Application
+
+```typescript
+const game = cb.game.createClient({ clientId: userId })
+
+game.on('onChat', (message) => {
+  displayMessage(message.senderId, message.message, message.timestamp)
+})
+
+await game.connect()
+await game.joinRoom('general-chat')
+
+// Send message
+chatInput.addEventListener('submit', () => {
+  game.sendChat(chatInput.value)
+  chatInput.value = ''
+})
+```
+
+## License
+
+MIT