scorezilla 0.1.0-next.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # Changelog
 
+## 0.2.0 — `scorezilla/server` HMAC adapter GA
+
+### Minor Changes
+
+- [#25](https://github.com/isco-tec/scorezilla-js/pull/25) [`5f7025b`](https://github.com/isco-tec/scorezilla-js/commit/5f7025b7b06dded92b3e710316454eb8c891d053) Thanks [@isco-tec](https://github.com/isco-tec)! - **`scorezilla/server`: HMAC requests now bind to the target host (v=2).**
+
+  The canonical signing string includes the host of the request URL, so a signature minted against staging cannot be replayed against prod (or any other origin that happens to share key material). SigV4 has had this since day one; closing the gap before MCP locks the format.
+
+  Wire format change:
+
+  ```
+  Authorization: Scorezilla-HMAC-SHA256 keyId=…, ts=…, nonce=…, signature=…, v=2
+  ```
+
+  The `v=2` parameter is new. The canonical signing string now has six lines instead of five — `host` is inserted between `METHOD` and `pathAndQuery`, lowercased per RFC 9110 §4.2.4.
+
+  **Backward compatibility.** The API verifier still accepts v=1 (no `v=` field, no host binding) during the rollout window — your existing pre-next.3 SDK builds will keep working until v=1 is deprecated. The SDK itself, however, emits v=2 unconditionally from next.3 onwards. If you've forked or wrapped `buildHmacAuthHeader` / `buildSigningString`, you'll need to thread a `host` parameter through.
+
+  **For consumers of `Scorezilla` from `scorezilla/server`:** no API changes. The constructor derives `host` from `baseUrl` automatically. As an added safety net, an invalid `baseUrl` now throws at construction time rather than producing 401 mismatches at every request.
+
+  **For low-level consumers of `buildSigningString` / `buildHmacAuthHeader`:** a new `host` parameter is now required. The latter also accepts an optional `version: 1 | 2` for explicit backward-compat scenarios.
+
+- [`239642a`](https://github.com/isco-tec/scorezilla-js/commit/239642aaf73f643c2f51d806170d3ced31a3fe68) Thanks [@isco-tec](https://github.com/isco-tec)! - **Initial public release candidate.** First publish of the `scorezilla` SDK to npm.
+
+  Includes the v0.1.0 public-key client surface:
+  - `Scorezilla` class with `submitScore`, `getLeaderboard`, `getPlayerRank`, `getWindowAround`
+  - `ScorezillaError` for every failure path (network, timeout, abort, HTTP non-2xx)
+  - Universal runtime support (browsers, Node ≥ 20, Cloudflare Workers, Bun, Deno)
+  - Automatic retries with idempotency keys
+  - Dual ESM/CJS build with [arethetypeswrong](https://arethetypeswrong.github.io/)-clean exports map
+  - ~3.8 KB ESM gzipped
+
+  This RC publishes under the `next` npm dist-tag — install with `npm install scorezilla@next` to try it out. The HMAC server adapter, React hooks, and Phaser plugin land in subsequent v0.2.0, v0.3.0, and v0.4.0 releases.
+
+- [#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.
+
+- [#23](https://github.com/isco-tec/scorezilla-js/pull/23) [`5163e31`](https://github.com/isco-tec/scorezilla-js/commit/5163e3130ac208d591b026d66870ce5a194f90b6) Thanks [@isco-tec](https://github.com/isco-tec)! - **`scorezilla/server` adopts a single-token secret-key format.** Breaking
+  change vs. v0.1.0-next.1; we're still in pre-release so this is permitted.
+
+  Before (v0.1.0-next.1):
+
+  ```ts
+  new Scorezilla({
+    secretKey: { id: 'sk-id-uuid', secret: 'sk_live_xxxxx' },
+  });
+  ```
+
+  After (v0.1.0-next.2):
+
+  ```ts
+  new Scorezilla({
+    secretKey: 'sk_live_<keyId>_xxxxx', // one self-contained token
+  });
+  ```
+
+  The keyId is embedded in the secret string itself; the SDK parses it
+  out via `/^sk_live_([0-9a-f]{8}-...)_/` before signing. The HMAC key
+  remains the WHOLE plaintext. Wire format on the Authorization header
+  is unchanged. API verification is unchanged.
+
+  Rationale: matches Stripe's design and the public-key client's
+  single-string shape. One value to copy from the dashboard, one to
+  manage in env config, one to pass into the constructor. Previously
+  users had to manage two distinct values (`id` AND `secret`) which
+  created confusion — they're functionally one credential.
+
+  **To upgrade**: issue (or rotate) a fresh secret key in the dashboard.
+  Old-format keys (no embedded keyId) are rejected by the SDK with a
+  clear error message pointing at the migration path.
+
+- [#30](https://github.com/isco-tec/scorezilla-js/pull/30) [`39fc70f`](https://github.com/isco-tec/scorezilla-js/commit/39fc70fa3a38bce619e87aa9f6179e79f1ae45ff) Thanks [@isco-tec](https://github.com/isco-tec)! - Handle HTTP 402 `usage_cap_exceeded` + observe API deprecation headers.
+
+  **402 / `usage_cap_exceeded`**: when the server returns 402 (tenant hit
+  their monthly submission cap or is suspended), the SDK now surfaces a
+  typed `ScorezillaError` with the full cap context:
+  - `err.code === 'usage_cap_exceeded'`
+  - `err.reason === 'over_cap' | 'suspended'`
+  - `err.tier`, `err.cap`, `err.count`, `err.period`, `err.resetsAt`
+  - `err.isUsageCapExceeded()` predicate
+  - `err.isSuspended()` predicate (distinguishes the suspended sub-case)
+  - `err.isTransient() === false` — no auto-retry (the cap doesn't lift
+    until `resetsAt`)
+
+  **Deprecation signals**: when an API response carries an RFC 8594
+  `Sunset` header or IETF `Deprecation` header, the SDK now logs a
+  once-per-process `console.warn` so developers see deprecation
+  notices during dev without prod-loop spam. The warning includes the
+  sunset date and any `Link: rel="deprecation"` documentation URL.
+
+  No breaking changes. New fields are additive; existing error handling
+  keeps working unchanged.
+
+### Patch Changes
+
+- [#31](https://github.com/isco-tec/scorezilla-js/pull/31) [`9376a2d`](https://github.com/isco-tec/scorezilla-js/commit/9376a2d93d4edb42decca1bcf495b83fc013c309) Thanks [@isco-tec](https://github.com/isco-tec)! - **Error mapping, retry-policy alignment, `AbortSignal` plumbing, injectable warn, validator-return tightening.**
+
+  Bundled correctness + ergonomics fixes from the in-house improvement-phase review:
+  - `ScorezillaError.code` now resolves to `'conflict'` on HTTP 409 responses (previously fell through to `'invalid_input'`). The error type already listed `'conflict'` as a valid code; the gap was in the status→code mapper. A new `e.isConflict()` predicate joins the existing `isAuth() / isNotFound() / isRateLimited() / isOutOfBounds() / isUsageCapExceeded() / isTransient()` family.
+  - `e.isTransient()` no longer flags `timeout` or `aborted` as transient — those are caller-observable terminal states, not retryable. The predicate is now aligned with the transport's actual retry policy (`shouldRetryError` in `retry.ts`), so consumer code mirroring "if (e.isTransient()) retry()" no longer loops on timeouts.
+  - All four public methods on **both** the public-key client (`Scorezilla`) and the secret-key server adapter (`Scorezilla` from `scorezilla/server`) now accept an optional `signal?: AbortSignal` via a shared `CancellableInput` shape, and forward it through the transport. Unblocks request-cancellation propagation under frameworks that thread cancellation through the request lifecycle (Next.js route handlers, Hono, Express middleware, React effect cleanup).
+  - New `warn?: (...args: unknown[]) => void` field on `ScorezillaConfig`. Defaults to `console.warn`. Pass your logger to route SDK deprecation notices into your observability stack, or pass `() => {}` to suppress them. Used today only for the `Deprecation` / `Sunset` once-per-process warning emitted when the API signals an upcoming sunset — at million-integration scale, embedders shouldn't have to console-filter our messages.
+  - `validateMetadata` now returns the serialized JSON string it computed (previously declared `void` despite a comment that claimed otherwise). Public callers that re-stringify metadata can reuse the value and skip a duplicate `JSON.stringify` pass on the hot submit path.
+
+  No breaking changes for callers that didn't rely on the two buggy classifications, didn't need cancellation, and didn't read `validateMetadata`'s return value.
+
+- [#28](https://github.com/isco-tec/scorezilla-js/pull/28) [`94b39d2`](https://github.com/isco-tec/scorezilla-js/commit/94b39d2e67ec7bba2681145560529f058acfc633) Thanks [@isco-tec](https://github.com/isco-tec)! - **Pre-release security hardening pass.** Three issues surfaced by a focused security review before the first public release of `scorezilla/server`:
+  - **HIGH — nonce injection.** `buildHmacAuthHeader` now requires injected nonces to be at least 16 characters. The default path (`crypto.randomUUID()`) is unaffected. Previously a misconfigured caller could pass `nonce: ''` and silently sign a header with no replay protection — the server has no minimum-length check, so the API would accept it. Now caught at SDK build-time with a clear error.
+  - **HIGH — server policy disclosure.** `HMAC_TIMESTAMP_WINDOW_SECONDS = 300` was previously exported as documentation of the API's clock-skew tolerance. Removed from the public API — publishing the server's replay-protection window in the SDK's types was unnecessary information disclosure and narrowed the pre-computation window for any future timestamp-forgery work. The SDK has no behavioral dependency on the value (it always emits a fresh `ts = floor(Date.now() / 1000)`).
+  - **MEDIUM — `EdgeRuntime` polyfill bypass.** The server adapter's runtime browser-guard previously trusted `globalThis.EdgeRuntime` as a "this is a server" signal. A browser extension or bundler misconfig setting that global would have bypassed the guard. Removed from the trusted set — the package's `exports.browser` condition remains the primary gate, and the runtime check now refuses to trust globals that can be polyfilled from a browser context. Real Vercel Edge runtimes still pass the guard because they don't have `window`/`document`.
+
+  No external-attack surface was exploitable; all three are self-inflicted/defense-in-depth issues caught before the first stable release. Tests added: 4 for nonce validation (rejects empty / too-short, accepts at-floor / default UUID), 1 for the EdgeRuntime polyfill scenario.
+
 ## 0.1.0-next.3
 
 ### Minor Changes

package/README.md

@@ -43,6 +43,19 @@ yarn add scorezilla
 bun add scorezilla
 ```
 
+## Get your keys
+
+The Quickstart below needs two values: a `publicKey` and a `boardId`. Both come from the dashboard:
+
+1. **Sign in** at [dashboard.scorezilla.dev](https://dashboard.scorezilla.dev) (magic-link email — no password).
+2. **Open the Tutorial Game** that's created for you on first sign-in (or create a new game).
+3. **Open Keys → Issue public key**. Copy the `pk_*` string (shown once — also visible in the keys list afterwards).
+4. **Open Boards → New board** (or use the auto-created "High Scores"). Copy the `boardId` UUID.
+
+You're now ready for the Quickstart below. **Public keys are safe to ship in client code** — they only authorize submits, not key rotation or board admin.
+
+> Using AI to scaffold? Skip the manual steps: install the [Scorezilla MCP server](https://github.com/isco-tec/scorezilla-mcp) in Claude Code / Cursor and run `bootstrap_leaderboard` — the AI gets your keys + board id + a ready-to-paste integration snippet in one tool call.
+
 ## Quickstart
 
 ```ts

package/dist/{errors-CUAQsaVS.d.cts → errors-B7hyC-C5.d.cts}

@@ -37,6 +37,13 @@ interface BaseConfig {
      *  this unset to use the default exponential backoff with jitter.
      *  @internal */
     sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Inject a sink for SDK deprecation warnings. Defaults to
+     *  `console.warn`. Pass your logger's `warn` to route SDK signals into
+     *  the rest of your observability stack, or pass `() => {}` to
+     *  suppress them. The SDK uses this ONLY for developer-visible
+     *  deprecation notices triggered by `Deprecation` / `Sunset` response
+     *  headers — never for runtime errors. */
+    warn?: (...args: unknown[]) => void;
 }
 /** Public-key auth: browser-safe path. The key is fingerprinted to a game
  *  on the server side via `pk_<gameSlug>_<base62>`. */
@@ -86,9 +93,22 @@ type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
  *
  * @stable v0.1.0
  */
-type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error'
+/** 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 & {});
 /** 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.
+ *  - `'over_cap'`   — tenant hit their tier's monthly submit limit
+ *  - `'suspended'`  — tenant's `billing_status` is `'suspended'`; every
+ *                     submit is rejected (cap is structurally 0)
+ *  Open union for forward compatibility.
+ */
+type UsageCapReason = 'over_cap' | 'suspended' | (string & {});
+/** Tier identifier mirrored from the server's `PlanConfig.key`. */
+type BillingTier = 'free' | 'indie' | 'pro' | 'studio' | 'enterprise' | 'suspended' | (string & {});
 /** Successful API response envelope. The `T` is the per-route payload. */
 type ApiSuccess<T> = {
     ok: true;
@@ -107,6 +127,21 @@ interface ApiError {
     layer?: string;
     /** The limit value that was crossed — present on `out_of_bounds`. */
     bound?: number;
+    /** Tenant's tier at the time of rejection. */
+    tier?: BillingTier;
+    /** The cap value that was crossed (monthly submit limit). `0` for
+     *  suspended tenants; `null` is never sent (enterprise has no cap and
+     *  can never be over). */
+    cap?: number;
+    /** The post-increment submit count when the cap was crossed. Always
+     *  > `cap` when `reason === 'over_cap'`. */
+    count?: number;
+    /** The period the count belongs to, in `YYYY-MM` UTC form. */
+    period?: string;
+    /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+     *  when the counter resets. Lets clients compute `Retry-After` without
+     *  parsing dates server-side. */
+    resetsAt?: string;
 }
 /** Discriminated envelope: every API response is one of these two shapes. */
 type ApiResponse<T> = ApiSuccess<T> | ApiError;
@@ -230,9 +265,11 @@ declare class ScorezillaError extends Error {
      *  {@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'`)
+    /** 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 | string | undefined;
+    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;
@@ -243,6 +280,20 @@ declare class ScorezillaError extends Error {
     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. */
@@ -255,19 +306,42 @@ declare class ScorezillaError extends Error {
         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 transient / retryable conditions: network errors, timeouts,
-     *  5xx, and 429. The transport layer relies on this for its retry policy. */
+    /** `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.
      *

package/dist/{errors-CUAQsaVS.d.ts → errors-B7hyC-C5.d.ts}

@@ -37,6 +37,13 @@ interface BaseConfig {
      *  this unset to use the default exponential backoff with jitter.
      *  @internal */
     sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Inject a sink for SDK deprecation warnings. Defaults to
+     *  `console.warn`. Pass your logger's `warn` to route SDK signals into
+     *  the rest of your observability stack, or pass `() => {}` to
+     *  suppress them. The SDK uses this ONLY for developer-visible
+     *  deprecation notices triggered by `Deprecation` / `Sunset` response
+     *  headers — never for runtime errors. */
+    warn?: (...args: unknown[]) => void;
 }
 /** Public-key auth: browser-safe path. The key is fingerprinted to a game
  *  on the server side via `pk_<gameSlug>_<base62>`. */
@@ -86,9 +93,22 @@ type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
  *
  * @stable v0.1.0
  */
-type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error'
+/** 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 & {});
 /** 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.
+ *  - `'over_cap'`   — tenant hit their tier's monthly submit limit
+ *  - `'suspended'`  — tenant's `billing_status` is `'suspended'`; every
+ *                     submit is rejected (cap is structurally 0)
+ *  Open union for forward compatibility.
+ */
+type UsageCapReason = 'over_cap' | 'suspended' | (string & {});
+/** Tier identifier mirrored from the server's `PlanConfig.key`. */
+type BillingTier = 'free' | 'indie' | 'pro' | 'studio' | 'enterprise' | 'suspended' | (string & {});
 /** Successful API response envelope. The `T` is the per-route payload. */
 type ApiSuccess<T> = {
     ok: true;
@@ -107,6 +127,21 @@ interface ApiError {
     layer?: string;
     /** The limit value that was crossed — present on `out_of_bounds`. */
     bound?: number;
+    /** Tenant's tier at the time of rejection. */
+    tier?: BillingTier;
+    /** The cap value that was crossed (monthly submit limit). `0` for
+     *  suspended tenants; `null` is never sent (enterprise has no cap and
+     *  can never be over). */
+    cap?: number;
+    /** The post-increment submit count when the cap was crossed. Always
+     *  > `cap` when `reason === 'over_cap'`. */
+    count?: number;
+    /** The period the count belongs to, in `YYYY-MM` UTC form. */
+    period?: string;
+    /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+     *  when the counter resets. Lets clients compute `Retry-After` without
+     *  parsing dates server-side. */
+    resetsAt?: string;
 }
 /** Discriminated envelope: every API response is one of these two shapes. */
 type ApiResponse<T> = ApiSuccess<T> | ApiError;
@@ -230,9 +265,11 @@ declare class ScorezillaError extends Error {
      *  {@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'`)
+    /** 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 | string | undefined;
+    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;
@@ -243,6 +280,20 @@ declare class ScorezillaError extends Error {
     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. */
@@ -255,19 +306,42 @@ declare class ScorezillaError extends Error {
         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 transient / retryable conditions: network errors, timeouts,
-     *  5xx, and 429. The transport layer relies on this for its retry policy. */
+    /** `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.
      *