@lgriffin/esi.ts 6.0.0 → 7.4.0

package/CHANGELOG.md

@@ -5,7 +5,116 @@ 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).
 
-## [Unreleased]
+## [7.4.0] - 2026-07-17
+
+### Added
+
+- **`withSafeMode()` on all domain clients** — mirrors existing `withMetadata()`, surfaces the `EsiResult<T>` discriminated union (`{ ok: true, data, meta } | { ok: false, error }`) without needing to call `createClient()` directly
+- **`responseSchema` on `routeEndpoints`** — was the only endpoint file without runtime response validation; now validated with `z.looseObject({ route: z.array(z.number()) })`
+
+### Changed
+
+- **ESLint 8 → 10 flat config migration** — replaced `.eslintrc.cjs` with `eslint.config.mjs`, switched to unified `typescript-eslint` package, dropped `eslint-plugin-prettier` (redundant with lint-staged)
+- **jest-fetch-mock 3 → 4** — updated null-body status mocks (204/304) to use `new Response(null, ...)` per Fetch spec
+- Updated 11 minor/patch dependencies: @commitlint/cli, @microsoft/api-extractor, @redocly/cli, @types/node, @typescript-eslint/*, eslint-plugin-sonarjs, fast-check, knip, prettier, typedoc
+
+### Fixed
+
+- CI: aligned `codeql.yml` branch targets to `[master, main, develop]`
+- CI: pinned `jest-coverage-comment@main` → `@v1.0.34` (supply-chain risk)
+- CI: added schema drift and generated types freshness checks to release pipeline
+
+### Deprecated
+
+- `AllianceClient.getContacts()` — use `ContactsClient.getAllianceContacts()` instead
+- `AllianceClient.getContactLabels()` — use `ContactsClient.getAllianceContactLabels()` instead
+
+## [7.3.0] - 2026-07-14
+
+### Added
+
+- **`EsiResult<T>` discriminated union** and `safeMode` option for error-safe API calls
+- **Branded ID types** (16 types) for type-safe ESI entity references
+- **Expanded type-level tests** with tsd for error guards, endpoints, and domain types
+- **Compile-time spec-to-Zod type alignment checks**
+- **Schema drift detection** as a blocking CI check
+- **Comprehensive testing gap closure** (+1233 tests)
+
+### Fixed
+
+- Resolved three CI jobs failing with continue-on-error
+- Normalized CRLF in API surface check
+- Fixed schemathesis report permissions and `--url` flag
+- Fixed API surface ordering issues
+- Added missing `system_id` to `MarketOrderSchema` test data
+
+## [7.2.0] - 2026-07-08
+
+### Added
+
+- **Contract testing infrastructure** — deep validation of all endpoint definitions against the live ESI OpenAPI spec (`npm run contract:live`). Checks path parameter alignment, required query params, request body consistency, auth requirements, response schema coverage, HTTP methods, pagination metadata, and deprecation sync. 8 contract validation categories with known-exception tracking.
+- **Property-based fuzz testing** with [fast-check](https://github.com/dubzzz/fast-check) — 601 tests fuzzing `validatePathParam()`, `validateQueryParam()`, `buildEndpointPath()`, and all Zod schemas with random/adversarial inputs (`npm run fuzz`)
+- **OpenAPI spec snapshot & diff** — `npm run contract:snapshot` saves a baseline; `npm run contract:diff` detects breaking changes via [oasdiff](https://github.com/Tufin/oasdiff) (Docker)
+- **Consumer type tests** with [tsd](https://github.com/tsdjs/tsd) — verifies public API type correctness (`npm run test:types`)
+- **Prism mock server** — `npm run mock:esi` starts a spec-conformant ESI mock on port 4010 via [@stoplight/prism-cli](https://stoplight.io/open-source/prism)
+- **Schemathesis fuzz runner** — `npm run fuzz:api` runs Schemathesis against the Prism mock (Docker, weekly CI)
+- Contract and fuzz test CI jobs added to `ci.yml` quality gate
+- Weekly spec drift detection job added to `maintenance.yml`
+- `jest.contract.config.cjs` and `jest.fuzz.config.cjs` test configurations
+
+### Dependencies
+
+- Added `fast-check` (dev) — property-based testing framework
+- Added `@stoplight/prism-cli` (dev) — OpenAPI mock server
+- Added `tsd` (dev) — TypeScript type testing
+
+## [7.1.0] - 2026-07-08
+
+### Added
+
+- **Redocly CLI integration** — lints the live ESI OpenAPI spec for structural validity and best-practice compliance (`npm run validate:spec`). Catches spec breakage from CCP before it breaks generated types, cache TTLs, or scopes. Baseline: 0 errors, 328 warnings (all known CCP spec issues).
+- `redocly.yaml` config with tuned rulesets for ESI — structural rules as errors, CCP spec quirks as warnings
+- `validate:spec` npm script added to `check:all` pipeline
+
+## [7.0.0] - 2026-07-08
+
+### Breaking Changes
+
+- **Swagger 2.0 → OpenAPI 3.1 migration** — all generated types, cache TTLs, scopes, and rate limit groups are now sourced from the ESI OpenAPI 3.1 spec (`/meta/openapi.json`) instead of the deprecated Swagger 2.0 spec (`/latest/swagger.json`). See [esi-issues#1490](https://github.com/esi/esi-issues/issues/1490).
+- **Generated interface names changed** — `EsiSpec` namespace types now use OpenAPI schema names (e.g., `AllianceDetail` instead of `GetAlliancesAllianceIdOk`). These are generated types; hand-written consumer types are unchanged.
+- **Cache TTL metadata key** — internally changed from `x-cached-seconds` to `x-cache-age`. No consumer-facing impact (cache behavior is identical).
+
+### Changed
+
+- Single OpenAPI spec fetch instead of dual Swagger + OpenAPI fetches
+- Updated all scripts, tests, and documentation to reference OpenAPI spec
+- Generated types now include 161 interfaces (up from 147), 126 cache TTLs, 70 scopes
+
+## [6.1.0] - 2026-07-07
+
+### Added
+
+- **Fleet wing/squad name validation** — `renameFleetWing()` and `renameFleetSquad()` now reject names exceeding ESI's 10-character limit before sending the request, with a clear error message
+- **43 runnable example scripts** covering all 210 ESI endpoints against live Tranquility (10 new example files: character-details, corporation-details, calendar-search, loyalty-pi, faction-details, industry-mining, market-orders, universe-encyclopedia, corp-contracts-wallet, dogma-meta-sov)
+- **3 write-operation example scripts** — `write-operations.ts` (contacts, fittings, mail, UI lifecycle), `universe-post-helpers.ts` (name resolution, affiliation), `freelance-jobs.ts` (cursor-paginated queries)
+- Live output captured for all example scripts in `examples/output/`
+- 3 new TDD test files and 1 new BDD feature file (81 TDD files, 40 BDD features total)
+- 2 new fleet validation unit tests
+
+### Fixed
+
+- **Fleet test babel parse errors** — replaced TypeScript cast syntax `(result as any[]).forEach(...)` with direct index access in fleet tests (pre-existing bug unmasked by stricter transpilation)
+- **Fleet rename test names** — test mock names shortened to respect ESI's 10-character limit (`'New Squad Name'` → `'New Squad'`)
+
+### Changed
+
+- README rewritten with "Why ESI.ts vs. OpenAPI-generated clients" comparison, full endpoint coverage table, and updated architecture/testing references
+- `guides/ARCHITECTURE.md`, `guides/TESTING.md`, and `TESTING.md` updated to current test counts (121 suites, 3,224 tests)
+- Autopilot example waypoint changed from Jita to Rens
+
+### Schemas
+
+- Multiple Zod schema fixes discovered during live endpoint validation: added missing enum values, corrected optional fields, and adjusted types to match actual ESI responses
 
 ## [6.0.0] - 2026-07-03
 

package/README.md

@@ -8,17 +8,46 @@
 [![Coverage](https://img.shields.io/badge/coverage-65%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)
 
-A type-safe TypeScript client for the [EVE Online ESI API](https://esi.evetech.net/).
-
-- Typed responses for all endpoints with **runtime validation** via Zod schemas
-- Spec-driven type generation from ESI swagger spec (147 interfaces)
-- ETag caching with Cache-Control TTL, stale-on-error, and write invalidation
-- Spec-aware cache TTLs — zero-request cache hits within ESI-specified windows
-- Batch requests with bounded concurrency and auto-chunking
-- Automatic offset-based pagination, cursor-based pagination, and streaming pagination support
-- Rate limiting with header-driven backoff
-- Automatic token refresh with 401 retry and concurrent coalescing
-- 35 domain clients covering the full ESI surface
+A production-grade TypeScript client for the [EVE Online ESI API](https://esi.evetech.net/), built on the **OpenAPI 3.1 spec**, with runtime validation, intelligent caching, and full endpoint coverage.
+
+**v7.0.0** — Fully migrated from the deprecated Swagger 2.0 spec to OpenAPI 3.1 (`/meta/openapi.json`). All generated types, cache TTLs, scopes, and rate limit groups are now sourced from a single OpenAPI fetch. See [esi-issues#1490](https://github.com/esi/esi-issues/issues/1490) for the deprecation notice.
+
+**208 endpoint definitions — 194 from the public ESI OpenAPI spec, plus 14 for newer EVE features (Equinox sovereignty, orbital skyhooks, mercenary dens, access lists, freelance jobs). All 206 exercisable endpoints validated against live Tranquility on 2026-07-08.**
+
+## Why ESI.ts vs. OpenAPI-Generated Clients?
+
+Tools like `openapi-typescript` or `openapi-generator` can produce a typed client from the ESI OpenAPI spec in minutes. They're a reasonable starting point — but they stop at type generation. ESI.ts is a purpose-built SDK that handles the problems you hit _after_ the types compile.
+
+### What generators give you
+
+- TypeScript interfaces from the OpenAPI spec
+- Basic request/response typing
+- A thin HTTP wrapper
+
+### What ESI.ts gives you on top of that
+
+| Capability                      | openapi-typescript                                                                                                  | ESI.ts                                                                                                                                                                                                  |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Runtime response validation** | None — types are erased at compile time. If CCP changes a field, you get silent data corruption.                    | Every GET response is validated at runtime via [Zod](https://zod.dev/) schemas — all 173 GET endpoints have schemas. Schema mismatches throw `EsiValidationError` immediately.                          |
+| **Intelligent caching**         | None — you build your own.                                                                                          | Three-tier: spec-aware TTL (zero HTTP calls within ESI's `x-cached-seconds` window), ETag conditional GETs, stale-on-error fallback on 5xx. Write operations auto-invalidate related GET caches.        |
+| **Rate limiting**               | None — you build your own.                                                                                          | 36 per-group token buckets extracted from the ESI spec at build time. Market requests can't starve wallet requests. Optional per-user bucketing for multi-character apps.                               |
+| **Pagination**                  | Manual — you write the page loop.                                                                                   | Automatic offset pagination, cursor-based pagination (Equinox-era endpoints), and streaming `AsyncGenerator` pagination for memory-efficient processing of large datasets.                              |
+| **Retry & resilience**          | None.                                                                                                               | Exponential backoff with jitter, circuit breaker (closed/open/half-open), automatic 401 token refresh with concurrent coalescing.                                                                       |
+| **Wire format correctness**     | Generates from spec, but ESI's spec has inconsistencies (query params documented as body, missing required fields). | Every endpoint tested against live ESI. Wire format bugs (query params vs. body, field naming) are caught and fixed — see the contacts and UI endpoint fixes in v6.1.0.                                 |
+| **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.                                                                                         | 35 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).                                      |
+| **Testing**                     | Whatever you write.                                                                                                 | 121+ test suites, 3,800+ tests across 9 tiers including property-based fuzzing (fast-check), deep contract tests against live OpenAPI spec, and consumer type tests (tsd). 43 runnable example scripts. |
+
+### The real problem with generated clients
+
+The ESI OpenAPI spec is not a perfect source of truth. During live endpoint validation against the OpenAPI 3.1 spec, we discovered:
+
+- `addContacts`, `editContacts`, and 4 UI endpoints document parameters as request body when ESI actually expects query parameters
+- `deleteCharacterContacts` expects comma-separated contact IDs as a query param, not a JSON body
+- Fleet wing/squad names have a 10-character limit not documented in the spec
+- The `updateMailMetadata` endpoint uses the field name `read`, not `is_read`
+
+A generated client faithfully reproduces these spec bugs. ESI.ts fixes them.
 
 ## Installation
 
@@ -44,7 +73,7 @@ Verify everything works:
 
 ```bash
 npm run example:status   # quick smoke test — checks ESI is reachable
-npm test                 # run the full test suite
+npm test                 # run the full test suite (121 suites, 3,224 tests)
 ```
 
 ## Quick Start
@@ -207,43 +236,74 @@ Key behaviors:
 
 All clients are accessed as properties on the `EsiClient` instance. Authenticated endpoints require an access token.
 
-| Client         | Property               | Auth | Examples                                                 |
-| -------------- | ---------------------- | ---- | -------------------------------------------------------- |
-| Alliance       | `client.alliance`      | Some | `getAlliances()`, `getAllianceById(id)`                  |
-| Assets         | `client.assets`        | Yes  | `getCharacterAssets(id)`                                 |
-| Calendar       | `client.calendar`      | Yes  | `getCharacterCalendar(id)`                               |
-| Characters     | `client.characters`    | Some | `getCharacterPublicInfo(id)`, `getCharacterPortrait(id)` |
-| Clones         | `client.clones`        | Yes  | `getCharacterClones(id)`                                 |
-| Contacts       | `client.contacts`      | Yes  | `getCharacterContacts(id)`                               |
-| Contracts      | `client.contracts`     | Yes  | `getCharacterContracts(id)`                              |
-| Corporations   | `client.corporations`  | Some | `getCorporationInfo(id)`, `getCorporationMembers(id)`    |
-| Dogma          | `client.dogma`         | No   | `getDogmaAttributes()`, `getDogmaEffects()`              |
-| Factions       | `client.factions`      | Some | `getFactionWarStats()`                                   |
-| Fittings       | `client.fittings`      | Yes  | `getFittings(id)`, `createFitting(id, body)`             |
-| Fleets         | `client.fleets`        | Yes  | `getFleet(id)`, `getFleetMembers(id)`                    |
-| Incursions     | `client.incursions`    | No   | `getIncursions()`                                        |
-| Industry       | `client.industry`      | Some | `getCharacterIndustryJobs(id)`                           |
-| Insurance      | `client.insurance`     | No   | `getInsurancePrices()`                                   |
-| Killmails      | `client.killmails`     | Some | `getKillmail(id, hash)`                                  |
-| Location       | `client.location`      | Yes  | `getCharacterLocation(id)`                               |
-| Loyalty        | `client.loyalty`       | Yes  | `getCharacterLoyaltyPoints(id)`                          |
-| Mail           | `client.mail`          | Yes  | `getCharacterMail(id)`                                   |
-| Market         | `client.market`        | Some | `getMarketPrices()`, `getMarketOrders(regionId)`         |
-| PI             | `client.pi`            | Yes  | `getCharacterPlanets(id)`                                |
-| Route          | `client.route`         | No   | `getRoute(origin, destination)`                          |
-| Search         | `client.search`        | Some | `search(characterId, query)`                             |
-| Skills         | `client.skills`        | Yes  | `getCharacterSkills(id)`                                 |
-| Sovereignty    | `client.sovereignty`   | No   | `getSovereigntySystems()`, `getSovereigntyMap()`         |
-| Skyhooks       | `client.skyhooks`      | No   | `getSovereigntyHubs()`, `getRaidableSkyhooks()`          |
-| Mercenary      | `client.mercenary`     | No   | `getMercenaryDens()`, `getMercenaryTacticalOperations()` |
-| Access Lists   | `client.accessLists`   | Yes  | `getAccessList(id)`                                      |
-| Status         | `client.status`        | No   | `getStatus()`                                            |
-| UI             | `client.ui`            | Yes  | `setWaypoint(id)`                                        |
-| Universe       | `client.universe`      | Some | `getSystemById(id)`, `getTypeById(id)`                   |
-| Wallet         | `client.wallet`        | Yes  | `getCharacterWallet(id)`                                 |
-| Wars           | `client.wars`          | No   | `getWars()`, `getWarById(id)`                            |
-| Freelance Jobs | `client.freelanceJobs` | Some | `getFreelanceJobs()`, `getFreelanceJobById(id)`          |
-| Meta           | `client.meta`          | No   | `getOpenApiJson()`, `getOpenApiYaml()`                   |
+| Client         | Property               | Auth | Examples                                                                         |
+| -------------- | ---------------------- | ---- | -------------------------------------------------------------------------------- |
+| Alliance       | `client.alliance`      | Some | `getAlliances()`, `getAllianceById(id)`                                          |
+| Assets         | `client.assets`        | Yes  | `getCharacterAssets(id)`                                                         |
+| Calendar       | `client.calendar`      | Yes  | `getCalendarEvents(id)`                                                          |
+| Characters     | `client.characters`    | Some | `getCharacterPublicInfo(id)`, `getCharacterPortrait(id)`                         |
+| Clones         | `client.clones`        | Yes  | `getCharacterClones(id)`                                                         |
+| Contacts       | `client.contacts`      | Yes  | `getCharacterContacts(id)`, `postCharacterContacts(id, standing, contactIds)`    |
+| Contracts      | `client.contracts`     | Yes  | `getCharacterContracts(id)`                                                      |
+| Corporations   | `client.corporations`  | Some | `getCorporationInfo(id)`, `getCorporationMembers(id)`                            |
+| Dogma          | `client.dogma`         | No   | `getDogmaAttributes()`, `getDynamicItemInfo(typeId, itemId)`                     |
+| Factions       | `client.factions`      | Some | `getFactionWarStats()`                                                           |
+| Fittings       | `client.fittings`      | Yes  | `getFittings(id)`, `createFitting(id, body)`                                     |
+| Fleets         | `client.fleets`        | Yes  | `getFleetInformation(id)`, `getFleetMembers(id)`                                 |
+| Incursions     | `client.incursions`    | No   | `getIncursions()`                                                                |
+| Industry       | `client.industry`      | Some | `getCharacterIndustryJobs(id)`                                                   |
+| Insurance      | `client.insurance`     | No   | `getInsurancePrices()`                                                           |
+| Killmails      | `client.killmails`     | Some | `getKillmail(id, hash)`                                                          |
+| Location       | `client.location`      | Yes  | `getCharacterLocation(id)`                                                       |
+| Loyalty        | `client.loyalty`       | Yes  | `getCharacterLoyaltyPoints(id)`                                                  |
+| Mail           | `client.mail`          | Yes  | `getCharacterMail(id)`, `sendMail(id, body)`                                     |
+| Market         | `client.market`        | Some | `getMarketPrices()`, `getMarketOrders(regionId)`                                 |
+| PI             | `client.pi`            | Yes  | `getCharacterPlanets(id)`                                                        |
+| Route          | `client.route`         | No   | `getRoute(origin, destination)`                                                  |
+| Search         | `client.search`        | Some | `search(characterId, query)`                                                     |
+| Skills         | `client.skills`        | Yes  | `getCharacterSkills(id)`                                                         |
+| Sovereignty    | `client.sovereignty`   | No   | `getSovereigntySystems()`, `getSovereigntyMap()`                                 |
+| Skyhooks       | `client.skyhooks`      | No   | `getSovereigntyHubs()`, `getRaidableSkyhooks()`                                  |
+| Mercenary      | `client.mercenary`     | No   | `getMercenaryDens()`, `getMercenaryTacticalOperations()`                         |
+| Access Lists   | `client.accessLists`   | Yes  | `getAccessList(id)`                                                              |
+| Status         | `client.status`        | No   | `getStatus()`                                                                    |
+| UI             | `client.ui`            | Yes  | `setAutopilotWaypoint(destId, addToBeginning, clear)`, `openNewMailWindow(body)` |
+| Universe       | `client.universe`      | Some | `getSystemById(id)`, `getTypeById(id)`                                           |
+| Wallet         | `client.wallet`        | Yes  | `getCharacterWallet(id)`                                                         |
+| Wars           | `client.wars`          | No   | `getWars()`, `getWarById(id)`                                                    |
+| Freelance Jobs | `client.freelanceJobs` | Some | `getFreelanceJobs()`, `getFreelanceJobById(id)`                                  |
+| Meta           | `client.meta`          | No   | `getOpenApiJson()`, `getOpenApiYaml()`                                           |
+
+## Runtime Response Validation
+
+ESI.ts validates API responses at runtime using [Zod](https://zod.dev/) schemas. All GET endpoints have schemas — these are the endpoints that return data your application consumes, where a silent shape change from CCP would cause bugs. POST/PUT/DELETE mutations typically return `204 No Content` (no body to validate) or simple confirmation values, so schemas are omitted where there is nothing meaningful to validate.
+
+Validation is **on by default**. Extra fields from ESI are preserved via `z.looseObject()` passthrough mode, so new fields added by CCP won't break your application — they flow through to your code untouched.
+
+```typescript
+import {
+  EsiClient,
+  EsiValidationError,
+  isValidationError,
+  schemas,
+} from '@lgriffin/esi.ts';
+
+const client = new EsiClient();
+
+// Validation happens automatically on every request
+const character = await client.characters.getCharacterPublicInfo(12345);
+
+// Disable validation globally if needed
+const rawClient = new EsiClient({ validateResponse: false });
+
+// Use schemas directly for your own validation
+const result = schemas.CharacterInfoSchema.safeParse(someData);
+if (result.success) {
+  console.log(result.data.name);
+}
+```
+
+See [guides/RUNTIME-VALIDATION.md](guides/RUNTIME-VALIDATION.md) for the full guide on schemas, error handling, and extending schemas.
 
 ## Caching
 
@@ -271,7 +331,7 @@ const uncachedClient = new EsiClient({ enableETagCache: false });
 
 ### Spec-Aware Cache TTLs
 
-The library reads `x-cached-seconds` from the ESI swagger spec (119 of 195 endpoints). Within the TTL window, repeated GET requests return cached data with **zero HTTP calls** — not even a conditional GET.
+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:
 
@@ -323,82 +383,6 @@ const allNames = await client.batchPost(
 );
 ```
 
-## Runtime Response Validation
-
-ESI.ts validates every API response at runtime using [Zod](https://zod.dev/) schemas. If CCP changes the ESI API and the response no longer matches the expected shape, you get an immediate `EsiValidationError` instead of silent data corruption.
-
-Validation is **on by default**. Extra fields from ESI are preserved (passthrough mode), so new fields added by CCP won't break your application.
-
-```typescript
-import {
-  EsiClient,
-  EsiValidationError,
-  isValidationError,
-  schemas,
-} from '@lgriffin/esi.ts';
-
-const client = new EsiClient();
-
-// Validation happens automatically on every request
-const character = await client.characters.getCharacterPublicInfo(12345);
-
-// Disable validation globally if needed
-const rawClient = new EsiClient({ validateResponse: false });
-
-// Use schemas directly for your own validation
-const result = schemas.CharacterInfoSchema.safeParse(someData);
-if (result.success) {
-  console.log(result.data.name);
-}
-```
-
-See [guides/RUNTIME-VALIDATION.md](guides/RUNTIME-VALIDATION.md) for the full guide on schemas, error handling, and extending schemas.
-
-## Generated Types
-
-The library includes TypeScript interfaces generated directly from the ESI swagger spec, available as the `EsiSpec` namespace. These are guaranteed to match the live spec and complement the hand-written types:
-
-```typescript
-import { EsiSpec } from '@lgriffin/esi.ts';
-
-// Generated type — exact spec field names and optionality
-const order: EsiSpec.GetMarketsRegionIdOrders200Ok = {
-  order_id: 123,
-  type_id: 34,
-  price: 5.5,
-  volume_remain: 1000,
-  volume_total: 5000,
-  is_buy_order: false,
-  // ...
-};
-```
-
-To regenerate types from the latest ESI spec:
-
-```bash
-npm run generate:types    # fetches spec, generates 147 interfaces + cache TTL map + rate limit groups + scope map
-npm run validate:esi      # reports type drift between hand-written and generated types
-```
-
-## ESI Scopes
-
-The library includes a generated scope-to-endpoint mapping extracted from the ESI swagger spec. Use it to check which OAuth scopes an endpoint requires before making a request:
-
-```typescript
-import { esiEndpointScopes, EsiScope } from '@lgriffin/esi.ts';
-
-// Look up scopes for a specific endpoint
-const walletScopes = esiEndpointScopes['GET:characters/{character_id}/wallet'];
-// → ['esi-wallet.read_character_wallet.v1']
-
-// Check if an endpoint requires auth
-const isPublic = !esiEndpointScopes['GET:universe/types/{type_id}'];
-// → true (public endpoint, no scopes needed)
-
-// Type-safe scope values
-const scope: EsiScope = 'esi-assets.read_assets.v1';
-```
-
 ## 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:
@@ -495,6 +479,51 @@ Key points:
 - **Duplicates across pages** are expected when records are modified between requests
 - Existing offset-based routes (`getMarketOrders`, etc.) are unchanged
 
+## Generated Types
+
+The library includes TypeScript interfaces generated directly from the ESI OpenAPI 3.1 spec, available as the `EsiSpec` namespace. These are guaranteed to match the live spec and complement the hand-written types:
+
+```typescript
+import { EsiSpec } from '@lgriffin/esi.ts';
+
+// Generated type — uses OpenAPI schema names (v7.0.0+)
+const order: EsiSpec.MarketsRegionIdOrdersGet = {
+  order_id: 123,
+  type_id: 34,
+  price: 5.5,
+  volume_remain: 1000,
+  volume_total: 5000,
+  is_buy_order: false,
+  // ...
+};
+```
+
+To regenerate types from the latest ESI spec:
+
+```bash
+npm run generate:types    # fetches OpenAPI spec, generates 161 interfaces + cache TTL map + rate limit groups + scope map
+npm run validate:esi      # reports type drift between hand-written and generated types
+```
+
+## ESI Scopes
+
+The library includes a generated scope-to-endpoint mapping extracted from the ESI OpenAPI spec. Use it to check which OAuth scopes an endpoint requires before making a request:
+
+```typescript
+import { esiEndpointScopes, EsiScope } from '@lgriffin/esi.ts';
+
+// Look up scopes for a specific endpoint
+const walletScopes = esiEndpointScopes['GET:characters/{character_id}/wallet'];
+// → ['esi-wallet.read_character_wallet.v1']
+
+// Check if an endpoint requires auth
+const isPublic = !esiEndpointScopes['GET:universe/types/{type_id}'];
+// → true (public endpoint, no scopes needed)
+
+// Type-safe scope values
+const scope: EsiScope = 'esi-assets.read_assets.v1';
+```
+
 ## Error Handling
 
 API errors throw `EsiError` with `statusCode`, `message`, and `url` properties:
@@ -628,9 +657,29 @@ const marketClient = EsiApiFactory.createMarketClient({
 const prices = await marketClient.getMarketPrices();
 ```
 
+## Endpoint Coverage
+
+All 208 endpoint definitions have been validated against live Tranquility using the **OpenAPI 3.1 spec** — 194 from the public ESI spec plus 14 for newer EVE features. 206 endpoints are exercisable (2 mercenary den endpoints await CCP deployment). Full output is captured in [`openapi.output.md`](openapi.output.md).
+
+| Category                    | Endpoints | Method                                             |
+| --------------------------- | --------- | -------------------------------------------------- |
+| Public GETs                 | 78        | 43 runnable example scripts with captured output   |
+| Authenticated GETs          | 72        | Example scripts + live testing with EVE SSO tokens |
+| Contacts (POST/PUT/DELETE)  | 3         | Live create/edit/delete lifecycle                  |
+| Fittings (POST/DELETE)      | 2         | Live create/delete lifecycle                       |
+| Mail (POST/PUT/DELETE)      | 5         | Live send/label/metadata/delete lifecycle          |
+| UI (POST)                   | 5         | Live testing with EVE client running               |
+| Calendar (PUT)              | 1         | Live RSVP to event                                 |
+| Fleet (GET/POST/PUT/DELETE) | 14        | Live fleet with fleet commander + squad members    |
+| Assets POST                 | 3         | Live asset location/name queries                   |
+| CSPA (POST)                 | 1         | Live charge cost calculation                       |
+| Dogma dynamic (GET)         | 1         | Live mutaplasmid (Abyssal) item query              |
+| Universe POST helpers       | 3         | Live name resolution and affiliation               |
+| Freelance Jobs (GET)        | 4         | Live queries (graceful 404 for no active jobs)     |
+
 ## Examples
 
-Runnable examples are in the `examples/` directory.
+43 runnable examples are in the `examples/` directory.
 
 ### Public Endpoints (no auth needed)
 
@@ -651,23 +700,39 @@ npm run example:rate-limiting      # Rate limiter & pagination demonstration
 npm run example:cursor-pagination  # Freelance Jobs with cursor pagination
 npm run example:streaming          # Streaming pagination for large datasets
 npm run example:token-refresh      # Automatic token refresh on 401
+npm run example:universe-encyclopedia  # Ancestries, bloodlines, races, celestials
+npm run example:dogma-meta-sov         # Dogma effects, sovereignty, meta endpoint
+npm run example:faction-details        # Faction warfare leaderboards and stats
 ```
 
 ### Authenticated Endpoints (require ESI_ACCESS_TOKEN)
 
-These examples require an EVE SSO token with the listed scopes. Set `ESI_ACCESS_TOKEN` in your environment or `.env` file.
-
 ```bash
 npm run example                    # Full character profile assembly
-npm run example:wallet       # Wallet balance, journal, transactions    (esi-wallet.read_character_wallet.v1)
-npm run example:skills       # Trained skills, queue, attributes        (esi-skills.read_skills.v1, esi-skills.read_skillqueue.v1)
-npm run example:assets       # Asset inventory with bulk name lookup    (esi-assets.read_assets.v1)
-npm run example:killmails    # Recent killmails + full details          (esi-killmails.read_killmails.v1)
-npm run example:fleet        # Fleet info, members, wing/squad structure (esi-fleets.read_fleet.v1)
-npm run example:mail         # Inbox headers, labels, mailing lists    (esi-mail.read_mail.v1)
-npm run example:location     # Current system, online status, ship     (esi-location.read_location.v1)
-npm run example:fittings     # Saved fittings + clone state + implants (esi-fittings.read_fittings.v1, esi-clones.read_clones.v1)
-npm run example:contacts     # Contact list with standings + labels    (esi-characters.read_contacts.v1)
+npm run example:wallet       # Wallet balance, journal, transactions
+npm run example:skills       # Trained skills, queue, attributes
+npm run example:assets       # Asset inventory with bulk name lookup
+npm run example:killmails    # Recent killmails + full details
+npm run example:fleet        # Fleet info, members, wing/squad structure
+npm run example:mail         # Inbox headers, labels, mailing lists
+npm run example:location     # Current system, online status, ship
+npm run example:fittings     # Saved fittings + clone state + implants
+npm run example:contacts     # Contact list with standings + labels
+npm run example:character-details  # Blueprints, roles, standings, medals
+npm run example:corporation-details  # Corp members, divisions, structures
+npm run example:calendar-search      # Calendar events + character search
+npm run example:loyalty-pi           # Loyalty points + planetary interaction
+npm run example:industry-mining      # Industry jobs + mining ledger
+npm run example:market-orders        # Character/corp market orders
+npm run example:corp-contracts-wallet # Corp contracts, contacts, wallets
+```
+
+### Write Operations (require specific scopes + caution)
+
+```bash
+npm run example:write-ops          # Contacts, fittings, mail, UI lifecycle tests
+npm run example:universe-posts     # Name resolution + character affiliation (public)
+npm run example:freelance-jobs     # Freelance job queries
 ```
 
 ### Parallel Requests
@@ -711,6 +776,35 @@ try {
 }
 ```
 
+## Testing
+
+ESI.ts has a comprehensive multi-tier testing strategy:
+
+| Tier                       | Tests            | Purpose                                                            |
+| -------------------------- | ---------------- | ------------------------------------------------------------------ |
+| **TDD unit tests**         | 81 files         | Every client method, endpoint path, query param, and body format   |
+| **BDD scenario tests**     | 40 feature files | Behavioral specifications in Gherkin (Given/When/Then)             |
+| **Mocked integration**     | Full suite       | Cross-layer request flow with jest-fetch-mock                      |
+| **Live smoke tests**       | 43 examples      | Every endpoint against live Tranquility                            |
+| **ESI spec contract**      | 15 tests         | Endpoint definitions validated against live OpenAPI spec           |
+| **Deep contract tests**    | 8 categories     | Path params, query params, body, auth, schemas, pagination vs spec |
+| **Property-based fuzzing** | 601 tests        | fast-check fuzzing of validation, URL construction, Zod schemas    |
+| **Type-level tests**       | tsd              | Consumer API type correctness via tsd                              |
+| **Gated auth tests**       | 33 tests         | Authenticated endpoints with real tokens                           |
+
+```bash
+npm test          # Unit + BDD tests (121 suites, 3,224 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 test:types # tsd consumer type tests
+```
+
+Coverage thresholds are enforced in CI: branches 50%, functions 50%, lines 65%, statements 65%.
+
+See [guides/TESTING.md](guides/TESTING.md) for the full testing guide, and [guides/ARCHITECTURE.md](guides/ARCHITECTURE.md) for architecture diagrams.
+
 ## Development
 
 ### Prerequisites
@@ -731,6 +825,7 @@ The project uses a comprehensive suite of static analysis and code quality tools
 | [eslint-plugin-sonarjs](https://github.com/SonarSource/eslint-plugin-sonarjs)        | Cognitive complexity and code smell detection           | Integrated into `npm run lint` |
 | [husky](https://typicode.github.io/husky/)                                           | Git pre-commit hooks                                    | Automatic on commit            |
 | [lint-staged](https://github.com/lint-staged/lint-staged)                            | Run linters on staged files only                        | Automatic on commit            |
+| [Redocly CLI](https://redocly.com/docs/cli/)                                         | OpenAPI spec validation and linting                     | `npm run validate:spec`        |
 
 ### Available Scripts
 
@@ -743,16 +838,21 @@ npm run format             # Format code with Prettier
 npm run format:check       # Check formatting without modifying
 
 # Testing
-npm test                   # Unit tests
-npm run test:all           # Unit + improved + BDD tests
+npm test                   # Unit tests (121 suites, 3,224 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
+npm run fuzz               # Property-based fuzz tests (fast-check)
+npm run test:types         # Consumer type tests (tsd)
+npm run mock:esi           # Start Prism mock ESI server on port 4010
 
 # Static Analysis
 npm run knip               # Detect dead code and unused exports
-npm run validate:esi       # Validate endpoints against live ESI swagger spec
+npm run validate:esi       # Validate endpoints against live ESI OpenAPI spec
+npm run validate:spec      # Lint ESI OpenAPI spec with Redocly (structural + best practices)
 npm run validate           # Run all checks: lint, format, build, coverage, knip
-npm run generate:types     # Regenerate TypeScript interfaces from ESI swagger spec
+npm run generate:types     # Regenerate TypeScript interfaces from ESI OpenAPI spec
 
 # Documentation
 npm run docs               # Generate TypeDoc API documentation
@@ -761,13 +861,13 @@ npm run docs:serve         # Serve docs locally on port 8080
 
 ### ESI Endpoint Validation
 
-To verify that the codebase endpoint definitions match the live ESI swagger spec:
+To verify that the codebase endpoint definitions match the live ESI OpenAPI spec:
 
 ```bash
 npm run validate:esi
 ```
 
-This fetches `https://esi.evetech.net/latest/swagger.json` and reports:
+This fetches the ESI OpenAPI spec and reports:
 
 - Endpoints in the codebase that are no longer in the ESI spec
 - Endpoints in the ESI spec that the codebase doesn't cover
@@ -784,7 +884,7 @@ 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 spec and verifies no diff)
+- 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: 50%, functions: 50%, lines: 65%, statements: 65%)
@@ -793,20 +893,6 @@ Every pull request runs the full validation suite:
 
 See [.github/workflows/README.md](.github/workflows/README.md) for full workflow details.
 
-## Testing
-
-```bash
-npm test          # Unit + BDD tests (108 suites, 2836 tests)
-npm run coverage  # Tests with coverage report (thresholds enforced)
-npm run bdd       # BDD scenario tests only
-```
-
-To verify against the live ESI API:
-
-```bash
-npm run example:status    # Confirms ESI connectivity and server status
-```
-
 ## Contributing
 
 1. Fork the repository