@lgriffin/esi.ts 9.7.0 → 10.2.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://badge.fury.io/js/%40lgriffin%2Fesi.ts.svg)](https://badge.fury.io/js/%40lgriffin%2Fesi.ts)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![TypeScript](https://img.shields.io/badge/TypeScript-6.0%2B-blue)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4%2B-blue)](https://www.typescriptlang.org/)
 [![CI/CD Pipeline](https://github.com/lgriffin/ESI.ts/actions/workflows/ci.yml/badge.svg)](https://github.com/lgriffin/ESI.ts/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-90%25%2B-brightgreen)](https://github.com/lgriffin/ESI.ts)
+[![Coverage](https://img.shields.io/badge/coverage-95%25%2B-brightgreen)](https://github.com/lgriffin/ESI.ts)
 [![npm downloads](https://img.shields.io/npm/dm/%40lgriffin/esi.ts)](https://www.npmjs.com/package/@lgriffin/esi.ts)
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/lgriffin/ESI.ts/badge)](https://scorecard.dev/viewer/?uri=github.com/lgriffin/ESI.ts)
 
@@ -41,7 +41,7 @@ Tools like `openapi-typescript` or `openapi-generator` can produce a typed clien
 | **Batch operations**            | None.                                                                                                               | `batch()` with bounded concurrency for GET fan-out, `batchPost()` with auto-chunking for large POST payloads.                                                                                                                     |
 | **Domain knowledge**            | None — generic HTTP client.                                                                                         | 39 domain clients with typed methods, JSDoc documentation, and input validation (e.g., fleet wing/squad names are capped at 10 characters before hitting the API).                                                                |
 | **Streaming pagination**        | None.                                                                                                               | 21 domain clients with 73+ `stream*` methods via `AsyncGenerator` — process large datasets page-by-page without loading everything into memory.                                                                                   |
-| **Testing**                     | Whatever you write.                                                                                                 | 167 test suites, 4,730 tests across 9 tiers including property-based fuzzing (fast-check), mutation testing (Stryker), deep contract tests against live OpenAPI spec, and consumer type tests (tsd). 52 runnable example scripts. |
+| **Testing**                     | Whatever you write.                                                                                                 | 171 test suites, 4,957 tests across 9 tiers including property-based fuzzing (fast-check), mutation testing (Stryker), deep contract tests against live OpenAPI spec, and consumer type tests (tsd). 52 runnable example scripts. |
 
 ### The real problem with generated clients
 
@@ -60,6 +60,8 @@ A generated client faithfully reproduces these spec bugs. ESI.ts fixes them.
 npm install @lgriffin/esi.ts
 ```
 
+Requires Node.js 18 or later. TypeScript projects need TypeScript 5.4 or later, with ES module or CommonJS code under `node16`, `nodenext` or `bundler` module resolution; the consumer contract checks each of those against the published tarball.
+
 ### Building from Source
 
 ```bash
@@ -78,7 +80,7 @@ Verify everything works:
 
 ```bash
 npm run example:status   # quick smoke test — checks ESI is reachable
-npm test                 # run the full test suite (167 suites, 4,730 tests)
+npm test                 # run the full test suite (171 suites, 4,957 tests)
 ```
 
 ## Sub-path Exports
@@ -90,7 +92,7 @@ ESI.ts provides sub-path exports for targeted imports, reducing bundle size when
 import { MarketOrderSchema } from '@lgriffin/esi.ts/schemas';
 
 // Error classes and type guards
-import { EsiError, isCircuitOpen } from '@lgriffin/esi.ts/errors';
+import { EsiError, isRetryable } from '@lgriffin/esi.ts/errors';
 
 // Test utilities
 import { TestDataFactory } from '@lgriffin/esi.ts/testing';
@@ -100,6 +102,15 @@ import { TestDataFactory } from '@lgriffin/esi.ts/testing';
 
 ESI.ts includes a standalone module for querying CCP's EVE Online Static Data Export — 102 YAML files loaded into in-memory Maps with 109 typed interfaces, Zod validation, and ~97 query methods. No database, no external services.
 
+Reading SDE files needs two optional peer dependencies, which `npm install @lgriffin/esi.ts` does not install:
+
+```bash
+npm install js-yaml    # SdeDataProvider.fromDirectory and fromZip (parses the YAML)
+npm install adm-zip    # SdeDataProvider.fromZip (reads the ZIP archive)
+```
+
+`@lgriffin/esi.ts/sde` loads without them, and `MemorySdeProvider` never needs them. A method that needs one that is missing throws an `SdeError` naming the package and the install command.
+
 ```typescript
 import { SdeDataProvider } from '@lgriffin/esi.ts/sde';
 
@@ -147,6 +158,28 @@ const wallet = await authedClient.wallet.getCharacterWallet(characterId);
 await client.shutdown();
 ```
 
+## Guides
+
+The README orients; the guides are canonical. Each one opens with the [engineering charter](guides/CHARTER.md) requirements it implements.
+
+| Guide                                              | Covers                                                                              |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [Architecture](guides/ARCHITECTURE.md)             | Layers, request path, caching, retry, rate limiting, circuit breaker, interceptors  |
+| [Design rules](guides/DESIGN-RULES.md)             | Naming and schema conventions, adding an endpoint, adding a client, generated files |
+| [Errors](guides/ERRORS.md)                         | Error classes, type guards, retryability, token refresh, safe mode                  |
+| [Logging](guides/LOGGING.md)                       | `ILogger`, per-client loggers, pino, `ESI_LOG_LEVEL`, silencing in tests            |
+| [Pagination](guides/PAGINATION.md)                 | Offset and cursor pagination, `stream*`, `fetchAll*`, batch helpers                 |
+| [Runtime validation](guides/RUNTIME-VALIDATION.md) | Zod response and request validation                                                 |
+| [Security](guides/SECURITY.md)                     | Runtime defences and supply-chain controls ([policy](SECURITY.md))                  |
+| [Testing](guides/TESTING.md)                       | Test tiers, coverage, EARS specification                                            |
+| [Mutation testing](guides/MUTATION-TESTING.md)     | Stryker configuration and scores                                                    |
+| [Quality gates](guides/QUALITY-GATES.md)           | What runs at commit, push, PR, nightly and release; every workflow and script       |
+| [Release](guides/RELEASE.md)                       | Cutting a release, changelog, provenance, signatures, supported versions            |
+| [Semantic versioning](guides/SEMVER.md)            | What is public, major/minor/patch decisions, breaking-change commits, merge buttons |
+| [OKF bundle](guides/OKF.md)                        | The generated Open Knowledge Format catalogue of ESI                                |
+| [Documentation](guides/DOCUMENTATION.md)           | Documentation surfaces and the TypeDoc reference                                    |
+| [Beads](guides/BEADS.md)                           | Issue tracking workflow                                                             |
+
 ## Configuration
 
 ```typescript
@@ -172,9 +205,10 @@ const client = new EsiClient({
   validateResponse: true, // Runtime Zod validation of ESI responses (default: true)
   validateRequest: false, // Opt-in request body Zod validation for POST/PUT/DELETE (default: false)
   retryStrategy: customRetryStrategy, // Injectable IRetryStrategy (default: built-in exponential backoff)
+  enableCircuitBreaker: false, // Opt-in circuit breaker (default: false); circuitBreakerConfig is ignored unless true
   circuitBreakerConfig: {
     keyStrategy: 'resolved', // CB keying: 'resolved' (per-URL) or 'template' (per-route) (default: 'resolved')
-    cleanupIntervalMs: 300000, // Automatic stale circuit cleanup interval (default: 5 min)
+    cleanupIntervalMs: 3600000, // Stale circuit cleanup interval (default: disabled)
   },
 });
 ```
@@ -278,6 +312,107 @@ Key behaviors:
 - If the refresh callback throws (e.g., refresh token revoked), a `TOKEN_REFRESH_FAILED` error is raised
 - Without a token provider, 401 errors throw immediately as before
 
+### Token Manager (multi-character, persistent)
+
+The refresh callback above is the low-level hook. For applications that hold tokens for one or many characters, `EsiTokenManager` does the whole lifecycle: the SSO code exchange, persistence through a pluggable storage adapter, proactive refresh ahead of expiry, coalescing of concurrent refreshes, persistence of the rotated refresh token, revocation tracking, and bulk refresh with a concurrency cap.
+
+```typescript
+import {
+  EsiTokenManager,
+  FileTokenStorage,
+  generateState,
+} from '@lgriffin/esi.ts';
+
+const tokens = new EsiTokenManager({
+  clientId: process.env.ESI_SSO_CLIENT_ID!,
+  clientSecret: process.env.ESI_SSO_CLIENT_SECRET, // omit for a public (PKCE) client
+  callbackUrl: 'https://my-app.example/callback',
+  storage: new FileTokenStorage('./tokens.json'), // or MemoryTokenStorage, or your own
+});
+
+// 1. Send the player to SSO
+const state = generateState();
+const loginUrl = tokens.getAuthorizationUrl({
+  scopes: ['esi-wallet.read_character_wallet.v1'],
+  state,
+});
+
+// 2. On the callback, exchange the code. The character id, name and scopes
+//    are decoded from the token; you never have to say who just logged in.
+const stored = await tokens.addCharacter(codeFromCallback);
+console.log(`Added ${stored.characterName} (${stored.characterId})`);
+
+// 3. Get a client bound to that character. Its token is refreshed before
+//    expiry, and again on a 401, through the manager.
+const client = await tokens.createClient(stored.characterId);
+const wallet = await client.wallet.getCharacterWallet(stored.characterId);
+
+// Or just the access token, for use elsewhere
+const accessToken = await tokens.getToken(stored.characterId);
+```
+
+Public clients (desktop and CLI tools that cannot keep a secret) use PKCE:
+
+```typescript
+import { generatePkcePair } from '@lgriffin/esi.ts';
+
+const pkce = generatePkcePair();
+const loginUrl = tokens.getAuthorizationUrl({
+  scopes,
+  state,
+  codeChallenge: pkce.codeChallenge,
+});
+// ...later, on the callback:
+await tokens.addCharacter(code, { codeVerifier: pkce.codeVerifier });
+```
+
+#### Bulk refresh
+
+Applications holding many characters (corporation tools, alliance services) refresh in bulk. Per-character failures never reject the call; each character gets its own result. The one exception is a storage adapter that cannot list tokens, which rejects with the storage error.
+
+```typescript
+const results = await tokens.refreshAll({
+  concurrency: 5, // simultaneous SSO requests (default 5)
+  expiringWithinMs: 5 * 60_000, // only tokens expiring in the next 5 minutes; omit for all
+});
+
+for (const r of results) {
+  switch (r.status) {
+    case 'refreshed':
+      break;
+    case 'skipped':
+      break; // not stale, or the run was aborted
+    case 'revoked':
+      console.log(`${r.characterId} must log in again`);
+      break;
+    case 'failed':
+      if (r.retryable) scheduleRetry(r.characterId);
+      break;
+  }
+}
+```
+
+#### Storage adapters
+
+`ITokenStorage` is four async methods keyed by character id: `get`, `set`, `delete`, `list`. Two adapters ship with the library:
+
+| Adapter              | Use for                                                                |
+| -------------------- | ---------------------------------------------------------------------- |
+| `MemoryTokenStorage` | Tests, CLIs that log in every run, a cache in front of a durable store |
+| `FileTokenStorage`   | Single-process apps; atomic temp-file-and-rename writes, `0600` mode   |
+
+Implement the interface over Redis, Postgres, or a keychain for anything else. One rule matters: `set` must be durable before it resolves, because the manager persists the rotated refresh token before returning the new access token, and SSO invalidates the previous one.
+
+Key behaviors:
+
+- **One token per character** — re-authorizing replaces the stored token rather than accumulating a second one; a warning is logged if the new consent drops scopes
+- **Proactive refresh** — `getToken` refreshes when the token is inside `refreshSkewMs` of expiry (default 60 s), so requests are never sent with a token about to fail
+- **Coalescing** — concurrent refreshes for the same character share one SSO call, which matters because SSO rotates the refresh token on every use
+- **Revocation tracking** — an `invalid_grant` from SSO marks the character revoked; later calls throw `TokenRevokedError` locally instead of hitting SSO again
+- **Hooks** — `onRefresh`, `onRefreshError`, and `onRevoked` for logging, metrics, or prompting a re-login
+- **No JWT signature verification** — tokens are trusted because they arrive directly from SSO over TLS; do not use `decodeAccessToken` to authenticate tokens presented by third parties
+- **Single process per store** — two processes sharing one `FileTokenStorage` would each rotate refresh tokens the other cannot see
+
 ### Environment variables reference
 
 | Variable           | Description                                  | Default                   |
@@ -382,47 +517,15 @@ See [guides/RUNTIME-VALIDATION.md](guides/RUNTIME-VALIDATION.md) for the full gu
 
 ## Caching
 
-ETag caching is enabled by default. The client automatically:
-
-1. Stores ETag and response data on GET requests
-2. Sends `If-None-Match` on subsequent requests
-3. Returns cached data on `304 Not Modified`
-4. Parses `Cache-Control: max-age` from ESI for per-endpoint TTL
-5. Serves stale cached data when ESI returns 5xx errors
-6. Invalidates related GET caches when POST/PUT/DELETE requests are made
+ETag caching is on by default and works in three tiers: a GET inside the spec-defined TTL is answered from cache with no HTTP call, an older entry is revalidated with `If-None-Match`, and a 5xx with a cached copy serves the stale body instead of throwing. Authenticated cache entries are isolated per token.
 
 ```typescript
-// Cache stats
-const stats = client.getCacheStats();
-console.log(`${stats.totalEntries}/${stats.maxEntries} entries cached`);
-
-// Manual cache operations
+const client = new EsiClient({ etagCacheConfig: { maxEntries: 2000 } });
+client.getCacheStats();
 client.clearCache();
-client.updateCacheConfig({ maxEntries: 2000 });
-
-// Disable caching entirely
-const uncachedClient = new EsiClient({ enableETagCache: false });
 ```
 
-### Spec-Aware Cache TTLs
-
-The library reads `x-cache-age` from the ESI OpenAPI spec (126 of 195 endpoints). Within the TTL window, repeated GET requests return cached data with **zero HTTP calls** — not even a conditional GET.
-
-This layers on top of ETag caching in three tiers:
-
-1. **Spec TTL** — data can't have changed yet, return cached data immediately
-2. **ETag conditional GET** — data might have changed, send `If-None-Match` to check
-3. **Full request** — no cache entry, fetch fresh data
-
-```typescript
-const client = new EsiClient();
-
-// First call — fetches from ESI
-const alliances = await client.alliance.getAlliances();
-
-// Second call within the next 3600s — returns cached data, zero HTTP calls
-const same = await client.alliance.getAlliances();
-```
+See [Caching in the architecture guide](guides/ARCHITECTURE.md#4-caching) for TTL precedence, invalidation, keys and configuration.
 
 ## Batch Requests
 
@@ -433,7 +536,7 @@ import { EsiClient } from '@lgriffin/esi.ts';
 
 const client = new EsiClient();
 
-// Fetch 500 type details with at most 10 concurrent requests
+// Fetch 500 type details with at most 10 concurrent requests (default 20)
 const result = await client.batch(
   typeIds,
   (id) => client.universe.getTypeById(id),
@@ -448,129 +551,36 @@ const result = await client.batch(
 console.log(`${result.results.size} succeeded, ${result.errors.size} failed`);
 ```
 
-For POST endpoints that accept arrays (e.g., `postUniverseNames` with a 1000-ID limit), `batchPost` auto-chunks and concatenates:
+For POST endpoints that accept arrays (e.g., `postNamesAndCategories` with a 1000-ID limit), `batchPost` auto-chunks and concatenates:
 
 ```typescript
 const allNames = await client.batchPost(
   largeIdArray,
-  (chunk) => client.universe.postUniverseNames(chunk),
+  (chunk) => client.universe.postNamesAndCategories(chunk),
   1000, // chunk size
 );
 ```
 
 ## Streaming Pagination
 
-For large paginated endpoints (market orders, contracts, assets), streaming yields one page at a time via `AsyncGenerator` instead of eagerly fetching all pages into memory:
+Paginated endpoints can be consumed three ways: the plain method fetches every page and returns one array, `stream*` methods yield one validated page at a time, and `fetchAll*` methods fetch the remaining pages concurrently.
 
 ```typescript
-import { EsiClient } from '@lgriffin/esi.ts';
-
-const client = new EsiClient();
-
-// Stream all market orders in The Forge, page by page
 for await (const page of client.market.streamMarketOrders(10000002)) {
   console.log(
     `Page ${page.page}/${page.totalPages}: ${page.data.length} orders`,
   );
-
-  // Process each order as it arrives
-  for (const order of page.data) {
-    if (order.is_buy_order && order.price > 1_000_000) {
-      console.log(`High-value buy: ${order.type_id} @ ${order.price} ISK`);
-    }
-  }
-
-  // Early termination — stops fetching remaining pages
-  if (page.page >= 3) break;
+  if (page.page >= 3) break; // stops fetching the remaining pages
 }
 ```
 
-21 domain clients expose 73+ streaming methods. `BaseEsiClient.streamEndpoint()` is also public as an escape hatch for any paginated endpoint not yet wrapped with a convenience method.
-
-Available streaming methods (representative selection):
-
-- **MarketClient** — `streamMarketOrders`, `streamMarketTypes`, `streamCharacterOrderHistory`, `streamCorporationOrders`, `streamCorporationOrderHistory`, `streamMarketOrdersInStructure`
-- **CorporationsClient** — `streamCorporationMembers`, `streamCorporationStructures`, `streamCorporationBlueprints`, + 14 more
-- **CharacterClient** — `streamCharacterBlueprints`, `streamCharacterNotifications`, `streamCharacterStandings`, + 5 more
-- **ContractsClient** — `streamPublicContracts`, `streamCharacterContracts`, `streamCorporationContracts`
-- **WalletClient** — `streamCharacterWalletJournal`, `streamCorporationWalletJournal`, `streamCharacterWalletTransactions`
-- **IndustryClient** — `streamCorporationIndustryJobs`, `streamCorporationMiningObservers`, + 6 more
-- **ContactsClient** — `streamAllianceContacts`, `streamCharacterContacts`, `streamCorporationContacts`, + 3 more
-- **AssetsClient** — `streamCharacterAssets`, `streamCorporationAssets`
-- **KillmailsClient** — `streamCharacterRecentKillmails`, `streamCorporationRecentKillmails`
-- **MailClient** — `streamCharacterMail`, `streamCharacterMailLabels`
-- **FleetsClient** — `streamFleetMembers`, `streamFleetWings`
-- **CalendarClient** — `streamCalendarEvents`
-- **FittingsClient** — `streamCharacterFittings`
-- **SkillsClient** — `streamCharacterSkillQueue`
-- **LoyaltyClient** — `streamCorporationLoyaltyStoreOffers`
-- **BookmarksClient** — `streamCharacterBookmarks`, `streamCorporationBookmarks`
-- **ClonesClient** — `streamCharacterImplants`
-- **PIClient** — `streamCharacterPlanets`
-- **WarsClient** — `streamWars`
-- **FactionWarfareClient** — `streamFactionWarfareStats`
-- **AllianceClient** — `streamAllianceCorporations`
-
-Try it: `npm run example:streaming`
+Try it: `npm run example:streaming`. See [guides/PAGINATION.md](guides/PAGINATION.md) for the full method list, concurrency defaults and failure behaviour.
 
 ## Cursor-based Pagination
 
-Newer ESI routes (Freelance Jobs, and future routes) use cursor-based pagination with opaque `before`/`after` tokens in the response body. See the [ESI blog post](https://developers.eveonline.com/blog/changing-pagination-turning-a-new-page) for background.
-
-```typescript
-import { EsiClient, fetchAllCursorPages } from '@lgriffin/esi.ts';
-
-const client = new EsiClient();
-
-// Fetch first page — returns { cursor: { before, after }, freelance_jobs: [...] }
-const page = await client.freelanceJobs.getFreelanceJobs();
-console.log(page.freelance_jobs); // job records
-console.log(page.cursor.after); // opaque token for next page
+Newer ESI routes such as Freelance Jobs page with opaque `before` / `after` cursor tokens instead of page numbers. `fetchAllCursorPages` follows them to the end of the dataset, and a saved `after` token can be polled later for changed records.
 
-// Fetch next page using the cursor
-const nextPage = await client.freelanceJobs.getFreelanceJobs(
-  undefined,
-  page.cursor.after,
-);
-
-// Auto-fetch all pages in one call
-const allJobs = await fetchAllCursorPages(
-  (before, after) => client.freelanceJobs.getFreelanceJobs(before, after),
-  (response) => response.freelance_jobs,
-  (response) => response.cursor,
-);
-
-// Authenticated endpoints — character/corporation freelance jobs
-const authedClient = new EsiClient({ accessToken: 'your-token' });
-const myJobs =
-  await authedClient.freelanceJobs.getCharacterFreelanceJobs(characterId);
-const corpJobs =
-  await authedClient.freelanceJobs.getCorporationFreelanceJobs(corporationId);
-```
-
-**Polling for changes** — cursor tokens persist across sessions, so you can save the last `after` token and poll later to get only records that changed:
-
-```typescript
-// After initial scan, save the final cursor
-let savedCursor = lastPage.cursor.after;
-
-// Later: check for updates (hours, days, or weeks later)
-const updates = await client.freelanceJobs.getFreelanceJobs(
-  undefined,
-  savedCursor,
-);
-if (updates.freelance_jobs.length > 0) {
-  // Process changed records — duplicates are expected for modified records
-  savedCursor = updates.cursor.after;
-}
-```
-
-Key points:
-
-- Cursor tokens are **opaque strings** — never parse or validate them
-- An **empty result array** signals the end of the dataset (not a short page)
-- **Duplicates across pages** are expected when records are modified between requests
-- Existing offset-based routes (`getMarketOrders`, etc.) are unchanged
+See [guides/PAGINATION.md](guides/PAGINATION.md) for cursor semantics and examples.
 
 ## Generated Types
 
@@ -587,7 +597,12 @@ const order: EsiSpec.MarketsRegionIdOrdersGet = {
   volume_remain: 1000,
   volume_total: 5000,
   is_buy_order: false,
-  // ...
+  duration: 90,
+  issued: '2026-09-01T12:00:00Z',
+  location_id: 60003760,
+  system_id: 30000142,
+  min_volume: 1,
+  range: 'region',
 };
 ```
 
@@ -619,43 +634,20 @@ const scope: EsiScope = 'esi-assets.read_assets.v1';
 
 ## Error Handling
 
-API errors throw `EsiError` with `statusCode`, `message`, and `url` properties:
+Failed calls throw `EsiError` (with `statusCode`, a sanitised `url` and `retryable`) or one of its subclasses, `TimeoutError` and `EsiValidationError`. An open circuit throws `CircuitOpenError`. Type guards such as `isRetryable`, `isTimeout`, `isValidationError` and `isCircuitOpen` narrow them, and `withSafeMode()` returns a result envelope instead of throwing.
 
 ```typescript
-import {
-  EsiError,
-  TimeoutError,
-  EsiValidationError,
-  isTimeout,
-  isRetryable,
-  isValidationError,
-  isCircuitOpen,
-} from '@lgriffin/esi.ts';
+import { EsiError, isCircuitOpen } from '@lgriffin/esi.ts';
 
 try {
-  const alliance = await client.alliance.getAllianceById(99999999);
-  console.log('Alliance:', alliance.name);
+  await client.alliance.getAllianceById(99999999);
 } catch (err) {
-  if (isCircuitOpen(err)) {
-    console.log('Circuit breaker is open — endpoint temporarily unavailable');
-  } else if (isValidationError(err)) {
-    console.log('Response validation failed:', err.validationError);
-  } else if (isTimeout(err)) {
-    console.log(`Request timed out after ${err.timeoutMs}ms`);
-  } else if (err instanceof EsiError) {
-    console.log(`ESI error ${err.statusCode}: ${err.message}`);
-    console.log(`Retryable: ${err.retryable}`);
-  }
+  if (isCircuitOpen(err)) console.log(`Retry in ${err.retryAfterMs} ms`);
+  else if (err instanceof EsiError) console.log(err.statusCode, err.retryable);
 }
 ```
 
-- **204 No Content** — returns `undefined` (valid for DELETE/POST actions)
-- **304 Not Modified** — handled internally, returns cached data
-- **4xx/5xx** — throws `EsiError`
-- **5xx with cache** — returns stale cached data instead of throwing
-- **Timeout** — throws `TimeoutError` (extends `EsiError` with `statusCode: 0` and `timeoutMs`)
-- **Retryable errors** — `EsiError.retryable` returns `true` for 502, 503, 504, 420, 429, and timeouts
-- **Validation errors** — throws `EsiValidationError` (extends `EsiError`) when response data doesn't match the expected Zod schema
+See [guides/ERRORS.md](guides/ERRORS.md) for the class hierarchy, retryability rules and safe mode.
 
 ## Response Metadata
 
@@ -688,42 +680,17 @@ The `meta` object includes:
 
 ## Rate Limiting
 
-ESI.ts automatically manages rate limiting using ESI's per-group token bucket system. The 36 rate limit groups from the ESI OpenAPI spec are extracted at build time, so each group (e.g., `market-order`, `char-notification`) gets its own independent bucket. A burst of market requests won't starve unrelated endpoints.
-
-Rate limiting works out of the box with no configuration. For multi-character applications, enable per-user bucketing:
+Rate limiting is always on and needs no configuration. Each ESI rate-limit group from the OpenAPI spec gets its own bucket, the limiter learns remaining tokens from ESI's response headers, and a 420 or 429 blocks only the affected group. Multi-character applications can give each token its own buckets:
 
 ```typescript
-import { EsiClient } from '@lgriffin/esi.ts';
-
 const client = new EsiClient({
   rateLimiterConfig: {
-    userKeyExtractor: (headers) => headers['authorization'] ?? 'anon',
+    userKeyExtractor: (headers) => headers['Authorization'] ?? 'anon',
   },
 });
 ```
 
-Monitor rate limit status per group:
-
-```typescript
-const limiter = client.getRateLimiter();
-
-// Worst-case across all groups (backward-compatible)
-const status = limiter.getStatus();
-console.log(status.remaining, status.limit, status.group);
-
-// Specific group
-const marketStatus = limiter.getGroupStatus('market-order');
-console.log(marketStatus?.remaining); // tokens remaining in this group
-
-// All active groups
-const all = limiter.getAllGroupStatuses();
-for (const [group, info] of all) {
-  console.log(`${group}: ${info.remaining}/${info.limit}`);
-}
-
-// Check if a specific group is blocked
-console.log(limiter.isBlocked('char-notification')); // true if 429'd
-```
+See [Rate limiting in the architecture guide](guides/ARCHITECTURE.md#6-rate-limiting) for the throttling rules, per-endpoint overrides and monitoring. Retry, deduplication, the opt-in [circuit breaker](guides/ARCHITECTURE.md#7-circuit-breaker) and [request/response interceptors](guides/ARCHITECTURE.md#8-interceptors) are documented alongside it.
 
 ## Lightweight Clients
 
@@ -864,7 +831,9 @@ console.log(`Best sell: ${Math.min(...sellOrders.map((o) => o.price))}`);
 
 Always call `shutdown()` when you're done to clean up cache timers:
 
-```typescript
+```typescript runnable
+import { EsiClient } from '@lgriffin/esi.ts';
+
 const client = new EsiClient();
 try {
   const status = await client.status.getStatus();
@@ -876,11 +845,11 @@ try {
 
 ## Testing
 
-ESI.ts has a comprehensive multi-tier testing strategy with 139 suites and 4,104 tests:
+ESI.ts has a comprehensive multi-tier testing strategy with 171 suites and 4,957 tests:
 
 | Tier                       | Tests            | Purpose                                                            |
 | -------------------------- | ---------------- | ------------------------------------------------------------------ |
-| **TDD unit tests**         | 100 files        | Every client method, endpoint path, query param, and body format   |
+| **TDD unit tests**         | 130 files        | Every client method, endpoint path, query param, and body format   |
 | **BDD scenario tests**     | 41 feature files | Behavioral specifications in Gherkin (Given/When/Then)             |
 | **Mocked integration**     | Full suite       | Cross-layer request flow with jest-fetch-mock                      |
 | **Live smoke tests**       | 46 examples      | Every endpoint against live Tranquility                            |
@@ -894,17 +863,17 @@ ESI.ts has a comprehensive multi-tier testing strategy with 139 suites and 4,104
 | **Spec-alignment**         | Type assertions  | Ensures hand-written types align with generated OpenAPI types      |
 
 ```bash
-npm test          # Unit + BDD tests (167 suites, 4,730 tests)
+npm test          # Unit + BDD tests (171 suites, 4,957 tests)
 npm run coverage  # Tests with coverage report (thresholds enforced)
 npm run bdd       # BDD scenario tests only
 npm run contract  # Contract tests (skipped without ESI_LIVE_TESTS=true)
 npm run fuzz      # Property-based fuzz tests (601 tests)
 npm run mutation  # Mutation testing (Stryker)
-npm run benchmark # Performance benchmark tests
+npm run benchmark # Micro-benchmarks (mitata); npm run soak for the heap soak
 npm run test:types # tsd consumer type tests
 ```
 
-Coverage: statements 98.47%, branches 90.10%, functions 97.54%, lines 98.59%. Thresholds enforced in CI: branches 80%, functions 75%, lines 90%, statements 90%.
+Coverage: statements 98.37%, branches 95.14%, functions 96.09%, lines 98.17%. Thresholds enforced in CI: branches 80%, functions 75%, lines 90%, statements 90%.
 
 See [guides/TESTING.md](guides/TESTING.md) for the full testing guide, and [guides/ARCHITECTURE.md](guides/ARCHITECTURE.md) for architecture diagrams.
 
@@ -941,14 +910,14 @@ npm run format             # Format code with Prettier
 npm run format:check       # Check formatting without modifying
 
 # Testing
-npm test                   # Unit tests (167 suites, 4,730 tests)
+npm test                   # Unit tests (171 suites, 4,957 tests)
 npm run test:all           # Unit + BDD + integration + fuzz + type tests
 npm run coverage           # Tests with coverage report (thresholds enforced)
 npm run bdd                # BDD scenario tests
-npm run contract:live      # Deep contract tests against live ESI spec
+ESI_LIVE_TESTS=true npm run contract:live  # Deep contract tests against live ESI spec (fails without the variable)
 npm run fuzz               # Property-based fuzz tests (fast-check)
 npm run mutation           # Mutation testing (Stryker)
-npm run benchmark          # Performance benchmark tests
+npm run benchmark          # Micro-benchmarks (mitata)
 npm run test:types         # Consumer type tests (tsd)
 npm run mock:esi           # Start Prism mock ESI server on port 4010
 
@@ -989,32 +958,9 @@ The project uses husky with lint-staged to run ESLint and Prettier on staged fil
 
 ### CI/CD
 
-Every pull request runs the full validation suite:
-
-- ESLint (with security and sonarjs plugins)
-- Prettier formatting check
-- TypeScript compilation
-- Generated types staleness check (regenerates from live ESI OpenAPI spec and verifies no diff)
-- Unit tests across Node.js 18, 20, and 22
-- BDD scenario tests
-- Coverage threshold enforcement (branches: 80%, functions: 75%, lines: 90%, statements: 90%)
-- Auth/scopes cross-validation
-- Spec-alignment type assertions
-- Schema drift detection
-- Mutation testing (Stryker)
-- Dead code detection via knip
-- npm security audit — diff-aware on PRs (fails only on advisories the PR introduces), state-of-the-world nightly and at release, with a reviewed-acceptance allowlist in `scripts/audit-exceptions.json`
-
-**Supply chain security:**
-
-- All GitHub Actions pinned by SHA hash (not mutable tags) to prevent supply chain attacks
-- Least-privilege `permissions:` on all workflows and jobs
-- Script injection prevention (user-controlled inputs passed via `env:`, never interpolated in `run:`)
-- npm publish with `--provenance` for SLSA attestations (verifiable build origin)
-- GitHub release artifacts signed with Cosign (keyless) and published with SHA256 checksums
-- OpenSSF Scorecard runs weekly via the `scorecard.yml` workflow
-
-See [.github/workflows/README.md](.github/workflows/README.md) for full workflow details.
+Every push runs lint, format, build, typecheck and unit tests; pull requests to `master` run the full matrix behind a single Quality Gate check. Actions are SHA-pinned, packages publish with npm provenance, and release assets are cosign-signed.
+
+See [guides/QUALITY-GATES.md](guides/QUALITY-GATES.md) for the gate matrix and every workflow, and [guides/SECURITY.md](guides/SECURITY.md) for the supply-chain controls.
 
 ## Contributing