scorezilla 0.2.0 → 0.3.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.3.0-next.0
+
+### Minor Changes
+
+- [#36](https://github.com/isco-tec/scorezilla-js/pull/36) [`19c2dcc`](https://github.com/isco-tec/scorezilla-js/commit/19c2dcc14d2000551d80498813b075172c8f4d66) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(identity): preset helpers for `scorezilla/identity` (Phase 1)
+
+  New subpath export: `scorezilla/identity`. Three identity-strategy
+  presets ship as `stable`; one OAuth helper ships as a preview stub.
+
+  **Stable in this release:**
+  - `useAnonymousPlayer({ storageKey })` — generates a UUID, persists in
+    localStorage, same browser keeps the same id across reloads. Returns
+    `{ id, forget() }`. Privacy-safe by default (no PII).
+  - `usePromptedPlayer({ storageKey, prompt })` — `window.prompt()` on
+    first run, persists to localStorage. Returns `{ id, forget() } | null`
+    (null when SSR, no `prompt`, or user cancels).
+  - `useServerAuthoritative()` — no-op marker for snippets using the
+    HMAC-signed secure path (`scorezilla/server`). The browser SDK does
+    no identity work; the server picks the value.
+
+  **Preview stub in this release (throws on call):**
+  - `useAuthProvider({ provider: 'google' | 'github' })` — OAuth-backed
+    identity. Full implementation (Google + GitHub for v1) ships in a
+    follow-up `next` release before the 0.3.0 latest promote.
+
+  Per [ADR 0003](https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md). All helpers document where data is stored and
+  what `forget()` / `signOut()` does NOT do (server-side history is
+  retained — call admin delete-player for full erasure).
+
+  Closes upstream tracking issue isco-tec/scorezilla#125 (Phase 1).
+
 ## 0.2.0 — `scorezilla/server` HMAC adapter GA
 
 ### Minor Changes

package/dist/identity.cjs

@@ -0,0 +1,87 @@
+'use strict';
+
+// 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."
+  );
+}
+
+exports.useAnonymousPlayer = useAnonymousPlayer;
+exports.useAuthProvider = useAuthProvider;
+exports.usePromptedPlayer = usePromptedPlayer;
+exports.useServerAuthoritative = useServerAuthoritative;
+//# sourceMappingURL=identity.cjs.map
+//# sourceMappingURL=identity.cjs.map

package/dist/identity.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/identity.ts"],"names":[],"mappings":"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","file":"identity.cjs","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/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":"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","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

@@ -633,7 +633,7 @@ function validateMetadata(metadata) {
 }
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`. */
-  static version = "0.2.0";
+  static version = "0.3.0-next.0";
   #config;
   #userAgent;
   #authHeader;
@@ -818,7 +818,7 @@ function createClient(config) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.2.0";
+var SDK_VERSION = "0.3.0-next.0";
 
 exports.SDK_VERSION = SDK_VERSION;
 exports.Scorezilla = Scorezilla;