@chrtco/sdk 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@chrtco/sdk` will be documented in this file.
+
+## [0.6.0] — 2026-04-27
+- **New sub-export `@chrtco/sdk/atlas/browser`** — S-52 atlas helpers for browser-side rendering. Previously lived in the React app's `src/lib/atlas/` and was internal-only; now part of the SDK so external consumers can drive map styling consistently with the platform.
+- **`OfflineError.detail.level` (`"team" | "key"`)** — `budget_exceeded` errors from `mint-offline-token` now carry a `level` field on `error.detail` so consumers can branch their messaging between per-key caps ("raise this key's storage cap") and per-team caps ("upgrade your team plan"). `team_used_bytes` is also surfaced on team-level refusals so dashboards can show usage context. Existing `budget_bytes` / `required_bytes` / `over_by_bytes` keys are unchanged.
+- **Internal**: `@maplibre/maplibre-gl-style-spec` declared as a devDep (was a runtime dep but only needed at build/typecheck time).
+
+## [0.5.0] — 2026-04-23
+- **CHRToffline** — download MBTiles bundles for offline rendering:
+  - `chrt.offline.list()`, `chrt.offline.download(region, opts)`, `chrt.offline.remove(region, opts)`, `chrt.offline.heartbeat(opts?)`, `chrt.offline.setStorageBudget(bytes, fs)`
+  - HTTP Range-based download resumption via `.partial` sidecar file
+  - SHA-256 verification before rename to final path
+  - `AbortSignal` support; interrupted downloads leave `.partial` on disk for resume
+  - Progress callback throttled to max(1 MB, 1%) boundaries; always fires at 0 and completion
+  - Optional local manifest (`ChrtConfig.manifestPath`) for budget enforcement and device-state tracking
+  - Typed errors via `OfflineError` with `code` discriminator (`budget_exceeded`, `download_corrupt`, `network_interrupted`, `coverage_denied`, `quota_exceeded`, `offline_not_enabled`, `sha_missing`, `missing_device_id`, `missing_manifest_path`, `region_not_available`, `invalid_api_key`, `unexpected_response`)
+- **New config options**: `deviceId` (required for `offline.*`), `manifestPath` (optional)
+- **New sub-export `@chrtco/sdk/node`**: `nodeFileSystemAdapter()` — Node 18+ implementation of `FileSystemAdapter` (core remains zero runtime deps)
+- **Runtime target v1**: Node, Bun, Deno only. React Native and browser support deferred to a follow-up phase.
+- **Internal**: SDK mints its own short-lived offline JWTs; customers never see them. Mint + offline traffic routes through `api.chrt.co/v1/mint/offline-token` and `api.chrt.co/v1/offline/*` (new `api-worker` proxy).
+
+## [0.4.0] — 2026-03-27 (republish)
+- **Coverage endpoint** — `chrt.coverage.list()` returns chart sources by country with cell counts
+- **Webhook event types** — discriminated-union types for `cell.updated`, `cell.new`, `cell.deleted` payloads; `parseWebhook()` runtime helper
+- **Async auto-pagination** — `chrt.featuresIter()` and `chrt.cellsIter()` return `AsyncIterable` for `for-await-of` loops
+- **AbortController support** — all request methods accept `signal?: AbortSignal` for cancellation
+
+## [0.3.2] — 2026-03-27
+- Fixed CI publish pipeline (removed --provenance flag incompatible with private repos)
+
+## [0.3.1] — 2026-03-27
+- Improved README with clearer quick-start examples and configuration options
+
+## [0.3.0] — 2026-03-26
+- Reordered package exports for bundler compatibility (types first)
+- Updated docs with Mapbox GL JS / MapLibre integration examples
+
+## [0.2.0] — 2026-02-01
+- Added Feature API endpoint (`chrt.features()`) with bbox, layer filtering, pagination
+- Added Spatial Query endpoint (`chrt.query()`) with point + radius search
+- Added Cell Metadata endpoints (`chrt.cells.list()`, `chrt.cells.get()`)
+
+## [0.1.0] — 2026-01-15
+- Initial release
+- Chrt client with API key authentication
+- Tiles endpoints: `styleUrl()`, `tileUrl()`, `groups()`
+- `transformRequest()` helper for Mapbox GL / MapLibre
+- `ChrtError` typed error class
+- Configurable retries on 5xx responses

package/README.md

@@ -121,6 +121,75 @@ try {
 }
 ```
 
+## Offline Downloads (CHRToffline)
+
+Download MBTiles bundles for offline rendering. Bundles are SHA-256 verified before commit. Interrupted downloads resume from a `.partial` sidecar file.
+
+**Runtime support in v1:** Node 18+, Bun, Deno. Browser and React Native are deferred to a follow-up.
+
+```typescript
+import { Chrt } from '@chrtco/sdk';
+import { nodeFileSystemAdapter } from '@chrtco/sdk/node';
+
+const chrt = new Chrt({
+  apiKey: process.env.CHRT_API_KEY!,
+  // Required for offline.* — generate once at first launch, persist per
+  // install. Echoed into the offline JWT + heartbeat for device-level usage
+  // tracking.
+  deviceId: 'my-app-install-uuid',
+  // Optional — enables budget enforcement + `list()` of local state. If
+  // unset, budget is not enforced and `setStorageBudget()` throws.
+  manifestPath: './chrt-offline-manifest.json',
+});
+
+const fs = nodeFileSystemAdapter();
+
+// Optional: cap total local storage across all regions.
+await chrt.offline.setStorageBudget(10 * 1024 ** 3, fs); // 10 GB
+
+// List what you're licensed to download.
+const regions = await chrt.offline.list();
+
+// Download a region. Resumes from a partial if one exists.
+await chrt.offline.download('NOAA_ENC', {
+  path: './noaa.mbtiles',
+  fs,
+  onProgress: (p) => console.log(`${p.fraction * 100}%`),
+});
+
+// Remove a region (deletes the file + updates manifest + heartbeats).
+await chrt.offline.remove('NOAA_ENC', { path: './noaa.mbtiles', fs });
+
+// Manual heartbeat — call at app launch + every 24h while running.
+await chrt.offline.heartbeat({ fs }); // derives regions + total from manifest
+```
+
+### Typed offline errors
+
+```typescript
+import { OfflineError } from '@chrtco/sdk';
+
+try {
+  await chrt.offline.download('NOAA_ENC', { path: './noaa.mbtiles', fs });
+} catch (e) {
+  if (e instanceof OfflineError) {
+    switch (e.code) {
+      case 'budget_exceeded': console.log(e.detail); break;
+      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;
+    }
+  }
+}
+```
+
+### Notes
+
+- The SDK mints its own short-lived JWTs internally. You never see them.
+- Heartbeats in v1 are manual — auto-scheduling comes in a later phase.
+- A budget smaller than current usage will not auto-prune; it only refuses new downloads. Use `remove()` explicitly.
+
 ## License
 
 MIT