react-native-pointr 9.8.0 → 10.0.0

package/API_REFERENCE.md

@@ -1,36 +1,28 @@
-# React Native Pointr - API Reference
+# React Native Pointr — API Reference
 
-> **Platform Compatibility:** This API reference is identical for both Android and iOS platforms. All methods, parameters, and behaviors are consistent across platforms.
+> **Platform Compatibility:** This API reference is identical for both Android and iOS platforms unless otherwise noted.
 
 ## Table of Contents
 - [Quick Start](#quick-start)
 - [PointrSdk Class](#pointrsdk-class)
-- [executeMapCommand](#executemapcommand)
+- [executeMapAction](#executemapaction)
 - [React Hooks](#react-hooks)
 - [PTRMapWidget Component](#ptrmapwidget-component)
 - [Constants & Enums](#constants--enums)
-- [Command Classes](#command-classes)
+- [Action Classes](#action-classes)
 - [Types](#types)
 - [Event Listeners](#event-listeners)
 - [Complete Example](#complete-example)
-- [Legacy API](#legacy-api)
 - [Error Handling](#error-handling)
 
 ---
 
 ## Quick Start
 
-The library now exposes two API layers:
-
-| Layer | When to use |
-|-------|-------------|
-| **New API** (`PointrSdk`, `usePointrSdk`, `PTRMapWidget` declarative props) | All new integration work |
-| **Legacy API** (`NativeModules.PTRNativePointrLibrary`, `showMapWidget`) | Existing code — still fully supported |
-
-**Minimal declarative setup (new API):**
+**Minimal declarative setup:**
 
 ```tsx
-import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
+import { PTRMapWidget, PTRFocusMapAction } from 'react-native-pointr';
 import type { PTRConfiguration } from 'react-native-pointr';
 
 const SDK_CONFIG: PTRConfiguration = {
@@ -44,7 +36,7 @@ export default function MapScreen() {
     <PTRMapWidget
       style={{ flex: 1 }}
       sdkConfig={SDK_CONFIG}
-      command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
+      action={new PTRFocusMapAction('<SITE_EXTERNAL_ID>')}
     />
   );
 }
@@ -92,19 +84,18 @@ pointrSdk.initialize({
 
 ---
 
-#### `start(callback?)`
-
-Starts the SDK. SDK must be initialized first.
+#### `start()`
 
-**Parameters:**
-- `callback` (`PTRStateCallback`, optional): Receives the native state string when the SDK is running.
+Starts the SDK. Returns a `Promise<void>` that resolves when the SDK reaches the `RUNNING` state. SDK must be initialized first.
 
 **Throws:** `Error` if not initialized.
 
 ```typescript
-pointrSdk.start((state) => {
-  console.log('Native state:', state); // e.g. "running"
-});
+await pointrSdk.start();
+// or with error handling:
+pointrSdk.start()
+  .then(() => console.log('SDK running'))
+  .catch((err) => console.error('Start failed:', err));
 ```
 
 ---
@@ -223,7 +214,7 @@ Subscribes to `OnBuildingClicked` events.
 
 ```typescript
 const sub = pointrSdk.onBuildingClick((event) => {
-  console.log(event.internalIdentifier, event.title);
+  console.log(event.buildingId, event.siteId);
 });
 ```
 
@@ -235,7 +226,7 @@ Subscribes to `OnSiteClicked` events.
 
 ```typescript
 const sub = pointrSdk.onSiteClick((event) => {
-  console.log(event.internalIdentifier, event.title);
+  console.log(event.siteId, event.siteName);
 });
 ```
 
@@ -253,6 +244,19 @@ const sub = pointrSdk.onGeofenceEvent((event) => {
 
 ---
 
+#### `getGeofences(siteId)`
+
+Returns a `Promise<PTRGeofence[]>` with the geofences configured for the given site.
+
+**Parameters:**
+- `siteId` (`string`): External site identifier.
+
+```typescript
+const geofences = await pointrSdk.getGeofences('<SITE_ID>');
+```
+
+---
+
 #### `getEventEmitter()`
 
 Returns the underlying `NativeEventEmitter` for advanced subscription use cases.
@@ -265,48 +269,48 @@ const emitter = pointrSdk.getEventEmitter();
 
 #### `getNativeModule()`
 
-Returns the raw `NativeModules.PTRNativePointrLibrary` reference for advanced use cases.
+Returns the raw `NativeModules.PTRNativeLibrary` reference for advanced use cases not covered by the `PointrSdk` wrapper (e.g. `getPois`, `searchPois`, `isWayfindingReady`, `calculateDistance`).
 
 ```typescript
 const native = pointrSdk.getNativeModule();
-native.requestPermissions();
+const pois = await native.getPois('<SITE_ID>');
 ```
 
 ---
 
-## executeMapCommand
+## executeMapAction
 
 A convenience function that resolves `findNodeHandle` internally and dispatches a command to the native map widget.
 
 **Import:**
 ```typescript
-import { executeMapCommand } from 'react-native-pointr';
+import { executeMapAction } from 'react-native-pointr';
 ```
 
 **Signature:**
 ```typescript
-function executeMapCommand(
+function executeMapAction(
   mapRef: React.RefObject<any> | any,
-  command: PTRCommand
+  action: PTRAction
 ): void
 ```
 
 **Parameters:**
 - `mapRef`: A React ref (or any object with a `.current` property) pointing to the rendered `PTRMapWidget`.
-- `command`: Any `PTRCommand` subclass instance.
+- `action`: Any `PTRAction` subclass instance.
 
 **Throws:** `Error` if `mapRef` is null, the native view tag cannot be resolved, or the command is invalid.
 
 **Example:**
 ```typescript
 import { useRef } from 'react';
-import { PTRMapWidget, PTRPoiCommand, executeMapCommand } from 'react-native-pointr';
+import { PTRMapWidget, PTRHighlightPoiAction, executeMapAction } from 'react-native-pointr';
 
 function MyMap() {
   const mapRef = useRef(null);
 
   const navigateToLobby = () => {
-    executeMapCommand(mapRef, new PTRPoiCommand('<SITE_ID>', 'Lobby'));
+    executeMapAction(mapRef, new PTRHighlightPoiAction('<SITE_ID>', 'Lobby'));
   };
 
   return <PTRMapWidget ref={mapRef} style={{ flex: 1 }} />;
@@ -431,7 +435,7 @@ Subscribes to building-tap events on the map.
 import { usePointrBuildingClick } from 'react-native-pointr';
 
 usePointrBuildingClick((event) => {
-  console.log('Building tapped:', event.internalIdentifier, event.title);
+  console.log('Building tapped:', event.buildingId, event.siteId);
 });
 ```
 
@@ -448,12 +452,39 @@ Subscribes to site-tap events on the map.
 import { usePointrSiteClick } from 'react-native-pointr';
 
 usePointrSiteClick((event) => {
-  console.log('Site tapped:', event.internalIdentifier, event.title);
+  console.log('Site tapped:', event.siteId, event.siteName);
 });
 ```
 
 ---
 
+### `usePointrGeofences(siteId?)`
+
+Fetches geofences for a site.
+
+**Parameters:**
+- `siteId` (string, optional): External site identifier. Fetches when this value changes.
+
+**Returns:**
+```typescript
+{
+  geofences: PTRGeofence[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => void;
+}
+```
+
+```typescript
+import { usePointrGeofences } from 'react-native-pointr';
+
+function GeofenceList() {
+  const { geofences, loading } = usePointrGeofences('<SITE_ID>');
+}
+```
+
+---
+
 ## PTRMapWidget Component
 
 `PTRMapWidget` is a typed React component (with `forwardRef`) that wraps the native map view.
@@ -469,7 +500,7 @@ import type { PTRMapWidgetProps } from 'react-native-pointr';
 | Prop | Type | Description |
 |------|------|-------------|
 | `style` | `ViewStyle` | Component styling |
-| `command` | `PTRCommand` | Declarative command executed automatically on mount |
+| `action` | `PTRAction` | Declarative action executed automatically on mount |
 | `sdkConfig` | `PTRConfiguration` | When provided, initializes the SDK without a prior `pointrSdk.initialize()` call |
 | `mapWidgetConfig` | `PTRMapWidgetConfiguration` | UI configuration applied before the widget renders |
 | `onMapWidgetDidEndLoading` | `(event: NativeSyntheticEvent<PTRMapCommandResponse>) => void` | Fired when the map finishes loading a command |
@@ -477,10 +508,10 @@ import type { PTRMapWidgetProps } from 'react-native-pointr';
 
 ### Declarative usage (recommended)
 
-Pass `command`, `sdkConfig`, and `mapWidgetConfig` as props so the widget handles initialization automatically:
+Pass `action`, `sdkConfig`, and `mapWidgetConfig` as props so the widget handles initialization automatically:
 
 ```tsx
-import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
+import { PTRMapWidget, PTRFocusMapAction } from 'react-native-pointr';
 import type { PTRConfiguration, PTRMapWidgetConfiguration } from 'react-native-pointr';
 
 const SDK_CONFIG: PTRConfiguration = {
@@ -501,7 +532,7 @@ function MapScreen() {
       style={{ flex: 1 }}
       sdkConfig={SDK_CONFIG}
       mapWidgetConfig={MAP_CONFIG}
-      command={new PTRSiteCommand('<SITE_ID>')}
+      action={new PTRFocusMapAction('<SITE_ID>')}
       onMapWidgetDidEndLoading={(e) => console.log('Loaded', e.nativeEvent)}
       onWayfindingEvent={(e) => console.log('Navigation', e.nativeEvent)}
     />
@@ -511,17 +542,17 @@ function MapScreen() {
 
 ### Imperative usage
 
-Use `ref` + `executeMapCommand` to dispatch commands after mount:
+Use `ref` + `executeMapAction` to dispatch actions after mount:
 
 ```tsx
 import { useRef } from 'react';
-import { PTRMapWidget, PTRPoiCommand, executeMapCommand } from 'react-native-pointr';
+import { PTRMapWidget, PTRHighlightPoiAction, executeMapAction } from 'react-native-pointr';
 
 function MapScreen() {
   const mapRef = useRef(null);
 
   const goToLobby = () => {
-    executeMapCommand(mapRef, new PTRPoiCommand('<SITE_ID>', 'Lobby'));
+    executeMapAction(mapRef, new PTRHighlightPoiAction('<SITE_ID>', 'Lobby'));
   };
 
   return (
@@ -576,21 +607,18 @@ enum PTRState {
 
 ---
 
-### `PTRCommandType`
-
-```typescript
-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',
+### `PTRActionType`
+
+```typescript
+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',
 }
 ```
 
@@ -598,7 +626,7 @@ enum PTRCommandType {
 
 ### `PTRAnimationType`
 
-Animation type constants for map transitions.
+Animation type constants for map transitions. Used in `PTRMarkMyCarAction` and `PTRShowMyCarAction`.
 
 ```typescript
 enum PTRAnimationType {
@@ -609,7 +637,64 @@ enum PTRAnimationType {
 }
 ```
 
-> **Note:** The "My Car" command constructors (`PTRMarkMyCarLevelCommand`, `PTRMarkMyCarSiteCommand`, `PTRShowMyCarSiteCommand`) accept `animationType` as a plain `number` parameter, not as `PTRAnimationType`. The numeric values `0`, `1`, `2` correspond to none, standard, and fly-over animation respectively.
+> **Note:** `PTRMarkMyCarAction` and `PTRShowMyCarAction` accept `animationType` as a plain `number` parameter (not the enum string). Values: `0` = none, `1` = standard, `2` = fly-over.
+
+---
+
+### `PTRWayfindingMode`
+
+Routing behaviour for turn-by-turn navigation.
+
+```typescript
+enum PTRWayfindingMode {
+  NORMAL     = 'normal',     // Standard routing
+  ACCESSIBLE = 'accessible', // Avoids stairs, prefers ramps / lifts
+}
+```
+
+---
+
+### `PTRMapTrackingMode`
+
+Controls how the map follows the user's position.
+
+```typescript
+enum PTRMapTrackingMode {
+  NONE                  = 'none',
+  TRACKING              = 'tracking',
+  TRACKING_WITH_HEADING = 'trackingWithHeading',
+}
+```
+
+---
+
+### `PTRMapWidgetLayoutState`
+
+Represents the active panel state of the map widget.
+
+```typescript
+enum PTRMapWidgetLayoutState {
+  IDLE             = 'idle',
+  POI_DETAILS      = 'poiDetails',
+  WAYFINDING       = 'wayfinding',
+  STATIC_WAYFINDING= 'staticWayfinding',
+  ROUTE_SUMMARY    = 'routeSummary',
+}
+```
+
+---
+
+### `PTRWayfindingEventType`
+
+Lifecycle states of a navigation session, used as `PTRWayfindingEvent.type`.
+
+```typescript
+enum PTRWayfindingEventType {
+  CANCELLED = -1, // Wayfinding cancelled by the user
+  STARTED   = 0,  // Navigation session started
+  ENDED     = 1,  // Destination reached
+}
+```
 
 ---
 
@@ -619,10 +704,11 @@ enum PTRAnimationType {
 enum PTRGeofenceEventType {
   ENTER = 'enter',
   EXIT  = 'exit',
+  DWELL = 'dwell',
 }
 ```
 
-> **Note:** `DWELL` is not emitted by the native SDK on either platform.
+> **Note:** `DWELL` is defined in the enum but is not emitted by the native SDK on either platform.
 
 ---
 
@@ -645,7 +731,7 @@ const PTREvents = {
 
 ### `PTRErrorMessages`
 
-Pre-defined error message strings thrown by `PointrSdk` and `executeMapCommand`.
+Pre-defined error message strings thrown by `PointrSdk` and `executeMapAction`.
 
 ```typescript
 const PTRErrorMessages = {
@@ -661,173 +747,121 @@ const PTRErrorMessages = {
 
 ---
 
-## Command Classes
-
-All command classes are exported from `react-native-pointr`.
-
-### `PTRSiteCommand`
+## Action Classes
 
-Shows a specific site on the map.
-
-```typescript
-new PTRSiteCommand(site: string)
-```
-
-```typescript
-new PTRSiteCommand('<SITE_EXTERNAL_ID>')
-```
-
----
+All action classes extend `PTRAction` and are exported from `react-native-pointr`. Pass an instance to `PTRMapWidget`'s `action` prop or to `executeMapAction`.
 
-### `PTRBuildingCommand`
+### `PTRFocusMapAction`
 
-Shows a specific building within a site.
+Focuses the map on a site, building, or level. Provide only as many parameters as needed for the desired zoom depth.
 
 ```typescript
-new PTRBuildingCommand(site: string, building: string)
+new PTRFocusMapAction(site: string, building?: string, level?: number)
 ```
 
----
-
-### `PTRLevelCommand`
-
-Shows a specific level within a building.
-
 ```typescript
-new PTRLevelCommand(site: string, building: string, level: number)
+new PTRFocusMapAction('<SITE_ID>')                       // focus on site
+new PTRFocusMapAction('<SITE_ID>', '<BUILDING_ID>')      // focus on building
+new PTRFocusMapAction('<SITE_ID>', '<BUILDING_ID>', 2)   // focus on level 2
 ```
 
 ---
 
-### `PTRPoiCommand`
+### `PTRHighlightPoiAction`
 
-Focuses the map on a specific POI.
+Highlights a specific POI on the map.
 
 ```typescript
-new PTRPoiCommand(site: string, poi: string)
+new PTRHighlightPoiAction(site: string, poi: string)
 ```
 
 - `poi`: POI external identifier or name.
 
 ---
 
-### `PTRPathCommand`
+### `PTRDisplayRouteAction`
 
-Shows a navigation path from the user's current location to a POI.
+Displays a static route between two POIs without requiring live user location.
 
 ```typescript
-new PTRPathCommand(site: string, poi: string)
+new PTRDisplayRouteAction(site: string, fromPoi: string, toPoi: string)
 ```
 
 ---
 
-### `PTRStaticPathCommand`
+### `PTRStartWayfindingAction`
 
-Shows a static path between two POIs.
+Starts turn-by-turn wayfinding from the user's current position to a destination POI.
 
 ```typescript
-new PTRStaticPathCommand(site: string, fromPoi: string, toPoi: string)
+new PTRStartWayfindingAction(site: string, poi: string)
 ```
 
 ---
 
-### `PTRStaticWayfindingCommand`
+### `PTRMarkMyCarAction`
 
-Initiates static wayfinding between two POIs.
+Marks the car location. When `building` and `level` are provided, pins to that specific level; otherwise pins at the site level using the current position.
 
 ```typescript
-new PTRStaticWayfindingCommand(site: string, sourcePoi: string, destinationPoi: string)
+new PTRMarkMyCarAction(
+  site: string,
+  building?: string,
+  level?: number,
+  shouldShowPopup?: boolean,  // default: true
+  animationType?: number      // default: 1 (standard). 0 = none, 2 = fly-over
+)
 ```
 
 ---
 
-### `PTRMarkMyCarLevelCommand`
+### `PTRShowMyCarAction`
 
-Marks the "My Car" location at a specific level.
+Shows the previously saved car location.
 
 ```typescript
-new PTRMarkMyCarLevelCommand(
+new PTRShowMyCarAction(
   site: string,
-  building: string,
-  level: number,
-  shouldShowPopup?: boolean,   // default: true
-  animationType?: number       // default: 1
+  shouldShowPopup?: boolean,  // default: true
+  animationType?: number      // default: 1
 )
 ```
 
 ---
 
-### `PTRMarkMyCarSiteCommand`
+### `PTRFocusCoordinateAction`
 
-Marks the "My Car" location at the current position within a site.
+Focuses the map on a specific geographic coordinate, optionally at a given level.
 
 ```typescript
-new PTRMarkMyCarSiteCommand(
+new PTRFocusCoordinateAction(
   site: string,
-  shouldShowPopup?: boolean,   // default: true
-  animationType?: number       // default: 1
+  latitude: number,
+  longitude: number,
+  levelIndex?: number
 )
 ```
 
----
-
-### `PTRShowMyCarSiteCommand`
-
-Shows the previously saved "My Car" location.
-
 ```typescript
-new PTRShowMyCarSiteCommand(
-  site: string,
-  shouldShowPopup?: boolean,   // default: true
-  animationType?: number       // default: 1
-)
+new PTRFocusCoordinateAction('<SITE_ID>', 47.4979, 19.0402)
+new PTRFocusCoordinateAction('<SITE_ID>', 47.4979, 19.0402, 2)
 ```
 
 ---
 
-### `PTRStartAndFocusCommand`
+### `PTRHighlightCategoryAction` / `PTRCategoryFilterAction`
 
-Combines SDK initialization with a focus command in a single native dispatch. Use for deep-link or notification-driven entry points where the SDK may not yet be running.
+Filters the visible POIs to only those belonging to the specified category identifiers. Pass an empty array to clear the active filter.
 
-> **Note:** This command is dispatched via `showMapWidget` / the legacy `UIManager` path and is not a `PTRCommand` subclass. Prefer the declarative `sdkConfig` + `command` props on `PTRMapWidget` for new code.
+> Exported under both names: `PTRHighlightCategoryAction` (class name) and `PTRCategoryFilterAction` (alias).
 
 ```typescript
-new PTRStartAndFocusCommand(
-  clientId: string,
-  licenseKey: string,
-  baseUrl: string,
-  logLevel: number,             // default: 4 (ERROR)
-  command: PTRSiteCommand | PTRBuildingCommand | PTRLevelCommand | PTRPoiCommand
-)
+new PTRHighlightCategoryAction(site: string, categoryIds: string[])
 ```
 
 ```typescript
-import { PTRStartAndFocusCommand, PTRSiteCommand, showMapWidget } from 'react-native-pointr';
-import { findNodeHandle } from 'react-native';
-
-const cmd = new PTRStartAndFocusCommand(
-  '<CLIENT_ID>',
-  '<LICENSE_KEY>',
-  'https://<your-instance>.pointr.cloud',
-  4,
-  new PTRSiteCommand('<SITE_ID>')
-);
-showMapWidget(findNodeHandle(mapRef.current), cmd);
-```
-
----
-
-### Type guards
-
-```typescript
-import {
-  isPTRSiteCommand,
-  isPTRBuildingCommand,
-  isPTRLevelCommand,
-  isPTRPoiCommand,
-  isPTRPathCommand,
-  isPTRStaticPathCommand,
-} from 'react-native-pointr';
+new PTRHighlightCategoryAction('<SITE_ID>', ['cafes', 'restaurants'])
+new PTRHighlightCategoryAction('<SITE_ID>', [])  // clear filter
 ```
 
 ---
@@ -851,8 +885,6 @@ interface PTRConfiguration {
 
 ### `PTRMapWidgetConfiguration`
 
-Parameter names must match the boolean properties of `PTRMapWidgetConfiguration` declared in the native SDK. See [iOS SDK reference](https://pointr.blob.core.windows.net/api-ref/ios/9.6/Classes/PTRMapWidgetConfiguration.html) and [Android SDK reference](https://pointr.blob.core.windows.net/api-ref/android/9.6/-pointr%20-android%20-s-d-k%209.6.0/com.pointrlabs.ui.map.viewmodels/-p-t-r-map-widget-configuration/index.html) for the full list.
-
 ```typescript
 interface PTRMapWidgetConfiguration {
   readonly isLevelSelectorEnabled?: boolean;
@@ -868,6 +900,14 @@ interface PTRMapWidgetConfiguration {
   readonly shouldFocusOnFirstUserPosition?: boolean;
   readonly isQuickAccessEnabled?: boolean;
   readonly isAppBannerEnabled?: boolean;
+  /** Position of the exit button. Accepted values: 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' */
+  readonly exitButtonPosition?: string;
+  /** Routing mode. Defaults to PTRWayfindingMode.NORMAL. */
+  readonly wayfindingMode?: PTRWayfindingMode;
+  /** Initial map tracking mode. Defaults to PTRMapTrackingMode.NONE. */
+  readonly initialMapTrackingMode?: PTRMapTrackingMode;
+  /** Search panel layout. Accepted values: 'default' | 'minimal' */
+  readonly searchLayout?: string;
 }
 ```
 
@@ -877,12 +917,20 @@ interface PTRMapWidgetConfiguration {
 
 ```typescript
 interface PTRPosition {
-  lat: number;      // Latitude
-  lon: number;      // Longitude
+  // Short names
+  lat: number;       // Latitude
+  lon: number;       // Longitude
+  sid: string;       // Site identifier
+  bid: string;       // Building identifier
+  lvl: number;       // Level index
   isValid: boolean;
-  sid: string;      // Site identifier
-  bid: string;      // Building identifier
-  lvl: number;      // Level index
+
+  // Readable aliases (optional — present when populated by the SDK)
+  latitude?: number;
+  longitude?: number;
+  siteId?: string;
+  buildingId?: string;
+  levelIndex?: number;
 }
 ```
 
@@ -890,7 +938,15 @@ interface PTRPosition {
 
 ### `PTRPositionEvent`
 
-The TypeScript return type of `usePointrPosition` and the argument type of `pointrSdk.onPositionUpdate` callbacks. The actual runtime payload is the raw native event object with the fields listed under [`getCurrentLocation()`](#getcurrentlocation) rather than a wrapped `PTRPosition`.
+The return type of `usePointrPosition` and the callback argument of `pointrSdk.onPositionUpdate`.
+
+```typescript
+interface PTRPositionEvent {
+  readonly position: PTRPosition;
+  readonly timestamp?: number;   // milliseconds since epoch
+  readonly accuracy?: number;    // accuracy in metres
+}
+```
 
 ---
 
@@ -901,7 +957,8 @@ interface PTRPoi {
   identifier: string;
   externalIdentifier: string;
   name: string;
-  typeCode: string;
+  mainType: string;
+  subType?: string;
   position: PTRPosition;
   geometry: PTRGeometry;
   attributes: PTRPoiAttributes;
@@ -947,20 +1004,20 @@ type PTRGeometry =
 
 ### `PTRWayfindingEvent`
 
-Fired via `onWayfindingEvent` prop on `PTRMapWidget`.
+Fired via the `onWayfindingEvent` prop on `PTRMapWidget`.
 
 ```typescript
 interface PTRWayfindingEvent {
-  type: -1 | 0 | 1;  // -1 Cancelled, 0 Started, 1 Ended
-  poi: PTRPoi;        // Destination POI
+  type: PTRWayfindingEventType; // CANCELLED = -1, STARTED = 0, ENDED = 1
+  poi: PTRPoi;                  // Destination POI
 }
 ```
 
-| `type` value | Meaning |
-|-----|---------|
-| `-1` | Wayfinding cancelled by user |
-| `0` | Wayfinding started |
-| `1` | Wayfinding ended (completed or dismissed) |
+| `type` value | `PTRWayfindingEventType` | Meaning |
+|-------------|--------------------------|---------|
+| `-1` | `CANCELLED` | Wayfinding cancelled by user |
+| `0` | `STARTED` | Navigation session started |
+| `1` | `ENDED` | Destination reached |
 
 ---
 
@@ -982,52 +1039,68 @@ interface PTRMapCommandResponse {
 
 ```typescript
 interface PTRGeofenceEvent {
-  readonly eventType: 'enter' | 'exit';
-  readonly geofence: PTRGeofence;
+  readonly eventType: PTRGeofenceEventType | string;
+  readonly geofence?: PTRGeofence;
   readonly geofenceNotification?: PTRGeofenceNotification;
-  readonly timestamp?: number;        // iOS only — milliseconds since epoch at root level
-  readonly geofenceType?: string;     // Android only — 'beacon' | 'gps' at root level
+  readonly timestamp?: number;  // iOS only — milliseconds since epoch
 }
 
 interface PTRGeofence {
   readonly id: string;
-  readonly externalId: string;
+  readonly externalId?: string;
   readonly name: string;
-  readonly geofenceType?: string;     // iOS only — 'beacon' | 'gps' inside geofence object
-  readonly position: {
-    readonly latitude: number;
-    readonly longitude: number;
-  };
+  readonly geofenceType: string;  // 'beacon' | 'gps'
+  readonly position: PTRPosition;
 }
 
 interface PTRGeofenceNotification {
   readonly id: string;
   readonly message: string;
-  readonly timestamp: number;          // milliseconds
+  readonly timestamp: number;  // milliseconds
 }
 ```
 
-**Platform differences:**
-- iOS: `timestamp` (milliseconds since epoch) is present at the event root level; `geofenceType` is inside the `geofence` object.
-- Android: No `timestamp` at the root level; `geofenceType` is at the event root level (not inside `geofence`).
-
 ---
 
 ### `PTRBuildingClickEvent` / `PTRSiteClickEvent`
 
-Both events share the same payload shape emitted by the native SDK:
-
 ```typescript
 interface PTRBuildingClickEvent {
-  readonly internalIdentifier: string;
-  readonly externalIdentifier: string;
-  readonly title: string;
+  readonly siteId: string;
+  readonly buildingId: string;
+  readonly buildingName?: string;
 }
 
 interface PTRSiteClickEvent {
-  readonly internalIdentifier: string;
+  readonly siteId: string;
+  readonly siteName?: string;
+}
+```
+
+---
+
+### `PTRSite` / `PTRBuilding` / `PTRLevel`
+
+```typescript
+interface PTRLevel {
+  readonly identifier: string;
+  readonly externalIdentifier: string;
+  readonly name: string;
+  readonly index: number;  // zero-based
+}
+
+interface PTRBuilding {
+  readonly identifier: string;
+  readonly externalIdentifier: string;
+  readonly name: string;
+  readonly levels: PTRLevel[];
+}
+
+interface PTRSite {
+  readonly identifier: string;
   readonly externalIdentifier: string;
-  readonly title: string;
+  readonly name: string;
+  readonly buildings: PTRBuilding[];
 }
 ```
 
@@ -1057,12 +1130,12 @@ usePointrGeofence((event) => {
 
 // Building click
 usePointrBuildingClick((event) => {
-  console.log('Building:', event.internalIdentifier, event.title);
+  console.log('Building:', event.buildingId, event.siteId);
 });
 
 // Site click
 usePointrSiteClick((event) => {
-  console.log('Site:', event.internalIdentifier, event.title);
+  console.log('Site:', event.siteId, event.siteName);
 });
 ```
 
@@ -1091,7 +1164,7 @@ Available methods: `onPositionUpdate`, `onBuildingClick`, `onSiteClick`, `onGeof
 import { NativeEventEmitter, NativeModules } from 'react-native';
 import { PTREvents } from 'react-native-pointr';
 
-const emitter = new NativeEventEmitter(NativeModules.PTRNativePointrLibrary);
+const emitter = new NativeEventEmitter(NativeModules.PTRNativeLibrary);
 
 const sub = emitter.addListener(PTREvents.ON_POSITION_CALCULATED, (pos) => {
   console.log(pos);
@@ -1130,12 +1203,12 @@ The `PTRMapWidget` component exposes two event callbacks as props:
 
 ### Declarative (recommended for simple integrations)
 
-Pass `sdkConfig`, `mapWidgetConfig`, and `command` directly as props. No hook or imperative call is needed.
+Pass `sdkConfig`, `mapWidgetConfig`, and `action` directly as props. No hook or imperative call is needed.
 
 ```tsx
 import React from 'react';
 import { StyleSheet } from 'react-native';
-import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
+import { PTRMapWidget, PTRFocusMapAction } from 'react-native-pointr';
 import type { PTRConfiguration, PTRMapWidgetConfiguration } from 'react-native-pointr';
 
 const SDK_CONFIG: PTRConfiguration = {
@@ -1157,7 +1230,7 @@ export default function MapScreen() {
       style={styles.map}
       sdkConfig={SDK_CONFIG}
       mapWidgetConfig={MAP_CONFIG}
-      command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
+      action={new PTRFocusMapAction('<SITE_EXTERNAL_ID>')}
       onMapWidgetDidEndLoading={(e) => {
         const { command, error } = e.nativeEvent;
         if (error) console.error(`${command} failed:`, error);
@@ -1185,7 +1258,7 @@ import React, { useState } from 'react';
 import { Text, View, TouchableOpacity, StyleSheet } from 'react-native';
 import {
   PTRMapWidget,
-  PTRSiteCommand,
+  PTRFocusMapAction,
   usePointrSdk,
 } from 'react-native-pointr';
 import type { PTRConfiguration } from 'react-native-pointr';
@@ -1218,7 +1291,7 @@ export default function App() {
       {showMap && (
         <PTRMapWidget
           style={StyleSheet.absoluteFill}
-          command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
+          action={new PTRFocusMapAction('<SITE_EXTERNAL_ID>')}
         />
       )}
     </View>
@@ -1232,113 +1305,6 @@ const styles = StyleSheet.create({
 
 ---
 
-## Legacy API
-
-The original imperative API is still fully functional. Existing integrations do not need to migrate.
-
-### `NativeModules.PTRNativePointrLibrary`
-
-All native module methods remain available via `NativeModules`:
-
-```typescript
-import { NativeModules } from 'react-native';
-
-const { PTRNativePointrLibrary } = NativeModules;
-
-// Initialize
-PTRNativePointrLibrary.initialize('<CLIENT_ID>', '<LICENSE_KEY>', '<BASE_URL>', 3);
-
-// Start
-PTRNativePointrLibrary.start((state: string) => {
-  console.log('State:', state);
-});
-
-// Stop
-PTRNativePointrLibrary.stop();
-
-// Permissions
-PTRNativePointrLibrary.requestPermissions();
-PTRNativePointrLibrary.shouldRequestPermissionsAtStartup(true);
-
-// Position
-PTRNativePointrLibrary.getCurrentLocation((location: any) => {
-  if (location) console.log(location);
-});
-
-// Map widget configuration
-PTRNativePointrLibrary.setPointrMapWidgetConfiguration(
-  JSON.stringify({ isExitButtonEnabled: false })
-);
-
-// POIs
-const pois = await PTRNativePointrLibrary.getPois('<SITE_ID>');
-
-// My car
-PTRNativePointrLibrary.isMyCarMarked((error: any) => {
-  if (!error) console.log('Car is marked');
-});
-```
-
-**Native start state strings:**
-
-| Value | Meaning |
-|-------|---------|
-| `"running"` | SDK running successfully |
-| `"failed registration"` | Registration failed |
-| `"failed validation"` | Validation failed |
-| `"failed invalid deep link url"` | Invalid deep link URL |
-| `"failed no internet"` | No internet connection |
-| `"off"` | SDK is off |
-
----
-
-### `showMapWidget(reactTag, command)`
-
-Dispatches a command directly by numeric native view tag.
-
-```typescript
-import { showMapWidget } from 'react-native-pointr';
-import { findNodeHandle } from 'react-native';
-
-const reactTag = findNodeHandle(mapRef.current);
-if (reactTag) {
-  showMapWidget(reactTag, new PTRSiteCommand('<SITE_ID>'));
-}
-```
-
----
-
-### `getPois(siteId)`
-
-```typescript
-import { getPois } from 'react-native-pointr';
-
-const pois = await getPois('<SITE_EXTERNAL_ID>');
-```
-
----
-
-### Legacy command imports
-
-```typescript
-import {
-  LegacyPTRCommand,
-  LegacyPTRSiteCommand,
-  LegacyPTRBuildingCommand,
-  LegacyPTRLevelCommand,
-  LegacyPTRPoiCommand,
-  LegacyPTRPathCommand,
-  LegacyPTRStaticPathCommand,
-  LegacyPTRStaticWayfindingCommand,
-  LegacyPTRMarkMyCarLevelCommand,
-  LegacyPTRMarkMyCarSiteCommand,
-  LegacyPTRShowMyCarSiteCommand,
-  LegacyPTRStartAndFocusCommand,
-} from 'react-native-pointr';
-```
-
----
-
 ## Error Handling
 
 ### Common errors
@@ -1348,8 +1314,8 @@ import {
 | `"Pointr SDK is not initialized. Call initialize() first."` | `start()` or other methods called before `initialize()` | Call `pointrSdk.initialize(config)` first |
 | `"Pointr SDK is not started. Call start() first."` | SDK method called before `start()` completes | Wait for `isStarted` / `PTRState.RUNNING` |
 | `"Pointr SDK is already initialized."` | `initialize()` called twice on the same singleton | Guard with `pointrSdk.isInitialized()` |
-| `"Map widget reference is required."` | `executeMapCommand` called with a null or unmounted ref | Ensure the ref is attached and the component is mounted |
-| `"Invalid map command provided."` | `executeMapCommand` called with a command missing a `type` | Use a proper `PTRCommand` subclass |
+| `"Map widget reference is required."` | `executeMapAction` called with a null or unmounted ref | Ensure the ref is attached and the component is mounted |
+| `"Invalid map command provided."` | `executeMapAction` called with an action missing a `type` | Use a proper `PTRAction` subclass |
 
 ### Best practices
 
@@ -1363,3 +1329,6 @@ import {
 ## License
 
 See the LICENSE file in the package root.
+
+
+