@atomiqlab/react-native-mapbox-navigation 1.1.0 → 1.1.2

package/README.md

@@ -1,25 +1,33 @@
 # @atomiqlab/react-native-mapbox-navigation
 
-Native Mapbox turn-by-turn navigation bridge for Expo / React Native (iOS + Android).
+Native Mapbox turn-by-turn navigation for Expo apps on iOS and Android.
 
-## Highlights
+## Features
 
-- Full-screen native navigation (`startNavigation`).
-- Embedded native navigation (`MapboxNavigationView`).
-- Event stream: location, route progress, banner instruction, arrival, cancel, error.
-- Flexible camera/theme/style controls.
-- Expo config plugin for Android + iOS setup defaults.
+- Full-screen native navigation via `startNavigation`.
+- Embedded native navigation UI via `MapboxNavigationView`.
+- Real-time events: location, route progress, banner instruction, arrival, cancel, and error.
+- Runtime controls for mute, voice volume, distance unit, and language.
+- Navigation customization: camera mode/pitch/zoom, theme, map style, and UI visibility toggles.
+- Expo config plugin that applies required Android and iOS native setup.
+
+## Requirements
+
+- Expo SDK `>=50`
+- iOS `14+`
+- Mapbox access credentials:
+  - Public token (`pk...`)
+  - Downloads token (`sk...`) with `DOWNLOADS:READ`
 
 ## Installation
 
 ```bash
 npm install @atomiqlab/react-native-mapbox-navigation
-npx expo install expo-build-properties
 ```
 
-## Expo Config
+## Expo Setup
 
-Add plugin in app config:
+Add the plugin in your app config (`app.json` or `app.config.js`):
 
 ```json
 {
@@ -31,18 +39,28 @@ Add plugin in app config:
 }
 ```
 
-### Required tokens
+Set these environment variables:
 
-- `EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN`: Mapbox public token (`pk...`)
-- `MAPBOX_DOWNLOADS_TOKEN`: Mapbox downloads token (`sk...`) with `DOWNLOADS:READ`
+- `EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN` (Mapbox public token)
+- `MAPBOX_DOWNLOADS_TOKEN` (Mapbox downloads token)
 
-Then regenerate native projects:
+Regenerate native projects:
 
 ```bash
 npx expo prebuild --clean
 ```
 
-## Quick Usage
+### Token validation behavior
+
+The config plugin now fails fast during prebuild/build when tokens are missing or malformed:
+
+- Missing/invalid public token (`pk...`)
+- Missing/invalid downloads token (`sk...`)
+
+This prevents silent runtime failures and surfaces setup issues early.
+
+
+## Quick Start
 
 ```ts
 import {
@@ -60,11 +78,14 @@ await startNavigation({
   destination: { latitude: 37.7847, longitude: -122.4073, name: "Downtown" },
   startOrigin: { latitude: 37.7749, longitude: -122.4194 },
   shouldSimulateRoute: true,
+  routeAlternatives: true,
   cameraMode: "following",
   uiTheme: "system",
+  distanceUnit: "metric",
+  language: "en",
 });
 
-const subs = [
+const subscriptions = [
   addLocationChangeListener((location) => console.log(location)),
   addRouteProgressChangeListener((progress) => console.log(progress)),
   addBannerInstructionListener((instruction) => console.log(instruction.primaryText)),
@@ -74,11 +95,11 @@ const subs = [
 ];
 
 // Cleanup
-subs.forEach((sub) => sub.remove());
+subscriptions.forEach((sub) => sub.remove());
 await stopNavigation();
 ```
 
-## Embedded View
+## Embedded Navigation View
 
 ```tsx
 import { MapboxNavigationView } from "@atomiqlab/react-native-mapbox-navigation";
@@ -89,13 +110,363 @@ import { MapboxNavigationView } from "@atomiqlab/react-native-mapbox-navigation"
   startOrigin={{ latitude: 37.7749, longitude: -122.4194 }}
   shouldSimulateRoute
   cameraMode="following"
+  showsTripProgress
   onBannerInstruction={(instruction) => console.log(instruction.primaryText)}
+  onRouteProgressChange={(progress) => console.log(progress.fractionTraveled)}
+  onError={(error) => console.warn(error.message)}
 />;
 ```
 
