react-native-pointr 9.6.0 → 9.8.0

package/ios/PTRMapWidgetContainerView.swift

@@ -6,7 +6,34 @@ import PointrKit
     @objc var onMapWidgetDidEndLoading: RCTBubblingEventBlock?
 
     @objc var onWayfindingEvent: RCTBubblingEventBlock?
-    
+
+    // Declarative command prop — JSON string encoding command type and its parameters.
+    // When set alongside an optional sdkConfig prop, the widget auto-starts and focuses
+    // without the JS caller needing to imperatively dispatch a command afterwards.
+    //
+    // Expected shape: { "type": "site"|"building"|"level"|"poi"|"path"|"staticPath"|"staticWayfinding",
+    //                   "site": "...", "building"?: "...", "level"?: 0,
+    //                   "poi"?: "...", "fromPoi"?: "...", "toPoi"?: "...",
+    //                   "sourcePoi"?: "...", "destinationPoi"?: "..." }
+    @objc var command: String? {
+        didSet { pendingCommandString = command }
+    }
+
+    // Optional SDK config prop — JSON with clientId / licenseKey / baseUrl / logLevel.
+    // When provided the widget uses these credentials instead of the globally-configured params.
+    @objc var sdkConfig: String? {
+        didSet { applySDKConfigIfNeeded() }
+    }
+
+    // Optional map widget UI configuration — JSON encoding PTRMapWidgetConfiguration keys.
+    // Applied before the map widget is created so that it takes effect on first render.
+    @objc var mapWidgetConfig: String? {
+        didSet { applyMapWidgetConfigIfNeeded() }
+    }
+
+    private var pendingCommandString: String?
+    private var commandDidExecute = false
+
     private(set) var mapWidget: PTRMapWidgetViewController?
     var semaphore: DispatchSemaphore?
     var site: PTRSite?
@@ -65,9 +92,13 @@ import PointrKit
                 print("PTRMapWidget - Pointr is not running")
             }
         }
+        if let existingWidget = self.mapWidget {
+            print("PTRMapWidget - reusing existing map widget, performing new action")
+            existingWidget.performAction(action)
+            return existingWidget
+        }
         print("PTRMapWidget - initializing map widget")
         let mapWidget = PTRMapWidgetViewController(action: action, configuration: PTRNativeLibrary.mapWidgetConfiguration)
-        self.mapWidget?.removeListener(self)
         self.mapWidget = mapWidget
         let adapter = WayfindingEventsAdapter(container: self, mapWidget: mapWidget)
         self.wayfindingEventsAdapter = adapter
