brawlstars-sdk 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [0.3.0] - 2026-02-28
+
+### Added
+
+- Validation modes: `off`, `warn` (default), `strict`.
+- `onRateLimit` hook with retry metadata.
+- Public export: `encodeTag` and `EncodeTagOptions`.
+- Integration test suite with mocked HTTP API scenarios (`test:integration`).
+- API parity script: `npm run verify:api`.
+- `CHANGES.md` update log.
+- Security scanner script: `npm run scan:secrets`.
+- Verification report output: `npm run verify:api:report` (`reports/verify-api.json`).
+
+### Changed
+
+- Strict validation now throws `ResponseValidationError` with `expectedSchema` and `actualPayload`.
+- Validation `warn` mode now uses configurable `logger.warn`.
+- Error metadata now includes `headers`, `retryAfter` (seconds), and `request` metadata.
+- Retry logic now consumes normalized `Retry-After` and `x-ratelimit-*` header variants.
+- Cache key generation now uses stable `method|path|sortedQuery|bodyHash|whitelistedHeaders`.
+- Cache-key whitelist is configurable through `cacheKeyHeaders`.
+- CI now runs integration tests in addition to unit tests.
+- CI and release workflows now use `npm ci`.
+
+## [0.2.0] - 2026-02-28
+
+### Added
+
+- Amélioration: corrections critiques et durcissement complet du SDK.
+- `ClientError` and `ValidationError` error classes with unified metadata fields (`body`, `requestId`, `retryAfterMs`).
+- Observability module with `requestStart`, `requestEnd`, `requestError` events.
+- Optional `prom-client` compatible adapter helper (`createPromClientAdapter`).
+- Endpoint-level cache invalidation (`invalidateCache(endpoint?)`).
+- Coverage gates via Vitest (`>= 90%` thresholds).
+- Coverage plugin `@vitest/coverage-v8` and thresholded runtime coverage reports.
+- Benchmark tooling (`benchmarks/local-bench.mjs`, `bench:local`, `bench:smoke`).
+- Consumer test for built package import (`tests/consumer.test.ts`).
+- Added targeted tests for validators, response parsers, list normalization, encoding, retry/rate-limit, cache and observability metadata.
+- Architecture, security, audit and benchmark documentation.
+- Release workflow (`.github/workflows/release.yml`) and Dependabot config.
+- `types/index.d.ts` public type entry.
+
+### Changed
+
+- Retry strategy now supports explicit jitter modes (`jitter: "full" | "none"`).
+- Default retry base delay is now `100ms` with `maxAttempts: 4`.
+- Rate-limit handling distinguishes route-scoped and global throttling windows.
+- Concurrency slots are now reserved only during active fetch attempts, so route-scoped waits do not block unrelated routes.
+- Preferred paginated signatures are now `opts?` with backward-compatible legacy overloads.
+- CI now runs lint, typecheck, tests, coverage, build, consumer test and benchmark smoke.
+- README rewritten with migration guide, architecture rationale and release policy.
+
+### Kept for Compatibility
+
+- `ResponseValidationError` remains exported as an alias-compatible class.
+- Legacy paginated method signatures (`query?, options?`) continue to work.
+
+## [0.1.0] - 2026-02-27
+
+### Added
+
+- Initial TypeScript wrapper for all discovered Brawl Stars API endpoints.
+- Strict public typings and normalized list response model.
+- `BrawlStarsClient` with endpoint groups: players, clubs, rankings, brawlers, gamemodes, events.
+- Resilience layer: timeout, retry with jitter, adaptive rate-limit handling, concurrency pool.
+- Optional in-memory LRU cache with request and endpoint overrides.
+- Hook system: `beforeRequest`, `afterResponse`, `onError`.
+- Typed error classes with structured metadata.
+- Optional runtime response validation.
+- Unit tests for retries, throttling, cache, parsing, hooks, and error behavior.
+- API discovery parser script and generated documentation (`docs/API_DISCOVERY.md`).
+- ESM + CJS packaging, CI workflow, and examples.

package/CHANGES.md

