scorezilla 0.3.1 → 0.5.0

package/dist/headless.cjs

@@ -0,0 +1,882 @@
+'use strict';
+
+// src/config.ts
+var DEFAULT_BASE_URL = "https://api.scorezilla.dev";
+var PUBLIC_KEY_PATTERN = /^pk_[a-z0-9-]+_[A-Za-z0-9]+$/;
+var SECRET_KEY_PREFIX = "sk_live_";
+function validateConfig(cfg) {
+  if (!cfg || typeof cfg !== "object") {
+    throw new Error("scorezilla: config must be an object with publicKey or secretKey");
+  }
+  const hasPublic = "publicKey" in cfg && cfg.publicKey !== void 0;
+  const hasSecret = "secretKey" in cfg && cfg.secretKey !== void 0;
+  if (hasPublic && hasSecret) {
+    throw new Error("scorezilla: config must not contain both publicKey and secretKey");
+  }
+  if (!hasPublic && !hasSecret) {
+    throw new Error("scorezilla: config must contain either publicKey or secretKey");
+  }
+  let auth;
+  if (hasPublic) {
+    auth = { kind: "public", key: validatePublicKeyValue(cfg.publicKey) };
+  } else {
+    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) {
+    throw new Error("scorezilla: baseUrl must be a non-empty string when provided");
+  }
+  return {
+    baseUrl: baseUrlRaw.replace(/\/+$/, ""),
+    fetch: cfg.fetch,
+    timeoutMs: cfg.timeoutMs,
+    maxRetries: cfg.maxRetries,
+    sleepImpl: cfg.sleepImpl,
+    warn: cfg.warn,
+    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) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`scorezilla: ${label} must be a non-empty string`);
+  }
+  return encodeURIComponent(value);
+}
+function buildQueryString(params) {
+  const usp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0) usp.set(k, String(v));
+  }
+  const qs = usp.toString();
+  return qs.length > 0 ? `?${qs}` : "";
+}
+function submitScorePath(boardId) {
+  return `/v1/boards/${encodeSegment(boardId, "boardId")}/scores`;
+}
+function getLeaderboardPath(boardId, q) {
+  return `/v1/boards/${encodeSegment(boardId, "boardId")}/leaderboard` + buildQueryString({ top: q?.top, offset: q?.offset });
+}
+function getPlayerRankPath(boardId, playerId) {
+  return `/v1/boards/${encodeSegment(boardId, "boardId")}/players/${encodeSegment(playerId, "playerId")}/rank`;
+}
+function getWindowAroundPath(boardId, playerId, q) {
+  return `/v1/boards/${encodeSegment(boardId, "boardId")}/players/${encodeSegment(playerId, "playerId")}/window` + buildQueryString({ before: q?.before, after: q?.after });
+}
+
+// src/errors.ts
+var MESSAGE_MAX_CHARS = 500;
+var TRUNCATION_SUFFIX = "\u2026 [truncated]";
+var STATUS_NETWORK_ERROR = 0;
+function truncateMessage(raw) {
+  if (typeof raw !== "string") return "";
+  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;
+}
+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. */
+  status;
+  /** 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'`. */
+  code;
+  /** 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
+   *  policy (Step 2.4). */
+  retryAfter;
+  /** Server-issued request ID, lifted from the `X-Request-Id` response
+   *  header. Pass this to support when filing bugs. */
+  requestId;
+  /** The bound value crossed on `out_of_bounds`. */
+  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. */
+  cause;
+  constructor(message, init) {
+    super(truncateMessage(message));
+    this.name = "ScorezillaError";
+    this.status = init.status;
+    this.code = init.code;
+    this.reason = truncateField(init.reason);
+    this.retryAfter = init.retryAfter;
+    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") {
+      Error.captureStackTrace(this, _ScorezillaError);
+    }
+  }
+  // ─── Sub-message helpers ─────────────────────────────────────────────
+  // Stable wrappers over the `code` discriminator so consumers can write
+  // `if (err.isRateLimited())` instead of memorizing the code spelling.
+  /** `true` when this error is a 429 / `rate_limited`. */
+  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";
+  }
+  /** `true` when this error is a 404 / `not_found`. */
+  isNotFound() {
+    return this.code === "not_found";
+  }
+  /** `true` when this error is a 422 / `out_of_bounds` (score below/above board limit). */
+  isOutOfBounds() {
+    return this.code === "out_of_bounds";
+  }
+  /** `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.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.
+   *
+   * 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) {
+    const { status, body, requestId, cause } = init;
+    if (body && body.ok === false && typeof body.error === "string") {
+      return new _ScorezillaError(body.message ?? `Request failed: ${body.error}`, {
+        status,
+        code: body.error,
+        reason: body.reason,
+        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
+      });
+    }
+    const code = codeForStatus(status);
+    return new _ScorezillaError(`Request failed with status ${status}`, {
+      status,
+      code,
+      requestId,
+      cause
+    });
+  }
+  /**
+   * Build a `ScorezillaError` for a transport-level failure (no HTTP
+   * response received): network error, abort, or timeout.
+   */
+  static network(message, cause) {
+    return new _ScorezillaError(message, {
+      status: STATUS_NETWORK_ERROR,
+      code: "network_error",
+      cause
+    });
+  }
+  /** Build a `ScorezillaError` for an `AbortSignal`-triggered cancellation. */
+  static aborted(cause) {
+    return new _ScorezillaError("Request aborted", {
+      status: STATUS_NETWORK_ERROR,
+      code: "aborted",
+      cause
+    });
+  }
+  /** Build a `ScorezillaError` for a request that exceeded its timeout budget. */
+  static timeout(timeoutMs) {
+    return new _ScorezillaError(`Request timed out after ${timeoutMs}ms`, {
+      status: STATUS_NETWORK_ERROR,
+      code: "timeout"
+    });
+  }
+};
+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";
+  if (status >= 400) return "invalid_input";
+  return "internal_error";
+}
+
+// src/uuid.ts
+function uuidV4FromBytes(bytes) {
+  bytes[6] = (bytes[6] ?? 0) & 15 | 64;
+  bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+  let hex = "";
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, "0");
+  }
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function randomUUID() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") {
+    return c.randomUUID();
+  }
+  if (c && typeof c.getRandomValues === "function") {
+    return uuidV4FromBytes(c.getRandomValues(new Uint8Array(16)));
+  }
+  throw new Error(
+    "scorezilla: no Web Crypto RNG available (neither crypto.randomUUID nor crypto.getRandomValues). The SDK requires Node \u2265 20 or a modern browser."
+  );
+}
+
+// src/retry.ts
+var DEFAULT_MAX_RETRIES = 2;
+var BASE_DELAY_MS = 200;
+var MAX_DELAY_MS = 4e3;
+var MAX_RETRY_AFTER_SEC = 30;
+function nextDelay(attempt, retryAfterSec, random = Math.random) {
+  if (typeof retryAfterSec === "number" && Number.isFinite(retryAfterSec) && retryAfterSec >= 0 && retryAfterSec <= MAX_RETRY_AFTER_SEC) {
+    return Math.round(retryAfterSec * 1e3);
+  }
+  const exponential = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+  const jitterFactor = 0.5 + random() * 0.5;
+  return Math.round(exponential * jitterFactor);
+}
+function shouldRetryStatus(status) {
+  if (status === 429) return true;
+  if (status >= 500 && status < 600) return true;
+  return false;
+}
+function shouldRetryError(err) {
+  if (err instanceof ScorezillaError) {
+    return err.code === "network_error";
+  }
+  return false;
+}
+function generateIdempotencyKey() {
+  try {
+    return randomUUID();
+  } catch {
+    throw new ScorezillaError(
+      "scorezilla: no Web Crypto RNG available (neither crypto.randomUUID nor crypto.getRandomValues). The SDK requires Node \u2265 20 or a modern browser.",
+      { status: 0, code: "internal_error" }
+    );
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(signal?.reason ?? new DOMException("Aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/transport.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+async function request(opts) {
+  const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error(
+      "scorezilla: globalThis.fetch is unavailable. Either upgrade your runtime (Node \u2265 20 has fetch built in) or pass `fetch: yourFetch` in the SDK config."
+    );
+  }
+  const url = buildUrl(opts.baseUrl, opts.path);
+  const maxRetries = opts.retry?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const random = opts.retry?.random ?? Math.random;
+  const sleepImpl = opts.retry?.sleepImpl ?? sleep;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error(
+      `scorezilla: timeoutMs must be a positive finite number (got ${String(timeoutMs)})`
+    );
+  }
+  const retrySleep = async (delay) => {
+    try {
+      await sleepImpl(delay, opts.signal);
+    } catch (cause) {
+      throw ScorezillaError.aborted(cause);
+    }
+  };
+  const idempotencyKey = opts.method === "POST" ? generateIdempotencyKey() : null;
+  let lastError;
+  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, headers: perAttemptHeaders }, idempotencyKey),
+        signal: combined.signal
+      };
+      if (opts.body !== void 0) {
+        init.body = bodyString;
+      }
+      const response = await fetchImpl(url, init);
+      if (response.ok) {
+        warnOnDeprecationOnce(response, opts.warnImpl);
+        return await parseJson(response);
+      }
+      const body = await safelyParseErrorBody(response);
+      const err = ScorezillaError.from({
+        status: response.status,
+        body,
+        requestId: response.headers.get("X-Request-Id") ?? void 0
+      });
+      if (shouldRetryStatus(response.status) && attempt < maxRetries) {
+        const retryAfter = readRetryAfter(response);
+        const delay = nextDelay(attempt, retryAfter, random);
+        await retrySleep(delay);
+        lastError = err;
+        continue;
+      }
+      throw err;
+    } catch (caught) {
+      if (caught instanceof ScorezillaError) {
+        if (shouldRetryError(caught) && attempt < maxRetries) {
+          const delay = nextDelay(attempt, void 0, random);
+          await retrySleep(delay);
+          lastError = caught;
+          continue;
+        }
+        throw caught;
+      }
+      const mapped = mapTransportError(caught, opts.signal, timeoutMs, combined);
+      if (shouldRetryError(mapped) && attempt < maxRetries) {
+        const delay = nextDelay(attempt, void 0, random);
+        await retrySleep(delay);
+        lastError = mapped;
+        continue;
+      }
+      throw mapped;
+    } finally {
+      combined.cleanup();
+    }
+  }
+  throw lastError ?? new ScorezillaError("Request failed after retries", {
+    status: 0,
+    code: "internal_error"
+  });
+}
+function buildUrl(baseUrl, path) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  return base + path;
+}
+function buildHeaders(opts, idempotencyKey) {
+  const headers = { Accept: "application/json" };
+  if (opts.body !== void 0) {
+    headers["Content-Type"] = "application/json";
+  }
+  if (idempotencyKey !== null) {
+    headers["Idempotency-Key"] = idempotencyKey;
+  }
+  if (opts.headers) {
+    for (const [k, v] of Object.entries(opts.headers)) headers[k] = v;
+  }
+  return headers;
+}
+async function parseJson(response) {
+  const requestId = response.headers.get("X-Request-Id") ?? void 0;
+  let parsed;
+  try {
+    parsed = await response.json();
+  } catch (cause) {
+    throw new ScorezillaError("Response body was not valid JSON", {
+      status: response.status,
+      code: "invalid_json",
+      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 {
+    const json = await response.json();
+    if (json && typeof json === "object" && "ok" in json && json.ok === false) {
+      return json;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readRetryAfter(response) {
+  const raw = response.headers.get("Retry-After");
+  if (!raw) return void 0;
+  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;
+  if (caller?.aborted) {
+    ctrl.abort(caller.reason);
+    return { signal: ctrl.signal, cleanup: () => {
+    }, timedOut: () => false };
+  }
+  const onCallerAbort = () => {
+    ctrl.abort(caller?.reason);
+  };
+  caller?.addEventListener("abort", onCallerAbort, { once: true });
+  const timer = setTimeout(() => {
+    didTimeOut = true;
+    ctrl.abort(new DOMException(`Request timed out after ${timeoutMs}ms`, "TimeoutError"));
+  }, timeoutMs);
+  return {
+    signal: ctrl.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      caller?.removeEventListener("abort", onCallerAbort);
+    },
+    timedOut: () => didTimeOut
+  };
+}
+function mapTransportError(caught, callerSignal, timeoutMs, combined) {
+  if (callerSignal?.aborted) {
+    return ScorezillaError.aborted(callerSignal.reason ?? caught);
+  }
+  if (combined.timedOut()) {
+    return ScorezillaError.timeout(timeoutMs);
+  }
+  const message = caught instanceof Error ? caught.message : "Network request failed";
+  return ScorezillaError.network(message, caught);
+}
+
+// src/user-agent.ts
+function detectRuntime(g = globalThis) {
+  if (typeof g.Bun !== "undefined") return "bun";
+  if (typeof g.Deno !== "undefined") return "deno";
+  if (typeof g.navigator?.userAgent === "string" && g.navigator.userAgent.includes("Cloudflare-Workers")) {
+    return "workers";
+  }
+  if (typeof g.process?.versions?.node === "string") return "node";
+  if (typeof g.document !== "undefined") return "browser";
+  return "unknown";
+}
+function defaultUserAgent(version, runtime = detectRuntime()) {
+  return `scorezilla-js/${version} (${runtime})`;
+}
+
+// src/client.ts
+var METADATA_MAX_BYTES = 4096;
+function validateMetadata(metadata) {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new Error(
+      "scorezilla: metadata must be a plain object (got " + (Array.isArray(metadata) ? "array" : typeof metadata) + ")"
+    );
+  }
+  let serialized;
+  try {
+    serialized = JSON.stringify(metadata, (_key, value) => {
+      if (typeof value === "function") {
+        throw new Error("scorezilla: metadata may not contain functions");
+      }
+      if (typeof value === "symbol") {
+        throw new Error("scorezilla: metadata may not contain symbols");
+      }
+      if (typeof value === "bigint") {
+        throw new Error("scorezilla: metadata may not contain BigInt");
+      }
+      return value;
+    });
+  } catch (cause) {
+    if (cause instanceof Error) {
+      if (cause.message.startsWith("scorezilla:")) throw cause;
+      if (/circular|convert|cyclic/i.test(cause.message)) {
+        throw new Error("scorezilla: metadata contains circular references");
+      }
+    }
+    throw cause;
+  }
+  const byteLength = new TextEncoder().encode(serialized).length;
+  if (byteLength > METADATA_MAX_BYTES) {
+    throw new Error(
+      `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.5.0";
+  #config;
+  #userAgent;
+  #authHeader;
+  /**
+   * @param config - public-key configuration. Passing `secretKey` throws —
+   *                 use the `scorezilla/server` adapter (v0.2.0) for HMAC.
+   */
+  constructor(config) {
+    const resolved = validateConfig(config);
+    if (resolved.auth.kind !== "public") {
+      throw new Error(
+        "scorezilla: the default `Scorezilla` client is public-key only. Secret-key (HMAC) auth ships in v0.2.0 via the `scorezilla/server` adapter \u2014 use that for server-side code; use `publicKey` for browser / public clients."
+      );
+    }
+    this.#config = resolved;
+    this.#userAgent = resolved.userAgent ?? defaultUserAgent(_Scorezilla.version);
+    this.#authHeader = `Bearer ${resolved.auth.key}`;
+  }
+  /**
+   * Submit a score to a board.
+   *
+   * Maps to `POST /v1/boards/:boardId/scores`. See [API.md](../API.md#submitscore)
+   * for the full contract.
+   *
+   * @example
+   * ```ts
+   * try {
+   *   const r = await sz.submitScore({ boardId, playerId: 'alice', score: 9001 });
+   *   if (r.isPersonalBest) console.log(`PB! Rank ${r.rank} of ${r.totalEntries}`);
+   * } catch (e) {
+   *   if (e instanceof ScorezillaError && e.code === 'out_of_bounds') {
+   *     console.warn(`Score outside board bounds (${e.reason}, limit ${e.bound})`);
+   *   } else throw e;
+   * }
+   * ```
+   *
+   * @throws {ScorezillaError} `unauthorized` (bad publicKey), `forbidden`
+   *   (key not bound to this board), `not_found` (board doesn't exist),
+   *   `out_of_bounds` (score outside board's min/max), `rate_limited`
+   *   (Layer 2/3 throttle hit), `invalid_input`, `network_error`, `timeout`.
+   * @since 0.1.0
+   * @stability stable
+   */
+  async submitScore(input) {
+    if (input.metadata !== void 0) {
+      validateMetadata(input.metadata);
+    }
+    const body = {
+      playerId: input.playerId,
+      score: input.score
+    };
+    if (input.metadata !== void 0) {
+      body.metadata = input.metadata;
+    }
+    if (input.name !== void 0) {
+      body.name = input.name;
+    }
+    if (input.turnstileToken !== void 0) {
+      body.turnstileToken = input.turnstileToken;
+    }
+    return this.#request({
+      path: submitScorePath(input.boardId),
+      method: "POST",
+      body,
+      signal: input.signal
+    });
+  }
+  /**
+   * Fetch the top-N leaderboard for a board.
+   *
+   * Maps to `GET /v1/boards/:boardId/leaderboard`.
+   *
+   * @example
+   * ```ts
+   * const { entries } = await sz.getLeaderboard({ boardId, top: 25 });
+   * for (const e of entries) console.log(`${e.rank}. ${e.playerId}: ${e.score}`);
+   * ```
+   *
+   * @throws {ScorezillaError} `not_found`, `network_error`, `timeout`.
+   * @since 0.1.0
+   * @stability stable
+   */
+  async getLeaderboard(input) {
+    const q = {};
+    if (input.top !== void 0) q.top = input.top;
+    if (input.offset !== void 0) q.offset = input.offset;
+    return this.#request({
+      path: getLeaderboardPath(input.boardId, q),
+      method: "GET",
+      signal: input.signal
+    });
+  }
+  /**
+   * Fetch a single player's rank on a board.
+   *
+   * Maps to `GET /v1/boards/:boardId/players/:playerId/rank`. "No entry yet"
+   * is a normal result, NOT an error: the response is `{ ranked: false }`
+   * (narrow on `ranked` before reading `rank`). A `not_found` is thrown only
+   * when the board itself doesn't exist.
+   *
+   * @example
+   * ```ts
+   * const r = await sz.getPlayerRank({ boardId, playerId: 'alice' });
+   * if (r.ranked) console.log(`Alice is rank ${r.rank} with score ${r.score}`);
+   * else console.log('Alice has no submission on this board yet.');
+   * ```
+   *
+   * @throws {ScorezillaError} `not_found` (board does not exist),
+   *   `network_error`, `timeout`.
+   * @since 0.1.0
+   * @stability stable
+   */
+  async getPlayerRank(input) {
+    return this.#request({
+      path: getPlayerRankPath(input.boardId, input.playerId),
+      method: "GET",
+      signal: input.signal
+    });
+  }
+  /**
+   * Fetch the slice of entries surrounding a player.
+   *
+   * Maps to `GET /v1/boards/:boardId/players/:playerId/window?before=&after=`.
+   *
+   * @example
+   * ```ts
+   * const { entries } = await sz.getWindowAround({
+   *   boardId, playerId: 'alice', before: 2, after: 2,
+   * });
+   * ```
+   *
+   * @throws {ScorezillaError} `network_error`, `timeout`.
+   * @since 0.1.0
+   * @stability stable
+   */
+  async getWindowAround(input) {
+    const q = {};
+    if (input.before !== void 0) q.before = input.before;
+    if (input.after !== void 0) q.after = input.after;
+    return this.#request({
+      path: getWindowAroundPath(input.boardId, input.playerId, q),
+      method: "GET",
+      signal: input.signal
+    });
+  }
+  // ─── Internal ────────────────────────────────────────────────────────
+  /**
+   * Common request wiring — auth header, default fetch impl, timeout, retry.
+   * Each public method composes its `path`, `method`, and (optionally) `body`
+   * and hands them to this thin pass-through. Keeps the four method bodies
+   * boilerplate-free and ensures every call shares identical defaults.
+   */
+  async #request(opts) {
+    const headers = {
+      Authorization: this.#authHeader,
+      // User-Agent: ignored by browsers (per Fetch spec), useful in
+      // Node/Bun/Deno/Workers for server-side observability.
+      "User-Agent": this.#userAgent,
+      // X-Scorezilla-Client: browser-honored, mirrors the UA for telemetry
+      // parity across runtimes.
+      "X-Scorezilla-Client": this.#userAgent
+    };
+    const requestOpts = {
+      baseUrl: this.#config.baseUrl,
+      path: opts.path,
+      method: opts.method,
+      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 = {
+        ...this.#config.maxRetries !== void 0 ? { maxRetries: this.#config.maxRetries } : {},
+        ...this.#config.sleepImpl !== void 0 ? { sleepImpl: this.#config.sleepImpl } : {}
+      };
+    }
+    return request(requestOpts);
+  }
+};
+
+// src/headless.ts
+function createHeadlessClient(config) {
+  const sz = new Scorezilla(config);
+  return {
+    async submit(input) {
+      try {
+        const r = await sz.submitScore(input);
+        return {
+          ok: true,
+          rank: r.rank,
+          totalEntries: r.totalEntries,
+          isPersonalBest: r.isPersonalBest
+        };
+      } catch {
+        return null;
+      }
+    },
+    async getLeaderboard(input) {
+      try {
+        const { entries } = await sz.getLeaderboard(input);
+        return entries;
+      } catch {
+        return [];
+      }
+    }
+  };
+}
+function isCrossOrigin(homeOrigin, currentOrigin = globalThis.location?.origin) {
+  if (!currentOrigin) return false;
+  try {
+    return currentOrigin !== new URL(homeOrigin).origin;
+  } catch {
+    return false;
+  }
+}
+
+exports.createHeadlessClient = createHeadlessClient;
+exports.isCrossOrigin = isCrossOrigin;
+//# sourceMappingURL=headless.cjs.map
+//# sourceMappingURL=headless.cjs.map