-## API Surface
+```tsx
+import React, { useEffect, useMemo, useState } from "react";
+import {
+  addArriveListener,
+  addBannerInstructionListener,
+  addCancelNavigationListener,
+  addErrorListener,
+  addLocationChangeListener,
+  addRouteProgressChangeListener,
+  getNavigationSettings,
+  isNavigating,
+  MapboxNavigationView,
+  setDistanceUnit,
+  setLanguage,
+  setMuted,
+  setVoiceVolume,
+  startNavigation,
+  stopNavigation,
+  type Waypoint,
+} from "@atomiqlab/react-native-mapbox-navigation";
+import {
+  Platform,
+  Pressable,
+  SafeAreaView,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TextInput,
+  View,
+} from "react-native";
+
+const START: Waypoint = {
+  latitude: 37.7749,
+  longitude: -122.4194,
+  name: "San Francisco",
+};
+const DEST: Waypoint = {
+  latitude: 37.7847,
+  longitude: -122.4073,
+  name: "Downtown",
+};
+
+export default function Index() {
+  const [logs, setLogs] = useState<string[]>([]);
+  const [navigating, setNavigating] = useState(false);
+  const [showEmbedded, setShowEmbedded] = useState(false);
+
+  const [mute, setMuteState] = useState(false);
+  const [unit, setUnit] = useState<"metric" | "imperial">("metric");
+  const [language, setLanguageState] = useState("en");
+  const [volumeInput, setVolumeInput] = useState("1");
+
+  const pushLog = (line: string) =>
+    setLogs((prev) =>
+      [`${new Date().toLocaleTimeString()}  ${line}`, ...prev].slice(0, 40),
+    );
+
+  useEffect(() => {
+    const s1 = addLocationChangeListener((e) =>
+      pushLog(`location: ${e.latitude.toFixed(5)}, ${e.longitude.toFixed(5)}`),
+    );
+    const s2 = addRouteProgressChangeListener((e) =>
+      pushLog(`progress: ${(e.fractionTraveled * 100).toFixed(1)}%`),
+    );
+    const s3 = addBannerInstructionListener((e) =>
+      pushLog(`banner: ${e.primaryText}`),
+    );
+    const s4 = addArriveListener((e) => {
+      pushLog(`arrive: ${e.name ?? "destination"}`);
+      setNavigating(false);
+    });
+    const s5 = addCancelNavigationListener(() => {
+      pushLog("cancelled");
+      setNavigating(false);
+    });
+    const s6 = addErrorListener((e) =>
+      pushLog(`error: ${e.message ?? e.code}`),
+    );
+
+    (async () => {
+      try {
+        setNavigating(await isNavigating());
+        pushLog(`isNavigating() loaded`);
+      } catch (e: any) {
+        pushLog(`isNavigating failed: ${e?.message ?? "unknown"}`);
+      }
+    })();
 
-### Core functions
+    return () => {
+      s1.remove();
+      s2.remove();
+      s3.remove();
+      s4.remove();
+      s5.remove();
+      s6.remove();
+    };
+  }, []);
+
+  const canRun = useMemo(
+    () => Platform.OS === "ios" || Platform.OS === "android",
+    [],
+  );
+
+  if (!canRun) {
+    return (
+      <SafeAreaView style={styles.center}>
+        <Text style={styles.title}>Run on iOS/Android only</Text>
+      </SafeAreaView>
+    );
+  }
+
+  return (
+    <SafeAreaView style={styles.container}>
+      <ScrollView contentContainerStyle={styles.content}>
+        <Text style={styles.title}>Mapbox Navigation Full API Test</Text>
+        <Text style={styles.status}>
+          Status: {navigating ? "Navigating" : "Idle"}
+        </Text>
+
+        <View style={styles.row}>
+          <Pressable
+            style={styles.btn}
+            onPress={async () => {
+              try {
+                await startNavigation({
+                  startOrigin: START,
+                  destination: DEST,
+                  shouldSimulateRoute: true,
+                  routeAlternatives: true,
+                  cameraMode: "following",
+                  uiTheme: "system",
+                  mute,
+                  voiceVolume: Math.max(
+                    0,
+                    Math.min(Number(volumeInput) || 1, 1),
+                  ),
+                  distanceUnit: unit,
+                  language,
+                });
+                setNavigating(true);
+                pushLog("startNavigation() ok");
+              } catch (e: any) {
+                pushLog(`startNavigation failed: ${e?.message ?? "unknown"}`);
+              }
+            }}
+          >
+            <Text style={styles.btnText}>startNavigation</Text>
+          </Pressable>
+
+          <Pressable
+            style={styles.btn}
+            onPress={async () => {
+              try {
+                await stopNavigation();
+                setNavigating(false);
+                pushLog("stopNavigation() ok");
+              } catch (e: any) {
+                pushLog(`stopNavigation failed: ${e?.message ?? "unknown"}`);
+              }
+            }}
+          >
+            <Text style={styles.btnText}>stopNavigation</Text>
+          </Pressable>
+        </View>
+
+        <View style={styles.row}>
+          <Pressable
+            style={styles.btn}
+            onPress={async () =>
+              pushLog(`isNavigating(): ${await isNavigating()}`)
+            }
+          >
+            <Text style={styles.btnText}>isNavigating</Text>
+          </Pressable>
+
+          <Pressable
+            style={styles.btn}
+            onPress={async () =>
+              pushLog(
+                `getNavigationSettings(): ${JSON.stringify(await getNavigationSettings())}`,
+              )
+            }
+          >
+            <Text style={styles.btnText}>getNavigationSettings</Text>
+          </Pressable>
+        </View>
+
+        <View style={styles.card}>
+          <Text style={styles.label}>mute / setMuted</Text>
+          <View style={styles.row}>
+            <Pressable
+              style={styles.btn}
+              onPress={async () => {
+                const next = !mute;
+                setMuteState(next);
+                await setMuted(next);
+                pushLog(`setMuted(${next})`);
+              }}
+            >
+              <Text style={styles.btnText}>{mute ? "Unmute" : "Mute"}</Text>
+            </Pressable>
+          </View>
+
+          <Text style={styles.label}>setVoiceVolume (0..1)</Text>
+          <View style={styles.row}>
+            <TextInput
+              style={styles.input}
+              value={volumeInput}
+              onChangeText={setVolumeInput}
+              keyboardType="decimal-pad"
+            />
+            <Pressable
+              style={styles.btn}
+              onPress={async () => {
+                const vol = Math.max(0, Math.min(Number(volumeInput) || 1, 1));
+                await setVoiceVolume(vol);
+                pushLog(`setVoiceVolume(${vol})`);
+              }}
+            >
+              <Text style={styles.btnText}>Apply</Text>
+            </Pressable>
+          </View>
+
+          <Text style={styles.label}>setDistanceUnit</Text>
+          <View style={styles.row}>
+            <Pressable
+              style={styles.btn}
+              onPress={async () => {
+                setUnit("metric");
+                await setDistanceUnit("metric");
+                pushLog("setDistanceUnit(metric)");
+              }}
+            >
+              <Text style={styles.btnText}>Metric</Text>
+            </Pressable>
+            <Pressable
+              style={styles.btn}
+              onPress={async () => {
+                setUnit("imperial");
+                await setDistanceUnit("imperial");
+                pushLog("setDistanceUnit(imperial)");
+              }}
+            >
+              <Text style={styles.btnText}>Imperial</Text>
+            </Pressable>
+          </View>
+
+          <Text style={styles.label}>setLanguage</Text>
+          <View style={styles.row}>
+            <TextInput
+              style={styles.input}
+              value={language}
+              onChangeText={setLanguageState}
+            />
+            <Pressable
+              style={styles.btn}
+              onPress={async () => {
+                await setLanguage(language.trim() || "en");
+                pushLog(`setLanguage(${language.trim() || "en"})`);
+              }}
+            >
+              <Text style={styles.btnText}>Apply</Text>
+            </Pressable>
+          </View>
+        </View>
+
+        <Pressable
+          style={styles.btn}
+          onPress={() => setShowEmbedded((v) => !v)}
+        >
+          <Text style={styles.btnText}>
+            {showEmbedded ? "Hide" : "Show"} Embedded MapboxNavigationView
+          </Text>
+        </Pressable>
+
+        {showEmbedded ? (
+          <View style={styles.embeddedWrap}>
+            <MapboxNavigationView
+              style={{ flex: 1 }}
+              destination={DEST}
+              startOrigin={START}
+              shouldSimulateRoute
+              cameraMode="overview"
+              uiTheme="system"
+              onError={(e) => pushLog(`embedded error: ${e.message ?? e.code}`)}
+              onBannerInstruction={(e) =>
+                pushLog(`embedded banner: ${e.primaryText}`)
+              }
+              onArrive={(e) =>
+                pushLog(`embedded arrive: ${e.name ?? "destination"}`)
+              }
+              onCancelNavigation={() => pushLog("embedded cancelled")}
+            />
+          </View>
+        ) : null}
+
+        <View style={styles.card}>
+          <Text style={styles.label}>Event Logs</Text>
+          {logs.map((l, i) => (
+            <Text key={`${l}-${i}`} style={styles.log}>
+              {l}
+            </Text>
+          ))}
+        </View>
+      </ScrollView>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, backgroundColor: "#0b1020" },
+  center: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "#0b1020",
+  },
+  content: { padding: 14, gap: 10, paddingBottom: 28 },
+  title: { color: "#fff", fontSize: 22, fontWeight: "800" },
+  status: { color: "#8ec5ff", fontSize: 13 },
+  row: { flexDirection: "row", gap: 8, alignItems: "center" },
+  card: { backgroundColor: "#131a2d", borderRadius: 12, padding: 10, gap: 8 },
+  label: { color: "#cde4ff", fontSize: 12, fontWeight: "700" },
+  input: {
+    flex: 1,
+    backgroundColor: "#0e1426",
+    borderColor: "#2b3a5d",
+    borderWidth: 1,
+    borderRadius: 8,
+    color: "#fff",
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+  },
+  btn: {
+    flex: 1,
+    backgroundColor: "#2563eb",
+    borderRadius: 10,
+    paddingVertical: 10,
+    paddingHorizontal: 10,
+    alignItems: "center",
+  },
+  btnText: { color: "#fff", fontWeight: "700", fontSize: 12 },
+  embeddedWrap: { height: 320, borderRadius: 12, overflow: "hidden" },
+  log: { color: "#dbeafe", fontSize: 11, marginBottom: 2 },
+});
+```
+
+## API Overview
+
+Core functions:
 
 - `startNavigation(options)`
 - `stopNavigation()`
