scorezilla 0.1.0-next.0

package/API.md

@@ -0,0 +1,305 @@
+# Scorezilla SDK — API Reference
+
+> **Status:** v0.1.0 (public-key client). The HMAC server adapter
+> (`scorezilla/server`) ships in v0.2.0; React adapter in v0.3.0; Phaser in
+> v0.4.0. See [CHANGELOG.md](./CHANGELOG.md) and
+> [VERSIONING.md](./VERSIONING.md) for the release timeline and stability
+> guarantees.
+
+## Quick start
+
+```ts
+import { Scorezilla } from 'scorezilla';
+
+const sz = new Scorezilla({ publicKey: 'pk_mygame_aBcDeF…' });
+
+const r = await sz.submitScore({
+  boardId: 'board-uuid',
+  playerId: 'player-uuid',
+  score: 9001,
+});
+console.log(r.rank, r.isPersonalBest);
+```
+
+## Configuration
+
+The constructor takes a `ScorezillaConfig`. Pass `publicKey` for client-side
+use; the SDK throws if you pass `secretKey` (use the `scorezilla/server` adapter
+from v0.2.0).
+
+```ts
+interface BaseConfig {
+  /** API base URL. Defaults to `https://api.scorezilla.dev`. */
+  baseUrl?: string;
+  /** Custom fetch (node-fetch, undici, mock). Defaults to globalThis.fetch. */
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  /** Per-request timeout in ms. Default 30 000. */
+  timeoutMs?: number;
+  /** Maximum retry attempts on transient failures. Default 2. */
+  maxRetries?: number;
+  /** Override the default User-Agent header. */
+  userAgent?: string;
+}
+
+type PublicKeyConfig = BaseConfig & { publicKey: string; secretKey?: never };
+
+type ScorezillaConfig = PublicKeyConfig /* | SecretKeyConfig — v0.2.0 */;
+```
+
+### Key format
+
+- `publicKey`: `pk_<game-slug>_<base62-suffix>`. Issued by the operator
+  dashboard. Safe to embed in browser code.
+- `secretKey` (v0.2.0+): `{ id: string, secret: 'sk_live_…' }`. Server-side
+  only. Used to compute HMAC signatures for the secure path.
+
+### Mutual exclusivity
+
+Passing both `publicKey` and `secretKey` is a TypeScript error. Passing neither
+throws at runtime.
+
+## Methods
+
+All methods are `async` and return parsed, typed responses on success. Every
+failure path — HTTP non-2xx, network error, timeout, abort, JSON parse error —
+throws a single error type, [`ScorezillaError`](#errors).
+
+### `submitScore`
+
+`POST /v1/boards/:boardId/scores`. Submits a score for a player. The API
+authoritatively decides if the new score is a personal best.
+
+```ts
+interface SubmitScoreInput {
+  boardId: string;
+  playerId: string; // ← The only accepted key (no `player` alias).
+  score: number; // Finite. NaN / Infinity rejected as invalid_input.
+  metadata?: Record<string, unknown>; // ≤ 4 KB UTF-8, JSON-serializable.
+}
+
+interface SubmitScoreResponse {
+  ok: true;
+  boardId: string;
+  keyId: string; // The publicKey ID that authorized the submission.
+  rank: number; // 1-based, after the submit settles.
+  totalEntries: number;
+  isPersonalBest: boolean;
+}
+
+const r = await sz.submitScore({
+  boardId: 'board-uuid',
+  playerId: 'alice',
+  score: 9001,
+  metadata: { level: 'hard', completionMs: 27_400 },
+});
+if (r.isPersonalBest) {
+  console.log(`New PB! Rank ${r.rank} of ${r.totalEntries}`);
+}
+```
+
+#### Metadata constraints
+
+- Must be a **plain object** (arrays / primitives / null rejected).
+- Values must be JSON-serializable: no `function`, `symbol`, or `bigint`.
+- No circular references.
+- ≤ **4096 UTF-8 bytes** when JSON-stringified (the byte count is what matters —
+  emoji weigh ~4 bytes each).
+
+Violations throw a plain `Error` (not `ScorezillaError`) before any network call
+— these are caller bugs, not API failures.
+
+#### Errors
+
+| Code                             | Status | Meaning                                                                                                                         |
+| -------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `unauthorized`                   | 401    | Invalid `publicKey`.                                                                                                            |
+| `forbidden`                      | 403    | Key is not bound to this `boardId`.                                                                                             |
+| `not_found`                      | 404    | Board doesn't exist.                                                                                                            |
+| `out_of_bounds`                  | 422    | Score outside the board's `[minScore, maxScore]`. `error.reason` is `'below_min'` or `'above_max'`; `error.bound` is the limit. |
+| `rate_limited`                   | 429    | Throttled. `error.retryAfter` (seconds), `error.layer`.                                                                         |
+| `invalid_input` / `invalid_json` | 400    | Malformed body.                                                                                                                 |
+| `network_error`                  | 0      | Could not reach the API.                                                                                                        |
+| `timeout`                        | 0      | Request exceeded `timeoutMs`.                                                                                                   |
+| `aborted`                        | 0      | Caller-provided `AbortSignal` fired.                                                                                            |
+
+### `getLeaderboard`
+
+`GET /v1/boards/:boardId/leaderboard?top=&offset=`.
+
+```ts
+interface GetLeaderboardInput {
+  boardId: string;
+  top?: number; // API caps at 1000; default 100.
+  offset?: number; // API caps at 1_000_000; default 0.
+}
+
+interface LeaderboardResponse {
+  ok: true;
+  boardId: string;
+  offset: number;
+  limit: number;
+  entries: RankedEntry[];
+}
+
+interface RankedEntry {
+  rank: number; // 1-based.
+  playerId: string;
+  score: number;
+  submittedAt: number; // Milliseconds since epoch.
+  metadata?: Record<string, unknown>;
+}
+
+const { entries } = await sz.getLeaderboard({ boardId, top: 25 });
+for (const e of entries) console.log(`${e.rank}. ${e.playerId}: ${e.score}`);
+```
+
+### `getPlayerRank`
+
+`GET /v1/boards/:boardId/players/:playerId/rank`. Returns 404 (`not_found`) if
+the player has no submission yet.
+
+```ts
+interface GetPlayerRankInput {
+  boardId: string;
+  playerId: string;
+}
+
+interface PlayerRankResponse {
+  ok: true;
+  boardId: string;
+  playerId: string;
+  rank: number;
+  score: number;
+  submittedAt: number;
+  totalEntries: number;
+}
+```
+
+### `getWindowAround`
+
+`GET /v1/boards/:boardId/players/:playerId/window?before=&after=`. Returns the
+slice of entries surrounding a player.
+
+```ts
+interface GetWindowAroundInput {
+  boardId: string;
+  playerId: string;
+  before?: number; // API caps at 100; default 5.
+  after?: number; // API caps at 100; default 5.
+}
+
+interface WindowAroundResponse {
+  ok: true;
+  boardId: string;
+  playerId: string;
+  before: number;
+  after: number;
+  entries: RankedEntry[];
+}
+```
+
+## Errors
+
+The SDK throws a single error type, `ScorezillaError`, for every failure mode.
+
+```ts
+class ScorezillaError extends Error {
+  /** HTTP status of the response, or 0 for network/abort/timeout. */
+  readonly status: number;
+  /** Machine-stable code — see the table above. */
+  readonly code: ScorezillaErrorCode;
+  /** Sub-classifier — present on out_of_bounds (`below_min`/`above_max`). */
+  readonly reason: string | undefined;
+  /** Seconds — present on rate_limited (also Retry-After header). */
+  readonly retryAfter: number | undefined;
+  /** Server-issued request ID for support tickets. */
+  readonly requestId: string | undefined;
+  /** Bound that was crossed — present on out_of_bounds. */
+  readonly bound: number | undefined;
+  /** Which rate-limit layer fired — present on rate_limited. */
+  readonly layer: string | undefined;
+  /** Underlying cause (TypeError, DOMException, …) for transport failures. */
+  readonly cause: unknown;
+
+  isRateLimited(): boolean;
+  isAuth(): boolean; // unauthorized OR forbidden
+  isNotFound(): boolean;
+  isOutOfBounds(): boolean;
+  isTransient(): boolean; // network_error, timeout, 5xx, 429
+}
+```
+
+### Branching pattern
+
+**Always branch on `code`** — `message` is English-only and NOT part of the
+SemVer contract (a minor release may reword any text).
+
+```ts
+try {
+  await sz.submitScore({ boardId, playerId, score });
+} catch (e) {
+  if (!(e instanceof ScorezillaError)) throw e;
+
+  if (e.isRateLimited()) {
+    await sleep(e.retryAfter! * 1000);
+    return retry();
+  }
+  if (e.code === 'out_of_bounds') {
+    console.warn(`Score outside ${e.reason} bound (limit ${e.bound})`);
+    return;
+  }
+  if (e.isAuth()) {
+    throw new Error('SDK is misconfigured — bad publicKey');
+  }
+  throw e;
+}
+```
+
+## Advanced
+
+### Custom fetch / polyfills
+
+```ts
+import fetch from 'node-fetch';
+const sz = new Scorezilla({ publicKey, fetch });
+```
+
+The signature is intentionally broader than `typeof fetch` so `node-fetch`,
+`undici`, `vi.fn()`, and other polyfills typecheck cleanly.
+
+### AbortController
+
+Every method accepts the SDK's internal abort signal. To cancel from your own
+code, configure a global `signal` on construction — TODO in v0.2.x; for v0.1.0,
+set a short `timeoutMs` per construction.
+
+### Idempotency keys
+
+Every `POST` (i.e., `submitScore`) gets an automatic `Idempotency-Key` header
+(UUID v4). The same key is reused across the SDK's internal retry attempts, so
+server-side dedup (when added) is safe by default.
+
+To control idempotency across your own retry loop, pass a fixed
+`Idempotency-Key` via the `headers` field of `RequestOptions` — TODO public on
+the client class in a follow-up release.
+
+### Custom User-Agent
+
+```ts
+const sz = new Scorezilla({
+  publicKey,
+  userAgent: 'my-game/2.0',
+});
+```
+
+Note: browsers silently ignore the `User-Agent` header per the Fetch spec. The
+SDK also sets `X-Scorezilla-Client` (which browsers do honor) to the same value
+for cross-runtime telemetry parity.
+
+## See also
+
+- [README.md](./README.md) — install + quickstart
+- [VERSIONING.md](./VERSIONING.md) — SemVer contract + deprecation policy
+- [CHANGELOG.md](./CHANGELOG.md) — release history
+- [Scorezilla operator dashboard](https://dashboard.scorezilla.dev) — manage
+  games + keys

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.1.0-next.0
+
+### Minor Changes
+
+- [`239642a`](https://github.com/isco-tec/scorezilla-js/commit/239642aaf73f643c2f51d806170d3ced31a3fe68) Thanks [@isco-tec](https://github.com/isco-tec)! - **Initial public release candidate.** First publish of the `scorezilla` SDK to npm.
+
+  Includes the v0.1.0 public-key client surface:
+  - `Scorezilla` class with `submitScore`, `getLeaderboard`, `getPlayerRank`, `getWindowAround`
+  - `ScorezillaError` for every failure path (network, timeout, abort, HTTP non-2xx)
+  - Universal runtime support (browsers, Node ≥ 20, Cloudflare Workers, Bun, Deno)
+  - Automatic retries with idempotency keys
+  - Dual ESM/CJS build with [arethetypeswrong](https://arethetypeswrong.github.io/)-clean exports map
+  - ~3.8 KB ESM gzipped
+
+  This RC publishes under the `next` npm dist-tag — install with `npm install scorezilla@next` to try it out. The HMAC server adapter, React hooks, and Phaser plugin land in subsequent v0.2.0, v0.3.0, and v0.4.0 releases.
+
+All notable changes to `scorezilla` are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/). Releases are
+managed by [Changesets](https://github.com/changesets/changesets) — see
+[VERSIONING.md](./VERSIONING.md) for the SemVer contract, deprecation policy,
+and the 0.x → 1.0 exit criteria.

package/COMPATIBILITY.md

@@ -0,0 +1,170 @@
+# Compatibility
+
+Where the Scorezilla SDK runs, what it needs, what it sends, and what it does
+not.
+
+## Runtime support
+
+The SDK targets ES2022 + the standard `fetch` / `AbortController` /
+`crypto.randomUUID` web platform APIs. Anywhere those are available, the SDK
+works.
+
+| Runtime                | Status        | Notes                                                                                                                                                                                             |
+| ---------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Node**               | ≥ 20 (hard)   | Native `fetch` since Node 18.0; `crypto.randomUUID` since Node 14.17. We require Node 20 to inherit the modern Web Crypto profile.                                                                |
+| **Browsers**           | All evergreen | Native `fetch` since 2017; `crypto.randomUUID` since Safari 15.4, Firefox 95, Chrome 92. **Safari 17.0–17.3** is supported despite lacking `AbortSignal.any` — the SDK composes signals manually. |
+| **Cloudflare Workers** | Supported     | Detected via `navigator.userAgent === 'Cloudflare-Workers'`. No Node-only API used.                                                                                                               |
+| **Bun**                | ≥ 1.0         | Bun ≥ 1.0 ships compatible fetch + WebCrypto. CI runs Bun as a best-effort matrix until v0.2.0 (see VERSIONING.md).                                                                               |
+| **Deno**               | ≥ 1.40        | Native fetch + Web Crypto.                                                                                                                                                                        |
+| **React Native**       | Unverified    | The standard `fetch` polyfill ships with RN ≥ 0.60, but `crypto.randomUUID` typically requires `react-native-get-random-values`. Not part of the v0.1.0 CI matrix.                                |
+
+### Minimum API version
+
+The SDK talks to `/v1/*` only. The base URL defaults to
+`https://api.scorezilla.dev`; pass `baseUrl` to override (e.g. for a local
+`wrangler dev` instance during development).
+
+The SDK does not negotiate API versions — it speaks `/v1` literally. When `/v2`
+ships, a major-bumped SDK will accept a new `apiVersion: '2'` knob.
+
+## TypeScript
+
+### Compiler version
+
+TypeScript ≥ 4.7 (for the modern `node16`/`bundler` `moduleResolution`). The
+SDK's published types include a `typesVersions` fallback for ≤ 4.6's `node10`
+resolver, so `import { Scorezilla } from 'scorezilla'` resolves cleanly under
+both algorithms.
+
+### `exactOptionalPropertyTypes`
+
+The SDK is built with `exactOptionalPropertyTypes: true`. The PUBLIC input types
+use `?: T | undefined` (with explicit `| undefined`) on optional fields
+specifically so callers under the same setting can pass a maybe-undefined
+variable without a workaround:
+
+```ts
+// Works under exactOptionalPropertyTypes: true thanks to `| undefined`.
+const meta: Record<string, unknown> | undefined = computeMeta();
+await sz.submitScore({ boardId, playerId, score, metadata: meta });
+```
+
+If you're consuming the SDK from a project that does NOT use
+`exactOptionalPropertyTypes`, this is fully transparent — the union collapses to
+just `T?` for you.
+
+### The spread workaround (for the rare strict consumer)
+
+If you find yourself with a value typed `T` (not `T | undefined`) inside a
+strict object you want to spread into a Scorezilla input, use object spread
+rather than property assignment:
+
+```ts
+// Don't:
+const input: SubmitScoreInput = {
+  boardId,
+  playerId,
+  score,
+  metadata: someStrictMeta as Record<string, unknown>, // cast
+};
+
+// Do:
+const input: SubmitScoreInput = {
+  boardId,
+  playerId,
+  score,
+  ...(someStrictMeta ? { metadata: someStrictMeta } : {}),
+};
+```
+
+The conditional spread keeps the `metadata` key absent (rather than
+present-with-`undefined`) when the value isn't ready — matching what the strict
+type system expects.
+
+## Custom fetch / polyfills
+
+`cfg.fetch` accepts any function with the shape
+`(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>`. This is
+intentionally broader than `typeof fetch` so common polyfills and test stubs
+typecheck cleanly:
+
+```ts
+import fetch from 'node-fetch';
+import { Scorezilla } from 'scorezilla';
+const sz = new Scorezilla({ publicKey, fetch });
+```
+
+Polyfill compatibility:
+
+- [`node-fetch`](https://www.npmjs.com/package/node-fetch) ≥ 3 — typechecks
+  against the SDK's `FetchImpl`; functional smoke-test in the SDK's own unit
+  suite.
+- [`undici`](https://www.npmjs.com/package/undici) — typechecks; not exercised
+  in CI but its native fetch matches the contract.
+- `vi.fn()` (Vitest) — used throughout the SDK's own 171-test suite.
+- `jest.fn()` — same shape as `vi.fn()`, expected to work but not currently
+  exercised in CI. File an issue if you hit a mismatch.
+
+## Bundle sizes
+
+| Bundle           | Format | Gzipped |
+| ---------------- | ------ | ------- |
+| `dist/index.js`  | ESM    | ~3.8 KB |
+| `dist/index.cjs` | CJS    | ~4.0 KB |
+
+These numbers come from `size-limit` simulating a consumer's bundler. Source
+maps ship alongside but aren't counted against the budget. The CI gate caps the
+bundle at 6 KB gzipped.
+
+## What the SDK does NOT do
+
+The SDK is deliberately minimal in side-effects and identifiers.
+
+### No fingerprinting
+
+`detectRuntime()` probes only `globalThis.Bun`, `globalThis.Deno`,
+`globalThis.process.versions.node`, `globalThis.document`, and a single specific
+string check on `navigator.userAgent` (`'Cloudflare-Workers'`). No other
+browser, hardware, locale, or timezone signal is read.
+
+### No cookies, no localStorage, no IndexedDB
+
+The SDK does not set cookies, write to `localStorage` / `sessionStorage` /
+`IndexedDB`, or use any persistent client storage. The `playerId` you pass is
+the only identifier the SDK transmits; it never generates or stores one on your
+behalf.
+
+### No analytics calls
+
+The SDK sends `POST` and `GET` requests only to the configured `baseUrl`. It
+does not phone home, report errors externally, or fetch from any other origin.
+
+### No console writes during normal operation
+
+The SDK throws `ScorezillaError` for failures rather than logging. The sole
+intentional `console.warn` site is the deprecation-warning machinery described
+in [VERSIONING.md](./VERSIONING.md), which fires at most once per deprecated
+symbol per process and can be suppressed.
+
+### No automatic retries on caller errors
+
+4xx responses (except 429) are surfaced verbatim. The retry loop only fires on
+5xx, 429, and network-level errors — exactly the conditions where re-attempt is
+idempotent and reasonable.
+
+## Privacy invariants summary
+
+For your `<privacy-policy>` if you embed the SDK:
+
+> The Scorezilla SDK transmits the player identifier and metadata you provide,
+> with the API requests you instruct it to send. It does not read browser
+> fingerprinting signals beyond a single runtime-detection probe; does not write
+> cookies, local storage, or any other persistent data; and does not contact any
+> origin besides the one you configure via `baseUrl`.
+
+## See also
+
+- [README.md](./README.md)
+- [API.md](./API.md)
+- [VERSIONING.md](./VERSIONING.md)
+- [CHANGELOG.md](./CHANGELOG.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 isco-tec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.