@atomiqlab/react-native-mapbox-navigation 1.1.1 → 1.1.3

package/docs/TROUBLESHOOTING.md

@@ -33,3 +33,25 @@ If not, verify you are running the latest package version and rebuilt native cod
 ```bash
 npx expo prebuild --clean
 ```
+
+## Prebuild Fails With Missing Token Error
+
+The config plugin now validates tokens early. Ensure one of these provides a public token:
+
+- `EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN`
+- `MAPBOX_PUBLIC_TOKEN`
+- `expo.extra.mapboxPublicToken`
+
+And provide downloads token:
+
+- `MAPBOX_DOWNLOADS_TOKEN` or `expo.extra.mapboxDownloadsToken`
+
+## Route Fetch Errors (401/403/429)
+
+Listen to `onError` / `addErrorListener` and check `code`:
+
+- `MAPBOX_TOKEN_INVALID` (invalid/expired token)
+- `MAPBOX_TOKEN_FORBIDDEN` (missing scopes)
+- `MAPBOX_RATE_LIMITED` (request throttling)
+
+For Android dependency download failures during build, verify `MAPBOX_DOWNLOADS_TOKEN` has `DOWNLOADS:READ` scope.

package/ios/MapboxNavigationModule.swift

@@ -157,8 +157,23 @@ public class MapboxNavigationModule: Module {
     }
   }
   
+  private func configuredMapboxPublicToken() -> String? {
+    guard let raw = Bundle.main.object(forInfoDictionaryKey: "MBXAccessToken") as? String else {
+      return nil
+    }
+    let token = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard token.hasPrefix("pk."), token.count > 20 else {
+      return nil
+    }
+    return token
+  }
+
   private func startNavigation(options: NavigationStartOptions, promise: Promise) {
     guard let destination = options.destination.toCLLocationCoordinate2D() else {
+      self.emitErrorAndShowScreen([
+        "code": "INVALID_COORDINATES",
+        "message": "Invalid coordinates provided"
+      ])
       promise.reject("INVALID_COORDINATES", "Invalid coordinates provided")
       return
     }
@@ -184,6 +199,10 @@ public class MapboxNavigationModule: Module {
           promise: promise
         )
       case .failure(let error):
+        self.emitErrorAndShowScreen([
+          "code": "CURRENT_LOCATION_UNAVAILABLE",
+          "message": error.localizedDescription
+        ])
         promise.reject("CURRENT_LOCATION_UNAVAILABLE", error.localizedDescription)
       }
     }
@@ -195,7 +214,16 @@ public class MapboxNavigationModule: Module {
     options: NavigationStartOptions,
     promise: Promise
   ) {
-    
+    guard configuredMapboxPublicToken() != nil else {
+      let message = "Missing or invalid MBXAccessToken. Add the package plugin to app.json and set EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN before prebuild."
+      self.emitErrorAndShowScreen([
+        "code": "MISSING_ACCESS_TOKEN",
+        "message": message
+      ])
+      promise.reject("MISSING_ACCESS_TOKEN", message)
+      return
+    }
+
     var waypoints = [Waypoint(coordinate: origin)]
     
     // Add intermediate waypoints if provided
@@ -225,6 +253,10 @@ public class MapboxNavigationModule: Module {
       switch result {
       case .success(let response):
         guard response.routes?.first != nil else {
+          self.emitErrorAndShowScreen([
+            "code": "NO_ROUTE",
+            "message": "No route found"
+          ])
           promise.reject("NO_ROUTE", "No route found")
           return
         }
@@ -272,11 +304,20 @@ public class MapboxNavigationModule: Module {
             promise.resolve(nil)
           }
         } else {
+          self.emitErrorAndShowScreen([
+            "code": "NO_ROOT_VC",
+            "message": "Could not find root view controller"
+          ])
           promise.reject("NO_ROOT_VC", "Could not find root view controller")
         }
         
       case .failure(let error):
-        promise.reject("ROUTE_ERROR", error.localizedDescription)
+        let (code, message) = self.mapDirectionsError(error)
+        self.emitErrorAndShowScreen([
+          "code": code,
+          "message": message
+        ])
+        promise.reject(code, message)
       }
     }
   }
@@ -292,6 +333,42 @@ public class MapboxNavigationModule: Module {
     }
   }
   
