@superrouteca/smap 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 (unreleased)
+
+- The Web SDK as an npm package: ES module and CommonJS entry points with types, the map renderer bundled, safe to
+  import on a server.
+- The JS client as `@superrouteca/smap/client` for browsers, Node.js 18+ and workers.
+- The stylesheet as `@superrouteca/smap/smap.css`.
+- Map keys (`apiKey`) beside tokens.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goodneo Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @superrouteca/smap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Maps from Superroute's sMap service for the web: five colour schemes, labels in any language, your points, lines and
+areas drawn on the GPU (hundreds of thousands of points, clustered or not), 3D buildings and areas, and tokens that
+renew themselves. Also the JS client (no map view) for servers and workers: tokens, the nearest node, styles, tiles
+and raw reads.
+
+- Version 1.0.0, MIT licence (see `LICENSE` at the repository root)
+- Works with bundlers (Vite, webpack, Next.js and others): ES module and CommonJS entry points with types
+- Nothing else to install: the map renderer is bundled in the package
+- Importing is safe on a server; a map is created in the browser only
+
+## Installation
+
+```sh
+npm install @superrouteca/smap
+```
+
+Without a bundler, the same SDK is served by the service:
+
+```html
+<link rel="stylesheet" href="https://tile.srsr.ca/sdk/v1/smap.css">
+<script src="https://tile.srsr.ca/sdk/v1/smap.js"></script>
+```
+
+## A minimal map
+
+```js
+import { Map } from '@superrouteca/smap';
+import '@superrouteca/smap/smap.css';
+
+const map = new Map({
+  container: 'map',            // an element or its id
+  apiKey: 'smk_…',             // a map key that allows this site
+  style: 'light',              // light, white, grayscale, dark, black
+  language: 'en',
+  center: [-79.38, 43.65],     // [longitude, latitude]
+  zoom: 11,
+});
+
+await map.ready;
+map.addPoints('stops', [{ lng: -79.38, lat: 43.65, name: 'Depot' }], { cluster: true, label: 'name' });
+map.addLines('route', routeGeoJson, { color: '#16a34a', width: 5 });
+map.addPolygons('zones', zonesGeoJson, { fill: '#f97316', extrude: { height: 'height' } });
+map.setBuildings3D(true);
+map.fitLayer('stops');
+```
+
+`setStyle()` and `setLanguage()` keep your layers. Other calls: `setData`, `setVisible`, `removeLayer`, `layers`,
+`flyTo`, `setProjection`, `on` / `off` / `once`, `remove`. `map.engine` is the renderer's own map for anything the
+SDK does not wrap, and `getEngine()` gives the renderer itself.
+
+In a server-rendered page (for example Next.js), create the map in an effect or event handler, never while rendering
+on the server: `new Map()` throws outside a browser. Importing the package is fine anywhere.
+
+## Map keys and tokens
+
+- **Map key** (`apiKey: 'smk_…'`): created in the Superroute developer center, with the sites (and apps) it may be
+  used from. Safe to put in a page.
+- **Token** (`token: 'sm1.…'`, or `getToken: async () => …`): signed by your own server for a limited time.
+  With `getToken` the SDK asks for a new token two minutes before the current one expires.
+- With both, both are sent and the token is checked first. Superroute's own sites need neither.
+
+Other options: `baseUrl` (default `https://tile.srsr.ca`), `nodes` (node addresses known in advance, used while
+`baseUrl` cannot be reached), `nearest` (read from the nearest node, default true). Every other option (`pitch`,
+`bearing`, `minZoom`, `maxZoom`, `maxBounds`, …) is passed to the renderer.
+
+## The JS client
+
+```js
+import SMapClient from '@superrouteca/smap/client';   // or require('@superrouteca/smap/client')
+
+const client = new SMapClient({ baseUrl: 'https://tile.srsr.ca', apiKey: 'smk_…' });
+const style = await client.style('dark', 'fr');      // a style document
+const tile = await client.tile('basemap', 12, 1143, 1493);   // Uint8Array, or null where there is none
+```
+
+Runs wherever `fetch` exists (browsers, Node.js 18+, workers); elsewhere pass `fetch` in the options.
+
+## Data attribution
+
+The map data credit stays visible on every map, as the data licence requires.
+
+## Where the code comes from
+
+`dist/` is copied from the sMap service repository by `tools/sync-js.sh`; `dist/SOURCE.json` records the commit.
+It is never edited here. The type declarations in `types/` are kept in this repository.
+
+## Tests
+
+```sh
+npm test
+```

