spotny-sdk 0.3.8 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # spotny-sdk
 
-A React Native SDK for iBeacon proximity detection. Detects nearby beacons, fires region enter/exit events, and powers real-time proximity experiences on iOS and Android.
+A React Native SDK for real-time proximity experiences. Detects nearby points of interest and fires location events on iOS and Android.
 
 > Requires **React Native 0.73+** with the New Architecture (Turbo Modules) enabled.
 
@@ -24,11 +24,11 @@ Add the following keys to your `Info.plist`:
 
 ```xml
 <key>NSLocationWhenInUseUsageDescription</key>
-<string>We use your location to detect nearby beacons.</string>
+<string>We use your location to detect nearby points of interest.</string>
 <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
-<string>We use your location in the background to detect nearby beacons.</string>
+<string>We use your location in the background to detect nearby points of interest.</string>
 <key>NSBluetoothAlwaysUsageDescription</key>
-<string>We use Bluetooth to scan for nearby beacons.</string>
+<string>We use Bluetooth to detect nearby points of interest.</string>
 ```
 
 Enable **Background Modes** in Xcode → your app target → **Signing & Capabilities** → **+ Capability** → Background Modes:
@@ -36,7 +36,7 @@ Enable **Background Modes** in Xcode → your app target → **Signing & Capabil
 - ✅ Location updates
 - ✅ Uses Bluetooth LE accessories
 
-> **Important — avoid crash on launch:** If your app does **not** enable the _Location updates_ background mode, the SDK will still work for foreground-only scanning. However, if you enable it in Xcode, the `UIBackgroundModes: [location]` entry is added to `Info.plist` and the SDK will automatically enable background scanning. Omitting this while calling `startScanner` is safe — the SDK detects the missing capability at runtime and skips the background-location setting. Earlier versions (< 0.3.4) would crash with `NSInternalInconsistencyException` if the background mode was not declared; this is fixed in **0.3.4+**.
+> **Note:** Background scanning requires the _Location updates_ background mode. The SDK works without it for foreground-only use.
 
 ### Android
 
