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

package/README.md

@@ -11,6 +11,17 @@ Native Mapbox turn-by-turn navigation for Expo apps on iOS and Android.
 - Navigation customization: camera mode/pitch/zoom, theme, map style, and UI visibility toggles.
 - Expo config plugin that applies required Android and iOS native setup.
 
+## Screenshots
+
+![Android](docs/screenshots/android.png)
+![iOS](docs/screenshots/ios.png)
+
+## Support Us
+
+[![Support on Ko-fi](docs/imgs/support_me_on_kofi_badge_red.png)](https://ko-fi.com/atomiqlab)
+
+If this package helps your work, support development on Ko-fi.
+
 ## Requirements
 
 - Expo SDK `>=50`
@@ -50,6 +61,16 @@ Regenerate native projects:
 npx expo prebuild --clean
 ```
 
+### 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
@@ -107,6 +128,353 @@ import { MapboxNavigationView } from "@atomiqlab/react-native-mapbox-navigation"
 />;
 ```
 
+```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"}`);
+      }
+    })();
+
+    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:
@@ -139,6 +507,17 @@ Main `NavigationOptions` fields:
 
 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
+
+Subscribe via `addErrorListener` or `onError` to surface these to developers during testing and production diagnostics.
+
 ## Platform Notes
 
 - Android: `startOrigin` is optional (current location is supported).

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

@@ -8,7 +8,10 @@ import android.os.Handler
 import android.os.Looper
 import android.util.Log
 import android.view.Gravity
+import android.view.ViewGroup
+import android.widget.Button
 import android.widget.FrameLayout
+import android.widget.LinearLayout
 import android.widget.TextView
 import androidx.appcompat.app.AppCompatDelegate
 import androidx.appcompat.app.AppCompatActivity
@@ -95,7 +98,7 @@ class MapboxNavigationActivity : AppCompatActivity() {
       result[Manifest.permission.ACCESS_COARSE_LOCATION] == true
 
     if (!granted) {
-      showErrorAndStay("Location permission is required to start navigation.", null)
+      showErrorScreen("Location permission is required to start navigation.", null)
       return@registerForActivityResult
     }
 
@@ -112,6 +115,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
+        )
+      )
+      showErrorScreen(message, null)
     }
 
     override fun onRouteFetchSuccessful(routes: List<NavigationRoute>) {
@@ -127,6 +139,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)."
+        )
+      )
     }
   }
 
@@ -166,7 +185,7 @@ class MapboxNavigationActivity : AppCompatActivity() {
         Log.w(TAG, "No valid destination extras provided, starting without preview")
       }
     } catch (throwable: Throwable) {
-      showErrorAndStay("Navigation init failed: ${throwable.message}", throwable)
+      showErrorScreen("Navigation init failed: ${throwable.message}", throwable)
       return
     }
 
@@ -256,7 +275,7 @@ class MapboxNavigationActivity : AppCompatActivity() {
       }
 
     } catch (throwable: Throwable) {
-      showErrorAndStay("Failed to create NavigationView: ${throwable.message}", throwable)
+      showErrorScreen("Failed to create NavigationView: ${throwable.message}", throwable)
     }
   }
 
@@ -301,6 +320,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,
@@ -315,23 +353,73 @@ class MapboxNavigationActivity : AppCompatActivity() {
     return fineGranted || coarseGranted
   }
 
-  private fun showErrorAndStay(message: String, throwable: Throwable?) {
+  private fun showErrorScreen(message: String, throwable: Throwable?) {
     if (throwable != null) {
       Log.e(TAG, message, throwable)
     } else {
       Log.e(TAG, message)
     }
 
-    val errorView = TextView(this).apply {
+    MapboxNavigationEventBridge.emit(
+      "onError",
+      mapOf(
+        "code" to "NATIVE_ERROR",
+        "message" to message
+      )
+    )
+
+    val titleView = TextView(this).apply {
+      text = "Navigation Error"
+      textSize = 22f
+      setTextColor(0xFFFFFFFF.toInt())
+      gravity = Gravity.CENTER
+    }
+
+    val messageView = TextView(this).apply {
       text = message
+      textSize = 15f
+      setTextColor(0xFFD6E4FF.toInt())
       gravity = Gravity.CENTER
-      textSize = 16f
-      setPadding(32, 32, 32, 32)
+      setPadding(0, 24, 0, 32)
     }
+
+    val closeButton = Button(this).apply {
+      text = "Back"
+      setOnClickListener { finish() }
+    }
+
+    val content = LinearLayout(this).apply {
+      orientation = LinearLayout.VERTICAL
+      gravity = Gravity.CENTER
+      setBackgroundColor(0xFF0B1020.toInt())
+      setPadding(48, 48, 48, 48)
+      addView(
+        titleView,
+        LinearLayout.LayoutParams(
+          ViewGroup.LayoutParams.MATCH_PARENT,
+          ViewGroup.LayoutParams.WRAP_CONTENT
+        )
+      )
+      addView(
+        messageView,
+        LinearLayout.LayoutParams(
+          ViewGroup.LayoutParams.MATCH_PARENT,
+          ViewGroup.LayoutParams.WRAP_CONTENT
+        )
+      )
+      addView(
+        closeButton,
+        LinearLayout.LayoutParams(
+          ViewGroup.LayoutParams.MATCH_PARENT,
+          ViewGroup.LayoutParams.WRAP_CONTENT
+        )
+      )
+    }
+
     setContentView(
       FrameLayout(this).apply {
         addView(
-          errorView,
+          content,
           FrameLayout.LayoutParams(
             FrameLayout.LayoutParams.MATCH_PARENT,
             FrameLayout.LayoutParams.MATCH_PARENT

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;