react-native-pointr 9.6.0 → 9.7.0

package/src/commands/index.ts

@@ -0,0 +1,275 @@
+/**
+ * Command pattern implementation for Pointr SDK
+ * Commands are immutable objects that represent actions to perform on the map
+ * @module commands
+ */
+
+import { PTRCommandType } from '../constants';
+
+/**
+ * Base class for all Pointr SDK commands
+ */
+export abstract class PTRCommand {
+  readonly type: PTRCommandType;
+
+  constructor(type: PTRCommandType) {
+    this.type = type;
+  }
+}
+
+/**
+ * Command to show a site on the map
+ */
+export class PTRSiteCommand extends PTRCommand {
+  readonly site: string;
+
+  constructor(site: string) {
+    super(PTRCommandType.SITE);
+    this.site = site;
+  }
+}
+
+/**
+ * Command to show a building on the map
+ */
+export class PTRBuildingCommand extends PTRCommand {
+  readonly site: string;
+  readonly building: string;
+
+  constructor(site: string, building: string) {
+    super(PTRCommandType.BUILDING);
+    this.site = site;
+    this.building = building;
+  }
+}
+
+/**
+ * Command to show a specific level of a building
+ */
+export class PTRLevelCommand extends PTRCommand {
+  readonly site: string;
+  readonly building: string;
+  readonly level: number;
+
+  constructor(site: string, building: string, level: number) {
+    super(PTRCommandType.LEVEL);
+    this.site = site;
+    this.building = building;
+    this.level = level;
+  }
+}
+
+/**
+ * Command to show a Point of Interest on the map
+ */
+export class PTRPoiCommand extends PTRCommand {
+  readonly site: string;
+  readonly poi: string;
+
+  constructor(site: string, poi: string) {
+    super(PTRCommandType.POI);
+    this.site = site;
+    this.poi = poi;
+  }
+}
+
+/**
+ * Command to show a navigation path to a POI from current location
+ */
+export class PTRPathCommand extends PTRCommand {
+  readonly site: string;
+  readonly poi: string;
+
+  constructor(site: string, poi: string) {
+    super(PTRCommandType.PATH);
+    this.site = site;
+    this.poi = poi;
+  }
+}
+
+/**
+ * Command to show a static path between two POIs
+ */
+export class PTRStaticPathCommand extends PTRCommand {
+  readonly site: string;
+  readonly fromPoi: string;
+  readonly toPoi: string;
+
+  constructor(site: string, fromPoi: string, toPoi: string) {
+    super(PTRCommandType.STATIC_PATH);
+    this.site = site;
+    this.fromPoi = fromPoi;
+    this.toPoi = toPoi;
+  }
+}
+
+/**
+ * Command to show static wayfinding between two POIs
+ */
+export class PTRStaticWayfindingCommand extends PTRCommand {
+  readonly site: string;
+  readonly sourcePoi: string;
+  readonly destinationPoi: string;
+
+  constructor(site: string, sourcePoi: string, destinationPoi: string) {
+    super(PTRCommandType.STATIC_WAYFINDING);
+    this.site = site;
+    this.sourcePoi = sourcePoi;
+    this.destinationPoi = destinationPoi;
+  }
+}
+
+/**
+ * Command to mark car location at a specific level
+ */
+export class PTRMarkMyCarLevelCommand extends PTRCommand {
+  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(PTRCommandType.MARK_MY_CAR_LEVEL);
+    this.site = site;
+    this.building = building;
+    this.level = level;
+    this.shouldShowPopup = shouldShowPopup;
+    this.animationType = animationType;
+  }
+}
+
+/**
+ * Command to mark car location at a site
+ */
+export class PTRMarkMyCarSiteCommand extends PTRCommand {
+  readonly site: string;
+  readonly shouldShowPopup: boolean;
+  readonly animationType: number;
+
+  constructor(
+    site: string,
+    shouldShowPopup: boolean = true,
+    animationType: number = 1
+  ) {
+    super(PTRCommandType.MARK_MY_CAR_SITE);
+    this.site = site;
+    this.shouldShowPopup = shouldShowPopup;
+    this.animationType = animationType;
+  }
+}
+
+/**
+ * Command to show marked car location at a site
+ */
+export class PTRShowMyCarSiteCommand extends PTRCommand {
+  readonly site: string;
+  readonly shouldShowPopup: boolean;
+  readonly animationType: number;
+
+  constructor(
+    site: string,
+    shouldShowPopup: boolean = true,
+    animationType: number = 1
+  ) {
+    super(PTRCommandType.SHOW_MY_CAR_SITE);
+    this.site = site;
+    this.shouldShowPopup = shouldShowPopup;
+    this.animationType = animationType;
+  }
+}
+
+/**
+ * Command to start the SDK and focus on a specific location
+ * This is a special command that combines initialization with navigation
+ */
+export class PTRStartAndFocusCommand {
+  readonly clientId: string;
+  readonly licenseKey: string;
+  readonly baseUrl: string;
+  readonly logLevel: number;
+  readonly command:
+    | PTRSiteCommand
+    | PTRBuildingCommand
+    | PTRLevelCommand
+    | PTRPoiCommand;
+
+  constructor(
+    clientId: string,
+    licenseKey: string,
+    baseUrl: string,
+    logLevel: number = 4,
+    command:
+      | PTRSiteCommand
+      | PTRBuildingCommand
+      | PTRLevelCommand
+      | PTRPoiCommand
+  ) {
+    this.clientId = clientId;
+    this.licenseKey = licenseKey;
+    this.baseUrl = baseUrl;
+    this.logLevel = logLevel;
+    this.command = command;
+  }
+}
+
+/**
+ * Type guard to check if a command is a PTRSiteCommand
+ */
+export function isPTRSiteCommand(
+  command: PTRCommand
+): command is PTRSiteCommand {
+  return command.type === PTRCommandType.SITE;
+}
+
+/**
+ * Type guard to check if a command is a PTRBuildingCommand
+ */
+export function isPTRBuildingCommand(
+  command: PTRCommand
+): command is PTRBuildingCommand {
+  return command.type === PTRCommandType.BUILDING;
+}
+
+/**
+ * Type guard to check if a command is a PTRLevelCommand
+ */
+export function isPTRLevelCommand(
+  command: PTRCommand
+): command is PTRLevelCommand {
+  return command.type === PTRCommandType.LEVEL;
+}
+
+/**
+ * Type guard to check if a command is a PTRPoiCommand
+ */
+export function isPTRPoiCommand(
+  command: PTRCommand
+): command is PTRPoiCommand {
+  return command.type === PTRCommandType.POI;
+}
+
+/**
+ * Type guard to check if a command is a PTRPathCommand
+ */
+export function isPTRPathCommand(
+  command: PTRCommand
+): command is PTRPathCommand {
+  return command.type === PTRCommandType.PATH;
+}
+
+/**
+ * Type guard to check if a command is a PTRStaticPathCommand
+ */
+export function isPTRStaticPathCommand(
+  command: PTRCommand
+): command is PTRStaticPathCommand {
+  return command.type === PTRCommandType.STATIC_PATH;
+}
+

