@fzgame/sdk 0.0.0-stage → 0.1.0

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,139 @@
-# 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.
+
+## 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 type { components, paths } from '@fzgame/sdk'
+
+type App = components['schemas']['App']
+type GameInstanceId = paths['/sdk/game-instances/{id}']['get']['parameters']['path']['id']
+```
+
+`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.
+
+## 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