@@ -60,32 +60,28 @@ import {
   configure,
   startScanner,
   stopScanner,
-  addBeaconsRangedListener,
-  addBeaconRegionListener,
+  addProximityListener,
+  addLocationEventListener,
 } from 'spotny-sdk';
 
 export default function App() {
   useEffect(() => {
-    // Optional: override defaults before starting
-    configure({ maxDetectionDistance: 10 });
-
-    // Start scanning with a unique device/user identifier
+    configure({ source: 'nike', maxDetectionDistance: 10 });
     startScanner('device-uuid-here', /* userId */ null);
 
-    // Listen for ranged beacons (fires ~every second)
-    const rangedSub = addBeaconsRangedListener(({ beacons, region }) => {
-      console.log('Beacons in range:', beacons);
+    const proxSub = addProximityListener((items) => {
+      console.log('Nearby:', items);
     });
 
-    // Listen for region enter / exit
-    const regionSub = addBeaconRegionListener(({ region, event }) => {
-      console.log(`Region ${region}: ${event}`);
+    const locationSub = addLocationEventListener(({ event, zone }) => {
+      if (event === 'enter') console.log('Entered zone', zone);
+      if (event === 'exit') console.log('Left zone', zone);
     });
 
     return () => {
       stopScanner();
-      rangedSub.remove();
-      regionSub.remove();
+      proxSub.remove();
+      locationSub.remove();
     };
   }, []);
 
@@ -97,18 +93,18 @@ export default function App() {
 
 ## API Reference
 
-### Core Scanning
+### Core
 
 #### `startScanner(userUUID, userId?)`
 
-Starts BLE beacon scanning and begins ranging / monitoring regions.
+Starts proximity scanning.
 
-| Parameter  | Type             | Required | Description                                     |
-| ---------- | ---------------- | -------- | ----------------------------------------------- |
-| `userUUID` | `string`         | Yes      | Unique identifier for this installation/session |
-| `userId`   | `number \| null` | No       | Authenticated user ID                           |
+| Parameter  | Type             | Required | Description                               |
+| ---------- | ---------------- | -------- | ----------------------------------------- |
+| `userUUID` | `string`         | Yes      | Unique identifier for this device/session |
+| `userId`   | `number \| null` | No       | Authenticated user ID                     |
 
-Returns `Promise<string>` — resolves with a status message.
+Returns `Promise<string>`.
 
 ```ts
 await startScanner('550e8400-e29b-41d4-a716-446655440000', 42);
@@ -118,23 +114,15 @@ await startScanner('550e8400-e29b-41d4-a716-446655440000', 42);
 
 #### `stopScanner()`
 
-Stops scanning, halts ranging, and clears all in-memory beacon state.
+Stops scanning and clears all state.
 
 Returns `Promise<string>`.
 
-```ts
-await stopScanner();
-```
-
 ---
 
 #### `isScanning()`
 
-Returns `Promise<boolean>` — `true` if the SDK is currently scanning.
-
-```ts
-const scanning = await isScanning();
-```
+Returns `Promise<boolean>`.
 
 ---
 
@@ -142,17 +130,15 @@ const scanning = await isScanning();
 
 #### `configure(config)`
 
-Overrides SDK defaults. **Must be called before `startScanner`.**
-
-| Option                 | Type     | Default | Description                                                                     |
-| ---------------------- | -------- | ------- | ------------------------------------------------------------------------------- |
-| `maxDetectionDistance` | `number` | `8.0`   | Maximum beacon detection radius (metres)                                        |
-| `source`               | `string` | –       | Identifier for your brand or app (e.g. `'nike'`). |
+Call **before** `startScanner`.
 
-Returns `Promise<string>`.
+| Option                 | Type     | Default | Description                                  |
+| ---------------------- | -------- | ------- | -------------------------------------------- |
+| `source`               | `string` | –       | Your brand or app identifier (e.g. `'nike'`) |
+| `maxDetectionDistance` | `number` | `8.0`   | Detection radius in metres                   |
 
 ```ts
-await configure({ maxDetectionDistance: 12, source: 'nike' });
+await configure({ source: 'nike', maxDetectionDistance: 10 });
 ```
 
 ---
@@ -161,139 +147,66 @@ await configure({ maxDetectionDistance: 12, source: 'nike' });
 
 #### `requestNotificationPermissions()` _(iOS only)_
 
-Prompts the user for local-notification permissions. Safe to call on Android (no-op).
+Requests local notification permissions.
 
 Returns `Promise<string>`.
 
-```ts
-await requestNotificationPermissions();
-```
-
 ---
 
 ### Event Listeners
 
 #### `addBeaconsRangedListener(callback)`
 
-Fires approximately every second while beacons are within `maxDetectionDistance`.
+Fires when nearby items are detected (approximately every second).
 
 ```ts
-const subscription = addBeaconsRangedListener(({ beacons, region }) => {
-  beacons.forEach((b) => {
-    console.log(`${b.uuid} — ${b.distance.toFixed(1)} m (${b.proximity})`);
+const sub = addBeaconsRangedListener(({ beacons }) => {
+  beacons.forEach((item) => {
+    console.log(`${item.distance.toFixed(1)} m — ${item.proximity}`);
   });
 });
 
-// When done:
-subscription.remove();
+sub.remove(); // when done
 ```
 
-**Callback payload — `BeaconRangedEvent`:**
-
-| Field     | Type           | Description              |
-| --------- | -------------- | ------------------------ |
-| `beacons` | `BeaconData[]` | Array of visible beacons |
-| `region`  | `string`       | Beacon region identifier |
-
-**`BeaconData`:**
+Each item contains:
 
 | Field       | Type     | Description                                         |
 | ----------- | -------- | --------------------------------------------------- |
-| `uuid`      | `string` | Proximity UUID                                      |
-| `major`     | `number` | Major value                                         |
-| `minor`     | `number` | Minor value                                         |
 | `distance`  | `number` | Estimated distance in metres                        |
-| `rssi`      | `number` | Signal strength (dBm)                               |
 | `proximity` | `string` | `'immediate'` \| `'near'` \| `'far'` \| `'unknown'` |
 
 ---
 
 #### `addBeaconRegionListener(callback)`
 
-Fires on region enter, exit, and state-determination events. Works in **foreground, background, and terminated state** (iOS).
+Fires when the user enters or exits a zone. Works in foreground, background, and terminated state (iOS).
 
 ```ts
-const subscription = addBeaconRegionListener(({ region, event, state }) => {
-  if (event === 'enter') console.log('Entered', region);
-  if (event === 'exit') console.log('Exited', region);
+const sub = addBeaconRegionListener(({ event, region, state }) => {
+  console.log(event, region); // 'enter' | 'exit' | 'determined'
 });
 
-// When done:
-subscription.remove();
+sub.remove(); // when done
 ```
 
-**Callback payload — `BeaconRegionEvent`:**
-
 | Field    | Type     | Description                                                |
 | -------- | -------- | ---------------------------------------------------------- |
-| `region` | `string` | Region identifier                                          |
 | `event`  | `string` | `'enter'` \| `'exit'` \| `'determined'`                    |
+| `region` | `string` | Zone identifier                                            |
 | `state`  | `string` | `'inside'` \| `'outside'` \| `'unknown'` (determined only) |
 
 ---
 
-### Debounce Helpers
-
-These let you tune how often repeated proximity events are emitted for the same beacon.
-
-#### `setDebounceInterval(seconds)`
-
-Sets the minimum gap (in seconds) between proximity events for the same beacon.
-
-```ts
-await setDebounceInterval(30); // fire at most once per 30 s per beacon
-```
-
-#### `clearDebounceCache()`
-
-Resets cooldown state for all beacons, allowing them to fire again immediately.
-
-```ts
-await clearDebounceCache();
-```
-
-#### `getDebounceStatus()`
-
-Returns the current cooldown state for all tracked beacons.
-
-```ts
-const status = await getDebounceStatus();
-console.log(status);
-```
-
----
-
 ### Debug Helpers
 
 #### `getDebugLogs()`
 
-Reads the on-device debug log file.
-
-```ts
-const logs = await getDebugLogs();
-console.log(logs);
-```
+Returns on-device debug logs as a string.
 
 #### `clearDebugLogs()`
 
-Deletes the on-device debug log file.
-
-```ts
-await clearDebugLogs();
-```
-
----
-
-## TypeScript Types
-
-```ts
-import type {
-  BeaconData,
-  BeaconRangedEvent,
-  BeaconRegionEvent,
-  SpotnySdkConfig,
-} from 'spotny-sdk';
-```
+Clears on-device debug logs.
 
 ---
 
@@ -301,7 +214,7 @@ import type {
 
 | Feature                  | iOS | Android |
 | ------------------------ | --- | ------- |
-| Region monitoring        | ✅  | ✅      |
+| Zone monitoring          | ✅  | ✅      |
 | Background scanning      | ✅  | ✅      |
 | Terminated-state wakeup  | ✅  | ✅      |
 | Notification permissions | ✅  | –       |

package/ios/SpotnyBeaconScanner.swift

@@ -11,6 +11,7 @@ import Foundation
 import CoreLocation
 import KontaktSDK
 import UserNotifications
+import Security
 
 // MARK: - Public ObjC-visible typealias for the event callback block
 
@@ -69,6 +70,7 @@ public class SpotnyBeaconScanner: NSObject {
   private var lastImpressionEventSent:      [String: Date]         = [:]
   private var lastCampaignFetchAttempt:     [String: Date]         = [:]
   private var fetchInProgress:              [String: Bool]         = [:]
+  private var fetchRetryCount:              [String: Int]          = [:]
   private var proximityEventInProgress:     [String: Bool]         = [:]
   private var impressionEventInProgress:    [String: Bool]         = [:]
 
@@ -227,6 +229,7 @@ public class SpotnyBeaconScanner: NSObject {
   ) {
     lastCampaignFetchAttempt.removeAll()
     fetchInProgress.removeAll()
+    fetchRetryCount.removeAll()
     resolve("Debounce cache cleared")
   }
 
@@ -302,13 +305,51 @@ public class SpotnyBeaconScanner: NSObject {
 
   private func beaconKey(major: Int, minor: Int) -> String { "\(major)_\(minor)" }
 
+  // ── Keychain helpers (device ID survives uninstall/reinstall) ──────────────
+  private let keychainService = "app.spotny.sdk"
+
+  private func keychainRead(key: String) -> String? {
+    let query: [CFString: Any] = [
+      kSecClass:       kSecClassGenericPassword,
+      kSecAttrService: keychainService,
+      kSecAttrAccount: key,
+      kSecReturnData:  true,
+      kSecMatchLimit:  kSecMatchLimitOne
+    ]
+    var result: AnyObject?
+    guard SecItemCopyMatching(query as CFDictionary, &result) == errSecSuccess,
+          let data = result as? Data else { return nil }
+    return String(data: data, encoding: .utf8)
+  }
+
+  private func keychainWrite(key: String, value: String) {
+    guard let data = value.data(using: .utf8) else { return }
+    let query: [CFString: Any] = [
+      kSecClass:       kSecClassGenericPassword,
+      kSecAttrService: keychainService,
+      kSecAttrAccount: key
+    ]
+    if SecItemCopyMatching(query as CFDictionary, nil) == errSecSuccess {
+      SecItemUpdate(query as CFDictionary, [kSecValueData: data] as CFDictionary)
+    } else {
+      var item = query; item[kSecValueData] = data
+      SecItemAdd(item as CFDictionary, nil)
+    }
+  }
+
   private func getDeviceId() -> String {
-    if let stored = UserDefaults.standard.string(forKey: "SpotnySDK_deviceId") {
-      return stored
+    let kcKey = "SpotnySDK_deviceId"
+    // 1. Keychain — survives uninstall
+    if let stored = keychainRead(key: kcKey) { return stored }
+    // 2. Migrate existing UserDefaults value on first run after upgrade
+    if let legacy = UserDefaults.standard.string(forKey: kcKey) {
+      keychainWrite(key: kcKey, value: legacy)
+      UserDefaults.standard.removeObject(forKey: kcKey)
+      return legacy
     }
+    // 3. Generate new ID
     let id = UIDevice.current.identifierForVendor?.uuidString ?? UUID().uuidString
-    UserDefaults.standard.set(id, forKey: "SpotnySDK_deviceId")
-    UserDefaults.standard.synchronize()
+    keychainWrite(key: kcKey, value: id)
     return id
   }
 
@@ -375,13 +416,22 @@ public class SpotnyBeaconScanner: NSObject {
 
   // MARK: - Campaign Fetching
 
+  /// Exponential cooldown: 5 s → 15 s → 45 s. After 3 failures the key is
+  /// considered permanently failed until the beacon region is re-entered.
+  private func fetchCooldown(for key: String) -> TimeInterval {
+    let retries = fetchRetryCount[key] ?? 0
+    return campaignFetchCooldown * pow(3.0, Double(min(retries, 3)))
+  }
+
   private func fetchCampaign(major: Int, minor: Int, deviceId: String) {
     let key = beaconKey(major: major, minor: minor)
     guard activeCampaigns[key] == nil else { return }
     guard fetchInProgress[key] != true else { return }
+    // Give up after 3 consecutive failures (cooldown would be 135 s+)
+    if (fetchRetryCount[key] ?? 0) > 3 { return }
 
     if let last = lastCampaignFetchAttempt[key],
-       Date().timeIntervalSince(last) < campaignFetchCooldown { return }
+       Date().timeIntervalSince(last) < fetchCooldown(for: key) { return }
 
     lastCampaignFetchAttempt[key] = Date()
     fetchInProgress[key] = true
@@ -398,6 +448,8 @@ public class SpotnyBeaconScanner: NSObject {
         if case .success(let (s, _)) = result {
           print("❌ SpotnySDK: Campaign fetch status \(s) for beacon \(key)")
         }
+        // Increment retry count so next attempt uses a longer cooldown
+        self.fetchRetryCount[key] = (self.fetchRetryCount[key] ?? 0) + 1
         return
       }
       do {
@@ -418,6 +470,7 @@ public class SpotnyBeaconScanner: NSObject {
         self.activeCampaigns[key] = CampaignData(
           campaignId: campaignId, screenId: screenId,
           sessionId: nil, inQueue: inQueue, major: major, minor: minor)
+        self.fetchRetryCount.removeValue(forKey: key)  // reset on success
         print("✅ SpotnySDK: Campaign loaded for beacon \(key) — screenId=\(screenId)")
       } catch {
         print("❌ SpotnySDK: JSON parse error for beacon \(key): \(error)")
@@ -517,6 +570,7 @@ public class SpotnyBeaconScanner: NSObject {
     lastImpressionEventSent.removeValue(forKey: key)
     lastCampaignFetchAttempt.removeValue(forKey: key)
     fetchInProgress.removeValue(forKey: key)
+    fetchRetryCount.removeValue(forKey: key)
     proximityEventInProgress.removeValue(forKey: key)
     impressionEventInProgress.removeValue(forKey: key)
     print("🧹 SpotnySDK: Cleaned up state for beacon \(key)")
@@ -630,7 +684,9 @@ extension SpotnyBeaconScanner: KTKBeaconManagerDelegate {
     let parts = region.identifier.components(separatedBy: "_")
     if parts.count == 3, let major = Int(parts[1]), let minor = Int(parts[2]) {
       let key = beaconKey(major: major, minor: minor)
+      // Reset fetch state on re-entry so retry backoff starts fresh
       lastCampaignFetchAttempt.removeValue(forKey: key)
+      fetchRetryCount.removeValue(forKey: key)
       if activeCampaigns[key] == nil {
         fetchCampaign(major: major, minor: minor, deviceId: getDeviceId())
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spotny-sdk",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Beacon Scanner",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",