package/src/components/index.tsx

@@ -0,0 +1,130 @@
+/**
+ * React Native component wrapper for PTRMapWidget
+ * @module components
+ */
+
+import React, { forwardRef } from 'react';
+import {
+  requireNativeComponent,
+  NativeSyntheticEvent,
+  ViewStyle,
+} from 'react-native';
+import type { PTRWayfindingEvent } from '../types/PTRWayfindingEvent';
+import type { PTRMapCommandResponse } from '../types/events';
+import type { PTRConfiguration, PTRMapWidgetConfiguration } from '../types/config';
+import type { PTRCommand } from '../commands';
+
+/**
+ * Native PTRMapWidget component
+ */
+const NativePTRMapWidget =
+  requireNativeComponent<NativePTRMapWidgetProps>('PTRMapWidget');
+
+/**
+ * Props for the PTRMapWidget component
+ */
+export interface PTRMapWidgetProps {
+  /** Component style */
+  style?: ViewStyle;
+  /**
+   * Declarative command 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.
+   *
+   * Supports all PTRCommand subtypes: PTRSiteCommand, PTRBuildingCommand,
+   * PTRLevelCommand, PTRPoiCommand, PTRPathCommand, PTRStaticPathCommand,
+   * PTRStaticWayfindingCommand.
+   *
+   * @example
+   * <PTRMapWidget command={new PTRSiteCommand('my-site')} style={{ flex: 1 }} />
+   */
+  command?: PTRCommand;
+  /**
+   * Optional SDK credentials. When provided the widget initialises the Pointr
+   * SDK with these credentials rather than relying on a prior `pointrSdk.initialize()` call.
+   */
+  sdkConfig?: PTRConfiguration;
+  /**
+   * 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 */
+  onMapWidgetDidEndLoading?: (
+    event: NativeSyntheticEvent<PTRMapCommandResponse>
+  ) => void;
+  /** Callback fired when wayfinding events occur (start/end/cancel) */
+  onWayfindingEvent?: (
+    event: NativeSyntheticEvent<PTRWayfindingEvent>
+  ) => void;
+  /** Additional native props */
+  [key: string]: any;
+}
+
+/**
+ * Internal props for the native component
+ */
+interface NativePTRMapWidgetProps extends PTRMapWidgetProps {}
+
+/**
+ * PTRMapWidget - Display the Pointr indoor map
+ *
+ * This component wraps the native map widget and provides a React-friendly
+ * interface with proper TypeScript typing.
+ *
+ * @example
+ * ```tsx
+ * import { PTRMapWidget, PTRSiteCommand, executeMapCommand } from 'react-native-pointr';
+ *
+ * function MyMap() {
+ *   const mapRef = useRef(null);
+ *
+ *   const showSite = () => {
+ *     executeMapCommand(mapRef, new PTRSiteCommand('my-site'));
+ *   };
+ *
+ *   return (
+ *     <PTRMapWidget
+ *       ref={mapRef}
+ *       style={{ flex: 1 }}
+ *       onMapWidgetDidEndLoading={(e) => console.log('Map loaded', e.nativeEvent)}
+ *       onWayfindingEvent={(e) => console.log('Navigation event', e.nativeEvent)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+/**
+ * Serialize a PTRCommand to the JSON string expected by the native command prop.
+ */
+function serializeCommand(command: PTRCommand): string {
+  const base = { type: command.type, ...(command 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) => {
+    const nativeProps: Record<string, any> = { ...rest };
+    if (command) {
+      nativeProps.command = serializeCommand(command);
+    }
+    if (sdkConfig) {
+      nativeProps.sdkConfig = JSON.stringify(sdkConfig);
+    }
+    if (mapWidgetConfig) {
+      nativeProps.mapWidgetConfig = JSON.stringify(mapWidgetConfig);
+    }
+    return <NativePTRMapWidget ref={ref} {...nativeProps} />;
+  }
+);
+
+PTRMapWidget.displayName = 'PTRMapWidget';
+
+export default PTRMapWidget;

package/src/constants/index.ts

@@ -0,0 +1,104 @@
+/**
+ * Constants and enums for the Pointr SDK
+ * @module constants
+ */
+
+/**
+ * Log levels for the Pointr SDK
+ */
+export enum PTRLogLevel {
+  /** Verbose logging - all messages */
+  VERBOSE = 0,
+  /** Debug logging - debug and higher */
+  DEBUG = 1,
+  /** Info logging - informational messages and higher */
+  INFO = 2,
+  /** Warning logging - warnings and errors */
+  WARNING = 3,
+  /** Error logging - errors only */
+  ERROR = 4,
+  /** No logging */
+  NONE = 5,
+}
+
+/**
+ * SDK state values
+ */
+export enum PTRState {
+  /** SDK is not initialized */
+  NOT_INITIALIZED = 'NOT_INITIALIZED',
+  /** SDK is initializing */
+  INITIALIZING = 'INITIALIZING',
+  /** SDK is initialized but not started */
+  INITIALIZED = 'INITIALIZED',
+  /** SDK is starting */
+  STARTING = 'STARTING',
+  /** SDK is running */
+  RUNNING = 'RUNNING',
+  /** SDK is stopped */
+  STOPPED = 'STOPPED',
+  /** SDK encountered an error */
+  ERROR = 'ERROR',
+}
+
+/**
+ * Animation types for map transitions
+ */
+export enum PTRAnimationType {
+  /** No animation */
+  NONE = 'none',
+  /** Fade animation */
+  FADE = 'fade',
+  /** Slide animation */
+  SLIDE = 'slide',
+  /** Zoom animation */
+  ZOOM = 'zoom',
+}
+
+/**
+ * Event names emitted by the Pointr SDK
+ */
+export const PTREvents = {
+  /** Fired when position is calculated */
+  ON_POSITION_CALCULATED: 'OnPositionManagerCalculatedLocation',
+  /** Fired when a building is clicked on the map */
+  ON_BUILDING_CLICKED: 'OnBuildingClicked',
+  /** Fired when a site is clicked on the map */
+  ON_SITE_CLICKED: 'OnSiteClicked',
+  /** Fired when a geofence event occurs */
+  ON_GEOFENCE_EVENT: 'OnGeofenceEvent',
+  /** Fired when wayfinding starts, ends, or is cancelled */
+  ON_WAYFINDING_EVENT: 'onWayfindingEvent',
+  /** Fired when map widget finishes loading */
+  ON_MAP_WIDGET_DID_END_LOADING: 'onMapWidgetDidEndLoading',
+} as const;
+
+/**
+ * Command 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',
+}
+
+/**
+ * Error messages
+ */
+export const PTRErrorMessages = {
+  NOT_INITIALIZED: 'Pointr SDK is not initialized. Call initialize() first.',
+  NOT_STARTED: 'Pointr SDK is not started. Call start() first.',
+  ALREADY_INITIALIZED: 'Pointr SDK is already initialized.',
+  INVALID_CONFIG: 'Invalid configuration provided.',
+  INVALID_COMMAND: 'Invalid map command provided.',
+  NO_MAP_REF: 'Map widget reference is required.',
+  NATIVE_ERROR: 'Native module error occurred.',
+} as const;

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export { usePointrSdk } from './usePointrSdk';
+export { usePointrPosition } from './usePointrPosition';
+export { usePointrPois } from './usePointrPois';
+export {
+  usePointrGeofence,
+  usePointrBuildingClick,
+  usePointrSiteClick,
+} from './usePointrEvents';

package/src/hooks/usePointrEvents.ts

@@ -0,0 +1,40 @@
+import { useEffect } from 'react';
+import { pointrSdk } from '../api/PointrSdk';
+import type {
+  PTRGeofenceEvent,
+  PTRBuildingClickEvent,
+  PTRSiteClickEvent,
+} from '../types/events';
+
+/**
+ * Hook to listen to geofence events.
+ * @param callback - Called whenever a geofence event occurs
+ */
+export function usePointrGeofence(callback: (event: PTRGeofenceEvent) => void) {
+  useEffect(() => {
+    const subscription = pointrSdk.onGeofenceEvent(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+/**
+ * Hook to listen to building click events.
+ * @param callback - Called whenever a building is tapped on the map
+ */
+export function usePointrBuildingClick(callback: (event: PTRBuildingClickEvent) => void) {
+  useEffect(() => {
+    const subscription = pointrSdk.onBuildingClick(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}
+
+/**
+ * Hook to listen to site click events.
+ * @param callback - Called whenever a site is tapped on the map
+ */
+export function usePointrSiteClick(callback: (event: PTRSiteClickEvent) => void) {
+  useEffect(() => {
+    const subscription = pointrSdk.onSiteClick(callback);
+    return () => subscription.remove();
+  }, [callback]);
+}

package/src/hooks/usePointrPois.ts

@@ -0,0 +1,41 @@
+import { useEffect, useState, useCallback } from 'react';
+import { getPois } from '../managers/PTRPoiManager';
+import type { PTRPoi } from '../types/PTRPoi';
+
+/**
+ * Hook to fetch and manage POIs for a site.
+ * @param siteId - External site identifier to fetch POIs for
+ * @returns POIs array, loading state, error, and a refetch function
+ */
+export function usePointrPois(siteId?: string) {
+  const [pois, setPois] = useState<PTRPoi[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchPois = useCallback(async (id: string) => {
+    if (!id) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const fetchedPois = await getPois(id);
+      setPois(fetchedPois);
+    } catch (err) {
+      setError(err as Error);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (siteId) {
+      fetchPois(siteId);
+    }
+  }, [siteId, fetchPois]);
+
+  return {
+    pois,
+    loading,
+    error,
+    refetch: () => siteId && fetchPois(siteId),
+  };
+}

package/src/hooks/usePointrPosition.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from 'react';
+import { pointrSdk } from '../api/PointrSdk';
+import type { PTRPositionEvent } from '../types/events';
+
+/**
+ * Hook to listen to position updates from the Pointr SDK.
+ * Subscribes as soon as the component mounts; the native layer only emits
+ * events once the SDK is running, so the subscription is harmlessly idle
+ * until then.
+ * @param enabled - Set to false to pause listening without unmounting
+ * @returns Current position or null
+ */
+export function usePointrPosition(enabled: boolean = true) {
+  const [position, setPosition] = useState<PTRPositionEvent | null>(null);
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const subscription = pointrSdk.onPositionUpdate((pos) => {
+      setPosition(pos);
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, [enabled]);
+
+  return position;
+}

package/src/hooks/usePointrSdk.ts

@@ -0,0 +1,41 @@
+import { useEffect, useState } from 'react';
+import { pointrSdk } from '../api/PointrSdk';
+import type { PTRConfiguration } from '../types/config';
+import { PTRState } from '../constants';
+
+/**
+ * Hook to initialize and manage the Pointr SDK lifecycle.
+ * @param config - Optional configuration. When provided, initializes and starts the SDK automatically.
+ * @returns SDK instance with state information
+ */
+export function usePointrSdk(config?: PTRConfiguration) {
+  const [state, setState] = useState<PTRState>(pointrSdk.getState());
+  const [isInitialized, setIsInitialized] = useState(pointrSdk.isInitialized());
+  const [isStarted, setIsStarted] = useState(pointrSdk.isStarted());
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (config && !isInitialized) {
+      try {
+        pointrSdk.initialize(config);
+        setIsInitialized(true);
+        setState(pointrSdk.getState());
+
+        pointrSdk.start(() => {
+          setState(PTRState.RUNNING);
+          setIsStarted(true);
+        });
+      } catch (err) {
+        setError(err as Error);
+      }
+    }
+  }, [config, isInitialized]);
+
+  return {
+    sdk: pointrSdk,
+    state,
+    isInitialized,
+    isStarted,
+    error,
+  };
+}