@chrtco/sdk 0.4.1 → 0.5.0

package/dist/index.js

@@ -71,6 +71,51 @@ var HttpClient = class {
     }
     throw lastError ?? new Error("CHRT API request failed");
   }
+  /**
+   * 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.
+   */
+  async postJson(path, body, opts) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    const headers = { "content-type": "application/json" };
+    if (opts?.bearerToken) {
+      headers["authorization"] = `Bearer ${opts.bearerToken}`;
+    } else {
+      headers["x-api-key"] = this.apiKey;
+    }
+    const res = await fetch(url.toString(), {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: opts?.signal
+    });
+    let parsed = null;
+    try {
+      parsed = await res.json();
+    } catch {
+      parsed = null;
+    }
+    return { ok: res.ok, status: res.status, body: parsed };
+  }
+  /** GET with Bearer auth (for offline-worker endpoints that require a JWT). */
+  async getJsonWithBearer(path, bearerToken, signal) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    const res = await fetch(url.toString(), {
+      method: "GET",
+      headers: { authorization: `Bearer ${bearerToken}` },
+      signal
+    });
+    let parsed = null;
+    try {
+      parsed = await res.json();
+    } catch {
+      parsed = null;
+    }
+    return { ok: res.ok, status: res.status, body: parsed };
+  }
 };
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -173,7 +218,748 @@ var QueryEndpoint = class {
       options.signal
     );
   }
