scorezilla 0.4.0 → 0.5.1

package/dist/{errors-BhPRMQiV.d.cts → types-BxxzS_pF.d.cts}

@@ -97,7 +97,25 @@ type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid
 /** 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 & {});
+ | 'usage_cap_exceeded'
+/** 402 — the board's tenant is suspended. Returned by the READ paths
+ *  (`getLeaderboard` / `getPlayerRank` / `getWindowAround`); the submit path
+ *  instead returns `usage_cap_exceeded` with `reason: 'suspended'`. */
+ | 'tenant_suspended'
+/** 403 — the player is on this board's denylist (banned by the game owner). */
+ | 'player_banned'
+/** 409 — the requested display `name` is already held by a different player. */
+ | 'name_taken'
+/** 409 — the board is archived (frozen); writes are rejected. */
+ | 'board_archived'
+/** 403 — the board requires a Cloudflare Turnstile token and none was sent. */
+ | 'turnstile_required'
+/** 403 — the supplied Turnstile token failed verification. */
+ | 'turnstile_failed'
+/** 403 — the Turnstile token was solved on an origin not allowed for this game. */
+ | 'turnstile_hostname_mismatch'
+/** 403 — the request Origin is not in the board's embed allowlist. */
+ | 'origin_not_allowed' | (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.
@@ -160,6 +178,9 @@ interface RankedEntry {
     /** Milliseconds since epoch. */
     submittedAt: number;
     metadata?: Record<string, unknown>;
+    /** The player's public display name, when they've set one. Absent on older
+     *  entries and for players who submit without a name. */
+    name?: string;
 }
 /** Payload from `POST /v1/boards/:boardId/scores`. */
 interface SubmitScoreResponse {
@@ -217,171 +238,4 @@ interface WindowAroundResponse {
     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'`
-     *    - `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 { type ApiSuccess as A, type BaseConfig as B, type FetchImpl as F, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type ScorezillaConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, type ApiError as b, type ApiResponse as c, type PublicKeyConfig as d, ScorezillaError as e, type ScorezillaErrorCode as f, type SecretKeyConfig as g };
+export type { ApiError as A, BillingTier as B, FetchImpl as F, LeaderboardResponse as L, OutOfBoundsReason as O, PublicKeyConfig as P, RankedEntry as R, ScorezillaErrorCode as S, UsageCapReason as U, WindowAroundResponse as W, ScorezillaConfig as a, ApiSuccess as b, SubmitScoreResponse as c, PlayerRankResponse as d, ApiResponse as e, BaseConfig as f, SecretKeyConfig as g };

package/dist/{errors-BhPRMQiV.d.ts → types-BxxzS_pF.d.ts}

@@ -97,7 +97,25 @@ type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid
 /** 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 & {});
+ | 'usage_cap_exceeded'
+/** 402 — the board's tenant is suspended. Returned by the READ paths
+ *  (`getLeaderboard` / `getPlayerRank` / `getWindowAround`); the submit path
+ *  instead returns `usage_cap_exceeded` with `reason: 'suspended'`. */
+ | 'tenant_suspended'
+/** 403 — the player is on this board's denylist (banned by the game owner). */
+ | 'player_banned'
+/** 409 — the requested display `name` is already held by a different player. */
+ | 'name_taken'
+/** 409 — the board is archived (frozen); writes are rejected. */
+ | 'board_archived'
+/** 403 — the board requires a Cloudflare Turnstile token and none was sent. */
+ | 'turnstile_required'
+/** 403 — the supplied Turnstile token failed verification. */
+ | 'turnstile_failed'
+/** 403 — the Turnstile token was solved on an origin not allowed for this game. */
+ | 'turnstile_hostname_mismatch'
+/** 403 — the request Origin is not in the board's embed allowlist. */
+ | 'origin_not_allowed' | (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.
@@ -160,6 +178,9 @@ interface RankedEntry {
     /** Milliseconds since epoch. */
     submittedAt: number;
     metadata?: Record<string, unknown>;
+    /** The player's public display name, when they've set one. Absent on older
+     *  entries and for players who submit without a name. */
+    name?: string;
 }
 /** Payload from `POST /v1/boards/:boardId/scores`. */
 interface SubmitScoreResponse {
@@ -217,171 +238,4 @@ interface WindowAroundResponse {
     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'`
-     *    - `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 { type ApiSuccess as A, type BaseConfig as B, type FetchImpl as F, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type ScorezillaConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, type ApiError as b, type ApiResponse as c, type PublicKeyConfig as d, ScorezillaError as e, type ScorezillaErrorCode as f, type SecretKeyConfig as g };
+export type { ApiError as A, BillingTier as B, FetchImpl as F, LeaderboardResponse as L, OutOfBoundsReason as O, PublicKeyConfig as P, RankedEntry as R, ScorezillaErrorCode as S, UsageCapReason as U, WindowAroundResponse as W, ScorezillaConfig as a, ApiSuccess as b, SubmitScoreResponse as c, PlayerRankResponse as d, ApiResponse as e, BaseConfig as f, SecretKeyConfig as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scorezilla",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -80,6 +80,16 @@
         "default": "./dist/identity.cjs"
       }
     },
+    "./headless": {
+      "import": {
+        "types": "./dist/headless.d.ts",
+        "default": "./dist/headless.js"
+      },
+      "require": {
+        "types": "./dist/headless.d.cts",
+        "default": "./dist/headless.cjs"
+      }
+    },
     "./phaser": {
       "import": {
         "types": "./dist/phaser.d.ts",
@@ -105,6 +115,9 @@
       ],
       "identity": [
         "./dist/identity.d.ts"
+      ],
+      "headless": [
+        "./dist/headless.d.ts"
       ]
     }
   },