scorezilla 0.1.0-next.3 → 0.2.0

package/dist/index.cjs

@@ -33,6 +33,7 @@ function validateConfig(cfg) {
     timeoutMs: cfg.timeoutMs,
     maxRetries: cfg.maxRetries,
     sleepImpl: cfg.sleepImpl,
+    warn: cfg.warn,
     userAgent: cfg.userAgent,
     auth
   };
@@ -119,7 +120,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
@@ -132,6 +135,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. */
@@ -146,6 +163,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") {
@@ -159,6 +181,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";
@@ -171,13 +209,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.
@@ -198,6 +244,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
       });
@@ -239,8 +292,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";
@@ -351,6 +406,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);
@@ -462,6 +518,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,10 +629,11 @@ function validateMetadata(metadata) {
       `scorezilla: metadata exceeds ${METADATA_MAX_BYTES} bytes (got ${byteLength} bytes when JSON-stringified)`
     );
   }
+  return serialized;
 }
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`. */
-  static version = "0.1.0-next.3";
+  static version = "0.2.0";
   #config;
   #userAgent;
   #authHeader;
@@ -611,7 +691,8 @@ var Scorezilla = class _Scorezilla {
     return this.#request({
       path: submitScorePath(input.boardId),
       method: "POST",
-      body
+      body,
+      signal: input.signal
     });
   }
   /**
@@ -635,7 +716,8 @@ var Scorezilla = class _Scorezilla {
     if (input.offset !== void 0) q.offset = input.offset;
     return this.#request({
       path: getLeaderboardPath(input.boardId, q),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /**
@@ -664,7 +746,8 @@ var Scorezilla = class _Scorezilla {
   async getPlayerRank(input) {
     return this.#request({
       path: getPlayerRankPath(input.boardId, input.playerId),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /**
@@ -689,7 +772,8 @@ var Scorezilla = class _Scorezilla {
     if (input.after !== void 0) q.after = input.after;
     return this.#request({
       path: getWindowAroundPath(input.boardId, input.playerId, q),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   // ─── Internal ────────────────────────────────────────────────────────
@@ -716,7 +800,9 @@ var Scorezilla = class _Scorezilla {
       headers
     };
     if (opts.body !== void 0) requestOpts.body = opts.body;
+    if (opts.signal !== void 0) requestOpts.signal = opts.signal;
     if (this.#config.fetch !== void 0) requestOpts.fetchImpl = this.#config.fetch;
+    if (this.#config.warn !== void 0) requestOpts.warnImpl = this.#config.warn;
     if (this.#config.timeoutMs !== void 0) requestOpts.timeoutMs = this.#config.timeoutMs;
     if (this.#config.maxRetries !== void 0 || this.#config.sleepImpl !== void 0) {
       requestOpts.retry = {
@@ -732,7 +818,7 @@ function createClient(config) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.1.0-next.3";
+var SDK_VERSION = "0.2.0";
 
 exports.SDK_VERSION = SDK_VERSION;
 exports.Scorezilla = Scorezilla;