@maas-mr/client 1.0.0

package/dist/index.cjs

@@ -0,0 +1,483 @@
+/**
+ * @maas/client — Map-as-a-Service SDK
+ *
+ * Arabic maps, routing, and navigation for Mauritania.
+ * Works in the browser (with MapLibre GL JS) and in React Native / Node for API calls.
+ */
+
+// ── Polyline6 decoder (Google/OSRM format, precision 1e-6) ────────────────────
+
+function _decodePolyline6(encoded) {
+  const coords = [];
+  let index = 0, lat = 0, lng = 0;
+  while (index < encoded.length) {
+    let b, shift = 0, result = 0;
+    do {
+      b = encoded.charCodeAt(index++) - 63;
+      result |= (b & 0x1f) << shift;
+      shift += 5;
+    } while (b >= 0x20);
+    lat += result & 1 ? ~(result >> 1) : result >> 1;
+
+    shift = 0; result = 0;
+    do {
+      b = encoded.charCodeAt(index++) - 63;
+      result |= (b & 0x1f) << shift;
+      shift += 5;
+    } while (b >= 0x20);
+    lng += result & 1 ? ~(result >> 1) : result >> 1;
+
+    coords.push([lng / 1e6, lat / 1e6]);
+  }
+  return coords;
+}
+
+// ── MaaSClient ────────────────────────────────────────────────────────────────
+
+class MaaSClient {
+  /**
+   * @param {object} options
+   * @param {string} options.baseUrl  Base URL of your MaaS API (no trailing slash)
+   * @param {string} options.apiKey   Your API key (X-API-Key header)
+   */
+  constructor({ baseUrl, apiKey }) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.apiKey = apiKey;
+    this._map = null;
+    this._driverMarker = null;
+    this._routeLayerAdded = false;
+    this._navSession = null;
+  }
+
+  // ── Internal HTTP helpers ──────────────────────────────────────────────────
+
+  async _get(path, params = {}) {
+    const url = new URL(this.baseUrl + path);
+    Object.entries(params).forEach(([k, v]) => {
+      if (v !== null && v !== undefined) url.searchParams.set(k, v);
+    });
+    const resp = await fetch(url.toString(), {
+      headers: { 'X-API-Key': this.apiKey },
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(`MaaS API error ${resp.status}: ${err.detail || err.message || resp.statusText}`);
+    }
+    return resp.json();
+  }
+
+  async _post(path, body) {
+    const resp = await fetch(this.baseUrl + path, {
+      method: 'POST',
+      headers: { 'X-API-Key': this.apiKey, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(`MaaS API error ${resp.status}: ${err.detail || err.message || resp.statusText}`);
+    }
+    return resp.json();
+  }
+
+  // ── Places ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Fuzzy-search places by Hassaniya Arabic name or variant spellings.
+   * @param {string} query
+   * @param {{ lat?: number, lon?: number, radiusKm?: number, limit?: number }} opts
+   * @returns {Promise<{ places: PlaceResult[], total: number }>}
+   */
+  searchPlaces(query, opts = {}) {
+    return this._get('/v1/places/search', {
+      q: query,
+      lat: opts.lat,
+      lon: opts.lon,
+      radius_km: opts.radiusKm,
+      limit: opts.limit ?? 10,
+    });
+  }
+
+  /**
+   * Get a single place by ID.
+   * @param {string} placeId
+   * @returns {Promise<PlaceResult>}
+   */
+  getPlace(placeId) {
+    return this._get(`/v1/places/${encodeURIComponent(placeId)}`);
+  }
+
+  // ── Geocoding ──────────────────────────────────────────────────────────────
+
+  /**
+   * Convert a place name to coordinates.
+   * @param {string} query
+   * @returns {Promise<ForwardGeocodeResult>}
+   */
+  forwardGeocode(query) {
+    return this._get('/v1/geocode/forward', { q: query });
+  }
+
+  /**
+   * Convert coordinates to the nearest known place name.
+   * @param {number} lat
+   * @param {number} lon
+   * @param {number} [maxDistM=500]
+   * @returns {Promise<ReverseGeocodeResult>}
+   */
+  reverseGeocode(lat, lon, maxDistM = 500) {
+    return this._get('/v1/geocode/reverse', { lat, lon, max_dist_m: maxDistM });
+  }
+
+  // ── Routing ────────────────────────────────────────────────────────────────
+
+  /**
+   * Get turn-by-turn directions between two points.
+   * @param {number} fromLat
+   * @param {number} fromLon
+   * @param {number} toLat
+   * @param {number} toLon
+   * @param {'ar'|'en'} [language='ar']
+   * @returns {Promise<RouteResult>}
+   */
+  getRoute(fromLat, fromLon, toLat, toLon, language = 'ar') {
+    return this._get('/v1/route', {
+      from_lat: fromLat, from_lon: fromLon,
+      to_lat: toLat, to_lon: toLon,
+      language,
+    });
+  }
+
+  /**
+   * Get navigation progress for a live GPS position on an active route.
+   * Call this on every GPS fix during navigation.
+   * @param {string} routeId  - From getRoute() response
+   * @param {number} lat
+   * @param {number} lon
+   * @returns {Promise<RouteProgress>}
+   */
+  getRouteProgress(routeId, lat, lon) {
+    return this._get('/v1/route/progress', { route_id: routeId, lat, lon });
+  }
+
+  // ── ETA ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get ETA between two points.
+   * @param {number} fromLat
+   * @param {number} fromLon
+   * @param {number} toLat
+   * @param {number} toLon
+   * @returns {Promise<EtaResult>}
+   */
+  getEta(fromLat, fromLon, toLat, toLon) {
+    return this._get('/v1/eta', {
+      from_lat: fromLat, from_lon: fromLon,
+      to_lat: toLat, to_lon: toLon,
+    });
+  }
+
+  /**
+   * Compute a distance/duration matrix (max 10×10).
+   * Useful for dispatch: find nearest available driver.
+   * @param {Array<{lat: number, lon: number}>} origins
+   * @param {Array<{lat: number, lon: number}>} destinations
+   * @returns {Promise<EtaMatrixResult>}
+   */
+  getEtaMatrix(origins, destinations) {
+    return this._post('/v1/eta/matrix', { origins, destinations });
+  }
+
+  // ── Driver Location ────────────────────────────────────────────────────────
+
+  /**
+   * Push current driver location (HTTP).
+   * @param {string} driverId
+   * @param {number} lat
+   * @param {number} lon
+   * @param {{ heading?: number, speedKmh?: number }} [opts]
+   */
+  updateDriverLocation(driverId, lat, lon, opts = {}) {
+    return this._post(`/v1/drivers/${encodeURIComponent(driverId)}/location`, {
+      lat, lon,
+      heading: opts.heading,
+      speed_kmh: opts.speedKmh,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Get nearby active drivers.
+   * @param {number} lat
+   * @param {number} lon
+   * @param {number} [radiusKm=5]
+   * @returns {Promise<NearbyDriversResult>}
+   */
+  getNearbyDrivers(lat, lon, radiusKm = 5) {
+    return this._get('/v1/drivers/nearby', { lat, lon, radius_km: radiusKm });
+  }
+
+  // ── Real-time Tracking (WebSocket) ─────────────────────────────────────────
+
+  /**
+   * Open a WebSocket to stream driver location updates. Call from the driver app.
+   * @param {string} tripId
+   * @param {string} driverId
+   * @returns {{ send: (lat: number, lon: number, opts?: object) => void, end: () => void, close: () => void }}
+   */
+  trackDriver(tripId, driverId) {
+    const wsUrl = this.baseUrl.replace(/^http/, 'ws')
+      + `/v1/tracking/${encodeURIComponent(tripId)}/driver`
+      + `?api_key=${encodeURIComponent(this.apiKey)}&driver_id=${encodeURIComponent(driverId)}`;
+
+    const ws = new WebSocket(wsUrl);
+    ws.onopen  = () => console.debug('[MaaS] Driver tracking connected');
+    ws.onerror = (e) => console.error('[MaaS] Driver WS error', e);
+
+    return {
+      send(lat, lon, opts = {}) {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({
+            type: 'location', lat, lon,
+            heading: opts.heading,
+            speed_kmh: opts.speedKmh,
+            timestamp: new Date().toISOString(),
+          }));
+        }
+      },
+      end() {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: 'trip_ended' }));
+        }
+      },
+      close() { ws.close(); },
+    };
+  }
+
+  /**
+   * Subscribe to driver location updates. Call from the passenger app.
+   * @param {string} tripId
+   * @param {(location: object) => void} onLocation
+   * @param {() => void} [onTripEnded]
+   * @returns {{ close: () => void }}
+   */
+  trackPassenger(tripId, onLocation, onTripEnded = () => {}) {
+    const wsUrl = this.baseUrl.replace(/^http/, 'ws')
+      + `/v1/tracking/${encodeURIComponent(tripId)}/passenger`
+      + `?api_key=${encodeURIComponent(this.apiKey)}`;
+
+    const ws = new WebSocket(wsUrl);
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        if (data.type === 'driver_location') onLocation(data);
+        if (data.type === 'trip_ended') onTripEnded();
+      } catch { /* ignore malformed */ }
+    };
+    ws.onerror = (e) => console.error('[MaaS] Passenger WS error', e);
+
+    const ping = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
+    }, 25000);
+
+    return { close() { clearInterval(ping); ws.close(); } };
+  }
+
+  // ── Map (browser only) ─────────────────────────────────────────────────────
+
+  /**
+   * Initialize a MapLibre GL map centred on Nouakchott.
+   * Requires `maplibre-gl` to be installed/loaded.
+   * @param {string|HTMLElement} container  DOM element id or element reference
+   * @param {{ center?: [number,number], zoom?: number, pitch?: number, bearing?: number, maxZoom?: number, style?: string }} [opts]
+   * @returns {import('maplibre-gl').Map}
+   */
+  createMap(container, opts = {}) {
+    // Support both CDN global and npm import
+    const mgl = typeof maplibregl !== 'undefined' ? maplibregl : opts._maplibregl;
+    if (!mgl) throw new Error('maplibre-gl is not available. Pass it as opts._maplibregl or load the CDN script.');
+
+    this._maplibregl = mgl;
+    const map = new mgl.Map({
+      container,
+      style: opts.style ?? `${this.baseUrl}/tiles/styles/mauritania-ar/style.json`,
+      center: opts.center ?? [-15.9785, 18.0864],
+      zoom: opts.zoom ?? 13,
+      pitch: opts.pitch ?? 45,
+      bearing: opts.bearing ?? 0,
+      maxZoom: opts.maxZoom ?? 18,
+    });
+
+    this._map = map;
+    return map;
+  }
+
+  /**
+   * Draw (or update) the route polyline on the map.
+   * @param {RouteResult} route  Response from getRoute()
+   */
+  showRoute(route) {
+    if (!this._map) throw new Error('Call createMap() first');
+    const coordinates = _decodePolyline6(route.geometry);
+
+    if (this._routeLayerAdded) {
+      this._map.getSource('maas-route').setData({
+        type: 'Feature', geometry: { type: 'LineString', coordinates },
+      });
+    } else {
+      this._map.addSource('maas-route', {
+        type: 'geojson',
+        data: { type: 'Feature', geometry: { type: 'LineString', coordinates } },
+      });
+      this._map.addLayer({
+        id: 'maas-route-line', type: 'line', source: 'maas-route',
+        layout: { 'line-join': 'round', 'line-cap': 'round' },
+        paint: { 'line-color': '#2563eb', 'line-width': 5, 'line-opacity': 0.85 },
+      });
+      this._routeLayerAdded = true;
+    }
+
+    const lngs = coordinates.map(c => c[0]);
+    const lats = coordinates.map(c => c[1]);
+    this._map.fitBounds(
+      [[Math.min(...lngs), Math.min(...lats)], [Math.max(...lngs), Math.max(...lats)]],
+      { padding: 60 }
+    );
+  }
+
+  /**
+   * Update (or create) the driver marker on the map.
+   * @param {number} lat
+   * @param {number} lon
+   * @param {number} [heading=0]
+   */
+  updateDriverMarker(lat, lon, heading = 0) {
+    if (!this._map) throw new Error('Call createMap() first');
+    if (!this._driverMarker) {
+      const el = document.createElement('div');
+      el.style.cssText = 'width:36px;height:36px;background:#2563eb;border-radius:50%;border:3px solid white;box-shadow:0 2px 8px rgba(0,0,0,0.3);cursor:pointer;';
+      this._driverMarker = new this._maplibregl.Marker({ element: el, rotation: heading })
+        .setLngLat([lon, lat]).addTo(this._map);
+    } else {
+      this._driverMarker.setLngLat([lon, lat]).setRotation(heading);
+    }
+  }
+
+  // ── Navigation ─────────────────────────────────────────────────────────────
+
+  /**
+   * Start turn-by-turn navigation between two points.
+   *
+   * Handles everything internally:
+   * - Fetches route and draws it on the map
+   * - Watches device GPS and moves camera to follow
+   * - Polls /route/progress on every GPS fix
+   * - Auto re-routes when off-route
+   * - Fires callbacks so your UI can show instructions, ETA, etc.
+   *
+   * @param {number} fromLat
+   * @param {number} fromLon
+   * @param {number} toLat
+   * @param {number} toLon
+   * @param {{
+   *   language?:          'ar'|'en',
+   *   arrivalThresholdM?: number,
+   *   onProgress?:        (progress: RouteProgress) => void,
+   *   onStep?:            (step: RouteStep, index: number) => void,
+   *   onOffRoute?:        (distanceM: number) => void,
+   *   onArrival?:         () => void,
+   *   onError?:           (err: Error) => void,
+   * }} [opts]
+   * @returns {Promise<{ route: RouteResult, stop: () => void }>}
+   */
+  async startNavigation(fromLat, fromLon, toLat, toLon, opts = {}) {
+    if (!this._map) throw new Error('Call createMap() first');
+
+    const {
+      language          = 'ar',
+      arrivalThresholdM = 30,
+      onProgress        = () => {},
+      onStep            = () => {},
+      onOffRoute        = () => {},
+      onArrival         = () => {},
+      onError           = () => {},
+    } = opts;
+
+    const route = await this.getRoute(fromLat, fromLon, toLat, toLon, language);
+    this.showRoute(route);
+
+    let routeId        = route.route_id;
+    let currentStepIdx = -1;
+    let reroutePending = false;
+    let stopped        = false;
+    let watchId        = null;
+
+    const el = document.createElement('div');
+    el.style.cssText = 'width:22px;height:22px;border-radius:50%;background:#2563eb;border:3px solid white;box-shadow:0 2px 8px rgba(0,0,0,0.4);';
+    const navMarker = new this._maplibregl.Marker({ element: el, rotationAlignment: 'map' })
+      .setLngLat([fromLon, fromLat]).addTo(this._map);
+
+    this._map.easeTo({ center: [fromLon, fromLat], zoom: 17, pitch: 60, bearing: 0, duration: 800 });
+
+    const handlePosition = async ({ coords }) => {
+      if (stopped) return;
+      const { latitude: lat, longitude: lon, heading } = coords;
+
+      navMarker.setLngLat([lon, lat]);
+      if (heading !== null) navMarker.setRotation(heading);
+      this._map.easeTo({ center: [lon, lat], bearing: heading ?? 0, duration: 400 });
+
+      try {
+        const progress = await this.getRouteProgress(routeId, lat, lon);
+        onProgress(progress);
+
+        if (progress.step_index !== currentStepIdx) {
+          currentStepIdx = progress.step_index;
+          onStep(progress.current_step, progress.step_index);
+        }
+
+        if (progress.off_route && !reroutePending) {
+          reroutePending = true;
+          onOffRoute(progress.off_route_distance_m);
+          try {
+            const newRoute = await this.getRoute(lat, lon, toLat, toLon, language);
+            routeId = newRoute.route_id;
+            this.showRoute(newRoute);
+            currentStepIdx = -1;
+          } catch (e) { onError(e); }
+          finally { reroutePending = false; }
+        }
+
+        if (progress.distance_remaining_m <= arrivalThresholdM) {
+          onArrival();
+          stop();
+        }
+      } catch (e) { onError(e); }
+    };
+
+    if (!navigator.geolocation) throw new Error('Geolocation not supported by this browser.');
+    watchId = navigator.geolocation.watchPosition(
+      handlePosition,
+      (e) => onError(new Error(`GPS: ${e.message}`)),
+      { enableHighAccuracy: true, maximumAge: 1000, timeout: 10000 },
+    );
+
+    function stop() {
+      if (stopped) return;
+      stopped = true;
+      if (watchId !== null) navigator.geolocation.clearWatch(watchId);
+      navMarker.remove();
+    }
+
+    this._navSession = { stop };
+    return { route, stop };
+  }
+
+  /** Stop an active navigation session. */
+  stopNavigation() {
+    if (this._navSession) { this._navSession.stop(); this._navSession = null; }
+  }
+}
+
+
+module.exports = { MaaSClient };
+module.exports.default = MaaSClient;

