scorezilla 0.3.1 → 0.5.0

package/dist/{errors-CWTmormh.d.cts → types-C6VO4OWP.d.cts}

@@ -160,6 +160,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 {
@@ -178,15 +181,36 @@ interface LeaderboardResponse {
     limit: number;
     entries: RankedEntry[];
 }
-/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
-interface PlayerRankResponse {
+/**
+ * Payload from `GET /v1/boards/:boardId/players/:playerId/rank`.
+ *
+ * Discriminated on `ranked`. "No entry yet" is a normal state, not an error:
+ * the API returns `200 { ranked: false }` (not a 404 — a 404 spammed an
+ * un-suppressable red console line for every benign "has this player scored?"
+ * check). A 404 is now reserved for a genuinely missing board.
+ *
+ * @example
+ * ```ts
+ * const r = await sz.getPlayerRank({ boardId, playerId });
+ * if (r.ranked) console.log(`Rank ${r.rank} of ${r.totalEntries}`);
+ * else console.log('No submission yet.');
+ * ```
+ */
+type PlayerRankResponse = {
     boardId: string;
     playerId: string;
+    ranked: true;
     rank: number;
     score: number;
     submittedAt: number;
     totalEntries: number;
-}
+} | {
+    boardId: string;
+    playerId: string;
+    ranked: false;
+    rank: null;
+    score: null;
+};
 /** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
 interface WindowAroundResponse {
     boardId: string;
@@ -196,171 +220,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-CWTmormh.d.ts → types-C6VO4OWP.d.ts}

@@ -160,6 +160,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 {
@@ -178,15 +181,36 @@ interface LeaderboardResponse {
     limit: number;
     entries: RankedEntry[];
 }
-/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
-interface PlayerRankResponse {
+/**
+ * Payload from `GET /v1/boards/:boardId/players/:playerId/rank`.
+ *
+ * Discriminated on `ranked`. "No entry yet" is a normal state, not an error:
+ * the API returns `200 { ranked: false }` (not a 404 — a 404 spammed an
+ * un-suppressable red console line for every benign "has this player scored?"
+ * check). A 404 is now reserved for a genuinely missing board.
+ *
+ * @example
+ * ```ts
+ * const r = await sz.getPlayerRank({ boardId, playerId });
+ * if (r.ranked) console.log(`Rank ${r.rank} of ${r.totalEntries}`);
+ * else console.log('No submission yet.');
+ * ```
+ */
+type PlayerRankResponse = {
     boardId: string;
     playerId: string;
+    ranked: true;
     rank: number;
     score: number;
     submittedAt: number;
     totalEntries: number;
-}
+} | {
+    boardId: string;
+    playerId: string;
+    ranked: false;
+    rank: null;
+    score: null;
+};
 /** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
 interface WindowAroundResponse {
     boardId: string;
@@ -196,171 +220,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.3.1",
+  "version": "0.5.0",
   "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"
       ]
     }
   },