scorezilla 0.1.0-next.3 → 0.2.0

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { S as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-CUAQsaVS.js';
-export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-CUAQsaVS.js';
+import { S as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-B7hyC-C5.js';
+export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-B7hyC-C5.js';
 
 /**
  * `scorezilla/server` — HMAC-signed adapter for game backends (#17, v0.2.0).
@@ -20,11 +20,14 @@ export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from
  * -----------------------------------------
  * The method shape is intentionally identical — `submitScore`,
  * `getLeaderboard`, `getPlayerRank`, `getWindowAround`. The only
- * difference at the call site is the constructor argument:
+ * difference at the call site is the constructor argument: a single
+ * `sk_live_<keyId>_<random>` token replaces the public key (Stripe-
+ * style single-token format; the keyId is embedded in the plaintext
+ * so consumers manage one value, not two):
  *
  *   import { Scorezilla } from 'scorezilla/server';
  *   const sz = new Scorezilla({
- *     secretKey: { id: 'sk-id-abc', secret: 'sk_live_…' },
+ *     secretKey: process.env.SCOREZILLA_SECRET_KEY!, // sk_live_<keyId>_<random>
  *   });
  *
  * Behind the scenes:
@@ -43,8 +46,14 @@ export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from
  * secret key MUST NEVER leave the server.
  */
 
+/** Caller-cancellable common shape — server-side too. */
+interface CancellableInput {
+    /** Optional `AbortSignal` to cancel mid-flight. The transport composes
+     *  it with the per-attempt timeout, so aborting always wins. */
+    signal?: AbortSignal | undefined;
+}
 /** Input for {@link Scorezilla.submitScore}. */
-interface SubmitScoreInput {
+interface SubmitScoreInput extends CancellableInput {
     /** UUID-typed board identifier — issued by the operator dashboard. */
     boardId: string;
     /** Stable per-player identifier (UUID, your account ID, etc.). Avoid PII. */
@@ -56,7 +65,7 @@ interface SubmitScoreInput {
     metadata?: Record<string, unknown> | undefined;
 }
 /** Input for {@link Scorezilla.getLeaderboard}. */
-interface GetLeaderboardInput {
+interface GetLeaderboardInput extends CancellableInput {
     boardId: string;
     /** Number of entries (API caps at 1000; default 100). */
     top?: number | undefined;
@@ -64,12 +73,12 @@ interface GetLeaderboardInput {
     offset?: number | undefined;
 }
 /** Input for {@link Scorezilla.getPlayerRank}. */
-interface GetPlayerRankInput {
+interface GetPlayerRankInput extends CancellableInput {
     boardId: string;
     playerId: string;
 }
 /** Input for {@link Scorezilla.getWindowAround}. */
-interface GetWindowAroundInput {
+interface GetWindowAroundInput extends CancellableInput {
     boardId: string;
     playerId: string;
     /** Entries strictly above the player (API caps at 100; default 5). */
@@ -90,10 +99,7 @@ interface GetWindowAroundInput {
  * import { Scorezilla, ScorezillaError } from 'scorezilla/server';
  *
  * const sz = new Scorezilla({
- *   secretKey: {
- *     id:     process.env.SCOREZILLA_KEY_ID!,
- *     secret: process.env.SCOREZILLA_KEY_SECRET!,
- *   },
+ *   secretKey: process.env.SCOREZILLA_SECRET_KEY!, // sk_live_<keyId>_<random>
  * });
  *
  * try {
@@ -139,4 +145,4 @@ declare class Scorezilla {
     getWindowAround(input: GetWindowAroundInput): Promise<ApiSuccess<WindowAroundResponse>>;
 }
 
-export { ApiSuccess, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, LeaderboardResponse, PlayerRankResponse, Scorezilla, type SubmitScoreInput, SubmitScoreResponse, WindowAroundResponse };
+export { ApiSuccess, type CancellableInput, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, LeaderboardResponse, PlayerRankResponse, Scorezilla, type SubmitScoreInput, SubmitScoreResponse, WindowAroundResponse };

package/dist/server.js

@@ -150,7 +150,9 @@ var ScorezillaError = class _ScorezillaError extends Error {
    *  {@link ScorezillaErrorCode}. For network errors, this is `'network_error'`;
    *  for aborts, `'aborted'`; for timeouts, `'timeout'`. */
   code;
-  /** 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. */
   reason;
   /** Seconds — present on `rate_limited`. Honored by the transport's retry
@@ -163,6 +165,20 @@ var ScorezillaError = class _ScorezillaError extends Error {
   bound;
   /** Which rate-limit layer fired on `rate_limited`. */
   layer;
+  /** Tenant's billing tier — present on `usage_cap_exceeded`. */
+  tier;
+  /** The cap value crossed on `usage_cap_exceeded`. `0` indicates a
+   *  suspended tenant. `undefined` on all other error codes. */
+  cap;
+  /** The post-increment submit count on `usage_cap_exceeded`. Always
+   *  `> cap` when `reason === 'over_cap'`. */
+  count;
+  /** The period the count belongs to on `usage_cap_exceeded`, in `YYYY-MM`
+   *  UTC form. */
+  period;
+  /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+   *  the counter's natural reset point on `usage_cap_exceeded`. */
+  resetsAt;
   /** 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. */
@@ -177,6 +193,11 @@ var ScorezillaError = class _ScorezillaError extends Error {
     this.requestId = truncateField(init.requestId);
     this.bound = init.bound;
     this.layer = truncateField(init.layer);
+    this.tier = truncateField(init.tier);
+    this.cap = init.cap;
+    this.count = init.count;
+    this.period = truncateField(init.period);
+    this.resetsAt = truncateField(init.resetsAt);
     this.cause = init.cause;
     Object.setPrototypeOf(this, _ScorezillaError.prototype);
     if (typeof Error.captureStackTrace === "function") {
@@ -190,6 +211,22 @@ var ScorezillaError = class _ScorezillaError extends Error {
   isRateLimited() {
     return this.code === "rate_limited";
   }
+  /**
+   * `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() {
+    return this.code === "usage_cap_exceeded";
+  }
+  /** `true` when this error is a 402 + reason 'suspended' (vs over-cap). */
+  isSuspended() {
+    return this.code === "usage_cap_exceeded" && this.reason === "suspended";
+  }
   /** `true` when this error is a 401 / `unauthorized` (or 403 / `forbidden`). */
   isAuth() {
     return this.code === "unauthorized" || this.code === "forbidden";
@@ -202,13 +239,21 @@ var ScorezillaError = class _ScorezillaError extends Error {
   isOutOfBounds() {
     return this.code === "out_of_bounds";
   }
-  /** `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() {
-    if (this.status === STATUS_NETWORK_ERROR) return true;
+    if (this.code === "network_error") return true;
     if (this.status >= 500 && this.status < 600) return true;
     return this.isRateLimited();
   }
+  /** `true` when this error is a 409 / `conflict` (idempotency-key conflict
+   *  on retry). */
+  isConflict() {
+    return this.code === "conflict";
+  }
   // ─── Factory ─────────────────────────────────────────────────────────
   /**
    * Build a `ScorezillaError` from a fetch round-trip outcome.
@@ -229,6 +274,13 @@ var ScorezillaError = class _ScorezillaError extends Error {
         retryAfter: body.retryAfter,
         bound: body.bound,
         layer: body.layer,
+        // Usage-cap fields from `ApiError` (populated by the server on
+        // 402 responses; undefined on other errors).
+        tier: body.tier,
+        cap: body.cap,
+        count: body.count,
+        period: body.period,
+        resetsAt: body.resetsAt,
         requestId,
         cause
       });
@@ -270,8 +322,10 @@ var ScorezillaError = class _ScorezillaError extends Error {
 };
 function codeForStatus(status) {
   if (status === 401) return "unauthorized";
+  if (status === 402) return "usage_cap_exceeded";
   if (status === 403) return "forbidden";
   if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
   if (status === 422) return "out_of_bounds";
   if (status === 429) return "rate_limited";
   if (status >= 500) return "internal_error";
@@ -382,6 +436,7 @@ async function request(opts) {
       }
       const response = await fetchImpl(url, init);
       if (response.ok) {
+        warnOnDeprecationOnce(response, opts.warnImpl);
         return await parseJson(response);
       }
       const body = await safelyParseErrorBody(response);
@@ -493,6 +548,29 @@ function readRetryAfter(response) {
   const n = Number(raw);
   return Number.isFinite(n) && n >= 0 ? n : void 0;
 }
+var seenDeprecations = /* @__PURE__ */ new Set();
+function warnOnDeprecationOnce(response, warnImpl) {
+  const deprecation = response.headers.get("Deprecation");
+  const sunset = response.headers.get("Sunset");
+  if (!deprecation && !sunset) return;
+  const link = response.headers.get("Link") ?? "";
+  const key = `${deprecation ?? ""}|${sunset ?? ""}|${link}`;
+  if (seenDeprecations.has(key)) return;
+  seenDeprecations.add(key);
+  const detail = [];
+  if (deprecation === "true" || deprecation) detail.push(`Deprecation: ${deprecation}`);
+  if (sunset) detail.push(`Sunset: ${sunset}`);
+  if (link) {
+    const m = link.match(/<([^>]+)>/);
+    if (m) detail.push(`Docs: ${m[1]}`);
+  }
+  const message = `[scorezilla-sdk] API responded with deprecation signal: ${detail.join(" \xB7 ")}. Upgrade your SDK before the sunset date.`;
+  if (warnImpl) {
+    warnImpl(message);
+  } else {
+    console.warn(message);
+  }
+}
 function combineSignalsWithTimeout(caller, timeoutMs) {
   const ctrl = new AbortController();
   let didTimeOut = false;
@@ -550,7 +628,7 @@ var Scorezilla = class _Scorezilla {
    *  Mirrors the static on the public-key client so consumers can log
    *  the running SDK build the same way regardless of which surface
    *  they imported. */
-  static version = "0.1.0-next.3";
+  static version = "0.2.0";
   #keyId;
   #secret;
   #baseUrl;
@@ -562,6 +640,7 @@ var Scorezilla = class _Scorezilla {
   #timeoutMs;
   #maxRetries;
   #sleepImpl;
+  #warnImpl;
   #userAgent;
   constructor(config) {
     if (isRealBrowserEnvironment()) {
@@ -584,6 +663,7 @@ var Scorezilla = class _Scorezilla {
     this.#timeoutMs = config.timeoutMs;
     this.#maxRetries = config.maxRetries;
     this.#sleepImpl = config.sleepImpl;
+    this.#warnImpl = config.warn;
     this.#userAgent = config.userAgent ?? defaultUserAgent(_Scorezilla.version);
   }
   /**
@@ -608,7 +688,8 @@ var Scorezilla = class _Scorezilla {
         playerId: input.playerId,
         score: input.score,
         ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
-      }
+      },
+      signal: input.signal
     });
   }
   /** Fetch the top-N entries on a board. */
@@ -618,14 +699,16 @@ var Scorezilla = class _Scorezilla {
         ...input.top !== void 0 ? { top: input.top } : {},
         ...input.offset !== void 0 ? { offset: input.offset } : {}
       }),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /** Look up a single player's rank on a board. */
   async getPlayerRank(input) {
     return this.#request({
       path: getPlayerRankPath(input.boardId, input.playerId),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /** Fetch the slice of entries surrounding a player. */
@@ -635,7 +718,8 @@ var Scorezilla = class _Scorezilla {
         ...input.before !== void 0 ? { before: input.before } : {},
         ...input.after !== void 0 ? { after: input.after } : {}
       }),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /**
@@ -666,7 +750,9 @@ var Scorezilla = class _Scorezilla {
       })
     };
     if (opts.body !== void 0) requestOpts.body = opts.body;
+    if (opts.signal !== void 0) requestOpts.signal = opts.signal;
     if (this.#fetchImpl !== void 0) requestOpts.fetchImpl = this.#fetchImpl;
+    if (this.#warnImpl !== void 0) requestOpts.warnImpl = this.#warnImpl;
     if (this.#timeoutMs !== void 0) requestOpts.timeoutMs = this.#timeoutMs;
     if (this.#maxRetries !== void 0 || this.#sleepImpl !== void 0) {
       requestOpts.retry = {