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

package/dist/errors-CUAQsaVS.d.ts

@@ -0,0 +1,292 @@
+/** Minimal fetch shape — broader than `typeof fetch` so polyfills and
+ *  test stubs (`vi.fn()`, `node-fetch`, etc.) typecheck cleanly. */
+type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * SDK configuration.
+ *
+ * The `ScorezillaConfig` is a TypeScript-level discriminated union of
+ * `PublicKeyConfig` and `SecretKeyConfig`. The mutual-exclusivity (you may
+ * pass `publicKey` OR `secretKey`, never both) is enforced at compile time:
+ * passing both fields fails type-checking before the runtime check fires.
+ *
+ * The runtime check in {@link validateConfig} is the second line of defense
+ * for consumers using plain JS or `as any` casts.
+ */
+
+/** Shared options across both auth modes. */
+interface BaseConfig {
+    /** API base URL (no trailing slash required). Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Custom fetch implementation — defaults to `globalThis.fetch`. Pass
+     *  `node-fetch`, `undici`, or a mock here. The explicit signature
+     *  (`(RequestInfo | URL, init?) => Promise<Response>`) is broader than
+     *  `typeof fetch` so common polyfills typecheck cleanly. */
+    fetch?: FetchImpl;
+    /** Per-request timeout in milliseconds. Defaults to 30 s. */
+    timeoutMs?: number;
+    /** Maximum retry attempts on transient failures. Defaults to 2 (so the
+     *  worst-case total request count is 3). */
+    maxRetries?: number;
+    /** Override the default `User-Agent` header (Node/Workers/Bun/Deno —
+     *  browsers silently ignore the value). */
+    userAgent?: string;
+    /** Injectable sleep implementation for the retry loop's inter-attempt
+     *  pause. Exists for tests that need deterministic, zero-delay retries
+     *  rather than real wall-clock backoff. Production code should leave
+     *  this unset to use the default exponential backoff with jitter.
+     *  @internal */
+    sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Public-key auth: browser-safe path. The key is fingerprinted to a game
+ *  on the server side via `pk_<gameSlug>_<base62>`. */
+type PublicKeyConfig = BaseConfig & {
+    publicKey: string;
+    secretKey?: never;
+};
+/** Secret-key auth: server-side HMAC. A single self-contained token of the
+ *  shape `sk_live_<keyId>_<random>`. The SDK parses the keyId out and uses
+ *  the whole string as the HMAC key. One value to copy, one to manage —
+ *  matches Stripe's design and the public-key client's single-string shape.
+ *
+ *  Past versions of the SDK took `{ id, secret }` separately. That was an
+ *  unnecessary cognitive tax — the id was always derivable from a properly-
+ *  formatted secret. v0.1.0-next.2+ takes the single-string form. */
+type SecretKeyConfig = BaseConfig & {
+    secretKey: string;
+    publicKey?: never;
+};
+/** The top-level config type. The union is open for additional auth modes
+ *  in future major releases. */
+type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
+
+/**
+ * Wire types for the Scorezilla API at /v1.
+ *
+ * Mirrors the documented response shapes. TypeScript's structural typing
+ * means additional fields the server adds in a minor release won't break
+ * consumers — see VERSIONING.md for the full SemVer contract.
+ *
+ * No Zod or other runtime validators in v0.1.0 — keeps the bundle small.
+ * Narrow untrusted input with the {@link isApiSuccess} / {@link isApiError}
+ * type guards exported below.
+ */
+/**
+ * Machine-stable error codes returned by the API.
+ *
+ * Consumers MUST branch on this `code` rather than the human-readable
+ * `message` — message text is English-only and explicitly NOT part of the
+ * SemVer contract.
+ *
+ * The union is intentionally open (`| (string & {})`) so unknown future
+ * codes from a server-side minor release don't compile-error against the
+ * SDK. The trick preserves autocomplete on the known set while permitting
+ * arbitrary strings at runtime — see
+ * https://github.com/microsoft/TypeScript/issues/29729 for the pattern.
+ *
+ * @stable v0.1.0
+ */
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+/** Reason sub-classifier on `out_of_bounds` errors. Open union — see {@link ScorezillaErrorCode}. */
+type OutOfBoundsReason = 'below_min' | 'above_max' | (string & {});
+/** Successful API response envelope. The `T` is the per-route payload. */
+type ApiSuccess<T> = {
+    ok: true;
+} & T;
+/** Failure response envelope. The server returns this on every non-2xx response. */
+interface ApiError {
+    ok: false;
+    error: ScorezillaErrorCode;
+    /** Human-readable, English only. Not machine-stable — branch on `error` and `reason`. */
+    message?: string;
+    /** Sub-classifier — used by `out_of_bounds` (`'below_min' | 'above_max'`). */
+    reason?: string;
+    /** Seconds — present on `rate_limited`. Also mirrored in the HTTP `Retry-After` header. */
+    retryAfter?: number;
+    /** Which rate-limit layer fired — present on `rate_limited`. */
+    layer?: string;
+    /** The limit value that was crossed — present on `out_of_bounds`. */
+    bound?: number;
+}
+/** Discriminated envelope: every API response is one of these two shapes. */
+type ApiResponse<T> = ApiSuccess<T> | ApiError;
+/**
+ * A single ranked entry on a leaderboard.
+ *
+ * Returned as an array on `leaderboard` and `window-around` responses, and
+ * inline on `playerRank` (without the `rank` wrapper — see
+ * {@link PlayerRankResponse}).
+ */
+interface RankedEntry {
+    /** 1-based rank. */
+    rank: number;
+    playerId: string;
+    score: number;
+    /** Milliseconds since epoch. */
+    submittedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/** Payload from `POST /v1/boards/:boardId/scores`. */
+interface SubmitScoreResponse {
+    boardId: string;
+    /** The key ID that authorized the submission. Useful for consumer-side audit. */
+    keyId: string;
+    /** 1-based rank after the submit settled. */
+    rank: number;
+    totalEntries: number;
+    isPersonalBest: boolean;
+}
+/** Payload from `GET /v1/boards/:boardId/leaderboard`. */
+interface LeaderboardResponse {
+    boardId: string;
+    offset: number;
+    limit: number;
+    entries: RankedEntry[];
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
+interface PlayerRankResponse {
+    boardId: string;
+    playerId: string;
+    rank: number;
+    score: number;
+    submittedAt: number;
+    totalEntries: number;
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
+interface WindowAroundResponse {
+    boardId: string;
+    playerId: string;
+    before: number;
+    after: number;
+    entries: RankedEntry[];
+}
+
+/**
+ * SDK error type.
+ *
+ * Every non-2xx API response is normalized into a `ScorezillaError` instance
+ * by the transport layer. Network failures and timeouts surface as the same
+ * class (with `status: 0`) so callers have a single error type to catch.
+ *
+ * **Invariant — consumers MUST branch on `code` (and optionally `reason`),
+ * never on `message`.** The English-language `message` is for operator
+ * logging only and is explicitly **not** part of the SemVer contract; a
+ * minor release MAY reword any message. Machine logic that depends on
+ * message text will break silently across upgrades.
+ */
+
+/**
+ * Options for {@link ScorezillaError.from}.
+ *
+ * The fields mirror what's available after a fetch round-trip: the HTTP
+ * status, the parsed JSON body (if any), the request ID from
+ * `X-Request-Id`, and an optional `cause` for the underlying
+ * network/abort error.
+ */
+interface ScorezillaErrorFromInit {
+    status: number;
+    body?: ApiError | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+/**
+ * Thrown by the SDK for every failure path — non-2xx responses, network
+ * errors, aborts, and timeouts.
+ *
+ * Cross-realm `instanceof` is guaranteed: the class sets `Error.prototype`
+ * explicitly so checks survive iframe / worker boundaries.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sz.submitScore({ boardId, playerId, score });
+ * } catch (e) {
+ *   if (!(e instanceof ScorezillaError)) throw e;
+ *
+ *   if (e.isRateLimited()) {
+ *     await sleep((e.retryAfter ?? 30) * 1000);
+ *     return retry();
+ *   }
+ *   if (e.code === 'out_of_bounds') {
+ *     console.warn(`Score crosses ${e.reason} bound (limit ${e.bound})`);
+ *     return;
+ *   }
+ *   if (e.isAuth()) throw new Error('SDK misconfigured — bad publicKey');
+ *
+ *   // Anything else: surface to your reporter with requestId for support.
+ *   console.error(`Scorezilla ${e.code} (${e.status}) — request ${e.requestId}`);
+ *   throw e;
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ * @stability stable
+ */
+declare class ScorezillaError extends Error {
+    /** HTTP status of the response, or {@link STATUS_NETWORK_ERROR} (0) for
+     *  network / abort / timeout. */
+    readonly status: number;
+    /** Machine-stable error code from the API. Open union — see
+     *  {@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'`)
+     *  and possibly other codes in future minor releases. */
+    readonly reason: OutOfBoundsReason | string | undefined;
+    /** Seconds — present on `rate_limited`. Honored by the transport's retry
+     *  policy (Step 2.4). */
+    readonly retryAfter: number | undefined;
+    /** Server-issued request ID, lifted from the `X-Request-Id` response
+     *  header. Pass this to support when filing bugs. */
+    readonly requestId: string | undefined;
+    /** The bound value crossed on `out_of_bounds`. */
+    readonly bound: number | undefined;
+    /** Which rate-limit layer fired on `rate_limited`. */
+    readonly layer: 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. */
+    readonly cause: unknown;
+    constructor(message: string, init: {
+        status: number;
+        code: ScorezillaErrorCode;
+        reason?: string | undefined;
+        retryAfter?: number | undefined;
+        requestId?: string | undefined;
+        bound?: number | undefined;
+        layer?: string | undefined;
+        cause?: unknown;
+    });
+    /** `true` when this error is a 429 / `rate_limited`. */
+    isRateLimited(): 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. */
+    isTransient(): boolean;
+    /**
+     * Build a `ScorezillaError` from a fetch round-trip outcome.
+     *
+     * Prefer this over `new ScorezillaError(...)` from the transport layer —
+     * it does the mapping from API response shape to error fields in one
+     * place, so future fields like `correlationId` get added once here.
+     *
+     * @param init - status, optional parsed body, optional requestId, optional cause
+     */
+    static from(init: ScorezillaErrorFromInit): ScorezillaError;
+    /**
+     * Build a `ScorezillaError` for a transport-level failure (no HTTP
+     * response received): network error, abort, or timeout.
+     */
+    static network(message: string, cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for an `AbortSignal`-triggered cancellation. */
+    static aborted(cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for a request that exceeded its timeout budget. */
+    static timeout(timeoutMs: number): ScorezillaError;
+}
+
+export { type ApiSuccess as A, type BaseConfig as B, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type SecretKeyConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, ScorezillaError as b, type ScorezillaErrorCode as c, type ScorezillaConfig as d, type ApiError as e, type ApiResponse as f, type PublicKeyConfig as g };

package/dist/index.cjs

@@ -18,24 +18,10 @@ function validateConfig(cfg) {
   }
   let auth;
   if (hasPublic) {
-    const pk = cfg.publicKey;
-    if (typeof pk !== "string" || !PUBLIC_KEY_PATTERN.test(pk)) {
-      throw new Error(
-        `scorezilla: publicKey must match ${PUBLIC_KEY_PATTERN.toString()} (got: ${typeof pk === "string" ? pk.slice(0, 12) + "\u2026" : typeof pk})`
-      );
-    }
-    auth = { kind: "public", key: pk };
+    auth = { kind: "public", key: validatePublicKeyValue(cfg.publicKey) };
   } else {
-    const sk = cfg.secretKey;
-    if (!sk || typeof sk !== "object" || typeof sk.id !== "string" || typeof sk.secret !== "string") {
-      throw new Error("scorezilla: secretKey must be an object with string `id` and `secret`");
-    }
-    if (!sk.secret.startsWith(SECRET_KEY_PREFIX)) {
-      throw new Error(
-        `scorezilla: secretKey.secret must start with "${SECRET_KEY_PREFIX}" (live keys only)`
-      );
-    }
-    auth = { kind: "secret", keyId: sk.id, secret: sk.secret };
+    const resolved = validateSecretKey(cfg);
+    auth = { kind: "secret", keyId: resolved.keyId, secret: resolved.secret };
   }
   const baseUrlRaw = cfg.baseUrl ?? DEFAULT_BASE_URL;
   if (typeof baseUrlRaw !== "string" || baseUrlRaw.length === 0) {
@@ -46,10 +32,40 @@ function validateConfig(cfg) {
     fetch: cfg.fetch,
     timeoutMs: cfg.timeoutMs,
     maxRetries: cfg.maxRetries,
+    sleepImpl: cfg.sleepImpl,
     userAgent: cfg.userAgent,
     auth
   };
 }
+function validatePublicKeyValue(pk) {
+  if (typeof pk !== "string" || !PUBLIC_KEY_PATTERN.test(pk)) {
+    const shape = typeof pk === "string" ? `string of length ${pk.length}` : typeof pk;
+    throw new Error(
+      `scorezilla: publicKey must match ${PUBLIC_KEY_PATTERN.toString()} (got: ${shape})`
+    );
+  }
+  return pk;
+}
+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 (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})`
+    );
+  }
+  const match = SECRET_KEY_PATTERN.exec(sk);
+  if (!match) {
+    const shape = `string of length ${sk.length}`;
+    throw new Error(
+      `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: match[1], secret: sk };
+}
 
 // src/paths.ts
 function encodeSegment(value, label) {
@@ -89,6 +105,12 @@ function truncateMessage(raw) {
   const sliceEnd = Math.max(0, MESSAGE_MAX_CHARS - TRUNCATION_SUFFIX.length);
   return raw.slice(0, sliceEnd) + TRUNCATION_SUFFIX;
 }
+function truncateField(raw) {
+  if (typeof raw !== "string") return void 0;
+  if (raw.length <= MESSAGE_MAX_CHARS) return raw;
+  const sliceEnd = Math.max(0, MESSAGE_MAX_CHARS - TRUNCATION_SUFFIX.length);
+  return raw.slice(0, sliceEnd) + TRUNCATION_SUFFIX;
+}
 var ScorezillaError = class _ScorezillaError extends Error {
   /** HTTP status of the response, or {@link STATUS_NETWORK_ERROR} (0) for
    *  network / abort / timeout. */
@@ -119,11 +141,11 @@ var ScorezillaError = class _ScorezillaError extends Error {
     this.name = "ScorezillaError";
     this.status = init.status;
     this.code = init.code;
-    this.reason = init.reason;
+    this.reason = truncateField(init.reason);
     this.retryAfter = init.retryAfter;
-    this.requestId = init.requestId;
+    this.requestId = truncateField(init.requestId);
     this.bound = init.bound;
-    this.layer = init.layer;
+    this.layer = truncateField(init.layer);
     this.cause = init.cause;
     Object.setPrototypeOf(this, _ScorezillaError.prototype);
     if (typeof Error.captureStackTrace === "function") {
@@ -253,8 +275,9 @@ function shouldRetryError(err) {
 function generateIdempotencyKey() {
   const c = globalThis.crypto;
   if (!c || typeof c.randomUUID !== "function") {
-    throw new Error(
-      "scorezilla: globalThis.crypto.randomUUID is unavailable. The SDK requires Node \u2265 20 or a modern browser. Check your runtime."
+    throw new ScorezillaError(
+      "scorezilla: globalThis.crypto.randomUUID is unavailable. The SDK requires Node \u2265 20 or a modern browser. Check your runtime.",
+      { status: 0, code: "internal_error" }
     );
   }
   return c.randomUUID();
@@ -309,16 +332,24 @@ async function request(opts) {
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     const combined = combineSignalsWithTimeout(opts.signal, timeoutMs);
     try {
+      const bodyString = opts.body !== void 0 ? JSON.stringify(opts.body) : "";
+      const perAttemptHeaders = { ...opts.headers ?? {} };
+      if (opts.signRequest) {
+        perAttemptHeaders.Authorization = await opts.signRequest({
+          method: opts.method,
+          pathAndQuery: opts.path,
+          body: bodyString
+        });
+      }
       const init = {
         method: opts.method,
-        headers: buildHeaders(opts, idempotencyKey),
+        headers: buildHeaders({ ...opts, headers: perAttemptHeaders }, idempotencyKey),
         signal: combined.signal
       };
       if (opts.body !== void 0) {
-        init.body = JSON.stringify(opts.body);
+        init.body = bodyString;
       }
       const response = await fetchImpl(url, init);
-      combined.cleanup();
       if (response.ok) {
         return await parseJson(response);
       }
@@ -337,7 +368,6 @@ async function request(opts) {
       }
       throw err;
     } catch (caught) {
-      combined.cleanup();
       if (caught instanceof ScorezillaError) {
         if (shouldRetryError(caught) && attempt < maxRetries) {
           const delay = nextDelay(attempt, void 0, random);
@@ -355,6 +385,8 @@ async function request(opts) {
         continue;
       }
       throw mapped;
+    } finally {
+      combined.cleanup();
     }
   }
   throw lastError ?? new ScorezillaError("Request failed after retries", {
@@ -380,16 +412,38 @@ function buildHeaders(opts, idempotencyKey) {
   return headers;
 }
 async function parseJson(response) {
+  const requestId = response.headers.get("X-Request-Id") ?? void 0;
+  let parsed;
   try {
-    return await response.json();
+    parsed = await response.json();
   } catch (cause) {
     throw new ScorezillaError("Response body was not valid JSON", {
       status: response.status,
       code: "invalid_json",
-      requestId: response.headers.get("X-Request-Id") ?? void 0,
+      requestId,
       cause
     });
   }
+  if (parsed === null || typeof parsed !== "object") {
+    const observed = parsed === null ? "null" : typeof parsed;
+    throw new ScorezillaError(`Response body was not a JSON object (got ${observed})`, {
+      status: response.status,
+      code: "invalid_json",
+      requestId
+    });
+  }
+  const okField = parsed.ok;
+  if (okField !== true) {
+    throw new ScorezillaError(
+      `Response body on a 2xx is missing the \`ok: true\` discriminator (got ok=${String(okField)})`,
+      {
+        status: response.status,
+        code: "invalid_json",
+        requestId
+      }
+    );
+  }
+  return parsed;
 }
 async function safelyParseErrorBody(response) {
   try {
@@ -499,7 +553,7 @@ function validateMetadata(metadata) {
 }
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`. */
-  static version = "0.1.0-next.0";
+  static version = "0.1.0-next.3";
   #config;
   #userAgent;
   #authHeader;
@@ -664,8 +718,11 @@ var Scorezilla = class _Scorezilla {
     if (opts.body !== void 0) requestOpts.body = opts.body;
     if (this.#config.fetch !== void 0) requestOpts.fetchImpl = this.#config.fetch;
     if (this.#config.timeoutMs !== void 0) requestOpts.timeoutMs = this.#config.timeoutMs;
-    if (this.#config.maxRetries !== void 0) {
-      requestOpts.retry = { maxRetries: this.#config.maxRetries };
+    if (this.#config.maxRetries !== void 0 || this.#config.sleepImpl !== void 0) {
+      requestOpts.retry = {
+        ...this.#config.maxRetries !== void 0 ? { maxRetries: this.#config.maxRetries } : {},
+        ...this.#config.sleepImpl !== void 0 ? { sleepImpl: this.#config.sleepImpl } : {}
+      };
     }
     return request(requestOpts);
   }
@@ -675,7 +732,7 @@ function createClient(config) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.1.0-next.0";
+var SDK_VERSION = "0.1.0-next.3";
 
 exports.SDK_VERSION = SDK_VERSION;
 exports.Scorezilla = Scorezilla;