+  // ── [CHRTquery] Staged — uncomment when serve-query/route is live ──
+  //
+  // /** Discover ENC cells along a route LineString */
+  // async alongRoute(options: RouteQueryOptions): Promise<RouteQueryResponse> {
+  //   const route = {
+  //     type: "LineString" as const,
+  //     coordinates: options.route,
+  //   };
+  //   return this.http.request<RouteQueryResponse>(
+  //     "/query/route",
+  //     {
+  //       route: JSON.stringify(route),
+  //       buffer: options.buffer,
+  //       source: options.source,
+  //       scale_band: options.scaleBand,
+  //       limit: options.limit,
+  //     },
+  //     options.signal,
+  //   );
+  // }
+  // ── [CHRTquery] Staged — uncomment when serve-query/route/features is live ──
+  //
+  // /** Find individual features along a route LineString */
+  // async featuresAlongRoute(options: RouteFeatureQueryOptions): Promise<RouteFeatureQueryResponse> {
+  //   const route = {
+  //     type: "LineString" as const,
+  //     coordinates: options.route,
+  //   };
+  //   return this.http.request<RouteFeatureQueryResponse>(
+  //     "/query/route/features",
+  //     {
+  //       route: JSON.stringify(route),
+  //       buffer: options.buffer,
+  //       layer: options.layer,
+  //       limit: options.limit,
+  //       offset: options.offset,
+  //     },
+  //     options.signal,
+  //   );
+  // }
+};
+
+// src/endpoints/offline-errors.ts
+var OfflineError = class extends Error {
+  code;
+  status;
+  detail;
+  constructor(code, message, status, detail) {
+    super(message);
+    this.name = "OfflineError";
+    this.code = code;
+    this.status = status;
+    this.detail = detail;
+  }
+};
+function mapServerError(body, status) {
+  const b = body ?? {};
+  const raw = typeof b.code === "string" ? b.code : typeof b.error === "string" ? b.error : "";
+  switch (raw) {
+    case "offline_budget_exceeded":
+      return {
+        code: "budget_exceeded",
+        detail: {
+          budget_bytes: b.budget_bytes,
+          required_bytes: b.required_bytes,
+          over_by_bytes: b.over_by_bytes,
+          remaining_bytes: b.remaining_bytes
+        }
+      };
+    case "offline_not_enabled":
+      return { code: "offline_not_enabled" };
+    case "region_not_licensed":
+      return {
+        code: "coverage_denied",
+        detail: { requested: b.requested, allowed: b.allowed }
+      };
+    case "no_offline_builds":
+    case "no_offline_build":
+      return { code: "region_not_available", detail: { detail: b.detail, region: b.region } };
+    case "invalid_api_key":
+    case "missing_auth":
+      return { code: "invalid_api_key" };
+    case "tile_quota_exceeded":
+      return { code: "quota_exceeded" };
+    case "rate_limited":
+      return {
+        code: "quota_exceeded",
+        detail: { limit: b.limit, period_seconds: b.period_seconds }
+      };
+    case "revoked":
+      return { code: "invalid_api_key", detail: { reason: "revoked" } };
+  }
+  if (status === 401) return { code: "invalid_api_key" };
+  if (status === 403) return { code: "coverage_denied" };
+  if (status === 429) return { code: "quota_exceeded" };
+  if (status === 503) return { code: "region_not_available" };
+  return { code: "unexpected_response", detail: { raw_error: raw } };
+}
+
+// src/endpoints/offline-token-manager.ts
+var REFRESH_MARGIN_SECONDS = 30;
+function now() {
+  return Math.floor(Date.now() / 1e3);
+}
+var OfflineTokenManager = class {
+  constructor(http) {
+    this.http = http;
+  }
+  cache = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  /**
+   * 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`.
+   */
+  async getToken(deviceId, regions) {
+    if (!deviceId) {
+      throw new OfflineError("missing_device_id", "deviceId is required for offline operations");
+    }
+    const key = this.cacheKey(deviceId, regions);
+    const cached = this.cache.get(key);
+    if (cached && cached.expiresAt - now() > REFRESH_MARGIN_SECONDS) {
+      return cached;
+    }
+    const inflight = this.pending.get(key);
+    if (inflight) return inflight;
+    const promise = this.mintFresh(deviceId, regions).finally(() => {
+      this.pending.delete(key);
+    });
+    this.pending.set(key, promise);
+    const token = await promise;
+    this.cache.set(key, token);
+    return token;
+  }
+  /** Force-evict the cached token for a (deviceId, regions) pair. Used after a 401. */
+  invalidate(deviceId, regions) {
+    this.cache.delete(this.cacheKey(deviceId, regions));
+  }
+  cacheKey(deviceId, regions) {
+    const tail = regions && regions.length > 0 ? [...regions].sort().join(",") : "*";
+    return `${deviceId}::${tail}`;
+  }
+  async mintFresh(deviceId, regions) {
+    const body = { device_id: deviceId };
+    if (regions && regions.length > 0) body.regions = regions;
+    const res = await this.http.postJson("/mint/offline-token", body);
+    if (!res.ok) {
+      const mapped = mapServerError(res.body, res.status);
+      throw new OfflineError(
+        mapped.code,
+        `mint-offline-token failed: HTTP ${res.status}`,
+        res.status,
+        mapped.detail
+      );
+    }
+    const body2 = res.body ?? {};
+    const regionsArr = Array.isArray(body2.regions) ? body2.regions : [];
+    const buildTags = {};
+    for (const r of regionsArr) {
+      if (r && typeof r === "object") {
+        const row = r;
+        if (typeof row.region === "string" && typeof row.build_tag === "string") {
+          buildTags[row.region] = row.build_tag;
+        }
+      }
+    }
+    if (typeof body2.token !== "string" || typeof body2.expires_at !== "number" || typeof body2.kid !== "string" || typeof body2.offline_until !== "number" || typeof body2.grace_period_days !== "number") {
+      throw new OfflineError(
+        "unexpected_response",
+        "mint-offline-token returned malformed body",
+        res.status
+      );
+    }
+    return {
+      token: body2.token,
+      expiresAt: body2.expires_at,
+      kid: body2.kid,
+      offlineUntil: body2.offline_until,
+      buildTags,
+      gracePeriodDays: body2.grace_period_days
+    };
+  }
+};
+
+// src/endpoints/offline-style.ts
+var OfflineStyleError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "OfflineStyleError";
+    this.code = code;
+  }
+};
+function buildOfflineStyle(onlineStyle, mbtilesPath, opts = {}) {
+  if (!onlineStyle || typeof onlineStyle !== "object") {
+    throw new OfflineStyleError("onlineStyle is required", "invalid_style");
+  }
+  if (!onlineStyle.sources || typeof onlineStyle.sources !== "object") {
+    throw new OfflineStyleError("style has no sources", "no_sources");
+  }
+  if (!mbtilesPath || typeof mbtilesPath !== "string") {
+    throw new OfflineStyleError("mbtilesPath is required", "invalid_path");
+  }
+  const platform = opts.platform ?? "ios";
+  const scheme = platform === "desktop" ? "file" : "mbtiles";
+  const url = `${scheme}://${mbtilesPath}`;
+  let sourceName;
+  if (opts.sourceName) {
+    if (!(opts.sourceName in onlineStyle.sources)) {
+      throw new OfflineStyleError(
+        `source "${opts.sourceName}" not found in style`,
+        "source_not_found"
+      );
+    }
+    sourceName = opts.sourceName;
+  } else {
+    const vectorSources = Object.entries(onlineStyle.sources).filter(
+      ([, src2]) => src2 && typeof src2 === "object" && src2.type === "vector"
+    );
+    if (vectorSources.length === 0) {
+      throw new OfflineStyleError(
+        "no vector sources in style \u2014 pass `opts.sourceName` to override",
+        "no_vector_source"
+      );
+    }
+    if (vectorSources.length > 1) {
+      throw new OfflineStyleError(
+        `${vectorSources.length} vector sources in style \u2014 pass \`opts.sourceName\``,
+        "ambiguous_source"
+      );
+    }
+    sourceName = vectorSources[0][0];
+  }
+  const cloned = JSON.parse(JSON.stringify(onlineStyle));
+  const src = cloned.sources[sourceName];
+  src.tiles = [url];
+  delete src.url;
+  return cloned;
+}
+
+// src/endpoints/offline-manifest.ts
+var CURRENT_VERSION = 1;
+function emptyManifest() {
+  return { version: CURRENT_VERSION, budget_bytes: null, regions: {} };
+}
+async function readManifest(manifestPath, fs) {
+  if (!manifestPath) return emptyManifest();
+  if (!await fs.exists(manifestPath)) return emptyManifest();
+  const raw = await fs.readFile(manifestPath);
+  const text = new TextDecoder().decode(raw);
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new OfflineError(
+      "unexpected_response",
+      `offline manifest at ${manifestPath} is not valid JSON`
+    );
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new OfflineError("unexpected_response", `offline manifest shape invalid`);
+  }
+  const m = parsed;
+  if (m.version !== CURRENT_VERSION) {
+    throw new OfflineError(
+      "unexpected_response",
+      `offline manifest version mismatch: got ${String(m.version)}, expected ${CURRENT_VERSION}`
+    );
+  }
+  return {
+    version: CURRENT_VERSION,
+    budget_bytes: typeof m.budget_bytes === "number" ? m.budget_bytes : null,
+    regions: m.regions && typeof m.regions === "object" ? m.regions : {}
+  };
+}
+async function writeManifest(manifestPath, fs, manifest) {
+  const text = JSON.stringify(manifest, null, 2);
+  const bytes = new TextEncoder().encode(text);
+  await fs.writeFile(manifestPath, bytes);
+}
+function usedBytes(manifest, excludeRegion) {
+  let total = 0;
+  for (const [region, entry] of Object.entries(manifest.regions)) {
+    if (region === excludeRegion) continue;
+    total += entry.bytes;
+  }
+  return total;
+}
+function requireManifestPath(manifestPath) {
+  if (!manifestPath) {
+    throw new OfflineError(
+      "missing_manifest_path",
+      "ChrtConfig.manifestPath is required for this operation"
+    );
+  }
+  return manifestPath;
+}
+
+// src/endpoints/offline.ts
+var PROGRESS_MIN_BYTES = 1024 * 1024;
+var PROGRESS_MIN_FRACTION = 0.01;
+var OfflineEndpoint = class {
+  constructor(http, deviceId, manifestPath) {
+    this.http = http;
+    this.deviceId = deviceId;
+    this.manifestPath = manifestPath;
+    this.tokenManager = new OfflineTokenManager(http);
+  }
+  tokenManager;
+  /** List regions downloadable under the caller's API key. */
+  async list() {
+    const token = await this.requireToken();
+    const res = await this.http.getJsonWithBearer(
+      "/offline/regions",
+      token.token
+    );
+    if (!res.ok) {
+      const mapped = mapServerError(res.body, res.status);
+      throw new OfflineError(
+        mapped.code,
+        `offline.list failed: HTTP ${res.status}`,
+        res.status,
+        mapped.detail
+      );
+    }
+    const arr = Array.isArray(res.body?.regions) ? res.body.regions : [];
+    const out = [];
+    for (const r of arr) {
+      if (!r || typeof r !== "object") continue;
+      const row = r;
+      if (typeof row.region === "string" && typeof row.build_id === "string" && typeof row.build_tag === "string" && typeof row.total_bytes === "number") {
+        out.push({
+          region: row.region,
+          build_id: row.build_id,
+          build_tag: row.build_tag,
+          total_bytes: row.total_bytes,
+          issued_at: typeof row.issued_at === "number" ? row.issued_at : null
+        });
+      }
+    }
+    return out;
+  }
+  /**
+   * Download an MBTiles bundle for `region` to `opts.path`. Resumable via a
+   * `<path>.partial` sidecar on interrupt. SHA-256 verified before rename.
+   */
+  async download(region, opts) {
+    return this.downloadInternal(region, opts, 0);
+  }
+  /** Delete local file and, if manifest is configured, drop its row + heartbeat. */
+  async remove(region, opts) {
+    if (await opts.fs.exists(opts.path)) {
+      await opts.fs.unlink(opts.path);
+    }
+    const partial = `${opts.path}.partial`;
+    if (await opts.fs.exists(partial)) {
+      await opts.fs.unlink(partial);
+    }
+    if (this.manifestPath) {
+      const manifest = await readManifest(this.manifestPath, opts.fs);
+      if (manifest.regions[region]) {
+        delete manifest.regions[region];
+        await writeManifest(this.manifestPath, opts.fs, manifest);
+      }
+      const regions = Object.keys(manifest.regions);
+      const total = usedBytes(manifest);
+      try {
+        await this.heartbeat({ regions, total_bytes: total, fs: opts.fs });
+      } catch {
+      }
+    }
+  }
+  /**
+   * 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, mbtilesPath, opts) {
+    return buildOfflineStyle(onlineStyle, mbtilesPath, opts);
+  }
+  /**
+   * 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(...)`.
+   */
+  async fetchStyle(region, opts = {}) {
+    const token = await this.requireToken([region]);
+    const palette = opts.palette ?? "DAY";
+    const protocol = opts.protocol ?? "mbtiles";
+    const path = `/offline/styles/${encodeURIComponent(region)}?palette=${palette}&protocol=${protocol}`;
+    const res = await this.http.getJsonWithBearer(
+      path,
+      token.token
+    );
+    if (!res.ok) {
+      const mapped = mapServerError(res.body, res.status);
+      throw new OfflineError(
+        mapped.code,
+        `offline.fetchStyle failed: HTTP ${res.status}`,
+        res.status,
+        mapped.detail
+      );
+    }
+    if (!res.body || typeof res.body !== "object" || !res.body.style) {
+      throw new OfflineError(
+        "unexpected_response",
+        "offline.fetchStyle: malformed response (missing `style`)",
+        res.status
+      );
+    }
+    return res.body;
+  }
+  /**
+   * 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()`.
+   */
+  async setStorageBudget(bytes, fs) {
+    if (!Number.isFinite(bytes) || bytes < 0) {
+      throw new OfflineError("unexpected_response", `invalid budget: ${bytes}`);
+    }
+    const path = requireManifestPath(this.manifestPath);
+    const manifest = await readManifest(path, fs);
+    manifest.budget_bytes = bytes;
+    await writeManifest(path, fs, manifest);
+  }
+  /**
+   * 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.
+   */
+  async heartbeat(opts) {
+    const deviceId = this.requireDeviceId();
+    let regions = opts?.regions;
+    let totalBytes = opts?.total_bytes;
+    if ((regions === void 0 || totalBytes === void 0) && this.manifestPath && opts?.fs) {
+      const manifest = await readManifest(this.manifestPath, opts.fs);
+      if (regions === void 0) regions = Object.keys(manifest.regions);
+      if (totalBytes === void 0) totalBytes = usedBytes(manifest);
+    }
+    if (regions === void 0) regions = [];
+    if (totalBytes === void 0) totalBytes = 0;
+    const token = await this.tokenManager.getToken(deviceId);
+    const body = {
+      device_id: deviceId,
+      regions,
+      total_bytes: totalBytes,
+      ...opts?.sdk_version ? { sdk_version: opts.sdk_version } : {},
+      ...opts?.platform ? { platform: opts.platform } : {}
+    };
+    const res = await this.http.postJson("/offline/heartbeat", body, {
+      bearerToken: token.token
+    });
+    if (!res.ok) {
+      const mapped = mapServerError(res.body, res.status);
+      throw new OfflineError(
+        mapped.code,
+        `offline.heartbeat failed: HTTP ${res.status}`,
+        res.status,
+        mapped.detail
+      );
+    }
+  }
+  // ── Internals ────────────────────────────────────────────────────────────
+  requireDeviceId() {
+    if (!this.deviceId) {
+      throw new OfflineError(
+        "missing_device_id",
+        "ChrtConfig.deviceId is required for offline operations"
+      );
+    }
+    return this.deviceId;
+  }
+  async requireToken(regions) {
+    const deviceId = this.requireDeviceId();
+    return this.tokenManager.getToken(deviceId, regions);
+  }
+  async fetchBundle(region, bearerToken) {
+    const res = await this.http.getJsonWithBearer(
+      `/offline/bundles/${encodeURIComponent(region)}`,
+      bearerToken
+    );
+    if (!res.ok) {
+      const mapped = mapServerError(res.body, res.status);
+      throw new OfflineError(
+        mapped.code,
+        `offline.download bundle fetch failed: HTTP ${res.status}`,
+        res.status,
+        mapped.detail
+      );
+    }
+    const b = res.body ?? {};
+    const missingFields = [];
+    const field = (k) => b[k];
+    for (const k of ["signed_url", "bytes", "build_id", "build_tag", "expires_at"]) {
+      if (field(k) === void 0) missingFields.push(k);
+    }
+    if (missingFields.length > 0) {
+      throw new OfflineError(
+        "unexpected_response",
+        `bundle response missing fields: ${missingFields.join(",")}`,
+        res.status
+      );
+    }
+    if (typeof field("sha256") !== "string" || field("sha256").length === 0) {
+      throw new OfflineError(
+        "sha_missing",
+        "bundle response did not include sha256; cannot verify integrity",
+        res.status
+      );
+    }
+    return {
+      region: typeof field("region") === "string" ? field("region") : region,
+      build_id: field("build_id"),
+      build_tag: field("build_tag"),
+      signed_url: field("signed_url"),
+      expires_at: field("expires_at"),
+      bytes: field("bytes"),
+      sha256: field("sha256").toLowerCase(),
+      offline_until: typeof field("offline_until") === "number" ? field("offline_until") : 0,
+      heartbeat_after: typeof field("heartbeat_after") === "number" ? field("heartbeat_after") : 0,
+      server_time: typeof field("server_time") === "number" ? field("server_time") : 0
+    };
+  }
+  async downloadInternal(region, opts, retryDepth) {
+    const { path, fs, onProgress, signal } = opts;
+    const partialPath = `${path}.partial`;
+    const token = await this.requireToken([region]);
+    const bundle = await this.fetchBundle(region, token.token);
+    if (this.manifestPath) {
+      const manifest = await readManifest(this.manifestPath, fs);
+      if (manifest.budget_bytes !== null) {
+        const currentUsed = usedBytes(manifest, region);
+        const projected = currentUsed + bundle.bytes;
+        if (projected > manifest.budget_bytes) {
+          throw new OfflineError(
+            "budget_exceeded",
+            `offline storage budget would be exceeded`,
+            void 0,
+            {
+              budget_bytes: manifest.budget_bytes,
+              used_bytes: currentUsed,
+              required_bytes: bundle.bytes,
+              over_by_bytes: projected - manifest.budget_bytes
+            }
+          );
+        }
+      }
+    }
+    let startByte = 0;
+    let resumed = false;
+    if (await fs.exists(partialPath)) {
+      const partialStat = await fs.stat(partialPath);
+      if (partialStat.size > bundle.bytes) {
+        await fs.unlink(partialPath);
+      } else if (partialStat.size === bundle.bytes) {
+        const computed = await fs.sha256(partialPath);
+        if (computed.toLowerCase() === bundle.sha256) {
+          await fs.rename(partialPath, path);
+          await this.persistManifestEntry(region, bundle, path, fs);
+          return {
+            path,
+            bytes: bundle.bytes,
+            sha256: bundle.sha256,
+            build_id: bundle.build_id,
+            build_tag: bundle.build_tag,
+            resumed: true
+          };
+        }
+        await fs.unlink(partialPath);
+      } else {
+        startByte = partialStat.size;
+        resumed = true;
+      }
+    }
+    const fetchInit = { method: "GET", signal };
+    if (startByte > 0) {
+      fetchInit.headers = { Range: `bytes=${startByte}-` };
+    }
+    let response;
+    try {
+      response = await fetch(bundle.signed_url, fetchInit);
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new OfflineError(
+          "network_interrupted",
+          "download aborted before response",
+          void 0,
+          { resumable: startByte > 0, bytes_written: startByte }
+        );
+      }
+      throw new OfflineError(
+        "network_interrupted",
+        err instanceof Error ? err.message : "fetch failed",
+        void 0,
+        { resumable: startByte > 0, bytes_written: startByte }
+      );
+    }
+    if (startByte > 0 && (response.status === 403 || response.status === 404)) {
+      await fs.unlink(partialPath);
+      if (retryDepth > 0) {
+        throw new OfflineError(
+          "unexpected_response",
+          `signed URL still rejected after re-mint (HTTP ${response.status})`,
+          response.status
+        );
+      }
+      this.tokenManager.invalidate(this.requireDeviceId(), [region]);
+      return this.downloadInternal(region, opts, retryDepth + 1);
+    }
+    if (startByte > 0 && response.status !== 206) {
+      throw new OfflineError(
+        "unexpected_response",
+        `expected 206 Partial Content on Range request, got ${response.status}`,
+        response.status
+      );
+    }
+    if (startByte === 0 && response.status !== 200) {
+      throw new OfflineError(
+        "unexpected_response",
+        `expected 200 on initial GET, got ${response.status}`,
+        response.status
+      );
+    }
+    if (!response.body) {
+      throw new OfflineError(
+        "unexpected_response",
+        "response had no body",
+        response.status
+      );
+    }
+    await fs.mkdir(dirname(path), { recursive: true });
+    const writer = (await fs.writeStream(partialPath, { append: startByte > 0 })).getWriter();
+    let bytesDownloaded = startByte;
+    let lastProgressBytes = startByte;
+    const progressThreshold = Math.max(
+      PROGRESS_MIN_BYTES,
+      Math.floor(bundle.bytes * PROGRESS_MIN_FRACTION)
+    );
+    const emit = (final) => {
+      if (!onProgress) return;
+      if (!final && bytesDownloaded - lastProgressBytes < progressThreshold) return;
+      const progress = {
+        bytesDownloaded,
+        bytesTotal: bundle.bytes,
+        fraction: bundle.bytes === 0 ? 1 : bytesDownloaded / bundle.bytes
+      };
+      try {
+        onProgress(progress);
+      } catch {
+      }
+      lastProgressBytes = bytesDownloaded;
+    };
+    emit(true);
+    try {
+      const reader = response.body.getReader();
+      while (true) {
+        if (signal?.aborted) {
+          throw new OfflineError(
+            "network_interrupted",
+            "download aborted by caller",
+            void 0,
+            { resumable: true, bytes_written: bytesDownloaded }
+          );
+        }
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) {
+          await writer.write(value);
+          bytesDownloaded += value.byteLength;
+          emit(false);
+        }
+      }
+      await writer.close();
+    } catch (err) {
+      try {
+        await writer.abort();
+      } catch {
+      }
+      if (err instanceof OfflineError) throw err;
+      throw new OfflineError(
+        "network_interrupted",
+        err instanceof Error ? err.message : "stream error",
+        void 0,
+        { resumable: true, bytes_written: bytesDownloaded }
+      );
+    }
+    emit(true);
+    const computedSha = await fs.sha256(partialPath);
+    if (computedSha.toLowerCase() !== bundle.sha256) {
+      await fs.unlink(partialPath);
+      throw new OfflineError(
+        "download_corrupt",
+        `SHA-256 mismatch for ${region}: expected ${bundle.sha256}, got ${computedSha}`,
+        void 0,
+        { expected: bundle.sha256, actual: computedSha }
+      );
+    }
+    await fs.rename(partialPath, path);
+    await this.persistManifestEntry(region, bundle, path, fs);
+    return {
+      path,
+      bytes: bundle.bytes,
+      sha256: bundle.sha256,
+      build_id: bundle.build_id,
+      build_tag: bundle.build_tag,
+      resumed
+    };
+  }
+  async persistManifestEntry(region, bundle, path, fs) {
+    if (!this.manifestPath) return;
+    const manifest = await readManifest(this.manifestPath, fs);
+    const nowSec = Math.floor(Date.now() / 1e3);
+    manifest.regions[region] = {
+      path,
+      bytes: bundle.bytes,
+      sha256: bundle.sha256,
+      build_id: bundle.build_id,
+      build_tag: bundle.build_tag,
+      downloaded_at: nowSec,
+      last_accessed_at: nowSec
+    };
+    await writeManifest(this.manifestPath, fs, manifest);
+  }
 };
