@chrtco/sdk 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,3 +1,108 @@
+import { F as FileSystemAdapter } from './fs-adapter-D5iwdb1Q.cjs';
+
+/**
+ * Pure helper: take an online MapLibre style and rewrite the named region's
+ * vector source to point at a local MBTiles file. Layers, paint, layout,
+ * glyphs, and sprite are untouched.
+ *
+ * This is the JS counterpart of the offline-worker's server-side rewriter
+ * (see `cloudflare/offline-worker/src/common.ts:rewriteStyleSources`).
+ * Customers can either:
+ *
+ *   1. Fetch a pre-baked offline style from the worker via
+ *      `chrt.offline.fetchStyle(region, opts)` — recommended for native
+ *      MapLibre clients (iOS/Android/desktop) that don't have the JS atlas
+ *      available.
+ *
+ *   2. Generate the online style themselves (e.g. via the React app's
+ *      `src/lib/atlas/style-generator.ts`) and call `buildOfflineStyle()`
+ *      locally — recommended for JS/web SDK consumers who already use the
+ *      atlas at runtime.
+ *
+ * Both paths produce equivalent output.
+ */
+/**
+ * MapLibre style specification (subset). Matches the JSON shape MapLibre GL
+ * JS, MapLibre Native iOS/Android, and the MapLibre style spec all consume.
+ * Customers who want full TypeScript style typing should reference
+ * `@maplibre/maplibre-gl-style-spec.StyleSpecification` directly.
+ */
+interface MapLibreStyle {
+    version: number;
+    name?: string;
+    metadata?: Record<string, unknown>;
+    sources: Record<string, MapLibreSource | unknown>;
+    sprite?: string;
+    glyphs?: string;
+    layers: unknown[];
+}
+interface MapLibreSource {
+    type: string;
+    tiles?: string[];
+    url?: string;
+    minzoom?: number;
+    maxzoom?: number;
+    [key: string]: unknown;
+}
+/** Target platform — drives the URL scheme used in the rewritten source. */
+type OfflineStylePlatform = "ios" | "android" | "desktop";
+interface BuildOfflineStyleOptions {
+    /**
+     * Target platform. iOS + Android use the `mbtiles://` scheme MapLibre Native
+     * understands; desktop uses `file://`. Default: `"ios"`.
+     */
+    platform?: OfflineStylePlatform;
+    /**
+     * Name of the source to rewrite. If omitted, defaults to the only vector
+     * source in the input style. Throws `OfflineStyleError` if there are zero
+     * or more than one vector sources and `sourceName` isn't provided.
+     */
+    sourceName?: string;
+}
+/**
+ * Thrown when `buildOfflineStyle` can't determine which source to swap or
+ * the named source isn't present in the input style.
+ */
+declare class OfflineStyleError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/**
+ * Returns a deep-copy of `onlineStyle` with the named (or auto-detected)
+ * vector source rewritten to point at `mbtilesPath`. Other sources, layers,
+ * paint, layout, glyphs, and sprite pass through unmodified.
+ *
+ * URL scheme:
+ *
+ *   platform="ios"     → `mbtiles://<mbtilesPath>`   MLN Native iOS
+ *   platform="android" → `mbtiles://<mbtilesPath>`   MLN Native Android
+ *   platform="desktop" → `file://<mbtilesPath>`      MLN GL native (Win/Mac/Linux)
+ *
+ * The `mbtilesPath` is intentionally treated as opaque text. Most native MLN
+ * bindings accept the bare scheme + filename and resolve against an
+ * app-defined root (typically the app's Documents directory). Pass an
+ * absolute path on desktop, or a relative filename on iOS/Android.
+ *
+ * @param onlineStyle  The base MapLibre style. Not mutated.
+ * @param mbtilesPath  Local-file path component (e.g. `"NOAA_ENC.mbtiles"`).
+ * @param opts         Platform + optional explicit `sourceName`.
+ *
+ * @example
+ *   import { buildOfflineStyle } from "@chrtco/sdk";
+ *
+ *   // Online style obtained however you like — generated client-side or
+ *   // fetched from a server.
+ *   const onlineStyle = generateStyle("DAY", { region: "NOAA_ENC" });
+ *
+ *   const offlineStyle = buildOfflineStyle(
+ *     onlineStyle,
+ *     "NOAA_ENC.mbtiles",
+ *     { platform: "ios" },
+ *   );
+ *   // → hand `offlineStyle` to MapLibre.
+ */
+declare function buildOfflineStyle(onlineStyle: MapLibreStyle, mbtilesPath: string, opts?: BuildOfflineStyleOptions): MapLibreStyle;
+
 interface GeoJsonGeometry {
     type: string;
     coordinates: unknown;
@@ -68,6 +173,48 @@ interface CellsResponse {
     limit: number;
     offset: number;
 }
+interface RouteQueryOptions {
+    /** Array of [longitude, latitude] waypoints forming the route */
+    route: [number, number][];
+    /** Buffer distance in metres (default 1000, max 50000) */
+    buffer?: number;
+    /** Filter by chart source, e.g. "NOAA" */
+    source?: string;
+    /** Filter by scale band, e.g. "4" */
+    scaleBand?: string;
+    /** Max cells to return (default 100) */
+    limit?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+interface RouteQueryResponse {
+    cells: CellDetail[];
+    query: {
+        buffer_m: number;
+        cell_count: number;
+    };
+    total_count: number;
+}
+interface RouteFeatureQueryOptions {
+    /** Array of [longitude, latitude] waypoints forming the route */
+    route: [number, number][];
+    /** Buffer distance in metres (default 1000, max 50000) */
+    buffer?: number;
+    /** Comma-separated layer codes to filter */
+    layer?: string;
+    /** Max features to return (default 100) */
+    limit?: number;
+    /** Pagination offset */
+    offset?: number;
+    /** AbortSignal to cancel the request */
+    signal?: AbortSignal;
+}
+interface RouteFeatureQueryResponse extends FeatureCollection {
+    query: {
+        buffer_m: number;
+        route_length_m?: number;
+    };
+}
 interface CoverageSource {
     /** Chart source ID, e.g. "NOAA" */
     source: string;
@@ -117,6 +264,119 @@ interface ChrtConfig {
     baseUrl?: string;
     /** Max retries on 5xx/network errors (default 2) */
     retries?: number;
+    /**
+     * Stable per-install device identifier. Required to call `chrt.offline.*`.
+     * Generate once at first launch (e.g. UUIDv4), persist, reuse forever.
+     * Echoed into the offline JWT + heartbeat for device-level correlation.
+     */
+    deviceId?: string;
+    /**
+     * Absolute path to a JSON file where the SDK tracks local offline state
+     * (which regions are downloaded, their sizes and hashes, the storage
+     * budget). Optional — if unset, `setStorageBudget` throws and
+     * budget enforcement in `download` is skipped. No hidden state otherwise.
+     */
+    manifestPath?: string;
+}
+interface OfflineRegionSummary {
+    region: string;
+    build_id: string;
+    build_tag: string;
+    total_bytes: number;
+    issued_at: number | null;
+}
+/**
+ * Response shape from `GET /v1/offline/bundles/{region}`.
+ *
+ * Designed against the post-groups-collapse single-URL shape. A parallel task
+ * is migrating the offline-worker from `groups[]` → one URL per region; this
+ * SDK expects that migration to land before end-to-end integration.
+ */
+interface OfflineBundleResponse {
+    region: string;
+    build_id: string;
+    build_tag: string;
+    signed_url: string;
+    expires_at: number;
+    bytes: number;
+    sha256: string;
+    offline_until: number;
+    heartbeat_after: number;
+    server_time: number;
+}
+interface OfflineDownloadProgress {
+    bytesDownloaded: number;
+    bytesTotal: number;
+    fraction: number;
+}
+interface OfflineDownloadOptions {
+    /** Final destination path for the downloaded MBTiles. SDK writes to `<path>.partial` first, then renames. */
+    path: string;
+    /** FileSystem adapter (e.g. `nodeFileSystemAdapter()` from `@chrtco/sdk/node`). */
+    fs: FileSystemAdapter;
+    /**
+     * Progress callback. Throttled to max(1 MB, 1%) boundaries. Always fires
+     * once at 0 bytes and once at completion regardless of threshold.
+     */
+    onProgress?: (p: OfflineDownloadProgress) => void;
+    /** AbortSignal — on abort, any bytes written persist as `<path>.partial` for resume. */
+    signal?: AbortSignal;
+}
+interface OfflineDownloadResult {
+    path: string;
+    bytes: number;
+    sha256: string;
+    build_id: string;
+    build_tag: string;
+    /** True if this call finished an in-flight download rather than starting fresh. */
+    resumed: boolean;
+}
+interface OfflineRemoveOptions {
+    path: string;
+    fs: FileSystemAdapter;
+}
+interface OfflineHeartbeatOptions {
+    /** Regions currently downloaded. If omitted, derived from manifest (requires `fs`). */
+    regions?: string[];
+    /** Total bytes on device. If omitted, derived from manifest (requires `fs`). */
+    total_bytes?: number;
+    /** FileSystem adapter. Required iff `regions`/`total_bytes` are omitted and manifestPath is set. */
+    fs?: FileSystemAdapter;
+    sdk_version?: string;
+    platform?: string;
+}
+/**
+ * Options for `chrt.offline.fetchStyle()` — fetch a pre-baked offline style
+ * from `GET /v1/offline/styles/{region}`.
+ */
+interface OfflineFetchStyleOptions {
+    /** S-52 colour palette. Default: `"DAY"`. */
+    palette?: "DAY" | "DUSK" | "NIGHT";
+    /**
+     * URL scheme baked into the source. Default: `"mbtiles"` (iOS/Android via
+     * MLN Native). Use `"file"` for desktop (Win/macOS/Linux).
+     */
+    protocol?: "mbtiles" | "file";
+    /** AbortSignal to cancel the request. */
+    signal?: AbortSignal;
+}
+/**
+ * Response shape from `GET /v1/offline/styles/{region}`. The `style` field is
+ * a MapLibre style spec ready to hand to MLN; the surrounding metadata mirrors
+ * the bundle response so callers can refresh `offline_until` from the same
+ * call without a separate heartbeat.
+ */
+interface OfflineStyleResponse {
+    region: string;
+    palette: "DAY" | "DUSK" | "NIGHT";
+    protocol: "mbtiles" | "file";
+    build_id: string;
+    build_tag: string;
+    /** Full MapLibre style JSON. Pass directly to `Map({ style: ... })`. */
+    style: MapLibreStyle;
+    offline_until: number;
+    heartbeat_after: number;
+    server_time: number;
 }
 
 declare class ChrtError extends Error {
@@ -133,6 +393,27 @@ declare class HttpClient {
     getBaseUrl(): string;
     getApiKey(): string;
     request<T>(path: string, params?: Record<string, string | number | undefined>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Typed wrapper for non-GET JSON requests. Returns the parsed body and HTTP
+     * status together so callers (e.g. offline endpoints) can map error bodies
+     * to typed errors without throwing at the HTTP layer. Auth defaults to
+     * `x-api-key` header; pass `bearerToken` to swap to `Authorization: Bearer`.
+     * No retry — the offline flow owns its own retry logic.
+     */
+    postJson<T>(path: string, body: unknown, opts?: {
+        bearerToken?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        ok: boolean;
+        status: number;
+        body: T | null;
+    }>;
+    /** GET with Bearer auth (for offline-worker endpoints that require a JWT). */
+    getJsonWithBearer<T>(path: string, bearerToken: string, signal?: AbortSignal): Promise<{
+        ok: boolean;
+        status: number;
+        body: T | null;
+    }>;
 }
 
 declare class TilesEndpoint {
@@ -162,6 +443,100 @@ declare class CoverageEndpoint {
     list(options?: CoverageOptions): Promise<CoverageResponse>;
 }
 
+/**
+ * Fresh-token shape from POST `/v1/mint/offline-token` (proxied to Supabase
+ * `mint-offline-token`). Mirrors docs/api/tile-jwt-claims.md §4.
+ */
+interface MintedOfflineToken {
+    token: string;
+    expiresAt: number;
+    kid: string;
+    offlineUntil: number;
+    /** Per-region build_tag map returned by the mint function. */
+    buildTags: Record<string, string>;
+    gracePeriodDays: number;
+}
+/**
+ * Cache + single-flight mint for offline JWTs.
+ *
+ * - Keyed by `(deviceId, sorted-regions)` so a token scoped to one region
+ *   doesn't accidentally get reused for a broader request.
+ * - Refreshes 30s before `exp`.
+ * - While a mint is in flight, concurrent callers share the same promise.
+ */
+declare class OfflineTokenManager {
+    private readonly http;
+    private readonly cache;
+    private readonly pending;
+    constructor(http: HttpClient);
+    /**
+     * Get a fresh-enough token for the caller's device + requested regions.
+     * If `regions` is omitted, the mint function defaults to the key's full
+     * `allowed_sources`.
+     */
+    getToken(deviceId: string, regions?: string[]): Promise<MintedOfflineToken>;
+    /** Force-evict the cached token for a (deviceId, regions) pair. Used after a 401. */
+    invalidate(deviceId: string, regions?: string[]): void;
+    private cacheKey;
+    private mintFresh;
+}
+
+declare class OfflineEndpoint {
+    private readonly http;
+    private readonly deviceId;
+    private readonly manifestPath;
+    readonly tokenManager: OfflineTokenManager;
+    constructor(http: HttpClient, deviceId: string | undefined, manifestPath: string | undefined);
+    /** List regions downloadable under the caller's API key. */
+    list(): Promise<OfflineRegionSummary[]>;
+    /**
+     * Download an MBTiles bundle for `region` to `opts.path`. Resumable via a
+     * `<path>.partial` sidecar on interrupt. SHA-256 verified before rename.
+     */
+    download(region: string, opts: OfflineDownloadOptions): Promise<OfflineDownloadResult>;
+    /** Delete local file and, if manifest is configured, drop its row + heartbeat. */
+    remove(region: string, opts: OfflineRemoveOptions): Promise<void>;
+    /**
+     * Pure helper — rewrites the named (or auto-detected) vector source in
+     * `onlineStyle` to point at a local MBTiles file. Layers/paint/glyphs
+     * untouched. Use when you already have an online style (e.g. generated
+     * client-side via the React app's atlas) and want the offline variant.
+     *
+     * Equivalent to importing `buildOfflineStyle` directly — exposed on the
+     * endpoint for discoverability.
+     */
+    style(onlineStyle: MapLibreStyle, mbtilesPath: string, opts?: BuildOfflineStyleOptions): MapLibreStyle;
+    /**
+     * Fetch a pre-baked offline style for `region` from
+     * `GET /v1/offline/styles/{region}`. The worker's response already has the
+     * source rewritten to `mbtiles://` (default) or `file://`, so the returned
+     * `style` is ready to hand directly to MapLibre.
+     *
+     * Recommended for native MLN clients (iOS/Android/desktop) that don't have
+     * the JS atlas available. JS/web SDK consumers can equivalently generate
+     * the online style themselves and call `chrt.offline.style(...)`.
+     */
+    fetchStyle(region: string, opts?: OfflineFetchStyleOptions): Promise<OfflineStyleResponse>;
+    /**
+     * Set the local storage budget in bytes. Requires `manifestPath`. Enforced
+     * at the start of each `download()`. A budget smaller than current usage
+     * does not auto-prune; it only refuses new downloads until the customer
+     * calls `remove()`.
+     */
+    setStorageBudget(bytes: number, fs: FileSystemAdapter): Promise<void>;
+    /**
+     * Send a heartbeat. If `opts.regions` / `opts.total_bytes` are omitted and
+     * a manifest is configured, values are derived from it. v1 is manual-call
+     * only; auto-scheduling is a follow-up phase.
+     */
+    heartbeat(opts?: OfflineHeartbeatOptions): Promise<void>;
+    private requireDeviceId;
+    private requireToken;
+    private fetchBundle;
+    private downloadInternal;
+    private persistManifestEntry;
+}
+
 /**
  * Generic async auto-pagination generator.
  *
@@ -241,6 +616,22 @@ type WebhookEventType = WebhookEvent["type"];
  */
 declare function parseWebhook(body: unknown): WebhookEvent;
 
+/**
+ * Typed errors surfaced by `chrt.offline.*`.
+ *
+ * Callers switch on `.code` — never parse `.message`. `.status` is set only
+ * when the error originated from an HTTP response. `.detail` carries
+ * machine-readable context for programmatic handling (byte math for budget
+ * violations, `resumable: true` for interrupts, etc.).
+ */
+type OfflineErrorCode = "budget_exceeded" | "coverage_denied" | "quota_exceeded" | "download_corrupt" | "network_interrupted" | "partial_file_invalid" | "invalid_api_key" | "region_not_available" | "offline_not_enabled" | "missing_device_id" | "missing_manifest_path" | "sha_missing" | "unexpected_response";
+declare class OfflineError extends Error {
+    readonly code: OfflineErrorCode;
+    readonly status?: number;
+    readonly detail?: Record<string, unknown>;
+    constructor(code: OfflineErrorCode, message: string, status?: number, detail?: Record<string, unknown>);
+}
+
 declare class Chrt {
     /** Tile endpoints — styleUrl, tileUrl, groups */
     readonly tiles: TilesEndpoint;
@@ -248,6 +639,12 @@ declare class Chrt {
     readonly cells: CellsEndpoint;
     /** Coverage data — list available chart sources */
     readonly coverage: CoverageEndpoint;
+    /**
+     * CHRToffline — download MBTiles bundles for offline use.
+     * Requires `deviceId` in config. Manifest-based budget enforcement
+     * requires `manifestPath`.
+     */
+    readonly offline: OfflineEndpoint;
     private featuresEp;
     private queryEp;
     private http;
@@ -293,4 +690,4 @@ declare class Chrt {
     transformRequest(): (url: string) => TransformRequest | undefined;
 }
 
-export { type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, Chrt, type ChrtConfig, ChrtError, type CoverageOptions, type CoverageResponse, type CoverageSource, type FeatureCollection, type FeaturesOptions, type GeoJsonFeature, type GeoJsonGeometry, type QueryOptions, type TileGroup, type TileGroupsResponse, type TransformRequest, type WebhookEvent, type WebhookEventType, type WebhookPayload, paginate, parseWebhook };
+export { type BuildOfflineStyleOptions, type CellDeletedEvent, type CellDetail, type CellEventData, type CellNewEvent, type CellUpdatedData, type CellUpdatedEvent, type CellsOptions, type CellsResponse, Chrt, type ChrtConfig, ChrtError, type CoverageOptions, type CoverageResponse, type CoverageSource, type FeatureCollection, type FeaturesOptions, FileSystemAdapter, type GeoJsonFeature, type GeoJsonGeometry, type MapLibreStyle, type OfflineBundleResponse, type OfflineDownloadOptions, type OfflineDownloadProgress, type OfflineDownloadResult, OfflineError, type OfflineErrorCode, type OfflineFetchStyleOptions, type OfflineHeartbeatOptions, type OfflineRegionSummary, type OfflineRemoveOptions, OfflineStyleError, type OfflineStylePlatform, type OfflineStyleResponse, type QueryOptions, type RouteFeatureQueryOptions, type RouteFeatureQueryResponse, type RouteQueryOptions, type RouteQueryResponse, type TileGroup, type TileGroupsResponse, type TransformRequest, type WebhookEvent, type WebhookEventType, type WebhookPayload, buildOfflineStyle, paginate, parseWebhook };