react-native-pointr 9.2.0 → 9.3.1

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [9.3.1] - 2026-01-07
+
+### Added
+- **POI Management API**: New `getPois(siteId)` method to retrieve all Points of Interest for a specific site
+- **Geofence Events**: Added `OnGeofenceEvent` listener for geofence enter/exit notifications
+  - Supports both beacon and GPS geofence types
+  - Includes position data and optional notification messages
+  - Available on both iOS and Android platforms
+- **TypeScript Types**: Complete type definitions for better IDE support
+  - `PTRPoi` - Point of Interest data structure
+  - `PTRPosition` - Geographic position with site/building/level info
+  - `PTRGeometry` - Geometry types (Point, Polygon, LineString, Circle, etc.)
+  - `PTRWayfindingEvent` - Wayfinding navigation events
+  - `PTRPoiAttributes` - POI metadata and attributes
+- **Module Exports**: Enhanced ES6 module exports
+  - Named exports for all commands, types, and utilities
+  - Default export maintains backward compatibility
+  - Tree-shaking support for optimized bundle sizes
+- **POI Manager**: New `PTRPoiManager` utility module for POI operations
+- **Platform Extensions**: Native extensions for iOS and Android
+  - iOS: `PTRFeature`, `PTRPosition` dictionary conversions
+  - Android: `PTRCoreExtensions` with Kotlin extension methods
+- Distribution preparation script (`prepare-distribution.sh`) for creating clean, distributable package archives
+- `prepare-dist` npm script for easy package distribution preparation
+- Automated cleanup of build artifacts, git history, and development files during distribution
+
+### Changed
+- **Event Listeners**: Geofence manager listeners now registered in `start()` and removed in `stop()`
+- **Module Structure**: Migrated from CommonJS to ES6 module exports
+- **iOS Implementation**: Improved Swift code organization and type safety
+- **Android Implementation**: Enhanced Kotlin code with extension methods
+
+### Fixed
+- None.
+
 ## [8.16.1]
 
 ## Updates

package/EXTENDING.md

