scorezilla 0.1.0-next.0

package/dist/index.d.cts

@@ -0,0 +1,557 @@
+/** 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;
+}
+/** 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. The pair `{ id, secret }` is what
+ *  the operator dashboard issues; the SDK signs requests with `secret` and
+ *  identifies them via `id`. */
+type SecretKeyConfig = BaseConfig & {
+    secretKey: {
+        id: string;
+        secret: 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;
+}
+
+/**
+ * `Scorezilla` — the public-key client for v0.1.0.
+ *
+ * Composes the substrate modules (transport, retry, errors, config,
+ * paths, user-agent) into the four documented public methods:
+ *
+ *   • {@link Scorezilla.submitScore}
+ *   • {@link Scorezilla.getLeaderboard}
+ *   • {@link Scorezilla.getPlayerRank}
+ *   • {@link Scorezilla.getWindowAround}
+ *
+ * Every method returns a parsed, typed response on the success path and
+ * throws {@link ScorezillaError} on every failure path (HTTP non-2xx,
+ * network failures, aborts, timeouts, invalid JSON).
+ *
+ * **Input contract — `playerId` only.** The SDK does NOT accept a `player`
+ * alias. TypeScript discriminated unions that differ only in key name
+ * produce no narrowing benefit and create friction for callers spreading
+ * existing types. v0.1.0 is the moment to be strict.
+ *
+ * **Auth — v0.1.0 is public-key only.** A `ScorezillaConfig` with
+ * `secretKey` is accepted by `validateConfig` (since the type union covers
+ * both kinds) but the constructor throws a clear `Error` pointing to the
+ * future `scorezilla/server` adapter (v0.2.0). This prevents accidental
+ * browser leakage of secret keys via the public-key surface.
+ */
+
+/** Input for {@link Scorezilla.submitScore}. */
+interface SubmitScoreInput {
+    /** UUID-typed board identifier — issued by the operator dashboard. */
+    boardId: string;
+    /** The SDK accepts ONLY `playerId`. Pass your stable per-player identifier
+     *  (UUID, account id, anonymous-session id). Avoid PII. */
+    playerId: string;
+    /** Finite number. The API rejects NaN, Infinity, and values outside the
+     *  board's configured `[minScore, maxScore]` range with `out_of_bounds`. */
+    score: number;
+    /** Optional structured context attached to the submission. Validated
+     *  locally before send: no functions, no symbols, no circular refs;
+     *  ≤ 4 KB UTF-8 bytes when JSON-stringified. */
+    metadata?: Record<string, unknown> | undefined;
+}
+/** Input for {@link Scorezilla.getLeaderboard}. */
+interface GetLeaderboardInput {
+    boardId: string;
+    /** Number of entries to return. API caps at 1000; default 100. */
+    top?: number | undefined;
+    /** Offset into the sorted board. API caps at 1_000_000; default 0. */
+    offset?: number | undefined;
+}
+/** Input for {@link Scorezilla.getPlayerRank}. */
+interface GetPlayerRankInput {
+    boardId: string;
+    playerId: string;
+}
+/** Input for {@link Scorezilla.getWindowAround}. */
+interface GetWindowAroundInput {
+    boardId: string;
+    playerId: string;
+    /** Entries strictly above the player. API caps at 100; default 5. */
+    before?: number | undefined;
+    /** Entries strictly below the player. API caps at 100; default 5. */
+    after?: number | undefined;
+}
+/**
+ * Public-key client for the Scorezilla API.
+ *
+ * ```ts
+ * const sz = new Scorezilla({ publicKey: 'pk_mygame_aBcDeF…' });
+ * const { rank, isPersonalBest } = await sz.submitScore({
+ *   boardId: 'board-uuid',
+ *   playerId: 'player-uuid',
+ *   score: 9001,
+ * });
+ * ```
+ *
+ * @since 0.1.0
+ * @stability stable
+ */
+declare class Scorezilla {
+    #private;
+    /** The package version, injected at build time from `package.json`. */
+    static readonly version: string;
+    /**
+     * @param config - public-key configuration. Passing `secretKey` throws —
+     *                 use the `scorezilla/server` adapter (v0.2.0) for HMAC.
+     */
+    constructor(config: ScorezillaConfig);
+    /**
+     * 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
+     */
+    submitScore(input: SubmitScoreInput): Promise<ApiSuccess<SubmitScoreResponse>>;
+    /**
+     * 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
+     */
+    getLeaderboard(input: GetLeaderboardInput): Promise<ApiSuccess<LeaderboardResponse>>;
+    /**
+     * Fetch a single player's rank on a board.
+     *
+     * Maps to `GET /v1/boards/:boardId/players/:playerId/rank`. Returns 404
+     * (`not_found`) if the player has no entry yet.
+     *
+     * @example
+     * ```ts
+     * try {
+     *   const { rank, score } = await sz.getPlayerRank({ boardId, playerId: 'alice' });
+     *   console.log(`Alice is rank ${rank} with score ${score}`);
+     * } catch (e) {
+     *   if (e instanceof ScorezillaError && e.isNotFound()) {
+     *     console.log('Alice has no submission on this board yet.');
+     *   } else throw e;
+     * }
+     * ```
+     *
+     * @throws {ScorezillaError} `not_found` (player has no submission),
+     *   `network_error`, `timeout`.
+     * @since 0.1.0
+     * @stability stable
+     */
+    getPlayerRank(input: GetPlayerRankInput): Promise<ApiSuccess<PlayerRankResponse>>;
+    /**
+     * 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
+     */
+    getWindowAround(input: GetWindowAroundInput): Promise<ApiSuccess<WindowAroundResponse>>;
+}
+/**
+ * Convenience factory for users who prefer a functional API.
+ *
+ * Functionally equivalent to `new Scorezilla(config)` — same auth rules,
+ * same validation, same instance type. The only reason to prefer one over
+ * the other is code style.
+ *
+ * @example
+ * ```ts
+ * import { createClient, ScorezillaError } from 'scorezilla';
+ *
+ * const sz = createClient({ publicKey: 'pk_mygame_…' });
+ * try {
+ *   await sz.submitScore({ boardId, playerId: 'alice', score: 9001 });
+ * } catch (e) {
+ *   if (e instanceof ScorezillaError && e.isRateLimited()) {
+ *     await new Promise((r) => setTimeout(r, (e.retryAfter ?? 30) * 1000));
+ *   } else throw e;
+ * }
+ * ```
+ *
+ * @throws Plain `Error` if the config is malformed (e.g. invalid
+ *   `publicKey` format, or `secretKey` passed to the public-key client).
+ *   See `validateConfig`.
+ * @since 0.1.0
+ * @stability stable
+ */
+declare function createClient(config: ScorezillaConfig): Scorezilla;
+
+/**
+ * Runtime detection + `User-Agent` builder.
+ *
+ * **Privacy invariant:** detection happens via cheap probes on
+ * `globalThis` only. The SDK never reads `navigator.userAgent` for
+ * fingerprinting — only for the narrow case of distinguishing Cloudflare
+ * Workers from a generic worker scope. No other DOM, hardware, or
+ * timezone signals are touched. This is documented in COMPATIBILITY.md.
+ *
+ * Note on browsers: per the Fetch spec, browsers silently ignore the
+ * `User-Agent` request header. Setting it has no effect there — but it
+ * remains meaningful in Node, Bun, Deno, and Workers, where we want
+ * server-side observability of which SDK version + runtime issued each
+ * request. The client layer also sends a separate `X-Scorezilla-Client`
+ * header that browsers do honor, so we get browser-side telemetry too.
+ */
+/** Runtimes the SDK explicitly identifies. `unknown` is the fallback when
+ *  no signature matches (e.g., a new runtime, or one with all the right
+ *  globals stripped). */
+type Runtime = 'browser' | 'node' | 'bun' | 'deno' | 'workers' | 'unknown';
+interface GlobalProbe {
+    readonly Bun?: unknown;
+    readonly Deno?: unknown;
+    readonly process?: {
+        readonly versions?: {
+            readonly node?: string;
+        };
+    };
+    readonly document?: unknown;
+    readonly WorkerGlobalScope?: unknown;
+    readonly navigator?: {
+        readonly userAgent?: string;
+    };
+}
+/**
+ * Detect the current runtime by probing well-known globals. Pure function
+ * — accepts an optional `g` override so tests can simulate any runtime.
+ *
+ * Order matters: Bun and Deno expose `process.versions.node`-like shims
+ * for compat, so we check their own identifiers first.
+ *
+ * @example
+ * ```ts
+ * import { detectRuntime } from 'scorezilla';
+ * const runtime = detectRuntime();   // → 'browser' | 'node' | 'bun' | 'deno' | 'workers' | 'unknown'
+ * myTelemetry.track('app.start', { sdk_runtime: runtime });
+ * ```
+ *
+ * @since 0.1.0
+ * @stability stable
+ */
+declare function detectRuntime(g?: GlobalProbe): Runtime;
+
+/**
+ * Scorezilla SDK — public entry.
+ *
+ * Surface (v0.1.0):
+ *   • `Scorezilla` — public-key client (browser + Node ≥ 20 + Workers + Bun + Deno)
+ *   • `createClient` — convenience factory
+ *   • `ScorezillaError` — the single error type the SDK throws
+ *   • `SDK_VERSION` — exported for support / bug-reporting
+ *   • All wire types — `SubmitScoreResponse`, `LeaderboardResponse`, etc.
+ *   • All input types — `SubmitScoreInput`, `GetLeaderboardInput`, etc.
+ *   • Config types — `ScorezillaConfig`, `PublicKeyConfig`, `SecretKeyConfig`
+ *
+ * The HMAC server-side client (`scorezilla/server`), React adapter
+ * (`scorezilla/react`), and Phaser plugin (`scorezilla/phaser`) ship in
+ * later minor releases — see CHANGELOG.md.
+ */
+
+declare const SDK_VERSION: string;
+
+export { type ApiError, type ApiResponse, type ApiSuccess, type BaseConfig, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, type LeaderboardResponse, type OutOfBoundsReason, type PlayerRankResponse, type PublicKeyConfig, type RankedEntry, type Runtime, SDK_VERSION, Scorezilla, type ScorezillaConfig, ScorezillaError, type ScorezillaErrorCode, type SecretKeyConfig, type SubmitScoreInput, type SubmitScoreResponse, type WindowAroundResponse, createClient, detectRuntime };