+function dirname(p) {
+  const i = p.lastIndexOf("/");
+  const j = p.lastIndexOf("\\");
+  const k = Math.max(i, j);
+  if (k <= 0) return ".";
+  return p.slice(0, k);
+}
 
 // src/pagination.ts
 async function* paginate(fetchPage, getItems, getTotalCount, options) {
@@ -224,6 +1010,12 @@ var Chrt = class {
   cells;
   /** Coverage data — list available chart sources */
   coverage;
+  /**
+   * CHRToffline — download MBTiles bundles for offline use.
+   * Requires `deviceId` in config. Manifest-based budget enforcement
+   * requires `manifestPath`.
+   */
+  offline;
   featuresEp;
   queryEp;
   http;
@@ -235,6 +1027,7 @@ var Chrt = class {
     this.coverage = new CoverageEndpoint(this.http);
     this.featuresEp = new FeaturesEndpoint(this.http);
     this.queryEp = new QueryEndpoint(this.http);
+    this.offline = new OfflineEndpoint(this.http, config.deviceId, config.manifestPath);
   }
   /* ── Convenience shortcuts ───────────────────────── */
   /** Query GeoJSON features by bounding box */
@@ -245,6 +1038,32 @@ var Chrt = class {
   async query(options) {
     return this.queryEp.nearby(options);
   }
+  // ── [CHRTquery] Staged — uncomment when serve-query/route is live ──
+  //
+  // /** Discover ENC cells along a route */
+  // async routeQuery(options: RouteQueryOptions): Promise<RouteQueryResponse> {
+  //   return this.queryEp.alongRoute(options);
+  // }
+  // ── [CHRTquery] Staged — uncomment when serve-query/route/features is live ──
+  //
+  // /** Find individual features along a route */
+  // async routeFeatures(options: RouteFeatureQueryOptions): Promise<RouteFeatureQueryResponse> {
+  //   return this.queryEp.featuresAlongRoute(options);
+  // }
+  //
+  // /** Iterate all features along a route, auto-paginating */
+  // routeFeaturesIter(
+  //   options: Omit<RouteFeatureQueryOptions, "offset">,
+  // ): AsyncIterable<GeoJsonFeature> {
+  //   const pageSize = options.limit ?? 100;
+  //   return paginate<RouteFeatureQueryResponse, GeoJsonFeature>(
+  //     (offset, signal) =>
+  //       this.routeFeatures({ ...options, limit: pageSize, offset, signal }),
+  //     (r) => r.features,
+  //     (r) => r.total_count ?? 0,
+  //     { pageSize, signal: options.signal },
+  //   );
+  // }
   /* ── Auto-pagination iterators ───────────────────── */
   /**
    * Iterate all features matching a bounding-box query, auto-paginating.
@@ -312,6 +1131,9 @@ var Chrt = class {
 export {
   Chrt,
   ChrtError,
+  OfflineError,
+  OfflineStyleError,
+  buildOfflineStyle,
   paginate,
   parseWebhook
 };