@chrtco/sdk 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@chrtco/sdk` will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- **Render-mode lever on the Style API** (`sail#2`): `StyleUrlOptions.mode` /
+  `OfflineFetchStyleOptions.mode` — `"continuous"` (default) or
+  `"chart:{band}"` (`chart:Overview | chart:General | chart:Coastal |
+  chart:Approach | chart:Harbor`) — threads `?mode=` to the served style
+  routes (online `style.json` and offline `/v1/offline/styles/{region}`),
+  which lock the portrayal to one scale band with cascade fallback: the
+  served twin of the app's Map Mode toggle, now available to every API
+  consumer, online and offshore. New exports: `ChrtStyleMode`,
+  `CHRT_STYLE_MODES`, `normalizeStyleMode()`, `styleModeBand()`.
+  `OfflineStyleResponse.mode` echoes the resolved mode. Servers reject
+  invalid modes AND unknown style-route query params with typed 400s
+  (`invalid_mode` / `unknown_param`) instead of silently serving the
+  default document.
+- **`OfflineFetchStyleOptions.symbols`** — the offline style route has
+  accepted `?symbols=s52|s101|chrt|raster` all along, but
+  `chrt.offline.fetchStyle()` had no way to send it, so native clients could
+  only ever fetch the default `s52` offline style. Now threaded through
+  (omitted → worker default `s52`), typed with the same `ChrtSymbolSet` as
+  the online `StyleUrlOptions.symbols`. `OfflineStyleResponse.symbols` types
+  the echoed set the worker already returns.
 - **Served styles now render in MapLibre Native as shipped.** Every generated
   style begins with a `chrt-background` layer (S-52 NODTA backdrop per
   palette) — previously native renderers drew a black void and

package/README.md

@@ -243,7 +243,8 @@ curl -X POST https://api.chrt.co/v1/mint/tile-token \
 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 \
+# --compressed matters: see "Tiles are gzipped" below.
+curl --compressed https://tiles.chrt.co/v1/tiles/NOAA_ENC/12/1234/1543.mvt \
   -H "Authorization: Bearer $TOKEN"
 ```
 
@@ -251,6 +252,29 @@ The returned document is a standard MapLibre style — hand it to MapLibre Nativ
 `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.
 
+### Tiles are gzipped — send `Accept-Encoding: gzip`
+
+Tiles are stored gzip-compressed in the PMTiles archive, and the edge negotiates per request:
+ask for `gzip` and you get gzip (`content-encoding: gzip` on the response); ask for `identity`,
+or send no `Accept-Encoding` at all, and you get the uncompressed bytes.
+
+**This changes tile-budget arithmetic by 2–2.5×.** MapLibre GL JS, MapLibre Native, every browser,
+and this SDK all send `Accept-Encoding: gzip` automatically — the compressed figure is what your
+users actually transfer. **Plain `curl` sends no `Accept-Encoding` at all**, so `curl -o tile.mvt`
+measures the *uncompressed* size. Use `curl --compressed` (as above), or read `content-encoding`
+off the response, before sizing a cache, a bundle, or a data plan.
+
+Reference measurement, prod `NOAA_ENC`, 2026-07-27, tile `z11/620/757` (Boston):
+
+| `Accept-Encoding` | Bytes on the wire |
+|---|---|
+| *(absent)* / `identity` | 1,152,506 B (1.10 MB) |
+| `gzip` | 462,273 B (451 KB) |
+
+Tile size tracks **feature density** far more than zoom — a harbor tile over a dense port dwarfs an
+offshore tile at the same zoom, and a tile with no data returns `204` with no body at all. Sample a
+spread of tiles across your own area of operations rather than extrapolating from one.
+
 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.
 
@@ -342,6 +366,9 @@ call any language can make. Everything marked **JS-only** runs in-process and ha
 | `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.weather.conditions(opts)` | `GET /v1/weather/conditions` | observed at sea (NDBC); needs `weather:read` |
+| `chrt.weather.alerts(opts)` | `GET /v1/weather/marine-alerts` | active NWS warnings; needs `weather:read` |
+| `chrt.weather.forecast(opts)` | `GET /v1/weather/marine-forecast` | NWS zone forecast; needs `weather:read` |
 | `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 | |
@@ -594,3 +621,55 @@ try {
 ## License
 
 MIT
+
+## CHRTweather (marine weather)
+
+NOAA-backed marine weather on the same client and the same key. **U.S. waters only**, and every
+call needs the **`weather:read` scope** — a chart key does not carry it implicitly, so ask CHRT to
+enable it. Without it you get `403 weather_not_entitled`, which retrying will never fix.
+
+```ts
+// Observed — a measurement from the nearest buoy, NOT live.
+const now = await chrt.weather.conditions({ lat: 41.0, lon: -71.1 });
+console.log(now.observed.ageMinutes);       // display this: median ~40 min old
+console.log(now.conditions.windSpeed);      // undefined => NOT REPORTED, not calm
+console.log(now.unavailable);               // what this station did not report
+
+// Warnings — poll these cheaply (~60 s) without pulling a forecast.
+const { alerts } = await chrt.weather.alerts({ lat: 42.5, lon: -70.3 });
+
+// Forecast — the NWS zone narrative.
+const fc = await chrt.weather.forecast({ zone: "LEZ166" });
+for (const p of fc.periods) console.log(p.label, p.text);
+```
+
+Three rules govern reading any of it. They are the difference between a useful readout and a
+dangerous one.
+
+**An empty result never means calm water.** No alerts in force, no buoy in range, no marine zone at
+this position — each means *we do not know* or *nothing is posted*, never *conditions are good*.
+There is deliberately no `safe` or `status` field to bind a green tick to. Render "no warnings in
+force", never "conditions are good".
+
+**Absent is not zero.** A measurement a station did not report, or a phrase the forecast parser
+could not read, is omitted rather than defaulted — `conditions.windSpeed === undefined` means the
+buoy sent NDBC's `MM` missing-value sentinel, and rendering that as `0 kn` puts a false calm on a
+sailing display. `"winds less than 10 knots"` gives you `maxKn` and no `minKn` for the same reason.
+
+**On the forecast, `text` is authoritative.** The structured `wind` / `seas` / `swell` fields are
+parsed from NWS's own sentence, and where they disagree the text wins — some content exists only
+there. Periods are NWS's own and are neither hourly nor uniform (`OVERNIGHT`, `TUE NIGHT`,
+`WED NIGHT THROUGH THU NIGHT`); a single period can span days, so do not flatten them into an
+hourly series.
+
+Two field-level traps worth naming:
+
+- **`expires` vs `ends`** on an alert. `expires` is when the *bulletin* lapses; `ends` is when the
+  *hazard* passes. Routinely hours apart. Describe the hazard with `ends`.
+- **`seas.minFt`/`maxFt` vs `seas.occasionalFt`.** The range is the mean of the highest **1/3**;
+  `occasionalFt` (Great Lakes only) is the mean of the highest **1/10**. In *"Waves 2 to 4 ft …
+  occasionally to 8 ft"* the 8 ft wave is the one that knocks a small boat down — never average it
+  into the range.
+
+CHRT is **not** the issuing authority. Every response carries `attribution` and `disclaimer`;
+display them, and always consult NWS and VHF broadcasts.