react-native-pointr 9.8.0 → 10.0.0

package/src/actions/index.ts

@@ -0,0 +1,171 @@
+/**
+ * Action pattern implementation for Pointr SDK
+ * Actions are immutable objects that represent operations to perform on the map
+ * @module commands
+ */
+
+import { PTRActionType } from '../constants';
+
+/**
+ * Base class for all Pointr SDK actions
+ */
+export abstract class PTRAction {
+  readonly type: PTRActionType;
+
+  constructor(type: PTRActionType) {
+    this.type = type;
+  }
+}
+
+/**
+ * Action to focus the map on a site, building, or level.
+ * All parameters are optional — provide only those needed for the desired zoom level.
+ */
+export class PTRFocusMapAction extends PTRAction {
+  readonly site: string;
+  readonly building?: string;
+  readonly level?: number;
+
+  constructor(site: string, building?: string, level?: number) {
+    super(PTRActionType.FOCUS_MAP);
+    this.site = site;
+    this.building = building;
+    this.level = level;
+  }
+}
+
+/**
+ * Action to highlight a Point of Interest on the map
+ */
+export class PTRHighlightPoiAction extends PTRAction {
+  readonly site: string;
+  readonly poi: string;
+
+  constructor(site: string, poi: string) {
+    super(PTRActionType.HIGHLIGHT_POI);
+    this.site = site;
+    this.poi = poi;
+  }
+}
+
+/**
+ * Action to display a static route between two POIs (no live location required).
+ * Both source and destination POIs must be specified.
+ */
+export class PTRDisplayRouteAction extends PTRAction {
+  readonly site: string;
+  readonly fromPoi: string;
+  readonly toPoi: string;
+
+  constructor(site: string, fromPoi: string, toPoi: string) {
+    super(PTRActionType.DISPLAY_ROUTE);
+    this.site = site;
+    this.fromPoi = fromPoi;
+    this.toPoi = toPoi;
+  }
+}
+
+/**
+ * Action to start wayfinding from the user's current position to a destination POI.
+ */
+export class PTRStartWayfindingAction extends PTRAction {
+  readonly site: string;
+  readonly poi: string;
+
+  constructor(site: string, poi: string) {
+    super(PTRActionType.START_WAYFINDING);
+    this.site = site;
+    this.poi = poi;
+  }
+}
+
+/**
+ * Action to mark the car location.
+ * When building and level are provided, marks at a specific level.
+ * Otherwise marks at the site level.
+ */
+export class PTRMarkMyCarAction extends PTRAction {
+  readonly site: string;
+  readonly building?: string;
+  readonly level?: number;
+  readonly shouldShowPopup: boolean;
+  readonly animationType: number;
+
+  constructor(
+    site: string,
+    building?: string,
+    level?: number,
+    shouldShowPopup: boolean = true,
+    animationType: number = 1
+  ) {
+    super(PTRActionType.MARK_MY_CAR);
+    this.site = site;
+    this.building = building;
+    this.level = level;
+    this.shouldShowPopup = shouldShowPopup;
+    this.animationType = animationType;
+  }
+}
+
+/**
+ * Action to show the previously saved car location at a site
+ */
+export class PTRShowMyCarAction extends PTRAction {
+  readonly site: string;
+  readonly shouldShowPopup: boolean;
+  readonly animationType: number;
+
+  constructor(
+    site: string,
+    shouldShowPopup: boolean = true,
+    animationType: number = 1
+  ) {
+    super(PTRActionType.SHOW_MY_CAR);
+    this.site = site;
+    this.shouldShowPopup = shouldShowPopup;
+    this.animationType = animationType;
+  }
+}
+
+/**
+ * Action to focus the map on a specific geographic coordinate.
+ *
+ * @example
+ * ```ts
+ * new PTRFocusCoordinateAction(SITE_ID, 47.4979, 19.0402, 2)
+ * ```
+ */
+export class PTRFocusCoordinateAction extends PTRAction {
+  readonly site: string;
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly levelIndex?: number;
+
+  constructor(site: string, latitude: number, longitude: number, levelIndex?: number) {
+    super(PTRActionType.FOCUS_COORDINATE);
+    this.site = site;
+    this.latitude = latitude;
+    this.longitude = longitude;
+    this.levelIndex = levelIndex;
+  }
+}
+
+/**
+ * Action to filter map POIs by one or more category identifiers.
+ * Pass an empty array to clear the active filter.
+ *
+ * @example
+ * ```ts
+ * new PTRHighlightCategoryAction(SITE_ID, ['cafes', 'restaurants'])
+ * ```
+ */
+export class PTRHighlightCategoryAction extends PTRAction {
+  readonly site: string;
+  readonly categoryIds: string[];
+
+  constructor(site: string, categoryIds: string[]) {
+    super(PTRActionType.HIGHLIGHT_CATEGORY);
+    this.site = site;
+    this.categoryIds = categoryIds;
+  }
+}