+  private func emitErrorAndShowScreen(_ payload: [String: Any]) {
+    sendEvent("onError", payload)
+
+    guard let navVC = navigationViewController else {
+      return
+    }
+
+    if navVC.presentingViewController == nil {
+      navigationViewController = nil
+      isCurrentlyNavigating = false
+      return
+    }
+
+    navVC.dismiss(animated: true) {
+      self.navigationViewController = nil
+      self.isCurrentlyNavigating = false
+    }
+  }
+
+  private func mapDirectionsError(_ error: Error) -> (String, String) {
+    let message = error.localizedDescription
+    let lowered = message.lowercased()
+
+    if lowered.contains("401") || lowered.contains("unauthorized") {
+      return ("MAPBOX_TOKEN_INVALID", "Route fetch failed: unauthorized. Check EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN and token scopes.")
+    }
+    if lowered.contains("403") || lowered.contains("forbidden") {
+      return ("MAPBOX_TOKEN_FORBIDDEN", "Route fetch failed: access forbidden. Verify token scopes and account permissions.")
+    }
+    if lowered.contains("429") || lowered.contains("rate") {
+      return ("MAPBOX_RATE_LIMITED", "Route fetch failed: rate limited by Mapbox.")
+    }
+
+    return ("ROUTE_ERROR", message)
+  }
+
   private func stopNavigation(promise: Promise) {
     guard let navVC = navigationViewController else {
       promise.resolve(nil)
@@ -611,3 +688,67 @@ private final class CurrentLocationResolver: NSObject, CLLocationManagerDelegate
     completion(result)
   }
 }
+
+private final class NavigationErrorViewController: UIViewController {
+  private let message: String
+
+  init(message: String) {
+    self.message = message
+    super.init(nibName: nil, bundle: nil)
+  }
+
+  required init?(coder: NSCoder) {
+    nil
+  }
+
+  override func viewDidLoad() {
+    super.viewDidLoad()
+
+    view.backgroundColor = UIColor(red: 11 / 255, green: 16 / 255, blue: 32 / 255, alpha: 1)
+
+    let titleLabel = UILabel()
+    titleLabel.translatesAutoresizingMaskIntoConstraints = false
+    titleLabel.text = "Navigation Error"
+    titleLabel.textColor = .white
+    titleLabel.font = UIFont.systemFont(ofSize: 28, weight: .bold)
+    titleLabel.textAlignment = .center
+    titleLabel.numberOfLines = 0
+
+    let messageLabel = UILabel()
+    messageLabel.translatesAutoresizingMaskIntoConstraints = false
+    messageLabel.text = message
+    messageLabel.textColor = UIColor(red: 214 / 255, green: 228 / 255, blue: 255 / 255, alpha: 1)
+    messageLabel.font = UIFont.systemFont(ofSize: 16, weight: .regular)
+    messageLabel.textAlignment = .center
+    messageLabel.numberOfLines = 0
+
+    let closeButton = UIButton(type: .system)
+    closeButton.translatesAutoresizingMaskIntoConstraints = false
+    closeButton.setTitle("Back", for: .normal)
+    closeButton.titleLabel?.font = UIFont.systemFont(ofSize: 17, weight: .semibold)
+    closeButton.backgroundColor = UIColor.white.withAlphaComponent(0.15)
+    closeButton.setTitleColor(.white, for: .normal)
+    closeButton.layer.cornerRadius = 10
+    closeButton.contentEdgeInsets = UIEdgeInsets(top: 12, left: 16, bottom: 12, right: 16)
+    closeButton.addTarget(self, action: #selector(closeTapped), for: .touchUpInside)
+
+    let stack = UIStackView(arrangedSubviews: [titleLabel, messageLabel, closeButton])
+    stack.translatesAutoresizingMaskIntoConstraints = false
+    stack.axis = .vertical
+    stack.alignment = .fill
+    stack.spacing = 20
+
+    view.addSubview(stack)
+
+    NSLayoutConstraint.activate([
+      stack.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 24),
+      stack.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -24),
+      stack.centerYAnchor.constraint(equalTo: view.centerYAnchor),
+    ])
+  }
+
+  @objc
+  private func closeTapped() {
+    dismiss(animated: true)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomiqlab/react-native-mapbox-navigation",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Native Mapbox turn-by-turn navigation for Expo and React Native (iOS + Android)",
   "main": "src/index.tsx",
   "types": "src/index.tsx",
@@ -27,6 +27,7 @@
     "README.md",
     "QUICKSTART.md",
     "CHANGELOG.md",
+    "SECURITY.md",
     "docs",
     "scripts"
   ],
