react-native-pointr 9.6.0 → 9.8.0

package/API_REFERENCE.md

@@ -3,287 +3,535 @@
 > **Platform Compatibility:** This API reference is identical for both Android and iOS platforms. All methods, parameters, and behaviors are consistent across platforms.
 
 ## Table of Contents
-- [Native Module API](#native-module-api)
-- [Map Widget Component](#map-widget-component)
-- [Command Types](#command-types)
-- [Utility Functions](#utility-functions)
+- [Quick Start](#quick-start)
+- [PointrSdk Class](#pointrsdk-class)
+- [executeMapCommand](#executemapcommand)
+- [React Hooks](#react-hooks)
+- [PTRMapWidget Component](#ptrmapwidget-component)
+- [Constants & Enums](#constants--enums)
+- [Command Classes](#command-classes)
+- [Types](#types)
 - [Event Listeners](#event-listeners)
+- [Complete Example](#complete-example)
+- [Legacy API](#legacy-api)
+- [Error Handling](#error-handling)
 
 ---
 
-## Native Module API
+## Quick Start
 
-### `PTRNativePointrLibrary`
+The library now exposes two API layers:
 
-The main native module for interacting with the Pointr SDK.
+| 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 |
 
-#### Methods
+**Minimal declarative setup (new API):**
 
-##### `initialize(clientId, licenseKey, baseUrl, logLevel)`
+```tsx
+import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
+import type { PTRConfiguration } from 'react-native-pointr';
 
-Initializes the Pointr SDK with credentials.
+const SDK_CONFIG: PTRConfiguration = {
+  clientId: '<CLIENT_ID>',
+  licenseKey: '<LICENSE_KEY>',
+  baseUrl: 'https://<your-instance>.pointr.cloud',
+};
+
+export default function MapScreen() {
+  return (
+    <PTRMapWidget
+      style={{ flex: 1 }}
+      sdkConfig={SDK_CONFIG}
+      command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
+    />
+  );
+}
+```
+
+---
+
+## PointrSdk Class
+
+`PointrSdk` is a singleton class that wraps the native module and provides a clean, typed interface for SDK lifecycle management.
+
+### Importing
+
+```typescript
+import { PointrSdk, pointrSdk } from 'react-native-pointr';
+
+// Use the pre-created singleton (recommended)
+pointrSdk.initialize({ ... });
+
+// Or obtain the singleton instance explicitly
+const sdk = PointrSdk.getInstance();
+```
+
+### Methods
+
+#### `initialize(config)`
+
+Initializes the SDK. Must be called before `start()`.
 
 **Parameters:**
-- `clientId` (string): Your Pointr client identifier
-- `licenseKey` (string): Your Pointr license key
-- `baseUrl` (string): The Pointr cloud base URL
-- `logLevel` (number): Log level (0-4)
-  - `0`: Verbose
-  - `1`: Debug
-  - `2`: Info
-  - `3`: Warning
-  - `4`: Error
+- `config` (`PTRConfiguration`): SDK credentials and options
+
+**Throws:** `Error` if already initialized or if required fields are missing.
 
-**Example:**
 ```typescript
-import { NativeModules } from 'react-native';
+import { pointrSdk, PTRLogLevel } from 'react-native-pointr';
 
-NativeModules.PTRNativePointrLibrary.initialize(
-  "client-id",
-  "license-key",
-  "https://your-instance.pointr.cloud",
-  3
-);
+pointrSdk.initialize({
+  clientId: '<CLIENT_ID>',
+  licenseKey: '<LICENSE_KEY>',
+  baseUrl: 'https://<your-instance>.pointr.cloud',
+  logLevel: PTRLogLevel.WARNING, // optional, defaults to ERROR
+});
 ```
 
 ---
 
-##### `start(callback)`
+#### `start(callback?)`
 
-Starts the Pointr SDK.
+Starts the SDK. SDK must be initialized first.
 
 **Parameters:**
-- `callback` (function): Callback function that receives the Pointr state as a string
+- `callback` (`PTRStateCallback`, optional): Receives the native state string when the SDK is running.
+
+**Throws:** `Error` if not initialized.
 
-**Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.start((state: string) => {
-  console.log(`Pointr state: ${state}`);
+pointrSdk.start((state) => {
+  console.log('Native state:', state); // e.g. "running"
 });
 ```
 
-**Possible States:**
-- `"running"` - SDK is 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
+---
+
+#### `stop()`
+
+Stops the SDK when it is in the `RUNNING` state.
+
+```typescript
+pointrSdk.stop();
+```
 
 ---
 
-##### `stop()`
+#### `getState()`
 
-Stops the Pointr SDK.
+Returns the current `PTRState` enum value.
 
-**Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.stop();
+const state: PTRState = pointrSdk.getState();
 ```
 
 ---
 
-##### `requestPermissions()`
+#### `isInitialized()`
 
-Requests necessary permissions (location, bluetooth, etc.).
+Returns `true` if the SDK has been initialized (any state other than `NOT_INITIALIZED`).
 
-**Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.requestPermissions();
+if (pointrSdk.isInitialized()) { ... }
 ```
 
 ---
 
-##### `shouldRequestPermissionsAtStartup(shouldRequest)`
+#### `isStarted()`
 
-Sets whether permissions should be requested automatically at startup.
+Returns `true` only if the SDK is in the `RUNNING` state.
 
-**Parameters:**
-- `shouldRequest` (boolean): True to request permissions automatically
+```typescript
+if (pointrSdk.isStarted()) { ... }
+```
+
+---
+
+#### `getConfig()`
+
+Returns the `PTRConfiguration` passed to `initialize()`, or `null` if not yet initialized.
+
+```typescript
+const config = pointrSdk.getConfig();
+```
+
+---
+
+#### `getCurrentLocation()`
+
+Returns a `Promise<any | null>` with the last known calculated position, or `null` if unavailable.
+
+The resolved object contains the raw native payload with these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `latitude` | number | Latitude |
+| `longitude` | number | Longitude |
+| `levelIndex` | number | Level index |
+| `siteInternalIdentifier` | string | Site internal ID |
+| `siteExternalIdentifier` | string | Site external ID |
+| `buildingInternalIdentifier` | string | Building internal ID |
+| `buildingExternalIdentifier` | string | Building external ID |
+| `accuracy` | number | Accuracy in meters (optional) |
+| `heading` | number | Heading in degrees (optional, only when accuracy is high) |
 
-**Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.shouldRequestPermissionsAtStartup(true);
+const loc = await pointrSdk.getCurrentLocation();
+if (loc) {
+  console.log(loc.latitude, loc.longitude, loc.levelIndex);
+}
 ```
 
 ---
 
-##### `getCurrentLocation(callback)`
+#### `setMapWidgetConfiguration(config)`
 
-Gets the current calculated position.
+Applies map widget UI settings. Must be called before the `PTRMapWidget` renders to take effect.
 
 **Parameters:**
-- `callback` (function): Callback function that receives location data or null
+- `config` (`PTRMapWidgetConfiguration`): UI feature toggles
 
-**Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.getCurrentLocation((location) => {
-  if (location) {
-    console.log('Site:', location.siteExternalIdentifier);
-    console.log('Building:', location.buildingExternalIdentifier);
-    console.log('Level:', location.levelIndex);
-    console.log('Coordinates:', location.latitude, location.longitude);
-  }
+pointrSdk.setMapWidgetConfiguration({
+  isLevelSelectorEnabled: true,
+  isJoystickEnabled: true,
+  isExitButtonEnabled: false,
 });
 ```
 
-**Location Object:**
-- `siteInternalIdentifier` (string)
-- `siteExternalIdentifier` (string)
-- `buildingInternalIdentifier` (string)
-- `buildingExternalIdentifier` (string)
-- `levelIndex` (number)
-- `latitude` (number)
-- `longitude` (number)
-- `accuracy` (number)
-- `heading` (number) - Only present if heading accuracy is high
+---
+
+#### `onPositionUpdate(callback)`
+
+Subscribes to `OnPositionManagerCalculatedLocation` events. Returns a subscription object with a `.remove()` method.
+
+```typescript
+const sub = pointrSdk.onPositionUpdate((pos) => {
+  console.log(pos);
+});
+// later:
+sub.remove();
+```
 
 ---
 
-##### `isMyCarMarked(callback)`
+#### `onBuildingClick(callback)`
 
-Checks if a "My Car" location has been saved.
+Subscribes to `OnBuildingClicked` events.
 
-**Parameters:**
-- `callback` (function): Callback with no arguments if marked, error message if not
+```typescript
+const sub = pointrSdk.onBuildingClick((event) => {
+  console.log(event.internalIdentifier, event.title);
+});
+```
+
+---
+
+#### `onSiteClick(callback)`
+
+Subscribes to `OnSiteClicked` events.
 
-**Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.isMyCarMarked((error) => {
-  if (!error) {
-    console.log('My car location is marked');
-  } else {
-    console.log('No saved location:', error);
-  }
+const sub = pointrSdk.onSiteClick((event) => {
+  console.log(event.internalIdentifier, event.title);
+});
+```
+
+---
+
+#### `onGeofenceEvent(callback)`
+
+Subscribes to `OnGeofenceEvent` events.
+
+```typescript
+const sub = pointrSdk.onGeofenceEvent((event) => {
+  console.log(event.eventType, event.geofence?.name);
 });
 ```
 
 ---
 
-##### `setPointrMapWidgetConfiguration(configJson)`
+#### `getEventEmitter()`
+
+Returns the underlying `NativeEventEmitter` for advanced subscription use cases.
+
+```typescript
+const emitter = pointrSdk.getEventEmitter();
+```
+
+---
+
+#### `getNativeModule()`
+
+Returns the raw `NativeModules.PTRNativePointrLibrary` reference for advanced use cases.
+
+```typescript
+const native = pointrSdk.getNativeModule();
+native.requestPermissions();
+```
+
+---
+
+## executeMapCommand
 
-Sets the map widget configuration.
+A convenience function that resolves `findNodeHandle` internally and dispatches a command to the native map widget.
+
+**Import:**
+```typescript
+import { executeMapCommand } from 'react-native-pointr';
+```
+
+**Signature:**
+```typescript
+function executeMapCommand(
+  mapRef: React.RefObject<any> | any,
+  command: PTRCommand
+): void
+```
 
 **Parameters:**
-- `configJson` (string): JSON string with configuration options
+- `mapRef`: A React ref (or any object with a `.current` property) pointing to the rendered `PTRMapWidget`.
+- `command`: Any `PTRCommand` subclass instance.
+
+**Throws:** `Error` if `mapRef` is null, the native view tag cannot be resolved, or the command is invalid.
 
 **Example:**
 ```typescript
-NativeModules.PTRNativePointrLibrary.setPointrMapWidgetConfiguration(
-  JSON.stringify({
-    isExitButtonEnabled: false,
-    isCompassEnabled: true,
-    isSearchBarEnabled: true,
-    isLevelSelectorEnabled: true,
-    isMyCarButtonEnabled: true
-  })
-);
-```
+import { useRef } from 'react';
+import { PTRMapWidget, PTRPoiCommand, executeMapCommand } from 'react-native-pointr';
+
+function MyMap() {
+  const mapRef = useRef(null);
 
-**Configuration Options:**
-- `isExitButtonEnabled` (boolean): Show/hide exit button
-- `isCompassEnabled` (boolean): Show/hide compass
-- `isSearchBarEnabled` (boolean): Show/hide search bar
-- `isLevelSelectorEnabled` (boolean): Show/hide level selector
-- `isMyCarButtonEnabled` (boolean): Show/hide my car button
-- `isRouteFooterViewEnabled` (boolean): Show/hide route footer
+  const navigateToLobby = () => {
+    executeMapCommand(mapRef, new PTRPoiCommand('<SITE_ID>', 'Lobby'));
+  };
+
+  return <PTRMapWidget ref={mapRef} style={{ flex: 1 }} />;
+}
+```
 
 ---
 
-##### `getPois(siteId)`
+## React Hooks
 
-Retrieves all Points of Interest (POIs) for a specific site.
+All hooks are exported from `react-native-pointr`.
+
+### `usePointrSdk(config?)`
+
+Manages SDK initialization and startup. When `config` is provided the hook initializes and starts the SDK automatically on mount.
 
 **Parameters:**
-- `siteId` (string): Site external identifier
+- `config` (`PTRConfiguration`, optional): When supplied, triggers `initialize` + `start` automatically.
 
-**Returns:** Promise<PTRPoi[]> - Array of POI objects
+**Returns:**
+```typescript
+{
+  sdk: PointrSdk;        // The singleton SDK instance
+  state: PTRState;       // Current SDK state
+  isInitialized: boolean;
+  isStarted: boolean;
+  error: Error | null;
+}
+```
 
 **Example:**
 ```typescript
-import { getPois } from 'react-native-pointr';
+import { usePointrSdk } from 'react-native-pointr';
 
-try {
-  const pois = await getPois('site-external-id');
-  console.log(`Found ${pois.length} POIs`);
-  
-  pois.forEach(poi => {
-    console.log(`${poi.name} (${poi.typeCode})`);
-    console.log(`  Location: ${poi.position.lat}, ${poi.position.lon}`);
-    console.log(`  Level: ${poi.position.lvl}`);
+function App() {
+  const { sdk, isStarted, state, error } = usePointrSdk({
+    clientId: '<CLIENT_ID>',
+    licenseKey: '<LICENSE_KEY>',
+    baseUrl: 'https://<your-instance>.pointr.cloud',
   });
-} catch (error) {
-  console.error('Failed to get POIs:', error);
+
+  // sdk is available immediately; isStarted turns true once the SDK is running
 }
 ```
 
-**POI Object Structure:**
+---
+
+### `usePointrPosition(enabled?)`
+
+Listens to live position updates from the SDK.
+
+**Parameters:**
+- `enabled` (boolean, default: `true`): Set to `false` to pause the subscription without unmounting.
+
+**Returns:** The raw native position event or `null`. The payload fields match those described under [`getCurrentLocation()`](#getcurrentlocation).
+
 ```typescript
-interface PTRPoi {
-  identifier: string;              // Internal ID
-  externalIdentifier: string;      // External ID
-  name: string;                    // Display name
-  typeCode: string;                // POI type code
-  position: PTRPosition;           // Geographic position
-  geometry: PTRGeometry;           // Shape data
-  attributes: PTRPoiAttributes;    // Metadata
+import { usePointrPosition } from 'react-native-pointr';
+
+function PositionView() {
+  const position = usePointrPosition();
+  if (position) {
+    console.log(position.latitude, position.longitude, position.levelIndex);
+  }
 }
+```
 
-interface PTRPosition {
-  lat: number;                     // Latitude
-  lon: number;                     // Longitude
-  isValid: boolean;                // Position validity
-  sid: string;                     // Site ID
-  bid: string;                     // Building ID
-  lvl: number;                     // Level index
+---
+
+### `usePointrPois(siteId?)`
+
+Fetches and manages the POI list for a given site.
+
+**Parameters:**
+- `siteId` (string, optional): External site identifier. POIs are fetched when this value changes.
+
+**Returns:**
+```typescript
+{
+  pois: PTRPoi[];
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
 }
+```
 
-interface PTRPoiAttributes {
-  logo?: string;                   // Logo URL
-  images?: string[];               // Image URLs
-  description?: string;            // Description text
-  extra?: Record<string, any>;     // Custom data
-  [key: string]: any;              // Other attributes
+```typescript
+import { usePointrPois } from 'react-native-pointr';
+
+function PoiList() {
+  const { pois, loading, error } = usePointrPois('<SITE_ID>');
 }
 ```
 
 ---
 
-## Map Widget Component
+### `usePointrGeofence(callback)`
 
-### `PTRMapWidget`
+Subscribes to geofence events for the lifetime of the component.
 
-A native UI component that displays the Pointr map.
+**Parameters:**
+- `callback` (`(event: PTRGeofenceEvent) => void`): Called on every geofence enter/exit event.
 
-**Props:**
-- `style` (ViewStyle): Component styling
-- `onMapWidgetDidEndLoading` (function): Callback when map finishes loading with a command
-- `ref` (ref): Reference to the component for sending commands
+```typescript
+import { usePointrGeofence } from 'react-native-pointr';
 
-**Example:**
+usePointrGeofence((event) => {
+  console.log(event.eventType, event.geofence?.name);
+});
+```
+
+---
+
+### `usePointrBuildingClick(callback)`
+
+Subscribes to building-tap events on the map.
+
+**Parameters:**
+- `callback` (`(event: PTRBuildingClickEvent) => void`)
+
+```typescript
+import { usePointrBuildingClick } from 'react-native-pointr';
+
+usePointrBuildingClick((event) => {
+  console.log('Building tapped:', event.internalIdentifier, event.title);
+});
+```
+
+---
+
+### `usePointrSiteClick(callback)`
+
+Subscribes to site-tap events on the map.
+
+**Parameters:**
+- `callback` (`(event: PTRSiteClickEvent) => void`)
+
+```typescript
+import { usePointrSiteClick } from 'react-native-pointr';
+
+usePointrSiteClick((event) => {
+  console.log('Site tapped:', event.internalIdentifier, event.title);
+});
+```
+
+---
+
+## PTRMapWidget Component
+
+`PTRMapWidget` is a typed React component (with `forwardRef`) that wraps the native map view.
+
+**Import:**
 ```typescript
-import { requireNativeComponent } from 'react-native';
+import { PTRMapWidget } from 'react-native-pointr';
+import type { PTRMapWidgetProps } from 'react-native-pointr';
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `style` | `ViewStyle` | Component styling |
+| `command` | `PTRCommand` | Declarative command 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 |
+| `onWayfindingEvent` | `(event: NativeSyntheticEvent<PTRWayfindingEvent>) => void` | Fired during wayfinding (start / end / cancel) |
+
+### Declarative usage (recommended)
+
+Pass `command`, `sdkConfig`, and `mapWidgetConfig` as props so the widget handles initialization automatically:
+
+```tsx
+import { PTRMapWidget, PTRSiteCommand } from 'react-native-pointr';
+import type { PTRConfiguration, PTRMapWidgetConfiguration } from 'react-native-pointr';
+
+const SDK_CONFIG: PTRConfiguration = {
+  clientId: '<CLIENT_ID>',
+  licenseKey: '<LICENSE_KEY>',
+  baseUrl: 'https://<your-instance>.pointr.cloud',
+};
+
+const MAP_CONFIG: PTRMapWidgetConfiguration = {
+  isLevelSelectorEnabled: true,
+  isJoystickEnabled: true,
+  isExitButtonEnabled: false,
+};
 
-interface PTRMapWidgetProps {
-  style?: any;
-  onMapWidgetDidEndLoading?: (event: NativeSyntheticEvent<any>) => void;
+function MapScreen() {
+  return (
+    <PTRMapWidget
+      style={{ flex: 1 }}
+      sdkConfig={SDK_CONFIG}
+      mapWidgetConfig={MAP_CONFIG}
+      command={new PTRSiteCommand('<SITE_ID>')}
+      onMapWidgetDidEndLoading={(e) => console.log('Loaded', e.nativeEvent)}
+      onWayfindingEvent={(e) => console.log('Navigation', e.nativeEvent)}
+    />
+  );
 }
+```
 
-const PTRMapWidget = requireNativeComponent<PTRMapWidgetProps>('PTRMapWidget');
+### Imperative usage
 
-function MyComponent() {
-  const ref = useRef(null);
+Use `ref` + `executeMapCommand` to dispatch commands after mount:
 
-  const handleLoadingComplete = (event) => {
-    const { command, siteExternalIdentifier, error } = event.nativeEvent;
-    console.log('Map loaded:', command, siteExternalIdentifier, error);
+```tsx
+import { useRef } from 'react';
+import { PTRMapWidget, PTRPoiCommand, executeMapCommand } from 'react-native-pointr';
+
+function MapScreen() {
+  const mapRef = useRef(null);
+
+  const goToLobby = () => {
+    executeMapCommand(mapRef, new PTRPoiCommand('<SITE_ID>', 'Lobby'));
   };
 
   return (
-    <PTRMapWidget 
-      ref={ref}
+    <PTRMapWidget
+      ref={mapRef}
       style={{ flex: 1 }}
-      onMapWidgetDidEndLoading={handleLoadingComplete}
+      onMapWidgetDidEndLoading={(e) => {
+        const { command, error } = e.nativeEvent;
+        if (error) console.error(command, error);
+      }}
     />
   );
 }
@@ -291,464 +539,588 @@ function MyComponent() {
 
 ---
 
-## Command Types
+## Constants & Enums
 
-### `PTRCommandType`
+All constants and enums are exported from `react-native-pointr`.
 
-Enum of supported command types.
+### `PTRLogLevel`
 
 ```typescript
-enum PTRCommandType {
-  SITE = "site",
-  BUILDING = "building",
-  LEVEL = "level",
-  POI = "poi",
-  PATH = "path",
-  STATIC_PATH = "staticPath",
-  MARK_MY_CAR_LEVEL = "markMyCarForLevel",
-  MARK_MY_CAR_SITE = "markMyCarForSite",
-  SHOW_MY_CAR_SITE = "showMyCarForSite",
-  START_AND_FOCUS = "startAndFocus"
+enum PTRLogLevel {
+  VERBOSE = 0,
+  DEBUG   = 1,
+  INFO    = 2,
+  WARNING = 3,
+  ERROR   = 4,  // default
+  NONE    = 5,
 }
 ```
 
 ---
 
-### Command Classes
+### `PTRState`
 
-#### `PTRSiteCommand`
+Tracks the lifecycle state of the SDK as managed by `PointrSdk`.
 
-Shows a specific site on the map.
+```typescript
+enum PTRState {
+  NOT_INITIALIZED = 'NOT_INITIALIZED',
+  INITIALIZING    = 'INITIALIZING',
+  INITIALIZED     = 'INITIALIZED',
+  STARTING        = 'STARTING',
+  RUNNING         = 'RUNNING',
+  STOPPED         = 'STOPPED',
+  ERROR           = 'ERROR',
+}
+```
+
+---
+
+### `PTRCommandType`
 
-**Constructor:**
 ```typescript
-new PTRSiteCommand(site: string)
+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',
+}
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
+---
+
+### `PTRAnimationType`
+
+Animation type constants for map transitions.
 
-**Example:**
 ```typescript
-import { PTRSiteCommand } from 'react-native-pointr/src/PTRCommand';
-import { showMapWidget } from 'react-native-pointr/src/PTRMapWidgetUtils';
+enum PTRAnimationType {
+  NONE  = 'none',
+  FADE  = 'fade',
+  SLIDE = 'slide',
+  ZOOM  = 'zoom',
+}
+```
+
+> **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.
+
+---
 
-const command = new PTRSiteCommand("site-external-id");
-showMapWidget(reactTag, command);
+### `PTRGeofenceEventType`
+
+```typescript
+enum PTRGeofenceEventType {
+  ENTER = 'enter',
+  EXIT  = 'exit',
+}
 ```
 
+> **Note:** `DWELL` is not emitted by the native SDK on either platform.
+
 ---
 
-#### `PTRBuildingCommand`
+### `PTREvents`
 
-Shows a specific building within a site.
+Event name constants used internally and available for direct `NativeEventEmitter` subscriptions.
 
-**Constructor:**
 ```typescript
-new PTRBuildingCommand(site: string, building: string)
+const PTREvents = {
+  ON_POSITION_CALCULATED:       'OnPositionManagerCalculatedLocation',
+  ON_BUILDING_CLICKED:          'OnBuildingClicked',
+  ON_SITE_CLICKED:              'OnSiteClicked',
+  ON_GEOFENCE_EVENT:            'OnGeofenceEvent',
+  ON_WAYFINDING_EVENT:          'onWayfindingEvent',
+  ON_MAP_WIDGET_DID_END_LOADING:'onMapWidgetDidEndLoading',
+}
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `building` (string): Building external identifier
+---
+
+### `PTRErrorMessages`
+
+Pre-defined error message strings thrown by `PointrSdk` and `executeMapCommand`.
 
-**Example:**
 ```typescript
-const command = new PTRBuildingCommand("site-id", "building-id");
-showMapWidget(reactTag, command);
+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.',
+}
 ```
 
 ---
 
-#### `PTRLevelCommand`
+## Command Classes
 
-Shows a specific level within a building.
+All command classes are exported from `react-native-pointr`.
+
+### `PTRSiteCommand`
+
+Shows a specific site on the map.
 
-**Constructor:**
 ```typescript
-new PTRLevelCommand(site: string, building: string, level: number)
+new PTRSiteCommand(site: string)
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `building` (string): Building external identifier
-- `level` (number): Level index
-
-**Example:**
 ```typescript
-const command = new PTRLevelCommand("site-id", "building-id", 1);
-showMapWidget(reactTag, command);
+new PTRSiteCommand('<SITE_EXTERNAL_ID>')
 ```
 
 ---
 
-#### `PTRPoiCommand`
+### `PTRBuildingCommand`
 
-Shows and focuses on a specific POI (Point of Interest).
+Shows a specific building within a site.
 
-**Constructor:**
 ```typescript
-new PTRPoiCommand(site: string, poi: string)
+new PTRBuildingCommand(site: string, building: string)
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `poi` (string): POI external identifier or name
+---
+
+### `PTRLevelCommand`
+
+Shows a specific level within a building.
 
-**Example:**
 ```typescript
-const command = new PTRPoiCommand("site-id", "Lobby");
-showMapWidget(reactTag, command);
+new PTRLevelCommand(site: string, building: string, level: number)
 ```
 
 ---
 
-#### `PTRPathCommand`
+### `PTRPoiCommand`
 
-Shows navigation path from current location to a POI.
+Focuses the map on a specific POI.
 
-**Constructor:**
 ```typescript
-new PTRPathCommand(site: string, poi: string)
+new PTRPoiCommand(site: string, poi: string)
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `poi` (string): Destination POI external identifier
+- `poi`: POI external identifier or name.
+
+---
+
+### `PTRPathCommand`
+
+Shows a navigation path from the user's current location to a POI.
 
-**Example:**
 ```typescript
-const command = new PTRPathCommand("site-id", "Lobby");
-showMapWidget(reactTag, command);
+new PTRPathCommand(site: string, poi: string)
 ```
 
 ---
 
-#### `PTRStaticPathCommand`
+### `PTRStaticPathCommand`
 
 Shows a static path between two POIs.
 
-**Constructor:**
 ```typescript
 new PTRStaticPathCommand(site: string, fromPoi: string, toPoi: string)
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `fromPoi` (string): Starting POI external identifier
-- `toPoi` (string): Destination POI external identifier
+---
+
+### `PTRStaticWayfindingCommand`
+
+Initiates static wayfinding between two POIs.
 
-**Example:**
 ```typescript
-const command = new PTRStaticPathCommand("site-id", "Lobby", "Cafeteria");
-showMapWidget(reactTag, command);
+new PTRStaticWayfindingCommand(site: string, sourcePoi: string, destinationPoi: string)
 ```
 
 ---
 
-#### `PTRMarkMyCarLevelCommand`
+### `PTRMarkMyCarLevelCommand`
 
-Marks "My Car" location on a specific level.
+Marks the "My Car" location at a specific level.
 
-**Constructor:**
 ```typescript
 new PTRMarkMyCarLevelCommand(
   site: string,
   building: string,
   level: number,
-  shouldShowPopup?: boolean,
-  animationType?: number
+  shouldShowPopup?: boolean,   // default: true
+  animationType?: number       // default: 1
 )
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `building` (string): Building external identifier
-- `level` (number): Level index
-- `shouldShowPopup` (boolean): Show popup after marking (default: true)
-- `animationType` (number): Animation type (default: 1)
-  - `0`: None
-  - `1`: Standard
-  - `2`: Fly over
-
-**Example:**
-```typescript
-const command = new PTRMarkMyCarLevelCommand("site-id", "building-id", 1, true, 1);
-showMapWidget(reactTag, command);
-```
-
 ---
 
-#### `PTRMarkMyCarSiteCommand`
+### `PTRMarkMyCarSiteCommand`
 
-Marks "My Car" location at the current position within a site.
+Marks the "My Car" location at the current position within a site.
 
-**Constructor:**
 ```typescript
 new PTRMarkMyCarSiteCommand(
   site: string,
-  shouldShowPopup?: boolean,
-  animationType?: number
+  shouldShowPopup?: boolean,   // default: true
+  animationType?: number       // default: 1
 )
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `shouldShowPopup` (boolean): Show popup after marking (default: true)
-- `animationType` (number): Animation type (default: 1)
-
-**Example:**
-```typescript
-const command = new PTRMarkMyCarSiteCommand("site-id", true, 1);
-showMapWidget(reactTag, command);
-```
-
 ---
 
-#### `PTRShowMyCarSiteCommand`
+### `PTRShowMyCarSiteCommand`
 
-Shows the saved "My Car" location.
+Shows the previously saved "My Car" location.
 
-**Constructor:**
 ```typescript
 new PTRShowMyCarSiteCommand(
   site: string,
-  shouldShowPopup?: boolean,
-  animationType?: number
+  shouldShowPopup?: boolean,   // default: true
+  animationType?: number       // default: 1
 )
 ```
 
-**Parameters:**
-- `site` (string): Site external identifier
-- `shouldShowPopup` (boolean): Show popup (default: true)
-- `animationType` (number): Animation type (default: 1)
-
-**Example:**
-```typescript
-const command = new PTRShowMyCarSiteCommand("site-id", true, 1);
-showMapWidget(reactTag, command);
-```
-
 ---
 
-#### `PTRStartAndFocusCommand`
+### `PTRStartAndFocusCommand`
 
-Initializes the SDK and focuses on a location in a single command.
+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.
+
+> **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.
 
-**Constructor:**
 ```typescript
 new PTRStartAndFocusCommand(
   clientId: string,
   licenseKey: string,
   baseUrl: string,
-  logLevel: number,
+  logLevel: number,             // default: 4 (ERROR)
   command: PTRSiteCommand | PTRBuildingCommand | PTRLevelCommand | PTRPoiCommand
 )
 ```
 
-**Parameters:**
-- `clientId` (string): Client identifier
-- `licenseKey` (string): License key
-- `baseUrl` (string): Base URL
-- `logLevel` (number): Log level (0-4)
-- `command` (PTRCommand): Focus command to execute after initialization
-
-**Example:**
 ```typescript
-const focusCommand = new PTRSiteCommand("site-id");
-const command = new PTRStartAndFocusCommand(
-  "client-id",
-  "license-key",
-  "https://your-instance.pointr.cloud",
-  3,
-  focusCommand
+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(reactTag, command);
+showMapWidget(findNodeHandle(mapRef.current), cmd);
 ```
 
 ---
 
-## Utility Functions
+### Type guards
 
-### `showMapWidget(reactTag, command)`
+```typescript
+import {
+  isPTRSiteCommand,
+  isPTRBuildingCommand,
+  isPTRLevelCommand,
+  isPTRPoiCommand,
+  isPTRPathCommand,
+  isPTRStaticPathCommand,
+} from 'react-native-pointr';
+```
 
-Sends a command to the map widget.
+---
 
-**Parameters:**
-- `reactTag` (number): The native view tag obtained from `findNodeHandle()`
-- `command` (PTRCommand | PTRStartAndFocusCommand): The command to execute
+## Types
+
+All types are exported from `react-native-pointr`.
+
+### `PTRConfiguration`
 
-**Example:**
 ```typescript
-import { findNodeHandle } from 'react-native';
-import { showMapWidget } from 'react-native-pointr/src/PTRMapWidgetUtils';
-import { PTRSiteCommand } from 'react-native-pointr/src/PTRCommand';
-
-const showSite = () => {
-  const reactTag = findNodeHandle(mapWidgetRef.current);
-  if (reactTag) {
-    const command = new PTRSiteCommand("site-id");
-    showMapWidget(reactTag, command);
-  }
-};
+interface PTRConfiguration {
+  readonly clientId: string;
+  readonly licenseKey: string;
+  readonly baseUrl: string;
+  readonly logLevel?: PTRLogLevel; // default: PTRLogLevel.ERROR
+}
 ```
 
 ---
 
-## Event Listeners
+### `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.
 
-### Position Manager Events
+```typescript
+interface PTRMapWidgetConfiguration {
+  readonly isLevelSelectorEnabled?: boolean;
+  readonly isLoadingViewEnabled?: boolean;
+  readonly isMapTrackingModeButtonEnabled?: boolean;
+  readonly isExitButtonEnabled?: boolean;
+  readonly isSplashScreenEnabled?: boolean;
+  readonly isOnboardingEnabled?: boolean;
+  readonly isJoystickEnabled?: boolean;
+  readonly isToastMessagesEnabled?: boolean;
+  readonly isInfoButtonEnabled?: boolean;
+  readonly isLocationIndicatorEnabled?: boolean;
+  readonly shouldFocusOnFirstUserPosition?: boolean;
+  readonly isQuickAccessEnabled?: boolean;
+  readonly isAppBannerEnabled?: boolean;
+}
+```
 
-Subscribe to position updates using the native event emitter.
+---
 
-**Events:**
-- `OnPositionManagerCalculatedLocation`: Fired when a new position is calculated
-- `OnBuildingClicked`: Fired when a building is tapped on the map
-- `OnSiteClicked`: Fired when a site is tapped on the map
-- `OnGeofenceEvent`: Fired when a geofence enter/exit event occurs
+### `PTRPosition`
 
-**Example:**
 ```typescript
-import { NativeEventEmitter, NativeModules } from 'react-native';
+interface PTRPosition {
+  lat: number;      // Latitude
+  lon: number;      // Longitude
+  isValid: boolean;
+  sid: string;      // Site identifier
+  bid: string;      // Building identifier
+  lvl: number;      // Level index
+}
+```
 
-const PTREventEmitter = NativeModules.PTRNativePointrLibrary;
-const eventEmitter = new NativeEventEmitter(PTREventEmitter);
+---
 
-// Listen to position updates
-const subscription = eventEmitter.addListener(
-  'OnPositionManagerCalculatedLocation',
-  (location) => {
-    console.log('New position:', location);
-  }
-);
+### `PTRPositionEvent`
 
-// Listen to building clicks
-const buildingSubscription = eventEmitter.addListener(
-  'OnBuildingClicked',
-  (building) => {
-    console.log('Building clicked:', building);
-  }
-);
+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`.
 
-// Listen to geofence events
-const geofenceSubscription = eventEmitter.addListener(
-  'OnGeofenceEvent',
-  (geofenceEvent) => {
-    console.log('Geofence event:', geofenceEvent);
-  }
-);
+---
+
+### `PTRPoi`
+
+```typescript
+interface PTRPoi {
+  identifier: string;
+  externalIdentifier: string;
+  name: string;
+  typeCode: string;
+  position: PTRPosition;
+  geometry: PTRGeometry;
+  attributes: PTRPoiAttributes;
+}
 
-// Clean up
-subscription.remove();
-buildingSubscription.remove();
-geofenceSubscription.remove();
+interface PTRPoiAttributes {
+  logo?: string;
+  images?: string[];
+  description?: string;
+  extra?: Record<string, any>;
+  [key: string]: any;
+}
 ```
 
 ---
 
-### Geofence Events
+### `PTRGeometry`
 
-The `OnGeofenceEvent` is fired when the user enters or exits a geofence area. This feature requires the Pointr SDK to be running and geofence listeners are automatically registered when calling `start()`.
+Union of all supported geometry shapes.
 
-**Event Structure:**
 ```typescript
-{
-  eventType: 'enter' | 'exit',       // Event type
-  timestamp?: number,                // Unix timestamp in milliseconds (iOS only)
-  geofence: {
-    id: string,                      // Internal geofence ID
-    externalId: string,              // External geofence ID
-    name: string,                    // Geofence name
-    geofenceType: 'beacon' | 'gps',  // Type of geofence
-    position: {
-      latitude: number,              // Geofence latitude
-      longitude: number              // Geofence longitude
-    }
-  },
-  geofenceNotification?: {           // Optional notification data
-    id: string,
-    message: string,
-    timestamp: number                // Unix timestamp in milliseconds (Android)
-                                     // or milliseconds (iOS)
-  }
+type PTRGeometry =
+  | PTRGeoPoint
+  | PTRGeoPolygon
+  | PTRGeoMultiPoint
+  | PTRGeoLineString
+  | PTRGeoMultiLineString
+  | PTRGeoMultiPolygon
+  | PTRGeoCircle;
+```
+
+| Type | Key fields |
+|------|-----------|
+| `PTRGeoPoint` | `type: 'Point'`, `lat`, `lon` |
+| `PTRGeoPolygon` | `type: 'Polygon'`, `outer: PTRGeoPoint[]`, `inners: PTRGeoPoint[][]` |
+| `PTRGeoMultiPoint` | `type: 'MultiPoint'`, `points: PTRGeoPoint[]` |
+| `PTRGeoLineString` | `type: 'LineString'`, `points: PTRGeoPoint[]` |
+| `PTRGeoMultiLineString` | `type: 'MultiLineString'`, `lines: PTRGeoPoint[][]` |
+| `PTRGeoMultiPolygon` | `type: 'MultiPolygon'`, `polygons: PTRGeoPolygon[]` |
+| `PTRGeoCircle` | `type: 'Circle'`, `center: PTRGeoPoint`, `radius: number` |
+
+---
+
+### `PTRWayfindingEvent`
+
+Fired via `onWayfindingEvent` prop on `PTRMapWidget`.
+
+```typescript
+interface PTRWayfindingEvent {
+  type: -1 | 0 | 1;  // -1 Cancelled, 0 Started, 1 Ended
+  poi: PTRPoi;        // Destination POI
 }
 ```
 
-**Platform Differences:**
-- iOS: Includes `timestamp` field at the root level with milliseconds since epoch
-- Android: Timestamp only available in `geofenceNotification` object
-- Both platforms support beacon and GPS geofence types
+| `type` value | Meaning |
+|-----|---------|
+| `-1` | Wayfinding cancelled by user |
+| `0` | Wayfinding started |
+| `1` | Wayfinding ended (completed or dismissed) |
+
+---
+
+### `PTRMapCommandResponse`
+
+Payload of the `onMapWidgetDidEndLoading` event.
 
-**Example:**
 ```typescript
-import React, { useEffect } from 'react';
-import { NativeEventEmitter, NativeModules } from 'react-native';
+interface PTRMapCommandResponse {
+  readonly command: string;
+  readonly siteExternalIdentifier?: string;
+  readonly error?: string;
+}
+```
+
+---
+
+### `PTRGeofenceEvent`
 
-function GeofenceMonitor() {
-  useEffect(() => {
-    const eventEmitter = new NativeEventEmitter(
-      NativeModules.PTRNativePointrLibrary
-    );
-    
-    const geofenceSubscription = eventEmitter.addListener(
-      'OnGeofenceEvent',
-      (geofenceEvent) => {
-        console.log(`Geofence ${geofenceEvent.eventType}: ${geofenceEvent.geofence.name}`);
-        console.log(`Type: ${geofenceEvent.geofence.geofenceType}`);
-        console.log(`Location: ${geofenceEvent.geofence.position.latitude}, ${geofenceEvent.geofence.position.longitude}`);
-        
-        if (geofenceEvent.geofenceNotification) {
-          console.log(`Notification: ${geofenceEvent.geofenceNotification.message}`);
-        }
-        
-        if (geofenceEvent.timestamp) {
-          console.log(`Timestamp: ${new Date(geofenceEvent.timestamp).toISOString()}`);
-        }
-      }
-    );
-    
-    return () => {
-      geofenceSubscription.remove();
-    };
-  }, []);
-  
-  return null;
-}
-```
-
----
-
-### Map Widget Load Events
-
-The `onMapWidgetDidEndLoading` prop receives events when commands complete.
-
-**Event Object:**
 ```typescript
-{
-  command: string,           // Command type that was executed
-  siteExternalIdentifier?: string,
-  buildingExternalIdentifier?: string,
-  levelIndex?: number,
-  poiExternalIdentifier?: string,
-  error?: string            // Error message if command failed
+interface PTRGeofenceEvent {
+  readonly eventType: 'enter' | 'exit';
+  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
+}
+
+interface PTRGeofence {
+  readonly id: 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;
+  };
+}
+
+interface PTRGeofenceNotification {
+  readonly id: string;
+  readonly message: string;
+  readonly timestamp: number;          // milliseconds
 }
 ```
 
-**Example:**
+**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
-const handleMapWidgetDidEndLoading = (event) => {
-  const { command, siteExternalIdentifier, error } = event.nativeEvent;
-  
-  if (error) {
-    console.error(`Command ${command} failed:`, error);
-  } else {
-    console.log(`Command ${command} completed for site:`, siteExternalIdentifier);
-  }
-};
+interface PTRBuildingClickEvent {
+  readonly internalIdentifier: string;
+  readonly externalIdentifier: string;
+  readonly title: string;
+}
 
+interface PTRSiteClickEvent {
+  readonly internalIdentifier: string;
+  readonly externalIdentifier: string;
+  readonly title: string;
+}
+```
+
+---
+
+## Event Listeners
+
+There are three ways to subscribe to SDK events, in order of preference:
+
+### 1. React Hooks (recommended)
+
+```typescript
+import {
+  usePointrPosition,
+  usePointrGeofence,
+  usePointrBuildingClick,
+  usePointrSiteClick,
+} from 'react-native-pointr';
+
+// Position
+const position = usePointrPosition();
+
+// Geofence
+usePointrGeofence((event) => {
+  console.log(event.eventType, event.geofence?.name);
+});
+
+// Building click
+usePointrBuildingClick((event) => {
+  console.log('Building:', event.internalIdentifier, event.title);
+});
+
+// Site click
+usePointrSiteClick((event) => {
+  console.log('Site:', event.internalIdentifier, event.title);
+});
+```
+
+---
+
+### 2. `PointrSdk` subscription methods
+
+```typescript
+import { pointrSdk } from 'react-native-pointr';
+
+useEffect(() => {
+  const sub = pointrSdk.onPositionUpdate((pos) => {
+    console.log(pos);
+  });
+  return () => sub.remove();
+}, []);
+```
+
+Available methods: `onPositionUpdate`, `onBuildingClick`, `onSiteClick`, `onGeofenceEvent`.
+
+---
+
+### 3. Direct `NativeEventEmitter` (advanced)
+
+```typescript
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import { PTREvents } from 'react-native-pointr';
+
+const emitter = new NativeEventEmitter(NativeModules.PTRNativePointrLibrary);
+
+const sub = emitter.addListener(PTREvents.ON_POSITION_CALCULATED, (pos) => {
+  console.log(pos);
+});
+// cleanup:
+sub.remove();
+```
+
+---
+
+### Map widget events
+
+The `PTRMapWidget` component exposes two event callbacks as props:
+
+- **`onMapWidgetDidEndLoading`** — fires when the map finishes loading a command.
+- **`onWayfindingEvent`** — fires during wayfinding (started / ended / cancelled).
+
+```tsx
 <PTRMapWidget
-  ref={ref}
-  onMapWidgetDidEndLoading={handleMapWidgetDidEndLoading}
+  style={{ flex: 1 }}
+  onMapWidgetDidEndLoading={(e) => {
+    const { command, siteExternalIdentifier, error } = e.nativeEvent;
+    if (error) console.error(`Command ${command} failed:`, error);
+  }}
+  onWayfindingEvent={(e) => {
+    const { type, poi } = e.nativeEvent;
+    // type: -1 cancelled, 0 started, 1 ended
+    console.log('Wayfinding', type, poi.name);
+  }}
 />
 ```
 
@@ -756,129 +1128,235 @@ const handleMapWidgetDidEndLoading = (event) => {
 
 ## Complete Example
 
-```typescript
-import React, { useRef, useEffect } from 'react';
+### Declarative (recommended for simple integrations)
+
+Pass `sdkConfig`, `mapWidgetConfig`, and `command` 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 type { PTRConfiguration, PTRMapWidgetConfiguration } from 'react-native-pointr';
+
+const SDK_CONFIG: PTRConfiguration = {
+  clientId: '<CLIENT_ID>',
+  licenseKey: '<LICENSE_KEY>',
+  baseUrl: 'https://<your-instance>.pointr.cloud',
+};
+
+const MAP_CONFIG: PTRMapWidgetConfiguration = {
+  isLevelSelectorEnabled: true,
+  isJoystickEnabled: true,
+  isExitButtonEnabled: false,
+  isQuickAccessEnabled: true,
+};
+
+export default function MapScreen() {
+  return (
+    <PTRMapWidget
+      style={styles.map}
+      sdkConfig={SDK_CONFIG}
+      mapWidgetConfig={MAP_CONFIG}
+      command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
+      onMapWidgetDidEndLoading={(e) => {
+        const { command, error } = e.nativeEvent;
+        if (error) console.error(`${command} failed:`, error);
+        else console.log(`${command} loaded`);
+      }}
+      onWayfindingEvent={(e) => {
+        const { type, poi } = e.nativeEvent;
+        console.log('Wayfinding event', type, 'to', poi.name);
+      }}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  map: { flex: 1 },
+});
+```
+
+### App-level SDK management (hooks)
+
+Use `usePointrSdk` when you need SDK state, position updates, or other events outside of the map widget.
+
+```tsx
+import React, { useState } from 'react';
+import { Text, View, TouchableOpacity, StyleSheet } from 'react-native';
 import {
-  requireNativeComponent,
-  findNodeHandle,
-  NativeModules,
-  NativeEventEmitter,
-  View
-} from 'react-native';
-import { 
+  PTRMapWidget,
   PTRSiteCommand,
-  showMapWidget,
-  getPois,
-  type PTRPoi
+  usePointrSdk,
 } from 'react-native-pointr';
+import type { PTRConfiguration } from 'react-native-pointr';
 
-const PTRMapWidget = requireNativeComponent('PTRMapWidget');
-
-function PointrMapExample() {
-  const mapRef = useRef(null);
+const SDK_CONFIG: PTRConfiguration = {
+  clientId: '<CLIENT_ID>',
+  licenseKey: '<LICENSE_KEY>',
+  baseUrl: 'https://<your-instance>.pointr.cloud',
+};
 
-  useEffect(() => {
-    // Initialize SDK
-    NativeModules.PTRNativePointrLibrary.initialize(
-      "client-id",
-      "license-key",
-      "https://your-instance.pointr.cloud",
-      3
-    );
-
-    // Start SDK
-    NativeModules.PTRNativePointrLibrary.start((state) => {
-      console.log('Pointr state:', state);
-      
-      if (state === 'running') {
-        // Show site when SDK is running
-        const reactTag = findNodeHandle(mapRef.current);
-        if (reactTag) {
-          const command = new PTRSiteCommand("site-id");
-          showMapWidget(reactTag, command);
-        }
-        
-        // Fetch POIs for the site
-        fetchPOIs();
-      }
-    });
-
-    // Listen to position updates
-    const eventEmitter = new NativeEventEmitter(
-      NativeModules.PTRNativePointrLibrary
-    );
-    const subscription = eventEmitter.addListener(
-      'OnPositionManagerCalculatedLocation',
-      (location) => {
-        console.log('Position update:', location);
-      }
-    );
-    
-    // Listen to geofence events
-    const geofenceSubscription = eventEmitter.addListener(
-      'OnGeofenceEvent',
-      (event) => {
-        console.log(`Geofence ${event.eventType}: ${event.geofence.name}`);
-      }
-    );
-
-    return () => {
-      subscription.remove();
-      geofenceSubscription.remove();
-      NativeModules.PTRNativePointrLibrary.stop();
-    };
-  }, []);
-  
-  const fetchPOIs = async () => {
-    try {
-      const pois: PTRPoi[] = await getPois('site-id');
-      console.log(`Found ${pois.length} POIs`);
-      pois.forEach(poi => {
-        console.log(`${poi.name} at level ${poi.position.lvl}`);
-      });
-    } catch (error) {
-      console.error('Failed to fetch POIs:', error);
-    }
-  };
+export default function App() {
+  const [showMap, setShowMap] = useState(false);
+  const { sdk, isStarted, state } = usePointrSdk(SDK_CONFIG);
 
-  const handleMapLoaded = (event) => {
-    const { command, error } = event.nativeEvent;
-    console.log('Map command completed:', command, error);
+  const checkPosition = async () => {
+    const loc = await sdk.getCurrentLocation();
+    if (loc) console.log(loc.latitude, loc.longitude, loc.levelIndex);
   };
 
   return (
-    <View style={{ flex: 1 }}>
-      <PTRMapWidget
-        ref={mapRef}
-        style={{ flex: 1 }}
-        onMapWidgetDidEndLoading={handleMapLoaded}
-      />
+    <View style={styles.container}>
+      <Text>SDK State: {state}</Text>
+      <TouchableOpacity onPress={checkPosition} disabled={!isStarted}>
+        <Text>Get Position</Text>
+      </TouchableOpacity>
+      <TouchableOpacity onPress={() => setShowMap(true)}>
+        <Text>Open Map</Text>
+      </TouchableOpacity>
+
+      {showMap && (
+        <PTRMapWidget
+          style={StyleSheet.absoluteFill}
+          command={new PTRSiteCommand('<SITE_EXTERNAL_ID>')}
+        />
+      )}
     </View>
   );
 }
 
-export default PointrMapExample;
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+});
+```
+
+---
+
+## 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
+### Common errors
 
-- **"Pointr is not initialized"**: Call `initialize()` before other methods
-- **"Pointr is not running"**: Call `start()` and wait for "running" state
-- **"Failed to find node handle for ref"**: Ensure ref is properly attached to component
-- **"No saved location"**: User hasn't marked a "My Car" location yet
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `"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 |
 
-### Best Practices
+### Best practices
 
-1. Always check the Pointr state before executing commands
-2. Handle errors in callbacks and event handlers
-3. Clean up event listeners when component unmounts
-4. Use `findNodeHandle()` to get the correct native view tag
-5. Initialize SDK before rendering the map widget
-6. Request permissions before starting SDK if needed
+1. Use `usePointrSdk(config)` or the declarative `sdkConfig` prop — they handle lifecycle errors internally.
+2. Always remove event subscriptions in cleanup functions (`useEffect` return / `componentWillUnmount`).
+3. Check `isStarted` before calling `getCurrentLocation()` or dispatching map commands imperatively.
+4. Initialize SDK once at the application root — `PointrSdk` is a singleton and re-initialization throws.
 
 ---