@@ -0,0 +1,19 @@
+# Update Log
+
+## Quality 10 Upgrade
+
+- Added validation modes: `off`, `warn` (default), and `strict`.
+- Added strict `ResponseValidationError` metadata (`expectedSchema`, `actualPayload`).
+- Improved rate-limit parsing (`Retry-After` numeric/date + x-ratelimit variants).
+- Extended typed error metadata with response headers, retry metadata, and request metadata.
+- Added `onRateLimit` hook.
+- Added stable cache-key utility with volatile-header exclusion.
+- Added cache-key body hashing and path-based key composition.
+- Added configurable cache-key header whitelist (`cacheKeyHeaders`).
+- Exported `encodeTag` from public API with configurable uppercasing.
+- Added integration tests with mocked HTTP API scenarios (200/404/429).
+- Added `verify:api` fixture-based test and support for `--doc`/positional path.
+- Added JSON report output for `verify-api` in `reports/verify-api.json`.
+- Added repository secret scan script for CI (`scripts/scan-secrets.sh`).
+- Updated CI to run integration tests.
+- Updated README with new configuration and error-handling guidance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# Brawl Stars TypeScript SDK
+
+Production-ready TypeScript wrapper for the official Brawl Stars API.
+
+## Install
+
+```bash
+npm install @dontbepooronbrawlstarsbrawlstars-sdk
+```
+
+## Quickstart
+
+```bash
+export BRAWLSTARS_API_TOKEN="your-token"
+```
+
+```ts
+import { BrawlStarsClient } from "@dontbepooronbrawlstarsbrawlstars-sdk";
+const client = new BrawlStarsClient({ token: process.env.BRAWLSTARS_API_TOKEN! });
+const player = await client.players.get("#2ABC");
+```
+
+## Core Usage
+
+```ts
+import { BrawlStarsClient } from "@dontbepooronbrawlstarsbrawlstars-sdk";
+
+const client = new BrawlStarsClient({ token: process.env.BRAWLSTARS_API_TOKEN! });
+
+const player = await client.players.get("#2ABC");
+const club = await client.clubs.get("#2XYZ");
+const brawlers = await client.brawlers.list({ limit: 25 });
+```
+
+## Tag Utility
+
+`encodeTag` is exported for direct use:
+
+```ts
+import { encodeTag } from "@dontbepooronbrawlstarsbrawlstars-sdk";
+
+encodeTag(" 2ab c "); // %232ABC
+encodeTag(" 2AbC ", { uppercase: false }); // %232AbC
+```
+
+Behavior:
+- removes whitespace
+- prefixes `#` if missing
+- uppercases by default
+- applies `encodeURIComponent`
+
+## Configuration
+
+```ts
+new BrawlStarsClient({
+  token: string,
+  baseUrl?: string,
+  timeoutMs?: number,
+  retries?: number | Partial<RetryOptions>,
+  concurrencyLimit?: number,
+  cache?: boolean | CacheOptions,
+  cacheKeyHeaders?: readonly string[],
+  validation?: "off" | "warn" | "strict",
+  logger?: { warn: (...args: unknown[]) => void; error?: (...args: unknown[]) => void; info?: (...args: unknown[]) => void },
+  hooks?: ClientHooks,
+  observability?: ObservabilityOptions,
+  fetch?: typeof fetch,
+});
+```
+
+### Validation Modes
+
+- `off`: no runtime validation (fastest)
+- `warn` (default): validates responses; on mismatch calls `logger.warn` and returns raw payload
+- `strict`: validates responses and throws `ResponseValidationError` on mismatch
+
+Detailed semantics are documented in [docs/VALIDATION.md](./docs/VALIDATION.md).
+
+Per-request overrides:
+
+```ts
+await client.players.get("#2ABC", {
+  timeoutMs: 8_000,
+  cache: false,
+  validation: "strict",
+});
+```
+
+## Errors, Rate Limit, and Retries
+
+All request failures throw typed errors (`ApiError`, `RateLimitError`, `TimeoutError`, `NetworkError`, `ResponseValidationError`).
+
+Error metadata includes:
+- `statusCode`
+- `headers`
+- `body`
+- `retryAfter` (seconds, when calculable)
+- `request` (`method`, `url`, request options)
+
+Example:
+
+```ts
+import { RateLimitError } from "@dontbepooronbrawlstarsbrawlstars-sdk";
+
+try {
+  await client.players.get("#2ABC");
+} catch (error) {
+  if (error instanceof RateLimitError && error.retryAfter) {
+    console.error(`Retry after ${error.retryAfter}s`);
+  }
+}
+```
+
+Retries use exponential backoff + jitter and respect `Retry-After` when present.
+
+## Hooks
+
+```ts
+const client = new BrawlStarsClient({
+  token,
+  hooks: {
+    onRateLimit: (ctx) => {
+      // ctx.retryAfter is in seconds
+      console.warn("Rate-limited", ctx.retryAfter);
+    },
+    onError: (ctx) => {
+      console.error(ctx.error.name, ctx.error.statusCode);
+    },
+  },
+});
+```
+
+## Cache
+
+- caches successful `GET` responses only
+- never caches error responses
+- cache key format: `method|path|sortedQuery|bodyHash|whitelistedHeaders`
+- default cache-key header whitelist: `accept-language`
+- volatile headers (e.g. `authorization`, `x-request-id`, `date`, `traceparent`, `user-agent`) do not affect key
+- whitelist is configurable via `cacheKeyHeaders`
+
+```ts
+client.invalidateCache("players.get");
+client.clearCache();
+```
+
+## Scripts
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run test:integration
+npm run test:coverage
+npm run verify:api
+npm run verify:api -- "./api-spec.txt"
+npm run verify:api:report
+npm run build
+npm run pack:check
+npm run scan:secrets
+npm run prepublish:verify
+```
+
+`verify:api` compares key TypeScript models against the provided API reference file (`api-spec.txt`) and prints JSON:
+
+```json
+{"missingInTs":[],"extraInTs":[]}
+```
+
+`verify:api:report` writes proof output to `reports/verify-apibrawlstars-sdkon`.
+
+You can provide a custom document path:
+
+```bash
+npm run verify:api -- --doc ./api-spec.txt
+# or positional:
+npm run verify:api -- ./api-spec.txt
+```
+
+## CI
+
+GitHub Actions runs:
+- lint
+- typecheck
+- verify-api
+- unit tests
+- integration tests (mocked)
+- pack check
+
+`tests/integration.live.test.ts` is optional and only runs when `BRAWLSTARS_TOKEN` is set.
+
+## Contributing
+
+1. Run `npm install`
+2. Run `npm run validate`
+3. Open PR with tests and documentation updates
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md).
+
+## Security
+
+See [docs/SECURITY.md](./docs/SECURITY.md).
+
+## API Verification
+
+See [docs/VERIFY_API_RUN.md](./docs/VERIFY_API_RUN.md).
+
+## Audit
+
+See [docs/AUDIT.md](./docs/AUDIT.md).