scorezilla 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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-DuRShuw9.d.cts

@@ -0,0 +1,170 @@
+import { S as ScorezillaErrorCode, O as OutOfBoundsReason, U as UsageCapReason, B as BillingTier, A as ApiError } from './types-C6VO4OWP.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 };

package/dist/errors-maldlTY-.d.ts

@@ -0,0 +1,170 @@
+import { S as ScorezillaErrorCode, O as OutOfBoundsReason, U as UsageCapReason, B as BillingTier, A as ApiError } from './types-C6VO4OWP.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 };