scorezilla 0.1.0-next.0

package/README.md

@@ -0,0 +1,212 @@
+# scorezilla
+
+[![npm version](https://img.shields.io/npm/v/scorezilla.svg)](https://www.npmjs.com/package/scorezilla)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/scorezilla)](https://bundlephobia.com/package/scorezilla)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/isco-tec/scorezilla-js/sdk-ci.yml?branch=main)](https://github.com/isco-tec/scorezilla-js/actions)
+[![provenance](https://img.shields.io/badge/npm-provenance-success)](https://docs.npmjs.com/generating-provenance-statements)
+
+Official JavaScript / TypeScript SDK for [Scorezilla](https://scorezilla.dev) —
+focused leaderboard infrastructure for indie games, browser games, and
+AI-vibe-coded games.
+
+- **Tiny.** ~4 KB gzipped. No runtime dependencies.
+- **Universal.** Browser, Node ≥ 20, Cloudflare Workers, Bun, Deno.
+- **Typed.** First-class TypeScript with strict types and rich JSDoc.
+- **Safe-by-default.** Automatic retries on transient failures with idempotency
+  keys; per-request timeouts; cancellation via `AbortSignal`.
+- **Private.** No cookies, no `localStorage`, no fingerprinting beyond runtime
+  detection — see [COMPATIBILITY.md](./COMPATIBILITY.md).
+
+> **Status:** v0.1.0 ships the **public-key client** (browser-safe). The HMAC
+> server adapter (`scorezilla/server`) lands in v0.2.0; React
+> (`scorezilla/react`) in v0.3.0; Phaser (`scorezilla/phaser`) in v0.4.0. See
+> [CHANGELOG.md](./CHANGELOG.md) and [VERSIONING.md](./VERSIONING.md).
+
+> **Commercial context.** Scorezilla is a hosted leaderboard service with free
+> and paid tiers — see [scorezilla.dev/pricing](https://scorezilla.dev/pricing).
+> This SDK is MIT-licensed and works identically across every plan; get your API
+> key from the [operator dashboard](https://dashboard.scorezilla.dev).
+
+## Install
+
+```bash
+npm install scorezilla
+# or
+pnpm add scorezilla
+# or
+yarn add scorezilla
+# or
+bun add scorezilla
+```
+
+## Quickstart
+
+```ts
+import { Scorezilla, ScorezillaError } from 'scorezilla';
+
+const sz = new Scorezilla({ publicKey: 'pk_mygame_aBcDeF…' });
+
+try {
+  const r = await sz.submitScore({
+    boardId: 'board-uuid',
+    playerId: 'player-uuid',
+    score: 9001,
+    metadata: { level: 'hard' },
+  });
+  if (r.isPersonalBest) {
+    console.log(`🏆 New personal best! Rank ${r.rank} of ${r.totalEntries}`);
+  }
+} catch (e) {
+  if (e instanceof ScorezillaError && e.isRateLimited()) {
+    console.warn(`Rate-limited. Retry after ${e.retryAfter}s.`);
+  } else throw e;
+}
+```
+
+The four public methods:
+
+```ts
+await sz.submitScore({ boardId, playerId, score, metadata? });
+await sz.getLeaderboard({ boardId, top?, offset? });
+await sz.getPlayerRank({ boardId, playerId });
+await sz.getWindowAround({ boardId, playerId, before?, after? });
+```
+
+See [**API.md**](./API.md) for the full reference, including every response
+field, every error code, and advanced patterns.
+
+## Error handling
+
+Every failure path — HTTP non-2xx, network error, timeout, abort, JSON parse
+error — throws a single `ScorezillaError`. **Branch on `code`**
+(machine-stable), never on `message` (English-only, may change without a major
+bump):
+
+```ts
+import { ScorezillaError } from 'scorezilla';
+
+try {
+  await sz.submitScore({ boardId, playerId, score });
+} catch (e) {
+  if (!(e instanceof ScorezillaError)) throw e;
+
+  if (e.isRateLimited()) await sleep((e.retryAfter ?? 30) * 1000);
+  else if (e.isAuth()) throw new Error('SDK misconfigured');
+  else if (e.code === 'out_of_bounds')
+    console.warn(`Score crosses ${e.reason} bound (limit ${e.bound})`);
+  else if (e.isTransient()) /* automatic retries already exhausted */ throw e;
+  else throw e;
+}
+```
+
+The error class carries the request ID, status, and the underlying cause for
+support tickets:
+
+```ts
+console.error(`Scorezilla ${e.code} (${e.status}) — req ${e.requestId}`);
+```
+
+## Runtime support
+
+| Runtime                | Status                        | Notes                                                   |
+| ---------------------- | ----------------------------- | ------------------------------------------------------- |
+| **Node**               | ≥ 20                          | Hard requirement. Native `fetch` + `crypto.randomUUID`. |
+| **Browsers**           | All evergreen                 | Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+.        |
+| **Cloudflare Workers** | ✅                            | Detected via `navigator.userAgent`.                     |
+| **Bun**                | ≥ 1.0 (best-effort in v0.1.0) | Promoted to hard gate in v0.2.0 if stable.              |
+| **Deno**               | ≥ 1.40                        | Native fetch + Web Crypto.                              |
+| **React Native**       | unverified                    | Requires `react-native-get-random-values` polyfill.     |
+
+See [COMPATIBILITY.md](./COMPATIBILITY.md) for the detailed matrix, the
+`exactOptionalPropertyTypes` workaround, and the privacy invariants.
+
+## CDN usage
+
+For zero-build prototyping, import from jsDelivr. Replace `<VERSION>` with the
+exact release you want (see the [releases page](https://github.com/isco-tec/scorezilla-js/releases)):
+
+```html
+<script type="module">
+  import { Scorezilla } from 'https://cdn.jsdelivr.net/npm/scorezilla@<VERSION>/dist/index.js';
+  const sz = new Scorezilla({ publicKey: 'pk_…' });
+  // …
+</script>
+```
+
+For production, pair the version pin with
+[Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
+— the SHA-384 hash for each release ships in the GitHub release notes:
+
+```html
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/scorezilla@<VERSION>/dist/index.js"
+  integrity="sha384-<copy-from-release-notes>"
+  crossorigin="anonymous"
+></script>
+```
+
+A complete vanilla example lives at
+[`examples/vanilla/`](https://github.com/isco-tec/scorezilla-js/tree/main/examples/vanilla)
+and a Node CLI demo at
+[`examples/node-cli/`](https://github.com/isco-tec/scorezilla-js/tree/main/examples/node-cli).
+(The examples are in the source repo only — not in the npm tarball.)
+
+## Custom fetch / polyfills
+
+Pass your own `fetch` for environments where the global is missing or you want
+to mock for tests:
+
+```ts
+import nodeFetch from 'node-fetch';
+const sz = new Scorezilla({ publicKey, fetch: nodeFetch });
+```
+
+The signature
+`(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>` is
+intentionally broader than `typeof fetch` so `node-fetch`, `undici`, `vi.fn()`,
+and `jest.fn()` all typecheck cleanly.
+
+## Per-request timeout and retries
+
+```ts
+const sz = new Scorezilla({
+  publicKey,
+  timeoutMs: 5_000, // default 30_000
+  maxRetries: 1, // default 2 (retries 5xx / 429 / network)
+});
+```
+
+Retries automatically reuse the same `Idempotency-Key` across attempts, so
+server-side dedup (when added) is safe by default.
+
+## Versioning
+
+Strict SemVer from v0.1.0 onward. The machine-stable surface is `code` strings
+on `ScorezillaError`, response field names, method signatures, and config
+fields. The human-readable `message` is **not** part of the contract.
+
+See [VERSIONING.md](./VERSIONING.md) for the full breaking-change rules,
+deprecation policy, and 0.x → 1.0 exit criteria.
+
+## Contributing
+
+Issues and PRs welcome. Local development:
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test                   # all projects
+pnpm test:unit              # unit only (fast)
+pnpm test:coverage          # unit + coverage gate
+pnpm build                  # tsup → dist/
+pnpm check:types-resolution # attw — exports map validation
+pnpm size                   # size-limit (6 KB gzip ceiling)
+```
+
+Add a release note with `pnpm changeset` — see [`.changeset/README.md`](./.changeset/README.md) for the workflow.
+
+## License
+
+[MIT](./LICENSE) © [isco-tec](https://github.com/isco-tec)

package/VERSIONING.md

@@ -0,0 +1,119 @@
+# Versioning policy
+
+Scorezilla follows [Semantic Versioning](https://semver.org/) starting at
+**v0.1.0**. This document defines what counts as a breaking change, what the
+SemVer contract covers (and explicitly does NOT cover), and the path to v1.0.
+
+## The SemVer contract
+
+### Covered by SemVer
+
+**Machine-stable.** A change to any of these requires a major version bump.
+
+| What                                               | Where                                                                   | Example                                                                                                           |
+| -------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **Method names**                                   | `Scorezilla.*`                                                          | Renaming `submitScore` → `postScore` is a major bump.                                                             |
+| **Method signatures (required args, return type)** | `Scorezilla.*`                                                          | Adding a required parameter is a major bump. Tightening a return type (`number` → `1 \| 2 \| 3`) is a major bump. |
+| **Error codes**                                    | `ScorezillaError.code`                                                  | Renaming `out_of_bounds` → `score_out_of_range` is a major bump. Removing a code is a major bump.                 |
+| **Error sub-fields**                               | `ScorezillaError.{reason, retryAfter, bound, layer, status, requestId}` | Renaming `retryAfter` → `retryAfterSec` is a major bump.                                                          |
+| **Config field names**                             | `ScorezillaConfig.*`                                                    | Renaming `baseUrl` → `apiOrigin` is a major bump.                                                                 |
+| **Auth mode discriminator**                        | `publicKey` vs `secretKey`                                              | Adding a third top-level auth field is non-breaking; renaming either is a major bump.                             |
+| **Type exports**                                   | `import type { … } from 'scorezilla'`                                   | Removing or renaming a type export is a major bump.                                                               |
+| **Default behavior of optional knobs**             | `timeoutMs`, `maxRetries`, retry windows                                | Changing the default of `timeoutMs` from 30 000 to 5 000 is a major bump.                                         |
+
+### NOT covered by SemVer
+
+**English-flavored and free to change.**
+
+| What                                     | Where                            | Why                                                                                                                                                                                                 |
+| ---------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`message` text on errors**             | `ScorezillaError.message`        | English-only operator hint. Branch on `code` and `reason` instead.                                                                                                                                  |
+| **Error stack format**                   | `ScorezillaError.stack`          | V8 / SpiderMonkey / JavaScriptCore each format differently and update across runtime versions.                                                                                                      |
+| **Whitespace / casing in `User-Agent`**  | Header value                     | Cosmetic.                                                                                                                                                                                           |
+| **Internal module layout**               | `src/*`                          | Not part of the public surface. Importing from anywhere other than `'scorezilla'` (or its documented subpaths `'scorezilla/server'` / `'scorezilla/react'` / `'scorezilla/phaser'`) is unsupported. |
+| **Server-side response field additions** | New fields on `*Response` shapes | Response types are open `Record`-friendly — the API may add fields in a minor release without breaking consumers who don't read them.                                                               |
+
+## What counts as a breaking change
+
+### Breaking (major bump)
+
+- Removing or renaming an exported symbol (class, function, type)
+- Removing a method on `Scorezilla`
+- Removing a field on a published response type
+- Renaming or removing an error code
+- Adding a **required** argument to a method
+- Narrowing a return type (e.g., `number | undefined` → `number`)
+- Changing the default value of an optional knob in a user-visible way
+- Tightening runtime validation that used to accept some input
+- Dropping support for a documented runtime (e.g., Node 20)
+
+### Non-breaking (minor or patch bump)
+
+- Adding a new method
+- Adding a new optional argument with a backward-compatible default
+- Adding a new error code that the server already returns
+- Adding a new field on a response type
+- Bug fixes that align behavior with the documented contract
+- Performance / bundle-size improvements
+- New exported type that doesn't replace an existing one
+- New subpath export (e.g., adding `scorezilla/server` in v0.2.0)
+
+### Patch-bump only
+
+- Documentation updates
+- Internal refactors that don't change observable behavior
+- Dependency version bumps within `peerDependencies` semver ranges
+
+## Deprecation policy
+
+When we need to remove or replace a public symbol:
+
+1. **Mark deprecated.** Add `@deprecated` JSDoc on the symbol with:
+   - The version it was deprecated (`@deprecated 0.5.0`)
+   - The version it will be removed (`will be removed in 1.0.0`)
+   - The replacement, if any
+2. **Runtime warning.** First call site emits a single `console.warn`:
+   ```
+   scorezilla: `oldMethod` is deprecated since 0.5.0 and will be removed in 1.0.0. Use `newMethod` instead.
+   ```
+   Suppressible via `SCOREZILLA_SUPPRESS_DEPRECATION_WARNINGS=1` env or the
+   `suppressDeprecationWarnings: true` config field.
+3. **Minimum window.** A symbol must spend at least **one full minor release**
+   in the deprecated state before removal in the next major. This gives
+   consumers a guaranteed upgrade path without forced churn.
+4. **CHANGELOG entry.** Both the deprecation and the removal are explicitly
+   called out.
+
+## 0.x → 1.0 exit criteria
+
+The SDK stays in `0.x` until ALL of the following are true:
+
+- [ ] 30 days have passed on `main` without a breaking change to the core
+      surface (the `Scorezilla` class + `ScorezillaError` + `ScorezillaConfig`).
+- [ ] **`scorezilla/server`** (HMAC adapter, v0.2.0) has shipped and seen
+      production use.
+- [ ] **`scorezilla/react`** (React adapter, v0.3.0) has shipped and seen
+      production use.
+- [ ] Zero open issues tagged `api-shape-drift` from real-world consumers.
+- [ ] The 4-method surface (`submitScore`, `getLeaderboard`, `getPlayerRank`,
+      `getWindowAround`) has not had a signature change for the same 30-day
+      window.
+
+When all five are met, we cut **v1.0.0** with no breaking changes from the last
+0.x — v1.0 is just "this is the surface we commit to." Subsequent breaking
+changes follow normal SemVer (major bump).
+
+## Pre-release tags
+
+| Tag            | Meaning                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------ |
+| `latest`       | Stable, recommended for production.                                                                          |
+| `next`         | Release candidate. Installable via `npm install scorezilla@next`.                                            |
+| `experimental` | Alpha features behind a flag. May break without notice between releases. Not covered by the SemVer contract. |
+
+## Reporting drift
+
+If you encounter behavior that contradicts this document — e.g., a `code` value
+changed across a minor release — please file an issue at
+<https://github.com/isco-tec/scorezilla-js/issues> with the tag
+`api-shape-drift`. These reports gate the 1.0 cut.