@usions/sdk 2.11.1 → 2.12.0

package/README.md

@@ -4,6 +4,14 @@ Client SDK for building mini-apps and games on the [Usion](https://usions.com) p
 
 Provides access to user info, storage, wallet, chat, sessions, and real-time multiplayer game features.
 
+## Documentation
+
+- [Guides](../../docs/sdk-guides/README.md) — first game in 30 min, the reliability contract, netcode, money, cloud saves
+- [API reference](../../docs/sdk-api/README.md) (generated from the type declarations)
+- [Platform behavior spec](../../docs/sdk-guides/06-platform-spec.md) — delivery guarantees, quotas, security model
+- [CHANGELOG](CHANGELOG.md) · [versioning policy](../../docs/sdk-versioning-policy.md)
+- Local development: [`@usions/devkit`](../devkit/README.md) — build and chaos-test without a Usion account
+
 ## Install
 
 ```bash
@@ -109,8 +117,36 @@ Usion.game.onGameRestarted((data) => { ... })
 Usion.game.onError((data) => { ... })
 Usion.game.onDisconnect((reason) => { ... })
 Usion.game.onReconnect((attempt) => { ... })
+Usion.game.onPlayerConnection((d) => { ... })  // d.state: 'connected' | 'reconnecting' | 'gone'
 ```
 
+#### Reliability contract (read this before shipping multiplayer)
+
+The platform recovers from connection blips for you — your game just has to
+follow four rules so both screens always agree:
+
+1. **Apply moves only in `onAction`** — never optimistically on send. Every
+   action (including your own) is echoed back with the authoritative
+   `sequence`; the SDK deduplicates, so each action is delivered exactly once
+   even across reconnect replays.
+2. **Turn-based? Pass `{ nextTurn }`** on every move and trust `current_turn`
+   from the join result / `onSync` instead of deriving the turn locally:
+   ```javascript
+   await Usion.game.action('move', { cell: 4 }, { nextTurn: opponentId })
+   ```
+3. **Handle `onDisconnect` / `onReconnect`** — pause input and show a
+   "reconnecting…" hint. The platform rejoins the room and replays missed
+   actions automatically. Use `onPlayerConnection` for the opponent's status;
+   don't end the match on `'reconnecting'` (a ~15s grace window applies),
+   treat `'gone'` as the opponent having left.
+4. **Authority checkpoints with `setState`** — the room authority
+   (`player_ids[0]`) should checkpoint at meaningful transitions so a
+   rejoining client restores instantly (delivered as `game_state` in the
+   join result and `onSync`; max 64 KB):
+   ```javascript
+   await Usion.game.setState(fullGameState)
+   ```
+
 #### Other
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.11.1",
+  "version": "2.12.0",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",
@@ -26,11 +26,18 @@
     "build": "rollup -c",
     "build:copy": "npm run build && cp src/browser.js ../../web/public/usion-sdk.js && cp src/browser.js ../../microservices/shared/usion-sdk.js",
     "watch": "rollup -c --watch",
-    "test": "npm run build && vitest run",
-    "prepublishOnly": "npm run build && vitest run"
+    "test": "npm run build && vitest run && npm run test:types && npm run check:src && npm run check:size",
+    "prepublishOnly": "npm run build && vitest run && npm run test:types && npm run check:src && npm run check:size",
+    "test:types": "tsc -p test/tsconfig.json",
+    "check:size": "node scripts/check-size.mjs",
+    "docs:api": "typedoc --plugin typedoc-plugin-markdown --entryPoints types/index.d.ts --out ../../docs/sdk-api --readme none --tsconfig test/tsconfig.json",
+    "check:src": "tsc -p tsconfig.src.json"
   },
   "devDependencies": {
     "rollup": "^4.0.0",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typescript": "^5.9.3",
     "vitest": "^2.1.9"
   },
   "keywords": [
@@ -53,4 +60,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}