scorezilla 0.4.0 → 0.5.1

package/API.md

@@ -111,17 +111,22 @@ Violations throw a plain `Error` (not `ScorezillaError`) before any network call
 
 #### 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.                                                                                            |
+| Code                             | Status | Meaning                                                                                                                                               |
+| -------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `unauthorized`                   | 401    | Invalid `publicKey`.                                                                                                                                  |
+| `forbidden`                      | 403    | Key is not bound to this `boardId`.                                                                                                                   |
+| `origin_not_allowed`             | 403    | Request `Origin` is not in the board's allowlist (configured in the dashboard). Gates browser submits only — server-to-server calls send no `Origin`. |
+| `player_banned`                  | 403    | The player is on this board's denylist (banned by the game owner).                                                                                    |
+| `turnstile_required`             | 403    | The board requires a Cloudflare Turnstile token and none was sent.                                                                                    |
+| `turnstile_failed`               | 403    | The supplied Turnstile token failed verification.                                                                                                     |
+| `turnstile_hostname_mismatch`    | 403    | The Turnstile token was solved on an origin not allowed for this game.                                                                                |
+| `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`
 
@@ -154,6 +159,12 @@ const { entries } = await sz.getLeaderboard({ boardId, top: 25 });
 for (const e of entries) console.log(`${e.rank}. ${e.playerId}: ${e.score}`);
 ```
 
+> **Read-path errors.** The read methods (`getLeaderboard`, `getPlayerRank`,
+> `getWindowAround`) share the codes in the [`submitScore` table](#errors)
+> (minus the submit-only ones), and add one: **`tenant_suspended`** (`402`) when
+> the board's tenant is suspended. (On the submit path that same condition
+> surfaces as `usage_cap_exceeded` with `reason: 'suspended'`.)
+
 ### `getPlayerRank`
 
 `GET /v1/boards/:boardId/players/:playerId/rank`. "No entry yet" is a normal

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- [#66](https://github.com/isco-tec/scorezilla-js/pull/66) [`746d599`](https://github.com/isco-tec/scorezilla-js/commit/746d599880a347ca656b233a9241dc6b8cc68926) Thanks [@isco-tec](https://github.com/isco-tec)! - Add `turnstile_hostname_mismatch` to the `ScorezillaErrorCode` union — a 403 the API can return when a Turnstile token is solved on an origin not allowed for the game. It previously fell through the open union as an untyped string; now it's a first-class code (with JSDoc) and documented in the API reference alongside the other 403 codes.
+
+- [#67](https://github.com/isco-tec/scorezilla-js/pull/67) [`2966433`](https://github.com/isco-tec/scorezilla-js/commit/2966433d66883fb3eee04596aefbba5d1677c436) Thanks [@isco-tec](https://github.com/isco-tec)! - Add `tenant_suspended` to the `ScorezillaErrorCode` union — a `402` the read paths (`getLeaderboard` / `getPlayerRank` / `getWindowAround`) return when the board's tenant is suspended. It previously fell through the open union as an untyped string; now it's typed (with JSDoc) and documented in the API reference. (On submit, the same condition still surfaces as `usage_cap_exceeded` with `reason: 'suspended'`.)
+
+- [#62](https://github.com/isco-tec/scorezilla-js/pull/62) [`90b277a`](https://github.com/isco-tec/scorezilla-js/commit/90b277afb745c29fbdcca46cd6dbd14479229c2f) Thanks [@isco-tec](https://github.com/isco-tec)! - Add the newer server error codes to the `ScorezillaErrorCode` union so consumers get autocomplete + type-checking when branching on them: `player_banned`, `name_taken`, `board_archived`, `turnstile_required`, `turnstile_failed`, `origin_not_allowed`. (Runtime behavior is unchanged — the union's open tail already carried these strings at runtime.) The `submitScore` `@throws` JSDoc now lists `player_banned` and `name_taken` as possible outcomes.
+
+## 0.5.0
+
+### Minor Changes
+
+- [#60](https://github.com/isco-tec/scorezilla-js/pull/60) [`20ccc50`](https://github.com/isco-tec/scorezilla-js/commit/20ccc50d0f37a491c309b2f47555c698c3ceaec2) Thanks [@isco-tec](https://github.com/isco-tec)! - Add the headless, never-throws client and cross-platform submit fields.
+  - **`scorezilla/headless`** — a new subpath exposing `createHeadlessClient(config)` with `submit(...) → { ok, rank, totalEntries, isPersonalBest } | null` and `getLeaderboard(...) → RankedEntry[]` that **never throw**: failures collapse to `null` / `[]`. This is the identical headless surface a host wraps so embedded game code never changes between platforms. Plus `isCrossOrigin(homeOrigin)` to detect cross-site embedding and decide whether the token path is needed.
+  - **`submitScore` / headless `submit`** now accept an optional **`name`** (public display name) and **`turnstileToken`** (the cross-origin token path); both are forwarded on the wire.
+  - **`RankedEntry`** now carries an optional **`name`** — the display name returned by the leaderboard read.
+
+  The throwing `Scorezilla` class is unchanged; reach for it when you want typed `ScorezillaError`s to branch on.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -92,6 +92,32 @@ 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.
 
+## Headless, never-throws client (`scorezilla/headless`)
+
+For embedded games that want the **same API on every host** and never want a
+failed call to throw, wrap the client in the headless facade. Failures collapse
+to `null` (submit) or `[]` (leaderboard), so a dropped network call can't crash
+a game loop:
+
+```ts
+import { createHeadlessClient, isCrossOrigin } from 'scorezilla/headless';
+
+const sz = createHeadlessClient({ publicKey: 'pk_mygame_…' });
+
+// Never throws — `null` means "didn't land", any result means it did.
+const result = await sz.submit({ boardId, playerId, score: 4200, name: 'Ada' });
+if (result) console.log(`rank ${result.rank} of ${result.totalEntries}`);
+
+// Never throws — `[]` on any failure. Each entry has at least
+// { rank, playerId, name?, score }.
+const top = await sz.getLeaderboard({ boardId, top: 10 });
+```
+
+When a game is embedded **cross-site** (itch.io, a portal) and the board has
+Turnstile gating on, pass a `turnstileToken` your host obtains (e.g. via a
+hidden broker iframe on a trusted origin). Use `isCrossOrigin(homeOrigin)` to
+decide whether that path is needed; same-origin submits need nothing extra.
+
 ## Player identity (`scorezilla/identity`)
 
 Browser-side helpers that produce the `playerId` you pass to `submitScore`:

package/dist/errors-8qzE40-2.d.ts

@@ -0,0 +1,170 @@
+import { S as ScorezillaErrorCode, O as OutOfBoundsReason, U as UsageCapReason, B as BillingTier, A as ApiError } from './types-BxxzS_pF.js';
+
+/**
+ * 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'`
+     *    - `usage_cap_exceeded`: `'over_cap' | 'suspended'`
+     *  and possibly other codes in future minor releases. */
+    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;
+    /** 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;
+    /** 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. */
+    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;
+        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 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.
+     *
+     * 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 { ScorezillaError as S };

package/dist/errors-Bu084BD9.d.cts

@@ -0,0 +1,170 @@
+import { S as ScorezillaErrorCode, O as OutOfBoundsReason, U as UsageCapReason, B as BillingTier, A as ApiError } from './types-BxxzS_pF.cjs';
+
+/**
+ * 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'`
+     *    - `usage_cap_exceeded`: `'over_cap' | 'suspended'`
+     *  and possibly other codes in future minor releases. */
+    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;
+    /** 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;
+    /** 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. */
+    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;
+        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 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.
+     *
+     * 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 { ScorezillaError as S };