scorezilla 0.1.0-next.3 → 0.3.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,189 @@
 # Changelog
 
+## 0.3.0-next.0
+
+### Minor Changes
+
+- [#36](https://github.com/isco-tec/scorezilla-js/pull/36) [`19c2dcc`](https://github.com/isco-tec/scorezilla-js/commit/19c2dcc14d2000551d80498813b075172c8f4d66) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(identity): preset helpers for `scorezilla/identity` (Phase 1)
+
+  New subpath export: `scorezilla/identity`. Three identity-strategy
+  presets ship as `stable`; one OAuth helper ships as a preview stub.
+
+  **Stable in this release:**
+  - `useAnonymousPlayer({ storageKey })` — generates a UUID, persists in
+    localStorage, same browser keeps the same id across reloads. Returns
+    `{ id, forget() }`. Privacy-safe by default (no PII).
+  - `usePromptedPlayer({ storageKey, prompt })` — `window.prompt()` on
+    first run, persists to localStorage. Returns `{ id, forget() } | null`
+    (null when SSR, no `prompt`, or user cancels).
+  - `useServerAuthoritative()` — no-op marker for snippets using the
+    HMAC-signed secure path (`scorezilla/server`). The browser SDK does
+    no identity work; the server picks the value.
+
+  **Preview stub in this release (throws on call):**
+  - `useAuthProvider({ provider: 'google' | 'github' })` — OAuth-backed
+    identity. Full implementation (Google + GitHub for v1) ships in a
+    follow-up `next` release before the 0.3.0 latest promote.
+
+  Per [ADR 0003](https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md). All helpers document where data is stored and
+  what `forget()` / `signOut()` does NOT do (server-side history is
+  retained — call admin delete-player for full erasure).
+
+  Closes upstream tracking issue isco-tec/scorezilla#125 (Phase 1).
+
+## 0.2.0 — `scorezilla/server` HMAC adapter GA
+
+### Minor Changes
+
+- [#25](https://github.com/isco-tec/scorezilla-js/pull/25) [`5f7025b`](https://github.com/isco-tec/scorezilla-js/commit/5f7025b7b06dded92b3e710316454eb8c891d053) Thanks [@isco-tec](https://github.com/isco-tec)! - **`scorezilla/server`: HMAC requests now bind to the target host (v=2).**
+
+  The canonical signing string includes the host of the request URL, so a signature minted against staging cannot be replayed against prod (or any other origin that happens to share key material). SigV4 has had this since day one; closing the gap before MCP locks the format.
+
+  Wire format change:
+
+  ```
+  Authorization: Scorezilla-HMAC-SHA256 keyId=…, ts=…, nonce=…, signature=…, v=2
+  ```
+
+  The `v=2` parameter is new. The canonical signing string now has six lines instead of five — `host` is inserted between `METHOD` and `pathAndQuery`, lowercased per RFC 9110 §4.2.4.
+
+  **Backward compatibility.** The API verifier still accepts v=1 (no `v=` field, no host binding) during the rollout window — your existing pre-next.3 SDK builds will keep working until v=1 is deprecated. The SDK itself, however, emits v=2 unconditionally from next.3 onwards. If you've forked or wrapped `buildHmacAuthHeader` / `buildSigningString`, you'll need to thread a `host` parameter through.
+
+  **For consumers of `Scorezilla` from `scorezilla/server`:** no API changes. The constructor derives `host` from `baseUrl` automatically. As an added safety net, an invalid `baseUrl` now throws at construction time rather than producing 401 mismatches at every request.
+
+  **For low-level consumers of `buildSigningString` / `buildHmacAuthHeader`:** a new `host` parameter is now required. The latter also accepts an optional `version: 1 | 2` for explicit backward-compat scenarios.
+
+- [`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.
+
+- [#18](https://github.com/isco-tec/scorezilla-js/pull/18) [`a02b07a`](https://github.com/isco-tec/scorezilla-js/commit/a02b07a116a9d15c2928ad4f98a9cfa3a8dceffd) Thanks [@isco-tec](https://github.com/isco-tec)! - **v0.2.0 — HMAC server adapter (`scorezilla/server`).** Closes [#17](https://github.com/isco-tec/scorezilla-js/issues/17).
+
+  The new `scorezilla/server` subpath ships an HMAC-SHA256 signing client for
+  game backends that need cheat-resistant submissions. The browser-side
+  public-key client (`scorezilla`) is unchanged.
+
+  ```ts
+  import { Scorezilla } from 'scorezilla/server';
+
+  const sz = new Scorezilla({
+    secretKey: {
+      id: process.env.SCOREZILLA_KEY_ID,
+      secret: process.env.SCOREZILLA_KEY_SECRET, // never ship to a browser
+    },
+  });
+
+  await sz.submitScore({ boardId, playerId, score, metadata });
+  await sz.getLeaderboard({ boardId, top });
+  await sz.getPlayerRank({ boardId, playerId });
+  await sz.getWindowAround({ boardId, playerId, before, after });
+  ```
+
+  Behavior:
+  - Each request is signed with HMAC-SHA256 over a canonical
+    `{ts}\n{nonce}\n{METHOD}\n{path?query}\n{sha256_hex(body)}` string and
+    delivered via `Authorization: Scorezilla-HMAC-SHA256 keyId=…, ts=…,
+nonce=…, signature=…`. Matches the API's verifier byte-for-byte.
+  - `submitScore` posts to `/v1/secure/scores` (the boardId moves into the
+    body — the public-key endpoint at `/v1/boards/:id/scores` is unchanged).
+  - Read methods (`getLeaderboard` / `getPlayerRank` / `getWindowAround`)
+    hit the same paths as the public-key client.
+  - Every retry attempt regenerates `(ts, nonce)` so server-side replay
+    protection (10-minute nonce window) doesn't trip.
+  - Importing `scorezilla/server` from a browser bundle throws at module
+    evaluation — the `sk_live_*` secret never reaches client-side code.
+
+  Same `ScorezillaError` surface (`isRateLimited()`, `isAuth()`,
+  `isTransient()`, `code`, `requestId`, etc.) — typed catch patterns
+  written for v0.1 work unchanged.
+
+  Bundle: ~3.84 KB ESM gzipped, ~4.04 KB CJS gzipped — well under the
+  6 KB per-entry cap.
+
+- [#23](https://github.com/isco-tec/scorezilla-js/pull/23) [`5163e31`](https://github.com/isco-tec/scorezilla-js/commit/5163e3130ac208d591b026d66870ce5a194f90b6) Thanks [@isco-tec](https://github.com/isco-tec)! - **`scorezilla/server` adopts a single-token secret-key format.** Breaking
+  change vs. v0.1.0-next.1; we're still in pre-release so this is permitted.
+
+  Before (v0.1.0-next.1):
+
+  ```ts
+  new Scorezilla({
+    secretKey: { id: 'sk-id-uuid', secret: 'sk_live_xxxxx' },
+  });
+  ```
+
+  After (v0.1.0-next.2):
+
+  ```ts
+  new Scorezilla({
+    secretKey: 'sk_live_<keyId>_xxxxx', // one self-contained token
+  });
+  ```
+
+  The keyId is embedded in the secret string itself; the SDK parses it
+  out via `/^sk_live_([0-9a-f]{8}-...)_/` before signing. The HMAC key
+  remains the WHOLE plaintext. Wire format on the Authorization header
+  is unchanged. API verification is unchanged.
+
+  Rationale: matches Stripe's design and the public-key client's
+  single-string shape. One value to copy from the dashboard, one to
+  manage in env config, one to pass into the constructor. Previously
+  users had to manage two distinct values (`id` AND `secret`) which
+  created confusion — they're functionally one credential.
+
+  **To upgrade**: issue (or rotate) a fresh secret key in the dashboard.
+  Old-format keys (no embedded keyId) are rejected by the SDK with a
+  clear error message pointing at the migration path.
+
+- [#30](https://github.com/isco-tec/scorezilla-js/pull/30) [`39fc70f`](https://github.com/isco-tec/scorezilla-js/commit/39fc70fa3a38bce619e87aa9f6179e79f1ae45ff) Thanks [@isco-tec](https://github.com/isco-tec)! - Handle HTTP 402 `usage_cap_exceeded` + observe API deprecation headers.
+
+  **402 / `usage_cap_exceeded`**: when the server returns 402 (tenant hit
+  their monthly submission cap or is suspended), the SDK now surfaces a
+  typed `ScorezillaError` with the full cap context:
+  - `err.code === 'usage_cap_exceeded'`
+  - `err.reason === 'over_cap' | 'suspended'`
+  - `err.tier`, `err.cap`, `err.count`, `err.period`, `err.resetsAt`
+  - `err.isUsageCapExceeded()` predicate
+  - `err.isSuspended()` predicate (distinguishes the suspended sub-case)
+  - `err.isTransient() === false` — no auto-retry (the cap doesn't lift
+    until `resetsAt`)
+
+  **Deprecation signals**: when an API response carries an RFC 8594
+  `Sunset` header or IETF `Deprecation` header, the SDK now logs a
+  once-per-process `console.warn` so developers see deprecation
+  notices during dev without prod-loop spam. The warning includes the
+  sunset date and any `Link: rel="deprecation"` documentation URL.
+
+  No breaking changes. New fields are additive; existing error handling
+  keeps working unchanged.
+
+### Patch Changes
+
+- [#31](https://github.com/isco-tec/scorezilla-js/pull/31) [`9376a2d`](https://github.com/isco-tec/scorezilla-js/commit/9376a2d93d4edb42decca1bcf495b83fc013c309) Thanks [@isco-tec](https://github.com/isco-tec)! - **Error mapping, retry-policy alignment, `AbortSignal` plumbing, injectable warn, validator-return tightening.**
+
+  Bundled correctness + ergonomics fixes from the in-house improvement-phase review:
+  - `ScorezillaError.code` now resolves to `'conflict'` on HTTP 409 responses (previously fell through to `'invalid_input'`). The error type already listed `'conflict'` as a valid code; the gap was in the status→code mapper. A new `e.isConflict()` predicate joins the existing `isAuth() / isNotFound() / isRateLimited() / isOutOfBounds() / isUsageCapExceeded() / isTransient()` family.
+  - `e.isTransient()` no longer flags `timeout` or `aborted` as transient — those are caller-observable terminal states, not retryable. The predicate is now aligned with the transport's actual retry policy (`shouldRetryError` in `retry.ts`), so consumer code mirroring "if (e.isTransient()) retry()" no longer loops on timeouts.
+  - All four public methods on **both** the public-key client (`Scorezilla`) and the secret-key server adapter (`Scorezilla` from `scorezilla/server`) now accept an optional `signal?: AbortSignal` via a shared `CancellableInput` shape, and forward it through the transport. Unblocks request-cancellation propagation under frameworks that thread cancellation through the request lifecycle (Next.js route handlers, Hono, Express middleware, React effect cleanup).
+  - New `warn?: (...args: unknown[]) => void` field on `ScorezillaConfig`. Defaults to `console.warn`. Pass your logger to route SDK deprecation notices into your observability stack, or pass `() => {}` to suppress them. Used today only for the `Deprecation` / `Sunset` once-per-process warning emitted when the API signals an upcoming sunset — at million-integration scale, embedders shouldn't have to console-filter our messages.
+  - `validateMetadata` now returns the serialized JSON string it computed (previously declared `void` despite a comment that claimed otherwise). Public callers that re-stringify metadata can reuse the value and skip a duplicate `JSON.stringify` pass on the hot submit path.
+
+  No breaking changes for callers that didn't rely on the two buggy classifications, didn't need cancellation, and didn't read `validateMetadata`'s return value.
+
+- [#28](https://github.com/isco-tec/scorezilla-js/pull/28) [`94b39d2`](https://github.com/isco-tec/scorezilla-js/commit/94b39d2e67ec7bba2681145560529f058acfc633) Thanks [@isco-tec](https://github.com/isco-tec)! - **Pre-release security hardening pass.** Three issues surfaced by a focused security review before the first public release of `scorezilla/server`:
+  - **HIGH — nonce injection.** `buildHmacAuthHeader` now requires injected nonces to be at least 16 characters. The default path (`crypto.randomUUID()`) is unaffected. Previously a misconfigured caller could pass `nonce: ''` and silently sign a header with no replay protection — the server has no minimum-length check, so the API would accept it. Now caught at SDK build-time with a clear error.
+  - **HIGH — server policy disclosure.** `HMAC_TIMESTAMP_WINDOW_SECONDS = 300` was previously exported as documentation of the API's clock-skew tolerance. Removed from the public API — publishing the server's replay-protection window in the SDK's types was unnecessary information disclosure and narrowed the pre-computation window for any future timestamp-forgery work. The SDK has no behavioral dependency on the value (it always emits a fresh `ts = floor(Date.now() / 1000)`).
+  - **MEDIUM — `EdgeRuntime` polyfill bypass.** The server adapter's runtime browser-guard previously trusted `globalThis.EdgeRuntime` as a "this is a server" signal. A browser extension or bundler misconfig setting that global would have bypassed the guard. Removed from the trusted set — the package's `exports.browser` condition remains the primary gate, and the runtime check now refuses to trust globals that can be polyfilled from a browser context. Real Vercel Edge runtimes still pass the guard because they don't have `window`/`document`.
+
+  No external-attack surface was exploitable; all three are self-inflicted/defense-in-depth issues caught before the first stable release. Tests added: 4 for nonce validation (rejects empty / too-short, accepts at-floor / default UUID), 1 for the EdgeRuntime polyfill scenario.
+
 ## 0.1.0-next.3
 
 ### Minor Changes

package/README.md

@@ -43,6 +43,19 @@ yarn add scorezilla
 bun add scorezilla
 ```
 
+## Get your keys
+
+The Quickstart below needs two values: a `publicKey` and a `boardId`. Both come from the dashboard:
+
+1. **Sign in** at [dashboard.scorezilla.dev](https://dashboard.scorezilla.dev) (magic-link email — no password).
+2. **Open the Tutorial Game** that's created for you on first sign-in (or create a new game).
+3. **Open Keys → Issue public key**. Copy the `pk_*` string (shown once — also visible in the keys list afterwards).
+4. **Open Boards → New board** (or use the auto-created "High Scores"). Copy the `boardId` UUID.
+
+You're now ready for the Quickstart below. **Public keys are safe to ship in client code** — they only authorize submits, not key rotation or board admin.
+
+> Using AI to scaffold? Skip the manual steps: install the [Scorezilla MCP server](https://github.com/isco-tec/scorezilla-mcp) in Claude Code / Cursor and run `bootstrap_leaderboard` — the AI gets your keys + board id + a ready-to-paste integration snippet in one tool call.
+
 ## Quickstart
 
 ```ts

package/dist/{errors-CUAQsaVS.d.cts → errors-B7hyC-C5.d.cts}

@@ -37,6 +37,13 @@ interface BaseConfig {
      *  this unset to use the default exponential backoff with jitter.
      *  @internal */
     sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Inject a sink for SDK deprecation warnings. Defaults to
+     *  `console.warn`. Pass your logger's `warn` to route SDK signals into
+     *  the rest of your observability stack, or pass `() => {}` to
+     *  suppress them. The SDK uses this ONLY for developer-visible
+     *  deprecation notices triggered by `Deprecation` / `Sunset` response
+     *  headers — never for runtime errors. */
+    warn?: (...args: unknown[]) => void;
 }
 /** Public-key auth: browser-safe path. The key is fingerprinted to a game
  *  on the server side via `pk_<gameSlug>_<base62>`. */
@@ -86,9 +93,22 @@ type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
  *
  * @stable v0.1.0
  */
-type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error'
+/** 402 Payment Required — tenant exceeded their monthly submission cap, OR
+ *  the tenant is `'suspended'` (see {@link UsageCapReason}). The error body
+ *  carries `tier`, `cap`, `count`, `period`, `resetsAt`. */
+ | 'usage_cap_exceeded' | (string & {});
 /** Reason sub-classifier on `out_of_bounds` errors. Open union — see {@link ScorezillaErrorCode}. */
 type OutOfBoundsReason = 'below_min' | 'above_max' | (string & {});
+/** Reason sub-classifier on `usage_cap_exceeded` errors.
+ *  - `'over_cap'`   — tenant hit their tier's monthly submit limit
+ *  - `'suspended'`  — tenant's `billing_status` is `'suspended'`; every
+ *                     submit is rejected (cap is structurally 0)
+ *  Open union for forward compatibility.
+ */
+type UsageCapReason = 'over_cap' | 'suspended' | (string & {});
+/** Tier identifier mirrored from the server's `PlanConfig.key`. */
+type BillingTier = 'free' | 'indie' | 'pro' | 'studio' | 'enterprise' | 'suspended' | (string & {});
 /** Successful API response envelope. The `T` is the per-route payload. */
 type ApiSuccess<T> = {
     ok: true;
@@ -107,6 +127,21 @@ interface ApiError {
     layer?: string;
     /** The limit value that was crossed — present on `out_of_bounds`. */
     bound?: number;
+    /** Tenant's tier at the time of rejection. */
+    tier?: BillingTier;
+    /** The cap value that was crossed (monthly submit limit). `0` for
+     *  suspended tenants; `null` is never sent (enterprise has no cap and
+     *  can never be over). */
+    cap?: number;
+    /** The post-increment submit count when the cap was crossed. Always
+     *  > `cap` when `reason === 'over_cap'`. */
+    count?: number;
+    /** The period the count belongs to, in `YYYY-MM` UTC form. */
+    period?: string;
+    /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+     *  when the counter resets. Lets clients compute `Retry-After` without
+     *  parsing dates server-side. */
+    resetsAt?: string;
 }
 /** Discriminated envelope: every API response is one of these two shapes. */
 type ApiResponse<T> = ApiSuccess<T> | ApiError;
@@ -230,9 +265,11 @@ declare class ScorezillaError extends Error {
      *  {@link ScorezillaErrorCode}. For network errors, this is `'network_error'`;
      *  for aborts, `'aborted'`; for timeouts, `'timeout'`. */
     readonly code: ScorezillaErrorCode;
-    /** Sub-classifier — present on `out_of_bounds` (`'below_min' | 'above_max'`)
+    /** Sub-classifier — present on:
+     *    - `out_of_bounds`: `'below_min' | 'above_max'`
+     *    - `usage_cap_exceeded`: `'over_cap' | 'suspended'`
      *  and possibly other codes in future minor releases. */
-    readonly reason: OutOfBoundsReason | string | undefined;
+    readonly reason: OutOfBoundsReason | UsageCapReason | string | undefined;
     /** Seconds — present on `rate_limited`. Honored by the transport's retry
      *  policy (Step 2.4). */
     readonly retryAfter: number | undefined;
@@ -243,6 +280,20 @@ declare class ScorezillaError extends Error {
     readonly bound: number | undefined;
     /** Which rate-limit layer fired on `rate_limited`. */
     readonly layer: string | undefined;
+    /** Tenant's billing tier — present on `usage_cap_exceeded`. */
+    readonly tier: BillingTier | undefined;
+    /** The cap value crossed on `usage_cap_exceeded`. `0` indicates a
+     *  suspended tenant. `undefined` on all other error codes. */
+    readonly cap: number | undefined;
+    /** The post-increment submit count on `usage_cap_exceeded`. Always
+     *  `> cap` when `reason === 'over_cap'`. */
+    readonly count: number | undefined;
+    /** The period the count belongs to on `usage_cap_exceeded`, in `YYYY-MM`
+     *  UTC form. */
+    readonly period: string | undefined;
+    /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+     *  the counter's natural reset point on `usage_cap_exceeded`. */
+    readonly resetsAt: string | undefined;
     /** The underlying cause (e.g., a `TypeError: fetch failed`) for
      *  network/abort/timeout paths. `undefined` when the error came from a
      *  successfully-parsed API error body. */
@@ -255,19 +306,42 @@ declare class ScorezillaError extends Error {
         requestId?: string | undefined;
         bound?: number | undefined;
         layer?: string | undefined;
+        tier?: BillingTier | undefined;
+        cap?: number | undefined;
+        count?: number | undefined;
+        period?: string | undefined;
+        resetsAt?: string | undefined;
         cause?: unknown;
     });
     /** `true` when this error is a 429 / `rate_limited`. */
     isRateLimited(): boolean;
+    /**
+     * `true` when this error is a 402 / `usage_cap_exceeded`. The tenant
+     * has either hit their tier's monthly submit cap (`reason ===
+     * 'over_cap'`) or is suspended (`reason === 'suspended'`).
+     *
+     * Consumers SHOULD NOT auto-retry on this error — the cap doesn't lift
+     * until `resetsAt`. Surface to the developer with an upgrade prompt
+     * (over_cap) or contact-support message (suspended).
+     */
+    isUsageCapExceeded(): boolean;
+    /** `true` when this error is a 402 + reason 'suspended' (vs over-cap). */
+    isSuspended(): boolean;
     /** `true` when this error is a 401 / `unauthorized` (or 403 / `forbidden`). */
     isAuth(): boolean;
     /** `true` when this error is a 404 / `not_found`. */
     isNotFound(): boolean;
     /** `true` when this error is a 422 / `out_of_bounds` (score below/above board limit). */
     isOutOfBounds(): boolean;
-    /** `true` for transient / retryable conditions: network errors, timeouts,
-     *  5xx, and 429. The transport layer relies on this for its retry policy. */
+    /** `true` for the SDK's retryable conditions: pure network errors, 5xx, and
+     *  429. Deliberately excludes `timeout` and `aborted` — those are caller-
+     *  observable terminal states, not transient. Aligned with `shouldRetryError`
+     *  in `retry.ts` so a consumer mirroring the SDK's retry policy gets the
+     *  same answer the transport does. */
     isTransient(): boolean;
+    /** `true` when this error is a 409 / `conflict` (idempotency-key conflict
+     *  on retry). */
+    isConflict(): boolean;
     /**
      * Build a `ScorezillaError` from a fetch round-trip outcome.
      *

package/dist/{errors-CUAQsaVS.d.ts → errors-B7hyC-C5.d.ts}

@@ -37,6 +37,13 @@ interface BaseConfig {
      *  this unset to use the default exponential backoff with jitter.
      *  @internal */
     sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Inject a sink for SDK deprecation warnings. Defaults to
+     *  `console.warn`. Pass your logger's `warn` to route SDK signals into
+     *  the rest of your observability stack, or pass `() => {}` to
+     *  suppress them. The SDK uses this ONLY for developer-visible
+     *  deprecation notices triggered by `Deprecation` / `Sunset` response
+     *  headers — never for runtime errors. */
+    warn?: (...args: unknown[]) => void;
 }
 /** Public-key auth: browser-safe path. The key is fingerprinted to a game
  *  on the server side via `pk_<gameSlug>_<base62>`. */
@@ -86,9 +93,22 @@ type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
  *
  * @stable v0.1.0
  */
-type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error'
+/** 402 Payment Required — tenant exceeded their monthly submission cap, OR
+ *  the tenant is `'suspended'` (see {@link UsageCapReason}). The error body
+ *  carries `tier`, `cap`, `count`, `period`, `resetsAt`. */
+ | 'usage_cap_exceeded' | (string & {});
 /** Reason sub-classifier on `out_of_bounds` errors. Open union — see {@link ScorezillaErrorCode}. */
 type OutOfBoundsReason = 'below_min' | 'above_max' | (string & {});
+/** Reason sub-classifier on `usage_cap_exceeded` errors.
+ *  - `'over_cap'`   — tenant hit their tier's monthly submit limit
+ *  - `'suspended'`  — tenant's `billing_status` is `'suspended'`; every
+ *                     submit is rejected (cap is structurally 0)
+ *  Open union for forward compatibility.
+ */
+type UsageCapReason = 'over_cap' | 'suspended' | (string & {});
+/** Tier identifier mirrored from the server's `PlanConfig.key`. */
+type BillingTier = 'free' | 'indie' | 'pro' | 'studio' | 'enterprise' | 'suspended' | (string & {});
 /** Successful API response envelope. The `T` is the per-route payload. */
 type ApiSuccess<T> = {
     ok: true;
@@ -107,6 +127,21 @@ interface ApiError {
     layer?: string;
     /** The limit value that was crossed — present on `out_of_bounds`. */
     bound?: number;
+    /** Tenant's tier at the time of rejection. */
+    tier?: BillingTier;
+    /** The cap value that was crossed (monthly submit limit). `0` for
+     *  suspended tenants; `null` is never sent (enterprise has no cap and
+     *  can never be over). */
+    cap?: number;
+    /** The post-increment submit count when the cap was crossed. Always
+     *  > `cap` when `reason === 'over_cap'`. */
+    count?: number;
+    /** The period the count belongs to, in `YYYY-MM` UTC form. */
+    period?: string;
+    /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+     *  when the counter resets. Lets clients compute `Retry-After` without
+     *  parsing dates server-side. */
+    resetsAt?: string;
 }
 /** Discriminated envelope: every API response is one of these two shapes. */
 type ApiResponse<T> = ApiSuccess<T> | ApiError;
@@ -230,9 +265,11 @@ declare class ScorezillaError extends Error {
      *  {@link ScorezillaErrorCode}. For network errors, this is `'network_error'`;
      *  for aborts, `'aborted'`; for timeouts, `'timeout'`. */
     readonly code: ScorezillaErrorCode;
-    /** Sub-classifier — present on `out_of_bounds` (`'below_min' | 'above_max'`)
+    /** Sub-classifier — present on:
+     *    - `out_of_bounds`: `'below_min' | 'above_max'`
+     *    - `usage_cap_exceeded`: `'over_cap' | 'suspended'`
      *  and possibly other codes in future minor releases. */
-    readonly reason: OutOfBoundsReason | string | undefined;
+    readonly reason: OutOfBoundsReason | UsageCapReason | string | undefined;
     /** Seconds — present on `rate_limited`. Honored by the transport's retry
      *  policy (Step 2.4). */
     readonly retryAfter: number | undefined;
@@ -243,6 +280,20 @@ declare class ScorezillaError extends Error {
     readonly bound: number | undefined;
     /** Which rate-limit layer fired on `rate_limited`. */
     readonly layer: string | undefined;
+    /** Tenant's billing tier — present on `usage_cap_exceeded`. */
+    readonly tier: BillingTier | undefined;
+    /** The cap value crossed on `usage_cap_exceeded`. `0` indicates a
+     *  suspended tenant. `undefined` on all other error codes. */
+    readonly cap: number | undefined;
+    /** The post-increment submit count on `usage_cap_exceeded`. Always
+     *  `> cap` when `reason === 'over_cap'`. */
+    readonly count: number | undefined;
+    /** The period the count belongs to on `usage_cap_exceeded`, in `YYYY-MM`
+     *  UTC form. */
+    readonly period: string | undefined;
+    /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+     *  the counter's natural reset point on `usage_cap_exceeded`. */
+    readonly resetsAt: string | undefined;
     /** The underlying cause (e.g., a `TypeError: fetch failed`) for
      *  network/abort/timeout paths. `undefined` when the error came from a
      *  successfully-parsed API error body. */
@@ -255,19 +306,42 @@ declare class ScorezillaError extends Error {
         requestId?: string | undefined;
         bound?: number | undefined;
         layer?: string | undefined;
+        tier?: BillingTier | undefined;
+        cap?: number | undefined;
+        count?: number | undefined;
+        period?: string | undefined;
+        resetsAt?: string | undefined;
         cause?: unknown;
     });
     /** `true` when this error is a 429 / `rate_limited`. */
     isRateLimited(): boolean;
+    /**
+     * `true` when this error is a 402 / `usage_cap_exceeded`. The tenant
+     * has either hit their tier's monthly submit cap (`reason ===
+     * 'over_cap'`) or is suspended (`reason === 'suspended'`).
+     *
+     * Consumers SHOULD NOT auto-retry on this error — the cap doesn't lift
+     * until `resetsAt`. Surface to the developer with an upgrade prompt
+     * (over_cap) or contact-support message (suspended).
+     */
+    isUsageCapExceeded(): boolean;
+    /** `true` when this error is a 402 + reason 'suspended' (vs over-cap). */
+    isSuspended(): boolean;
     /** `true` when this error is a 401 / `unauthorized` (or 403 / `forbidden`). */
     isAuth(): boolean;
     /** `true` when this error is a 404 / `not_found`. */
     isNotFound(): boolean;
     /** `true` when this error is a 422 / `out_of_bounds` (score below/above board limit). */
     isOutOfBounds(): boolean;
-    /** `true` for transient / retryable conditions: network errors, timeouts,
-     *  5xx, and 429. The transport layer relies on this for its retry policy. */
+    /** `true` for the SDK's retryable conditions: pure network errors, 5xx, and
+     *  429. Deliberately excludes `timeout` and `aborted` — those are caller-
+     *  observable terminal states, not transient. Aligned with `shouldRetryError`
+     *  in `retry.ts` so a consumer mirroring the SDK's retry policy gets the
+     *  same answer the transport does. */
     isTransient(): boolean;
+    /** `true` when this error is a 409 / `conflict` (idempotency-key conflict
+     *  on retry). */
+    isConflict(): boolean;
     /**
      * Build a `ScorezillaError` from a fetch round-trip outcome.
      *

package/dist/identity.cjs

@@ -0,0 +1,87 @@
+'use strict';
+
+// src/identity.ts
+var isBrowser = () => typeof window !== "undefined";
+function readPersisted(key) {
+  if (!isBrowser()) return null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writePersisted(key, value) {
+  if (!isBrowser()) return;
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+  }
+}
+function removePersisted(key) {
+  if (!isBrowser()) return;
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+  }
+}
+function mintUuid() {
+  if (isBrowser() && typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `anon-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function requireStorageKey(fnName, options) {
+  if (!options || typeof options.storageKey !== "string" || options.storageKey.length === 0) {
+    throw new TypeError(`${fnName}: options.storageKey is required (non-empty string)`);
+  }
+  return options.storageKey;
+}
+function useAnonymousPlayer(options) {
+  const storageKey = requireStorageKey("useAnonymousPlayer", options);
+  let id = readPersisted(storageKey);
+  if (id === null || id.length === 0) {
+    id = mintUuid();
+    writePersisted(storageKey, id);
+  }
+  return {
+    id,
+    forget: () => removePersisted(storageKey)
+  };
+}
+function usePromptedPlayer(options) {
+  const storageKey = requireStorageKey("usePromptedPlayer", options);
+  if (typeof options.prompt !== "string" || options.prompt.length === 0) {
+    throw new TypeError("usePromptedPlayer: options.prompt is required (non-empty string)");
+  }
+  let id = readPersisted(storageKey);
+  if (id === null || id.length === 0) {
+    if (!isBrowser() || typeof window.prompt !== "function") {
+      return null;
+    }
+    const entered = window.prompt(options.prompt);
+    if (entered === null || entered.length === 0) {
+      return null;
+    }
+    id = entered;
+    writePersisted(storageKey, id);
+  }
+  return {
+    id,
+    forget: () => removePersisted(storageKey)
+  };
+}
+function useServerAuthoritative() {
+  return { source: "server-authoritative" };
+}
+function useAuthProvider(_options) {
+  throw new Error(
+    "useAuthProvider is not yet implemented in this 0.3.0-next preview. OAuth provider helpers (Google + GitHub for v1) ship in a follow-up release on the `next` dist-tag. Until then, drive your own OAuth flow and pass the resulting user identifier to submitScore directly."
+  );
+}
+
+exports.useAnonymousPlayer = useAnonymousPlayer;
+exports.useAuthProvider = useAuthProvider;
+exports.usePromptedPlayer = usePromptedPlayer;
+exports.useServerAuthoritative = useServerAuthoritative;
+//# sourceMappingURL=identity.cjs.map
+//# sourceMappingURL=identity.cjs.map

package/dist/identity.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/identity.ts"],"names":[],"mappings":"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","file":"identity.cjs","sourcesContent":["/**\n * Identity preset helpers — opinionated, selectable ways for your game to\n * generate or fetch a `playerId` for score submission.\n *\n * Background: every Scorezilla score carries an opaque `playerId`. The SDK\n * doesn't care whether it's a UUID, a nickname, an email, or a server\n * session token. But _how_ your game decides on that value is a UX +\n * privacy decision the team should make explicitly. These presets are the\n * blessed patterns; pick one per integration.\n *\n * See ADR 0003 (MCP identity axis) for the design rationale:\n * https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md\n *\n * @module scorezilla/identity\n * @since 0.3.0\n */\n\nexport interface AnonymousPlayerOptions {\n  /** localStorage key under which the generated UUID is persisted. */\n  readonly storageKey: string;\n}\n\nexport interface PromptedPlayerOptions {\n  /** localStorage key under which the user-entered name is persisted. */\n  readonly storageKey: string;\n  /** Message shown in `window.prompt()` on first run. */\n  readonly prompt: string;\n}\n\n/**\n * Identity handle returned by the storage-backed presets.\n *\n * `forget()` clears the persisted value from browser storage. It does\n * **not** delete server-side score history for this player — to fully\n * erase a player's data, call the admin \"delete player\" endpoint.\n */\nexport interface PlayerHandle {\n  readonly id: string;\n  readonly forget: () => void;\n}\n\n/**\n * Marker returned by `useServerAuthoritative()` to signal that the\n * game's backend (not the browser) owns the `playerId` via the\n * HMAC-signed secure path (`scorezilla/server`).\n */\nexport interface ServerAuthoritativeMarker {\n  readonly source: 'server-authoritative';\n}\n\nconst isBrowser = (): boolean => typeof window !== 'undefined';\n\nfunction readPersisted(key: string): string | null {\n  if (!isBrowser()) return null;\n  try {\n    return window.localStorage.getItem(key);\n  } catch {\n    // Storage may throw in sandboxed iframes, privacy mode, or when the\n    // user has disabled site data. Treat as \"missing\"; the caller will\n    // mint or re-prompt.\n    return null;\n  }\n}\n\nfunction writePersisted(key: string, value: string): void {\n  if (!isBrowser()) return;\n  try {\n    window.localStorage.setItem(key, value);\n  } catch {\n    // ignore; next call will re-mint or re-prompt\n  }\n}\n\nfunction removePersisted(key: string): void {\n  if (!isBrowser()) return;\n  try {\n    window.localStorage.removeItem(key);\n  } catch {\n    // ignore\n  }\n}\n\nfunction mintUuid(): string {\n  if (isBrowser() && typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  // Best-effort fallback: timestamp + random suffix. Not cryptographically\n  // strong, but opaque enough for the identifier-only use case. The\n  // browsers we target (Chrome 92+, Firefox 95+, Safari 15.4+) all have\n  // crypto.randomUUID — this branch is reached only in non-browser\n  // environments where useAnonymousPlayer shouldn't be called anyway.\n  return `anon-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;\n}\n\nfunction requireStorageKey(fnName: string, options: { storageKey?: unknown } | undefined): string {\n  if (!options || typeof options.storageKey !== 'string' || options.storageKey.length === 0) {\n    throw new TypeError(`${fnName}: options.storageKey is required (non-empty string)`);\n  }\n  return options.storageKey;\n}\n\n/**\n * Anonymous player identity. Generates an opaque UUID on first run and\n * persists it in `localStorage` so the same browser keeps the same ID\n * across page reloads.\n *\n * **Privacy.** Stores a randomly-generated UUID in browser localStorage;\n * the value is sent to the API on every score submission and persisted\n * indefinitely in the player's score-history rows. No PII is collected.\n * `forget()` removes the localStorage entry; for full server-side erasure\n * call the admin \"delete player\" endpoint.\n *\n * @example\n * ```ts\n * import { Scorezilla } from 'scorezilla';\n * import { useAnonymousPlayer } from 'scorezilla/identity';\n *\n * const player = useAnonymousPlayer({ storageKey: 'mygame:player' });\n * const sz = new Scorezilla({ publicKey: 'pk_…' });\n * await sz.submitScore({ boardId, playerId: player.id, score: 42 });\n * ```\n *\n * @since 0.3.0\n * @stability stable\n */\nexport function useAnonymousPlayer(options: AnonymousPlayerOptions): PlayerHandle {\n  const storageKey = requireStorageKey('useAnonymousPlayer', options);\n  let id = readPersisted(storageKey);\n  if (id === null || id.length === 0) {\n    id = mintUuid();\n    writePersisted(storageKey, id);\n  }\n  return {\n    id,\n    forget: () => removePersisted(storageKey),\n  };\n}\n\n/**\n * Prompted player identity. On first run shows a `window.prompt()` asking\n * the user for a name, then persists it in `localStorage` for subsequent\n * visits. Returns `null` if there is no browser (SSR), no `window.prompt`,\n * or if the user cancelled / entered an empty value.\n *\n * **Privacy.** The user-entered string is stored in browser localStorage,\n * transmitted to the API on every score submission, and persisted\n * indefinitely on the leaderboard. The persisted value is whatever the\n * user typed — sanitize at the UI layer if you care. `forget()` clears\n * local state but does NOT delete server-side history.\n *\n * **UX caveat.** `window.prompt()` blocks the main thread and looks\n * dated in modern apps. For a polished flow, build your own inline form\n * and pass the result to `submitScore` directly — the preset is here to\n * cover quick prototypes and jam-style integrations.\n *\n * @example\n * ```ts\n * import { Scorezilla } from 'scorezilla';\n * import { usePromptedPlayer } from 'scorezilla/identity';\n *\n * const player = usePromptedPlayer({\n *   storageKey: 'mygame:player',\n *   prompt: 'Enter a name for the leaderboard:',\n * });\n *\n * if (player) {\n *   const sz = new Scorezilla({ publicKey: 'pk_…' });\n *   await sz.submitScore({ boardId, playerId: player.id, score: 42 });\n * }\n * ```\n *\n * @since 0.3.0\n * @stability stable\n */\nexport function usePromptedPlayer(options: PromptedPlayerOptions): PlayerHandle | null {\n  const storageKey = requireStorageKey('usePromptedPlayer', options);\n  if (typeof options.prompt !== 'string' || options.prompt.length === 0) {\n    throw new TypeError('usePromptedPlayer: options.prompt is required (non-empty string)');\n  }\n\n  let id = readPersisted(storageKey);\n  if (id === null || id.length === 0) {\n    if (!isBrowser() || typeof window.prompt !== 'function') {\n      return null;\n    }\n    const entered = window.prompt(options.prompt);\n    if (entered === null || entered.length === 0) {\n      return null;\n    }\n    id = entered;\n    writePersisted(storageKey, id);\n  }\n  return {\n    id,\n    forget: () => removePersisted(storageKey),\n  };\n}\n\n/**\n * Server-authoritative identity marker. Signals that the game's backend\n * is responsible for the `playerId` via the HMAC-signed secure path\n * (`scorezilla/server`). The browser SDK does no identity work — the\n * server picks the value, signs the submission, and posts.\n *\n * The return value is a no-op marker; you don't pass it anywhere. It\n * exists so MCP-returned snippets can emit a single line that\n * unambiguously says \"this game uses the secure path; identity is\n * server-authoritative.\"\n *\n * @example\n * ```ts\n * // Client (no identity helper needed):\n * import { useServerAuthoritative } from 'scorezilla/identity';\n * useServerAuthoritative();\n *\n * // Server (where the real work happens):\n * import { Scorezilla } from 'scorezilla/server';\n * const sz = new Scorezilla({ secretKey: process.env.SCOREZILLA_SECRET_KEY! });\n * await sz.submitScore({ boardId, playerId: serverDerivedId, score });\n * ```\n *\n * @since 0.3.0\n * @stability stable\n */\nexport function useServerAuthoritative(): ServerAuthoritativeMarker {\n  return { source: 'server-authoritative' };\n}\n\n/**\n * OAuth-backed player identity. **Preview stub in 0.3.0-next.x** — throws\n * on call. Full implementation (Google + GitHub for v1, Apple + Discord\n * deferred) lands in a follow-up release on the `next` dist-tag, before\n * the `latest` 0.3.0 ships.\n *\n * Until then: drive your own OAuth flow and pass the resulting user\n * identifier to `submitScore` directly.\n *\n * @since 0.3.0\n * @stability preview\n */\nexport function useAuthProvider(_options: { readonly provider: 'google' | 'github' }): never {\n  throw new Error(\n    'useAuthProvider is not yet implemented in this 0.3.0-next preview. ' +\n      'OAuth provider helpers (Google + GitHub for v1) ship in a follow-up ' +\n      'release on the `next` dist-tag. Until then, drive your own OAuth flow ' +\n      'and pass the resulting user identifier to submitScore directly.',\n  );\n}\n"]}