@fzgame/sdk 0.0.0-stage → 0.3.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Fanzeal
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,249 @@
-# Temporary Holding Version
+# @fzgame/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed client for the GameHub server API. The types come from the server's own OpenAPI document, so
+every path, parameter, and response you touch is checked at compile time.
+
+The client is `openapi-fetch` underneath and has no other runtime dependency. The root entry works in
+Node and in the browser; the optional `@fzgame/sdk/react` entry adds a React component for apps that
+want the client configured from a component tree.
+
+## Install
+
+```bash
+pnpm add @fzgame/sdk
+```
+
+React is a peer dependency, and only the `/react` entry needs it. Install React 18.2 or 19 if you use
+that entry.
+
+## Where credentials may live
+
+An app key and app secret authorize an *application*, so they belong to server-side code. Anything
+marked `NEXT_PUBLIC_*` is inlined into the browser bundle your players download, which publishes the
+secret. In a browser, keep the secret on your own backend and send the player a short-lived token
+instead.
+
+## Configure a client
+
+`initializeSDK` sets the process-wide client that `fetchClient` proxies to:
+
+```ts
+import { fetchClient, initializeSDK } from '@fzgame/sdk'
+
+initializeSDK({
+  apiUrl: 'https://api.example.com',
+  appKey: process.env.FZ_APP_KEY,
+  appSecret: process.env.FZ_APP_SECRET,
+})
+
+const { data, error } = await fetchClient.GET('/sdk/app/current')
+```
+
+`createSdkClient` returns an independent client, which is what to use when one process serves more
+than one app:
+
+```ts
+import { createSdkClient } from '@fzgame/sdk'
+
+const tenantA = createSdkClient({ apiUrl: 'https://api.example.com', appKey: 'a', appSecret: 'sa' })
+const tenantB = createSdkClient({ apiUrl: 'https://api.example.com', appKey: 'b', appSecret: 'sb' })
+```
+
+From React:
+
+```tsx
+import { SDKInitializer } from '@fzgame/sdk/react'
+
+export function Providers() {
+  return <SDKInitializer apiUrl="https://api.example.com" appKey="..." appSecret="..." />
+}
+```
+
+The effect depends on each value, so a rotated secret or a tenant switch reconfigures the client
+instead of being dropped after the first render.
+
+### `InitOptions`
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `apiUrl` | `string` | Base URL of the API. Required; a trailing slash is trimmed. |
+| `appKey` | `string` | Value of the `x-app-key` header: the app's `id`, which is what the guard looks the app up by. |
+| `appSecret` | `string` | Value of the `x-app-secret` header: one of the app's credential `clientSecret` values. |
+| `timeoutMs` | `number` | Abort a request after this many milliseconds. `0` or unset means no deadline. |
+| `fetch` | `typeof fetch` | Override the fetch implementation, for a Node polyfill or a test. |
+
+Credentials travel in headers, which the server's OpenAPI document does not declare, so attach them
+with `initializeSDK` or `createSdkClient` rather than by hand. The exported header names are
+`APP_KEY_HEADER` (`x-app-key`) and `APP_SECRET_HEADER` (`x-app-secret`) if you need to set them
+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 |
+| --- | --- |
+| `SdkConfigError` | `apiUrl` is missing or blank. |
+| `SdkNotInitializedError` | A call on `fetchClient` happens before `initializeSDK` or `<SDKInitializer>` ran. |
+
+Both are exported so a caller can branch on them. `fetchClient` throws rather than sending a request
+to a placeholder origin, so a mis-ordered import fails where it happens.
+
+Failed requests do not throw: `openapi-fetch` returns `{ data, error }`, and `error` carries the
+status and the parsed body.
+
+## Types
+
+`@fzgame/sdk` re-exports the generated types, so you can name a response shape without importing the
+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
+`apps/server/public/openapi-sdk.json`. Regenerate it after a server API change:
+
+```bash
+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 |
+| --- | --- |
+| `@fzgame/sdk` | Client, errors, header names, generated types. No React. |
+| `@fzgame/sdk/react` | `SDKInitializer`. Requires React 18.2 or 19. |
+| `@fzgame/sdk/package.json` | The manifest, for tooling that reads it. |
+
+Both entries ship ESM and CommonJS, each with matching type declarations.
+
+## Development
+
+```bash
+pnpm --filter @fzgame/sdk check-types
+pnpm --filter @fzgame/sdk test:run
+pnpm --filter @fzgame/sdk build
+pnpm --filter @fzgame/sdk smoke   # packs the tarball and consumes it from CJS and ESM
+```
+
+## License
+
+ISC