@chrtco/sdk 0.9.2 → 0.10.1

package/README.md

@@ -4,6 +4,10 @@ Official TypeScript SDK for the [CHRT](https://chrt.co) nautical chart API.
 
 Zero dependencies · Works in Node 18+, browsers, Deno, Bun · Full TypeScript types
 
+> **Situational awareness only — not for primary navigation.** CHRT is not an ECDIS and is not
+> SOLAS-compliant. Do not use it as your primary means of navigation. Every chart CHRT serves comes
+> from the issuing hydrographic office; keep the source attribution visible in anything you build.
+
 ## Install
 
 ```bash
@@ -15,7 +19,8 @@ npm install @chrtco/sdk
 ```typescript
 import { Chrt } from '@chrtco/sdk';
 
-const chrt = new Chrt('chrt_live_...');
+// Read the key from the environment — never hard-code it in source.
+const chrt = new Chrt(process.env.CHRT_API_KEY!);
 
 // Get depth areas in a bounding box
 const features = await chrt.features({
@@ -30,25 +35,119 @@ const nearby = await chrt.query({
   layer: 'BOYCAR,BOYLAT',
 });
 
-// List ENC cells
-const cells = await chrt.cells.list({ source: 'NOAA' });
+// List ENC cells — `source` takes the chart-source id ('NOAA_ENC'), not the
+// agency name ('NOAA'), which matches nothing. chrt.coverage.list() lists the ids.
+const cells = await chrt.cells.list({ source: 'NOAA_ENC' });
 
 // Get a specific cell
 const cell = await chrt.cells.get('US5MA11M');
+console.log(cell.bbox_north, cell.bbox_west); // → 42.38 -71.05
+```
+
+## API keys
+
+Keys are issued in the CHRT platform under **Settings → API keys** and look like:
+
+```
+chrt_pk_live_<team>_<random>     chrt_sk_live_<team>_<random>
+chrt_pk_test_<team>_<random>     chrt_sk_test_<team>_<random>
+      ▲    ▲
+      │    └── environment: live | test
+      └── key type: pk (publishable) | sk (secret)
+```
+
+| | `pk` — publishable | `sk` — secret |
+|---|---|---|
+| Intended for | client-side code (browser, mobile app) | servers, CI, backend jobs |
+| Retrievable later | ✓ — re-reveal it in the dashboard | ✗ — shown once at creation; regenerate if lost |
+
+> **`pk` and `sk` carry identical API privileges.** The prefix records intent and whether CHRT keeps
+> the plaintext for you to re-reveal — it is **not** a capability boundary. Any key you ship to a
+> client can be extracted from it and replayed with full access.
+>
+> So treat any key embedded in a browser bundle or mobile app as public: develop against a
+> `test`-environment key, grant it only the scopes it needs, and rotate it if it leaks.
+>
+> For a key you ship to a browser, set **Allowed domains** on it (platform → API keys). A browser
+> request whose `Origin` isn't on the list is refused, so a key lifted from your bundle won't work
+> on someone else's site. It is a **browser-only deterrent, never a boundary** — a non-browser
+> caller sends no `Origin` and is allowed through, by design. Do **not** set the **IP allowlist**:
+> it does not work, and setting it bricks the key on every real request path.
+
+## Spatial queries
+
+`query()` answers "what's around me". Underway, the question is narrower.
+
+```typescript
+// What's charted AHEAD — position + bearing, no route needed.
+const fan = await chrt.ahead({
+  point: [-70.9245, 42.33604],
+  bearing: gps.cog,   // degrees true
+  arc: 60,            // FULL sector width, so ±30°
+  rangeNm: 3,
+  safetyDepth: 3,     // omit if you set `vessel`
+});
+
+// What's charted along a PLANNED PASSAGE — ordered by how far in you meet it.
+const passage = await chrt.alongRoute({
+  route: [[-70.95, 42.33], [-71.0, 42.35], [-71.02, 42.36]],
+  bufferNm: 0.5,
+});
+for (const f of passage.features) {
+  const { along_m, distance_m, depth_clearance_m } = f.properties;
+}
+
+// Which CHARTS that passage needs — a different question, so a different call.
+const { cells } = await chrt.coverage.forRoute({ route, bufferNm: 1 });
+```
+
+Neither replaces the other: a boat with a route still drifts, and COG rarely equals the route
+bearing — so a passage app wants `alongRoute()` once per route edit and `ahead()` continuously
+against the real track.
+
+**These tell you what is CHARTED, never whether it is safe.** There is no severity score and no
+`safe` flag, deliberately — a risk model is a navigation-grade claim, and CHRT is
+situational-awareness only. You get facts that sort (`distance_m`, `bearing_deg`, `along_m`,
+`least_depth_m`, `depth_clearance_m` — negative means shallower than you declared safe) and your
+application owns the judgment.
+
+**An empty result is not an all-clear.** It can mean nothing is charted there, or that CHRT has no
+coverage there at all. Every response carries a `coverage` block — check `coverage.covered` before
+telling a user anything.
+
+```typescript
+if (!fan.coverage.covered) {
+  // CHRT holds no chart for this sector. Say so — do not report "clear".
+}
 ```
 
+There is no `speed` parameter, by design: turning SOG into a lookahead distance is a navigational
+judgment that belongs to you. The usual recipe is `rangeNm = SOG_knots × lookahead_hours`,
+narrowing `arc` as speed rises. Re-fan on a meaningful course change rather than on a timer.
+
 ## Maps (MapLibre GL JS / Mapbox GL JS)
 
-`chrt.style()` returns a ready-to-use IHO **S-52** nautical style; `chrt.transformRequest()`
-mints a short-lived tile token from your API key and attaches it to tile requests
-automatically. Examples use MapLibre — substitute `mapbox-gl` if you're already on Mapbox.
+CHRT gives you two ways to get an IHO **S-52** style. They are not interchangeable — pick by whether
+your client runs JavaScript:
+
+| | `chrt.style()` | `chrt.styleUrl()` / `chrt.fetchStyle()` |
+|---|---|---|
+| What it is | a JS function that **builds** the style locally | a **URL CHRT serves** (`tiles.chrt.co/v1/styles/…`) |
+| Network | none — works offline | one authenticated request |
+| Usable from | **JavaScript only** | any HTTP client (Swift, Kotlin, Python, curl) |
+| Custom style bound to your key | not applied | **applied server-side** (Dev plan and above) |
+
+`chrt.transformRequest()` mints a short-lived tile token from your API key and attaches it to tile
+**and served-style** requests automatically. Examples use MapLibre — substitute `mapbox-gl` if you're
+already on Mapbox.
 
 ```typescript
 import maplibregl from 'maplibre-gl';
 import { Chrt } from '@chrtco/sdk';
 
-const chrt = new Chrt('chrt_live_...');
+const chrt = new Chrt(process.env.CHRT_API_KEY!);
 
+// Locally generated style — no network, no custom style applied.
 const map = new maplibregl.Map({
   container: 'map',
   style: chrt.style({ palette: 'DAY' }),   // 'DAY' | 'DUSK' | 'NIGHT'
@@ -58,14 +157,47 @@ const map = new maplibregl.Map({
 });
 ```
 
-Tiles are served from `tiles.chrt.co` and gated by a short-lived ES256 JWT. The SDK mints
-it from your key, attaches it as `Authorization: Bearer` on tile requests only, and refreshes
-it before expiry — you never handle tokens directly.
+Or use the **served** style, which honours the CHRTstyle custom style bound to your key:
+
+```typescript
+const map = new maplibregl.Map({
+  container: 'map',
+  style: await chrt.styleUrl({ theme: 'dusk' }),   // 'day' | 'dusk' | 'night'
+  transformRequest: chrt.transformRequest(),       // required — authenticates the style request too
+});
+```
+
+`styleUrl()` is `async`: it pre-mints the tile token so the style request — which MapLibre does
+**not** retry — is guaranteed to carry auth. Always pair it with `transformRequest()`.
+
+Tiles are served from `tiles.chrt.co` and gated by a short-lived ES256 JWT. The SDK mints it from
+your key, attaches it as `Authorization: Bearer`, and refreshes it before expiry — you never handle
+tokens directly.
+
+### Symbol families
+
+`style()`, `styleUrl()` and `fetchStyle()` all select symbol artwork, but **the option is spelled
+differently** on the local and served paths:
+
+```typescript
+chrt.style({ symbolSet: 's101' });      // local  — symbolSet, palette: 'DAY' | 'DUSK' | 'NIGHT'
+await chrt.styleUrl({ symbols: 's101' }); // served — symbols,   theme:   'day' | 'dusk' | 'night'
+```
+
+| Value | Artwork |
+|---|---|
+| `s52` (default) | IHO S-52 Presentation Library — spec-exact ATON/LIGHTS selection |
+| `s101` | official IHO S-101 Portrayal Catalogue artwork |
+| `chrt` | CHRT house set — colour-true silhouettes, capability badges |
+| `raster` | raster symbol set |
+
+`s101` and `chrt` need their images loaded at runtime via `loadS101SymbolImages` /
+`loadChrtSymbolImages` from `@chrtco/sdk/atlas/browser`.
 
 ### Custom styles
 
-`chrt.style()` returns a standard MapLibre style object you can mutate. For a fully custom
-look, build your own style over CHRT's vector source with `buildSources()` and keep
+`chrt.style()` returns a standard MapLibre style object you can mutate. For a fully custom look,
+build your own style over CHRT's vector source with `buildSources()` and keep
 `chrt.transformRequest()` for auth:
 
 ```typescript
@@ -76,22 +208,150 @@ const sources = buildSources({ region: 'NOAA_ENC' });
 // Each S-57 class (DEPARE, LIGHTS, BOYLAT, …) is a `source-layer` inside that one source.
 ```
 
-> S-101 portrayal is on the roadmap; today `chrt.style()` emits S-52.
+## Using CHRT without JavaScript
+
+> **Prefer codegen?** The whole HTTP surface is described by an OpenAPI 3.1 spec at
+> **https://api.chrt.co/openapi.json** — generate a typed Swift/Kotlin/Python/Go client
+> from it instead of hand-rolling the calls below.
+
+Native iOS/Android, Swift, Kotlin, Python and plain `curl` clients cannot call `chrt.style()` — it is
+a JavaScript function that builds a style object in-process. **Use the served style API instead.**
+It is two HTTP calls, no SDK required.
+
+**1. Mint a tile token** (valid for a short window; re-mint before `expires_at`):
+
+```bash
+curl -X POST https://api.chrt.co/v1/mint/tile-token \
+  -H "x-api-key: $CHRT_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"region":"NOAA_ENC"}'
+```
+
+```jsonc
+{
+  "token": "eyJhbGciOiJFUzI1NiIs…",  // ES256 JWT — do not log
+  "expires_at": 1752600000,          // unix seconds, matches the JWT `exp`
+  "kid": "chrt-tile-2026-04",
+  "build_tag": "…",
+  "region": "NOAA_ENC"
+}
+```
+
+**2. Fetch the style and the tiles** with that token as a Bearer credential:
+
+```bash
+curl https://tiles.chrt.co/v1/styles/NOAA_ENC/style.json?theme=day \
+  -H "Authorization: Bearer $TOKEN"
+
+curl https://tiles.chrt.co/v1/tiles/NOAA_ENC/12/1234/1543.mvt \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+The returned document is a standard MapLibre style — hand it to MapLibre Native (iOS/Android),
+`maplibre-gl`, or any renderer that speaks the style spec. Point your renderer's request transformer
+at the same `Authorization: Bearer` header so tile requests carry it too.
+
+The REST endpoints in the table below (`/v1/features`, `/v1/query`, `/v1/query/ahead`, `/v1/cells`,
+`/v1/coverage`) take the API key directly as `x-api-key` — no token minting needed.
+
+## Click-to-inspect (CHRTinteract)
+
+Wires click → decode onto any MapLibre / Mapbox GL map showing CHRT tiles. **Requires the Dev plan or
+above**; the entitlement is enforced server-side at attach time.
+
+```typescript
+const handle = await chrt.interact.attach(map, {
+  onInspect: (result) => {
+    // result.kind: 'navaid' | 'bridge' | 'area'
+    // e.g. a light characteristic decoded to "Fl(2+1) W 10s", sector arcs,
+    // bridge clearances, restriction lists, coordinates
+    console.log(result);
+  },
+});
+
+handle.detach();
+```
+
+With no `onInspect`/`onCandidates` callback, `attach()` renders a minimal built-in popup instead.
+Every result carries a `notice` — the non-SOLAS disclaimer, issuing-HO attribution and data
+currency. The built-in popup always renders them; **if you build your own UI, render them too.**
+
+A chart click rarely hits exactly one feature (a buoy on a channel over a depth area), so interact
+collects every candidate under the click, dedupes them across tile boundaries by S-57 identity, and
+orders them point → line → area with safety-critical classes first.
+
+```typescript
+// Headless candidate collection for any screen point or [lng, lat].
+const { candidates, select } = await chrt.interact.inspectAll(map, [-70.86, 42.02]);
+const result = await select(candidates[0]);
+
+// Decode a single feature you already have.
+const one = await chrt.interact.inspect(feature);
+
+// Resolve full S-57 source properties + cell provenance (edition, update number,
+// issue date). Metered against your `featureCalls` quota.
+const enriched = await chrt.interact.inspect(feature, { enrich: true });
+```
 
 ## Configuration
 
 ```typescript
 const chrt = new Chrt({
-  apiKey: 'chrt_live_...',
-  baseUrl: 'https://api.chrt.co/v1',     // default
-  retries: 2,                             // retry on 5xx, default 2
+  apiKey: process.env.CHRT_API_KEY!,
+  baseUrl: 'https://api.chrt.co/v1',      // default
+  retries: 2,                             // retry on 5xx + network errors, default 2
   region: 'NOAA_ENC',                     // default tile region
   tileBaseUrl: 'https://tiles.chrt.co',   // override for staging tiles
+  deviceId: 'my-app-install-uuid',        // required for offline.* — see below
+  manifestPath: './chrt-offline-manifest.json', // optional — enables offline budget + list()
+  vessel: { safetyDepthM: 3 },            // one safety depth for every depth-aware call
 });
 ```
 
+`new Chrt('chrt_sk_live_…')` is shorthand for `new Chrt({ apiKey: 'chrt_sk_live_…' })`.
+
+### `vessel` — one safety depth
+
+Set your draft-plus-margin once and every depth-aware call inherits it: `ahead()` and
+`alongRoute()` filter at it, and `style()` shades soundings and draws danger rings at it. An
+explicit per-call `safetyDepth` / `safetyContour` always wins.
+
+It is **client-side and per-instance, deliberately — not bound to your API key**. A consumer app
+has one key and many skippers with different boats; a key-scoped draft would give them all the
+same number. Construct a `Chrt` per user, or pass `safetyDepth` per call.
+
+**With no `vessel`, CHRT sends no depth at all** rather than guessing a draft — filtering on an
+invented one would silently drop real hazards.
+
+> Not yet reachable from the *served* style: `styleUrl()` takes `theme` + `symbols` only, so a
+> non-JS client cannot currently get per-user depth shading.
+
 ## API Reference
 
+**Which methods can a non-JS client use?** Everything under *HTTP endpoint* below is a plain REST
+call any language can make. Everything marked **JS-only** runs in-process and has no HTTP equivalent.
+
+| Method | HTTP endpoint | Notes |
+|---|---|---|
+| `chrt.features(opts)` | `GET /v1/features` | |
+| `chrt.query(opts)` | `GET /v1/query` | |
+| `chrt.ahead(opts)` | `GET /v1/query/ahead` | what's charted in a sector ahead |
+| `chrt.alongRoute(opts)` | `GET /v1/query/route` | same, for a planned passage |
+| `chrt.alongRouteIter(opts)` | `GET /v1/query/route` | auto-paginates |
+| `chrt.cells.list(opts?)` | `GET /v1/cells` | |
+| `chrt.cells.get(id)` | `GET /v1/cells/{id}` | |
+| `chrt.coverage.list(opts?)` | `GET /v1/coverage` | |
+| `chrt.coverage.forRoute(opts)` | `GET /v1/coverage/route` | which cells a passage needs |
+| `chrt.warmTiles(region?)` | `POST /v1/mint/tile-token` | |
+| `chrt.styleUrl(opts?)` | `GET {tileBaseUrl}/v1/styles/{region}/style.json` | mints first |
+| `chrt.fetchStyle(opts?)` | same, then fetches it | |
+| `chrt.interact.entitlement()` | `POST /v1/interact/entitlement` | |
+| `chrt.style(opts?)` | — | **JS-only** — local generator |
+| `chrt.transformRequest(opts?)` | — | **JS-only** — returns a closure |
+| `chrt.tiles.tileUrl(z, x, y)` | — | **JS-only** — string builder |
+| `chrt.interact.attach/inspectAll` | — | **JS-only** — needs a GL JS map |
+| `chrt.featuresIter` / `cellsIter` | — | **JS-only** — async iterators |
+
 ### `chrt.features(options)`
 Query GeoJSON features by bounding box.
 
@@ -99,8 +359,11 @@ Query GeoJSON features by bounding box.
 |--------|------|----------|-------------|
 | `bbox` | `[w, s, e, n]` | ✓ | Bounding box |
 | `layer` | `string` | | S-57 layer code (e.g. `DEPARE`) |
-| `limit` | `number` | | Max results (default 100) |
+| `limit` | `number` | | Max results (default 100, max 1000) |
 | `offset` | `number` | | Pagination offset |
+| `signal` | `AbortSignal` | | |
+
+Returns a GeoJSON `FeatureCollection` with `total_count`, `limit` and `offset` alongside `features`.
 
 ### `chrt.query(options)`
 Spatial proximity search around a point.
@@ -108,37 +371,130 @@ Spatial proximity search around a point.
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `point` | `[lng, lat]` | ✓ | Centre point |
-| `radius` | `number` | | Radius in metres (default 1000) |
+| `radius` | `number` | | Radius in metres (default 500, clamped 1–50 000) |
 | `layer` | `string` | | Comma-separated layer codes |
-| `limit` | `number` | | Max results |
+| `limit` | `number` | | Max results (default 50, max 500) |
+| `signal` | `AbortSignal` | | |
+
+Returns a `QueryResponse`: a GeoJSON `FeatureCollection` whose `properties` carry `layer`, `cell_id`
+and `distance_m` (geodesic metres from `point`), plus a `query` block echoing what the server
+**actually applied after clamping** — read `res.query.radius_m` to see that `radius: 90000` silently
+became `50000`. Unlike `chrt.features()`, this endpoint is **not paginated**: it returns no `offset`,
+so widen `radius` rather than paging.
+
+### `chrt.ahead(options)`
+The fan-ahead query — the significant features in a sector from a point along a bearing. Built for
+the position-plus-COG case: a craft with a heading but no planned route.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `point` | `[lng, lat]` | ✓ | Origin |
+| `bearing` | `number` | ✓ | Degrees true; out-of-range values normalise |
+| `arc` | `number` | | **Full** sector width centred on `bearing` (default 90 — `arc: 60` sweeps ±30°) |
+| `range` | `number` | | Metres (default 5000, clamped 1–50 000) |
+| `rangeNm` | `number` | | Nautical miles — mutually exclusive with `range` (passing both throws) |
+| `safetyDepth` | `number` | | Filters out only what is **known** to be deeper |
+| `layer` | `string` | | Defaults to CHRT's significant-feature set |
+| `limit` | `number` | | Default 50, max 500 |
+
+Each feature carries `distance_m`, `bearing_deg`, `least_depth_m` and `depth_clearance_m` (negative =
+shallower than your `safetyDepth`).
+
+> **Facts that sort, never a verdict.** There is deliberately no severity score and no `safe` flag —
+> a risk model is a navigation-grade claim. You sort; CHRT ranks nothing.
+>
+> **An empty result is not an all-clear.** Zero features in covered water and zero features because
+> CHRT has no cells there are different answers. Every response carries a `coverage` block
+> (`covered`, `covered_fraction`, `cells`) — **check `coverage.covered` before telling a user
+> anything.**
 
 ### `chrt.cells.list(options?)`
 List available ENC cells.
 
-### `chrt.cells.get(cellId)`
-Get metadata for a specific cell.
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `source` | `string` | | Chart-source **id**, e.g. `'NOAA_ENC'` — *not* the agency name `'NOAA'`, which matches nothing and returns an empty list rather than an error. `chrt.coverage.list()` enumerates the ids. |
+| `status` | `string` | | e.g. `'CURRENT'`. Case-insensitive. |
+| `scaleBand` | `ScaleBand` | | `'Overview'` \| `'General'` \| `'Coastal'` \| `'Approach'` \| `'Harbor'`. Matched **case-sensitively** — `'harbor'` matches nothing. |
+| `bbox` | `[w, s, e, n]` | | Cells whose bounds *intersect* this box |
+| `limit` | `number` | | Max results (default 100, max 1000) |
+| `offset` | `number` | | Pagination offset |
+| `signal` | `AbortSignal` | | |
 
-### `chrt.style(opts?)`
-Returns a ready-to-use MapLibre/Mapbox GL **S-52** style object. Options: `palette`
-(`'DAY'` | `'DUSK'` | `'NIGHT'`), `region`, `depthUnits`, plus the other atlas style options.
+Returns `{ cells, total_count, limit, offset }`. Use `chrt.cellsIter(options?)` to page automatically.
 
-### `chrt.transformRequest(opts?)`
-Returns a `transformRequest` that mints a short-lived tile JWT from your API key and attaches
-it as `Authorization: Bearer` on `tiles.chrt.co` requests only. Pass `{ region }` to override
-the default region.
+### `chrt.cells.get(cellId)`
+Get metadata for a specific cell. Takes the id positionally: `chrt.cells.get('US5MA11M')`.
+Returns a `CellDetail`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cell_id` | `string` | e.g. `'US5MA11M'` |
+| `title` | `string \| null` | Chart title |
+| `chart_source` | `string` | Source id, e.g. `'NOAA_ENC'` |
+| `status` | `string` | e.g. `'CURRENT'` |
+| `scale` | `number \| null` | Compilation scale denominator |
+| `scale_band` | `string \| null` | Usage band — a `ScaleBand` name, e.g. `'Harbor'` |
+| `edition` · `update_number` · `issue_date` | | **Data currency** — the fields that say how current the chart is |
+| `bbox_north` · `bbox_south` · `bbox_east` · `bbox_west` | `number \| null` | Bounds in decimal degrees (WGS 84), `null` if the issuing office recorded none. Written as a group, so in practice all four are set or all four are `null`. |
+| `last_checked_at` | `string \| null` | ISO 8601 — when CHRT last checked the issuing office's catalogue for this cell. Freshness of the *check*, not of the chart; use `edition` / `update_number` / `issue_date` for chart currency. |
+
+> **Bounds are flat here and on `coverage.forRoute()` — one shape across the API.** Up to
+> 0.9.2 the SDK declared these flat fields while `/v1/cells` alone returned a nested `bbox`
+> object, so `cell.bbox_north` typechecked and read `undefined` on every response. The
+> endpoint was the outlier; it now sends what this type has always declared, and reading
+> `cell.bbox_north` works against any deployed CHRT API.
+
+### `chrt.coverage.list(options?)`
+List the chart sources available to your key. Options: `country` (e.g. `'US'`), `source`.
+Returns `{ sources, total_cells }`, where each source carries `source` (the **id** you filter cells
+by, e.g. `'NOAA_ENC'`), `agency` (the issuing office's display name, e.g. `'NOAA'`), `cell_count` and
+`scale_bands` (counts keyed by band name). This is the endpoint that tells you which `source` ids are
+valid — passing an agency name anywhere else silently matches nothing.
+
+### `chrt.style(opts?)` — **JS-only**
+Returns a ready-to-use MapLibre/Mapbox GL **S-52** style object. Generated locally: no network, works
+offline, and **does not apply a custom style bound to your key**. Options: `palette`
+(`'DAY' | 'DUSK' | 'NIGHT'`), `symbolSet`, `region`, `depthUnits`, `safetyContour`, `chartMode`, plus
+the other atlas style options. Non-JS clients want `styleUrl()` instead.
+
+### `chrt.styleUrl(opts?)`
+URL of the **served** S-52 style — the CHRTstyle Style API at
+`{tileBaseUrl}/v1/styles/{region}/style.json`. `async`: it pre-mints the tile token so the style
+request (which MapLibre does not retry) carries auth. Options: `theme`
+(`'day' | 'dusk' | 'night'`), `symbols`. Always pair with `transformRequest()`.
+
+The served document honours the CHRTstyle custom style bound to your key (a **Dev+** feature; Free
+keys and keys with no bound style get the default themes). This is the style path for any client that
+can't run `chrt.style()`.
+
+### `chrt.fetchStyle(opts?)`
+Fetches the served style as a MapLibre style object. Same options as `styleUrl()`, plus `signal`.
+Prefer it over `styleUrl()` when you want to inspect or mutate the document, or when you can't use
+`transformRequest()` for the style request itself. Throws `ChrtError` on failure; does not retry.
+
+### `chrt.transformRequest(opts?)` — **JS-only**
+Returns a `transformRequest` closure that attaches the tile JWT as `Authorization: Bearer` on
+`tiles.chrt.co` **tile and served-style** requests only. Sprite, glyph and third-party URLs pass
+through untouched. Pass `{ region }` to override the default region.
 
 ### `chrt.warmTiles(region?)`
-Pre-mints the tile token so you can surface auth errors (e.g. `region_not_licensed`,
-`tile_quota_exceeded`) before the map loads. Optional — `transformRequest()` warms the cache
-on its own.
+Pre-mints the tile token so you can surface auth errors (`region_not_licensed`,
+`tile_quota_exceeded`, …) before the map loads. Optional — `transformRequest()` warms the cache on
+its own.
+
+### `chrt.tiles.tileUrl(z, x, y)` — **JS-only**
+Concrete vector tile URL at `tiles.chrt.co` for one tile. Prefer `chrt.style()` / `chrt.styleUrl()`,
+which wire the source for you.
 
-### `chrt.tiles.tileUrl(z, x, y)`
-Single vector tile URL template at `tiles.chrt.co`. Prefer `chrt.style()`, which wires the
-source for you.
+### `chrt.interact.*`
+See [Click-to-inspect](#click-to-inspect-chrtinteract). `attach(map, opts?)` and
+`inspectAll(map, point, opts?)` need a GL JS map instance; `inspect(feature, opts?)` decodes locally
+but checks entitlement over HTTP first.
 
-### `chrt.styleUrl()` · `chrt.tiles.groups()` — deprecated
-CHRT serves no remote `style.json` — use `chrt.style()`. Tilesets were consolidated to one
-source per region (2026-04), so the per-group catalogue is legacy.
+### `chrt.tiles.groups()` — deprecated
+Tilesets were consolidated to one source per region (2026-04). The route no longer exists — calling
+it fails with `ChrtError` 404. Use `chrt.style()` or `chrt.styleUrl()`.
 
 ## Error Handling
 
@@ -154,10 +510,21 @@ try {
 }
 ```
 
+Typed errors by area: `ChrtError` (REST), `TileTokenError` (minting — `invalid_api_key`,
+`region_not_licensed`, `tile_quota_exceeded`, `region_not_available`, `feature_flag_disabled`,
+`network_error`, `unexpected_response`), `InteractError` (`interact_not_enabled` — includes the
+current `plan` and an upgrade hint — `invalid_api_key`, `missing_scope`, `enrich_failed`,
+`unknown_layer`, `network_error`, `unexpected_response`), and `OfflineError` (below).
+
 ## Offline Downloads (CHRToffline)
 
 Download MBTiles bundles for offline rendering. Bundles are SHA-256 verified before commit. Interrupted downloads resume from a `.partial` sidecar file.
 
+**Requires the Pro plan or above**, enforced server-side at mint time — Free and Dev keys get
+`OfflineError` code `offline_requires_pro_plan`. The key also needs the `offline:download`
+scope, which is checked **before** the plan: a key without it gets `offline_not_enabled`
+regardless of tier, so add the scope first or the plan refusal never surfaces.
+
 **Runtime support in v1:** Node 18+, Bun, Deno. Browser and React Native are deferred to a follow-up.
 
 ```typescript
@@ -211,7 +578,8 @@ try {
       case 'download_corrupt': console.log('SHA mismatch'); break;
       case 'network_interrupted': console.log('resume later'); break;
       case 'coverage_denied': console.log('region not licensed'); break;
-      case 'offline_not_enabled': console.log('enable use_offline on this API key'); break;
+      case 'offline_requires_pro_plan': console.log('CHRToffline needs Pro+ — chrt.co/pricing'); break;
+      case 'offline_not_enabled': console.log('add the offline:download scope to this API key'); break;
     }
   }
 }