package/dist/SOURCE.json

@@ -0,0 +1,18 @@
+{
+  "repository": "sMap",
+  "commit": "54f7117da908fd02d8df09c85a61777299263e06",
+  "commitSubject": "Version 1.0.1 (was 1.1.0, unreleased)",
+  "uncommittedSources": false,
+  "sdkVersion": "1.0.1",
+  "engine": "maplibre-gl 5.24.0",
+  "files": {
+    "smap.mjs": "33375b7d5167ed8aab6e9351cf1e5074200d8654f91d4a5f0aa2c680ada603b8",
+    "smap.cjs": "b878b5a59c6422ed5d98e95848755e549f473574d5366b3babe0a11796825acc",
+    "smap.css": "ab1e70d59ec40465bae7e7030da2f3ccf28133fd502e62bd598eefbadfd7a732",
+    "smap-client.cjs": "fdc7ab0c8e53a2e941c5d28af51fb6c0508b2690d0beec5369a9fa94ceba0392",
+    "smap-client.mjs": "d0bd9ce3a42484888f7627d548f0cd0ff85854c2f9919be867175aae33bf8929",
+    "smap-client.d.cts": "a87a12d46ac61971a5c294afe4df49c481552aed65c7404537dacdc0afaff512",
+    "smap-client.d.mts": "009474b826fb3016b0200cbf40a969ea42ba331c6ff37cfb363c61ce54084e28",
+    "vendor-licenses.txt": "ee5fc05a0677eaf69601d2c7db0d9ecd6cc27c3abc1d0733bc9ed34707cf8ef2"
+  }
+}

package/dist/smap-client.cjs

