@doorstepai/dropoff-sdk 2.0.7 → 2.0.9

package/src/DoorstepAI.tsx

@@ -1,6 +1,14 @@
-import { NativeModules, Platform } from 'react-native';
+import { NativeModules, NativeEventEmitter, Platform } from 'react-native';
+import type { EmitterSubscription } from 'react-native';
 const { DoorstepAI } = NativeModules;
 
+// Bridges the native geofence-session event stream (iOS RCTEventEmitter /
+// Android DeviceEventManagerModule) to JS. See `addGeofenceSessionListener`.
+const GEOFENCE_SESSION_EVENT = 'DoorstepGeofenceSessionEvent';
+const doorstepEventEmitter = DoorstepAI
+  ? new NativeEventEmitter(DoorstepAI)
+  : undefined;
+
 type AddressType = {
   streetNumber: string;
   route: string;
@@ -15,6 +23,45 @@ type LatLngObject = {
   lng: number;
 };
 
+/**
+ * A single stop the SDK should geofence in `startRouteGeofencing`. On geofence
+ * ENTER the SDK auto-starts a delivery session for `deliveryId`; on EXIT it stops
+ * it (only if `markDropoff` was called for that id — otherwise the per-session
+ * timeout backstop applies).
+ */
+type DeliveryStop = {
+  deliveryId: string;
+  address: string;
+  latitude: number;
+  longitude: number;
+  /** Fence radius in meters. Falls back to `RouteGeofenceOptions.defaultRadiusMeters` (250 m). */
+  radiusMeters?: number;
+  customerId?: string;
+  driverId?: string;
+};
+
+/** Route-wide options for `startRouteGeofencing`. */
+type RouteGeofenceOptions = {
+  /** Radius (m) for stops that don't set their own `radiusMeters`. Default 250. */
+  defaultRadiusMeters?: number;
+  /** Per-session safety timeout (s) forwarded to the auto-started delivery. */
+  timeoutSeconds?: number;
+  /** Auto-stop countdown (s) applied when `stopDelivery` is called for a stop. */
+  autoStopAfterDropoffSeconds?: number;
+  /** Android only. Host owns the foreground service; SDK won't promote its own. Ignored on iOS. */
+  manualForeground?: boolean;
+};
+
+type GeofenceSessionEventType = 'STARTED' | 'STOPPED';
+
+/** Emitted whenever route geofencing auto-starts or auto-stops a session. */
+type GeofenceSessionEvent = {
+  deliveryId: string;
+  type: GeofenceSessionEventType;
+  /** Short trigger tag, e.g. "geofence", "distance", "route_cleared". */
+  reason: string;
+};
+
 /**
  * Per-delivery options shared across both platforms. Fields not supported on a
  * given platform are silently ignored.
@@ -39,6 +86,16 @@ type StartDeliveryOptions = {
    * Ignored on iOS.
    */
   manualForeground?: boolean;
+  /**
+   * Optional customer identifier associated with this delivery. Forwarded to
+   * the native SDK on both platforms.
+   */
+  customerId?: string;
+  /**
+   * Optional driver identifier associated with this delivery. Forwarded to the
+   * native SDK on both platforms.
+   */
+  driverId?: string;
 };
 
 /**
@@ -128,6 +185,8 @@ class DoorstepAIModule {
       const timeout =
         timeoutSeconds ?? options?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
       const autoStop = options?.autoStopAfterDropoffSeconds ?? null;
+      const customerId = options?.customerId ?? null;
+      const driverId = options?.driverId ?? null;
       const result =
         Platform.OS === 'android'
           ? await DoorstepAI.startDeliveryByPlaceID(
@@ -135,13 +194,17 @@ class DoorstepAIModule {
               deliveryId,
               timeout,
               autoStop,
-              options?.manualForeground ?? false
+              options?.manualForeground ?? false,
+              customerId,
+              driverId
             )
           : await DoorstepAI.startDeliveryByPlaceID(
               placeID,
               deliveryId,
               timeout,
-              autoStop
+              autoStop,
+              customerId,
+              driverId
             );
       console.log(
         'DOORSTEPAI - Delivery started successfully by Place ID:',
@@ -168,20 +231,27 @@ class DoorstepAIModule {
     try {
       const timeout =
         timeoutSeconds ?? options?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
-      // Android's deprecated startDeliveryByPlusCode does not accept the new
-      // options, so we forward only the supported parameters there.
+      const customerId = options?.customerId ?? null;
+      const driverId = options?.driverId ?? null;
+      // Android's deprecated startDeliveryByPlusCode does not accept
+      // autoStopAfterDropoffSeconds, so we forward only the supported
+      // parameters there.
       const result =
         Platform.OS === 'ios'
           ? await DoorstepAI.startDeliveryByPlusCode(
               plusCode,
               deliveryId,
               timeout,
-              options?.autoStopAfterDropoffSeconds ?? null
+              options?.autoStopAfterDropoffSeconds ?? null,
+              customerId,
+              driverId
             )
           : await DoorstepAI.startDeliveryByPlusCode(
               plusCode,
               deliveryId,
-              timeout
+              timeout,
+              customerId,
+              driverId
             );
       console.log(
         'DOORSTEPAI - Delivery started successfully by Plus Code:',
@@ -209,6 +279,8 @@ class DoorstepAIModule {
       const timeout =
         timeoutSeconds ?? options?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
       const autoStop = options?.autoStopAfterDropoffSeconds ?? null;
+      const customerId = options?.customerId ?? null;
+      const driverId = options?.driverId ?? null;
       const result =
         Platform.OS === 'android'
           ? await DoorstepAI.startDeliveryByAddress(
@@ -217,14 +289,18 @@ class DoorstepAIModule {
               coordinates ?? null,
               timeout,
               autoStop,
-              options?.manualForeground ?? false
+              options?.manualForeground ?? false,
+              customerId,
+              driverId
             )
           : await DoorstepAI.startDeliveryByAddress(
               address,
               deliveryId,
               coordinates ?? null,
               timeout,
-              autoStop
+              autoStop,
+              customerId,
+              driverId
             );
       console.log(
         'DOORSTEPAI - Delivery started successfully by Address:',
@@ -249,6 +325,8 @@ class DoorstepAIModule {
       const timeout =
         timeoutSeconds ?? options?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
       const autoStop = options?.autoStopAfterDropoffSeconds ?? null;
+      const customerId = options?.customerId ?? null;
+      const driverId = options?.driverId ?? null;
       const result =
         Platform.OS === 'android'
           ? await DoorstepAI.startDeliveryByAddressString(
@@ -257,14 +335,18 @@ class DoorstepAIModule {
               coordinates ?? null,
               timeout,
               autoStop,
-              options?.manualForeground ?? false
+              options?.manualForeground ?? false,
+              customerId,
+              driverId
             )
           : await DoorstepAI.startDeliveryByAddressString(
               address,
               deliveryId,
               coordinates ?? null,
               timeout,
-              autoStop
+              autoStop,
+              customerId,
+              driverId
             );
       console.log(
         'DOORSTEPAI - Delivery started successfully by Address String:',
@@ -293,8 +375,11 @@ class DoorstepAIModule {
     try {
       const timeout =
         timeoutSeconds ?? options?.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
-      // Android's deprecated startDeliveryByLatLng does not accept the new
-      // options, so we forward only the supported parameters there.
+      const customerId = options?.customerId ?? null;
+      const driverId = options?.driverId ?? null;
+      // Android's deprecated startDeliveryByLatLng does not accept
+      // autoStopAfterDropoffSeconds, so we forward only the supported
+      // parameters there.
       const result =
         Platform.OS === 'ios'
           ? await DoorstepAI.startDeliveryByLatLng(
@@ -303,14 +388,18 @@ class DoorstepAIModule {
               subUnit,
               deliveryId,
               timeout,
-              options?.autoStopAfterDropoffSeconds ?? null
+              options?.autoStopAfterDropoffSeconds ?? null,
+              customerId,
+              driverId
             )
           : await DoorstepAI.startDeliveryByLatLng(
               latitude,
               longitude,
               subUnit,
               deliveryId,
-              timeout
+              timeout,
+              customerId,
+              driverId
             );
       console.log(
         'DOORSTEPAI - Delivery started successfully by LatLng:',
@@ -355,9 +444,21 @@ class DoorstepAIModule {
     }
   }
 
-  static async newEvent(eventName: string, deliveryId: string) {
+  /**
+   * Record a custom event on a delivery. `timestamp` is optional epoch SECONDS —
+   * when provided the event is recorded at that time instead of "now".
+   */
+  static async newEvent(
+    eventName: string,
+    deliveryId: string,
+    timestamp?: number
+  ) {
     try {
-      const result = await DoorstepAI.newEvent(eventName, deliveryId);
+      const result = await DoorstepAI.newEvent(
+        eventName,
+        deliveryId,
+        timestamp ?? null
+      );
       console.log('DOORSTEPAI - Event sent successfully:', result);
       return result;
     } catch (error: any) {
@@ -371,6 +472,77 @@ class DoorstepAIModule {
     }
   }
 
+  // ---- Route geofencing (in-SDK) ----
+
+  /**
+   * Begin in-SDK route geofencing. The SDK fences each stop and auto-starts a
+   * delivery session on geofence ENTER / stops it on EXIT (EXIT is gated on
+   * `markDropoff`). Requires location permission; background operation needs
+   * "Allow all the time" (Android) / Always authorization (iOS). Subscribe to
+   * start/stop events via `addGeofenceSessionListener`.
+   */
+  static async startRouteGeofencing(
+    stops: DeliveryStop[],
+    options?: RouteGeofenceOptions
+  ): Promise<void> {
+    try {
+      await DoorstepAI.startRouteGeofencing(stops, options ?? null);
+      console.log(
+        'DOORSTEPAI - Route geofencing started for',
+        stops.length,
+        'stop(s)'
+      );
+    } catch (error: any) {
+      console.error('DOORSTEPAI - Failed to start route geofencing:', error);
+      throw error;
+    }
+  }
+
+  /** Stop route geofencing and clear all monitored stops. */
+  static async stopRouteGeofencing(): Promise<void> {
+    try {
+      await DoorstepAI.stopRouteGeofencing();
+    } catch (error: any) {
+      console.error('DOORSTEPAI - Failed to stop route geofencing:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Re-arm route geofencing after a process relaunch if a route was active.
+   * Safe no-op when no route is persisted.
+   */
+  static async resumeRouteGeofencingIfNeeded(): Promise<void> {
+    try {
+      await DoorstepAI.resumeRouteGeofencingIfNeeded();
+    } catch (error: any) {
+      console.error('DOORSTEPAI - Failed to resume route geofencing:', error);
+      throw error;
+    }
+  }
+
+  /** The stops currently registered for route geofencing (empty if none). */
+  static async getMonitoredStops(): Promise<DeliveryStop[]> {
+    try {
+      const stops = await DoorstepAI.getMonitoredStops();
+      return (stops as DeliveryStop[]) ?? [];
+    } catch (error: any) {
+      console.error('DOORSTEPAI - Failed to get monitored stops:', error);
+      return [];
+    }
+  }
+
+  /**
+   * Subscribe to geofence-session events (auto start/stop of a delivery on
+   * geofence transitions). Returns a subscription — call `.remove()` to
+   * unsubscribe. Returns `undefined` if the native module is unavailable.
+   */
+  static addGeofenceSessionListener(
+    listener: (event: GeofenceSessionEvent) => void
+  ): EmitterSubscription | undefined {
+    return doorstepEventEmitter?.addListener(GEOFENCE_SESSION_EVENT, listener);
+  }
+
   // ---- Dev-mode helpers (Android exposes a richer surface than iOS) ----
 
   static async enableDevMode(apiKey: string): Promise<boolean> {
@@ -395,4 +567,13 @@ class DoorstepAIModule {
 }
 
 export { DoorstepAIModule as DoorstepAI };
-export type { AddressType, LatLngObject, StartDeliveryOptions, SDKLogLevel };
+export type {
+  AddressType,
+  LatLngObject,
+  StartDeliveryOptions,
+  SDKLogLevel,
+  DeliveryStop,
+  RouteGeofenceOptions,
+  GeofenceSessionEvent,
+  GeofenceSessionEventType,
+};

package/src/index.tsx

@@ -5,6 +5,10 @@ export type {
   LatLngObject,
   StartDeliveryOptions,
   SDKLogLevel,
+  DeliveryStop,
+  RouteGeofenceOptions,
+  GeofenceSessionEvent,
+  GeofenceSessionEventType,
 } from './DoorstepAI';
 
 export { DoorstepAI, RootDoorstepAI };