scorezilla 0.1.0-next.1 → 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-Bp9ZDYqm.js';
-export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-Bp9ZDYqm.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 {
@@ -120,6 +126,15 @@ declare class Scorezilla {
     /**
      * Submit a score to a board. Signed end-to-end — the API verifies
      * before any state change.
+     *
+     * **Behavioral note vs. the public-key client**: the server adapter
+     * does NOT perform local `metadata` validation. The public-key
+     * client (`scorezilla`) validates size + structure client-side and
+     * fails fast; the server adapter relies on the API to reject
+     * malformed metadata with `invalid_input`. Trade-off: smaller bundle
+     * + simpler server-side logic vs. one extra network round-trip on
+     * caller mistakes. If you want fast-fail behavior, validate metadata
+     * yourself before calling this method.
      */
     submitScore(input: SubmitScoreInput): Promise<ApiSuccess<SubmitScoreResponse>>;
     /** Fetch the top-N entries on a board. */
@@ -130,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

@@ -1,34 +1,46 @@
 // src/config.ts
 var DEFAULT_BASE_URL = "https://api.scorezilla.dev";
 var SECRET_KEY_PREFIX = "sk_live_";
+var SECRET_KEY_PATTERN = /^sk_live_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})_[A-Za-z0-9]+$/;
 function validateSecretKey(cfg) {
   if (!cfg || typeof cfg !== "object") {
     throw new Error("scorezilla/server: config must be an object with a secretKey field");
   }
   const sk = cfg.secretKey;
-  if (!sk || typeof sk !== "object" || typeof sk.id !== "string" || typeof sk.secret !== "string") {
-    throw new Error("scorezilla/server: secretKey must be an object with string `id` and `secret`");
-  }
-  if (sk.id.length === 0) {
-    throw new Error("scorezilla/server: secretKey.id must be a non-empty string");
+  if (typeof sk !== "string") {
+    throw new Error(
+      `scorezilla/server: secretKey must be a single string of the shape ${SECRET_KEY_PREFIX}<keyId>_<random> (got: ${typeof sk})`
+    );
   }
-  if (!sk.secret.startsWith(SECRET_KEY_PREFIX)) {
-    const shape = `string of length ${sk.secret.length}`;
+  const match = SECRET_KEY_PATTERN.exec(sk);
+  if (!match) {
+    const shape = `string of length ${sk.length}`;
     throw new Error(
-      `scorezilla/server: secretKey.secret must start with "${SECRET_KEY_PREFIX}" (live keys only) (got: ${shape})`
+      `scorezilla/server: secretKey must match ${SECRET_KEY_PATTERN.toString()} (got: ${shape}). v0.1.0-next.2 switched to a single-token format \u2014 if you have a pre-next.2 pair, issue a fresh key in the dashboard to upgrade.`
     );
   }
-  return { keyId: sk.id, secret: sk.secret };
+  return { keyId: match[1], secret: sk };
 }
 
 // src/hmac.ts
 var enc = new TextEncoder();
 var HMAC_AUTH_SCHEME = "Scorezilla-HMAC-SHA256";
-async function buildSigningString(method, pathAndQuery, ts, nonce, body) {
+var MIN_NONCE_LENGTH = 16;
+var HMAC_SIGNING_VERSION_LATEST = 2;
+async function buildSigningString(method, pathAndQuery, ts, nonce, body, host, version = HMAC_SIGNING_VERSION_LATEST) {
   const bodyHash = await sha256Hex(body);
+  const upperMethod = method.toUpperCase();
+  if (version === 1) {
+    return `${ts}
+${nonce}
+${upperMethod}
+${pathAndQuery}
+${bodyHash}`;
+  }
   return `${ts}
 ${nonce}
-${method.toUpperCase()}
+${upperMethod}
+${host.toLowerCase()}
 ${pathAndQuery}
 ${bodyHash}`;
 }
@@ -49,16 +61,27 @@ async function sha256Hex(message) {
 }
 async function buildHmacAuthHeader(args) {
   const ts = args.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  if (args.nonce !== void 0) {
+    if (typeof args.nonce !== "string" || args.nonce.length < MIN_NONCE_LENGTH) {
+      throw new Error(
+        `scorezilla: nonce must be a string of at least ${MIN_NONCE_LENGTH} characters; use the default (UUIDv4 via crypto.randomUUID) unless you have a specific reason.`
+      );
+    }
+  }
   const nonce = args.nonce ?? generateNonce();
+  const version = args.version ?? HMAC_SIGNING_VERSION_LATEST;
   const signingString = await buildSigningString(
     args.method,
     args.pathAndQuery,
     ts,
     nonce,
-    args.body
+    args.body,
+    args.host,
+    version
   );
   const signature = await hmacSha256B64u(args.secret, signingString);
-  return `${HMAC_AUTH_SCHEME} keyId=${args.keyId}, ts=${ts}, nonce=${nonce}, signature=${signature}`;
+  const vParam = version === 1 ? "" : `, v=${version}`;
+  return `${HMAC_AUTH_SCHEME} keyId=${args.keyId}, ts=${ts}, nonce=${nonce}, signature=${signature}${vParam}`;
 }
 function generateNonce() {
   const c = globalThis.crypto;
@@ -127,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
@@ -140,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. */
@@ -154,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") {
@@ -167,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";
@@ -179,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.
@@ -206,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
       });
@@ -247,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";
@@ -359,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);
@@ -470,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;
@@ -527,27 +628,56 @@ 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.1";
+  static version = "0.2.0";
   #keyId;
   #secret;
   #baseUrl;
+  /** Host portion of `#baseUrl` (e.g. "api.scorezilla.dev"). Captured at
+   *  construction so every signed request binds to this exact origin —
+   *  see `buildSigningString` v=2 in `hmac.ts`. */
+  #host;
   #fetchImpl;
   #timeoutMs;
   #maxRetries;
+  #sleepImpl;
+  #warnImpl;
   #userAgent;
   constructor(config) {
+    if (isRealBrowserEnvironment()) {
+      throw new Error(
+        "scorezilla/server: this adapter is server-only and must not run in browsers. Your bundler is shipping `scorezilla/server` into a browser bundle \u2014 check that it honors the `browser` export condition in package.json. Use the public-key client (`import { Scorezilla } from 'scorezilla'`) from browser code."
+      );
+    }
     const resolved = validateSecretKey(config);
     this.#keyId = resolved.keyId;
     this.#secret = resolved.secret;
     this.#baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    try {
+      this.#host = new URL(this.#baseUrl).host;
+    } catch {
+      throw new Error(
+        `scorezilla/server: baseUrl must be a valid absolute URL (got: ${this.#baseUrl})`
+      );
+    }
     this.#fetchImpl = config.fetch;
     this.#timeoutMs = config.timeoutMs;
     this.#maxRetries = config.maxRetries;
+    this.#sleepImpl = config.sleepImpl;
+    this.#warnImpl = config.warn;
     this.#userAgent = config.userAgent ?? defaultUserAgent(_Scorezilla.version);
   }
   /**
    * Submit a score to a board. Signed end-to-end — the API verifies
    * before any state change.
+   *
+   * **Behavioral note vs. the public-key client**: the server adapter
+   * does NOT perform local `metadata` validation. The public-key
+   * client (`scorezilla`) validates size + structure client-side and
+   * fails fast; the server adapter relies on the API to reject
+   * malformed metadata with `invalid_input`. Trade-off: smaller bundle
+   * + simpler server-side logic vs. one extra network round-trip on
+   * caller mistakes. If you want fast-fail behavior, validate metadata
+   * yourself before calling this method.
    */
   async submitScore(input) {
     return this.#request({
@@ -558,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. */
@@ -568,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. */
@@ -585,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
     });
   }
   /**
@@ -611,18 +745,31 @@ var Scorezilla = class _Scorezilla {
         secret: this.#secret,
         method,
         pathAndQuery,
+        host: this.#host,
         body
       })
     };
     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) {
-      requestOpts.retry = { maxRetries: this.#maxRetries };
+    if (this.#maxRetries !== void 0 || this.#sleepImpl !== void 0) {
+      requestOpts.retry = {
+        ...this.#maxRetries !== void 0 ? { maxRetries: this.#maxRetries } : {},
+        ...this.#sleepImpl !== void 0 ? { sleepImpl: this.#sleepImpl } : {}
+      };
     }
     return request(requestOpts);
   }
 };
+function isRealBrowserEnvironment() {
+  const g = globalThis;
+  const hasBrowserGlobals = typeof g.window !== "undefined" && typeof g.document !== "undefined";
+  if (!hasBrowserGlobals) return false;
+  const hasNodeLikeHost = Boolean(g.process?.versions?.node) || typeof g.Deno !== "undefined" || typeof g.Bun !== "undefined";
+  return !hasNodeLikeHost;
+}
 
 export { Scorezilla, ScorezillaError };
 //# sourceMappingURL=server.js.map