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

package/dist/identity.d.cts

@@ -0,0 +1,151 @@
+/**
+ * Identity preset helpers — opinionated, selectable ways for your game to
+ * generate or fetch a `playerId` for score submission.
+ *
+ * Background: every Scorezilla score carries an opaque `playerId`. The SDK
+ * doesn't care whether it's a UUID, a nickname, an email, or a server
+ * session token. But _how_ your game decides on that value is a UX +
+ * privacy decision the team should make explicitly. These presets are the
+ * blessed patterns; pick one per integration.
+ *
+ * See ADR 0003 (MCP identity axis) for the design rationale:
+ * https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md
+ *
+ * @module scorezilla/identity
+ * @since 0.3.0
+ */
+interface AnonymousPlayerOptions {
+    /** localStorage key under which the generated UUID is persisted. */
+    readonly storageKey: string;
+}
+interface PromptedPlayerOptions {
+    /** localStorage key under which the user-entered name is persisted. */
+    readonly storageKey: string;
+    /** Message shown in `window.prompt()` on first run. */
+    readonly prompt: string;
+}
+/**
+ * Identity handle returned by the storage-backed presets.
+ *
+ * `forget()` clears the persisted value from browser storage. It does
+ * **not** delete server-side score history for this player — to fully
+ * erase a player's data, call the admin "delete player" endpoint.
+ */
+interface PlayerHandle {
+    readonly id: string;
+    readonly forget: () => void;
+}
+/**
+ * Marker returned by `useServerAuthoritative()` to signal that the
+ * game's backend (not the browser) owns the `playerId` via the
+ * HMAC-signed secure path (`scorezilla/server`).
+ */
+interface ServerAuthoritativeMarker {
+    readonly source: 'server-authoritative';
+}
+/**
+ * Anonymous player identity. Generates an opaque UUID on first run and
+ * persists it in `localStorage` so the same browser keeps the same ID
+ * across page reloads.
+ *
+ * **Privacy.** Stores a randomly-generated UUID in browser localStorage;
+ * the value is sent to the API on every score submission and persisted
+ * indefinitely in the player's score-history rows. No PII is collected.
+ * `forget()` removes the localStorage entry; for full server-side erasure
+ * call the admin "delete player" endpoint.
+ *
+ * @example
+ * ```ts
+ * import { Scorezilla } from 'scorezilla';
+ * import { useAnonymousPlayer } from 'scorezilla/identity';
+ *
+ * const player = useAnonymousPlayer({ storageKey: 'mygame:player' });
+ * const sz = new Scorezilla({ publicKey: 'pk_…' });
+ * await sz.submitScore({ boardId, playerId: player.id, score: 42 });
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function useAnonymousPlayer(options: AnonymousPlayerOptions): PlayerHandle;
+/**
+ * Prompted player identity. On first run shows a `window.prompt()` asking
+ * the user for a name, then persists it in `localStorage` for subsequent
+ * visits. Returns `null` if there is no browser (SSR), no `window.prompt`,
+ * or if the user cancelled / entered an empty value.
+ *
+ * **Privacy.** The user-entered string is stored in browser localStorage,
+ * transmitted to the API on every score submission, and persisted
+ * indefinitely on the leaderboard. The persisted value is whatever the
+ * user typed — sanitize at the UI layer if you care. `forget()` clears
+ * local state but does NOT delete server-side history.
+ *
+ * **UX caveat.** `window.prompt()` blocks the main thread and looks
+ * dated in modern apps. For a polished flow, build your own inline form
+ * and pass the result to `submitScore` directly — the preset is here to
+ * cover quick prototypes and jam-style integrations.
+ *
+ * @example
+ * ```ts
+ * import { Scorezilla } from 'scorezilla';
+ * import { usePromptedPlayer } from 'scorezilla/identity';
+ *
+ * const player = usePromptedPlayer({
+ *   storageKey: 'mygame:player',
+ *   prompt: 'Enter a name for the leaderboard:',
+ * });
+ *
+ * if (player) {
+ *   const sz = new Scorezilla({ publicKey: 'pk_…' });
+ *   await sz.submitScore({ boardId, playerId: player.id, score: 42 });
+ * }
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function usePromptedPlayer(options: PromptedPlayerOptions): PlayerHandle | null;
+/**
+ * Server-authoritative identity marker. Signals that the game's backend
+ * is responsible for the `playerId` via the HMAC-signed secure path
+ * (`scorezilla/server`). The browser SDK does no identity work — the
+ * server picks the value, signs the submission, and posts.
+ *
+ * The return value is a no-op marker; you don't pass it anywhere. It
+ * exists so MCP-returned snippets can emit a single line that
+ * unambiguously says "this game uses the secure path; identity is
+ * server-authoritative."
+ *
+ * @example
+ * ```ts
+ * // Client (no identity helper needed):
+ * import { useServerAuthoritative } from 'scorezilla/identity';
+ * useServerAuthoritative();
+ *
+ * // Server (where the real work happens):
+ * import { Scorezilla } from 'scorezilla/server';
+ * const sz = new Scorezilla({ secretKey: process.env.SCOREZILLA_SECRET_KEY! });
+ * await sz.submitScore({ boardId, playerId: serverDerivedId, score });
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function useServerAuthoritative(): ServerAuthoritativeMarker;
+/**
+ * OAuth-backed player identity. **Preview stub in 0.3.0-next.x** — throws
+ * on call. Full implementation (Google + GitHub for v1, Apple + Discord
+ * deferred) lands in a follow-up release on the `next` dist-tag, before
+ * the `latest` 0.3.0 ships.
+ *
+ * Until then: drive your own OAuth flow and pass the resulting user
+ * identifier to `submitScore` directly.
+ *
+ * @since 0.3.0
+ * @stability preview
+ */
+declare function useAuthProvider(_options: {
+    readonly provider: 'google' | 'github';
+}): never;
+
+export { type AnonymousPlayerOptions, type PlayerHandle, type PromptedPlayerOptions, type ServerAuthoritativeMarker, useAnonymousPlayer, useAuthProvider, usePromptedPlayer, useServerAuthoritative };