@@ -0,0 +1,301 @@
+/* Generated by tools/sync-js.sh from the sMap repository (see SOURCE.json). Do not edit. */
+/*! sMap JS client 1.0.1 — tokens, the nearest node, styles, tiles and raw reads, without a map view. */
+/*
+ * Runs wherever `fetch` exists: browsers, Node.js 18+, workers; elsewhere (mini programs, older runtimes) pass your
+ * own `fetch`. UMD: `window.SMapClient`, `require('smap-client')`, or an AMD module.
+ *
+ *   const client = new SMapClient({ baseUrl: 'https://tile.srsr.ca', getToken: () => myServer.mapToken() });
+ *   const keyed = new SMapClient({ baseUrl: 'https://tile.srsr.ca', apiKey: 'smk_…' });   // or a map key
+ *   const tile = await client.tile('basemap', 12, 1143, 1493);   // Uint8Array (vector tile)
+ *   const style = await client.style('light', 'en');             // style document
+ *
+ * Every request goes to the nearest node that answers (asked of baseUrl, remembered for an hour) and moves to the
+ * next one when a node fails.
+ */
+(function (root, factory) {
+  if (typeof define === 'function' && define.amd) { define([], factory); }
+  else if (typeof module === 'object' && module.exports) { module.exports = factory(); }
+  else { root.SMapClient = factory(); }
+}(typeof self !== 'undefined' ? self : this, function () {
+  'use strict';
+
+  var VERSION = '1.0.1';
+  var NODE_TTL = 3600 * 1000;          // the measured order
+  var KNOWN_TTL = 30 * 86400 * 1000;   // the last node list received, used when none can be read
+
+  function unique(list) {
+    var seen = {};
+    return list.filter(function (u) { if (!u || seen[u]) { return false; } seen[u] = true; return true; });
+  }
+  var memory = {};
+
+  function store() {
+    try {
+      if (typeof localStorage !== 'undefined') { localStorage.getItem('smap'); return localStorage; }
+    } catch (e) { /* storage unavailable */ }
+    return { getItem: function (k) { return memory[k] || null; }, setItem: function (k, v) { memory[k] = v; } };
+  }
+
+  function decodeBase64Url(s) {
+    s = s.replace(/-/g, '+').replace(/_/g, '/');
+    while (s.length % 4) { s += '='; }
+    if (typeof atob === 'function') { return atob(s); }
+    return Buffer.from(s, 'base64').toString('binary');
+  }
+
+  /** Seconds since 1970 when a token expires; 0 when it cannot be read. */
+  function tokenExpiry(token) {
+    try { return JSON.parse(decodeBase64Url(String(token).split('.')[1])).exp || 0; } catch (e) { return 0; }
+  }
+
+  function SMapError(message, status, url) {
+    var e = new Error(message);
+    e.name = 'SMapError';
+    e.status = status || 0;
+    e.url = url || '';
+    return e;
+  }
+
+  /**
+   * @param {Object} options
+   * @param {string} options.baseUrl                   the public sMap address (e.g. https://tile.srsr.ca)
+   * @param {string} [options.token]                   a map token; or
+   * @param {function(): (string|Promise<string>)} [options.getToken]  called at start and before each token expires
+   * @param {string} [options.apiKey]                  a map key (`smk_…`); with a token both are sent (token first)
+   * @param {string[]} [options.nodes]                 node URLs known in advance (used while baseUrl is down)
+   * @param {boolean} [options.nearest=true]           read from the nearest node
+   * @param {function} [options.fetch]                 a fetch implementation (default: the global one)
+   * @param {number} [options.timeoutMs=15000]         per request
+   */
+  function SMapClient(options) {
+    if (!(this instanceof SMapClient)) { return new SMapClient(options); }
+    options = options || {};
+    if (!options.baseUrl) { throw SMapError('sMap: baseUrl is required'); }
+    this.baseUrl = String(options.baseUrl).replace(/\/$/, '');
+    this._fetch = options.fetch || (typeof fetch === 'function' ? fetch.bind(typeof self !== 'undefined' ? self : globalThis) : null);
+    if (!this._fetch) { throw SMapError('sMap: no fetch available; pass options.fetch'); }
+    this._token = options.token || null;
+    this._getToken = options.getToken || null;
+    this._apiKey = options.apiKey || null;
+    this._nearest = options.nearest !== false;
+    this._seeds = (options.nodes || []).map(function (u) { return String(u).replace(/\/$/, ''); });
+    this._timeout = options.timeoutMs || 15000;
+    this._nodes = null;      // ordered: nearest first
+    this._picking = null;
+    this._tokening = null;
+  }
+
+  SMapClient.version = VERSION;
+  SMapClient.tokenExpiry = tokenExpiry;
+
+  SMapClient.prototype._timed = function (url, init, ms) {
+    var ctrl = typeof AbortController !== 'undefined' ? new AbortController() : null;
+    var timer = ctrl ? setTimeout(function () { ctrl.abort(); }, ms) : null;
+    init = init || {};
+    if (ctrl) { init.signal = ctrl.signal; }
+    return this._fetch(url, init).then(function (res) { clearTimeout(timer); return res; }, function (e) { clearTimeout(timer); throw e; });
+  };
+
+  /** The token to send now, asking getToken again two minutes before it expires. */
+  SMapClient.prototype.token = function () {
+    var self = this;
+    var exp = this._token ? tokenExpiry(this._token) : 0;
+    var fresh = this._token && (!exp || exp - Date.now() / 1000 > 120);
+    if (fresh || !this._getToken) { return Promise.resolve(this._token); }
+    if (!this._tokening) {
+      this._tokening = Promise.resolve(this._getToken()).then(function (t) {
+        self._token = t;
+        self._tokening = null;
+        return t;
+      }, function (e) { self._tokening = null; throw e; });
+    }
+    return this._tokening;
+  };
+
+  /**
+   * The nodes in the order they are tried: nearest first, then the others; baseUrl alone when nearest is off or the
+   * list cannot be read.
+   *
+   * @returns {Promise<string[]>}
+   */
+  SMapClient.prototype.nodes = function () {
+    var self = this;
+    if (this._nodes) { return Promise.resolve(this._nodes); }
+    if (!this._nearest) { this._nodes = [this.baseUrl]; return Promise.resolve(this._nodes); }
+    if (this._picking) { return this._picking; }
+    var key = 'smap.nodes:' + this.baseUrl;
+    var storage = store();
+    var saved = null;
+    try { saved = JSON.parse(storage.getItem(key) || 'null'); } catch (e) { saved = null; }
+    if (saved && saved.urls && saved.urls.length && Date.now() - saved.at < NODE_TTL) {
+      this._nodes = saved.urls;
+      return Promise.resolve(this._nodes);
+    }
+    // Every node this client knows of: the kept list (30 days), the seed list, then baseUrl.
+    var kept = saved && saved.known && Date.now() - (saved.knownAt || 0) < KNOWN_TTL ? saved.known : [];
+    var known = unique([this.baseUrl].concat(this._seeds, kept));
+    this._picking = this._discover(known)
+      .then(function (list) {
+        var urls = list || unique(self._seeds.concat(kept));
+        if (urls.length === 0) { return { order: [self.baseUrl], known: null }; }
+        return self._measure(urls).then(function (order) { return { order: order, known: list }; });
+      })
+      .then(function (r) {
+        self._nodes = r.order;
+        self._picking = null;
+        // An order is remembered for the hour only when a node list was read; a guess made while nothing answered
+        // is tried again by the next client instead of being kept.
+        var record = { urls: r.known ? r.order : [], at: r.known ? Date.now() : 0, known: r.known || kept, knownAt: r.known ? Date.now() : (saved && saved.knownAt) || 0 };
+        try { storage.setItem(key, JSON.stringify(record)); } catch (e) { /* ignore */ }
+        return r.order;
+      });
+    return this._picking;
+  };
+
+  /** Asks each node in turn for the node list (any node answers the whole list); null when none answers. */
+  SMapClient.prototype._discover = function (candidates) {
+    var self = this;
+    function ask(i) {
+      if (i >= candidates.length) { return Promise.resolve(null); }
+      return self._timed(candidates[i] + '/v1/nodes', {}, 2000)
+        .then(function (res) { return res.ok ? res.json() : null; })
+        .then(function (body) {
+          var urls = ((body && body.nodes) || []).map(function (n) { return String(n.url).replace(/\/$/, ''); });
+          return urls.length ? urls : ask(i + 1);
+        }, function () { return ask(i + 1); });
+    }
+    return ask(0);
+  };
+
+  /** Times one small request to each node: fastest first, silent ones after, baseUrl last when not listed. */
+  SMapClient.prototype._measure = function (urls) {
+    var self = this;
+    return Promise.all(urls.map(function (url) {
+      var t0 = Date.now();
+      return self._timed(url + '/v1/ping', { cache: 'no-store' }, 1500)
+        .then(function (res) { return { url: url, ms: res.ok ? Date.now() - t0 : Infinity }; }, function () { return { url: url, ms: Infinity }; });
+    })).then(function (timed) {
+      timed.sort(function (a, b) { return a.ms - b.ms; });
+      var order = timed.map(function (t) { return t.url; });
+      if (order.indexOf(self.baseUrl) < 0) { order.push(self.baseUrl); }
+      return order;
+    });
+  };
+
+  /** Forgets the chosen node order, so the next request measures again. */
+  SMapClient.prototype.resetNodes = function () {
+    this._nodes = null;
+    var key = 'smap.nodes:' + this.baseUrl;
+    try {
+      var saved = JSON.parse(store().getItem(key) || 'null');
+      // The kept node list survives a reset; only the measured order is forgotten.
+      store().setItem(key, JSON.stringify(saved ? { urls: [], at: 0, known: saved.known, knownAt: saved.knownAt } : null));
+    } catch (e) { /* ignore */ }
+  };
+
+  /**
+   * GET `path` from the nearest node that answers, with the token; a node that fails (network error, 5xx) is moved
+   * to the end and the next one is tried. 4xx answers are final.
+   *
+   * @param {string} path      starting with /
+   * @param {Object} [headers]
+   * @returns {Promise<Response>}
+   */
+  SMapClient.prototype.request = function (path, headers) {
+    var self = this;
+    return Promise.all([this.nodes(), this.token()]).then(function (r) {
+      var nodes = r[0].slice();
+      var token = r[1];
+      var last = null;
+      function attempt(i) {
+        if (i >= nodes.length) { throw last || SMapError('sMap: no node answered', 0, path); }
+        var h = {};
+        for (var k in (headers || {})) { if (Object.prototype.hasOwnProperty.call(headers, k)) { h[k] = headers[k]; } }
+        if (token) { h.Authorization = 'Bearer ' + token; }
+        if (self._apiKey) { h['X-SMap-Key'] = self._apiKey; }
+        var url = nodes[i] + path;
+        return self._timed(url, { headers: h }, self._timeout).then(function (res) {
+          if (res.status >= 500) {
+            last = SMapError('sMap: HTTP ' + res.status, res.status, url);
+            self._demote(nodes[i]);
+            return attempt(i + 1);
+          }
+          if (!res.ok && res.status !== 206) {
+            return res.text().then(function (text) { throw SMapError('sMap: ' + (text || ('HTTP ' + res.status)), res.status, url); });
+          }
+          return res;
+        }, function (e) {
+          last = SMapError('sMap: ' + (e && e.message ? e.message : 'network error'), 0, url);
+          self._demote(nodes[i]);
+          return attempt(i + 1);
+        });
+      }
+      return attempt(0);
+    });
+  };
+
+  SMapClient.prototype._demote = function (url) {
+    if (!this._nodes || this._nodes.length < 2) { return; }
+    var i = this._nodes.indexOf(url);
+    if (i >= 0) { this._nodes.splice(i, 1); this._nodes.push(url); }
+  };
+
+  function bytes(res) { return res.arrayBuffer().then(function (b) { return new Uint8Array(b); }); }
+
+  // A map key also goes in the query of styles and TileJSON: the service carries it into their tile URLs, so a
+  // renderer given the document reads its tiles with the key.
+  SMapClient.prototype._withKey = function (path) {
+    if (!this._apiKey) { return path; }
+    return path + (path.indexOf('?') >= 0 ? '&' : '?') + 'key=' + encodeURIComponent(this._apiKey);
+  };
+
+  /**
+   * A style document ('light', 'white', 'grayscale', 'dark', 'black') with labels in `language`.
+   * Its tile URLs point at the node that answered.
+   */
+  SMapClient.prototype.style = function (flavor, language) {
+    var q = language ? '?lang=' + encodeURIComponent(language) : '';
+    return this.request(this._withKey('/v1/styles/' + encodeURIComponent(flavor || 'light') + q)).then(function (r) { return r.json(); });
+  };
+
+  /** TileJSON of a source (bounds, zooms, layers, tile URL template). */
+  SMapClient.prototype.tileJSON = function (source) {
+    return this.request(this._withKey('/v1/tiles/' + encodeURIComponent(source || 'basemap'))).then(function (r) { return r.json(); });
+  };
+
+  /** One vector tile as bytes; null where the source has no tile (204 / 404). */
+  SMapClient.prototype.tile = function (source, z, x, y) {
+    var path = '/v1/tiles/' + encodeURIComponent(source) + '/' + (z | 0) + '/' + (x | 0) + '/' + (y | 0);
+    return this.request(path).then(function (r) { return r.status === 204 ? null : bytes(r); }, function (e) {
+      if (e && e.status === 404) { return null; }
+      throw e;
+    });
+  };
+
+  /** Raw bytes `[start, end]` (inclusive) of a source's archive, where your access allows raw reads. */
+  SMapClient.prototype.range = function (source, start, end) {
+    return this.request('/' + encodeURIComponent(source) + '.pmtiles', { Range: 'bytes=' + start + '-' + end }).then(bytes);
+  };
+
+  /** A font glyph range (`0-255.pbf` style), for renderers that load fonts themselves. */
+  SMapClient.prototype.glyphs = function (fontstack, range) {
+    return this.request('/v1/fonts/' + encodeURIComponent(fontstack) + '/' + range + '.pbf').then(bytes);
+  };
+
+  /**
+   * Headers and URL rewriting for a renderer that fetches by itself: returns the URL unchanged plus the
+   * Authorization (and map key) headers to add for sMap URLs; none for any other host.
+   */
+  SMapClient.prototype.authorize = function (url) {
+    var self = this;
+    return this.token().then(function (token) {
+      var ours = url.indexOf(self.baseUrl) === 0 || self._seeds.concat(self._nodes || []).some(function (n) { return url.indexOf(n) === 0; });
+      var headers = {};
+      if (ours && token) { headers.Authorization = 'Bearer ' + token; }
+      if (ours && self._apiKey) { headers['X-SMap-Key'] = self._apiKey; }
+      return { url: url, headers: headers };
+    });
+  };
+
+  return SMapClient;
+}));

