@explorins/pers-sdk-react-native 2.3.0-alpha.3 → 2.3.2

package/dist/providers/PersSDKProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAkB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CA6NA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}
+{"version":3,"file":"PersSDKProvider.d.ts","sourceRoot":"","sources":["../../src/providers/PersSDKProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAuC,SAAS,EAA2C,MAAM,OAAO,CAAC;AAEvH,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAIpF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAmB3D,YAAY,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,WAAW,cAAc;IAE7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAGpB,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAGzC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,CAAC;IAGhC,UAAU,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sBAAsB,EAAE,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI,EAAE,eAAe,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5F,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;CAC/C;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;IACrC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB,CA+OA,CAAC;AAGF,eAAO,MAAM,UAAU,QAAO,cAQ7B,CAAC"}

package/dist/providers/PersSDKProvider.js

@@ -5,6 +5,7 @@ import { PersSDK } from '@explorins/pers-sdk/core';
 import { ReactNativeHttpClient } from './react-native-http-client';
 import { createReactNativeAuthProvider } from './react-native-auth-provider';
 import { ReactNativeDPoPProvider } from './rn-dpop-provider';
+import { detectReactNativePlatform } from '../utils/platform-detection';
 // Create the context
 const SDKContext = createContext(null);
 /**
@@ -92,6 +93,22 @@ export const PersSDKProvider = ({ children, config }) => {
             };
             // Initialize PersSDK with platform-aware auth provider
             const sdkInstance = new PersSDK(httpClient, sdkConfig);
+            // Auto-configure data source and platform for React Native
+            // Native apps MUST set channel as backend cannot auto-detect without browser User-Agent
+            if (Platform.OS !== 'web') {
+                sdkInstance.setDataSource({
+                    channel: 'mobile',
+                    source: config.dataSource?.source || 'app',
+                    medium: config.dataSource?.medium,
+                    campaign: config.dataSource?.campaign,
+                });
+                // Auto-detect platform info asynchronously
+                detectReactNativePlatform().then(platformInfo => {
+                    sdkInstance.setPlatform(platformInfo);
+                }).catch(error => {
+                    console.debug('[PersSDK] Platform detection failed:', error);
+                });
+            }
             // Subscribe to auth events BEFORE exposing SDK to consumers
             // This ensures no events are missed due to React timing
             eventUnsubscribeRef.current = sdkInstance.events.subscribe((event) => {

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility exports for React Native SDK
+ */
+export { detectReactNativePlatform, detectReactNativePlatformSync } from './platform-detection';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,yBAAyB,EACzB,6BAA6B,EAC9B,MAAM,sBAAsB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,4 @@
+/**
+ * Utility exports for React Native SDK
+ */
+export { detectReactNativePlatform, detectReactNativePlatformSync } from './platform-detection';

package/dist/utils/platform-detection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * React Native Platform Detection Utilities
+ *
+ * Provides automatic platform info detection for React Native apps.
+ *
+ * @module @explorins/pers-sdk-react-native/utils
+ */
+import type { Platform } from '@explorins/pers-sdk/core';
+/**
+ * Detect platform info for React Native apps
+ *
+ * Automatically gathers OS, version, app info, and device type.
+ * Uses react-native-device-info for enhanced detection if installed.
+ *
+ * @example
+ * ```typescript
+ * import { detectReactNativePlatform } from '@explorins/pers-sdk-react-native';
+ *
+ * // Get platform info
+ * const platform = await detectReactNativePlatform();
+ * // { os: 'iOS', osVersion: '17.4', app: 'MyApp', appVersion: '2.3.1', deviceType: 'phone' }
+ *
+ * // Set in SDK
+ * sdk.setPlatform(platform);
+ * ```
+ */
+export declare function detectReactNativePlatform(): Promise<Platform>;
+/**
+ * Synchronous version for immediate use (limited info)
+ *
+ * Use when you need platform info immediately without async.
+ * For full info including device type, use detectReactNativePlatform().
+ */
+export declare function detectReactNativePlatformSync(): Platform;
+//# sourceMappingURL=platform-detection.d.ts.map

package/dist/utils/platform-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-detection.d.ts","sourceRoot":"","sources":["../../src/utils/platform-detection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAWzD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,QAAQ,CAAC,CAsBnE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,IAAI,QAAQ,CAiBxD"}

package/dist/utils/platform-detection.js

@@ -0,0 +1,79 @@
+/**
+ * React Native Platform Detection Utilities
+ *
+ * Provides automatic platform info detection for React Native apps.
+ *
+ * @module @explorins/pers-sdk-react-native/utils
+ */
+import { Platform as RNPlatform } from 'react-native';
+// DeviceInfo is optional - dynamically loaded if available
+let DeviceInfo = null;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    DeviceInfo = require('react-native-device-info').default;
+}
+catch {
+    // react-native-device-info not installed - will use basic detection
+}
+/**
+ * Detect platform info for React Native apps
+ *
+ * Automatically gathers OS, version, app info, and device type.
+ * Uses react-native-device-info for enhanced detection if installed.
+ *
+ * @example
+ * ```typescript
+ * import { detectReactNativePlatform } from '@explorins/pers-sdk-react-native';
+ *
+ * // Get platform info
+ * const platform = await detectReactNativePlatform();
+ * // { os: 'iOS', osVersion: '17.4', app: 'MyApp', appVersion: '2.3.1', deviceType: 'phone' }
+ *
+ * // Set in SDK
+ * sdk.setPlatform(platform);
+ * ```
+ */
+export async function detectReactNativePlatform() {
+    const platform = {
+        os: RNPlatform.OS === 'ios' ? 'iOS' : RNPlatform.OS === 'android' ? 'Android' : RNPlatform.OS,
+        osVersion: RNPlatform.Version?.toString(),
+        deviceType: 'phone', // Default fallback
+    };
+    if (DeviceInfo) {
+        try {
+            // App info
+            platform.app = await DeviceInfo.getApplicationName();
+            platform.appVersion = DeviceInfo.getVersion();
+            // Device type detection
+            const isTablet = await DeviceInfo.isTablet();
+            platform.deviceType = isTablet ? 'tablet' : 'phone';
+        }
+        catch (error) {
+            console.debug('[Platform] DeviceInfo error, using basic detection');
+        }
+    }
+    return platform;
+}
+/**
+ * Synchronous version for immediate use (limited info)
+ *
+ * Use when you need platform info immediately without async.
+ * For full info including device type, use detectReactNativePlatform().
+ */
+export function detectReactNativePlatformSync() {
+    const platform = {
+        os: RNPlatform.OS === 'ios' ? 'iOS' : RNPlatform.OS === 'android' ? 'Android' : RNPlatform.OS,
+        osVersion: RNPlatform.Version?.toString(),
+        deviceType: 'phone', // Default, can't detect tablet sync without DeviceInfo
+    };
+    if (DeviceInfo) {
+        try {
+            platform.app = DeviceInfo.getApplicationNameSync?.();
+            platform.appVersion = DeviceInfo.getVersion?.();
+        }
+        catch {
+            // Ignore if DeviceInfo methods fail
+        }
+    }
+    return platform;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@explorins/pers-sdk-react-native",
-  "version": "2.3.0-alpha.3",
+  "version": "2.3.2",
   "description": "React Native SDK for PERS Platform - Tourism Loyalty System with Blockchain Transaction Signing and WebAuthn Authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -37,7 +37,7 @@
   "author": "eXplorins",
   "license": "MIT",
   "dependencies": {
-    "@explorins/pers-sdk": "^2.2.0-alpha.2",
+    "@explorins/pers-sdk": "^2.3.3",
     "@explorins/pers-signer": "^1.0.34",
     "buffer": "^6.0.3",
     "ethers": "^6.15.0",
@@ -94,6 +94,7 @@
     "@react-native-async-storage/async-storage": ">=1.15.0",
     "react": ">=16.8.0",
     "react-native": ">=0.60.0",
+    "react-native-device-info": "^15.0.2",
     "react-native-get-random-values": ">=1.8.0",
     "react-native-keychain": ">=8.0.0",
     "react-native-passkey": ">=3.0.0",
@@ -103,6 +104,9 @@
     "@react-native-async-storage/async-storage": {
       "optional": false
     },
+    "react-native-device-info": {
+      "optional": true
+    },
     "react-native-get-random-values": {
       "optional": false
     },
@@ -162,7 +166,7 @@
     "@ethersproject/scrypt": false
   },
   "devDependencies": {
-    "@explorins/pers-shared": "^2.1.128",
+    "@explorins/pers-shared": "^2.1.183",
     "@react-native-async-storage/async-storage": "^3.0.2",
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",

package/src/hooks/useRedemptions.ts

@@ -14,11 +14,15 @@ import type {
   DynamicContext,
   SortOrder
 } from '@explorins/pers-sdk';
-import type { RedemptionRedeemFilters } from '@explorins/pers-sdk/redemption';
+import type { RedemptionRedeemQueryParams, RedemptionQueryParams } from '@explorins/pers-sdk/redemption';
 import type { PaginationOptions } from '@explorins/pers-sdk';
 
-// Re-export for consumers
-export type { RedemptionRedeemFilters, RedemptionFilterOptions } from '@explorins/pers-sdk/redemption';
+// Re-export for consumers (new names + deprecated aliases)
+export type { RedemptionRedeemQueryParams, RedemptionQueryParams } from '@explorins/pers-sdk/redemption';
+/** @deprecated Use RedemptionRedeemQueryParams instead */
+export type RedemptionRedeemFilters = RedemptionRedeemQueryParams;
+/** @deprecated Use RedemptionQueryParams instead */
+export type RedemptionFilterOptions = RedemptionQueryParams;
 
 /**
  * Options for fetching redemptions with filtering and pagination
@@ -105,7 +109,14 @@ export const useRedemptions = () => {
     }
     
     try {
-      const result = await sdk.redemptions.getRedemptions(options);
+      // Convert Date to ISO string for API compatibility
+      const apiOptions = options ? {
+        ...options,
+        startDate: options.startDate instanceof Date ? options.startDate.toISOString() : options.startDate,
+        endDate: options.endDate instanceof Date ? options.endDate.toISOString() : options.endDate,
+      } : undefined;
+      
+      const result = await sdk.redemptions.getRedemptions(apiOptions);
       return result;
     } catch (error) {
       console.error('Failed to fetch redemptions:', error);
@@ -327,7 +338,7 @@ export const useRedemptions = () => {
    * ```
    */
   const getRedemptionRedeems = useCallback(async (
-    filters?: RedemptionRedeemFilters,
+    filters?: RedemptionRedeemQueryParams,
     include?: RedemptionRedeemIncludeRelation[]
   ): Promise<PaginatedResponseDTO<RedemptionRedeemDTO>> => {
     if (!isInitialized || !sdk) {

package/src/index.ts

@@ -1,3 +1,6 @@
+// Polyfills - must be imported first for Hermes engine compatibility
+import 'react-native-url-polyfill/auto';
+
 /**
  * @fileoverview PERS SDK for React Native - Tourism Loyalty System
  * 
@@ -566,4 +569,202 @@ export {
   PersApiError, 
   AuthenticationError,
   ErrorUtils 
-} from '@explorins/pers-sdk/core';
+} from '@explorins/pers-sdk/core';
+
+// ==============================================================================
+// DATA SOURCE TRACKING
+// ==============================================================================
+
+/**
+ * Data source tracking utilities for attribution analytics
+ * 
+ * Native apps MUST configure data source and platform info for proper attribution.
+ * Web apps benefit from auto-detection, but can still set explicit values.
+ * 
+ * @example
+ * **React Native Setup:**
+ * ```typescript
+ * import { usePersSDK, detectReactNativePlatform } from '@explorins/pers-sdk-react-native';
+ * 
+ * const { sdk } = usePersSDK();
+ * 
+ * // Set platform info (call once on app start)
+ * sdk.setPlatform(detectReactNativePlatform());
+ * 
+ * // Set data source (call once, update on deep links/push)
+ * sdk.setDataSource({
+ *   channel: 'mobile',
+ *   source: 'app_store',
+ * });
+ * ```
+ * 
+ * @example
+ * **Handle Deep Links:**
+ * ```typescript
+ * import { parseUtmParams } from '@explorins/pers-sdk-react-native';
+ * 
+ * function handleDeepLink(url: string) {
+ *   const utm = parseUtmParams(url);
+ *   sdk.updateDataSource({
+ *     medium: utm.medium,
+ *     campaign: utm.campaign,
+ *     source: utm.source || 'deep_link',
+ *   });
+ * }
+ * ```
+ * 
+ * @example
+ * **Handle Push Notifications:**
+ * ```typescript
+ * function handlePushNotification(notification: PushNotification) {
+ *   sdk.updateDataSource({
+ *     medium: 'push',
+ *     source: 'push_notification',
+ *     campaign: notification.campaignId,
+ *   });
+ * }
+ * ```
+ */
+export {
+  // Types
+  type Platform,
+  type DataSource,
+  type UtmParams,
+  type WebDataSourceConfig,
+  type NativeDataSourceConfig,
+  
+  // Utilities
+  parseUtmParams,
+  detectSourceFromReferrer,
+  detectWebPlatform,
+} from '@explorins/pers-sdk/core';
+
+// React Native specific platform detection
+export { detectReactNativePlatform } from './utils/platform-detection';
+
+// ==============================================================================
+// FIELD VALIDATION UTILITIES
+// ==============================================================================
+
+/**
+ * Field validation utilities for custom fields and forms
+ * 
+ * These functions are re-exported from @explorins/pers-shared for convenience.
+ * Use them for client-side validation before submitting data to the backend.
+ * 
+ * @example
+ * **Single Field Validation:**
+ * ```typescript
+ * import { validateFieldValue, FieldType, FieldValidationRules } from '@explorins/pers-sdk-react-native';
+ * 
+ * const rules: FieldValidationRules = { minLength: 3 };
+ * const error = validateFieldValue('ab', rules, 'text');
+ * // error: { message: 'Must be at least 3 characters' }
+ * ```
+ * 
+ * @example
+ * **Form Validation:**
+ * ```typescript
+ * import { validateAllFields, FieldDefinition } from '@explorins/pers-sdk-react-native';
+ * 
+ * const definitions: FieldDefinition[] = [
+ *   { key: 'email', fieldType: 'email', label: 'Email', validation: { minLength: 1 } },
+ *   { key: 'phone', fieldType: 'phone', label: 'Phone', validation: {} }
+ * ];
+ * 
+ * const formData = { email: 'invalid', phone: '123' };
+ * const errors = validateAllFields(formData, definitions);
+ * // errors: [{ field: 'email', message: 'Invalid email format' }]
+ * ```
+ * 
+ * @see {@link validateFieldValue} - Validate a single field value
+ * @see {@link validateAllFields} - Validate all fields against definitions
+ * @see {@link FieldDefinition} - Field definition structure
+ * @see {@link FieldValidationRules} - Available validation rules
+ */
+export {
+  validateFieldValue,
+  validateAllFields,
+  validateFieldComparisons,
+  compareValues,
+  type FieldDefinition,
+  type FieldValidationRules,
+  type ValidationErrorDetail,
+  type FieldType,
+  type FieldComparison,
+  type ComparisonOperator,
+} from '@explorins/pers-sdk';
+
+// ==============================================================================
+// BOOKING STATUS VALIDATION
+// ==============================================================================
+
+/**
+ * Booking status types and validation utilities for eligibility checks
+ * 
+ * Use these to validate if a user's booking status meets requirements
+ * for redemptions, campaigns, or other booking-dependent features.
+ * 
+ * **BookingStatus:** 'past' | 'active' | 'future'
+ * - `past`: User's stay has ended (checkOut ≤ now)
+ * - `active`: User is currently staying (checkIn ≤ now < checkOut)
+ * - `future`: Upcoming booking (checkIn > now)
+ * 
+ * **BookingRequirementType:** 'active' | 'future' | 'past' | 'active_future' | 'any'
+ * - `active`: Only active bookings allowed
+ * - `future`: Only future bookings allowed
+ * - `past`: Only past bookings allowed
+ * - `active_future`: Active OR future bookings allowed
+ * - `any`: Any booking status allowed
+ * 
+ * @example
+ * **Basic Validation:**
+ * ```typescript
+ * import { 
+ *   isBookingStatusValid,
+ *   BookingStatus,
+ *   BookingRequirementType 
+ * } from '@explorins/pers-sdk-react-native';
+ * 
+ * const userBookingStatus: BookingStatus = booking.status;
+ * const requirement: BookingRequirementType = redemption.bookingRequirement;
+ * const canRedeem = isBookingStatusValid(userBookingStatus, requirement);
+ * ```
+ * 
+ * @example
+ * **Redemption Screen:**
+ * ```typescript
+ * function RedemptionCard({ redemption, userBooking }) {
+ *   const isEligible = redemption.bookingRequirement 
+ *     ? isBookingStatusValid(userBooking?.status ?? 'past', redemption.bookingRequirement)
+ *     : true;
+ *   
+ *   return (
+ *     <View style={[styles.card, !isEligible && styles.disabled]}>
+ *       <Text>{redemption.name}</Text>
+ *       {!isEligible && (
+ *         <Text style={styles.warning}>
+ *           Requires {redemption.bookingRequirement} booking
+ *         </Text>
+ *       )}
+ *     </View>
+ *   );
+ * }
+ * ```
+ * 
+ * @example
+ * **Validation Results:**
+ * ```typescript
+ * isBookingStatusValid('active', 'active');         // true
+ * isBookingStatusValid('future', 'active');         // false
+ * isBookingStatusValid('active', 'active_future');  // true
+ * isBookingStatusValid('future', 'active_future');  // true
+ * isBookingStatusValid('past', 'active_future');    // false
+ * isBookingStatusValid('past', 'any');              // true
+ * ```
+ */
+export { 
+  isBookingStatusValid,
+  type BookingStatus, 
+  type BookingRequirementType 
+} from '@explorins/pers-sdk';

package/src/providers/PersSDKProvider.tsx

@@ -5,6 +5,7 @@ import { ReactNativeHttpClient } from './react-native-http-client';
 import { createReactNativeAuthProvider } from './react-native-auth-provider';
 import { ReactNativeDPoPProvider } from './rn-dpop-provider';
 import { UserDTO, AdminDTO } from '@explorins/pers-shared';
+import { detectReactNativePlatform } from '../utils/platform-detection';
 
 // Import manager types for TypeScript
 import type {
@@ -191,6 +192,24 @@ export const PersSDKProvider: React.FC<{
       // Initialize PersSDK with platform-aware auth provider
       const sdkInstance = new PersSDK(httpClient, sdkConfig);
       
+      // Auto-configure data source and platform for React Native
+      // Native apps MUST set channel as backend cannot auto-detect without browser User-Agent
+      if (Platform.OS !== 'web') {
+        sdkInstance.setDataSource({
+          channel: 'mobile',
+          source: config.dataSource?.source || 'app',
+          medium: config.dataSource?.medium,
+          campaign: config.dataSource?.campaign,
+        });
+        
+        // Auto-detect platform info asynchronously
+        detectReactNativePlatform().then(platformInfo => {
+          sdkInstance.setPlatform(platformInfo);
+        }).catch(error => {
+          console.debug('[PersSDK] Platform detection failed:', error);
+        });
+      }
+      
       // Subscribe to auth events BEFORE exposing SDK to consumers
       // This ensures no events are missed due to React timing
       eventUnsubscribeRef.current = sdkInstance.events.subscribe((event) => {

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility exports for React Native SDK
+ */
+
+export { 
+  detectReactNativePlatform, 
+  detectReactNativePlatformSync 
+} from './platform-detection';

package/src/utils/platform-detection.ts

@@ -0,0 +1,86 @@
+/**
+ * React Native Platform Detection Utilities
+ * 
+ * Provides automatic platform info detection for React Native apps.
+ * 
+ * @module @explorins/pers-sdk-react-native/utils
+ */
+
+import { Platform as RNPlatform } from 'react-native';
+import type { Platform } from '@explorins/pers-sdk/core';
+
+// DeviceInfo is optional - dynamically loaded if available
+let DeviceInfo: any = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  DeviceInfo = require('react-native-device-info').default;
+} catch {
+  // react-native-device-info not installed - will use basic detection
+}
+
+/**
+ * Detect platform info for React Native apps
+ * 
+ * Automatically gathers OS, version, app info, and device type.
+ * Uses react-native-device-info for enhanced detection if installed.
+ * 
+ * @example
+ * ```typescript
+ * import { detectReactNativePlatform } from '@explorins/pers-sdk-react-native';
+ * 
+ * // Get platform info
+ * const platform = await detectReactNativePlatform();
+ * // { os: 'iOS', osVersion: '17.4', app: 'MyApp', appVersion: '2.3.1', deviceType: 'phone' }
+ * 
+ * // Set in SDK
+ * sdk.setPlatform(platform);
+ * ```
+ */
+export async function detectReactNativePlatform(): Promise<Platform> {
+  const platform: Platform = {
+    os: RNPlatform.OS === 'ios' ? 'iOS' : RNPlatform.OS === 'android' ? 'Android' : RNPlatform.OS,
+    osVersion: RNPlatform.Version?.toString(),
+    deviceType: 'phone', // Default fallback
+  };
+
+  if (DeviceInfo) {
+    try {
+      // App info
+      platform.app = await DeviceInfo.getApplicationName();
+      platform.appVersion = DeviceInfo.getVersion();
+      
+      // Device type detection
+      const isTablet = await DeviceInfo.isTablet();
+      platform.deviceType = isTablet ? 'tablet' : 'phone';
+    } catch (error) {
+      console.debug('[Platform] DeviceInfo error, using basic detection');
+    }
+  }
+
+  return platform;
+}
+
+/**
+ * Synchronous version for immediate use (limited info)
+ * 
+ * Use when you need platform info immediately without async.
+ * For full info including device type, use detectReactNativePlatform().
+ */
+export function detectReactNativePlatformSync(): Platform {
+  const platform: Platform = {
+    os: RNPlatform.OS === 'ios' ? 'iOS' : RNPlatform.OS === 'android' ? 'Android' : RNPlatform.OS,
+    osVersion: RNPlatform.Version?.toString(),
+    deviceType: 'phone', // Default, can't detect tablet sync without DeviceInfo
+  };
+
+  if (DeviceInfo) {
+    try {
+      platform.app = DeviceInfo.getApplicationNameSync?.();
+      platform.appVersion = DeviceInfo.getVersion?.();
+    } catch {
+      // Ignore if DeviceInfo methods fail
+    }
+  }
+
+  return platform;
+}