package/dist/identity.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Identity preset helpers — opinionated, selectable ways for your game to
+ * generate or fetch a `playerId` for score submission.
+ *
+ * Background: every Scorezilla score carries an opaque `playerId`. The SDK
+ * doesn't care whether it's a UUID, a nickname, an email, or a server
+ * session token. But _how_ your game decides on that value is a UX +
+ * privacy decision the team should make explicitly. These presets are the
+ * blessed patterns; pick one per integration.
+ *
+ * See ADR 0003 (MCP identity axis) for the design rationale:
+ * https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md
+ *
+ * @module scorezilla/identity
+ * @since 0.3.0
+ */
+interface AnonymousPlayerOptions {
+    /** localStorage key under which the generated UUID is persisted. */
+    readonly storageKey: string;
+}
+interface PromptedPlayerOptions {
+    /** localStorage key under which the user-entered name is persisted. */
+    readonly storageKey: string;
+    /** Message shown in `window.prompt()` on first run. */
+    readonly prompt: string;
+}
+/**
+ * Identity handle returned by the storage-backed presets.
+ *
+ * `forget()` clears the persisted value from browser storage. It does
+ * **not** delete server-side score history for this player — to fully
+ * erase a player's data, call the admin "delete player" endpoint.
+ */
+interface PlayerHandle {
+    readonly id: string;
+    readonly forget: () => void;
+}
+/**
+ * Marker returned by `useServerAuthoritative()` to signal that the
+ * game's backend (not the browser) owns the `playerId` via the
+ * HMAC-signed secure path (`scorezilla/server`).
+ */
+interface ServerAuthoritativeMarker {
+    readonly source: 'server-authoritative';
+}
+/**
+ * Anonymous player identity. Generates an opaque UUID on first run and
+ * persists it in `localStorage` so the same browser keeps the same ID
+ * across page reloads.
+ *
+ * **Privacy.** Stores a randomly-generated UUID in browser localStorage;
+ * the value is sent to the API on every score submission and persisted
+ * indefinitely in the player's score-history rows. No PII is collected.
+ * `forget()` removes the localStorage entry; for full server-side erasure
+ * call the admin "delete player" endpoint.
+ *
+ * @example
+ * ```ts
+ * import { Scorezilla } from 'scorezilla';
+ * import { useAnonymousPlayer } from 'scorezilla/identity';
+ *
+ * const player = useAnonymousPlayer({ storageKey: 'mygame:player' });
+ * const sz = new Scorezilla({ publicKey: 'pk_…' });
+ * await sz.submitScore({ boardId, playerId: player.id, score: 42 });
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function useAnonymousPlayer(options: AnonymousPlayerOptions): PlayerHandle;
+/**
+ * Prompted player identity. On first run shows a `window.prompt()` asking
+ * the user for a name, then persists it in `localStorage` for subsequent
+ * visits. Returns `null` if there is no browser (SSR), no `window.prompt`,
+ * or if the user cancelled / entered an empty value.
+ *
+ * **Privacy.** The user-entered string is stored in browser localStorage,
+ * transmitted to the API on every score submission, and persisted
+ * indefinitely on the leaderboard. The persisted value is whatever the
+ * user typed — sanitize at the UI layer if you care. `forget()` clears
+ * local state but does NOT delete server-side history.
+ *
+ * **UX caveat.** `window.prompt()` blocks the main thread and looks
+ * dated in modern apps. For a polished flow, build your own inline form
+ * and pass the result to `submitScore` directly — the preset is here to
+ * cover quick prototypes and jam-style integrations.
+ *
+ * @example
+ * ```ts
+ * import { Scorezilla } from 'scorezilla';
+ * import { usePromptedPlayer } from 'scorezilla/identity';
+ *
+ * const player = usePromptedPlayer({
+ *   storageKey: 'mygame:player',
+ *   prompt: 'Enter a name for the leaderboard:',
+ * });
+ *
+ * if (player) {
+ *   const sz = new Scorezilla({ publicKey: 'pk_…' });
+ *   await sz.submitScore({ boardId, playerId: player.id, score: 42 });
+ * }
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function usePromptedPlayer(options: PromptedPlayerOptions): PlayerHandle | null;
+/**
+ * Server-authoritative identity marker. Signals that the game's backend
+ * is responsible for the `playerId` via the HMAC-signed secure path
+ * (`scorezilla/server`). The browser SDK does no identity work — the
+ * server picks the value, signs the submission, and posts.
+ *
+ * The return value is a no-op marker; you don't pass it anywhere. It
+ * exists so MCP-returned snippets can emit a single line that
+ * unambiguously says "this game uses the secure path; identity is
+ * server-authoritative."
+ *
+ * @example
+ * ```ts
+ * // Client (no identity helper needed):
+ * import { useServerAuthoritative } from 'scorezilla/identity';
+ * useServerAuthoritative();
+ *
+ * // Server (where the real work happens):
+ * import { Scorezilla } from 'scorezilla/server';
+ * const sz = new Scorezilla({ secretKey: process.env.SCOREZILLA_SECRET_KEY! });
+ * await sz.submitScore({ boardId, playerId: serverDerivedId, score });
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function useServerAuthoritative(): ServerAuthoritativeMarker;
+/**
+ * OAuth-backed player identity. **Preview stub in 0.3.0-next.x** — throws
+ * on call. Full implementation (Google + GitHub for v1, Apple + Discord
+ * deferred) lands in a follow-up release on the `next` dist-tag, before
+ * the `latest` 0.3.0 ships.
+ *
+ * Until then: drive your own OAuth flow and pass the resulting user
+ * identifier to `submitScore` directly.
+ *
+ * @since 0.3.0
+ * @stability preview
+ */
+declare function useAuthProvider(_options: {
+    readonly provider: 'google' | 'github';
+}): never;
+
+export { type AnonymousPlayerOptions, type PlayerHandle, type PromptedPlayerOptions, type ServerAuthoritativeMarker, useAnonymousPlayer, useAuthProvider, usePromptedPlayer, useServerAuthoritative };

