@nways/maps 0.0.0-stage → 1.0.0

package/index.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 N-WAYS LIMITED
+// The N-Ways Maps SDK for the web, version 1: a MapLibre GL JS map with
+// N-Ways' hosted style, tiles and fonts and your API key on every request,
+// plus small helpers for the N-Ways APIs (geocoding, routes, places, static
+// maps, an address autocomplete box).
+//
+//   import { createMap, createClient } from '@nways/maps'
+//   const map = createMap({ container: 'map', key: 'YOUR_API_KEY', center: [3.3792, 6.5244], zoom: 12 })
+//
+// MapLibre GL JS (6 or later) and pmtiles are peer dependencies: bring your
+// own (npm, or an import map), or load the standalone build from
+// https://nways.ng/sdk/v1/nways-maps.standalone.js. See https://nways.ng/developers/maps-sdk.
+import * as maplibregl from 'maplibre-gl'
+import { Protocol } from 'pmtiles'
+import { ATTRIBUTION, NWAYS_ORIGIN, STYLE_IDS, THEMES, TILESETS, buildStyle, styleUrl, withKey } from './style.js'
+import { ApiError, createClient, PATHS, sessionToken, staticMapUrl } from './services.js'
+import { attachAutocomplete, suggestionsOf } from './autocomplete.js'
+
+export { ATTRIBUTION, NWAYS_ORIGIN, STYLE_IDS, THEMES, TILESETS, buildStyle, styleUrl, withKey }
+export { ApiError, createClient, PATHS, sessionToken, staticMapUrl, attachAutocomplete, suggestionsOf }
+// MapLibre itself (markers, popups, controls), so the standalone build needs no other import.
+export { maplibregl }
+
+export const VERSION = '1.0.0'
+
+let registered = false
+// Each map's style options, so setTheme keeps its key, origin, language and source.
+const optionsOf = new WeakMap()
+
+/** Lets MapLibre read PMTiles archives (once per page). */
+function registerPMTiles() {
+  if (registered) return
+  maplibregl.addProtocol('pmtiles', new Protocol().tile)
+  registered = true
+}
+
+/** The style a map starts with: N-Ways' hosted style (default), the built-in one, or the caller's own. */
+function styleFor({ key, theme, origin, lang, style }) {
+  if (style === 'bundled') return buildStyle({ key, theme, origin, lang })
+  if (style === undefined || style === 'hosted') return styleUrl({ key, theme, origin, lang })
+  return style
+}
+
+/**
+ * A message over the map when N-Ways refuses it (a key that's missing,
+ * restricted elsewhere or over its quota), so the page doesn't stay blank.
+ */
+function showRefusal(map, err) {
+  const box = map.getContainer()
+  if (box.querySelector('.nways-refused')) return
+  const note = document.createElement('div')
+  note.className = 'nways-refused'
+  note.setAttribute('role', 'alert')
+  note.style.cssText =
+    'position:absolute;inset:auto 12px 12px 12px;z-index:5;padding:10px 12px;border-radius:8px;font:13px/1.4 system-ui,sans-serif;' +
+    'background:rgba(20,24,28,.92);color:#fff;box-shadow:0 2px 8px rgba(0,0,0,.3)'
+  const reason = err.reason ? ` (${err.reason})` : ''
+  note.textContent = `This map can’t load: N-Ways refused the API key${reason}. `
+  const link = document.createElement('a')
+  link.href = 'https://nways.ng/developers/errors#key-errors'
+  link.textContent = 'What to do'
+  link.style.color = '#9fd3b5'
+  note.append(link)
+  box.append(note)
+}
+
+/** Asks N-Ways why a request was refused (the error's reason), for the console and the note. */
+async function refusalOf(url) {
+  try {
+    const res = await fetch(url)
+    if (res.ok) return null
+    const body = await res.json().catch(() => null)
+    return { status: res.status, reason: body?.error?.reason, message: body?.error?.message }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A map of Nigeria, Ghana, Benin and Togo. Takes MapLibre's map options plus
+ * `key` (your N-Ways API key), `theme` ('light' or 'dark'), `lang` ('en' or 'fr'),
+ * `style` ('hosted' (default), 'bundled', or your own style or URL) and
+ * `showErrors` (default true: a note over the map when the key is refused).
+ */
+export function createMap(options) {
+  const { key, theme = 'light', lang = 'en', origin = NWAYS_ORIGIN, style, showErrors = true, ...rest } = options ?? {}
+  if (!key) console.warn('N-Ways: no API key. Pass createMap({ key }); requests from your website without one are refused.')
+  if (!THEMES[theme]) throw new Error(`N-Ways: unknown theme "${theme}" (light or dark)`)
+  registerPMTiles()
+  const opts = { key, theme, origin, lang, style }
+  const map = new maplibregl.Map({
+    center: [3.3792, 6.5244], // Lagos
+    zoom: 11,
+    maxBounds: [
+      [-4.5, 2.5],
+      [16.5, 15.5],
+    ],
+    ...rest,
+    style: styleFor(opts),
+    // Anything the map asks N-Ways for (style, tiles, fonts, sprites) carries the key; nothing else does.
+    transformRequest: (url, kind) => {
+      const own = rest.transformRequest?.(url, kind)
+      return own ?? { url: withKey(url, key, origin) }
+    },
+  })
+  optionsOf.set(map, opts)
+  if (rest.attributionControl !== false) {
+    // The credit stays even if a custom style forgets it (OpenStreetMap's licence requires it).
+    map.on('load', () => {
+      const credits = Object.values(map.getStyle()?.sources ?? {}).map((s) => s.attribution ?? '')
+      if (!credits.some((c) => c.includes('OpenStreetMap'))) map.addControl(new maplibregl.AttributionControl({ customAttribution: ATTRIBUTION }))
+    })
+  }
+  // A refused key leaves a blank map: say why in the console (and over the map).
+  // If the hosted style can't be had for another reason, fall back to the built-in one.
+  let told = false
+  let fellBack = false
+  let styled = false
+  map.once('style.load', () => (styled = true))
+  map.on('error', async (e) => {
+    const err = e?.error ?? {}
+    // Tile archives (PMTiles) report only "Bad response code: 403" in the message.
+    const status = err.status ?? Number(/\b(401|403|429)\b/.exec(String(err.message ?? ''))?.[1])
+    const hosted = (optionsOf.get(map)?.style ?? 'hosted') === 'hosted'
+    if ([401, 403, 429].includes(status)) {
+      if (told) return
+      told = true
+      const why = err.url ? await refusalOf(err.url) : null
+      const reason = why?.reason ? ` ${why.reason}: ${why.message ?? ''}` : ''
+      console.error(`N-Ways: a map request was refused (HTTP ${status}).${reason} Check the key's restrictions: https://nways.ng/developers/errors#key-errors`)
+      if (showErrors && typeof document !== 'undefined') showRefusal(map, { status, reason: why?.reason })
+      return
+    }
+    // Any other failure before the hosted style has loaded (unreachable, not JSON): the built-in style.
+    if (hosted && !fellBack && !styled) {
+      fellBack = true
+      optionsOf.get(map).style = 'bundled'
+      console.warn('N-Ways: the hosted style is unavailable; using the built-in style.')
+      map.setStyle(buildStyle({ key, theme: optionsOf.get(map).theme, origin, lang }), { diff: false })
+    }
+  })
+  return map
+}
+
+/** Switches a map made by createMap between light and dark. */
+export function setTheme(map, theme) {
+  const opts = optionsOf.get(map)
+  if (!opts) throw new Error('N-Ways: setTheme needs a map made by createMap')
+  if (!THEMES[theme]) throw new Error(`N-Ways: unknown theme "${theme}" (light or dark)`)
+  opts.theme = theme
+  if (opts.style !== undefined && opts.style !== 'hosted' && opts.style !== 'bundled') return // the caller's own style
+  map.setStyle(styleFor(opts))
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@nways/maps",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "N-Ways Maps SDK for the web: MapLibre GL JS maps of Nigeria, Ghana, Benin and Togo with N-Ways' style, tiles and API key, plus geocoding, routes, places, static maps and an address autocomplete box.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./style": {
+      "types": "./style.d.ts",
+      "default": "./style.js"
+    },
+    "./services": {
+      "types": "./services.d.ts",
+      "default": "./services.js"
+    },
+    "./autocomplete": {
+      "types": "./autocomplete.d.ts",
+      "default": "./autocomplete.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "style.js",
+    "style.d.ts",
+    "services.js",
+    "services.d.ts",
+    "autocomplete.js",
+    "autocomplete.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@types/geojson": "^7946.0.16"
+  },
+  "peerDependencies": {
+    "maplibre-gl": ">=6 <7",
+    "pmtiles": ">=4 <5"
+  },
+  "keywords": [
+    "maps",
+    "maplibre",
+    "nigeria",
+    "ghana",
+    "benin",
+    "togo",
+    "geocoding",
+    "routing",
+    "postcodes",
+    "west africa"
+  ],
+  "homepage": "https://nways.ng/developers",
+  "bugs": {
+    "email": "hello@nways.ng"
+  },
+  "author": "N-Ways <hello@nways.ng>",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/services.d.ts

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 N-WAYS LIMITED
+import type { FeatureCollection } from 'geojson'
+
+/** A GeoJSON point: coordinates are [lng, lat]. */
+export interface GeoPoint {
+  type: 'Point'
+  coordinates: [number, number]
+}
+
+/** A point: { lat, lng }, [lng, lat] (GeoJSON order) or a GeoJSON Point. */
+export type LatLng = { lat: number; lng: number } | [number, number] | GeoPoint
+
+/** Where a route starts, stops or ends: a point, a NIPOST postcode, a GhanaPost GPS address or a Plus Code. */
+export type Waypoint =
+  | LatLng
+  | { lat: number; lng: number; heading?: number }
+  | { postcode: string }
+  | { ghanaPost: string }
+  | { plusCode: string }
+
+export const PATHS: Record<
+  | 'geocode' | 'reverse' | 'postcode' | 'ghanapost' | 'autocomplete' | 'validateAddress'
+  | 'placesNearby' | 'placesSearch' | 'place' | 'route' | 'matrix' | 'optimize' | 'fares' | 'traffic' | 'staticMap',
+  string
+>
+
+/** An error answer from N-Ways. */
+export class ApiError extends Error {
+  /** HTTP status: 400, 401, 403, 404, 429, 503… */
+  status: number
+  /** The stable reason: API_KEY_INVALID, RATE_LIMIT_EXCEEDED, no_route… (null if none). */
+  reason: string | null
+  /** The status word: PERMISSION_DENIED, RESOURCE_EXHAUSTED… (null if none). */
+  statusText: string | null
+  /** Seconds to wait before trying again (429 and 503). */
+  retryAfter?: number
+  /** The whole answer. */
+  body: unknown
+}
+
+export interface Place {
+  id: string
+  name: string
+  type?: string
+  category?: string
+  location: GeoPoint
+  formattedAddress?: string
+  postcode?: string
+  ghanaPost?: string
+  plusCode?: string
+  context?: string
+  country?: 'NG' | 'GH' | 'BJ' | 'TG' | string
+  bbox?: [number, number, number, number]
+  attribution?: string
+  [field: string]: unknown
+}
+
+export interface Suggestion {
+  id?: string
+  name: string
+  context: string
+  location?: GeoPoint
+  [field: string]: unknown
+}
+
+export interface Route {
+  distanceM: number
+  durationS: number
+  /** The line, as a GeoJSON LineString ([lng, lat] pairs). */
+  geometry: { type: 'LineString'; coordinates: [number, number][] }
+  [field: string]: unknown
+}
+
+export interface RouteRequest {
+  origin: Waypoint
+  destination: Waypoint
+  intermediates?: Waypoint[]
+  /** drive, van, okada, keke, danfo, walk, bicycle, train, boat… (see the Routes docs). */
+  mode?: string
+  alternatives?: boolean
+  routingPreference?: 'traffic_unaware' | 'traffic_aware'
+  departAt?: string
+  avoid?: ('tolls' | 'highways' | 'bad_roads')[]
+  fares?: boolean
+  lang?: 'en' | 'fr'
+  [field: string]: unknown
+}
+
+type Opts = { signal?: AbortSignal }
+
+export interface MatrixElement {
+  originIndex: number
+  destinationIndex: number
+  /** OK, or ROUTE_NOT_FOUND. */
+  status: string
+  durationS: number
+  distanceM: number
+}
+
+export interface MatrixResponse {
+  elements: MatrixElement[]
+  [k: string]: unknown
+}
+
+export interface StaticMapOptions {
+  key?: string
+  origin?: string
+  center?: LatLng
+  zoom?: number
+  /** Width and height in CSS pixels (default 640×400). */
+  size?: [number, number]
+  scale?: 1 | 2
+  theme?: 'light' | 'dark'
+  format?: 'png' | 'jpg'
+  /** Up to 100. color: a name (red, green, blue, orange…) or #RRGGBB; label: one letter or digit. */
+  markers?: { at: LatLng; color?: string; label?: string; size?: 'tiny' | 'small' | 'mid' }[]
+  /** Up to 10 lines (or areas, with fillColor). weight: 0 to 30 px. */
+  paths?: StaticPath[]
+  /** One path (same as paths: [path]). */
+  path?: StaticPath
+}
+
+export interface StaticPath {
+  points: LatLng[]
+  color?: string
+  weight?: number
+  fillColor?: string
+}
+
+export interface Client {
+  url(name: keyof typeof PATHS, query?: Record<string, unknown>, params?: Record<string, unknown>): string
+  geocode(q: string, o?: Opts & { near?: LatLng; country?: string | string[]; limit?: number; fields?: string | string[]; lang?: 'en' | 'fr' }): Promise<{ results: Place[]; [k: string]: unknown }>
+  reverse(at: LatLng, o?: Opts & { radius?: number; lang?: 'en' | 'fr' }): Promise<Record<string, unknown> | null>
+  postcode(code: string, o?: Opts): Promise<Record<string, unknown>>
+  ghanapost(code: string, o?: Opts): Promise<Record<string, unknown>>
+  autocomplete(q: string, o?: Opts & { session?: string; near?: LatLng; types?: string | string[]; country?: string | string[]; limit?: number }): Promise<{ suggestions?: Suggestion[]; [k: string]: unknown }>
+  validateAddress(address: string, o?: Opts & { country?: string; near?: LatLng }): Promise<Record<string, unknown>>
+  placesNearby(at: LatLng, o?: Opts & { category?: string; q?: string; radius?: number; limit?: number; pageToken?: string; fields?: string | string[] }): Promise<{ places: Place[]; nextPageToken?: string; [k: string]: unknown }>
+  placesSearch(q: string, o?: Opts & { near?: LatLng; radius?: number; limit?: number; fields?: string | string[] }): Promise<{ places: Place[]; nextPageToken?: string; [k: string]: unknown }>
+  place(id: string, o?: Opts & { fields?: string | string[] }): Promise<Place>
+  route(req: RouteRequest, o?: Opts): Promise<{ routes: Route[]; [k: string]: unknown }>
+  matrix(req: { origins: Waypoint[]; destinations: Waypoint[]; mode?: string; [k: string]: unknown }, o?: Opts): Promise<MatrixResponse>
+  optimize(
+    req: { stops: { id: string; location: Waypoint; demand?: number; serviceS?: number }[]; vehicles: { id: string; start: Waypoint; end?: Waypoint; capacity?: number }[]; mode?: string; [k: string]: unknown },
+    o?: Opts,
+  ): Promise<Record<string, unknown>>
+  fares(from: LatLng, to: LatLng, o?: Opts & { mode?: string | string[]; at?: string; distanceM?: number; durationS?: number; charter?: boolean; rain?: boolean }): Promise<Record<string, unknown>>
+  traffic(bbox: [number, number, number, number], o?: Opts): Promise<FeatureCollection>
+  staticMapUrl(o: Omit<StaticMapOptions, 'key' | 'origin'>): string
+}
+
+export interface ClientOptions {
+  key?: string
+  /** Default https://nways.ng. */
+  origin?: string
+  lang?: 'en' | 'fr'
+  fetch?: typeof fetch
+  headers?: Record<string, string>
+}
+
+export function createClient(options?: ClientOptions): Client
+export function staticMapUrl(o: StaticMapOptions): string
+export function sessionToken(): string

package/services.js

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 N-WAYS LIMITED
+// Small helpers for the N-Ways APIs, for web pages and Node 18+ (anything with
+// fetch): geocoding, reverse geocoding, postcodes, places, routes, the route
+// matrix, fares, autocomplete, address validation and static map addresses.
+// Every call carries your key; errors come back as ApiError with N-Ways'
+// machine-readable reason (API_KEY_HTTP_REFERRER_BLOCKED, RATE_LIMIT_EXCEEDED…).
+//
+//   const nways = createClient({ key: 'YOUR_API_KEY' })
+//   const { results } = await nways.geocode('Allen Avenue, Ikeja')
+import { NWAYS_ORIGIN, withKey } from './style.js'
+
+/**
+ * Where each API answers, relative to the origin. One table, so a move (for
+ * example from the preview /v1 addresses to /maps/v1) is a one-line change.
+ */
+export const PATHS = {
+  geocode: '/maps/v1/geocode',
+  reverse: '/maps/v1/reverse',
+  postcode: '/maps/v1/postcodes/{code}',
+  ghanapost: '/maps/v1/ghanapost/{code}',
+  autocomplete: '/maps/v1/autocomplete',
+  validateAddress: '/maps/v1/addresses/validate',
+  placesNearby: '/maps/v1/places/nearby',
+  placesSearch: '/maps/v1/places/search',
+  place: '/maps/v1/places/{id}',
+  route: '/maps/v1/routes/compute',
+  matrix: '/maps/v1/routes/matrix',
+  optimize: '/maps/v1/routes/optimize',
+  fares: '/maps/v1/fares/estimate',
+  traffic: '/maps/v1/traffic',
+  staticMap: '/maps/v1/staticmap',
+}
+
+// The APIs that take a language (lang=en|fr): in the query, or in the JSON body.
+const LANG_QUERY = new Set(['geocode', 'reverse', 'autocomplete', 'placesSearch', 'fares'])
+const LANG_BODY = new Set(['route', 'optimize', 'validateAddress'])
+
+/** An error answer from N-Ways: HTTP status, the stable reason, the message, and when to retry (seconds). */
+export class ApiError extends Error {
+  constructor(status, body, retryAfter) {
+    const e = body?.error
+    const env = e && typeof e === 'object' ? e : null
+    super(env?.message ?? (typeof e === 'string' ? e : `N-Ways answered HTTP ${status}`))
+    this.name = 'ApiError'
+    this.status = status
+    this.reason = env?.reason ?? body?.code ?? null
+    this.statusText = env?.status ?? null
+    this.retryAfter = retryAfter
+    this.body = body
+  }
+}
+
+const fill = (path, params) => path.replace(/\{(\w+)\}/g, (_, k) => encodeURIComponent(String(params[k])))
+/** A point as `lat,lng`: from { lat, lng }, [lng, lat] or a GeoJSON Point. */
+const ll = (p) => {
+  const c = Array.isArray(p) ? p : p?.type === 'Point' ? p.coordinates : null
+  return c ? `${c[1]},${c[0]}` : `${p.lat},${p.lng}`
+}
+
+/** A random session token for autocomplete (one per search, ended by the pick). */
+export function sessionToken() {
+  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID()
+  return Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join('')
+}
+
+/**
+ * A client for the N-Ways APIs: `{ key, origin?, lang?, fetch?, headers? }`.
+ * `lang: 'fr'` asks for French names and instructions where there are any.
+ */
+export function createClient(options = {}) {
+  const { key, origin = NWAYS_ORIGIN, lang, headers: extra = {} } = options
+  const doFetch = options.fetch ?? globalThis.fetch?.bind(globalThis)
+  if (!doFetch) throw new Error('N-Ways: no fetch here; pass createClient({ fetch })')
+
+  /** The full address of an API with its query (and the key), without fetching it. */
+  function url(name, query = {}, params = {}) {
+    const u = new URL(origin + fill(PATHS[name], params))
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null || v === '') continue
+      u.searchParams.set(k, Array.isArray(v) ? v.join(',') : String(v))
+    }
+    if (lang && LANG_QUERY.has(name) && !u.searchParams.has('lang')) u.searchParams.set('lang', lang)
+    return withKey(u.toString(), key, origin)
+  }
+
+  async function call(name, { query, params, body, signal } = {}) {
+    const init = { method: body === undefined ? 'GET' : 'POST', headers: { Accept: 'application/json', ...extra }, signal }
+    if (body !== undefined) {
+      init.headers['Content-Type'] = 'application/json'
+      init.body = JSON.stringify(lang && LANG_BODY.has(name) && body.lang === undefined ? { ...body, lang } : body)
+    }
+    const res = await doFetch(url(name, query, params), init)
+    if (res.status === 204) return null
+    const text = await res.text()
+    let data = null
+    try {
+      data = text ? JSON.parse(text) : null
+    } catch {
+      data = { error: text }
+    }
+    if (!res.ok) {
+      const ra = Number(res.headers.get('Retry-After'))
+      throw new ApiError(res.status, data, Number.isFinite(ra) && ra > 0 ? ra : undefined)
+    }
+    return data
+  }
+
+  return {
+    url,
+    /** Places, addresses, postcodes and GhanaPost codes for what someone typed. */
+    geocode: (q, o = {}) =>
+      call('geocode', { query: { q, near: o.near && ll(o.near), country: o.country, limit: o.limit, fields: o.fields, lang: o.lang }, signal: o.signal }),
+    /** What's at a point (null when nothing is known there). */
+    reverse: (at, o = {}) => {
+      const [lat, lng] = ll(at).split(',')
+      return call('reverse', { query: { lat, lng, radius: o.radius, lang: o.lang }, signal: o.signal })
+    },
+    /** A NIPOST postcode's building, entrances and area. */
+    postcode: (code, o = {}) => call('postcode', { params: { code }, signal: o.signal }),
+    /** A GhanaPost GPS address. */
+    ghanapost: (code, o = {}) => call('ghanapost', { params: { code }, signal: o.signal }),
+    /** Suggestions while someone types (bill per session: pass the same session until they pick). */
+    autocomplete: (q, o = {}) =>
+      call('autocomplete', { query: { q, session: o.session, near: o.near && ll(o.near), types: o.types, country: o.country, limit: o.limit }, signal: o.signal }),
+    /** Checks and completes an address: a verdict, its parts, the point and a corrected postcode. */
+    validateAddress: (address, o = {}) =>
+      call('validateAddress', { body: { address, country: o.country, near: o.near && toLatLng(o.near) }, signal: o.signal }),
+    /** Businesses and places near a point, by category or name. */
+    placesNearby: (at, o = {}) => {
+      const [lat, lng] = ll(at).split(',')
+      return call('placesNearby', {
+        query: { lat, lng, category: o.category, q: o.q, radius: o.radius, limit: o.limit, pageToken: o.pageToken, fields: o.fields },
+        signal: o.signal,
+      })
+    },
+    /** Places by name or text anywhere, nearest first when `near` is given. */
+    placesSearch: (q, o = {}) =>
+      call('placesSearch', { query: { q, near: o.near && ll(o.near), radius: o.radius, limit: o.limit, fields: o.fields }, signal: o.signal }),
+    /** One place's details (`fields` chooses what comes back, and the price tier). */
+    place: (id, o = {}) => call('place', { params: { id }, query: { fields: o.fields }, signal: o.signal }),
+    /** A route: `{ origin, destination, intermediates?, mode?, alternatives?, routingPreference?, departAt?, fares? }`. */
+    route: (req, o = {}) =>
+      call('route', {
+        body: { ...req, origin: wp(req.origin), destination: wp(req.destination), ...(req.intermediates ? { intermediates: req.intermediates.map(wp) } : {}) },
+        signal: o.signal,
+      }),
+    /** Times and distances from each origin to each destination: `{ origins, destinations, mode? }`. */
+    matrix: (req, o = {}) => call('matrix', { body: { ...req, origins: req.origins.map(wp), destinations: req.destinations.map(wp) }, signal: o.signal }),
+    /** The best order for a batch of stops: `{ stops: [{ id, location }], vehicles: [{ id, start }], mode? }`. */
+    optimize: (req, o = {}) =>
+      call('optimize', {
+        body: {
+          ...req,
+          stops: req.stops.map((st) => ({ ...st, location: wp(st.location) })),
+          vehicles: req.vehicles.map((v) => ({ ...v, start: wp(v.start), ...(v.end ? { end: wp(v.end) } : {}) })),
+        },
+        signal: o.signal,
+      }),
+    /** What a taxi, okada, keke, bus or boat ride should cost. */
+    fares: (from, to, o = {}) =>
+      call('fares', { query: { from: ll(from), to: ll(to), mode: o.mode, at: o.at, distanceM: o.distanceM, durationS: o.durationS, charter: o.charter, rain: o.rain }, signal: o.signal }),
+    /** Live road speeds in a box [west, south, east, north], as GeoJSON. */
+    traffic: (bbox, o = {}) => call('traffic', { query: { bbox: bbox.join(',') }, signal: o.signal }),
+    /** The address of a map picture (an <img src>), with markers and a path. */
+    staticMapUrl: (o) => staticMapUrl({ key, origin, ...o }),
+  }
+}
+
+/** A waypoint: points ([lng, lat], GeoJSON) become { lat, lng }; postcodes and other codes pass as they are. */
+const wp = (p) => (Array.isArray(p) || p?.type === 'Point' ? toLatLng(p) : p)
+
+const toLatLng = (p) => {
+  const c = Array.isArray(p) ? p : p?.type === 'Point' ? p.coordinates : null
+  return c ? { lat: c[1], lng: c[0] } : { lat: p.lat, lng: p.lng }
+}
+
+/** A colour for static maps: a name (red, green, blue…) or #RRGGBB[AA] → 0xRRGGBB[AA]. */
+const colour = (c) => (c.startsWith('#') ? '0x' + c.slice(1) : c)
+
+/**
+ * A static map picture's address: `{ key, center, zoom, size: [w, h], scale?, theme?,
+ * format?, markers?: [{ at, color?, label?, size? }], paths?: [{ points, color?, weight?, fillColor? }] }`.
+ * Points are { lat, lng }, [lng, lat] or GeoJSON points. Without center and zoom,
+ * the map frames the markers and paths.
+ */
+export function staticMapUrl(o) {
+  const { key, origin = NWAYS_ORIGIN, center, zoom, size = [640, 400], scale, theme, format, markers = [], path } = o
+  const paths = o.paths ?? (path ? [path] : [])
+  const u = new URL(origin + PATHS.staticMap)
+  if (center) u.searchParams.set('center', ll(center))
+  if (zoom !== undefined) u.searchParams.set('zoom', String(zoom))
+  u.searchParams.set('size', `${size[0]}x${size[1]}`)
+  if (scale) u.searchParams.set('scale', String(scale))
+  if (theme) u.searchParams.set('theme', theme)
+  if (format) u.searchParams.set('format', format)
+  for (const m of markers) {
+    const style = [m.color && `color:${colour(m.color)}`, m.label && `label:${m.label}`, m.size && `size:${m.size}`].filter(Boolean)
+    u.searchParams.append('markers', [...style, ll(m.at)].join('|'))
+  }
+  for (const p of paths) {
+    const style = [p.color && `color:${colour(p.color)}`, p.weight !== undefined && `weight:${p.weight}`, p.fillColor && `fillcolor:${colour(p.fillColor)}`].filter(Boolean)
+    u.searchParams.append('path', [...style, ...p.points.map(ll)].join('|'))
+  }
+  return withKey(u.toString(), key, origin)
+}

package/style.d.ts

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 N-WAYS LIMITED
+import type { StyleSpecification } from 'maplibre-gl'
+
+export type Theme = 'light' | 'dark'
+
+export interface StyleOptions {
+  /** Your N-Ways API key. */
+  key?: string
+  theme?: Theme
+  /** Where the style, tiles and fonts are served (default https://nways.ng). */
+  origin?: string
+  /** Label language: local names, or French names where there are any. */
+  lang?: 'en' | 'fr'
+}
+
+export const NWAYS_ORIGIN: string
+export const TILESETS: { base: string }
+export const ATTRIBUTION: string
+export const THEMES: Record<Theme, Record<string, string>>
+/** The hosted styles' ids by theme: streets-light, streets-dark. */
+export const STYLE_IDS: Record<Theme, string>
+/** The address of N-Ways' hosted style (with the key). */
+export function styleUrl(options?: StyleOptions): string
+export function withKey(url: string, key: string | undefined, origin?: string): string
+/** The SDK's built-in style as a plain MapLibre style object. */
+export function buildStyle(options?: StyleOptions): StyleSpecification