@@ -0,0 +1,419 @@
+# Extending react-native-pointr Package
+
+This guide demonstrates how to extend the functionality of the `react-native-pointr` package by adding new features. We'll use implementing a `getPois` function as an example to show the complete process of adding new functionality.
+
+## Overview
+
+Extending the package involves three main steps:
+
+1. **Add native code** - Implement the functionality in both iOS (Swift/Objective-C) and Android (Kotlin/Java)
+2. **Create TypeScript interfaces** - Define types and interfaces for the new functionality
+3. **Expose to JavaScript** - Make the functionality accessible from React Native
+
+## Example: Adding getPois Functionality
+
+This example shows how to add a function that retrieves all Points of Interest (POIs) for a specific site.
+
+### Step 1: Add Native Implementation
+
+#### iOS Implementation
+
+**File: `ios/PTRNativePointrLibrary.swift`**
+
+Add the following method to your native iOS module:
+
+```swift
+@objc(getPois:resolver:rejecter:)
+func getPois(_ siteId: String, 
+             resolver resolve: @escaping RCTPromiseResolveBlock,
+             rejecter reject: @escaping RCTPromiseRejectBlock) {
+    
+    // Ensure Pointr SDK is initialized
+    guard let site = Pointr.shared.getSite(withExternalIdentifier: siteId) else {
+        reject("ERROR", "Site not found: \(siteId)", nil)
+        return
+    }
+    
+    // Get all POIs for the site
+    let pois = site.getAllPois()
+    
+    // Convert POIs to dictionary format
+    let poisData = pois.map { poi -> [String: Any] in
+        return [
+            "id": poi.externalIdentifier,
+            "name": poi.name ?? "",
+            "buildingId": poi.building?.externalIdentifier ?? "",
+            "levelIndex": poi.level?.index ?? 0,
+            "category": poi.category ?? "",
+            "latitude": poi.coordinate.latitude,
+            "longitude": poi.coordinate.longitude
+        ]
+    }
+    
+    resolve(poisData)
+}
+```
+
+**File: `ios/PTRNativePointrLibrary.m`**
+
+Add the method declaration to the bridge:
+
+```objective-c
+RCT_EXTERN_METHOD(getPois:(NSString *)siteId
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+```
+
+#### Android Implementation
+
+**File: `android/src/main/java/com/reactnativepointr/PTRNativePointrLibraryModule.kt`**
+
+Add the following method to your native Android module:
+
+```kotlin
+@ReactMethod
+fun getPois(siteId: String, promise: Promise) {
+    try {
+        // Ensure Pointr SDK is initialized
+        val site = Pointr.getSite(siteId)
+        
+        if (site == null) {
+            promise.reject("ERROR", "Site not found: $siteId")
+            return
+        }
+        
+        // Get all POIs for the site
+        val pois = site.getAllPois()
+        
+        // Convert POIs to WritableArray
+        val poisArray = Arguments.createArray()
+        
+        pois.forEach { poi ->
+            val poiMap = Arguments.createMap().apply {
+                putString("id", poi.externalIdentifier)
+                putString("name", poi.name ?: "")
+                putString("buildingId", poi.building?.externalIdentifier ?: "")
+                putInt("levelIndex", poi.level?.index ?: 0)
+                putString("category", poi.category ?: "")
+                putDouble("latitude", poi.coordinate.latitude)
+                putDouble("longitude", poi.coordinate.longitude)
+            }
+            poisArray.pushMap(poiMap)
+        }
+        
+        promise.resolve(poisArray)
+        
+    } catch (e: Exception) {
+        promise.reject("ERROR", "Failed to get POIs: ${e.message}", e)
+    }
+}
+```
+
+### Step 2: Create TypeScript Interfaces
+
+**File: `src/types/PTRPoi.ts`**
+
+Create a new file to define the POI type:
+
+```typescript
+/**
+ * Point of Interest (POI) data structure
+ */
+export interface PTRPoi {
+  /** Unique identifier for the POI */
+  id: string;
+  
+  /** Display name of the POI */
+  name: string;
+  
+  /** Building identifier where the POI is located */
+  buildingId: string;
+  
+  /** Level/floor index where the POI is located */
+  levelIndex: number;
+  
+  /** Category or type of the POI */
+  category: string;
+  
+  /** Latitude coordinate */
+  latitude: number;
+  
+  /** Longitude coordinate */
+  longitude: number;
+}
+```
+
+### Step 3: Create JavaScript Wrapper
+
+**File: `src/PTRNativePointrLibrary.ts`**
+
+Create a wrapper function that provides a clean API:
+
+```typescript
+import { NativeModules } from 'react-native';
+import { PTRPoi } from './types/PTRPoi';
+
+const { PTRNativePointrLibrary } = NativeModules;
+
+/**
+ * Get all Points of Interest (POIs) for a specific site
+ * @param siteId - The external identifier of the site
+ * @returns Promise that resolves with an array of POIs
+ * @throws Error if the site is not found or if the operation fails
+ */
+export async function getPois(siteId: string): Promise<PTRPoi[]> {
+  try {
+    const pois = await PTRNativePointrLibrary.getPois(siteId);
+    return pois as PTRPoi[];
+  } catch (error) {
+    console.error('Failed to get POIs:', error);
+    throw error;
+  }
+}
+```
+
+### Step 4: Export the New Functionality
+
+**File: `src/index.ts`**
+
+Export the new functions and types from the main entry point:
+
+```typescript
+// Existing exports
+export * from './PTRCommand';
+export * from './PTRMapWidgetUtils';
+
+// New exports
+export { getPois } from './PTRNativePointrLibrary';
+export type { PTRPoi } from './types/PTRPoi';
+```
+
+### Step 5: Usage Example
+
+Now you can use the new functionality in your React Native app:
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import { View, Text, FlatList, ActivityIndicator } from 'react-native';
+import { getPois, PTRPoi } from 'react-native-pointr';
+
+function PoiListScreen() {
+  const [pois, setPois] = useState<PTRPoi[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadPois();
+  }, []);
+
+  const loadPois = async () => {
+    try {
+      setLoading(true);
+      const siteId = 'your-site-id';
+      const poisData = await getPois(siteId);
+      setPois(poisData);
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to load POIs');
+      console.error('Error loading POIs:', err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (loading) {
+    return (
+      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+        <ActivityIndicator size="large" />
+        <Text>Loading POIs...</Text>
+      </View>
+    );
+  }
+
+  if (error) {
+    return (
+      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
+        <Text style={{ color: 'red' }}>Error: {error}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <FlatList
+      data={pois}
+      keyExtractor={(item) => item.id}
+      renderItem={({ item }) => (
+        <View style={{ padding: 16, borderBottomWidth: 1, borderColor: '#ccc' }}>
+          <Text style={{ fontSize: 18, fontWeight: 'bold' }}>{item.name}</Text>
+          <Text>Category: {item.category}</Text>
+          <Text>Building: {item.buildingId}</Text>
+          <Text>Level: {item.levelIndex}</Text>
+          <Text>
+            Location: {item.latitude.toFixed(6)}, {item.longitude.toFixed(6)}
+          </Text>
+        </View>
+      )}
+    />
+  );
+}
+
+export default PoiListScreen;
+```
+
+## Best Practices for Extensions
+
+### 1. Type Safety
+
+Always define TypeScript interfaces for data structures:
+
+```typescript
+export interface PTRCustomData {
+  id: string;
+  value: any;
+  // Add proper types
+}
+```
+
+### 2. Error Handling
+
+Implement comprehensive error handling in both native and JavaScript code:
+
+```typescript
+try {
+  const result = await nativeModule.someMethod();
+  return result;
+} catch (error) {
+  console.error('Operation failed:', error);
+  throw new Error(`Failed to execute: ${error.message}`);
+}
+```
+
+### 3. Promise-based APIs
+
+Use Promises for asynchronous operations to provide a consistent API:
+
+```swift
+// iOS
+@objc(someAsyncMethod:resolver:rejecter:)
+func someAsyncMethod(_ param: String,
+                     resolver resolve: @escaping RCTPromiseResolveBlock,
+                     rejecter reject: @escaping RCTPromiseRejectBlock) {
+    // Implementation
+}
+```
+
+```kotlin
+// Android
+@ReactMethod
+fun someAsyncMethod(param: String, promise: Promise) {
+    // Implementation
+}
+```
+
+### 4. Documentation
+
+Document all new functionality with JSDoc comments:
+
+```typescript
+/**
+ * Description of what the function does
+ * @param paramName - Description of the parameter
+ * @returns Description of what is returned
+ * @throws Description of potential errors
+ * @example
+ * ```typescript
+ * const result = await someFunction('value');
+ * ```
+ */
+export async function someFunction(paramName: string): Promise<ResultType> {
+  // Implementation
+}
+```
+
+### 5. Testing
+
+Create test cases for new functionality:
+
+```typescript
+import { getPois } from 'react-native-pointr';
+
+describe('getPois', () => {
+  it('should return an array of POIs', async () => {
+    const pois = await getPois('test-site-id');
+    expect(Array.isArray(pois)).toBe(true);
+    expect(pois.length).toBeGreaterThan(0);
+  });
+
+  it('should throw error for invalid site', async () => {
+    await expect(getPois('invalid-site')).rejects.toThrow();
+  });
+});
+```
+
+### 6. Platform Consistency
+
+Ensure both iOS and Android implementations return the same data structure:
+
+```typescript
+// Both platforms should return identical structure
+{
+  id: string;
+  name: string;
+  // Same fields with same types
+}
+```
+
+## Adding Event Listeners
+
+For continuous data streams or callbacks, use event emitters:
+
+### Native Side (iOS)
+
+```swift
+@objc
+func sendEvent(_ name: String, body: Any) {
+    sendEvent(withName: name, body: body)
+}
+
+override func supportedEvents() -> [String]! {
+    return ["onLocationUpdate", "onPoiEnter"]
+}
+```
+
+### Native Side (Android)
+
+```kotlin
+private fun sendEvent(eventName: String, params: WritableMap?) {
+    reactContext
+        .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
+        .emit(eventName, params)
+}
+```
+
+### JavaScript Side
+
+```typescript
+import { NativeEventEmitter, NativeModules } from 'react-native';
+
+const { PTRNativePointrLibrary } = NativeModules;
+const eventEmitter = new NativeEventEmitter(PTRNativePointrLibrary);
+
+export function subscribeToLocationUpdates(
+  callback: (location: PTRLocation) => void
+): () => void {
+  const subscription = eventEmitter.addListener('onLocationUpdate', callback);
+  return () => subscription.remove();
+}
+```
+
+## Conclusion
+
+Extending the `react-native-pointr` package follows a consistent pattern:
+
+1. Implement native functionality on both platforms
+2. Define TypeScript types
+3. Create JavaScript wrappers
+4. Export from the package
+5. Document and test
+
+This approach ensures a maintainable, type-safe, and platform-consistent API for your React Native application.