@@ -106,7 +477,7 @@ import { MapboxNavigationView } from "@atomiqlab/react-native-mapbox-navigation"
 - `setDistanceUnit(unit)`
 - `setLanguage(language)`
 
-### Listener helpers
+Event listeners:
 
 - `addLocationChangeListener(listener)`
 - `addRouteProgressChangeListener(listener)`
@@ -115,17 +486,28 @@ import { MapboxNavigationView } from "@atomiqlab/react-native-mapbox-navigation"
 - `addCancelNavigationListener(listener)`
 - `addErrorListener(listener)`
 
-### Key navigation options
+Main `NavigationOptions` fields:
 
-- Routing: `destination`, `startOrigin`, `waypoints`, `routeAlternatives`, `shouldSimulateRoute`
+- Route: `destination`, `startOrigin`, `waypoints`, `routeAlternatives`, `shouldSimulateRoute`
 - Camera: `cameraMode`, `cameraPitch`, `cameraZoom`
 - Theme/style: `uiTheme`, `mapStyleUri`, `mapStyleUriDay`, `mapStyleUriNight`
-- Guidance/UI: `distanceUnit`, `language`, `mute`, `voiceVolume`
-- Visibility toggles: `showsSpeedLimits`, `showsWayNameLabel`, `showsTripProgress`, `showsManeuverView`, `showsActionButtons`
+- Guidance: `distanceUnit`, `language`, `mute`, `voiceVolume`
+- UI toggles: `showsSpeedLimits`, `showsWayNameLabel`, `showsTripProgress`, `showsManeuverView`, `showsActionButtons`
+
+Full types: `src/MapboxNavigation.types.ts`
+
+## Common Error Codes
+
+- `MAPBOX_TOKEN_INVALID`: invalid/expired token or unauthorized access
+- `MAPBOX_TOKEN_FORBIDDEN`: token lacks required scopes/permissions
+- `MAPBOX_RATE_LIMITED`: Mapbox rate limit reached
+- `ROUTE_FETCH_FAILED`: route request failed with native details
+- `CURRENT_LOCATION_UNAVAILABLE`: unable to resolve device location
+- `INVALID_COORDINATES`: invalid origin/destination coordinates
 
