@playcademy/sdk 0.1.13 → 0.1.15

package/README.md

@@ -31,6 +31,17 @@ The SDK serves as the primary interface between your game and the Playcademy pla
 - **Server Integration**: Backend services integrating with Playcademy APIs
 - **Testing & Automation**: Automated testing of platform integrations
 
+### Connection Monitoring
+
+The SDK automatically monitors network connectivity and provides hooks for games to handle disconnects gracefully:
+
+- **Automatic Detection**: Multi-signal approach detects offline, slow, and degraded connections
+- **Game Handlers**: Implement custom disconnect behavior (e.g., return to lobby, pause game)
+- **Platform Integration**: Built-in helpers for displaying connection alerts
+- **Zero Config**: Works out of the box, customizable when needed
+
+See [DISCONNECT_HANDLING.md](./DISCONNECT_HANDLING.md) for detailed documentation and examples.
+
 ## Installation
 
 Install the SDK using your preferred package manager:
@@ -61,7 +72,15 @@ import { PlaycademyClient } from '@playcademy/sdk'
 async function initializeGame() {
     try {
         // Automatic initialization - detects environment and configures appropriately
-        const client = await PlaycademyClient.init()
+        const client = await PlaycademyClient.init({
+            // Optional: Handle connection issues gracefully
+            onDisconnect: ({ state, displayAlert }) => {
+                if (state === 'offline') {
+                    displayAlert?.('Connection lost. Reconnecting...', { type: 'warning' })
+                    // Return to safe state (e.g., lobby)
+                }
+            },
+        })
 
         // Get current user
         const user = await client.users.me()
@@ -322,6 +341,11 @@ client.on('authChange', payload => {
     console.log('Authentication changed:', payload.token)
 })
 
+// Connection state changes
+client.on('connectionChange', ({ state, reason }) => {
+    console.log(`Connection: ${state} - ${reason}`)
+})
+
 // Inventory changes
 client.on('inventoryChange', payload => {
     console.log(`Item ${payload.itemId}: ${payload.delta} (total: ${payload.newTotal})`)
@@ -339,6 +363,19 @@ client.on('levelUp', payload => {
 })
 ```
 
+### Disconnect Handling
+
+For convenience, use the `onDisconnect` method to handle only offline/degraded states:
+
+```typescript
+const cleanup = client.onDisconnect(({ state, reason, displayAlert }) => {
+    console.log(`Disconnect detected: ${state}`)
+    displayAlert?.(`Connection ${state}: ${reason}`, { type: 'warning' })
+})
+
+// Later: cleanup() to unregister
+```
+
 ### Event-Driven UI Updates
 
 ```typescript