@fzgame/sdk 0.1.0 → 0.3.1

package/README.md

@@ -80,6 +80,109 @@ yourself.
 A timeout is combined with any `AbortSignal` you pass to a request, so your own cancellation keeps
 working.
 
+## Integrate a game into your app
+
+The path from a configured client to a resumed play session. This code runs on your server; the
+browser receives a play URL and never sees the app secret.
+
+| Step | Call | Returns |
+| --- | --- | --- |
+| List the games published in the app | `GET /sdk/game-instances` | instances, each with its `game` |
+| Identify or create the player | `POST /sdk/login` | `{ player, playerAccessToken }` |
+| Read the player's live session, for a continue screen | `GET /sdk/sessions/active` | `{ session }`, the newest live session or `null` |
+| Build the play URL | `resolveGameURL(...)` | `{resolvedUrl}?apiUrl=…&gameInstanceId=…&playerAccessToken=…` |
+| Game connects, play starts or resumes | `POST /games/runtime/sessions` | the session, used by the kit |
+| Game saves progress | `PUT /games/runtime/sessions/{token}/snapshot` | the session |
+
+### 1. List the games
+
+```ts
+const { data, error } = await fetchClient.GET('/sdk/game-instances', {
+  params: { query: { page: 1, limit: 20 } },
+})
+const instances = data?.data ?? []
+const instance = instances.find((i) => i.game?.slug === 'flabby-bird')
+```
+
+The response is paginated: `data.data` holds the instances and `data.pageInfo` holds `page`,
+`total`, `hasNextPage`, and related counts. Only instances in `PUBLISHED` status for the client's app
+come back. Each item carries `id`, `resolvedUrl`, `overrides`, `status`, and a `game` relation.
+`game.configSchema` is JSON; read `viewMode` out of it (`'landscape'` or `'portrait'`) to tell the two
+apart.
+
+### 2. Identify the player
+
+```ts
+const { data: login } = await fetchClient.POST('/sdk/login', {
+  body: { identity: 'user-42', displayName: 'Ada' },
+})
+const player = login?.player
+const playerAccessToken = login?.playerAccessToken
+```
+
+`identity` is your own user id. `AppPlayer` is unique per app on that value, so sending it on every
+call returns the same player. `playerAccessToken` is a signed JWT for that player, bound to your app
+and expiring with the play-session window; pass it to the game, never the app secret.
+
+### 3. Build the play URL
+
+```ts
+const url = resolveGameURL(instance, login.playerAccessToken)
+```
+
+`resolveGameURL` starts from `instance.resolvedUrl` and appends `apiUrl` (the one passed to
+`initializeSDK`), `gameInstanceId`, `playerAccessToken`, and the instance `overrides` as `gameSetting`.
+`apiUrl` must be reachable from the browser, because the frame calls the public instance and runtime
+endpoints itself. A `createSdkClient` caller, or one that needs a different frame origin, passes it in
+the optional third argument: `resolveGameURL(instance, token, { apiUrl, config })`, where `config`
+replaces the instance overrides. The kit reads the token when the game calls `createKit()`; nothing
+has to be sent into the frame first.
+
+The token is a bearer credential: anyone holding it can play as that player, so keep it out of logs
+and analytics. A host that holds a `playSessionToken` already can also post the kit's `session`
+message after the frame loads (see the kit README).
+
+### 4. Landscape games
+
+On a phone, present the frame rotated when `viewMode` is `'landscape'`. The API reports the value
+only; rotation belongs to the host. The portal's `GameViewport` rotates the iframe with a CSS
+transform on coarse-pointer devices, and the SDK plays no part in it.
+
+### 5. Play and resume
+
+The game calls `POST /games/runtime/sessions` with `{ gameInstanceId, playerAccessToken }`. The
+server verifies the JWT with the same key as `BETTER_AUTH_SECRET`, resolves the player it names, and
+creates a session or returns the player's newest `CREATED`, `READY`, `PLAYING`, or `PAUSED` session
+for the instance, so a returning player lands back in the same round with `kit.snapshot.state`
+restored from the session's snapshot. The host does not create the session and does not look it up.
+
+A host that shows its own "continue" or progress screen reads the same session first:
+
+```ts
+const { data } = await fetchClient.GET('/sdk/sessions/active', {
+  params: { query: { playerId: player.id, gameInstanceId: instance.id } },
+})
+// data.session is the newest live session, or null
+```
+
+`playerId` is the `AppPlayer.id` (the row id) and `playerAccessToken` is the JWT login returned. Pass
+`gameInstanceId` to scope the answer to one build. A live session carries `token`, `status`,
+`metadata.snapshot`, `score`, and `result`, so a host can show "your last round" before the frame
+loads. The numbers and state the game reports stay authoritative: the host reads, the game writes.
+
+A session ends on `finish` or `abort`, and a terminal session is not resumed. Closing the frame
+leaves it resumable. Sessions expire after 24 hours, and `POST /sdk/players/{id}/logout` expires
+every live session of a player.
+
+### What this package does not cover
+
+- The frame side of the flow. `postMessage`, the snapshot, and the lifecycle events belong to
+  `@fzgame/kit`; this package calls the HTTP API.
+- Landscape presentation. The API reports `viewMode` inside `game.configSchema`; rotating the frame
+  is the host's job, and the portal's `GameViewport` is the reference.
+- `POST /sdk/sessions` creates a session from the host when you need the token up front. The session
+  events are `/sdk/sessions/{token}/start|pause|resume|score|finish|abort`.
+
 ## Errors
 
 | Error | Thrown when |
@@ -99,10 +202,14 @@ status and the parsed body.
 document separately:
 
 ```ts
+import { resolveGameURL, type GameInstance } from '@fzgame/sdk'
 import type { components, paths } from '@fzgame/sdk'
 
 type App = components['schemas']['App']
 type GameInstanceId = paths['/sdk/game-instances/{id}']['get']['parameters']['path']['id']
+
+// GameInstance is components['schemas']['AppGameInstance']: an item from GET /sdk/game-instances.
+const playUrl = resolveGameURL(gameInstance, playerAccessToken)
 ```
 
 `src/types/schema.d.ts` is generated from the server document that the workspace build writes to
@@ -115,6 +222,9 @@ pnpm --filter @fzgame/sdk compile
 That path is inside this monorepo, so the script runs for contributors here. Consumers of the
 published package get the types that were generated at release time.
 
+A route without a declared success response types its body as empty. When you add a controller
+response, annotate it with `@ApiResponse` so the regenerated types carry it.
+
 ## Entry points
 
 | Specifier | Contents |