package/dist/index.d.ts

@@ -0,0 +1,196 @@
+// ── Shared types ───────────────────────────────────────────────────────────────
+
+export interface PlaceResult {
+  id: string;
+  canonical_name: string;
+  variants: string[];
+  lat: number;
+  lon: number;
+  distance_m?: number;
+  score?: number;
+}
+
+export interface PlaceSearchResult {
+  places: PlaceResult[];
+  total: number;
+}
+
+export interface ForwardGeocodeResult {
+  place_id: string;
+  canonical_name: string;
+  lat: number;
+  lon: number;
+  confidence: number;
+}
+
+export interface ReverseGeocodeResult {
+  place_id: string;
+  canonical_name: string;
+  lat: number;
+  lon: number;
+  distance_m: number;
+}
+
+export interface RouteStep {
+  instruction: string;
+  distance_m: number;
+  duration_s: number;
+  maneuver_type: string;
+  street_name: string;
+  lat: number;
+  lon: number;
+}
+
+export interface RouteWaypoint {
+  lat: number;
+  lon: number;
+  snapped_lat: number;
+  snapped_lon: number;
+}
+
+export interface RouteResult {
+  route_id: string;
+  distance_m: number;
+  duration_s: number;
+  /** Encoded polyline (precision 1e-6) */
+  geometry: string;
+  steps: RouteStep[];
+  waypoints: RouteWaypoint[];
+  /** 'osrm' or 'estimated' (straight-line fallback) */
+  routing: 'osrm' | 'estimated';
+}
+
+export interface RouteProgress {
+  step_index: number;
+  current_step: RouteStep;
+  next_step: RouteStep | null;
+  distance_to_next_m: number;
+  distance_remaining_m: number;
+  duration_remaining_s: number;
+  off_route: boolean;
+  off_route_distance_m: number;
+}
+
+export interface EtaResult {
+  distance_m: number;
+  duration_s: number;
+  /** ISO 8601 timestamp */
+  eta_iso: string;
+  traffic_factor: number;
+}
+
+export interface EtaMatrixResult {
+  durations_s: Array<Array<number | null>>;
+  distances_m: Array<Array<number | null>>;
+}
+
+export interface DriverLocation {
+  lat: number;
+  lon: number;
+  heading?: number;
+  speed_kmh?: number;
+}
+
+export interface DriverInfo extends DriverLocation {
+  driver_id: string;
+  distance_m: number;
+  last_seen?: string;
+}
+
+export interface NearbyDriversResult {
+  drivers: DriverInfo[];
+}
+
+export interface DriverTracker {
+  send(lat: number, lon: number, opts?: { heading?: number; speedKmh?: number }): void;
+  end(): void;
+  close(): void;
+}
+
+export interface PassengerTracker {
+  close(): void;
+}
+
+export interface NavigationSession {
+  route: RouteResult;
+  stop(): void;
+}
+
+// ── MaaSClient options ─────────────────────────────────────────────────────────
+
+export interface MaaSClientOptions {
+  baseUrl: string;
+  apiKey: string;
+}
+
+export interface SearchPlacesOptions {
+  lat?: number;
+  lon?: number;
+  radiusKm?: number;
+  limit?: number;
+}
+
+export interface CreateMapOptions {
+  /** [lng, lat] — defaults to Nouakchott centre */
+  center?: [number, number];
+  zoom?: number;
+  pitch?: number;
+  bearing?: number;
+  maxZoom?: number;
+  /** Override the style URL */
+  style?: string;
+  /** Pass maplibre-gl module when not available as a global (npm usage) */
+  _maplibregl?: unknown;
+}
+
+export interface NavigationOptions {
+  language?: 'ar' | 'en';
+  /** Distance in metres at which arrival is triggered (default 30) */
+  arrivalThresholdM?: number;
+  onProgress?: (progress: RouteProgress) => void;
+  onStep?: (step: RouteStep, index: number) => void;
+  onOffRoute?: (distanceM: number) => void;
+  onArrival?: () => void;
+  onError?: (err: Error) => void;
+}
+
+// ── MaaSClient ─────────────────────────────────────────────────────────────────
+
+export declare class MaaSClient {
+  constructor(options: MaaSClientOptions);
+
+  // Places
+  searchPlaces(query: string, opts?: SearchPlacesOptions): Promise<PlaceSearchResult>;
+  getPlace(placeId: string): Promise<PlaceResult>;
+
+  // Geocoding
+  forwardGeocode(query: string): Promise<ForwardGeocodeResult>;
+  reverseGeocode(lat: number, lon: number, maxDistM?: number): Promise<ReverseGeocodeResult>;
+
+  // Routing
+  getRoute(fromLat: number, fromLon: number, toLat: number, toLon: number, language?: 'ar' | 'en'): Promise<RouteResult>;
+  getRouteProgress(routeId: string, lat: number, lon: number): Promise<RouteProgress>;
+
+  // ETA
+  getEta(fromLat: number, fromLon: number, toLat: number, toLon: number): Promise<EtaResult>;
+  getEtaMatrix(origins: DriverLocation[], destinations: DriverLocation[]): Promise<EtaMatrixResult>;
+
+  // Drivers
+  updateDriverLocation(driverId: string, lat: number, lon: number, opts?: { heading?: number; speedKmh?: number }): Promise<void>;
+  getNearbyDrivers(lat: number, lon: number, radiusKm?: number): Promise<NearbyDriversResult>;
+
+  // Real-time tracking
+  trackDriver(tripId: string, driverId: string): DriverTracker;
+  trackPassenger(tripId: string, onLocation: (location: DriverLocation) => void, onTripEnded?: () => void): PassengerTracker;
+
+  // Map (browser only)
+  createMap(container: string | HTMLElement, opts?: CreateMapOptions): unknown;
+  showRoute(route: RouteResult): void;
+  updateDriverMarker(lat: number, lon: number, heading?: number): void;
+
+  // Navigation (browser only)
+  startNavigation(fromLat: number, fromLon: number, toLat: number, toLon: number, opts?: NavigationOptions): Promise<NavigationSession>;
+  stopNavigation(): void;
+}
+
+export default MaaSClient;