-Full type reference: `src/MapboxNavigation.types.ts`
+Subscribe via `addErrorListener` or `onError` to surface these to developers during testing and production diagnostics.
 
-## Platform behavior
+## Platform Notes
 
-- Android: `startOrigin` optional; current location start is supported.
-- iOS: `startOrigin` optional; when omitted, the module resolves current device location (requires location permission).
+- Android: `startOrigin` is optional (current location is supported).
+- iOS: `startOrigin` is optional (current location is resolved at runtime with location permission).

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest published minor version receives security updates.
+
+## Reporting a Vulnerability
+
+- Open a private security advisory on GitHub, or
+- Email the maintainers listed in the repository profile.
+
+Include:
+- Package version
+- Platform (iOS/Android)
+- Reproduction steps
+- Impact assessment
+
+## Dependency Audit Policy
+
+`npm audit` output in Expo/React Native apps can include transitive advisories from upstream tooling.
+
+Project policy:
+1. Prioritize vulnerabilities reachable in production runtime dependencies.
+2. Track dev/build-only advisories from Expo/Metro/Jest and resolve when upstream ships patched versions.
+3. Never run `npm audit fix --force` blindly in release branches.
+4. Keep Expo SDK and React Native versions updated to receive upstream security fixes.
+
+## Token Security
+
+- Never commit Mapbox tokens to git.
+- Use environment variables or CI/CD secrets.
+- Rotate tokens immediately if leaked.
+
+Required tokens:
+- `EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN` (`pk...`)
+- `MAPBOX_DOWNLOADS_TOKEN` (`sk...`, `DOWNLOADS:READ`)

