@lgriffin/esi.ts 10.0.0 → 10.2.0

package/CHANGELOG.md

@@ -5,6 +5,148 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [10.2.0](https://github.com/lgriffin/ESI.ts/compare/v10.1.1...v10.2.0) (2026-09-19)
+
+
+### Added
+
+* **release:** attach a signed CycloneDX SBOM to each release ([bf6c045](https://github.com/lgriffin/ESI.ts/commit/bf6c0458b81fc9123ca29f712db8a89948e2b382))
+* **release:** attach a signed CycloneDX SBOM to each release ([1e29d7d](https://github.com/lgriffin/ESI.ts/commit/1e29d7de39237ecd250dcac3ef90da54a9c52df3))
+
+
+### Testing
+
+* **contract:** re-record ESI payloads whose shape changed ([2ea4198](https://github.com/lgriffin/ESI.ts/commit/2ea4198d8832d12618e9f9a9da0720ffb9b07f55))
+* **contract:** recorded ESI payloads changed shape ([06fa27a](https://github.com/lgriffin/ESI.ts/commit/06fa27ab0516af9f9d450059cb0cb3fcd6463345))
+
+## [10.1.1](https://github.com/lgriffin/ESI.ts/compare/v10.1.0...v10.1.1) (2026-09-18)
+
+
+### Documentation
+
+* **mutation:** record the first complete sharded run, and fix what it exposed ([7acf195](https://github.com/lgriffin/ESI.ts/commit/7acf1950d5781dad571e2f79e52d03324683f7bd))
+* **mutation:** record the first complete sharded run, and fix what it exposed ([3209241](https://github.com/lgriffin/ESI.ts/commit/32092415c551cbc7cc75266fa7158ab884040aad))
+
+## [10.1.0](https://github.com/lgriffin/ESI.ts/compare/v10.0.0...v10.1.0) (2026-09-18)
+
+
+### Added
+
+* **dedupe:** detach in-flight reads of a path a write has just changed ([0339db7](https://github.com/lgriffin/ESI.ts/commit/0339db70d2cd34827c5575f1d731006fa1500ea0))
+* **dedupe:** detach in-flight reads of a path a write has just changed ([e3a3d91](https://github.com/lgriffin/ESI.ts/commit/e3a3d91d2ef74759245cd43affb2e109040bf221))
+* **release:** verify what npm serves, not only what CI built ([999125c](https://github.com/lgriffin/ESI.ts/commit/999125cd2c167410cdba7f35590afe6b5fa025d8))
+* **release:** verify what npm serves, not only what CI built ([281e008](https://github.com/lgriffin/ESI.ts/commit/281e008d9fd65e45619f73c6abeb7a48dbc70831))
+
+
+### Fixed
+
+* add the composition and concurrency test tier and fix the five pipeline races it found ([c7a7642](https://github.com/lgriffin/ESI.ts/commit/c7a764213ebc34fc47bd8396863b4f8f7938f4a1))
+* **bdd:** escape backslashes in the job summary's table cells ([751d098](https://github.com/lgriffin/ESI.ts/commit/751d098f4d2fa81c86c80e7a8e8221991c81495d))
+* **benchmark:** keep the harness filter a substring and gate the soak heap trend on Node 20 ([d559157](https://github.com/lgriffin/ESI.ts/commit/d5591576dcdb2823a7df8e2692597b7fc92575fe))
+* **cache:** do not store a read that a write overtook while it was in flight ([e2f3141](https://github.com/lgriffin/ESI.ts/commit/e2f3141b2a4713bf4a46c2ea58ad42e02bc40814))
+* **cache:** keep the stored ETag when a late 304 names an older one ([bb63097](https://github.com/lgriffin/ESI.ts/commit/bb6309753938f8868fcb1ea9684d44989933086a))
+* **cache:** refetch when a 304 arrives for an entry evicted in flight ([4ae476e](https://github.com/lgriffin/ESI.ts/commit/4ae476e9462ae1eac33569b9d4c70bb36ad545d3))
+* **ci:** pack the downloaded dist with npm 11 ([7e7ff71](https://github.com/lgriffin/ESI.ts/commit/7e7ff7131a3b383cae3ae65c79f677a28f1369b7))
+* **circuit-breaker:** count the call that opens half-open as the first probe ([b418625](https://github.com/lgriffin/ESI.ts/commit/b418625bbf7ade64217fde9970bd76229dbb8ffd))
+* **circuit-breaker:** keep an open circuit open when an earlier call succeeds ([03b27a5](https://github.com/lgriffin/ESI.ts/commit/03b27a5e1e641ddcf015f5e08f1420966c60b4ce))
+* **ci:** read the attw report from a file so CI gets the whole JSON ([dac266d](https://github.com/lgriffin/ESI.ts/commit/dac266d5ec13b5bb2ba13a0a6f7a94b25da0ba0c))
+* **dedupe:** key in-flight requests by identity as well as endpoint ([5bab05c](https://github.com/lgriffin/ESI.ts/commit/5bab05c85cfb8067baecffd8e740f6c1c27b6629))
+* **dedupe:** key in-flight requests by identity as well as endpoint ([5d662d9](https://github.com/lgriffin/ESI.ts/commit/5d662d9699aab9f9bb34af93a8fb5809a02ccde6))
+* five defects found by new model-based property tests (circuit breaker, pagination cache, backoff) ([80fcafa](https://github.com/lgriffin/ESI.ts/commit/80fcafa5bb99aed93348c30722c090e526b85fb7))
+* **generate:** generate from the compatibility date the client actually sends ([ff781bd](https://github.com/lgriffin/ESI.ts/commit/ff781bd54777b2c3fda5189772e431e4d9de3657))
+* **generate:** generate from the compatibility date the client actually sends ([5ea4a2f](https://github.com/lgriffin/ESI.ts/commit/5ea4a2fe0891bcba5c3d08171bb3d858639ea3f4))
+* **mutation:** escape backslashes in the job summary table cells ([9ab23fa](https://github.com/lgriffin/ESI.ts/commit/9ab23fa685f68288b138dad749aed9bf871c215f))
+* **package:** ship ES module declarations for the import condition ([2090682](https://github.com/lgriffin/ESI.ts/commit/20906829b64a093e8d66e2b6890cf2bbadb012c7))
+* **package:** ship ES module declarations for the import condition ([d53fe91](https://github.com/lgriffin/ESI.ts/commit/d53fe914a156faad1835c1e748cd500254e57b69))
+* **pagination:** cache an authenticated paginated result under the token-scoped key ([23313ff](https://github.com/lgriffin/ESI.ts/commit/23313ff95cf45a043ce2c27ea61d483969701366))
+* **pagination:** never revalidate page 1 alone when a later page exhausts its retries ([8c48085](https://github.com/lgriffin/ESI.ts/commit/8c48085366af3eeb278be8bf033b45e53d353962))
+* **pipeline:** name the status when an error response has no reason phrase ([94827fb](https://github.com/lgriffin/ESI.ts/commit/94827fb5652d8e76b27d509eb3eabb2ae21c6ecc))
+* **pipeline:** time out and retry a response body that stalls or resets ([8e8753f](https://github.com/lgriffin/ESI.ts/commit/8e8753f36c272cbd796f93a92776c8c3d3fd7d0a))
+* **rate-limiter:** honour Retry-After given as an HTTP date ([1fb7cba](https://github.com/lgriffin/ESI.ts/commit/1fb7cba9a6b553f969fa2466f181018102d63bf3))
+* **rate-limit:** keep the error-limit back-off when a late response reports budget left ([1c7279b](https://github.com/lgriffin/ESI.ts/commit/1c7279b9223702e64943e71bef3278488b4762d6))
+* **release:** keep the canary off the shared npm cache ([8604246](https://github.com/lgriffin/ESI.ts/commit/86042464188ec6603f681d5564984275acd40866))
+* **release:** publish the tarball that was tested and signed ([8c7c25f](https://github.com/lgriffin/ESI.ts/commit/8c7c25f77413349eca764f542015e944a55f738f))
+* **release:** publish the tarball that was tested and signed ([c4ac638](https://github.com/lgriffin/ESI.ts/commit/c4ac6389a1844ddddc37fb7d380377e296e90ba1))
+* **retry:** return a zero backoff instead of NaN past attempt 1023 ([ae36c02](https://github.com/lgriffin/ESI.ts/commit/ae36c022ce2c05fc33474110a801bd9121cb2438))
+* **retry:** serve a retry from a fresh cache entry a concurrent call stored ([de5f7ee](https://github.com/lgriffin/ESI.ts/commit/de5f7eee75b89a45bbbe8e909462145ea805fba1))
+* **type-mutation:** resolve entry points whose types sit under a condition ([1dd356d](https://github.com/lgriffin/ESI.ts/commit/1dd356d7874ecad0ff5b81a2f56695f408b0ad93))
+* **type-mutation:** resolve entry points whose types sit under a condition ([330c69e](https://github.com/lgriffin/ESI.ts/commit/330c69e78b7854e6a7a9718fa2ce0fff4257c3ef))
+* **types:** escape backslashes before pipes in the type mutation survivor table ([8d7d4de](https://github.com/lgriffin/ESI.ts/commit/8d7d4de6278cd968070c0c58f3e5e781815ad512))
+
+
+### Changed
+
+* **bdd:** share the feature outline and feature bindings ([f75f261](https://github.com/lgriffin/ESI.ts/commit/f75f261958addd53fb22571ac649de9153b8cdab))
+* **ci:** lint the packed tarball and budget each exports sub-path's size ([63c5f26](https://github.com/lgriffin/ESI.ts/commit/63c5f26d19236d6ab397e5e95b5d3ee3328aead9))
+* **ci:** run the properties nightly at 10000 runs and document the tier ([06c79d2](https://github.com/lgriffin/ESI.ts/commit/06c79d268c85cd654d8f8e48b6b93ceb4d2cfc5d))
+* **ci:** sample four overlapping calls nightly in seeded random order ([510b940](https://github.com/lgriffin/ESI.ts/commit/510b940f2cdf10abdbaaa38097f289143d7bf307))
+* **lint:** lint tests/ for focused, skipped, assertion-free and silenced tests ([9bdf6bf](https://github.com/lgriffin/ESI.ts/commit/9bdf6bf174fe0476a213389ca4103fe90b00898c))
+* **scripts:** check that every npm script points at a file that exists ([7b1fe81](https://github.com/lgriffin/ESI.ts/commit/7b1fe81b2cc52ac958a34490fdcd445eb57b2528))
+* **scripts:** check that every npm script points at a file that exists ([55b03c7](https://github.com/lgriffin/ESI.ts/commit/55b03c77f0b6d636b7ec6ce6837f2bf642cb48c9))
+* **scripts:** run every offline CI tier locally with one command ([14fc738](https://github.com/lgriffin/ESI.ts/commit/14fc738a13e5a8e6c782b032c708e46243b66087))
+* **scripts:** run every offline CI tier locally with one command ([31197ac](https://github.com/lgriffin/ESI.ts/commit/31197accc81750b20a7412421e7b9e3ada57f9c6))
+
+
+### Documentation
+
+* **agents:** pin the semver rules against drift, and fix a retired config reference ([52ad44f](https://github.com/lgriffin/ESI.ts/commit/52ad44fa6e79018d21d0fafac6c98ab42117fe44))
+* **agents:** pin the semver rules against drift, and fix a retired config reference ([d2af258](https://github.com/lgriffin/ESI.ts/commit/d2af258aa7a2d82a12eb56a014432f1d14c1a558))
+* **bdd:** document the execution check, bug tags and when a Rule is protection ([fa0be02](https://github.com/lgriffin/ESI.ts/commit/fa0be0281996fd5e7fadeffcadbece5c81299b59))
+* **contract:** name the real reason those endpoints cannot be recorded ([1b864da](https://github.com/lgriffin/ESI.ts/commit/1b864da3c9688833cf90ac748acb775f135d39b5))
+* **contract:** name the real reason those endpoints cannot be recorded ([b8ea80d](https://github.com/lgriffin/ESI.ts/commit/b8ea80d3861813490fe012fcc1abda57bdce5485))
+* declare TypeScript 5.4 as the oldest supported version ([f9e5f66](https://github.com/lgriffin/ESI.ts/commit/f9e5f66c4a3065ac82d8f0dab809b44d931e2a0a))
+* describe the benchmark and heap soak tier ([f28cc2c](https://github.com/lgriffin/ESI.ts/commit/f28cc2c9d74115ebffce382a27ed362d96e5401a))
+* **mutation:** record the measured pull request job timings ([62c70c9](https://github.com/lgriffin/ESI.ts/commit/62c70c93c7f0904a4804e64a8c7a62d971e79cea))
+* **testing:** describe the composition and concurrency tier ([e1ee338](https://github.com/lgriffin/ESI.ts/commit/e1ee338f738a35c8bcdcfc461304a8d8c560e0c3))
+* **testing:** describe the fault tier and the decisions it pins ([39416c7](https://github.com/lgriffin/ESI.ts/commit/39416c72167ab589dce475912a75832fc2318c1e))
+* **testing:** describe the recorded payload replay tier ([1b190f3](https://github.com/lgriffin/ESI.ts/commit/1b190f31e4c2d10de462905f83681881ecb9ee20))
+* **testing:** map the suite in C4 and refresh the tier counts ([06facdb](https://github.com/lgriffin/ESI.ts/commit/06facdb6994e41bff84eea7ca5fe1fe649066ba6))
+
+
+### Testing
+
+* **bdd:** let the transport seam fail an exchange the way a network does ([8f0a7a9](https://github.com/lgriffin/ESI.ts/commit/8f0a7a9d9eb4dc9c7eeb9a2ffe1d958ca64d7f2f))
+* **bdd:** prove every scenario executes, name JUnit cases by Rule, and link [@bug](https://github.com/bug) to a tracker ([752de4c](https://github.com/lgriffin/ESI.ts/commit/752de4caa193c8fbb6d4f6d79de2a54fc071a46f))
+* **bdd:** report every scenario by Rule and fail when one did not run ([b04a2d7](https://github.com/lgriffin/ESI.ts/commit/b04a2d7818754cd3daa1b504ed17d2fe1af4bd23))
+* **bdd:** state what the performance scenarios verify, not a latency budget ([12b4461](https://github.com/lgriffin/ESI.ts/commit/12b44616b7b2f7e59cac06fc27e1d9eaed797815))
+* **benchmark:** decide regressions statistically, not by percentage ([a3da1f8](https://github.com/lgriffin/ESI.ts/commit/a3da1f875fd2853e4312b41b2a3aaa799f49db9b))
+* **benchmark:** measure the client hot paths with a mitata harness ([307b978](https://github.com/lgriffin/ESI.ts/commit/307b97850e4d5127b1572b6bed9313dcee17b698))
+* **benchmark:** soak the pipeline for 100 000 requests and watch the heap ([34ab5ec](https://github.com/lgriffin/ESI.ts/commit/34ab5eca8c4918ee9f1147e0ff41318078e81d43))
+* **benchmark:** statistical benchmark comparison, heap soak and a smoke-only latency spec ([1c62567](https://github.com/lgriffin/ESI.ts/commit/1c625674c1befaa90bf39438f931e16f15eb4119))
+* **composition:** add a deterministic interleaving scheduler at the transport seam ([9ebbedb](https://github.com/lgriffin/ESI.ts/commit/9ebbedbc0935e3351e3fad55f56984cf9ea0d457))
+* **composition:** escape backslashes in the printed reproduce command ([d96de7b](https://github.com/lgriffin/ESI.ts/commit/d96de7ba999268d0438661d67b407e8df945d86b))
+* **composition:** explore retry inside an opening circuit and stale-on-error during a refresh ([309658d](https://github.com/lgriffin/ESI.ts/commit/309658d9490261e7eef84b5a6de1da12e16e161a))
+* **composition:** explore three overlapping calls on PRs and four nightly ([4122f14](https://github.com/lgriffin/ESI.ts/commit/4122f14693ed1927f957836304999db42078393e))
+* **consumer:** check the tarball as a matrix of consumer cells ([81c0cd0](https://github.com/lgriffin/ESI.ts/commit/81c0cd0cd97f548b35266991aad7c1ec805a233d))
+* **consumer:** stop esbuild once the tree-shaking check has run ([9e9bea3](https://github.com/lgriffin/ESI.ts/commit/9e9bea30affcc0fdd73a015c9cb516f8b3d79144))
+* **consumer:** widen the consumer contract to a Node x TypeScript x resolution matrix ([14880dd](https://github.com/lgriffin/ESI.ts/commit/14880dd5e341ec66f0871d5fadd5092e1e681b52))
+* **contract:** assert replay failures through named helpers the lint knows ([48cd863](https://github.com/lgriffin/ESI.ts/commit/48cd863d5f74d0ea38c42f3bf2b60cdc236bcde9))
+* **contract:** assert replay failures through named helpers the lint knows ([53e4b03](https://github.com/lgriffin/ESI.ts/commit/53e4b032ba437a71841086ec68541ea9fa78f295))
+* **contract:** re-record ESI payloads whose shape changed ([bfe9af5](https://github.com/lgriffin/ESI.ts/commit/bfe9af5bb1ef26b639c5f836446633d7fb76a924))
+* **contract:** re-record ESI payloads whose shape changed ([1f1be53](https://github.com/lgriffin/ESI.ts/commit/1f1be53fdec4f2a42ba260d5113c3e85d4dc0a4c))
+* **contract:** record public ESI payloads and replay them through the client pipeline ([60d897e](https://github.com/lgriffin/ESI.ts/commit/60d897e45f845bb729cda580730412c5bb2d4ecb))
+* **contract:** record sanitised public ESI payloads as fixtures ([d08cae6](https://github.com/lgriffin/ESI.ts/commit/d08cae62d9dc09ca86f773602641f89363044c69))
+* **contract:** recorded ESI payloads changed shape ([184d67f](https://github.com/lgriffin/ESI.ts/commit/184d67f781e32c6be8763eb93ef8a4ffa293c509))
+* **contract:** recorded ESI payloads changed shape ([6d1bbe8](https://github.com/lgriffin/ESI.ts/commit/6d1bbe83f3ecd2239b3abffe5df472b2b02ccdfe))
+* **contract:** replay recorded ESI payloads through the client pipeline ([ee8f0df](https://github.com/lgriffin/ESI.ts/commit/ee8f0dff5dd527ad089d77c5246456f48fa08c9b))
+* **docs:** type-check documentation examples against the packed package ([7746ada](https://github.com/lgriffin/ESI.ts/commit/7746ada98d04b8af72a005cc3645efc205e83cc3))
+* **faults:** add a 400 served while the cache holds an entry ([d85b4fb](https://github.com/lgriffin/ESI.ts/commit/d85b4fba2c2e496337b46f3dce6ff1974870775e))
+* **faults:** add a status the client has no text for, without a reason phrase ([1fe646a](https://github.com/lgriffin/ESI.ts/commit/1fe646a526ece7434966e0211c4a933071aad0b5))
+* **faults:** add a transport fault catalogue run through the real pipeline ([1f5f055](https://github.com/lgriffin/ESI.ts/commit/1f5f055c2721cb7da9e67518d6237425b599e980))
+* **faults:** assert through the helpers the suite-health lint knows ([0064539](https://github.com/lgriffin/ESI.ts/commit/0064539656221bdd30e1b0559da5d9854ee88e5c))
+* **faults:** drop the x-pages gap the pagination fix closed ([6e367d6](https://github.com/lgriffin/ESI.ts/commit/6e367d6f1b6f6e864654384ba656cb00b709efa2))
+* **faults:** drop the x-pages gap the pagination fix closed ([2f89d91](https://github.com/lgriffin/ESI.ts/commit/2f89d919c531c2b06f1eb41539e4c5ed71f4297a))
+* **faults:** fault injection and fuzzing tier (transport fault catalogue) ([e3cee50](https://github.com/lgriffin/ESI.ts/commit/e3cee50f55a9f4c75b3d73569c55b1a608580acf))
+* **faults:** fuzz every endpoint's payloads from its Zod schema nightly ([49dc045](https://github.com/lgriffin/ESI.ts/commit/49dc045d33fb538483e046c1c525d1982c7a0512))
+* **fuzz:** model-based properties with a vacuity check for every property ([d2890ab](https://github.com/lgriffin/ESI.ts/commit/d2890ab5b6e1b9de690b6ba4ac7c08d8e33af253))
+* **fuzz:** require eager pagination repeat calls to come from the cache ([cc57bc8](https://github.com/lgriffin/ESI.ts/commit/cc57bc8507f76af3614ddfc8441b6172fcde73d1))
+* **fuzz:** respell all occurrences in cache-key lookalikes; ratchet export baseline ([1554338](https://github.com/lgriffin/ESI.ts/commit/155433898d56a6f52055f13f4847cf5ca025c56d))
+* **mutation:** gate changed files per directory and prove the gate can fail ([c9a1b44](https://github.com/lgriffin/ESI.ts/commit/c9a1b4436643d529d30049eceaad8fb088a9b029))
+* reference the exports v10 added and drop ContractBid from the export baseline ([dcb2081](https://github.com/lgriffin/ESI.ts/commit/dcb208160d195fef9cbfe226c61c9cc16a9c187d))
+* reference the exports v10 added and drop ContractBid from the export baseline ([2633694](https://github.com/lgriffin/ESI.ts/commit/26336943d3897e1a8af85b82d0f9cc5754f54b75))
+* **spec-audit:** require a tracker tag beside every [@bug](https://github.com/bug) ([04ad7a0](https://github.com/lgriffin/ESI.ts/commit/04ad7a00ed0e1b009c39db799740b2e32bbbcaa0))
+* **types:** mutate the built declarations nightly and ratchet the tsd kill score ([5d0a8a8](https://github.com/lgriffin/ESI.ts/commit/5d0a8a8c3ba32ac383e01de768040ac9d075bd64))
+
 ## [10.0.0](https://github.com/lgriffin/ESI.ts/compare/v9.9.0...v10.0.0) (2026-09-17)
 
 

package/README.md

@@ -2,7 +2,7 @@
 
 [![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-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)
@@ -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
@@ -595,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',
 };
 ```
 
@@ -824,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();
@@ -860,7 +869,7 @@ 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
 ```
 
@@ -908,7 +917,7 @@ npm run bdd                # BDD scenario tests
 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
 

package/dist/EsiClient.d.mts

@@ -0,0 +1,140 @@
+import { TokenProvider } from './core/ApiClient.mjs';
+import { RequestInterceptor, ResponseInterceptor } from './core/middleware/Middleware.mjs';
+import { AllianceClient } from './clients/AllianceClient.mjs';
+import { AssetsClient } from './clients/AssetsClient.mjs';
+import { CalendarClient } from './clients/CalendarClient.mjs';
+import { CharacterClient } from './clients/CharacterClient.mjs';
+import { ClonesClient } from './clients/ClonesClient.mjs';
+import { ContactsClient } from './clients/ContactsClient.mjs';
+import { ContractsClient } from './clients/ContractsClient.mjs';
+import { CorporationsClient } from './clients/CorporationsClient.mjs';
+import { CorporationProjectsClient } from './clients/CorporationProjectsClient.mjs';
+import { DogmaClient } from './clients/DogmaClient.mjs';
+import { FactionClient } from './clients/FactionClient.mjs';
+import { FittingsClient } from './clients/FittingsClient.mjs';
+import { FleetClient } from './clients/FleetClient.mjs';
+import { IncursionsClient } from './clients/IncursionsClient.mjs';
+import { IndustryClient } from './clients/IndustryClient.mjs';
+import { InsuranceClient } from './clients/InsuranceClient.mjs';
+import { KillmailsClient } from './clients/KillmailsClient.mjs';
+import { LocationClient } from './clients/LocationClient.mjs';
+import { LoyaltyClient } from './clients/LoyaltyClient.mjs';
+import { MailClient } from './clients/MailClient.mjs';
+import { MarketClient } from './clients/MarketClient.mjs';
+import { PiClient } from './clients/PiClient.mjs';
+import { RouteClient } from './clients/RouteClient.mjs';
+import { SearchClient } from './clients/SearchClient.mjs';
+import { CharacterSkillsClient } from './clients/SkillsClient.mjs';
+import { SovereigntyClient } from './clients/SovereigntyClient.mjs';
+import { StatusClient } from './clients/StatusClient.mjs';
+import { UiClient } from './clients/UiClient.mjs';
+import { UniverseClient } from './clients/UniverseClient.mjs';
+import { WalletClient } from './clients/WalletClient.mjs';
+import { WarsClient } from './clients/WarsClient.mjs';
+import { MetaClient } from './clients/MetaClient.mjs';
+import { FreelanceJobsClient } from './clients/FreelanceJobsClient.mjs';
+import { CosmeticsClient } from './clients/CosmeticsClient.mjs';
+import { ParagonHubClient } from './clients/ParagonHubClient.mjs';
+import { SkyhooksClient } from './clients/SkyhooksClient.mjs';
+import { MercenaryClient } from './clients/MercenaryClient.mjs';
+import { AccessListsClient } from './clients/AccessListsClient.mjs';
+import { MilitaryCampaignsClient } from './clients/MilitaryCampaignsClient.mjs';
+import { ETagCacheConfig } from './core/cache/ETagCacheManager.mjs';
+import { CircuitBreakerConfig } from './core/circuitBreaker/CircuitBreaker.mjs';
+import { RateLimiterConfig } from './core/rateLimiter/RateLimiter.mjs';
+import { RetryConfig } from './core/util/retry.mjs';
+import { IRetryStrategy } from './core/IRetryStrategy.mjs';
+import { EsiDiagnostics } from './core/EsiDiagnostics.mjs';
+import { BatchOptions, BatchResult } from './core/BatchRequestHandler.mjs';
+export type EsiDatasource = 'tranquility' | 'singularity';
+export interface EsiClientConfig {
+    clientId?: string;
+    baseUrl?: string;
+    accessToken?: string;
+    datasource?: EsiDatasource;
+    onTokenRefresh?: TokenProvider;
+    timeout?: number;
+    retryAttempts?: number;
+    retryConfig?: RetryConfig;
+    retryStrategy?: IRetryStrategy;
+    enableETagCache?: boolean;
+    etagCacheConfig?: ETagCacheConfig;
+    enableCircuitBreaker?: boolean;
+    circuitBreakerConfig?: CircuitBreakerConfig;
+    unsafeAllowCustomHost?: boolean;
+    enableRequestDeduplication?: boolean;
+    language?: string;
+    compatibilityDate?: string;
+    rateLimiterConfig?: RateLimiterConfig;
+    requestInterceptors?: RequestInterceptor[];
+    responseInterceptors?: ResponseInterceptor[];
+    validateResponse?: boolean;
+    validateRequest?: boolean;
+    /** Custom logger for this client. Falls back to the global logger, then pino. */
+    logger?: import('./core/logger/ILogger.mjs').ILogger;
+    /** Log level for the default pino logger (`error|warn|info|debug|trace`). Overrides `ESI_LOG_LEVEL`. */
+    logLevel?: import('./core/logger/DefaultLogger.mjs').LogLevel;
+}
+export declare class EsiClient {
+    private apiClient;
+    private clients;
+    private etagCacheEnabled;
+    private _diagnostics;
+    private deduplicator;
+    constructor(config?: EsiClientConfig);
+    private getClient;
+    get alliance(): AllianceClient;
+    get assets(): AssetsClient;
+    get calendar(): CalendarClient;
+    get characters(): CharacterClient;
+    get clones(): ClonesClient;
+    get contacts(): ContactsClient;
+    get contracts(): ContractsClient;
+    get corporations(): CorporationsClient;
+    get corporationProjects(): CorporationProjectsClient;
+    get dogma(): DogmaClient;
+    get factions(): FactionClient;
+    get fittings(): FittingsClient;
+    get fleets(): FleetClient;
+    get incursions(): IncursionsClient;
+    get industry(): IndustryClient;
+    get insurance(): InsuranceClient;
+    get killmails(): KillmailsClient;
+    get location(): LocationClient;
+    get loyalty(): LoyaltyClient;
+    get mail(): MailClient;
+    get market(): MarketClient;
+    get pi(): PiClient;
+    get route(): RouteClient;
+    get search(): SearchClient;
+    get skills(): CharacterSkillsClient;
+    get sovereignty(): SovereigntyClient;
+    get status(): StatusClient;
+    get ui(): UiClient;
+    get universe(): UniverseClient;
+    get wallet(): WalletClient;
+    get wars(): WarsClient;
+    get meta(): MetaClient;
+    get freelanceJobs(): FreelanceJobsClient;
+    get cosmetics(): CosmeticsClient;
+    get paragonHub(): ParagonHubClient;
+    get skyhooks(): SkyhooksClient;
+    get mercenary(): MercenaryClient;
+    get militaryCampaigns(): MilitaryCampaignsClient;
+    get accessLists(): AccessListsClient;
+    addRequestInterceptor(fn: RequestInterceptor): () => void;
+    addResponseInterceptor(fn: ResponseInterceptor): () => void;
+    setAccessToken(token: string): void;
+    setTokenProvider(provider: TokenProvider | undefined): void;
+    get diagnostics(): EsiDiagnostics;
+    getCacheStats(): import("./index.mjs").CacheStats | null;
+    clearCache(): void;
+    updateCacheConfig(newConfig: Partial<ETagCacheConfig>): void;
+    getCircuitBreakerStats(): import("./index.mjs").CircuitBreakerStats | null;
+    resetCircuitBreaker(endpoint?: string): void;
+    batch<K, T>(keys: K[], fetcher: (key: K) => Promise<T>, options?: BatchOptions): Promise<BatchResult<K, T>>;
+    batchPost<T>(ids: number[], poster: (chunk: number[]) => Promise<T[]>, chunkSize?: number): Promise<T[]>;
+    shutdown(): void;
+}
+export declare function getDefaultClient(): EsiClient;
+//# sourceMappingURL=EsiClient.d.ts.map

package/dist/EsiClientBuilder.d.mts

@@ -0,0 +1,75 @@
+import { ApiClientType, ClientInstance, AllianceClient, AssetsClient, CalendarClient, CharacterClient, ClonesClient, ContactsClient, ContractsClient, CorporationsClient, DogmaClient, FactionClient, FittingsClient, FleetClient, IncursionsClient, IndustryClient, InsuranceClient, KillmailsClient, LocationClient, LoyaltyClient, MailClient, MarketClient, PiClient, RouteClient, SearchClient, CharacterSkillsClient, SovereigntyClient, StatusClient, UiClient, UniverseClient, WalletClient, WarsClient, MetaClient, FreelanceJobsClient, SkyhooksClient, MercenaryClient, AccessListsClient } from './core/ClientRegistry.mjs';
+import { EsiClientConfig } from './EsiClient.mjs';
+export { ApiClientType, ClientInstance };
+export declare class CustomEsiClient {
+    private apiClient;
+    private clients;
+    private enabledClients;
+    private deduplicator;
+    constructor(config: EsiClientConfig & {
+        clients: ApiClientType[];
+    });
+    getClient(clientType: ApiClientType): ClientInstance | undefined;
+    hasClient(clientType: ApiClientType): boolean;
+    getEnabledClients(): ApiClientType[];
+    get alliance(): AllianceClient | undefined;
+    get assets(): AssetsClient | undefined;
+    get calendar(): CalendarClient | undefined;
+    get characters(): CharacterClient | undefined;
+    get clones(): ClonesClient | undefined;
+    get contacts(): ContactsClient | undefined;
+    get contracts(): ContractsClient | undefined;
+    get corporations(): CorporationsClient | undefined;
+    get dogma(): DogmaClient | undefined;
+    get factions(): FactionClient | undefined;
+    get fittings(): FittingsClient | undefined;
+    get fleets(): FleetClient | undefined;
+    get incursions(): IncursionsClient | undefined;
+    get industry(): IndustryClient | undefined;
+    get insurance(): InsuranceClient | undefined;
+    get killmails(): KillmailsClient | undefined;
+    get location(): LocationClient | undefined;
+    get loyalty(): LoyaltyClient | undefined;
+    get mail(): MailClient | undefined;
+    get market(): MarketClient | undefined;
+    get pi(): PiClient | undefined;
+    get route(): RouteClient | undefined;
+    get search(): SearchClient | undefined;
+    get skills(): CharacterSkillsClient | undefined;
+    get sovereignty(): SovereigntyClient | undefined;
+    get status(): StatusClient | undefined;
+    get ui(): UiClient | undefined;
+    get universe(): UniverseClient | undefined;
+    get wallet(): WalletClient | undefined;
+    get wars(): WarsClient | undefined;
+    get meta(): MetaClient | undefined;
+    get freelanceJobs(): FreelanceJobsClient | undefined;
+    get skyhooks(): SkyhooksClient | undefined;
+    get mercenary(): MercenaryClient | undefined;
+    get accessLists(): AccessListsClient | undefined;
+    shutdown(): void;
+}
+export declare class EsiApiFactory {
+    static createAllianceClient(config?: EsiClientConfig): AllianceClient;
+    static createCharacterClient(config?: EsiClientConfig): CharacterClient;
+    static createCorporationClient(config?: EsiClientConfig): CorporationsClient;
+    static createMarketClient(config?: EsiClientConfig): MarketClient;
+    static createUniverseClient(config?: EsiClientConfig): UniverseClient;
+    static createFleetClient(config?: EsiClientConfig): FleetClient;
+    static createAssetsClient(config?: EsiClientConfig): AssetsClient;
+    static createWalletClient(config?: EsiClientConfig): WalletClient;
+    static createMailClient(config?: EsiClientConfig): MailClient;
+    static createClient(clientType: ApiClientType, config?: EsiClientConfig): ClientInstance;
+    private static buildApiClient;
+}
+export declare class EsiClientBuilder {
+    private clients;
+    private config;
+    addClient(clientType: ApiClientType): this;
+    addClients(clientTypes: ApiClientType[]): this;
+    withConfig(config: EsiClientConfig): this;
+    withClientId(clientId: string): this;
+    withAccessToken(accessToken: string): this;
+    build(): CustomEsiClient;
+}
+//# sourceMappingURL=EsiClientBuilder.d.ts.map

package/dist/auth/EsiTokenManager.d.mts

@@ -0,0 +1,200 @@
+import { EsiClient, EsiClientConfig } from '../EsiClient.mjs';
+import type { FetchLike, TokenProvider } from '../core/ApiClient.mjs';
+import type { ILogger } from '../core/logger/ILogger.mjs';
+import { EveSsoClient, AuthorizationUrlOptions, ExchangeCodeOptions } from './EveSsoClient.mjs';
+import type { ITokenStorage, StoredToken } from './types.mjs';
+export interface EsiTokenManagerConfig {
+    /** The application's SSO client id. */
+    clientId: string;
+    /** The application's SSO client secret. Omit for a public (PKCE) client. */
+    clientSecret?: string;
+    /** Redirect URI registered for the application. */
+    callbackUrl?: string;
+    /** Where tokens are persisted. Defaults to {@link MemoryTokenStorage}. */
+    storage?: ITokenStorage;
+    /** Pre-built SSO client. When given, `clientId`, `clientSecret`, `callbackUrl` and `fetch` are ignored for SSO calls. */
+    ssoClient?: EveSsoClient;
+    /** Custom fetch for SSO calls. Defaults to `globalThis.fetch`. */
+    fetch?: FetchLike;
+    /**
+     * How long before expiry a token counts as stale, in milliseconds.
+     * Defaults to 60 000 (one minute).
+     */
+    refreshSkewMs?: number;
+    /**
+     * When true (the default), {@link EsiTokenManager.getToken} refreshes a
+     * stale token before returning it. When false it returns the stored token
+     * as-is and refresh only happens through {@link EsiTokenManager.refresh},
+     * {@link EsiTokenManager.refreshAll}, or the 401 path of a created client.
+     */
+    autoRefresh?: boolean;
+    /** Called after a token is refreshed and persisted. */
+    onRefresh?: (token: StoredToken) => void;
+    /** Called when a refresh fails for a reason other than revocation. */
+    onRefreshError?: (characterId: number, error: Error) => void;
+    /** Called when SSO reports a character's refresh token as invalid. */
+    onRevoked?: (characterId: number) => void;
+    /** Logger for refresh activity. Defaults to the library logger. */
+    logger?: ILogger;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+export interface AddCharacterOptions extends ExchangeCodeOptions {
+    /**
+     * When the character already has a stored token, revoke its refresh token
+     * at SSO before replacing it. Defaults to false.
+     */
+    revokeReplaced?: boolean;
+}
+export interface RemoveCharacterOptions {
+    /** Revoke the refresh token at SSO before deleting it. Defaults to false. */
+    revoke?: boolean;
+}
+export interface RefreshAllOptions {
+    /** Maximum simultaneous SSO requests. Defaults to 5. */
+    concurrency?: number;
+    /**
+     * Only refresh tokens that expire within this many milliseconds (after
+     * applying the refresh skew). Omit to refresh every token.
+     */
+    expiringWithinMs?: number;
+    /** Abort the run; remaining tokens are reported as skipped. */
+    signal?: AbortSignal;
+    /**
+     * Progress callback, invoked after each token settles. A callback that
+     * throws does not stop the run; the exception is discarded.
+     */
+    onProgress?: (completed: number, total: number) => void;
+}
+export type RefreshStatus = 'refreshed' | 'skipped' | 'failed' | 'revoked';
+export interface RefreshResult {
+    characterId: number;
+    status: RefreshStatus;
+    /** New expiry in epoch milliseconds, when refreshed. */
+    expiresAt?: number;
+    /** The error, when failed or revoked. */
+    error?: Error;
+    /** True when the failure was an SSO 429 or 5xx and can be retried later. */
+    retryable?: boolean;
+    /** Why the token was skipped. */
+    reason?: 'not-stale' | 'aborted';
+}
+/** Lightweight view of a stored character, without the secrets. */
+export interface CharacterSummary {
+    characterId: number;
+    characterName: string;
+    scopes: string[];
+    expiresAt: number;
+    revoked: boolean;
+}
+/** EsiClient options a manager-created client accepts; token fields are supplied by the manager. */
+export type ManagedClientConfig = Omit<EsiClientConfig, 'accessToken' | 'onTokenRefresh'>;
+/**
+ * Keeps one valid SSO token per character on top of a pluggable
+ * {@link ITokenStorage}, refreshing ahead of expiry, coalescing concurrent
+ * refreshes, persisting rotated refresh tokens, and recording revocations so
+ * SSO is not hammered with a dead refresh token.
+ */
+export declare class EsiTokenManager {
+    private readonly storage;
+    private readonly sso;
+    private readonly refreshSkewMs;
+    private readonly autoRefresh;
+    private readonly logger;
+    private readonly now;
+    private readonly hooks;
+    private readonly inFlight;
+    /**
+     * Per-character write generation. Bumped whenever a record is replaced or
+     * removed so a refresh that was already waiting on SSO can tell its result
+     * is stale and must not be persisted over the newer state.
+     */
+    private readonly generations;
+    constructor(config: EsiTokenManagerConfig);
+    /** The SSO client used for all token traffic. */
+    getSsoClient(): EveSsoClient;
+    /** The storage adapter backing this manager. */
+    getStorage(): ITokenStorage;
+    /** Build the SSO login URL. See {@link EveSsoClient.getAuthorizationUrl}. */
+    getAuthorizationUrl(options: AuthorizationUrlOptions): string;
+    /**
+     * Exchange an authorization code and store the resulting token under the
+     * character it belongs to. An existing token for that character is
+     * replaced; storage never holds two entries for one character.
+     */
+    addCharacter(code: string, options?: AddCharacterOptions): Promise<StoredToken>;
+    /**
+     * Import tokens obtained elsewhere (a previous library version, another
+     * tool, a migration). The character identity is decoded from the access
+     * token; `expiresIn` is in seconds and defaults to the JWT `exp` claim.
+     */
+    importToken(token: {
+        accessToken: string;
+        refreshToken: string;
+        expiresIn?: number;
+    }): Promise<StoredToken>;
+    /** Delete a character's token, optionally revoking it at SSO first. */
+    removeCharacter(characterId: number, options?: RemoveCharacterOptions): Promise<void>;
+    /** The stored record for a character, or null. */
+    getStoredToken(characterId: number): Promise<StoredToken | null>;
+    /** Every stored token. */
+    listTokens(): Promise<StoredToken[]>;
+    /** Every stored character without its secrets. */
+    listCharacters(): Promise<CharacterSummary[]>;
+    /** True when the stored token grants every listed scope. */
+    hasScopes(characterId: number, scopes: readonly string[]): Promise<boolean>;
+    /**
+     * A usable access token for the character. With `autoRefresh` on, a token
+     * inside the refresh skew is refreshed first.
+     *
+     * @throws CharacterNotFoundError when no token is stored
+     * @throws TokenRevokedError when the character's refresh token is revoked
+     */
+    getToken(characterId: number): Promise<string>;
+    /**
+     * Refresh a character's token through SSO regardless of expiry. Concurrent
+     * calls for the same character share one SSO request.
+     */
+    refresh(characterId: number): Promise<StoredToken>;
+    /**
+     * Refresh stored tokens with bounded concurrency. Per-character failures
+     * never reject: each character gets its own {@link RefreshResult}. The one
+     * rejection is a failing `storage.list()`, because with no records there
+     * is no character to attribute the fault to and a silent empty run would
+     * hide a broken store from a scheduler.
+     */
+    refreshAll(options?: RefreshAllOptions): Promise<RefreshResult[]>;
+    /**
+     * A {@link TokenProvider} bound to a character, for `onTokenRefresh`. Every
+     * invocation refreshes through SSO (coalesced), because the client only
+     * calls it after ESI has rejected the current token.
+     */
+    tokenProviderFor(characterId: number): TokenProvider;
+    /**
+     * An {@link EsiClient} whose access token and refresh provider are bound to
+     * the character. The token is validated (and refreshed if stale) first.
+     */
+    createClient(characterId: number, config?: ManagedClientConfig): Promise<EsiClient>;
+    private isStale;
+    private requireStored;
+    private generationOf;
+    private bumpGeneration;
+    /**
+     * After an SSO round trip, decide whether the refresh still owns the
+     * character's record. Returns null when it does. When the record was
+     * replaced meanwhile, returns the current record so the caller hands out
+     * the newer credentials; when it was removed, throws CharacterNotFoundError.
+     */
+    private supersededBy;
+    private doRefresh;
+    private refreshOne;
+    private storeResponse;
+    /**
+     * Build the record to persist. When adding a character the access token
+     * must decode, because it is the only source of the character id. On a
+     * refresh the identity is already known, so a token that does not decode
+     * (a proxy, a future SSO format) keeps the previous record's identity.
+     */
+    private buildStoredToken;
+}
+//# sourceMappingURL=EsiTokenManager.d.ts.map