@@ -77,6 +108,7 @@ import PointrKit
     }
     
     @objc func present(_ mapWidget: PTRMapWidgetViewController) {
+        guard mapWidget.view.superview == nil else { return }
         addSubview(mapWidget.view)
         mapWidget.view.translatesAutoresizingMaskIntoConstraints = false
         NSLayoutConstraint.activate([
@@ -295,5 +327,156 @@ import PointrKit
         semaphore.wait()
         return Pointr.shared.state
     }
+
+    // MARK: - Declarative command prop handling
+
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        guard window != nil, !commandDidExecute, let jsonString = pendingCommandString else { return }
+        commandDidExecute = true
+        DispatchQueue.global(qos: .userInitiated).async { [weak self] in
+            self?.executeCommandFromJSON(jsonString)
+        }
+    }
+
+    private func applySDKConfigIfNeeded() {
+        guard let jsonString = sdkConfig,
+              let data = jsonString.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return }
+        if let clientId = json["clientId"] as? String { PTRNativeLibrary.params.clientIdentifier = clientId }
+        if let licenseKey = json["licenseKey"] as? String { PTRNativeLibrary.params.licenseKey = licenseKey }
+        if let baseUrl = json["baseUrl"] as? String { PTRNativeLibrary.params.baseUrl = baseUrl }
+        if let logLevel = json["logLevel"] as? Int32 {
+            PTRNativeLibrary.params.loggerLevel = PTRLoggerLevel(rawValue: logLevel) ?? .error
+        }
+        PTRNativeLibrary.params.mode = PointrDebugMode()
+        PTRNativeLibrary.mapWidgetConfiguration.sdkParams = PTRNativeLibrary.params
+    }
+
+    private func applyMapWidgetConfigIfNeeded() {
+        guard let jsonString = mapWidgetConfig,
+              let data = jsonString.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return }
+        let cfg = PTRNativeLibrary.mapWidgetConfiguration
+        let mirror = Mirror(reflecting: cfg)
+        for child in mirror.children {
+            guard let key = child.label, let value = json[key] as? Bool else { continue }
+            cfg.setValue(value, forKey: key)
+        }
+        // The following properties are computed in PTRMapWidgetConfiguration, so Mirror
+        // does not include them in children. Assign them directly.
+        if let value = json["isQuickAccessEnabled"] as? Bool {
+            cfg.isQuickAccessEnabled = value
+        }
+        if let value = json["isMarkMyCarEnabled"] as? Bool {
+            cfg.isMarkMyCarEnabled = value
+        }
+        if let value = json["isInfoButtonEnabled"] as? Bool {
+            cfg.isInfoButtonEnabled = value
+        }
+        if let value = json["shouldFocusOnFirstUserPosition"] as? Bool {
+            cfg.shouldFocusOnFirstUserPosition = value
+        }
+    }
+
+    private func executeCommandFromJSON(_ jsonString: String) {
+        guard let data = jsonString.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let type = json["type"] as? String else {
+            print("PTRMapWidget: invalid command JSON")
+            return
+        }
+
+        let siteId = json["site"] as? String ?? ""
+        let buildingId = json["building"] as? String ?? ""
+        let levelIndex = json["level"] as? Int ?? 0
+        let poiId = json["poi"] as? String ?? ""
+        let fromPoiId = json["fromPoi"] as? String ?? ""
+        let toPoiId = json["toPoi"] as? String ?? ""
+        let sourcePoiId = json["sourcePoi"] as? String ?? ""
+        let destinationPoiId = json["destinationPoi"] as? String ?? ""
+
+        let action: PTRMapWidgetAction
+        let commandParams: [String: Any]
+
+        switch type {
+        case "site":
+            let location = PTRMapWidgetSiteLocation(siteIdentifier: siteId, isExternalIdentifiers: true)
+            let focus = PTRMapWidgetMapFocusAction(location: location, completion: nil)
+            commandParams = ["command": "site", "siteExternalIdentifier": siteId]
+            focus.completion = { [weak self] error in
+                var p = commandParams; p["error"] = error?.errorCode ?? ""
+                self?.ptrMapWidgetDidEndLoading(withParameters: p)
+            }
+            action = focus
+
+        case "building":
+            let location = PTRMapWidgetBuildingLocation(siteIdentifier: siteId, buildingIdentifier: buildingId, isExternalIdentifiers: true)
+            let focus = PTRMapWidgetMapFocusAction(location: location, completion: nil)
+            commandParams = ["command": "building", "siteExternalIdentifier": siteId, "buildingExternalIdentifier": buildingId]
+            focus.completion = { [weak self] error in
+                var p = commandParams; p["error"] = error?.errorCode ?? ""
+                self?.ptrMapWidgetDidEndLoading(withParameters: p)
+            }
+            action = focus
+
+        case "level":
+            let location = PTRMapWidgetLevelLocation(siteIdentifier: siteId, buildingIdentifier: buildingId, levelIndex: levelIndex, isExternalIdentifiers: true)
+            let focus = PTRMapWidgetMapFocusAction(location: location, completion: nil)
+            commandParams = ["command": "level", "siteExternalIdentifier": siteId, "buildingExternalIdentifier": buildingId, "levelIndex": levelIndex]
+            focus.completion = { [weak self] error in
+                var p = commandParams; p["error"] = error?.errorCode ?? ""
+                self?.ptrMapWidgetDidEndLoading(withParameters: p)
+            }
+            action = focus
+
+        case "poi":
+            let location = PTRMapWidgetPoiLocation(siteIdentifier: siteId, poiIdentifier: poiId, isExternalIdentifiers: true)
+            let focus = PTRMapWidgetMapFocusAction(location: location, completion: nil)
+            commandParams = ["command": "poi", "siteExternalIdentifier": siteId, "poiExternalIdentifier": poiId]
+            focus.completion = { [weak self] error in
+                var p = commandParams; p["error"] = error?.errorCode ?? ""
+                self?.ptrMapWidgetDidEndLoading(withParameters: p)
+            }
+            action = focus
+
+        case "path":
+            let wayfinding = PTRMapWidgetWayfindingAction(poiDestination: PTRMapWidgetPoiLocation(siteIdentifier: siteId, poiIdentifier: poiId, isExternalIdentifiers: true))
+            commandParams = ["command": "path", "siteExternalIdentifier": siteId, "poiExternalIdentifier": poiId]
+            wayfinding.completion = { [weak self] error in
+                var p = commandParams; p["error"] = error?.errorCode ?? ""
+                self?.ptrMapWidgetDidEndLoading(withParameters: p)
+            }
+            action = wayfinding
+
+        case "staticPath":
+            DispatchQueue.global(qos: .default).async { [weak self] in
+                self?.showStaticPath(siteId, fromPoiExternalIdentifier: fromPoiId, toPoiExternalIdentifier: toPoiId)
+            }
+            return
+
+        case "staticWayfinding":
+            let srcLocation = PTRMapWidgetPoiLocation(siteIdentifier: siteId, poiIdentifier: sourcePoiId, isExternalIdentifiers: true)
+            let dstLocation = PTRMapWidgetPoiLocation(siteIdentifier: siteId, poiIdentifier: destinationPoiId, isExternalIdentifiers: true)
+            let sw = PTRMapWidgetStaticWayfindingAction(poiSource: srcLocation, poiDestination: dstLocation)
+            commandParams = ["command": "staticWayfinding", "siteExternalIdentifier": siteId, "sourcePoiExternalIdentifier": sourcePoiId, "destinationPoiExternalIdentifier": destinationPoiId]
+            sw.completion = { [weak self] error in
+                var p = commandParams; p["error"] = error?.localizedDescription ?? ""
+                self?.ptrMapWidgetDidEndLoading(withParameters: p)
+            }
+            action = sw
+
+        default:
+            print("PTRMapWidget: unknown command type '\(type)'")
+            return
+        }
+
+        waitForPointrState()
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            let mapWidget = self.getMapWidget(action)
+            self.present(mapWidget)
+        }
+    }
 }
 