package/android/src/main/java/expo/modules/mapboxnavigation/MapboxNavigationActivity.kt

@@ -112,6 +112,15 @@ class MapboxNavigationActivity : AppCompatActivity() {
 
     override fun onRouteFetchFailed(reasons: List<RouterFailure>, routeOptions: RouteOptions) {
       Log.e(TAG, "Route fetch failed. reasons=${reasons.size}, options=$routeOptions")
+      val (code, message) = mapRouteFetchFailure(reasons)
+      MapboxNavigationEventBridge.emit(
+        "onError",
+        mapOf(
+          "code" to code,
+          "message" to message
+        )
+      )
+      showErrorAndStay(message, null)
     }
 
     override fun onRouteFetchSuccessful(routes: List<NavigationRoute>) {
@@ -127,6 +136,13 @@ class MapboxNavigationActivity : AppCompatActivity() {
 
     override fun onRouteFetchCanceled(routeOptions: RouteOptions, routerOrigin: RouterOrigin) {
       Log.w(TAG, "Route fetch canceled. origin=$routerOrigin, options=$routeOptions")
+      MapboxNavigationEventBridge.emit(
+        "onError",
+        mapOf(
+          "code" to "ROUTE_FETCH_CANCELED",
+          "message" to "Route fetch canceled (origin: $routerOrigin)."
+        )
+      )
     }
   }
 
@@ -301,6 +317,25 @@ class MapboxNavigationActivity : AppCompatActivity() {
     }
   }
 
+  private fun mapRouteFetchFailure(reasons: List<RouterFailure>): Pair<String, String> {
+    val details = reasons.joinToString(" | ") { it.message.orEmpty() }.trim()
+    if (details.contains("401") || details.contains("unauthorized", ignoreCase = true)) {
+      return "MAPBOX_TOKEN_INVALID" to
+        "Route fetch failed: unauthorized. Check EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN and token scopes."
+    }
+    if (details.contains("403") || details.contains("forbidden", ignoreCase = true)) {
+      return "MAPBOX_TOKEN_FORBIDDEN" to
+        "Route fetch failed: access forbidden. Verify token scopes and account permissions."
+    }
+    if (details.contains("429") || details.contains("rate", ignoreCase = true)) {
+      return "MAPBOX_RATE_LIMITED" to
+        "Route fetch failed: rate limited by Mapbox."
+    }
+
+    return "ROUTE_FETCH_FAILED" to
+      (if (details.isNotEmpty()) "Route fetch failed: $details" else "Route fetch failed for unknown reason.")
+  }
+
   private fun hasLocationPermission(): Boolean {
     val fineGranted = ContextCompat.checkSelfPermission(
       this,
@@ -322,6 +357,14 @@ class MapboxNavigationActivity : AppCompatActivity() {
       Log.e(TAG, message)
     }
 
+    MapboxNavigationEventBridge.emit(
+      "onError",
+      mapOf(
+        "code" to "NATIVE_ERROR",
+        "message" to message
+      )
+    )
+
     val errorView = TextView(this).apply {
       text = message
       gravity = Gravity.CENTER

package/app.plugin.js

@@ -32,6 +32,64 @@ const REQUIRED_ANDROID_PERMISSIONS = [
 const DEFAULT_IOS_LOCATION_USAGE =
   "Allow $(PRODUCT_NAME) to access your location for turn-by-turn navigation.";
 
+function resolveToken(config, envKeys = [], extraKeys = []) {
+  for (const key of envKeys) {
+    const value = process.env[key]?.trim();
+    if (value) {
+      return value;
+    }
+  }
+
+  const extra = config?.extra ?? {};
+  for (const key of extraKeys) {
+    const value = typeof extra[key] === "string" ? extra[key].trim() : "";
+    if (value) {
+      return value;
+    }
+  }
+
+  return "";
+}
+
+function validateMapboxTokenShape(token, expectedPrefix) {
+  return token.startsWith(expectedPrefix) && token.length > 20;
+}
+
+function assertRequiredTokens(config) {
+  const publicToken = resolveToken(
+    config,
+    ["EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN", "MAPBOX_PUBLIC_TOKEN"],
+    ["mapboxPublicToken", "expoPublicMapboxAccessToken", "mapboxAccessToken"]
+  );
+  const downloadsToken = resolveToken(
+    config,
+    ["MAPBOX_DOWNLOADS_TOKEN"],
+    ["mapboxDownloadsToken"]
+  );
+
+  if (!publicToken) {
+    throw new Error(
+      "[@atomiqlab/react-native-mapbox-navigation] Missing EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN (or MAPBOX_PUBLIC_TOKEN / expo.extra.mapboxPublicToken)."
+    );
+  }
+  if (!validateMapboxTokenShape(publicToken, "pk.")) {
+    throw new Error(
+      "[@atomiqlab/react-native-mapbox-navigation] Invalid public token format. Expected a Mapbox public token starting with 'pk.'."
+    );
+  }
+
+  if (!downloadsToken) {
+    throw new Error(
+      "[@atomiqlab/react-native-mapbox-navigation] Missing MAPBOX_DOWNLOADS_TOKEN (or expo.extra.mapboxDownloadsToken)."
+    );
+  }
+  if (!validateMapboxTokenShape(downloadsToken, "sk.")) {
+    throw new Error(
+      "[@atomiqlab/react-native-mapbox-navigation] Invalid downloads token format. Expected a Mapbox secret token starting with 'sk.' and DOWNLOADS:READ scope."
+    );
+  }
+}
+
 function ensureAndroidPermissions(androidManifest) {
   const manifest = androidManifest.manifest;
   if (!manifest["uses-permission"]) {
@@ -114,10 +172,11 @@ function withMapboxNavigationAndroid(config) {
 function withMapboxNavigationIos(config) {
   return withInfoPlist(config, (config) => {
     const infoPlist = config.modResults;
-    const mapboxPublicToken =
-      process.env.EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN ||
-      process.env.MAPBOX_PUBLIC_TOKEN ||
-      "";
+    const mapboxPublicToken = resolveToken(
+      config,
+      ["EXPO_PUBLIC_MAPBOX_ACCESS_TOKEN", "MAPBOX_PUBLIC_TOKEN"],
+      ["mapboxPublicToken", "expoPublicMapboxAccessToken", "mapboxAccessToken"]
+    );
 
     if (!infoPlist.MBXAccessToken && mapboxPublicToken) {
       infoPlist.MBXAccessToken = mapboxPublicToken;
@@ -142,6 +201,7 @@ function withMapboxNavigationIos(config) {
 }
 
 const withMapboxNavigation = (config) => {
+  assertRequiredTokens(config);
   config = withMapboxNavigationAndroid(config);
   config = withMapboxNavigationIos(config);
   return config;
@@ -150,5 +210,5 @@ const withMapboxNavigation = (config) => {
 module.exports = createRunOncePlugin(
   withMapboxNavigation,
   "react-native-mapbox-navigation-plugin",
-  "1.1.0"
+  "1.1.1"
 );

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

@@ -159,6 +159,10 @@ public class MapboxNavigationModule: Module {
   
   private func startNavigation(options: NavigationStartOptions, promise: Promise) {
     guard let destination = options.destination.toCLLocationCoordinate2D() else {
+      self.sendEvent("onError", [
+        "code": "INVALID_COORDINATES",
+        "message": "Invalid coordinates provided"
+      ])
       promise.reject("INVALID_COORDINATES", "Invalid coordinates provided")
       return
     }
@@ -184,6 +188,10 @@ public class MapboxNavigationModule: Module {
           promise: promise
         )
       case .failure(let error):
+        self.sendEvent("onError", [
+          "code": "CURRENT_LOCATION_UNAVAILABLE",
+          "message": error.localizedDescription
+        ])
         promise.reject("CURRENT_LOCATION_UNAVAILABLE", error.localizedDescription)
       }
     }
@@ -225,6 +233,10 @@ public class MapboxNavigationModule: Module {
       switch result {
       case .success(let response):
         guard response.routes?.first != nil else {
+          self.sendEvent("onError", [
+            "code": "NO_ROUTE",
+            "message": "No route found"
+          ])
           promise.reject("NO_ROUTE", "No route found")
           return
         }
@@ -276,7 +288,12 @@ public class MapboxNavigationModule: Module {
         }
         
       case .failure(let error):
-        promise.reject("ROUTE_ERROR", error.localizedDescription)
+        let (code, message) = self.mapDirectionsError(error)
+        self.sendEvent("onError", [
+          "code": code,
+          "message": message
+        ])
+        promise.reject(code, message)
       }
     }
   }
@@ -292,6 +309,23 @@ public class MapboxNavigationModule: Module {
     }
   }
   
+  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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomiqlab/react-native-mapbox-navigation",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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;
 }

package/src/index.tsx

@@ -2,24 +2,22 @@ import { requireNativeModule, requireNativeViewManager } from "expo-modules-core
 import { ViewProps } from "react-native";
 
 import type {
-    ArrivalEvent,
-    BannerInstruction,
-    LocationUpdate,
-    MapboxNavigationModule as MapboxNavigationModuleType,
-    MapboxNavigationViewProps,
-    NavigationSettings,
-    NavigationError,
-    NavigationOptions,
-    RouteProgress,
-    Subscription,
+  ArrivalEvent,
+  BannerInstruction,
+  LocationUpdate,
+  MapboxNavigationModule as MapboxNavigationModuleType,
+  MapboxNavigationViewProps,
+  NavigationSettings,
+  NavigationError,
+  NavigationOptions,
+  RouteProgress,
+  Subscription,
 } from "./MapboxNavigation.types";
 
-// Get the native module (use requireNativeModule instead of deprecated NativeModulesProxy)
 const MapboxNavigationModule = requireNativeModule<MapboxNavigationModuleType>(
   "MapboxNavigationModule",
 );
 
-// The native module already acts as an EventEmitter; don't wrap with `new EventEmitter`.
 const emitter = MapboxNavigationModule as unknown as {
   addListener: (
     eventName: string,
@@ -106,74 +104,166 @@ function normalizeNavigationOptions(options: NavigationOptions): NavigationOptio
   };
 }
 
-// Module API
+function normalizeNativeError(error: unknown, fallbackCode = "NATIVE_ERROR"): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  const candidate = error as { code?: string; message?: string } | undefined;
+  const code = candidate?.code ?? fallbackCode;
+  const message = candidate?.message ?? "Unknown native error";
+  return new Error(`[${code}] ${message}`);
+}
+
+/**
+ * Start full-screen native turn-by-turn navigation.
+ *
+ * @param options Navigation settings such as destination, camera mode, simulation, and map UI options.
+ * @throws Error if options are invalid or native route/token setup fails.
+ */
 export async function startNavigation(
   options: NavigationOptions,
 ): Promise<void> {
   const normalizedOptions = normalizeNavigationOptions(options);
-  return await MapboxNavigationModule.startNavigation(normalizedOptions);
+  try {
+    await MapboxNavigationModule.startNavigation(normalizedOptions);
+  } catch (error) {
+    throw normalizeNativeError(error, "START_NAVIGATION_FAILED");
+  }
 }
 
+/**
+ * Stop/dismiss native navigation if active.
+ */
 export async function stopNavigation(): Promise<void> {
-  return await MapboxNavigationModule.stopNavigation();
+  try {
+    await MapboxNavigationModule.stopNavigation();
+  } catch (error) {
+    throw normalizeNativeError(error, "STOP_NAVIGATION_FAILED");
+  }
 }
 
+/**
+ * Enable or disable voice guidance.
+ *
+ * @param muted `true` to mute voice instructions.
+ */
 export async function setMuted(muted: boolean): Promise<void> {
-  return await MapboxNavigationModule.setMuted(muted);
+  try {
+    await MapboxNavigationModule.setMuted(muted);
+  } catch (error) {
+    throw normalizeNativeError(error, "SET_MUTED_FAILED");
+  }
 }
 
+/**
+ * Set voice instruction volume in range `0..1`.
+ */
 export async function setVoiceVolume(volume: number): Promise<void> {
-  return await MapboxNavigationModule.setVoiceVolume(volume);
+  try {
+    await MapboxNavigationModule.setVoiceVolume(volume);
+  } catch (error) {
+    throw normalizeNativeError(error, "SET_VOICE_VOLUME_FAILED");
+  }
 }
 
+/**
+ * Set spoken and displayed distance units.
+ */
 export async function setDistanceUnit(unit: "metric" | "imperial"): Promise<void> {
-  return await MapboxNavigationModule.setDistanceUnit(unit);
+  try {
+    await MapboxNavigationModule.setDistanceUnit(unit);
+  } catch (error) {
+    throw normalizeNativeError(error, "SET_DISTANCE_UNIT_FAILED");
+  }
 }
 
+/**
+ * Set instruction language (BCP-47-like code, for example `en`, `fr`).
+ */
 export async function setLanguage(language: string): Promise<void> {
-  return await MapboxNavigationModule.setLanguage(language);
+  try {
+    await MapboxNavigationModule.setLanguage(language);
+  } catch (error) {
+    throw normalizeNativeError(error, "SET_LANGUAGE_FAILED");
+  }
 }
 
+/**
+ * Check whether full-screen native navigation is currently active.
+ */
 export async function isNavigating(): Promise<boolean> {
-  return await MapboxNavigationModule.isNavigating();
+  try {
+    return await MapboxNavigationModule.isNavigating();
+  } catch (error) {
+    throw normalizeNativeError(error, "IS_NAVIGATING_FAILED");
+  }
 }
 
+/**
+ * Read current native navigation runtime settings.
+ */
 export async function getNavigationSettings(): Promise<NavigationSettings> {
-  return await MapboxNavigationModule.getNavigationSettings();
+  try {
+    return await MapboxNavigationModule.getNavigationSettings();
+  } catch (error) {
+    throw normalizeNativeError(error, "GET_NAVIGATION_SETTINGS_FAILED");
+  }
 }
 
-// Event listeners
+/**
+ * Subscribe to location updates from native navigation.
+ */
 export function addLocationChangeListener(
   listener: (location: LocationUpdate) => void,
 ): Subscription {
   return emitter.addListener("onLocationChange", listener);
 }
 
+/**
+ * Subscribe to route progress updates.
+ */
 export function addRouteProgressChangeListener(
   listener: (progress: RouteProgress) => void,
 ): Subscription {
   return emitter.addListener("onRouteProgressChange", listener);
 }
 
+/**
+ * Subscribe to arrival events.
+ */
 export function addArriveListener(listener: (point: ArrivalEvent) => void): Subscription {
   return emitter.addListener("onArrive", listener);
 }
 
+/**
+ * Subscribe to cancellation events.
+ */
 export function addCancelNavigationListener(listener: () => void): Subscription {
   return emitter.addListener("onCancelNavigation", listener);
 }
 
+/**
+ * Subscribe to native errors (token issues, route fetch failures, permission failures, etc.).
+ */
 export function addErrorListener(listener: (error: NavigationError) => void): Subscription {
   return emitter.addListener("onError", listener);
 }
 
+/**
+ * Subscribe to banner instruction updates.
+ */
 export function addBannerInstructionListener(
   listener: (instruction: BannerInstruction) => void,
 ): Subscription {
   return emitter.addListener("onBannerInstruction", listener);
 }
 
-// React component wrapper
+/**
+ * Embedded native navigation component.
+ *
+ * Use this when you need navigation inside your own screen layout instead of full-screen modal navigation.
+ */
 export function MapboxNavigationView(
   props: MapboxNavigationViewProps & ViewProps,
 ) {
@@ -181,10 +271,8 @@ export function MapboxNavigationView(
   return <NativeView {...props} />;
 }
 
-// Export types
 export * from "./MapboxNavigation.types";
 
-// Default export
 export default {
   startNavigation,
   stopNavigation,