@chrtco/sdk 0.10.3 → 0.10.5

package/README.md

@@ -366,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 | |
@@ -618,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.

package/dist/index.cjs

@@ -96,6 +96,7 @@ __export(index_exports, {
   TileAuth: () => TileAuth,
   TileTokenError: () => TileTokenError,
   WATER_BODY_LAYER_GROUPS: () => WATER_BODY_LAYER_GROUPS,
+  WeatherEndpoint: () => WeatherEndpoint,
   applyChrtSymbolSet: () => applyChrtSymbolSet,
   applyColorTheme: () => applyColorTheme,
   applyCustomStyleSettings: () => applyCustomStyleSettings,
@@ -647,6 +648,79 @@ var CellsEndpoint = class {
   }
 };
 
+// src/endpoints/weather.ts
+var WeatherEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Observed conditions from the nearest reporting NOAA NDBC station.
+   *
+   * A **measurement, not a forecast**, and not live — most buoys report hourly
+   * and the median observation is around 40 minutes old. `observed.ageMinutes`
+   * is on every response and should be displayed: a readout that looks current
+   * but is 90 minutes stale is worse than one that says so.
+   *
+   * `unavailable` names every field the station did not report, so absence is
+   * stated rather than inferred from a missing key.
+   */
+  async conditions(options) {
+    return this.http.request(
+      "/weather/conditions",
+      {
+        lat: options.lat,
+        lon: options.lon,
+        units: options.units,
+        station: options.station
+      },
+      options.signal
+    );
+  }
+  /**
+   * Active NWS marine warnings for the zone — Small Craft Advisory, Gale,
+   * Storm, Hurricane Force Wind, Special Marine Warning. Most severe first.
+   *
+   * Its own call, so warnings can be re-checked cheaply (~60 s) without pulling
+   * a forecast you already have.
+   *
+   * **`expires` and `ends` are different.** `expires` is when the *bulletin*
+   * lapses — alerts are usually re-issued before then. `ends` is when the
+   * *hazard* is expected to be over. They are routinely hours apart, so
+   * describe the hazard with `ends` and use `expires` only to decide when to
+   * re-fetch.
+   *
+   * Display `instruction` verbatim: it is NWS's own advice to mariners.
+   */
+  async alerts(options) {
+    return this.http.request(
+      "/weather/marine-alerts",
+      { lat: options.lat, lon: options.lon, zone: options.zone },
+      options.signal
+    );
+  }
+  /**
+   * The NWS marine zone forecast — U.S. coastal and Great Lakes waters.
+   *
+   * 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.
+   * Flattening them into an hourly series invents resolution the data does not
+   * have.
+   *
+   * `expires` is the forecast's **own** stated validity, taken from the
+   * bulletin, not a TTL CHRT invented. `source.productId` identifies the
+   * upstream NWS product, so you can verify CHRT against NOAA directly.
+   *
+   * Offshore zones are not yet supported and fail with `501`.
+   */
+  async forecast(options) {
+    return this.http.request(
+      "/weather/marine-forecast",
+      { lat: options.lat, lon: options.lon, zone: options.zone },
+      options.signal
+    );
+  }
+};
+
 // src/endpoints/coverage.ts
 var METRES_PER_NAUTICAL_MILE = 1852;
 var CoverageEndpoint = class {
@@ -726,6 +800,37 @@ var FeaturesEndpoint = class {
   }
 };
 
+// src/endpoints/search.ts
+var SearchEndpoint = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Search the gazetteer.
+   *
+   * `near` biases ranking and never filters — "Newport" is Rhode Island, Oregon
+   * *and* California, and all three come back with the nearest first. `bbox`
+   * does filter.
+   */
+  async find(options) {
+    return this.http.request(
+      "/search",
+      {
+        q: options.q,
+        near: options.near ? `${options.near[0]},${options.near[1]}` : void 0,
+        bbox: options.bbox ? options.bbox.join(",") : void 0,
+        kind: options.kind,
+        // Both spellings are accepted server-side; the SDK sends the
+        // comma-joined form so one array maps to one query parameter.
+        layer: Array.isArray(options.layer) ? options.layer.join(",") : options.layer,
+        limit: options.limit,
+        offset: options.offset
+      },
+      options.signal
+    );
+  }
+};
+
 // src/endpoints/query.ts
 var METRES_PER_NAUTICAL_MILE2 = 1852;
 var QueryEndpoint = class {
@@ -28582,6 +28687,14 @@ var Chrt = class {
   cells;
   /** Coverage data — list available chart sources */
   coverage;
+  /**
+   * CHRTweather — NOAA-backed marine weather: observed conditions, active
+   * warnings, and the NWS zone forecast. U.S. waters only, and requires the
+   * `weather:read` scope on your key — a chart key does not carry it.
+   *
+   * An empty result from any of these never means calm water.
+   */
+  weather;
   /**
    * CHRToffline — download MBTiles bundles for offline use.
    * Requires `deviceId` in config. Manifest-based budget enforcement
@@ -28595,6 +28708,7 @@ var Chrt = class {
    */
   interact;
   featuresEp;
+  searchEp;
   queryEp;
   http;
   tileAuth;
@@ -28613,7 +28727,9 @@ var Chrt = class {
     this.tiles = new TilesEndpoint(this.http, this.tileAuth, tileOpts);
     this.cells = new CellsEndpoint(this.http);
     this.coverage = new CoverageEndpoint(this.http);
+    this.weather = new WeatherEndpoint(this.http);
     this.featuresEp = new FeaturesEndpoint(this.http);
+    this.searchEp = new SearchEndpoint(this.http);
     this.queryEp = new QueryEndpoint(this.http);
     this.offline = new OfflineEndpoint(this.http, config.deviceId, config.manifestPath);
     this.interact = new InteractClient(this.http);
@@ -28623,6 +28739,32 @@ var Chrt = class {
   async features(options) {
     return this.featuresEp.list(options);
   }
+  /**
+   * CHRTsearch — find charted places by name.
+   *
+   * The only CHRT surface addressed by NAME rather than by space or identifier.
+   * Text in, a small ranked list of named charted places out.
+   *
+   * ```ts
+   * const { results } = await chrt.search({ q: "cutty harbor", near: [-70.93, 41.42] });
+   * // -> [{ name: "Cuttyhunk Harbor Channel", class: "Fairway", kind: "place", ... }]
+   * ```
+   *
+   * Three things worth knowing before wiring it to a text field:
+   *
+   * 1. **Pass `near`.** It biases ranking and never filters. "Newport" is
+   *    Rhode Island, Oregon *and* California; without `near` the first row is
+   *    the wrong Newport most of the time.
+   * 2. **It is metered separately** from `features()` — exhausting one does not
+   *    affect the other. Sized for a typeahead, and not gated by tier.
+   * 3. **An empty `results` array is not proof a place does not exist.** If the
+   *    response carries a `coverage` block, CHRT holds no charts at that
+   *    position and the search could not run there. That is a different answer
+   *    from "nothing matched", and neither means the water is clear.
+   */
+  async search(options) {
+    return this.searchEp.find(options);
+  }
   /** Spatial proximity query around a point */
   async query(options) {
     return this.queryEp.nearby(options);
@@ -28949,6 +29091,7 @@ var Chrt = class {
   TileAuth,
   TileTokenError,
   WATER_BODY_LAYER_GROUPS,
+  WeatherEndpoint,
   applyChrtSymbolSet,
   applyColorTheme,
   applyCustomStyleSettings,