package/dist/identity.js

@@ -0,0 +1,82 @@
+// src/identity.ts
+var isBrowser = () => typeof window !== "undefined";
+function readPersisted(key) {
+  if (!isBrowser()) return null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writePersisted(key, value) {
+  if (!isBrowser()) return;
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+  }
+}
+function removePersisted(key) {
+  if (!isBrowser()) return;
+  try {
+    window.localStorage.removeItem(key);
+  } catch {
+  }
+}
+function mintUuid() {
+  if (isBrowser() && typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `anon-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+function requireStorageKey(fnName, options) {
+  if (!options || typeof options.storageKey !== "string" || options.storageKey.length === 0) {
+    throw new TypeError(`${fnName}: options.storageKey is required (non-empty string)`);
+  }
+  return options.storageKey;
+}
+function useAnonymousPlayer(options) {
+  const storageKey = requireStorageKey("useAnonymousPlayer", options);
+  let id = readPersisted(storageKey);
+  if (id === null || id.length === 0) {
+    id = mintUuid();
+    writePersisted(storageKey, id);
+  }
+  return {
+    id,
+    forget: () => removePersisted(storageKey)
+  };
+}
+function usePromptedPlayer(options) {
+  const storageKey = requireStorageKey("usePromptedPlayer", options);
+  if (typeof options.prompt !== "string" || options.prompt.length === 0) {
+    throw new TypeError("usePromptedPlayer: options.prompt is required (non-empty string)");
+  }
+  let id = readPersisted(storageKey);
+  if (id === null || id.length === 0) {
+    if (!isBrowser() || typeof window.prompt !== "function") {
+      return null;
+    }
+    const entered = window.prompt(options.prompt);
+    if (entered === null || entered.length === 0) {
+      return null;
+    }
+    id = entered;
+    writePersisted(storageKey, id);
+  }
+  return {
+    id,
+    forget: () => removePersisted(storageKey)
+  };
+}
+function useServerAuthoritative() {
+  return { source: "server-authoritative" };
+}
+function useAuthProvider(_options) {
+  throw new Error(
+    "useAuthProvider is not yet implemented in this 0.3.0-next preview. OAuth provider helpers (Google + GitHub for v1) ship in a follow-up release on the `next` dist-tag. Until then, drive your own OAuth flow and pass the resulting user identifier to submitScore directly."
+  );
+}
+
+export { useAnonymousPlayer, useAuthProvider, usePromptedPlayer, useServerAuthoritative };
+//# sourceMappingURL=identity.js.map
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/identity.ts"],"names":[],"mappings":";AAkDA,IAAM,SAAA,GAAY,MAAe,OAAO,MAAA,KAAW,WAAA;AAEnD,SAAS,cAAc,GAAA,EAA4B;AACjD,EAAA,IAAI,CAAC,SAAA,EAAU,EAAG,OAAO,IAAA;AACzB,EAAA,IAAI;AACF,IAAA,OAAO,MAAA,CAAO,YAAA,CAAa,OAAA,CAAQ,GAAG,CAAA;AAAA,EACxC,CAAA,CAAA,MAAQ;AAIN,IAAA,OAAO,IAAA;AAAA,EACT;AACF;AAEA,SAAS,cAAA,CAAe,KAAa,KAAA,EAAqB;AACxD,EAAA,IAAI,CAAC,WAAU,EAAG;AAClB,EAAA,IAAI;AACF,IAAA,MAAA,CAAO,YAAA,CAAa,OAAA,CAAQ,GAAA,EAAK,KAAK,CAAA;AAAA,EACxC,CAAA,CAAA,MAAQ;AAAA,EAER;AACF;AAEA,SAAS,gBAAgB,GAAA,EAAmB;AAC1C,EAAA,IAAI,CAAC,WAAU,EAAG;AAClB,EAAA,IAAI;AACF,IAAA,MAAA,CAAO,YAAA,CAAa,WAAW,GAAG,CAAA;AAAA,EACpC,CAAA,CAAA,MAAQ;AAAA,EAER;AACF;AAEA,SAAS,QAAA,GAAmB;AAC1B,EAAA,IAAI,SAAA,MAAe,OAAO,MAAA,KAAW,eAAe,OAAO,MAAA,CAAO,eAAe,UAAA,EAAY;AAC3F,IAAA,OAAO,OAAO,UAAA,EAAW;AAAA,EAC3B;AAMA,EAAA,OAAO,CAAA,KAAA,EAAQ,IAAA,CAAK,GAAA,EAAK,IAAI,IAAA,CAAK,MAAA,EAAO,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,KAAA,CAAM,CAAA,EAAG,EAAE,CAAC,CAAA,CAAA;AACtE;AAEA,SAAS,iBAAA,CAAkB,QAAgB,OAAA,EAAuD;AAChG,EAAA,IAAI,CAAC,WAAW,OAAO,OAAA,CAAQ,eAAe,QAAA,IAAY,OAAA,CAAQ,UAAA,CAAW,MAAA,KAAW,CAAA,EAAG;AACzF,IAAA,MAAM,IAAI,SAAA,CAAU,CAAA,EAAG,MAAM,CAAA,mDAAA,CAAqD,CAAA;AAAA,EACpF;AACA,EAAA,OAAO,OAAA,CAAQ,UAAA;AACjB;AA0BO,SAAS,mBAAmB,OAAA,EAA+C;AAChF,EAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,oBAAA,EAAsB,OAAO,CAAA;AAClE,EAAA,IAAI,EAAA,GAAK,cAAc,UAAU,CAAA;AACjC,EAAA,IAAI,EAAA,KAAO,IAAA,IAAQ,EAAA,CAAG,MAAA,KAAW,CAAA,EAAG;AAClC,IAAA,EAAA,GAAK,QAAA,EAAS;AACd,IAAA,cAAA,CAAe,YAAY,EAAE,CAAA;AAAA,EAC/B;AACA,EAAA,OAAO;AAAA,IACL,EAAA;AAAA,IACA,MAAA,EAAQ,MAAM,eAAA,CAAgB,UAAU;AAAA,GAC1C;AACF;AAsCO,SAAS,kBAAkB,OAAA,EAAqD;AACrF,EAAA,MAAM,UAAA,GAAa,iBAAA,CAAkB,mBAAA,EAAqB,OAAO,CAAA;AACjE,EAAA,IAAI,OAAO,OAAA,CAAQ,MAAA,KAAW,YAAY,OAAA,CAAQ,MAAA,CAAO,WAAW,CAAA,EAAG;AACrE,IAAA,MAAM,IAAI,UAAU,kEAAkE,CAAA;AAAA,EACxF;AAEA,EAAA,IAAI,EAAA,GAAK,cAAc,UAAU,CAAA;AACjC,EAAA,IAAI,EAAA,KAAO,IAAA,IAAQ,EAAA,CAAG,MAAA,KAAW,CAAA,EAAG;AAClC,IAAA,IAAI,CAAC,SAAA,EAAU,IAAK,OAAO,MAAA,CAAO,WAAW,UAAA,EAAY;AACvD,MAAA,OAAO,IAAA;AAAA,IACT;AACA,IAAA,MAAM,OAAA,GAAU,MAAA,CAAO,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA;AAC5C,IAAA,IAAI,OAAA,KAAY,IAAA,IAAQ,OAAA,CAAQ,MAAA,KAAW,CAAA,EAAG;AAC5C,MAAA,OAAO,IAAA;AAAA,IACT;AACA,IAAA,EAAA,GAAK,OAAA;AACL,IAAA,cAAA,CAAe,YAAY,EAAE,CAAA;AAAA,EAC/B;AACA,EAAA,OAAO;AAAA,IACL,EAAA;AAAA,IACA,MAAA,EAAQ,MAAM,eAAA,CAAgB,UAAU;AAAA,GAC1C;AACF;AA4BO,SAAS,sBAAA,GAAoD;AAClE,EAAA,OAAO,EAAE,QAAQ,sBAAA,EAAuB;AAC1C;AAcO,SAAS,gBAAgB,QAAA,EAA6D;AAC3F,EAAA,MAAM,IAAI,KAAA;AAAA,IACR;AAAA,GAIF;AACF","file":"identity.js","sourcesContent":["/**\n * Identity preset helpers — opinionated, selectable ways for your game to\n * generate or fetch a `playerId` for score submission.\n *\n * Background: every Scorezilla score carries an opaque `playerId`. The SDK\n * doesn't care whether it's a UUID, a nickname, an email, or a server\n * session token. But _how_ your game decides on that value is a UX +\n * privacy decision the team should make explicitly. These presets are the\n * blessed patterns; pick one per integration.\n *\n * See ADR 0003 (MCP identity axis) for the design rationale:\n * https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md\n *\n * @module scorezilla/identity\n * @since 0.3.0\n */\n\nexport interface AnonymousPlayerOptions {\n  /** localStorage key under which the generated UUID is persisted. */\n  readonly storageKey: string;\n}\n\nexport interface PromptedPlayerOptions {\n  /** localStorage key under which the user-entered name is persisted. */\n  readonly storageKey: string;\n  /** Message shown in `window.prompt()` on first run. */\n  readonly prompt: string;\n}\n\n/**\n * Identity handle returned by the storage-backed presets.\n *\n * `forget()` clears the persisted value from browser storage. It does\n * **not** delete server-side score history for this player — to fully\n * erase a player's data, call the admin \"delete player\" endpoint.\n */\nexport interface PlayerHandle {\n  readonly id: string;\n  readonly forget: () => void;\n}\n\n/**\n * Marker returned by `useServerAuthoritative()` to signal that the\n * game's backend (not the browser) owns the `playerId` via the\n * HMAC-signed secure path (`scorezilla/server`).\n */\nexport interface ServerAuthoritativeMarker {\n  readonly source: 'server-authoritative';\n}\n\nconst isBrowser = (): boolean => typeof window !== 'undefined';\n\nfunction readPersisted(key: string): string | null {\n  if (!isBrowser()) return null;\n  try {\n    return window.localStorage.getItem(key);\n  } catch {\n    // Storage may throw in sandboxed iframes, privacy mode, or when the\n    // user has disabled site data. Treat as \"missing\"; the caller will\n    // mint or re-prompt.\n    return null;\n  }\n}\n\nfunction writePersisted(key: string, value: string): void {\n  if (!isBrowser()) return;\n  try {\n    window.localStorage.setItem(key, value);\n  } catch {\n    // ignore; next call will re-mint or re-prompt\n  }\n}\n\nfunction removePersisted(key: string): void {\n  if (!isBrowser()) return;\n  try {\n    window.localStorage.removeItem(key);\n  } catch {\n    // ignore\n  }\n}\n\nfunction mintUuid(): string {\n  if (isBrowser() && typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {\n    return crypto.randomUUID();\n  }\n  // Best-effort fallback: timestamp + random suffix. Not cryptographically\n  // strong, but opaque enough for the identifier-only use case. The\n  // browsers we target (Chrome 92+, Firefox 95+, Safari 15.4+) all have\n  // crypto.randomUUID — this branch is reached only in non-browser\n  // environments where useAnonymousPlayer shouldn't be called anyway.\n  return `anon-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;\n}\n\nfunction requireStorageKey(fnName: string, options: { storageKey?: unknown } | undefined): string {\n  if (!options || typeof options.storageKey !== 'string' || options.storageKey.length === 0) {\n    throw new TypeError(`${fnName}: options.storageKey is required (non-empty string)`);\n  }\n  return options.storageKey;\n}\n\n/**\n * Anonymous player identity. Generates an opaque UUID on first run and\n * persists it in `localStorage` so the same browser keeps the same ID\n * across page reloads.\n *\n * **Privacy.** Stores a randomly-generated UUID in browser localStorage;\n * the value is sent to the API on every score submission and persisted\n * indefinitely in the player's score-history rows. No PII is collected.\n * `forget()` removes the localStorage entry; for full server-side erasure\n * call the admin \"delete player\" endpoint.\n *\n * @example\n * ```ts\n * import { Scorezilla } from 'scorezilla';\n * import { useAnonymousPlayer } from 'scorezilla/identity';\n *\n * const player = useAnonymousPlayer({ storageKey: 'mygame:player' });\n * const sz = new Scorezilla({ publicKey: 'pk_…' });\n * await sz.submitScore({ boardId, playerId: player.id, score: 42 });\n * ```\n *\n * @since 0.3.0\n * @stability stable\n */\nexport function useAnonymousPlayer(options: AnonymousPlayerOptions): PlayerHandle {\n  const storageKey = requireStorageKey('useAnonymousPlayer', options);\n  let id = readPersisted(storageKey);\n  if (id === null || id.length === 0) {\n    id = mintUuid();\n    writePersisted(storageKey, id);\n  }\n  return {\n    id,\n    forget: () => removePersisted(storageKey),\n  };\n}\n\n/**\n * Prompted player identity. On first run shows a `window.prompt()` asking\n * the user for a name, then persists it in `localStorage` for subsequent\n * visits. Returns `null` if there is no browser (SSR), no `window.prompt`,\n * or if the user cancelled / entered an empty value.\n *\n * **Privacy.** The user-entered string is stored in browser localStorage,\n * transmitted to the API on every score submission, and persisted\n * indefinitely on the leaderboard. The persisted value is whatever the\n * user typed — sanitize at the UI layer if you care. `forget()` clears\n * local state but does NOT delete server-side history.\n *\n * **UX caveat.** `window.prompt()` blocks the main thread and looks\n * dated in modern apps. For a polished flow, build your own inline form\n * and pass the result to `submitScore` directly — the preset is here to\n * cover quick prototypes and jam-style integrations.\n *\n * @example\n * ```ts\n * import { Scorezilla } from 'scorezilla';\n * import { usePromptedPlayer } from 'scorezilla/identity';\n *\n * const player = usePromptedPlayer({\n *   storageKey: 'mygame:player',\n *   prompt: 'Enter a name for the leaderboard:',\n * });\n *\n * if (player) {\n *   const sz = new Scorezilla({ publicKey: 'pk_…' });\n *   await sz.submitScore({ boardId, playerId: player.id, score: 42 });\n * }\n * ```\n *\n * @since 0.3.0\n * @stability stable\n */\nexport function usePromptedPlayer(options: PromptedPlayerOptions): PlayerHandle | null {\n  const storageKey = requireStorageKey('usePromptedPlayer', options);\n  if (typeof options.prompt !== 'string' || options.prompt.length === 0) {\n    throw new TypeError('usePromptedPlayer: options.prompt is required (non-empty string)');\n  }\n\n  let id = readPersisted(storageKey);\n  if (id === null || id.length === 0) {\n    if (!isBrowser() || typeof window.prompt !== 'function') {\n      return null;\n    }\n    const entered = window.prompt(options.prompt);\n    if (entered === null || entered.length === 0) {\n      return null;\n    }\n    id = entered;\n    writePersisted(storageKey, id);\n  }\n  return {\n    id,\n    forget: () => removePersisted(storageKey),\n  };\n}\n\n/**\n * Server-authoritative identity marker. Signals that the game's backend\n * is responsible for the `playerId` via the HMAC-signed secure path\n * (`scorezilla/server`). The browser SDK does no identity work — the\n * server picks the value, signs the submission, and posts.\n *\n * The return value is a no-op marker; you don't pass it anywhere. It\n * exists so MCP-returned snippets can emit a single line that\n * unambiguously says \"this game uses the secure path; identity is\n * server-authoritative.\"\n *\n * @example\n * ```ts\n * // Client (no identity helper needed):\n * import { useServerAuthoritative } from 'scorezilla/identity';\n * useServerAuthoritative();\n *\n * // Server (where the real work happens):\n * import { Scorezilla } from 'scorezilla/server';\n * const sz = new Scorezilla({ secretKey: process.env.SCOREZILLA_SECRET_KEY! });\n * await sz.submitScore({ boardId, playerId: serverDerivedId, score });\n * ```\n *\n * @since 0.3.0\n * @stability stable\n */\nexport function useServerAuthoritative(): ServerAuthoritativeMarker {\n  return { source: 'server-authoritative' };\n}\n\n/**\n * OAuth-backed player identity. **Preview stub in 0.3.0-next.x** — throws\n * on call. Full implementation (Google + GitHub for v1, Apple + Discord\n * deferred) lands in a follow-up release on the `next` dist-tag, before\n * the `latest` 0.3.0 ships.\n *\n * Until then: drive your own OAuth flow and pass the resulting user\n * identifier to `submitScore` directly.\n *\n * @since 0.3.0\n * @stability preview\n */\nexport function useAuthProvider(_options: { readonly provider: 'google' | 'github' }): never {\n  throw new Error(\n    'useAuthProvider is not yet implemented in this 0.3.0-next preview. ' +\n      'OAuth provider helpers (Google + GitHub for v1) ship in a follow-up ' +\n      'release on the `next` dist-tag. Until then, drive your own OAuth flow ' +\n      'and pass the resulting user identifier to submitScore directly.',\n  );\n}\n"]}

package/dist/index.cjs

@@ -33,6 +33,7 @@ function validateConfig(cfg) {
     timeoutMs: cfg.timeoutMs,
     maxRetries: cfg.maxRetries,
     sleepImpl: cfg.sleepImpl,
+    warn: cfg.warn,
     userAgent: cfg.userAgent,
     auth
   };
@@ -119,7 +120,9 @@ var ScorezillaError = class _ScorezillaError extends Error {
    *  {@link ScorezillaErrorCode}. For network errors, this is `'network_error'`;
    *  for aborts, `'aborted'`; for timeouts, `'timeout'`. */
   code;
-  /** Sub-classifier — present on `out_of_bounds` (`'below_min' | 'above_max'`)
+  /** Sub-classifier — present on:
+   *    - `out_of_bounds`: `'below_min' | 'above_max'`
+   *    - `usage_cap_exceeded`: `'over_cap' | 'suspended'`
    *  and possibly other codes in future minor releases. */
   reason;
   /** Seconds — present on `rate_limited`. Honored by the transport's retry
@@ -132,6 +135,20 @@ var ScorezillaError = class _ScorezillaError extends Error {
   bound;
   /** Which rate-limit layer fired on `rate_limited`. */
   layer;
+  /** Tenant's billing tier — present on `usage_cap_exceeded`. */
+  tier;
+  /** The cap value crossed on `usage_cap_exceeded`. `0` indicates a
+   *  suspended tenant. `undefined` on all other error codes. */
+  cap;
+  /** The post-increment submit count on `usage_cap_exceeded`. Always
+   *  `> cap` when `reason === 'over_cap'`. */
+  count;
+  /** The period the count belongs to on `usage_cap_exceeded`, in `YYYY-MM`
+   *  UTC form. */
+  period;
+  /** ISO-8601 timestamp of midnight UTC on the 1st of the next month —
+   *  the counter's natural reset point on `usage_cap_exceeded`. */
+  resetsAt;
   /** The underlying cause (e.g., a `TypeError: fetch failed`) for
    *  network/abort/timeout paths. `undefined` when the error came from a
    *  successfully-parsed API error body. */
@@ -146,6 +163,11 @@ var ScorezillaError = class _ScorezillaError extends Error {
     this.requestId = truncateField(init.requestId);
     this.bound = init.bound;
     this.layer = truncateField(init.layer);
+    this.tier = truncateField(init.tier);
+    this.cap = init.cap;
+    this.count = init.count;
+    this.period = truncateField(init.period);
+    this.resetsAt = truncateField(init.resetsAt);
     this.cause = init.cause;
     Object.setPrototypeOf(this, _ScorezillaError.prototype);
     if (typeof Error.captureStackTrace === "function") {
@@ -159,6 +181,22 @@ var ScorezillaError = class _ScorezillaError extends Error {
   isRateLimited() {
     return this.code === "rate_limited";
   }
+  /**
+   * `true` when this error is a 402 / `usage_cap_exceeded`. The tenant
+   * has either hit their tier's monthly submit cap (`reason ===
+   * 'over_cap'`) or is suspended (`reason === 'suspended'`).
+   *
+   * Consumers SHOULD NOT auto-retry on this error — the cap doesn't lift
+   * until `resetsAt`. Surface to the developer with an upgrade prompt
+   * (over_cap) or contact-support message (suspended).
+   */
+  isUsageCapExceeded() {
+    return this.code === "usage_cap_exceeded";
+  }
+  /** `true` when this error is a 402 + reason 'suspended' (vs over-cap). */
+  isSuspended() {
+    return this.code === "usage_cap_exceeded" && this.reason === "suspended";
+  }
   /** `true` when this error is a 401 / `unauthorized` (or 403 / `forbidden`). */
   isAuth() {
     return this.code === "unauthorized" || this.code === "forbidden";
@@ -171,13 +209,21 @@ var ScorezillaError = class _ScorezillaError extends Error {
   isOutOfBounds() {
     return this.code === "out_of_bounds";
   }
-  /** `true` for transient / retryable conditions: network errors, timeouts,
-   *  5xx, and 429. The transport layer relies on this for its retry policy. */
+  /** `true` for the SDK's retryable conditions: pure network errors, 5xx, and
+   *  429. Deliberately excludes `timeout` and `aborted` — those are caller-
+   *  observable terminal states, not transient. Aligned with `shouldRetryError`
+   *  in `retry.ts` so a consumer mirroring the SDK's retry policy gets the
+   *  same answer the transport does. */
   isTransient() {
-    if (this.status === STATUS_NETWORK_ERROR) return true;
+    if (this.code === "network_error") return true;
     if (this.status >= 500 && this.status < 600) return true;
     return this.isRateLimited();
   }
+  /** `true` when this error is a 409 / `conflict` (idempotency-key conflict
+   *  on retry). */
+  isConflict() {
+    return this.code === "conflict";
+  }
   // ─── Factory ─────────────────────────────────────────────────────────
   /**
    * Build a `ScorezillaError` from a fetch round-trip outcome.
@@ -198,6 +244,13 @@ var ScorezillaError = class _ScorezillaError extends Error {
         retryAfter: body.retryAfter,
         bound: body.bound,
         layer: body.layer,
+        // Usage-cap fields from `ApiError` (populated by the server on
+        // 402 responses; undefined on other errors).
+        tier: body.tier,
+        cap: body.cap,
+        count: body.count,
+        period: body.period,
+        resetsAt: body.resetsAt,
         requestId,
         cause
       });
@@ -239,8 +292,10 @@ var ScorezillaError = class _ScorezillaError extends Error {
 };
 function codeForStatus(status) {
   if (status === 401) return "unauthorized";
+  if (status === 402) return "usage_cap_exceeded";
   if (status === 403) return "forbidden";
   if (status === 404) return "not_found";
+  if (status === 409) return "conflict";
   if (status === 422) return "out_of_bounds";
   if (status === 429) return "rate_limited";
   if (status >= 500) return "internal_error";
@@ -351,6 +406,7 @@ async function request(opts) {
       }
       const response = await fetchImpl(url, init);
       if (response.ok) {
+        warnOnDeprecationOnce(response, opts.warnImpl);
         return await parseJson(response);
       }
       const body = await safelyParseErrorBody(response);
@@ -462,6 +518,29 @@ function readRetryAfter(response) {
   const n = Number(raw);
   return Number.isFinite(n) && n >= 0 ? n : void 0;
 }
+var seenDeprecations = /* @__PURE__ */ new Set();
+function warnOnDeprecationOnce(response, warnImpl) {
+  const deprecation = response.headers.get("Deprecation");
+  const sunset = response.headers.get("Sunset");
+  if (!deprecation && !sunset) return;
+  const link = response.headers.get("Link") ?? "";
+  const key = `${deprecation ?? ""}|${sunset ?? ""}|${link}`;
+  if (seenDeprecations.has(key)) return;
+  seenDeprecations.add(key);
+  const detail = [];
+  if (deprecation === "true" || deprecation) detail.push(`Deprecation: ${deprecation}`);
+  if (sunset) detail.push(`Sunset: ${sunset}`);
+  if (link) {
+    const m = link.match(/<([^>]+)>/);
+    if (m) detail.push(`Docs: ${m[1]}`);
+  }
+  const message = `[scorezilla-sdk] API responded with deprecation signal: ${detail.join(" \xB7 ")}. Upgrade your SDK before the sunset date.`;
+  if (warnImpl) {
+    warnImpl(message);
+  } else {
+    console.warn(message);
+  }
+}
 function combineSignalsWithTimeout(caller, timeoutMs) {
   const ctrl = new AbortController();
   let didTimeOut = false;
@@ -550,10 +629,11 @@ function validateMetadata(metadata) {
       `scorezilla: metadata exceeds ${METADATA_MAX_BYTES} bytes (got ${byteLength} bytes when JSON-stringified)`
     );
   }
+  return serialized;
 }
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`. */
-  static version = "0.1.0-next.3";
+  static version = "0.3.0-next.0";
   #config;
   #userAgent;
   #authHeader;
@@ -611,7 +691,8 @@ var Scorezilla = class _Scorezilla {
     return this.#request({
       path: submitScorePath(input.boardId),
       method: "POST",
-      body
+      body,
+      signal: input.signal
     });
   }
   /**
@@ -635,7 +716,8 @@ var Scorezilla = class _Scorezilla {
     if (input.offset !== void 0) q.offset = input.offset;
     return this.#request({
       path: getLeaderboardPath(input.boardId, q),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /**
@@ -664,7 +746,8 @@ var Scorezilla = class _Scorezilla {
   async getPlayerRank(input) {
     return this.#request({
       path: getPlayerRankPath(input.boardId, input.playerId),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   /**
@@ -689,7 +772,8 @@ var Scorezilla = class _Scorezilla {
     if (input.after !== void 0) q.after = input.after;
     return this.#request({
       path: getWindowAroundPath(input.boardId, input.playerId, q),
-      method: "GET"
+      method: "GET",
+      signal: input.signal
     });
   }
   // ─── Internal ────────────────────────────────────────────────────────
@@ -716,7 +800,9 @@ var Scorezilla = class _Scorezilla {
       headers
     };
     if (opts.body !== void 0) requestOpts.body = opts.body;
+    if (opts.signal !== void 0) requestOpts.signal = opts.signal;
     if (this.#config.fetch !== void 0) requestOpts.fetchImpl = this.#config.fetch;
+    if (this.#config.warn !== void 0) requestOpts.warnImpl = this.#config.warn;
     if (this.#config.timeoutMs !== void 0) requestOpts.timeoutMs = this.#config.timeoutMs;
     if (this.#config.maxRetries !== void 0 || this.#config.sleepImpl !== void 0) {
       requestOpts.retry = {
@@ -732,7 +818,7 @@ function createClient(config) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.1.0-next.3";
+var SDK_VERSION = "0.3.0-next.0";
 
 exports.SDK_VERSION = SDK_VERSION;
 exports.Scorezilla = Scorezilla;