package/src/api/MapWidgetApi.ts

@@ -5,19 +5,19 @@
  */
 
 import { findNodeHandle } from 'react-native';
-import type { PTRCommand } from '../commands';
+import type { PTRAction } from '../actions';
 import { PTRErrorMessages } from '../constants';
 import { showMapWidget } from '../PTRMapWidgetUtils';
 
 /**
- * Execute a command on the map widget
+ * Execute an action on the map widget
  * @param mapRef - Reference to the map widget component
- * @param command - Command to execute
- * @throws Error if mapRef is null or command is invalid
+ * @param action - Action to execute
+ * @throws Error if mapRef is null or action is invalid
  */
-export function executeMapCommand(
+export function executeMapAction(
   mapRef: React.RefObject<any> | any,
-  command: PTRCommand
+  action: PTRAction
 ): void {
   if (!mapRef) {
     throw new Error(PTRErrorMessages.NO_MAP_REF);
@@ -30,12 +30,12 @@ export function executeMapCommand(
     throw new Error(PTRErrorMessages.NO_MAP_REF);
   }
 
-  if (!command || !command.type) {
+  if (!action || !action.type) {
     throw new Error(PTRErrorMessages.INVALID_COMMAND);
   }
 
   try {
-    showMapWidget(reactTag, command);
+    showMapWidget(reactTag, action);
   } catch (error) {
     console.error('Error executing map command:', error);
     throw error;

package/src/api/PointrSdk.ts

@@ -5,8 +5,9 @@
  */
 
 import { NativeModules, NativeEventEmitter, Platform } from 'react-native';
-import type { PTRConfiguration, PTRMapWidgetConfiguration, PTRStateCallback } from '../types/config';
+import type { PTRConfiguration, PTRMapWidgetConfiguration } from '../types/config';
 import type { PTRPosition } from '../types/PTRPosition';
+import type { PTRGeofence } from '../types/events';
 import { PTRState, PTRLogLevel, PTRErrorMessages, PTREvents } from '../constants';
 
 const LINKING_ERROR =
@@ -15,8 +16,8 @@ const LINKING_ERROR =
   '- You rebuilt the app after installing the package\n' +
   '- You are not using Expo Go\n';
 
-const PTRNativePointrLibrary = NativeModules.PTRNativePointrLibrary
-  ? NativeModules.PTRNativePointrLibrary
+const PTRNativeLibrary = NativeModules.PTRNativeLibrary
+  ? NativeModules.PTRNativeLibrary
   : new Proxy(
       {},
       {
@@ -36,12 +37,10 @@ export class PointrSdk {
   private eventEmitter: NativeEventEmitter;
 
   private constructor() {
-    this.eventEmitter = new NativeEventEmitter(PTRNativePointrLibrary);
+    this.eventEmitter = new NativeEventEmitter(PTRNativeLibrary);
   }
 
-  /**
-   * Get the singleton instance of PointrSdk
-   */
+  /** Get the singleton instance of PointrSdk */
   public static getInstance(): PointrSdk {
     if (!PointrSdk.instance) {
       PointrSdk.instance = new PointrSdk();
@@ -58,7 +57,6 @@ export class PointrSdk {
     if (this.state !== PTRState.NOT_INITIALIZED) {
       throw new Error(PTRErrorMessages.ALREADY_INITIALIZED);
     }
-
     if (!config.clientId || !config.licenseKey || !config.baseUrl) {
       throw new Error(PTRErrorMessages.INVALID_CONFIG);
     }
@@ -67,9 +65,8 @@ export class PointrSdk {
     this.config = config;
 
     const logLevel = config.logLevel ?? PTRLogLevel.ERROR;
-
     try {
-      PTRNativePointrLibrary.initialize(
+      PTRNativeLibrary.initialize(
         config.clientId,
         config.licenseKey,
         config.baseUrl,
@@ -83,132 +80,88 @@ export class PointrSdk {
   }
 
   /**
-   * Start the Pointr SDK
-   * @param callback - Optional callback for state changes
+   * Start the Pointr SDK.
+   * Resolves when the SDK reaches the RUNNING state.
    * @throws Error if not initialized
    */
-  public start(callback?: PTRStateCallback): void {
+  public start(): Promise<void> {
     if (this.state === PTRState.NOT_INITIALIZED) {
-      throw new Error(PTRErrorMessages.NOT_INITIALIZED);
+      return Promise.reject(new Error(PTRErrorMessages.NOT_INITIALIZED));
     }
-
     this.state = PTRState.STARTING;
-
-    try {
-      PTRNativePointrLibrary.start((state: string) => {
+    return PTRNativeLibrary.start()
+      .then(() => {
         this.state = PTRState.RUNNING;
-        if (callback) {
-          callback(state);
-        }
+      })
+      .catch((error: Error) => {
+        this.state = PTRState.ERROR;
+        throw error;
       });
-    } catch (error) {
-      this.state = PTRState.ERROR;
-      throw error;
-    }
   }
 
-  /**
-   * Stop the Pointr SDK
-   */
+  /** Stop the Pointr SDK */
   public stop(): void {
     if (this.state === PTRState.RUNNING) {
-      try {
-        PTRNativePointrLibrary.stop();
-        this.state = PTRState.STOPPED;
-      } catch (error) {
-        console.error('Error stopping Pointr SDK:', error);
-        throw error;
-      }
+      PTRNativeLibrary.stop();
+      this.state = PTRState.STOPPED;
     }
   }
 
-  /**
-   * Get the current SDK state
-   */
+  /** Get the current SDK state */
   public getState(): PTRState {
     return this.state;
   }
 
-  /**
-   * Check if SDK is initialized
-   */
+  /** Check if SDK is initialized */
   public isInitialized(): boolean {
     return this.state !== PTRState.NOT_INITIALIZED;
   }
 
-  /**
-   * Check if SDK is started and running
-   */
+  /** Check if SDK is started and running */
   public isStarted(): boolean {
     return this.state === PTRState.RUNNING;
   }
 
-  /**
-   * Get the current configuration
-   */
+  /** Get the current configuration */
   public getConfig(): PTRConfiguration | null {
     return this.config;
   }
 
-  /**
-   * Get the event emitter for subscribing to Pointr events
-   */
+  /** Get the event emitter for subscribing to Pointr events */
   public getEventEmitter(): NativeEventEmitter {
     return this.eventEmitter;
   }
 
-  /**
-   * Subscribe to position updates
-   * @param callback - Function to call when position is updated
-   * @returns Subscription that can be removed
-   */
+  // ─── Event subscriptions ───────────────────────────────────────────────────
+
+  /** Subscribe to position updates */
   public onPositionUpdate(callback: (position: any) => void) {
-    return this.eventEmitter.addListener(
-      PTREvents.ON_POSITION_CALCULATED,
-      callback
-    );
+    return this.eventEmitter.addListener(PTREvents.ON_POSITION_CALCULATED, callback);
   }
 
-  /**
-   * Subscribe to building click events
-   * @param callback - Function to call when building is clicked
-   * @returns Subscription that can be removed
-   */
+  /** Subscribe to building click events */
   public onBuildingClick(callback: (event: any) => void) {
-    return this.eventEmitter.addListener(
-      PTREvents.ON_BUILDING_CLICKED,
-      callback
-    );
+    return this.eventEmitter.addListener(PTREvents.ON_BUILDING_CLICKED, callback);
   }
 
-  /**
-   * Subscribe to site click events
-   * @param callback - Function to call when site is clicked
-   * @returns Subscription that can be removed
-   */
+  /** Subscribe to site click events */
   public onSiteClick(callback: (event: any) => void) {
     return this.eventEmitter.addListener(PTREvents.ON_SITE_CLICKED, callback);
   }
 
-  /**
-   * Subscribe to geofence events
-   * @param callback - Function to call when geofence event occurs
-   * @returns Subscription that can be removed
-   */
+  /** Subscribe to geofence events */
   public onGeofenceEvent(callback: (event: any) => void) {
-    return this.eventEmitter.addListener(
-      PTREvents.ON_GEOFENCE_EVENT,
-      callback
-    );
+    return this.eventEmitter.addListener(PTREvents.ON_GEOFENCE_EVENT, callback);
   }
 
+  // ─── Map widget ────────────────────────────────────────────────────────────
+
   /**
-   * Set the map widget configuration
+   * Set the map widget configuration.
    * Must be called before the map widget renders to take effect.
-   * @param config - Map widget configuration options
    */
   public setMapWidgetConfiguration(config: PTRMapWidgetConfiguration): void {
-    PTRNativePointrLibrary.setPointrMapWidgetConfiguration(JSON.stringify(config));
+    PTRNativeLibrary.setPointrMapWidgetConfiguration(JSON.stringify(config));
   }
 
   /**
@@ -217,7 +170,7 @@ export class PointrSdk {
    */
   public getCurrentLocation(): Promise<PTRPosition | null> {
     return new Promise((resolve) => {
-      PTRNativePointrLibrary.getCurrentLocation((result: any) => {
+      PTRNativeLibrary.getCurrentLocation((result: any) => {
         if (!result || typeof result === 'string') {
           resolve(null);
         } else {
@@ -227,15 +180,21 @@ export class PointrSdk {
     });
   }
 
+  // ─── Geofences ─────────────────────────────────────────────────────────────
+
   /**
-   * Get native module reference (for advanced use cases)
+   * Get all configured geofences for a site.
+   * @param siteId - External site identifier
    */
+  public getGeofences(siteId: string): Promise<PTRGeofence[]> {
+    return PTRNativeLibrary.getGeofences(siteId);
+  }
+
+  /** Get native module reference (for advanced use cases) */
   public getNativeModule() {
-    return PTRNativePointrLibrary;
+    return PTRNativeLibrary;
   }
 }
 
-/**
- * Export singleton instance for easy access
- */
+/** Singleton instance for easy access */
 export const pointrSdk = PointrSdk.getInstance();

package/src/components/index.tsx

@@ -10,9 +10,11 @@ import {
   ViewStyle,
 } from 'react-native';
 import type { PTRWayfindingEvent } from '../types/PTRWayfindingEvent';
-import type { PTRMapCommandResponse } from '../types/events';
+import type {
+  PTRMapCommandResponse,
+} from '../types/events';
 import type { PTRConfiguration, PTRMapWidgetConfiguration } from '../types/config';
-import type { PTRCommand } from '../commands';
+import type { PTRAction } from '../actions';
 
 /**
  * Native PTRMapWidget component
@@ -27,18 +29,15 @@ export interface PTRMapWidgetProps {
   /** Component style */
   style?: ViewStyle;
   /**
-   * Declarative command that the map widget executes automatically on mount.
+   * Declarative action that the map widget executes automatically on mount.
    * When provided the SDK is started if not already running, removing the need
-   * for an imperative `executeMapCommand` call after the widget loads.
+   * for an imperative `executeMapAction` call after the widget loads.
    *
-   * Supports all PTRCommand subtypes: PTRSiteCommand, PTRBuildingCommand,
-   * PTRLevelCommand, PTRPoiCommand, PTRPathCommand, PTRStaticPathCommand,
-   * PTRStaticWayfindingCommand.
-   *
-   * @example
-   * <PTRMapWidget command={new PTRSiteCommand('my-site')} style={{ flex: 1 }} />
+   * Supports all PTRAction subtypes: PTRFocusMapAction, PTRHighlightPoiAction,
+   * PTRFocusCoordinateAction, PTRHighlightCategoryAction, PTRDisplayRouteAction,
+   * PTRStartWayfindingAction.
    */
-  command?: PTRCommand;
+  action?: PTRAction;
   /**
    * Optional SDK credentials. When provided the widget initialises the Pointr
    * SDK with these credentials rather than relying on a prior `pointrSdk.initialize()` call.
@@ -47,21 +46,23 @@ export interface PTRMapWidgetProps {
   /**
    * Map widget UI configuration applied before the widget renders.
    * Equivalent to calling `pointrSdk.setMapWidgetConfiguration(...)` imperatively.
-   *
-   * @example
-   * <PTRMapWidget
-   *   mapWidgetConfig={{ isLevelSelectorEnabled: true, isJoystickEnabled: true }}
-   * />
    */
   mapWidgetConfig?: PTRMapWidgetConfiguration;
-  /** Callback fired when the map finishes loading */
+
+  // ─── Map lifecycle events ────────────────────────────────────────────────
+
+  /** Fired when the map finishes loading */
   onMapWidgetDidEndLoading?: (
     event: NativeSyntheticEvent<PTRMapCommandResponse>
   ) => void;
-  /** Callback fired when wayfinding events occur (start/end/cancel) */
+
+  // ─── Navigation events ───────────────────────────────────────────────────
+
+  /** Fired when wayfinding starts, ends, or is cancelled */
   onWayfindingEvent?: (
     event: NativeSyntheticEvent<PTRWayfindingEvent>
   ) => void;
+
   /** Additional native props */
   [key: string]: any;
 }
@@ -79,13 +80,13 @@ interface NativePTRMapWidgetProps extends PTRMapWidgetProps {}
  *
  * @example
  * ```tsx
- * import { PTRMapWidget, PTRSiteCommand, executeMapCommand } from 'react-native-pointr';
+ * import { PTRMapWidget, PTRFocusMapAction, executeMapAction } from 'react-native-pointr';
  *
  * function MyMap() {
  *   const mapRef = useRef(null);
  *
  *   const showSite = () => {
- *     executeMapCommand(mapRef, new PTRSiteCommand('my-site'));
+ *     executeMapAction(mapRef, new PTRFocusMapAction('my-site'));
  *   };
  *
  *   return (
@@ -100,20 +101,20 @@ interface NativePTRMapWidgetProps extends PTRMapWidgetProps {}
  * ```
  */
 /**
- * Serialize a PTRCommand to the JSON string expected by the native command prop.
+ * Serialize a PTRAction to the JSON string expected by the native action prop.
  */
-function serializeCommand(command: PTRCommand): string {
-  const base = { type: command.type, ...(command as any) };
+function serializeCommand(action: PTRAction): string {
+  const base = { type: action.type, ...(action as any) };
   // Remove the 'type' key duplication from spread then re-add cleanly
   return JSON.stringify(base);
 }
 
 export const PTRMapWidget = forwardRef<any, PTRMapWidgetProps>(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ({ command, sdkConfig, mapWidgetConfig, ...rest }: PTRMapWidgetProps, ref: any) => {
+  ({ action, sdkConfig, mapWidgetConfig, ...rest }: PTRMapWidgetProps, ref: any) => {
     const nativeProps: Record<string, any> = { ...rest };
-    if (command) {
-      nativeProps.command = serializeCommand(command);
+    if (action) {
+      nativeProps.action = serializeCommand(action);
     }
     if (sdkConfig) {
       nativeProps.sdkConfig = JSON.stringify(sdkConfig);

package/src/constants/index.ts

@@ -74,20 +74,39 @@ export const PTREvents = {
 } as const;
 
 /**
- * Command types supported by the Pointr SDK
+ * Action types supported by the Pointr SDK
  */
-export enum PTRCommandType {
-  SITE = 'site',
-  BUILDING = 'building',
-  LEVEL = 'level',
-  POI = 'poi',
-  PATH = 'path',
-  STATIC_PATH = 'staticPath',
-  STATIC_WAYFINDING = 'staticWayfinding',
-  MARK_MY_CAR_LEVEL = 'markMyCarForLevel',
-  MARK_MY_CAR_SITE = 'markMyCarForSite',
-  SHOW_MY_CAR_SITE = 'showMyCarForSite',
-  START_AND_FOCUS = 'startAndFocus',
+export enum PTRActionType {
+  FOCUS_MAP = 'focusMap',
+  HIGHLIGHT_POI = 'highlightPoi',
+  DISPLAY_ROUTE = 'displayRoute',
+  START_WAYFINDING = 'startWayfinding',
+  MARK_MY_CAR = 'markMyCar',
+  SHOW_MY_CAR = 'showMyCar',
+  FOCUS_COORDINATE = 'focusCoordinate',
+  HIGHLIGHT_CATEGORY = 'highlightCategory',
+}
+
+/**
+ * Wayfinding mode controlling accessible vs standard routing
+ */
+export enum PTRWayfindingMode {
+  /** Standard routing */
+  NORMAL = 'normal',
+  /** Accessible routing (avoids stairs, prefers ramps/lifts) */
+  ACCESSIBLE = 'accessible',
+}
+
+/**
+ * Wayfinding event type — lifecycle of a navigation session
+ */
+export enum PTRWayfindingEventType {
+  /** Wayfinding was cancelled by the user */
+  CANCELLED = -1,
+  /** Wayfinding session started */
+  STARTED = 0,
+  /** Wayfinding session ended (destination reached) */
+  ENDED = 1,
 }
 
 /**

package/src/hooks/index.ts

@@ -6,3 +6,4 @@ export {
   usePointrBuildingClick,
   usePointrSiteClick,
 } from './usePointrEvents';
+export { usePointrGeofences } from './usePointrGeofences';

package/src/hooks/usePointrGeofences.ts

@@ -0,0 +1,37 @@
+import { useEffect, useState, useCallback } from 'react';
+import { pointrSdk } from '../api/PointrSdk';
+import type { PTRGeofence } from '../types/events';
+
+/**
+ * Hook that loads configured geofences for a site.
+ *
+ * @param siteId - External site identifier
+ * @returns `{ geofences, loading, error, refresh }`
+ *
+ * @example
+ * ```tsx
+ * const { geofences, loading } = usePointrGeofences(SITE_ID);
+ * ```
+ */
+export function usePointrGeofences(siteId: string | undefined) {
+  const [geofences, setGeofences] = useState<PTRGeofence[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refresh = useCallback(() => {
+    if (!siteId) return;
+    setLoading(true);
+    setError(null);
+    pointrSdk
+      .getGeofences(siteId)
+      .then(setGeofences)
+      .catch((err: Error) => setError(err))
+      .finally(() => setLoading(false));
+  }, [siteId]);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  return { geofences, loading, error, refresh };
+}