package/ios/PTRMapWidgetManager-Bridging.m

@@ -17,6 +17,12 @@ RCT_EXPORT_VIEW_PROPERTY(onMapWidgetDidEndLoading, RCTBubblingEventBlock)
 
 RCT_EXPORT_VIEW_PROPERTY(onWayfindingEvent, RCTBubblingEventBlock)
 
+RCT_EXPORT_VIEW_PROPERTY(command, NSString)
+
+RCT_EXPORT_VIEW_PROPERTY(sdkConfig, NSString)
+
+RCT_EXPORT_VIEW_PROPERTY(mapWidgetConfig, NSString)
+
 RCT_EXTERN_METHOD(site:(nonnull NSNumber *)reactTag
                     siteExternalIdentifier:(NSString *)siteExternalIdentifier)
 RCT_EXTERN_METHOD(building:(nonnull NSNumber *)reactTag

package/ios/PTRNativeLibrary.swift

@@ -38,6 +38,20 @@ class PTRNativeLibrary: RCTEventEmitter, PTREventManagerDelegate {
                 }
                 mapWidgetConfiguration.setValue(value, forKey: key)
             }
+            // The following properties are computed in PTRMapWidgetConfiguration, so Mirror
+            // does not include them in children. Assign them directly.
+            if let value = configuration["isQuickAccessEnabled"] as? Bool {
+                mapWidgetConfiguration.isQuickAccessEnabled = value
+            }
+            if let value = configuration["isMarkMyCarEnabled"] as? Bool {
+                mapWidgetConfiguration.isMarkMyCarEnabled = value
+            }
+            if let value = configuration["isInfoButtonEnabled"] as? Bool {
+                mapWidgetConfiguration.isInfoButtonEnabled = value
+            }
+            if let value = configuration["shouldFocusOnFirstUserPosition"] as? Bool {
+                mapWidgetConfiguration.shouldFocusOnFirstUserPosition = value
+            }
         }
     }
     

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-pointr",
-  "version": "9.6.0",
+  "version": "9.8.0",
   "description": "Pointr React-Native Module",
   "main": "src/index",
   "files": [
@@ -25,17 +25,28 @@
     "version": "0.41.0"
   },
   "peerDependencies": {
-    "react-native": ">=0.64.0",
-    "react": ">=17.0.0"
+    "react-native": ">=0.72",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@types/node": "^24.10.1",
-    "react-native": "^0.82.1"
+    "@types/node": ">=20",
+    "react-native": "0.82.1",
+    "typescript": "^5.8.3"
   },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