package/dist/smap-client.d.cts

@@ -0,0 +1,43 @@
+// Generated by tools/sync-js.sh. Do not edit.
+// sMap JS client — type declarations (UMD: `require('smap-client')`, `import SMapClient from …`, `window.SMapClient`).
+declare namespace SMapClient {
+  interface Options {
+    /** The public sMap address, e.g. https://tile.srsr.ca */
+    baseUrl: string;
+    token?: string;
+    getToken?: () => string | Promise<string>;
+    /** A map key (`smk_…`); with a token both are sent and the token is checked first. */
+    apiKey?: string;
+    /** Node URLs known in advance, used while baseUrl is down. */
+    nodes?: string[];
+    /** Read from the nearest node (default true). */
+    nearest?: boolean;
+    fetch?: typeof fetch;
+    /** Per request, default 15000. */
+    timeoutMs?: number;
+  }
+  type StyleFlavor = 'light' | 'white' | 'grayscale' | 'dark' | 'black';
+  interface SMapError extends Error {
+    status: number;
+    url: string;
+  }
+}
+
+declare class SMapClient {
+  constructor(options: SMapClient.Options);
+  static readonly version: string;
+  static tokenExpiry(token: string): number;
+  readonly baseUrl: string;
+  token(): Promise<string | null>;
+  nodes(): Promise<string[]>;
+  resetNodes(): void;
+  request(path: string, headers?: Record<string, string>): Promise<Response>;
+  style(flavor?: SMapClient.StyleFlavor, language?: string): Promise<Record<string, unknown>>;
+  tileJSON(source?: string): Promise<Record<string, unknown>>;
+  tile(source: string, z: number, x: number, y: number): Promise<Uint8Array | null>;
+  range(source: string, start: number, end: number): Promise<Uint8Array>;
+  glyphs(fontstack: string, range: string): Promise<Uint8Array>;
+  authorize(url: string): Promise<{ url: string; headers: Record<string, string> }>;
+}
+
+export = SMapClient;

