@chrtco/sdk 0.7.7 → 0.8.1

package/dist/index.js

@@ -121,20 +121,243 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+// src/tile-auth.ts
+var DEFAULT_TILE_REGION = "NOAA_ENC";
+var DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
+var TileTokenError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(message);
+    this.name = "TileTokenError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var TILE_URL_PATH = /\/v1\/tiles\/[A-Za-z0-9_]+(?:\/[a-z][a-z0-9-]*)?\/\d+\/\d+\/\d+\.mvt(?:\?.*)?$/i;
+var REFRESH_MARGIN_SECONDS = 30;
+var STALE_GRACE_SECONDS = 1;
+var MINT_RETRY_DELAYS_MS = [500, 1e3, 2e3];
+function nowSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function mapErrorCode(raw, status) {
+  const known = [
+    "invalid_api_key",
+    "feature_flag_disabled",
+    "region_not_licensed",
+    "tile_quota_exceeded",
+    "region_not_available"
+  ];
+  if (typeof raw === "string" && known.includes(raw)) {
+    return raw;
+  }
+  if (status === 401) return "invalid_api_key";
+  if (status === 403) return "feature_flag_disabled";
+  if (status === 429) return "tile_quota_exceeded";
+  if (status === 503) return "region_not_available";
+  return "unexpected_response";
+}
+var TileAuth = class {
+  constructor(http, opts) {
+    this.http = http;
+    this.defaultRegion = opts?.region ?? DEFAULT_TILE_REGION;
+    this.tileBaseUrl = (opts?.tileBaseUrl ?? DEFAULT_TILE_BASE_URL).replace(/\/+$/, "");
+  }
+  cache = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
+  defaultRegion;
+  tileBaseUrl;
+  lifecycleRegistered = false;
+  /** Mint once via the HTTP client (POST `/mint/tile-token`, `x-api-key`). */
+  async mintOnce(region) {
+    let res;
+    try {
+      res = await this.http.postJson("/mint/tile-token", { region });
+    } catch (err) {
+      throw new TileTokenError(
+        "network_error",
+        err instanceof Error ? err.message : "mint request failed"
+      );
+    }
+    if (!res.ok) {
+      const code = mapErrorCode(res.body?.error, res.status);
+      const msg = typeof res.body?.error === "string" ? res.body.error : `HTTP ${res.status}`;
+      throw new TileTokenError(code, msg, res.status);
+    }
+    const b = res.body;
+    if (!b || typeof b.token !== "string" || typeof b.expires_at !== "number" || typeof b.kid !== "string" || typeof b.build_tag !== "string" || typeof b.region !== "string") {
+      throw new TileTokenError(
+        "unexpected_response",
+        "mint-tile-token returned a malformed body",
+        res.status
+      );
+    }
+    return {
+      token: b.token,
+      expiresAt: b.expires_at,
+      kid: b.kid,
+      buildTag: b.build_tag,
+      region: b.region
+    };
+  }
+  /** Mint with exponential backoff on network errors only. */
+  async mintWithRetry(region) {
+    let lastErr;
+    for (let attempt = 0; attempt <= MINT_RETRY_DELAYS_MS.length; attempt++) {
+      try {
+        return await this.mintOnce(region);
+      } catch (err) {
+        lastErr = err;
+        if (err instanceof TileTokenError && err.code !== "network_error") throw err;
+        if (attempt === MINT_RETRY_DELAYS_MS.length) break;
+        await sleep2(MINT_RETRY_DELAYS_MS[attempt]);
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new TileTokenError("network_error", "mint failed");
+  }
+  scheduleRefresh(region, expiresAt) {
+    const delaySeconds = expiresAt - nowSeconds() - REFRESH_MARGIN_SECONDS;
+    if (delaySeconds <= 0) return null;
+    const timer = setTimeout(() => {
+      void this.refreshInBackground(region);
+    }, delaySeconds * 1e3);
+    timer.unref?.();
+    return timer;
+  }
+  async refreshInBackground(region) {
+    try {
+      const response = await this.mintWithRetry(region);
+      this.store(region, response);
+    } catch {
+      this.invalidate(region);
+    }
+  }
+  store(region, response) {
+    const existing = this.cache.get(region);
+    if (existing?.refreshTimer) clearTimeout(existing.refreshTimer);
+    this.cache.set(region, {
+      response,
+      refreshTimer: this.scheduleRefresh(region, response.expiresAt)
+    });
+    this.registerLifecycleHandlers();
+  }
+  /**
+   * Fetch (or reuse a cached) tile token for `region`. Concurrent callers for
+   * the same region await the same in-flight mint.
+   */
+  async getToken(region) {
+    const r = region ?? this.defaultRegion;
+    const cached = this.cache.get(r);
+    if (cached && cached.response.expiresAt - nowSeconds() > REFRESH_MARGIN_SECONDS) {
+      return cached.response;
+    }
+    const inflight = this.pending.get(r);
+    if (inflight) return inflight;
+    const promise = (async () => {
+      try {
+        const response = await this.mintWithRetry(r);
+        this.store(r, response);
+        return response;
+      } finally {
+        this.pending.delete(r);
+      }
+    })();
+    this.pending.set(r, promise);
+    return promise;
+  }
+  /** Synchronous cache peek — null if absent or within the stale grace window. */
+  peek(region) {
+    const entry = this.cache.get(region ?? this.defaultRegion);
+    if (!entry) return null;
+    if (entry.response.expiresAt - nowSeconds() <= STALE_GRACE_SECONDS) return null;
+    return entry.response.token;
+  }
+  /**
+   * Produce a MapLibre / Mapbox GL `transformRequest`. Attaches
+   * `Authorization: Bearer <jwt>` only to CHRT tile URLs; style, sprite, and
+   * glyph URLs pass through untouched (never leak the token to third-party
+   * CDNs). Kicks off a background mint immediately so the cache warms within
+   * one round-trip; the first tile or two may go unauthenticated and be
+   * retried by the renderer.
+   */
+  transformRequest(region) {
+    const r = region ?? this.defaultRegion;
+    void this.getToken(r).catch(() => void 0);
+    return (url) => {
+      if (!url.startsWith(this.tileBaseUrl) || !TILE_URL_PATH.test(url)) return void 0;
+      const token = this.peek(r);
+      if (!token) return { url };
+      return { url, headers: { Authorization: `Bearer ${token}` } };
+    };
+  }
+  /** Clear the cached token + timer for a region. */
+  invalidate(region) {
+    const r = region ?? this.defaultRegion;
+    const entry = this.cache.get(r);
+    if (entry?.refreshTimer) clearTimeout(entry.refreshTimer);
+    this.cache.delete(r);
+  }
+  /**
+   * Browser-only defense against `setTimeout` freezing while a tab is
+   * suspended (laptop sleep, mobile background, bfcache restore): proactively
+   * re-mint near-expiry entries on wake. Inert under SSR / Node / Deno.
+   */
+  registerLifecycleHandlers() {
+    if (this.lifecycleRegistered) return;
+    if (typeof document === "undefined" || typeof window === "undefined") return;
+    const onWake = () => {
+      if (document.visibilityState !== "visible") return;
+      for (const [region, entry] of this.cache.entries()) {
+        if (entry.response.expiresAt - nowSeconds() >= REFRESH_MARGIN_SECONDS) continue;
+        void this.refreshInBackground(region);
+      }
+    };
+    document.addEventListener("visibilitychange", onWake);
+    window.addEventListener("pageshow", (e) => {
+      if (e.persisted) onWake();
+    });
+    this.lifecycleRegistered = true;
+  }
+};
+
 // src/endpoints/tiles.ts
 var TilesEndpoint = class {
-  constructor(http) {
+  constructor(http, opts) {
     this.http = http;
+    this.region = opts?.region ?? DEFAULT_TILE_REGION;
+    this.tileBaseUrl = (opts?.tileBaseUrl ?? DEFAULT_TILE_BASE_URL).replace(/\/+$/, "");
   }
-  /** Full style.json URL with API key as query param */
+  region;
+  tileBaseUrl;
+  /**
+   * @deprecated CHRT has no remote `style.json` endpoint — the S-52 style is
+   * generated client-side. Use `chrt.style(opts)` to get a ready-to-use
+   * MapLibre style object instead. Calling this throws to prevent silently
+   * pointing a map at a dead URL.
+   */
   styleUrl() {
-    return `${this.http.getBaseUrl()}/tiles/style.json?key=${this.http.getApiKey()}`;
+    throw new Error(
+      "chrt.tiles.styleUrl() is no longer supported: CHRT serves no remote style.json. Use chrt.style(opts) to generate an S-52 MapLibre style object, and chrt.transformRequest() for tile auth. See https://chrt.co/docs/vector-tiles"
+    );
   }
-  /** Individual tile URL template */
-  tileUrl(z, x, y, format = "mvt") {
-    return `${this.http.getBaseUrl()}/tiles/${z}/${x}/${y}.${format}?key=${this.http.getApiKey()}`;
+  /**
+   * Vector tile URL template for the configured region, served by the
+   * tile-worker at `tiles.chrt.co`. Tiles are JWT-gated — pair this with
+   * `chrt.transformRequest()`, which attaches the `Authorization: Bearer`
+   * header. Prefer `chrt.style()`, which wires the source for you.
+   */
+  tileUrl(z, x, y) {
+    return `${this.tileBaseUrl}/v1/tiles/${this.region}/${z}/${x}/${y}.mvt`;
   }
-  /** List available tileset groups */
+  /**
+   * @deprecated Tilesets were consolidated to one PMTiles per region (2026-04);
+   * the per-group catalogue endpoint is legacy and no longer served. Render via
+   * `chrt.style()` instead, which emits a single vector source per region.
+   */
   async groups() {
     return this.http.request("/tiles/groups");
   }
@@ -326,7 +549,7 @@ function mapServerError(body, status) {
 }
 
 // src/endpoints/offline-token-manager.ts
-var REFRESH_MARGIN_SECONDS = 30;
+var REFRESH_MARGIN_SECONDS2 = 30;
 function now() {
   return Math.floor(Date.now() / 1e3);
 }
@@ -347,7 +570,7 @@ var OfflineTokenManager = class {
     }
     const key = this.cacheKey(deviceId, regions);
     const cached = this.cache.get(key);
-    if (cached && cached.expiresAt - now() > REFRESH_MARGIN_SECONDS) {
+    if (cached && cached.expiresAt - now() > REFRESH_MARGIN_SECONDS2) {
       return cached;
     }
     const inflight = this.pending.get(key);
@@ -969,47 +1192,6 @@ function dirname(p) {
   return p.slice(0, k);
 }
 
-// src/pagination.ts
-async function* paginate(fetchPage, getItems, getTotalCount, options) {
-  const pageSize = options?.pageSize ?? 100;
-  const signal = options?.signal;
-  let offset = 0;
-  while (true) {
-    if (signal?.aborted) return;
-    const response = await fetchPage(offset, signal);
-    const items = getItems(response);
-    for (const item of items) {
-      yield item;
-    }
-    if (items.length === 0) return;
-    offset += items.length;
-    const total = getTotalCount(response);
-    if (total > 0 && offset >= total) return;
-  }
-}
-
-// src/webhooks.ts
-var VALID_TYPES = /* @__PURE__ */ new Set(["cell.updated", "cell.new", "cell.deleted"]);
-function parseWebhook(body) {
-  if (typeof body !== "object" || body === null) {
-    throw new Error("Invalid webhook payload: expected an object");
-  }
-  const obj = body;
-  if (typeof obj.id !== "string") {
-    throw new Error("Invalid webhook payload: missing 'id'");
-  }
-  if (typeof obj.timestamp !== "string") {
-    throw new Error("Invalid webhook payload: missing 'timestamp'");
-  }
-  if (typeof obj.type !== "string" || !VALID_TYPES.has(obj.type)) {
-    throw new Error(`Invalid webhook payload: unknown type '${String(obj.type)}'`);
-  }
-  if (typeof obj.data !== "object" || obj.data === null) {
-    throw new Error("Invalid webhook payload: missing 'data'");
-  }
-  return obj;
-}
-
 // src/atlas/s52-colors.ts
 var S52_DAY = {
   // Depth
@@ -9374,7 +9556,7 @@ var BUILD_MINZOOM = 3;
 var BUILD_MAXZOOM = 14;
 
 // src/atlas/source-registry.ts
-var DEFAULT_TILE_BASE_URL = "https://tiles.chrt.co";
+var DEFAULT_TILE_BASE_URL2 = "https://tiles.chrt.co";
 var DEFAULT_REGION = "NOAA_ENC";
 function buildSources(opts = {}) {
   const mode = opts.mode ?? "pmtiles";
@@ -9387,7 +9569,7 @@ function buildSources(opts = {}) {
       }
     };
   }
-  const base = (opts.tileBaseUrl ?? DEFAULT_TILE_BASE_URL).replace(/\/+$/, "");
+  const base = (opts.tileBaseUrl ?? DEFAULT_TILE_BASE_URL2).replace(/\/+$/, "");
   return {
     [region]: {
       type: "vector",
@@ -11114,6 +11296,47 @@ function getStyleStats(style) {
   };
 }
 
+// src/pagination.ts
+async function* paginate(fetchPage, getItems, getTotalCount, options) {
+  const pageSize = options?.pageSize ?? 100;
+  const signal = options?.signal;
+  let offset = 0;
+  while (true) {
+    if (signal?.aborted) return;
+    const response = await fetchPage(offset, signal);
+    const items = getItems(response);
+    for (const item of items) {
+      yield item;
+    }
+    if (items.length === 0) return;
+    offset += items.length;
+    const total = getTotalCount(response);
+    if (total > 0 && offset >= total) return;
+  }
+}
+
+// src/webhooks.ts
+var VALID_TYPES = /* @__PURE__ */ new Set(["cell.updated", "cell.new", "cell.deleted"]);
+function parseWebhook(body) {
+  if (typeof body !== "object" || body === null) {
+    throw new Error("Invalid webhook payload: expected an object");
+  }
+  const obj = body;
+  if (typeof obj.id !== "string") {
+    throw new Error("Invalid webhook payload: missing 'id'");
+  }
+  if (typeof obj.timestamp !== "string") {
+    throw new Error("Invalid webhook payload: missing 'timestamp'");
+  }
+  if (typeof obj.type !== "string" || !VALID_TYPES.has(obj.type)) {
+    throw new Error(`Invalid webhook payload: unknown type '${String(obj.type)}'`);
+  }
+  if (typeof obj.data !== "object" || obj.data === null) {
+    throw new Error("Invalid webhook payload: missing 'data'");
+  }
+  return obj;
+}
+
 // src/index.ts
 var Chrt = class {
   /** Tile endpoints — styleUrl, tileUrl, groups */
@@ -11131,15 +11354,22 @@ var Chrt = class {
   featuresEp;
   queryEp;
   http;
+  tileAuth;
+  region;
+  tileBaseUrl;
   constructor(apiKeyOrConfig) {
     const config = typeof apiKeyOrConfig === "string" ? { apiKey: apiKeyOrConfig } : apiKeyOrConfig;
+    this.region = config.region ?? DEFAULT_TILE_REGION;
+    this.tileBaseUrl = config.tileBaseUrl ?? DEFAULT_TILE_BASE_URL;
     this.http = new HttpClient(config.apiKey, config.baseUrl, config.retries);
-    this.tiles = new TilesEndpoint(this.http);
+    const tileOpts = { region: this.region, tileBaseUrl: this.tileBaseUrl };
+    this.tiles = new TilesEndpoint(this.http, tileOpts);
     this.cells = new CellsEndpoint(this.http);
     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);
+    this.tileAuth = new TileAuth(this.http, tileOpts);
   }
   /* ── Convenience shortcuts ───────────────────────── */
   /** Query GeoJSON features by bounding box */
@@ -11216,28 +11446,63 @@ var Chrt = class {
     );
   }
   /* ── Map integration helpers ─────────────────────── */
-  /** Returns a style.json URL ready for Mapbox GL / MapLibre */
+  /**
+   * Build a ready-to-use MapLibre / Mapbox GL style object for CHRT's nautical
+   * charts. The default is the full IHO **S-52** portrayal; pick a palette and
+   * tweak rendering via `opts`. The returned object is a standard MapLibre
+   * style — mutate it freely, or build your own from scratch over the CHRT
+   * vector source (see `buildSources`) for a fully custom look.
+   *
+   * Pair with `transformRequest()` so tile requests carry their auth token.
+   *
+   * @example
+   * const map = new maplibregl.Map({
+   *   container: 'map',
+   *   style: chrt.style({ palette: 'DAY' }),
+   *   transformRequest: chrt.transformRequest(),
+   * });
+   *
+   * @remarks S-101 portrayal is on the roadmap; today `style()` emits S-52.
+   */
+  style(opts = {}) {
+    const { palette = "DAY", ...styleOpts } = opts;
+    return generateStyle(palette, {
+      region: this.region,
+      tileBaseUrl: this.tileBaseUrl,
+      ...styleOpts
+    });
+  }
+  /**
+   * @deprecated CHRT serves no remote `style.json`. Use {@link style} to get a
+   * MapLibre style object instead. Throws to avoid silently pointing a map at a
+   * dead URL.
+   */
   styleUrl() {
     return this.tiles.styleUrl();
   }
   /**
-   * Returns a `transformRequest` function for Mapbox GL JS / MapLibre GL JS.
-   * Injects the API key header for requests to api.chrt.co.
+   * Returns a `transformRequest` for Mapbox GL JS / MapLibre GL JS that mints a
+   * short-lived tile JWT from your API key and attaches it as
+   * `Authorization: Bearer` on requests to `tiles.chrt.co` only. Style, sprite,
+   * and glyph URLs pass through untouched. The cache warms in the background on
+   * first call, so the first tile or two may be retried by the renderer.
    *
    * @example
-   * const map = new mapboxgl.Map({
-   *   style: chrt.styleUrl(),
+   * const map = new maplibregl.Map({
+   *   style: chrt.style(),
    *   transformRequest: chrt.transformRequest(),
    * });
    */
-  transformRequest() {
-    const apiKey = this.http.getApiKey();
-    return (url) => {
-      if (url.includes("api.chrt.co")) {
-        return { url, headers: { "x-api-key": apiKey } };
-      }
-      return void 0;
-    };
+  transformRequest(opts) {
+    return this.tileAuth.transformRequest(opts?.region);
+  }
+  /**
+   * Pre-mint the tile token for a region. Optional — `transformRequest()` warms
+   * the cache automatically — but useful if you want to surface a mint error
+   * (e.g. `region_not_licensed`, `tile_quota_exceeded`) before the map loads.
+   */
+  async warmTiles(region) {
+    await this.tileAuth.getToken(region);
   }
 };
 export {
@@ -11252,6 +11517,7 @@ export {
   ChrtError,
   DEFAULT_REGION,
   DEFAULT_TILE_BASE_URL,
+  DEFAULT_TILE_REGION,
   LABELED_LAYERS,
   LABEL_BEHAVIOR,
   NAUTICAL_SYMBOLS,
@@ -11269,6 +11535,8 @@ export {
   S52_NIGHT,
   SYMBOL_GROUPS,
   SYMBOL_MAP,
+  TileAuth,
+  TileTokenError,
   applyColorTheme,
   bandFilterExpression,
   buildLabelLayer,