+    "check-react": "./check_react.sh",
+    "typescript": "tsc --noEmit",
     "prepare-dist": "chmod +x prepare-distribution.sh && ./prepare-distribution.sh"
   }
 }

package/react-native-pointr.podspec

@@ -16,7 +16,7 @@ Pod::Spec.new do |s|
 
   s.source_files = "ios/**/*.{h,m,mm,swift}"
 
-  s.dependency 'PointrKit', '9.6.0'
+  s.dependency 'PointrKit', '9.8.0'
 
   # Use install_modules_dependencies helper to install the dependencies if React Native version >=0.71.0.
   # See https://github.com/facebook/react-native/blob/febf6b7f33fdb4904669f99d795eba4c0f95d7bf/scripts/cocoapods/new_architecture.rb#L79.

package/src/PTRMapWidgetUtils.ts

@@ -1,5 +1,5 @@
 import { UIManager } from 'react-native';
-import { PTRSiteCommand, PTRBuildingCommand, PTRLevelCommand, PTRPoiCommand, PTRPathCommand, PTRStaticPathCommand, PTRStaticWayfindingCommand, PTRCommand, PTRCommandType, PTRMarkMyCarLevelCommand, PTRMarkMyCarSiteCommand, PTRShowMyCarSiteCommand, PTRStartAndFocusCommand } from 'react-native-pointr/src/PTRCommand';
+import { PTRSiteCommand, PTRBuildingCommand, PTRLevelCommand, PTRPoiCommand, PTRPathCommand, PTRStaticPathCommand, PTRStaticWayfindingCommand, PTRCommand, PTRCommandType, PTRMarkMyCarLevelCommand, PTRMarkMyCarSiteCommand, PTRShowMyCarSiteCommand, PTRStartAndFocusCommand } from './PTRCommand';
 /**
  * Handle PTRStartAndFocusCommand specifically
  * @param reactTag view tag of the map widget
@@ -7,10 +7,8 @@ import { PTRSiteCommand, PTRBuildingCommand, PTRLevelCommand, PTRPoiCommand, PTR
  */
 const handleStartAndFocusCommand = (reactTag: number, startAndFocusCommand: PTRStartAndFocusCommand) => {
   const innerCommand = startAndFocusCommand.command;
-  console.info('Handling PTRStartAndFocusCommand with type:', innerCommand.type);
   // Build arguments based on the inner command type
   let args: any[];
-  console.info('Inner command details:', innerCommand);
   
   switch (innerCommand.type) {
     case PTRCommandType.SITE: {
@@ -73,7 +71,6 @@ const handleStartAndFocusCommand = (reactTag: number, startAndFocusCommand: PTRS
       console.error('Unsupported command type in PTRStartAndFocusCommand:', innerCommand.type);
       return;
   }
-  console.info('Dispatching startAndFocus with args:', args);
   UIManager.dispatchViewManagerCommand(
     reactTag,
     'startAndFocus',
@@ -89,15 +86,12 @@ const handleStartAndFocusCommand = (reactTag: number, startAndFocusCommand: PTRS
 export const showMapWidget = (reactTag: number, ptrCommand: PTRCommand | PTRStartAndFocusCommand) => {
   // Check if it's a PTRStartAndFocusCommand (which doesn't have a 'type' property)
   if ('command' in ptrCommand) {
-    const startAndFocusCommand = ptrCommand as PTRStartAndFocusCommand;
-    console.log(`Showing map widget with start and focus command: ${startAndFocusCommand.command.type} and reactTag: ${reactTag}`);
-    handleStartAndFocusCommand(reactTag, startAndFocusCommand);
+    handleStartAndFocusCommand(reactTag, ptrCommand as PTRStartAndFocusCommand);
     return;
   }
 
   // Handle regular PTRCommand
   const command = ptrCommand as PTRCommand;
-  console.log(`Showing map widget with command: ${command.type} and reactTag: ${reactTag}`);
   switch (command.type) {
     case PTRCommandType.SITE: {
       const siteCommand = ptrCommand as PTRSiteCommand;

package/src/api/MapWidgetApi.ts

@@ -0,0 +1,45 @@
+/**
+ * Map Widget API utilities
+ * Provides type-safe command execution for the map widget
+ * @module api/MapWidgetApi
+ */
+
+import { findNodeHandle } from 'react-native';
+import type { PTRCommand } from '../commands';
+import { PTRErrorMessages } from '../constants';
+import { showMapWidget } from '../PTRMapWidgetUtils';
+
+/**
+ * Execute a command 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
+ */
+export function executeMapCommand(
+  mapRef: React.RefObject<any> | any,
+  command: PTRCommand
+): void {
+  if (!mapRef) {
+    throw new Error(PTRErrorMessages.NO_MAP_REF);
+  }
+
+  const ref = 'current' in mapRef ? mapRef.current : mapRef;
+  const reactTag = findNodeHandle(ref);
+
+  if (!reactTag) {
+    throw new Error(PTRErrorMessages.NO_MAP_REF);
+  }
+
+  if (!command || !command.type) {
+    throw new Error(PTRErrorMessages.INVALID_COMMAND);
+  }
+
+  try {
+    showMapWidget(reactTag, command);
+  } catch (error) {
+    console.error('Error executing map command:', error);
+    throw error;
+  }
+}
+
+

package/src/api/PointrSdk.ts

@@ -0,0 +1,241 @@
+/**
+ * Pointr SDK singleton wrapper
+ * Provides a clean, type-safe API for the Pointr SDK
+ * @module api/PointrSdk
+ */
+
+import { NativeModules, NativeEventEmitter, Platform } from 'react-native';
+import type { PTRConfiguration, PTRMapWidgetConfiguration, PTRStateCallback } from '../types/config';
+import type { PTRPosition } from '../types/PTRPosition';
+import { PTRState, PTRLogLevel, PTRErrorMessages, PTREvents } from '../constants';
+
+const LINKING_ERROR =
+  `The package 'react-native-pointr' doesn't seem to be linked. Make sure: \n\n` +
+  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
+  '- You rebuilt the app after installing the package\n' +
+  '- You are not using Expo Go\n';
+
+const PTRNativePointrLibrary = NativeModules.PTRNativePointrLibrary
+  ? NativeModules.PTRNativePointrLibrary
+  : new Proxy(
+      {},
+      {
+        get() {
+          throw new Error(LINKING_ERROR);
+        },
+      }
+    );
+
+/**
+ * Singleton class for managing the Pointr SDK
+ */
+export class PointrSdk {
+  private static instance: PointrSdk | null = null;
+  private state: PTRState = PTRState.NOT_INITIALIZED;
+  private config: PTRConfiguration | null = null;
+  private eventEmitter: NativeEventEmitter;
+
+  private constructor() {
+    this.eventEmitter = new NativeEventEmitter(PTRNativePointrLibrary);
+  }
+
+  /**
+   * Get the singleton instance of PointrSdk
+   */
+  public static getInstance(): PointrSdk {
+    if (!PointrSdk.instance) {
+      PointrSdk.instance = new PointrSdk();
+    }
+    return PointrSdk.instance;
+  }
+
+  /**
+   * Initialize the Pointr SDK with configuration
+   * @param config - Configuration options
+   * @throws Error if already initialized or invalid config
+   */
+  public initialize(config: PTRConfiguration): void {
+    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);
+    }
+
+    this.state = PTRState.INITIALIZING;
+    this.config = config;
+
+    const logLevel = config.logLevel ?? PTRLogLevel.ERROR;
+
+    try {
+      PTRNativePointrLibrary.initialize(
+        config.clientId,
+        config.licenseKey,
+        config.baseUrl,
+        logLevel
+      );
+      this.state = PTRState.INITIALIZED;
+    } catch (error) {
+      this.state = PTRState.ERROR;
+      throw error;
+    }
+  }
+
+  /**
+   * Start the Pointr SDK
+   * @param callback - Optional callback for state changes
+   * @throws Error if not initialized
+   */
+  public start(callback?: PTRStateCallback): void {
+    if (this.state === PTRState.NOT_INITIALIZED) {
+      throw new Error(PTRErrorMessages.NOT_INITIALIZED);
+    }
+
+    this.state = PTRState.STARTING;
+
+    try {
+      PTRNativePointrLibrary.start((state: string) => {
+        this.state = PTRState.RUNNING;
+        if (callback) {
+          callback(state);
+        }
+      });
+    } catch (error) {
+      this.state = PTRState.ERROR;
+      throw error;
+    }
+  }
+
+  /**
+   * 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;
+      }
+    }
+  }
+
+  /**
+   * Get the current SDK state
+   */
+  public getState(): PTRState {
+    return this.state;
+  }
+
+  /**
+   * Check if SDK is initialized
+   */
+  public isInitialized(): boolean {
+    return this.state !== PTRState.NOT_INITIALIZED;
+  }
+
+  /**
+   * Check if SDK is started and running
+   */
+  public isStarted(): boolean {
+    return this.state === PTRState.RUNNING;
+  }
+
+  /**
+   * Get the current configuration
+   */
+  public getConfig(): PTRConfiguration | null {
+    return this.config;
+  }
+
+  /**
+   * 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
+   */
+  public onPositionUpdate(callback: (position: any) => void) {
+    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
+   */
+  public onBuildingClick(callback: (event: any) => void) {
+    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
+   */
+  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
+   */
+  public onGeofenceEvent(callback: (event: any) => void) {
+    return this.eventEmitter.addListener(
+      PTREvents.ON_GEOFENCE_EVENT,
+      callback
+    );
+  }
+
+  /**
+   * 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));
+  }
+
+  /**
+   * Get the current calculated position.
+   * Resolves with the position or null if unavailable.
+   */
+  public getCurrentLocation(): Promise<PTRPosition | null> {
+    return new Promise((resolve) => {
+      PTRNativePointrLibrary.getCurrentLocation((result: any) => {
+        if (!result || typeof result === 'string') {
+          resolve(null);
+        } else {
+          resolve(result as PTRPosition);
+        }
+      });
+    });
+  }
+
+  /**
+   * Get native module reference (for advanced use cases)
+   */
+  public getNativeModule() {
+    return PTRNativePointrLibrary;
+  }
+}
+
+/**
+ * Export singleton instance for easy access
+ */
+export const pointrSdk = PointrSdk.getInstance();

package/src/api/index.ts

@@ -0,0 +1,9 @@
+/**
+ * API utilities for the Pointr SDK
+ * @module api
+ */
+
+export { PointrSdk, pointrSdk } from './PointrSdk';
+export {
+  executeMapCommand,
+} from './MapWidgetApi';