package/dist/smap-client.d.mts

@@ -0,0 +1,44 @@
+// Generated by tools/sync-js.sh. Do not edit.
+// sMap JS client — type declarations (UMD: `require('smap-client')`, `import SMapClient from …`, `window.SMapClient`).
+declare namespace SMapClient {
+  interface Options {
+    /** The public sMap address, e.g. https://tile.srsr.ca */
+    baseUrl: string;
+    token?: string;
+    getToken?: () => string | Promise<string>;
+    /** A map key (`smk_…`); with a token both are sent and the token is checked first. */
+    apiKey?: string;
+    /** Node URLs known in advance, used while baseUrl is down. */
+    nodes?: string[];
+    /** Read from the nearest node (default true). */
+    nearest?: boolean;
+    fetch?: typeof fetch;
+    /** Per request, default 15000. */
+    timeoutMs?: number;
+  }
+  type StyleFlavor = 'light' | 'white' | 'grayscale' | 'dark' | 'black';
+  interface SMapError extends Error {
+    status: number;
+    url: string;
+  }
+}
+
+declare class SMapClient {
+  constructor(options: SMapClient.Options);
+  static readonly version: string;
+  static tokenExpiry(token: string): number;
+  readonly baseUrl: string;
+  token(): Promise<string | null>;
+  nodes(): Promise<string[]>;
+  resetNodes(): void;
+  request(path: string, headers?: Record<string, string>): Promise<Response>;
+  style(flavor?: SMapClient.StyleFlavor, language?: string): Promise<Record<string, unknown>>;
+  tileJSON(source?: string): Promise<Record<string, unknown>>;
+  tile(source: string, z: number, x: number, y: number): Promise<Uint8Array | null>;
+  range(source: string, start: number, end: number): Promise<Uint8Array>;
+  glyphs(fontstack: string, range: string): Promise<Uint8Array>;
+  authorize(url: string): Promise<{ url: string; headers: Record<string, string> }>;
+}
+
+export { SMapClient };
+export default SMapClient;