scorezilla 0.1.0-next.0 → 0.1.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 0.1.0-next.1
+
+### Minor Changes
+
+- [#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.
+
 ## 0.1.0-next.0
 
 ### Minor Changes

package/README.md

@@ -18,10 +18,13 @@ AI-vibe-coded games.
 - **Private.** No cookies, no `localStorage`, no fingerprinting beyond runtime
   detection — see [COMPATIBILITY.md](./COMPATIBILITY.md).
 
-> **Status:** v0.1.0 ships the **public-key client** (browser-safe). The HMAC
-> server adapter (`scorezilla/server`) lands in v0.2.0; React
-> (`scorezilla/react`) in v0.3.0; Phaser (`scorezilla/phaser`) in v0.4.0. See
-> [CHANGELOG.md](./CHANGELOG.md) and [VERSIONING.md](./VERSIONING.md).
+> **Status:** v0.1.0 ships the **public-key client** (browser-safe).
+> v0.2.0 ships the **HMAC server adapter** (`scorezilla/server`) for
+> game backends that need cheat-resistant submissions. React
+> (`scorezilla/react`) lands in v0.3.0; Phaser (`scorezilla/phaser`) in
+> v0.4.0. The first preview is on the `next` dist-tag — install with
+> `npm install scorezilla@next`. See [CHANGELOG.md](./CHANGELOG.md) and
+> [VERSIONING.md](./VERSIONING.md).
 
 > **Commercial context.** Scorezilla is a hosted leaderboard service with free
 > and paid tiers — see [scorezilla.dev/pricing](https://scorezilla.dev/pricing).
@@ -76,6 +79,36 @@ await sz.getWindowAround({ boardId, playerId, before?, after? });
 See [**API.md**](./API.md) for the full reference, including every response
 field, every error code, and advanced patterns.
 
+## Server-side HMAC (`scorezilla/server`)
+
+Public-key submissions are client-authoritative — anyone with your `pk_` can
+submit any score from devtools. For games where ranking matters, sign each
+submission server-side with a `sk_live_*` secret:
+
+```ts
+import { Scorezilla, ScorezillaError } 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 });
+```
+
+Same method shape as the public-key client — `submitScore`, `getLeaderboard`,
+`getPlayerRank`, `getWindowAround`. The adapter signs every request with
+**HMAC-SHA256** over a canonical string (method + path + ts + nonce +
+sha256(body)), and the API verifies before any state change. Replay
+protection is enforced server-side via a 10-minute nonce window.
+
+The `scorezilla/server` subpath is server-only — importing it from the
+browser throws at module evaluation. Use environment variables (or your
+secret manager) to load the `sk_live_*` value; never embed it in a build
+that ships to clients.
+
 ## Error handling
 
 Every failure path — HTTP non-2xx, network error, timeout, abort, JSON parse

package/dist/errors-Bp9ZDYqm.d.cts

@@ -0,0 +1,284 @@
+/** Minimal fetch shape — broader than `typeof fetch` so polyfills and
+ *  test stubs (`vi.fn()`, `node-fetch`, etc.) typecheck cleanly. */
+type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * SDK configuration.
+ *
+ * The `ScorezillaConfig` is a TypeScript-level discriminated union of
+ * `PublicKeyConfig` and `SecretKeyConfig`. The mutual-exclusivity (you may
+ * pass `publicKey` OR `secretKey`, never both) is enforced at compile time:
+ * passing both fields fails type-checking before the runtime check fires.
+ *
+ * The runtime check in {@link validateConfig} is the second line of defense
+ * for consumers using plain JS or `as any` casts.
+ */
+
+/** Shared options across both auth modes. */
+interface BaseConfig {
+    /** API base URL (no trailing slash required). Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Custom fetch implementation — defaults to `globalThis.fetch`. Pass
+     *  `node-fetch`, `undici`, or a mock here. The explicit signature
+     *  (`(RequestInfo | URL, init?) => Promise<Response>`) is broader than
+     *  `typeof fetch` so common polyfills typecheck cleanly. */
+    fetch?: FetchImpl;
+    /** Per-request timeout in milliseconds. Defaults to 30 s. */
+    timeoutMs?: number;
+    /** Maximum retry attempts on transient failures. Defaults to 2 (so the
+     *  worst-case total request count is 3). */
+    maxRetries?: number;
+    /** Override the default `User-Agent` header (Node/Workers/Bun/Deno —
+     *  browsers silently ignore the value). */
+    userAgent?: string;
+}
+/** Public-key auth: browser-safe path. The key is fingerprinted to a game
+ *  on the server side via `pk_<gameSlug>_<base62>`. */
+type PublicKeyConfig = BaseConfig & {
+    publicKey: string;
+    secretKey?: never;
+};
+/** Secret-key auth: server-side HMAC. The pair `{ id, secret }` is what
+ *  the operator dashboard issues; the SDK signs requests with `secret` and
+ *  identifies them via `id`. */
+type SecretKeyConfig = BaseConfig & {
+    secretKey: {
+        id: string;
+        secret: string;
+    };
+    publicKey?: never;
+};
+/** The top-level config type. The union is open for additional auth modes
+ *  in future major releases. */
+type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
+
+/**
+ * Wire types for the Scorezilla API at /v1.
+ *
+ * Mirrors the documented response shapes. TypeScript's structural typing
+ * means additional fields the server adds in a minor release won't break
+ * consumers — see VERSIONING.md for the full SemVer contract.
+ *
+ * No Zod or other runtime validators in v0.1.0 — keeps the bundle small.
+ * Narrow untrusted input with the {@link isApiSuccess} / {@link isApiError}
+ * type guards exported below.
+ */
+/**
+ * Machine-stable error codes returned by the API.
+ *
+ * Consumers MUST branch on this `code` rather than the human-readable
+ * `message` — message text is English-only and explicitly NOT part of the
+ * SemVer contract.
+ *
+ * The union is intentionally open (`| (string & {})`) so unknown future
+ * codes from a server-side minor release don't compile-error against the
+ * SDK. The trick preserves autocomplete on the known set while permitting
+ * arbitrary strings at runtime — see
+ * https://github.com/microsoft/TypeScript/issues/29729 for the pattern.
+ *
+ * @stable v0.1.0
+ */
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+/** Reason sub-classifier on `out_of_bounds` errors. Open union — see {@link ScorezillaErrorCode}. */
+type OutOfBoundsReason = 'below_min' | 'above_max' | (string & {});
+/** Successful API response envelope. The `T` is the per-route payload. */
+type ApiSuccess<T> = {
+    ok: true;
+} & T;
+/** Failure response envelope. The server returns this on every non-2xx response. */
+interface ApiError {
+    ok: false;
+    error: ScorezillaErrorCode;
+    /** Human-readable, English only. Not machine-stable — branch on `error` and `reason`. */
+    message?: string;
+    /** Sub-classifier — used by `out_of_bounds` (`'below_min' | 'above_max'`). */
+    reason?: string;
+    /** Seconds — present on `rate_limited`. Also mirrored in the HTTP `Retry-After` header. */
+    retryAfter?: number;
+    /** Which rate-limit layer fired — present on `rate_limited`. */
+    layer?: string;
+    /** The limit value that was crossed — present on `out_of_bounds`. */
+    bound?: number;
+}
+/** Discriminated envelope: every API response is one of these two shapes. */
+type ApiResponse<T> = ApiSuccess<T> | ApiError;
+/**
+ * A single ranked entry on a leaderboard.
+ *
+ * Returned as an array on `leaderboard` and `window-around` responses, and
+ * inline on `playerRank` (without the `rank` wrapper — see
+ * {@link PlayerRankResponse}).
+ */
+interface RankedEntry {
+    /** 1-based rank. */
+    rank: number;
+    playerId: string;
+    score: number;
+    /** Milliseconds since epoch. */
+    submittedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/** Payload from `POST /v1/boards/:boardId/scores`. */
+interface SubmitScoreResponse {
+    boardId: string;
+    /** The key ID that authorized the submission. Useful for consumer-side audit. */
+    keyId: string;
+    /** 1-based rank after the submit settled. */
+    rank: number;
+    totalEntries: number;
+    isPersonalBest: boolean;
+}
+/** Payload from `GET /v1/boards/:boardId/leaderboard`. */
+interface LeaderboardResponse {
+    boardId: string;
+    offset: number;
+    limit: number;
+    entries: RankedEntry[];
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
+interface PlayerRankResponse {
+    boardId: string;
+    playerId: string;
+    rank: number;
+    score: number;
+    submittedAt: number;
+    totalEntries: number;
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
+interface WindowAroundResponse {
+    boardId: string;
+    playerId: string;
+    before: number;
+    after: number;
+    entries: RankedEntry[];
+}
+
+/**
+ * SDK error type.
+ *
+ * Every non-2xx API response is normalized into a `ScorezillaError` instance
+ * by the transport layer. Network failures and timeouts surface as the same
+ * class (with `status: 0`) so callers have a single error type to catch.
+ *
+ * **Invariant — consumers MUST branch on `code` (and optionally `reason`),
+ * never on `message`.** The English-language `message` is for operator
+ * logging only and is explicitly **not** part of the SemVer contract; a
+ * minor release MAY reword any message. Machine logic that depends on
+ * message text will break silently across upgrades.
+ */
+
+/**
+ * Options for {@link ScorezillaError.from}.
+ *
+ * The fields mirror what's available after a fetch round-trip: the HTTP
+ * status, the parsed JSON body (if any), the request ID from
+ * `X-Request-Id`, and an optional `cause` for the underlying
+ * network/abort error.
+ */
+interface ScorezillaErrorFromInit {
+    status: number;
+    body?: ApiError | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+/**
+ * Thrown by the SDK for every failure path — non-2xx responses, network
+ * errors, aborts, and timeouts.
+ *
+ * Cross-realm `instanceof` is guaranteed: the class sets `Error.prototype`
+ * explicitly so checks survive iframe / worker boundaries.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sz.submitScore({ boardId, playerId, score });
+ * } catch (e) {
+ *   if (!(e instanceof ScorezillaError)) throw e;
+ *
+ *   if (e.isRateLimited()) {
+ *     await sleep((e.retryAfter ?? 30) * 1000);
+ *     return retry();
+ *   }
+ *   if (e.code === 'out_of_bounds') {
+ *     console.warn(`Score crosses ${e.reason} bound (limit ${e.bound})`);
+ *     return;
+ *   }
+ *   if (e.isAuth()) throw new Error('SDK misconfigured — bad publicKey');
+ *
+ *   // Anything else: surface to your reporter with requestId for support.
+ *   console.error(`Scorezilla ${e.code} (${e.status}) — request ${e.requestId}`);
+ *   throw e;
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ * @stability stable
+ */
+declare class ScorezillaError extends Error {
+    /** HTTP status of the response, or {@link STATUS_NETWORK_ERROR} (0) for
+     *  network / abort / timeout. */
+    readonly status: number;
+    /** Machine-stable error code from the API. Open union — see
+     *  {@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'`)
+     *  and possibly other codes in future minor releases. */
+    readonly reason: OutOfBoundsReason | string | undefined;
+    /** Seconds — present on `rate_limited`. Honored by the transport's retry
+     *  policy (Step 2.4). */
+    readonly retryAfter: number | undefined;
+    /** Server-issued request ID, lifted from the `X-Request-Id` response
+     *  header. Pass this to support when filing bugs. */
+    readonly requestId: string | undefined;
+    /** The bound value crossed on `out_of_bounds`. */
+    readonly bound: number | undefined;
+    /** Which rate-limit layer fired on `rate_limited`. */
+    readonly layer: 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. */
+    readonly cause: unknown;
+    constructor(message: string, init: {
+        status: number;
+        code: ScorezillaErrorCode;
+        reason?: string | undefined;
+        retryAfter?: number | undefined;
+        requestId?: string | undefined;
+        bound?: number | undefined;
+        layer?: string | undefined;
+        cause?: unknown;
+    });
+    /** `true` when this error is a 429 / `rate_limited`. */
+    isRateLimited(): 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. */
+    isTransient(): boolean;
+    /**
+     * Build a `ScorezillaError` from a fetch round-trip outcome.
+     *
+     * Prefer this over `new ScorezillaError(...)` from the transport layer —
+     * it does the mapping from API response shape to error fields in one
+     * place, so future fields like `correlationId` get added once here.
+     *
+     * @param init - status, optional parsed body, optional requestId, optional cause
+     */
+    static from(init: ScorezillaErrorFromInit): ScorezillaError;
+    /**
+     * Build a `ScorezillaError` for a transport-level failure (no HTTP
+     * response received): network error, abort, or timeout.
+     */
+    static network(message: string, cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for an `AbortSignal`-triggered cancellation. */
+    static aborted(cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for a request that exceeded its timeout budget. */
+    static timeout(timeoutMs: number): ScorezillaError;
+}
+
+export { type ApiSuccess as A, type BaseConfig as B, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type SecretKeyConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, ScorezillaError as b, type ScorezillaErrorCode as c, type ScorezillaConfig as d, type ApiError as e, type ApiResponse as f, type PublicKeyConfig as g };

package/dist/errors-Bp9ZDYqm.d.ts

@@ -0,0 +1,284 @@
+/** Minimal fetch shape — broader than `typeof fetch` so polyfills and
+ *  test stubs (`vi.fn()`, `node-fetch`, etc.) typecheck cleanly. */
+type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * SDK configuration.
+ *
+ * The `ScorezillaConfig` is a TypeScript-level discriminated union of
+ * `PublicKeyConfig` and `SecretKeyConfig`. The mutual-exclusivity (you may
+ * pass `publicKey` OR `secretKey`, never both) is enforced at compile time:
+ * passing both fields fails type-checking before the runtime check fires.
+ *
+ * The runtime check in {@link validateConfig} is the second line of defense
+ * for consumers using plain JS or `as any` casts.
+ */
+
+/** Shared options across both auth modes. */
+interface BaseConfig {
+    /** API base URL (no trailing slash required). Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Custom fetch implementation — defaults to `globalThis.fetch`. Pass
+     *  `node-fetch`, `undici`, or a mock here. The explicit signature
+     *  (`(RequestInfo | URL, init?) => Promise<Response>`) is broader than
+     *  `typeof fetch` so common polyfills typecheck cleanly. */
+    fetch?: FetchImpl;
+    /** Per-request timeout in milliseconds. Defaults to 30 s. */
+    timeoutMs?: number;
+    /** Maximum retry attempts on transient failures. Defaults to 2 (so the
+     *  worst-case total request count is 3). */
+    maxRetries?: number;
+    /** Override the default `User-Agent` header (Node/Workers/Bun/Deno —
+     *  browsers silently ignore the value). */
+    userAgent?: string;
+}
+/** Public-key auth: browser-safe path. The key is fingerprinted to a game
+ *  on the server side via `pk_<gameSlug>_<base62>`. */
+type PublicKeyConfig = BaseConfig & {
+    publicKey: string;
+    secretKey?: never;
+};
+/** Secret-key auth: server-side HMAC. The pair `{ id, secret }` is what
+ *  the operator dashboard issues; the SDK signs requests with `secret` and
+ *  identifies them via `id`. */
+type SecretKeyConfig = BaseConfig & {
+    secretKey: {
+        id: string;
+        secret: string;
+    };
+    publicKey?: never;
+};
+/** The top-level config type. The union is open for additional auth modes
+ *  in future major releases. */
+type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
+
+/**
+ * Wire types for the Scorezilla API at /v1.
+ *
+ * Mirrors the documented response shapes. TypeScript's structural typing
+ * means additional fields the server adds in a minor release won't break
+ * consumers — see VERSIONING.md for the full SemVer contract.
+ *
+ * No Zod or other runtime validators in v0.1.0 — keeps the bundle small.
+ * Narrow untrusted input with the {@link isApiSuccess} / {@link isApiError}
+ * type guards exported below.
+ */
+/**
+ * Machine-stable error codes returned by the API.
+ *
+ * Consumers MUST branch on this `code` rather than the human-readable
+ * `message` — message text is English-only and explicitly NOT part of the
+ * SemVer contract.
+ *
+ * The union is intentionally open (`| (string & {})`) so unknown future
+ * codes from a server-side minor release don't compile-error against the
+ * SDK. The trick preserves autocomplete on the known set while permitting
+ * arbitrary strings at runtime — see
+ * https://github.com/microsoft/TypeScript/issues/29729 for the pattern.
+ *
+ * @stable v0.1.0
+ */
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+/** Reason sub-classifier on `out_of_bounds` errors. Open union — see {@link ScorezillaErrorCode}. */
+type OutOfBoundsReason = 'below_min' | 'above_max' | (string & {});
+/** Successful API response envelope. The `T` is the per-route payload. */
+type ApiSuccess<T> = {
+    ok: true;
+} & T;
+/** Failure response envelope. The server returns this on every non-2xx response. */
+interface ApiError {
+    ok: false;
+    error: ScorezillaErrorCode;
+    /** Human-readable, English only. Not machine-stable — branch on `error` and `reason`. */
+    message?: string;
+    /** Sub-classifier — used by `out_of_bounds` (`'below_min' | 'above_max'`). */
+    reason?: string;
+    /** Seconds — present on `rate_limited`. Also mirrored in the HTTP `Retry-After` header. */
+    retryAfter?: number;
+    /** Which rate-limit layer fired — present on `rate_limited`. */
+    layer?: string;
+    /** The limit value that was crossed — present on `out_of_bounds`. */
+    bound?: number;
+}
+/** Discriminated envelope: every API response is one of these two shapes. */
+type ApiResponse<T> = ApiSuccess<T> | ApiError;
+/**
+ * A single ranked entry on a leaderboard.
+ *
+ * Returned as an array on `leaderboard` and `window-around` responses, and
+ * inline on `playerRank` (without the `rank` wrapper — see
+ * {@link PlayerRankResponse}).
+ */
+interface RankedEntry {
+    /** 1-based rank. */
+    rank: number;
+    playerId: string;
+    score: number;
+    /** Milliseconds since epoch. */
+    submittedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/** Payload from `POST /v1/boards/:boardId/scores`. */
+interface SubmitScoreResponse {
+    boardId: string;
+    /** The key ID that authorized the submission. Useful for consumer-side audit. */
+    keyId: string;
+    /** 1-based rank after the submit settled. */
+    rank: number;
+    totalEntries: number;
+    isPersonalBest: boolean;
+}
+/** Payload from `GET /v1/boards/:boardId/leaderboard`. */
+interface LeaderboardResponse {
+    boardId: string;
+    offset: number;
+    limit: number;
+    entries: RankedEntry[];
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
+interface PlayerRankResponse {
+    boardId: string;
+    playerId: string;
+    rank: number;
+    score: number;
+    submittedAt: number;
+    totalEntries: number;
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
+interface WindowAroundResponse {
+    boardId: string;
+    playerId: string;
+    before: number;
+    after: number;
+    entries: RankedEntry[];
+}
+
+/**
+ * SDK error type.
+ *
+ * Every non-2xx API response is normalized into a `ScorezillaError` instance
+ * by the transport layer. Network failures and timeouts surface as the same
+ * class (with `status: 0`) so callers have a single error type to catch.
+ *
+ * **Invariant — consumers MUST branch on `code` (and optionally `reason`),
+ * never on `message`.** The English-language `message` is for operator
+ * logging only and is explicitly **not** part of the SemVer contract; a
+ * minor release MAY reword any message. Machine logic that depends on
+ * message text will break silently across upgrades.
+ */
+
+/**
+ * Options for {@link ScorezillaError.from}.
+ *
+ * The fields mirror what's available after a fetch round-trip: the HTTP
+ * status, the parsed JSON body (if any), the request ID from
+ * `X-Request-Id`, and an optional `cause` for the underlying
+ * network/abort error.
+ */
+interface ScorezillaErrorFromInit {
+    status: number;
+    body?: ApiError | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+/**
+ * Thrown by the SDK for every failure path — non-2xx responses, network
+ * errors, aborts, and timeouts.
+ *
+ * Cross-realm `instanceof` is guaranteed: the class sets `Error.prototype`
+ * explicitly so checks survive iframe / worker boundaries.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sz.submitScore({ boardId, playerId, score });
+ * } catch (e) {
+ *   if (!(e instanceof ScorezillaError)) throw e;
+ *
+ *   if (e.isRateLimited()) {
+ *     await sleep((e.retryAfter ?? 30) * 1000);
+ *     return retry();
+ *   }
+ *   if (e.code === 'out_of_bounds') {
+ *     console.warn(`Score crosses ${e.reason} bound (limit ${e.bound})`);
+ *     return;
+ *   }
+ *   if (e.isAuth()) throw new Error('SDK misconfigured — bad publicKey');
+ *
+ *   // Anything else: surface to your reporter with requestId for support.
+ *   console.error(`Scorezilla ${e.code} (${e.status}) — request ${e.requestId}`);
+ *   throw e;
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ * @stability stable
+ */
+declare class ScorezillaError extends Error {
+    /** HTTP status of the response, or {@link STATUS_NETWORK_ERROR} (0) for
+     *  network / abort / timeout. */
+    readonly status: number;
+    /** Machine-stable error code from the API. Open union — see
+     *  {@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'`)
+     *  and possibly other codes in future minor releases. */
+    readonly reason: OutOfBoundsReason | string | undefined;
+    /** Seconds — present on `rate_limited`. Honored by the transport's retry
+     *  policy (Step 2.4). */
+    readonly retryAfter: number | undefined;
+    /** Server-issued request ID, lifted from the `X-Request-Id` response
+     *  header. Pass this to support when filing bugs. */
+    readonly requestId: string | undefined;
+    /** The bound value crossed on `out_of_bounds`. */
+    readonly bound: number | undefined;
+    /** Which rate-limit layer fired on `rate_limited`. */
+    readonly layer: 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. */
+    readonly cause: unknown;
+    constructor(message: string, init: {
+        status: number;
+        code: ScorezillaErrorCode;
+        reason?: string | undefined;
+        retryAfter?: number | undefined;
+        requestId?: string | undefined;
+        bound?: number | undefined;
+        layer?: string | undefined;
+        cause?: unknown;
+    });
+    /** `true` when this error is a 429 / `rate_limited`. */
+    isRateLimited(): 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. */
+    isTransient(): boolean;
+    /**
+     * Build a `ScorezillaError` from a fetch round-trip outcome.
+     *
+     * Prefer this over `new ScorezillaError(...)` from the transport layer —
+     * it does the mapping from API response shape to error fields in one
+     * place, so future fields like `correlationId` get added once here.
+     *
+     * @param init - status, optional parsed body, optional requestId, optional cause
+     */
+    static from(init: ScorezillaErrorFromInit): ScorezillaError;
+    /**
+     * Build a `ScorezillaError` for a transport-level failure (no HTTP
+     * response received): network error, abort, or timeout.
+     */
+    static network(message: string, cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for an `AbortSignal`-triggered cancellation. */
+    static aborted(cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for a request that exceeded its timeout budget. */
+    static timeout(timeoutMs: number): ScorezillaError;
+}
+
+export { type ApiSuccess as A, type BaseConfig as B, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type SecretKeyConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, ScorezillaError as b, type ScorezillaErrorCode as c, type ScorezillaConfig as d, type ApiError as e, type ApiResponse as f, type PublicKeyConfig as g };