@@ -70,6 +71,7 @@
     "react-native": "*"
   },
   "devDependencies": {
-    "expo-module-scripts": "^3.0.0"
+    "expo-module-scripts": "^3.0.0",
+    "typescript": "^5.9.3"
   }
 }

package/scripts/verify-release.mjs

@@ -5,9 +5,9 @@ import { fileURLToPath } from "node:url";
 
 const __filename = fileURLToPath(import.meta.url);
 const moduleDir = path.resolve(path.dirname(__filename), "..");
-const repoRoot = path.resolve(moduleDir, "..", "..");
-const androidDir = path.join(repoRoot, "android");
-const envFilePath = path.join(repoRoot, ".env");
+const repoRoot = moduleDir;
+const androidDir = path.join(moduleDir, "android");
+const envFilePath = path.join(moduleDir, ".env");
 
 function loadDotEnv(filePath) {
   if (!existsSync(filePath)) {
@@ -49,7 +49,8 @@ function run(command, cwd = moduleDir, options = {}) {
       env: {
         ...process.env,
         GRADLE_USER_HOME:
-          process.env.GRADLE_USER_HOME || "/tmp/gradle-user-home-react-native-mapbox-navigation",
+          process.env.GRADLE_USER_HOME ||
+          "/tmp/gradle-user-home-react-native-mapbox-navigation",
       },
     });
     if (output?.length) {
@@ -72,7 +73,9 @@ function run(command, cwd = moduleDir, options = {}) {
       combined.includes("SocketException: Operation not permitted");
 
     if (optionalOnOfflineGradle && skippableGradleEnvironmentIssue) {
-      console.warn(`\nSkipping optional Gradle check due to restricted/offline environment: ${command}`);
+      console.warn(
+        `\nSkipping optional Gradle check due to restricted/offline environment: ${command}`,
+      );
       return;
     }
     throw error;
@@ -95,7 +98,14 @@ function runWithFallback(commands, cwd, options = {}) {
 
 loadDotEnv(envFilePath);
 
-run("npx tsc --noEmit", repoRoot);
+const tsconfigPath = path.join(moduleDir, "tsconfig.json");
+if (existsSync(tsconfigPath)) {
+  run(`npx --no-install tsc -p ${tsconfigPath} --noEmit`, moduleDir);
+} else {
+  console.log(
+    "\n> Skipping TypeScript check (tsconfig.json not found in package root).",
+  );
+}
 
 if (existsSync(path.join(androidDir, "gradlew"))) {
   runWithFallback(
@@ -104,12 +114,17 @@ if (existsSync(path.join(androidDir, "gradlew"))) {
       "./gradlew :mapbox-navigation-native:compileDebugKotlin",
     ],
     androidDir,
-    { optionalOnOfflineGradle: true }
+    { optionalOnOfflineGradle: true },
   );
 } else {
-  console.log("\n> Skipping Android compile check (android/gradlew not found).");
+  console.log(
+    "\n> Skipping Android compile check (android/gradlew not found).",
+  );
 }
 
-run("npm pack --dry-run --cache /tmp/npm-cache-react-native-mapbox-navigation", moduleDir);
+run(
+  "npm pack --dry-run --cache /tmp/npm-cache-react-native-mapbox-navigation",
+  moduleDir,
+);
 
 console.log("\nRelease verification completed.");

package/src/MapboxNavigation.types.ts

@@ -1,36 +1,66 @@
+/** Geographic coordinate in WGS84 format. */
 export type Coordinate = {
+  /** Latitude in range -90..90 */
   latitude: number;
+  /** Longitude in range -180..180 */
   longitude: number;
 };
 
+/** A route point that can optionally include a display name. */
 export type Waypoint = Coordinate & {
+  /** Optional label for UI/debug output. */
   name?: string;
 };
 
+/**
+ * Options passed to `startNavigation`.
+ */
 export type NavigationOptions = {
+  /** Optional route origin. If omitted, native layer may resolve current location. */
   startOrigin?: Coordinate;
+  /** Final destination waypoint (required). */
   destination: Waypoint;
+  /** Optional intermediate waypoints. */
   waypoints?: Waypoint[];
+  /** Enable route simulation for testing without physical movement. */
   shouldSimulateRoute?: boolean;
+  /** UI theme selection for native UI. */
   uiTheme?: 'system' | 'light' | 'dark' | 'day' | 'night';
+  /** Request alternative routes when available. */
   routeAlternatives?: boolean;
+  /** Distance unit for guidance. */
   distanceUnit?: 'metric' | 'imperial';
+  /** Guidance language (for example `en`, `fr`). */
   language?: string;
+  /** Start muted. */
   mute?: boolean;
+  /** Voice volume range `0..1`. */
   voiceVolume?: number;
+  /** Camera pitch range `0..85`. */
   cameraPitch?: number;
+  /** Camera zoom range `1..22`. */
   cameraZoom?: number;
+  /** Camera behavior mode. */
   cameraMode?: 'following' | 'overview';
+  /** One style URI used for both day/night fallback. */
   mapStyleUri?: string;
+  /** Day style URI override. */
   mapStyleUriDay?: string;
+  /** Night style URI override. */
   mapStyleUriNight?: string;
+  /** Show speed limit panel when supported. */
   showsSpeedLimits?: boolean;
+  /** Show current road name label. */
   showsWayNameLabel?: boolean;
+  /** Show trip progress summary. */
   showsTripProgress?: boolean;
+  /** Show maneuver/instruction view. */
   showsManeuverView?: boolean;
+  /** Show default action buttons in native UI. */
   showsActionButtons?: boolean;
 };
 
+/** Runtime settings/state returned by `getNavigationSettings()`. */
 export type NavigationSettings = {
   isNavigating: boolean;
   mute: boolean;
@@ -39,6 +69,7 @@ export type NavigationSettings = {
   language: string;
 };
 
+/** Location update payload emitted by native layer. */
 export type LocationUpdate = {
   latitude: number;
   longitude: number;
@@ -48,6 +79,7 @@ export type LocationUpdate = {
   accuracy?: number;
 };
 
+/** Route progress payload emitted by native layer. */
 export type RouteProgress = {
   distanceTraveled: number;
   distanceRemaining: number;
@@ -55,52 +87,45 @@ export type RouteProgress = {
   fractionTraveled: number;
 };
 
+/** Arrival event payload. */
 export type ArrivalEvent = {
   index?: number;
   name?: string;
 };
 
+/** Error payload emitted by native layer. */
 export type NavigationError = {
+  /** Machine-readable error code. */
   code: string;
+  /** Developer-readable error details. */
   message: string;
 };
 
+/** Banner instruction payload emitted during guidance. */
 export type BannerInstruction = {
   primaryText: string;
   secondaryText?: string;
   stepDistanceRemaining?: number;
 };
 
+/** Event subscription handle. */
 export type Subscription = {
   remove: () => void;
 };
 
+/** Native module interface bridged from iOS/Android. */
 export interface MapboxNavigationModule {
-  // Start navigation with options
   startNavigation(options: NavigationOptions): Promise<void>;
-  
-  // Stop/cancel navigation
   stopNavigation(): Promise<void>;
-  
-  // Mute/unmute voice guidance
   setMuted(muted: boolean): Promise<void>;
-
-  // Set voice volume (0.0 - 1.0)
   setVoiceVolume(volume: number): Promise<void>;
-
-  // Set distance unit used by spoken and visual instructions
   setDistanceUnit(unit: 'metric' | 'imperial'): Promise<void>;
-
-  // Set route instruction language (BCP-47, e.g. 'en', 'fr')
   setLanguage(language: string): Promise<void>;
-  
-  // Check if navigation is active
   isNavigating(): Promise<boolean>;
-
-  // Get current native navigation settings
   getNavigationSettings(): Promise<NavigationSettings>;
 }
 
+/** Props for embedded `MapboxNavigationView`. */
 export interface MapboxNavigationViewProps {
   style?: any;
   startOrigin?: Coordinate;
@@ -125,12 +150,17 @@ export interface MapboxNavigationViewProps {
   showsTripProgress?: boolean;
   showsManeuverView?: boolean;
   showsActionButtons?: boolean;
-  
-  // Event callbacks
+
+  /** Callback for location changes. */
   onLocationChange?: (location: LocationUpdate) => void;
+  /** Callback for route progress changes. */
   onRouteProgressChange?: (progress: RouteProgress) => void;
+  /** Callback when arrival is detected. */
   onArrive?: (point: ArrivalEvent) => void;
+  /** Callback when navigation is canceled by user. */
   onCancelNavigation?: () => void;
+  /** Callback for native errors. */
   onError?: (error: NavigationError) => void;
+  /** Callback for banner instruction updates. */
   onBannerInstruction?: (instruction: BannerInstruction) => void;
 }