package/dist/index.js

@@ -0,0 +1,481 @@
+/**
+ * @maas/client — Map-as-a-Service SDK
+ *
+ * Arabic maps, routing, and navigation for Mauritania.
+ * Works in the browser (with MapLibre GL JS) and in React Native / Node for API calls.
+ */
+
+// ── Polyline6 decoder (Google/OSRM format, precision 1e-6) ────────────────────
+
+function _decodePolyline6(encoded) {
+  const coords = [];
+  let index = 0, lat = 0, lng = 0;
+  while (index < encoded.length) {
+    let b, shift = 0, result = 0;
+    do {
+      b = encoded.charCodeAt(index++) - 63;
+      result |= (b & 0x1f) << shift;
+      shift += 5;
+    } while (b >= 0x20);
+    lat += result & 1 ? ~(result >> 1) : result >> 1;
+
+    shift = 0; result = 0;
+    do {
+      b = encoded.charCodeAt(index++) - 63;
+      result |= (b & 0x1f) << shift;
+      shift += 5;
+    } while (b >= 0x20);
+    lng += result & 1 ? ~(result >> 1) : result >> 1;
+
+    coords.push([lng / 1e6, lat / 1e6]);
+  }
+  return coords;
+}
+
+// ── MaaSClient ────────────────────────────────────────────────────────────────
+
+export class MaaSClient {
+  /**
+   * @param {object} options
+   * @param {string} options.baseUrl  Base URL of your MaaS API (no trailing slash)
+   * @param {string} options.apiKey   Your API key (X-API-Key header)
+   */
+  constructor({ baseUrl, apiKey }) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.apiKey = apiKey;
+    this._map = null;
+    this._driverMarker = null;
+    this._routeLayerAdded = false;
+    this._navSession = null;
+  }
+
+  // ── Internal HTTP helpers ──────────────────────────────────────────────────
+
+  async _get(path, params = {}) {
+    const url = new URL(this.baseUrl + path);
+    Object.entries(params).forEach(([k, v]) => {
+      if (v !== null && v !== undefined) url.searchParams.set(k, v);
+    });
+    const resp = await fetch(url.toString(), {
+      headers: { 'X-API-Key': this.apiKey },
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(`MaaS API error ${resp.status}: ${err.detail || err.message || resp.statusText}`);
+    }
+    return resp.json();
+  }
+
+  async _post(path, body) {
+    const resp = await fetch(this.baseUrl + path, {
+      method: 'POST',
+      headers: { 'X-API-Key': this.apiKey, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+      const err = await resp.json().catch(() => ({}));
+      throw new Error(`MaaS API error ${resp.status}: ${err.detail || err.message || resp.statusText}`);
+    }
+    return resp.json();
+  }
+
+  // ── Places ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Fuzzy-search places by Hassaniya Arabic name or variant spellings.
+   * @param {string} query
+   * @param {{ lat?: number, lon?: number, radiusKm?: number, limit?: number }} opts
+   * @returns {Promise<{ places: PlaceResult[], total: number }>}
+   */
+  searchPlaces(query, opts = {}) {
+    return this._get('/v1/places/search', {
+      q: query,
+      lat: opts.lat,
+      lon: opts.lon,
+      radius_km: opts.radiusKm,
+      limit: opts.limit ?? 10,
+    });
+  }
+
+  /**
+   * Get a single place by ID.
+   * @param {string} placeId
+   * @returns {Promise<PlaceResult>}
+   */
+  getPlace(placeId) {
+    return this._get(`/v1/places/${encodeURIComponent(placeId)}`);
+  }
+
+  // ── Geocoding ──────────────────────────────────────────────────────────────
+
+  /**
+   * Convert a place name to coordinates.
+   * @param {string} query
+   * @returns {Promise<ForwardGeocodeResult>}
+   */
+  forwardGeocode(query) {
+    return this._get('/v1/geocode/forward', { q: query });
+  }
+
+  /**
+   * Convert coordinates to the nearest known place name.
+   * @param {number} lat
+   * @param {number} lon
+   * @param {number} [maxDistM=500]
+   * @returns {Promise<ReverseGeocodeResult>}
+   */
+  reverseGeocode(lat, lon, maxDistM = 500) {
+    return this._get('/v1/geocode/reverse', { lat, lon, max_dist_m: maxDistM });
+  }
+
+  // ── Routing ────────────────────────────────────────────────────────────────
+
+  /**
+   * Get turn-by-turn directions between two points.
+   * @param {number} fromLat
+   * @param {number} fromLon
+   * @param {number} toLat
+   * @param {number} toLon
+   * @param {'ar'|'en'} [language='ar']
+   * @returns {Promise<RouteResult>}
+   */
+  getRoute(fromLat, fromLon, toLat, toLon, language = 'ar') {
+    return this._get('/v1/route', {
+      from_lat: fromLat, from_lon: fromLon,
+      to_lat: toLat, to_lon: toLon,
+      language,
+    });
+  }
+
+  /**
+   * Get navigation progress for a live GPS position on an active route.
+   * Call this on every GPS fix during navigation.
+   * @param {string} routeId  - From getRoute() response
+   * @param {number} lat
+   * @param {number} lon
+   * @returns {Promise<RouteProgress>}
+   */
+  getRouteProgress(routeId, lat, lon) {
+    return this._get('/v1/route/progress', { route_id: routeId, lat, lon });
+  }
+
+  // ── ETA ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Get ETA between two points.
+   * @param {number} fromLat
+   * @param {number} fromLon
+   * @param {number} toLat
+   * @param {number} toLon
+   * @returns {Promise<EtaResult>}
+   */
+  getEta(fromLat, fromLon, toLat, toLon) {
+    return this._get('/v1/eta', {
+      from_lat: fromLat, from_lon: fromLon,
+      to_lat: toLat, to_lon: toLon,
+    });
+  }
+
+  /**
+   * Compute a distance/duration matrix (max 10×10).
+   * Useful for dispatch: find nearest available driver.
+   * @param {Array<{lat: number, lon: number}>} origins
+   * @param {Array<{lat: number, lon: number}>} destinations
+   * @returns {Promise<EtaMatrixResult>}
+   */
+  getEtaMatrix(origins, destinations) {
+    return this._post('/v1/eta/matrix', { origins, destinations });
+  }
+
+  // ── Driver Location ────────────────────────────────────────────────────────
+
+  /**
+   * Push current driver location (HTTP).
+   * @param {string} driverId
+   * @param {number} lat
+   * @param {number} lon
+   * @param {{ heading?: number, speedKmh?: number }} [opts]
+   */
+  updateDriverLocation(driverId, lat, lon, opts = {}) {
+    return this._post(`/v1/drivers/${encodeURIComponent(driverId)}/location`, {
+      lat, lon,
+      heading: opts.heading,
+      speed_kmh: opts.speedKmh,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Get nearby active drivers.
+   * @param {number} lat
+   * @param {number} lon
+   * @param {number} [radiusKm=5]
+   * @returns {Promise<NearbyDriversResult>}
+   */
+  getNearbyDrivers(lat, lon, radiusKm = 5) {
+    return this._get('/v1/drivers/nearby', { lat, lon, radius_km: radiusKm });
+  }
+
+  // ── Real-time Tracking (WebSocket) ─────────────────────────────────────────
+
+  /**
+   * Open a WebSocket to stream driver location updates. Call from the driver app.
+   * @param {string} tripId
+   * @param {string} driverId
+   * @returns {{ send: (lat: number, lon: number, opts?: object) => void, end: () => void, close: () => void }}
+   */
+  trackDriver(tripId, driverId) {
+    const wsUrl = this.baseUrl.replace(/^http/, 'ws')
+      + `/v1/tracking/${encodeURIComponent(tripId)}/driver`
+      + `?api_key=${encodeURIComponent(this.apiKey)}&driver_id=${encodeURIComponent(driverId)}`;
+
+    const ws = new WebSocket(wsUrl);
+    ws.onopen  = () => console.debug('[MaaS] Driver tracking connected');
+    ws.onerror = (e) => console.error('[MaaS] Driver WS error', e);
+
+    return {
+      send(lat, lon, opts = {}) {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({
+            type: 'location', lat, lon,
+            heading: opts.heading,
+            speed_kmh: opts.speedKmh,
+            timestamp: new Date().toISOString(),
+          }));
+        }
+      },
+      end() {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify({ type: 'trip_ended' }));
+        }
+      },
+      close() { ws.close(); },
+    };
+  }
+
+  /**
+   * Subscribe to driver location updates. Call from the passenger app.
+   * @param {string} tripId
+   * @param {(location: object) => void} onLocation
+   * @param {() => void} [onTripEnded]
+   * @returns {{ close: () => void }}
+   */
+  trackPassenger(tripId, onLocation, onTripEnded = () => {}) {
+    const wsUrl = this.baseUrl.replace(/^http/, 'ws')
+      + `/v1/tracking/${encodeURIComponent(tripId)}/passenger`
+      + `?api_key=${encodeURIComponent(this.apiKey)}`;
+
+    const ws = new WebSocket(wsUrl);
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        if (data.type === 'driver_location') onLocation(data);
+        if (data.type === 'trip_ended') onTripEnded();
+      } catch { /* ignore malformed */ }
+    };
+    ws.onerror = (e) => console.error('[MaaS] Passenger WS error', e);
+
+    const ping = setInterval(() => {
+      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'ping' }));
+    }, 25000);
+
+    return { close() { clearInterval(ping); ws.close(); } };
+  }
+
+  // ── Map (browser only) ─────────────────────────────────────────────────────
+
+  /**
+   * Initialize a MapLibre GL map centred on Nouakchott.
+   * Requires `maplibre-gl` to be installed/loaded.
+   * @param {string|HTMLElement} container  DOM element id or element reference
+   * @param {{ center?: [number,number], zoom?: number, pitch?: number, bearing?: number, maxZoom?: number, style?: string }} [opts]
+   * @returns {import('maplibre-gl').Map}
+   */
+  createMap(container, opts = {}) {
+    // Support both CDN global and npm import
+    const mgl = typeof maplibregl !== 'undefined' ? maplibregl : opts._maplibregl;
+    if (!mgl) throw new Error('maplibre-gl is not available. Pass it as opts._maplibregl or load the CDN script.');
+
+    this._maplibregl = mgl;
+    const map = new mgl.Map({
+      container,
+      style: opts.style ?? `${this.baseUrl}/tiles/styles/mauritania-ar/style.json`,
+      center: opts.center ?? [-15.9785, 18.0864],
+      zoom: opts.zoom ?? 13,
+      pitch: opts.pitch ?? 45,
+      bearing: opts.bearing ?? 0,
+      maxZoom: opts.maxZoom ?? 18,
+    });
+
+    this._map = map;
+    return map;
+  }
+
+  /**
+   * Draw (or update) the route polyline on the map.
+   * @param {RouteResult} route  Response from getRoute()
+   */
+  showRoute(route) {
+    if (!this._map) throw new Error('Call createMap() first');
+    const coordinates = _decodePolyline6(route.geometry);
+
+    if (this._routeLayerAdded) {
+      this._map.getSource('maas-route').setData({
+        type: 'Feature', geometry: { type: 'LineString', coordinates },
+      });
+    } else {
+      this._map.addSource('maas-route', {
+        type: 'geojson',
+        data: { type: 'Feature', geometry: { type: 'LineString', coordinates } },
+      });
+      this._map.addLayer({
+        id: 'maas-route-line', type: 'line', source: 'maas-route',
+        layout: { 'line-join': 'round', 'line-cap': 'round' },
+        paint: { 'line-color': '#2563eb', 'line-width': 5, 'line-opacity': 0.85 },
+      });
+      this._routeLayerAdded = true;
+    }
+
+    const lngs = coordinates.map(c => c[0]);
+    const lats = coordinates.map(c => c[1]);
+    this._map.fitBounds(
+      [[Math.min(...lngs), Math.min(...lats)], [Math.max(...lngs), Math.max(...lats)]],
+      { padding: 60 }
+    );
+  }
+
+  /**
+   * Update (or create) the driver marker on the map.
+   * @param {number} lat
+   * @param {number} lon
+   * @param {number} [heading=0]
+   */
+  updateDriverMarker(lat, lon, heading = 0) {
+    if (!this._map) throw new Error('Call createMap() first');
+    if (!this._driverMarker) {
+      const el = document.createElement('div');
+      el.style.cssText = 'width:36px;height:36px;background:#2563eb;border-radius:50%;border:3px solid white;box-shadow:0 2px 8px rgba(0,0,0,0.3);cursor:pointer;';
+      this._driverMarker = new this._maplibregl.Marker({ element: el, rotation: heading })
+        .setLngLat([lon, lat]).addTo(this._map);
+    } else {
+      this._driverMarker.setLngLat([lon, lat]).setRotation(heading);
+    }
+  }
+
+  // ── Navigation ─────────────────────────────────────────────────────────────
+
+  /**
+   * Start turn-by-turn navigation between two points.
+   *
+   * Handles everything internally:
+   * - Fetches route and draws it on the map
+   * - Watches device GPS and moves camera to follow
+   * - Polls /route/progress on every GPS fix
+   * - Auto re-routes when off-route
+   * - Fires callbacks so your UI can show instructions, ETA, etc.
+   *
+   * @param {number} fromLat
+   * @param {number} fromLon
+   * @param {number} toLat
+   * @param {number} toLon
+   * @param {{
+   *   language?:          'ar'|'en',
+   *   arrivalThresholdM?: number,
+   *   onProgress?:        (progress: RouteProgress) => void,
+   *   onStep?:            (step: RouteStep, index: number) => void,
+   *   onOffRoute?:        (distanceM: number) => void,
+   *   onArrival?:         () => void,
+   *   onError?:           (err: Error) => void,
+   * }} [opts]
+   * @returns {Promise<{ route: RouteResult, stop: () => void }>}
+   */
+  async startNavigation(fromLat, fromLon, toLat, toLon, opts = {}) {
+    if (!this._map) throw new Error('Call createMap() first');
+
+    const {
+      language          = 'ar',
+      arrivalThresholdM = 30,
+      onProgress        = () => {},
+      onStep            = () => {},
+      onOffRoute        = () => {},
+      onArrival         = () => {},
+      onError           = () => {},
+    } = opts;
+
+    const route = await this.getRoute(fromLat, fromLon, toLat, toLon, language);
+    this.showRoute(route);
+
+    let routeId        = route.route_id;
+    let currentStepIdx = -1;
+    let reroutePending = false;
+    let stopped        = false;
+    let watchId        = null;
+
+    const el = document.createElement('div');
+    el.style.cssText = 'width:22px;height:22px;border-radius:50%;background:#2563eb;border:3px solid white;box-shadow:0 2px 8px rgba(0,0,0,0.4);';
+    const navMarker = new this._maplibregl.Marker({ element: el, rotationAlignment: 'map' })
+      .setLngLat([fromLon, fromLat]).addTo(this._map);
+
+    this._map.easeTo({ center: [fromLon, fromLat], zoom: 17, pitch: 60, bearing: 0, duration: 800 });
+
+    const handlePosition = async ({ coords }) => {
+      if (stopped) return;
+      const { latitude: lat, longitude: lon, heading } = coords;
+
+      navMarker.setLngLat([lon, lat]);
+      if (heading !== null) navMarker.setRotation(heading);
+      this._map.easeTo({ center: [lon, lat], bearing: heading ?? 0, duration: 400 });
+
+      try {
+        const progress = await this.getRouteProgress(routeId, lat, lon);
+        onProgress(progress);
+
+        if (progress.step_index !== currentStepIdx) {
+          currentStepIdx = progress.step_index;
+          onStep(progress.current_step, progress.step_index);
+        }
+
+        if (progress.off_route && !reroutePending) {
+          reroutePending = true;
+          onOffRoute(progress.off_route_distance_m);
+          try {
+            const newRoute = await this.getRoute(lat, lon, toLat, toLon, language);
+            routeId = newRoute.route_id;
+            this.showRoute(newRoute);
+            currentStepIdx = -1;
+          } catch (e) { onError(e); }
+          finally { reroutePending = false; }
+        }
+
+        if (progress.distance_remaining_m <= arrivalThresholdM) {
+          onArrival();
+          stop();
+        }
+      } catch (e) { onError(e); }
+    };
+
+    if (!navigator.geolocation) throw new Error('Geolocation not supported by this browser.');
+    watchId = navigator.geolocation.watchPosition(
+      handlePosition,
+      (e) => onError(new Error(`GPS: ${e.message}`)),
+      { enableHighAccuracy: true, maximumAge: 1000, timeout: 10000 },
+    );
+
+    function stop() {
+      if (stopped) return;
+      stopped = true;
+      if (watchId !== null) navigator.geolocation.clearWatch(watchId);
+      navMarker.remove();
+    }
+
+    this._navSession = { stop };
+    return { route, stop };
+  }
+
+  /** Stop an active navigation session. */
+  stopNavigation() {
+    if (this._navSession) { this._navSession.stop(); this._navSession = null; }
+  }
+}
+
+export default MaaSClient;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@maas-mr/client",
+  "version": "1.0.0",
+  "description": "JavaScript SDK for Map-as-a-Service — Arabic maps, routing, and navigation for Mauritania",
+  "keywords": ["mauritania", "nouakchott", "maps", "arabic", "routing", "navigation", "maplibre"],
+  "type": "module",
+  "author": "MaaS",
+  "license": "MIT",
+  "homepage": "https://api.healthycornermauritanie.me",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "node build.js"
+  },
+  "peerDependencies": {
+    "maplibre-gl": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    }
+  }
+}