@chrtco/sdk 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to `@chrtco/sdk` will be documented in this file.
+
+## [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

package/dist/fs-adapter-D5iwdb1Q.d.cts

@@ -0,0 +1,33 @@
+/**
+ * Pluggable filesystem surface used by the offline endpoints.
+ *
+ * The core SDK is zero-dependency and can't import `node:*`. Callers bring
+ * their own adapter — `@chrtco/sdk/node` ships the Node 18+ implementation;
+ * future adapters (Bun/Deno-native, React Native, browser-OPFS) slot in the
+ * same shape without touching the endpoint code.
+ *
+ * Paths are plain strings. All methods are async. Streaming SHA-256 lives on
+ * the adapter so each runtime can use its native streaming digest primitive
+ * (Node: `crypto.createHash`; browser-OPFS: chunked `SubtleCrypto` etc.).
+ */
+interface FileSystemAdapter {
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<{
+        size: number;
+    }>;
+    /** Returns a WritableStream for the given path. `append: true` opens in append mode; otherwise the file is truncated. */
+    writeStream(path: string, opts?: {
+        append?: boolean;
+    }): Promise<WritableStream<Uint8Array>>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    /** Compute SHA-256 of the file at `path`. Lowercase hex. Must stream for large files. */
+    sha256(path: string): Promise<string>;
+}
+
+export type { FileSystemAdapter as F };

package/dist/fs-adapter-D5iwdb1Q.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pluggable filesystem surface used by the offline endpoints.
+ *
+ * The core SDK is zero-dependency and can't import `node:*`. Callers bring
+ * their own adapter — `@chrtco/sdk/node` ships the Node 18+ implementation;
+ * future adapters (Bun/Deno-native, React Native, browser-OPFS) slot in the
+ * same shape without touching the endpoint code.
+ *
+ * Paths are plain strings. All methods are async. Streaming SHA-256 lives on
+ * the adapter so each runtime can use its native streaming digest primitive
+ * (Node: `crypto.createHash`; browser-OPFS: chunked `SubtleCrypto` etc.).
+ */
+interface FileSystemAdapter {
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<{
+        size: number;
+    }>;
+    /** Returns a WritableStream for the given path. `append: true` opens in append mode; otherwise the file is truncated. */
+    writeStream(path: string, opts?: {
+        append?: boolean;
+    }): Promise<WritableStream<Uint8Array>>;
+    rename(from: string, to: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    mkdir(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    /** Compute SHA-256 of the file at `path`. Lowercase hex. Must stream for large files. */
+    sha256(path: string): Promise<string>;
+}
+
+export type { FileSystemAdapter as F };