scorezilla 0.1.0-next.3 → 0.3.0-next.0

package/dist/server.cjs

@@ -152,7 +152,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
@@ -165,6 +167,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. */
@@ -179,6 +195,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") {
@@ -192,6 +213,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";
@@ -204,13 +241,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.
@@ -231,6 +276,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
       });
@@ -272,8 +324,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";
@@ -384,6 +438,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);
@@ -495,6 +550,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;
@@ -552,7 +630,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.3.0-next.0";
   #keyId;
   #secret;
   #baseUrl;
@@ -564,6 +642,7 @@ var Scorezilla = class _Scorezilla {
   #timeoutMs;
   #maxRetries;
   #sleepImpl;
+  #warnImpl;
   #userAgent;
   constructor(config) {
     if (isRealBrowserEnvironment()) {
@@ -586,6 +665,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);
   }
   /**
@@ -610,7 +690,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. */
@@ -620,14 +701,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. */
@@ -637,7 +720,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
     });
   }
   /**
@@ -668,7 +752,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 = {