spotny-sdk 0.2.0

package/ios/SpotnyBeaconScanner.swift

@@ -0,0 +1,681 @@
+//
+//  SpotnyBeaconScanner.swift
+//  SpotnySdk
+//
+//  Core iBeacon scanning logic using Kontakt.io SDK.
+//  Handles campaign fetching and proximity / impression tracking against
+//  the Spotny backend.
+//
+
+import Foundation
+import CoreLocation
+import KontaktSDK
+import UserNotifications
+
+// MARK: - Public ObjC-visible typealias for the event callback block
+
+public typealias SpotnyEventCallback = @convention(block) (_ name: String, _ body: [String: Any]) -> Void
+
+// MARK: - Internal data structures
+
+private struct CampaignData {
+  let campaignId: Int?    // nil when no active campaign
+  let screenId: Int
+  let sessionId: String?  // set after first proximity response
+  let inQueue: Bool       // campaign is queued — skip impressions
+  let major: Int
+  let minor: Int
+}
+
+// MARK: - SpotnyBeaconScanner
+
+@objc(SpotnyBeaconScanner)
+public class SpotnyBeaconScanner: NSObject {
+
+  // ── Callback to send events back to SpotnySdk.mm ─────────────────────────
+  private var eventCallback: SpotnyEventCallback?
+
+  // ── Managers ──────────────────────────────────────────────────────────────
+  private var beaconManager: KTKBeaconManager!
+  private var locationManager: CLLocationManager!
+
+  // ── Session state ─────────────────────────────────────────────────────────
+  private var currentUserUUID: String?
+  private var userId: Int?
+  private var scanning: Bool = false
+
+  // ── Configuration (overridable via configure()) ────────────────────────────
+  private var backendURL: String = "https://api.spotny.app"
+  private var maxDetectionDistance: Double = 8.0
+  private var kontaktAPIKey: String = "mgrz08TOKNHafeY02cWIs9mxUHbynNQJ"
+
+  // ── Beacon UUID (standard Kontakt.io default) ─────────────────────────────
+  private let beaconUUID = UUID(uuidString: "f7826da6-4fa2-4e98-8024-bc5b71e0893e")!
+
+  // ── Timing constants ──────────────────────────────────────────────────────
+  private let campaignFetchCooldown: TimeInterval    = 5.0
+  private let proximityDistanceThreshold: Double     = 0.75
+  private let impressionEventInterval: TimeInterval  = 10.0
+  private let impressionDistance: Double             = 2.0
+  private var debounceInterval: TimeInterval         = 5.0
+
+  // ── Per-beacon tracking state ──────────────────────────────────────────────
+  private var activeCampaigns:              [String: CampaignData] = [:]
+  private var lastProximityEventSent:       [String: Date]         = [:]
+  private var lastProximityDistance:        [String: Double]       = [:]
+  private var lastImpressionEventSent:      [String: Date]         = [:]
+  private var lastCampaignFetchAttempt:     [String: Date]         = [:]
+  private var fetchInProgress:              [String: Bool]         = [:]
+  private var proximityEventInProgress:     [String: Bool]         = [:]
+  private var impressionEventInProgress:    [String: Bool]         = [:]
+
+  // MARK: - Init
+
+  @objc
+  public init(eventCallback: @escaping SpotnyEventCallback) {
+    self.eventCallback = eventCallback
+    super.init()
+    setupManagers()
+    resumeStoredSession()
+  }
+
+  // MARK: - Setup
+
+  private func setupManagers() {
+    // Initialise the Kontakt.io SDK with the API key before creating any manager
+    Kontakt.setAPIKey(kontaktAPIKey)
+    print("✅ SpotnySDK: Kontakt.io SDK initialised")
+
+    locationManager = CLLocationManager()
+    locationManager.delegate = self
+    locationManager.allowsBackgroundLocationUpdates = true
+    locationManager.pausesLocationUpdatesAutomatically = false
+
+    beaconManager = KTKBeaconManager(delegate: self)
+  }
+
+  private func resumeStoredSession() {
+    guard let stored = UserDefaults.standard.string(forKey: "SpotnySDK_userUUID") else { return }
+    currentUserUUID = stored
+    userId = UserDefaults.standard.object(forKey: "SpotnySDK_userId") as? Int
+    print("🔄 SpotnySDK: Resuming session for UUID: \(stored)")
+    startPersistentScanning()
+    scanning = true
+  }
+
+  // MARK: - ObjC-Exposed Methods (called from SpotnySdk.mm)
+
+  @objc
+  public func startScanner(
+    withUserUUID userUUID: String,
+    userId: NSNumber?,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    if scanning {
+      resolve("Already scanning")
+      return
+    }
+
+    currentUserUUID = userUUID
+    self.userId = userId?.intValue
+
+    UserDefaults.standard.set(userUUID, forKey: "SpotnySDK_userUUID")
+    if let uid = userId {
+      UserDefaults.standard.set(uid.intValue, forKey: "SpotnySDK_userId")
+    } else {
+      UserDefaults.standard.removeObject(forKey: "SpotnySDK_userId")
+    }
+    UserDefaults.standard.synchronize()
+
+    let status = locationManager.authorizationStatus
+    if status == .notDetermined {
+      locationManager.requestAlwaysAuthorization()
+    }
+
+    startPersistentScanning()
+    scanning = true
+    print("✅ SpotnySDK: Started scanning for \(userUUID)")
+    resolve("Scanning started")
+  }
+
+  @objc
+  public func stopScanner(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    beaconManager.stopMonitoringForAllRegions()
+    beaconManager.stopRangingBeaconsInAllRegions()
+    cleanupAllProximityState()
+
+    UserDefaults.standard.removeObject(forKey: "SpotnySDK_userUUID")
+    UserDefaults.standard.removeObject(forKey: "SpotnySDK_userId")
+    UserDefaults.standard.synchronize()
+
+    scanning = false
+    currentUserUUID = nil
+    userId = nil
+
+    print("⏹️ SpotnySDK: Stopped scanning")
+    resolve("Scanning stopped")
+  }
+
+  @objc
+  public func isScanning(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    resolve(scanning)
+  }
+
+  @objc
+  public func configure(
+    with config: NSDictionary,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    if let url = config["backendURL"] as? String {
+      backendURL = url
+      print("⚙️ SpotnySDK: backendURL = \(url)")
+    }
+    if let dist = config["maxDetectionDistance"] as? Double {
+      maxDetectionDistance = dist
+      print("⚙️ SpotnySDK: maxDetectionDistance = \(dist)m")
+    }
+    if let key = config["kontaktAPIKey"] as? String {
+      kontaktAPIKey = key
+      Kontakt.setAPIKey(key)
+      print("⚙️ SpotnySDK: Kontakt.io API key updated")
+    }
+    resolve("Configuration updated")
+  }
+
+  @objc
+  public func requestNotificationPermissions(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
+      DispatchQueue.main.async {
+        if let error = error {
+          reject("PERMISSION_ERROR", error.localizedDescription, error)
+        } else {
+          resolve(granted ? "granted" : "denied")
+        }
+      }
+    }
+  }
+
+  @objc
+  public func setDebounceInterval(
+    _ interval: Double,
+    resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    debounceInterval = interval
+    resolve("Debounce interval set to \(interval)s")
+  }
+
+  @objc
+  public func clearDebounceCache(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    lastCampaignFetchAttempt.removeAll()
+    fetchInProgress.removeAll()
+    resolve("Debounce cache cleared")
+  }
+
+  @objc
+  public func getDebounceStatus(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    var status: [String: Any] = [:]
+    for (key, _) in activeCampaigns {
+      var entry: [String: Any] = [:]
+      if let lastFetch = lastCampaignFetchAttempt[key] {
+        entry["lastFetchAttempt"] = lastFetch.timeIntervalSince1970
+      }
+      if let inProg = fetchInProgress[key] {
+        entry["fetchInProgress"] = inProg
+      }
+      if let lastProx = lastProximityEventSent[key] {
+        entry["lastProximityEvent"] = lastProx.timeIntervalSince1970
+      }
+      if let lastImp = lastImpressionEventSent[key] {
+        entry["lastImpressionEvent"] = lastImp.timeIntervalSince1970
+      }
+      status[key] = entry
+    }
+    resolve(status)
+  }
+
+  // MARK: - Debug Logging
+
+  @objc
+  public func getDebugLogs(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else {
+      reject("ERROR", "Cannot access documents directory", nil); return
+    }
+    let logURL = docsURL.appendingPathComponent("spotny_beacon_debug.log")
+    resolve((try? String(contentsOf: logURL, encoding: .utf8)) ?? "No logs found")
+  }
+
+  @objc
+  public func clearDebugLogs(
+    withResolve resolve: @escaping RCTPromiseResolveBlock,
+    reject: @escaping RCTPromiseRejectBlock
+  ) {
+    guard let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else {
+      reject("ERROR", "Cannot access documents directory", nil); return
+    }
+    try? FileManager.default.removeItem(at: docsURL.appendingPathComponent("spotny_beacon_debug.log"))
+    resolve("Logs cleared")
+  }
+
+  // MARK: - Scanning Setup
+
+  private func startPersistentScanning() {
+    print("🚀 SpotnySDK: Starting persistent beacon scanning…")
+
+    // General region — monitors all beacons with the Kontakt.io UUID
+    let generalRegion = KTKBeaconRegion(proximityUUID: beaconUUID, identifier: "SpotnySDK_GeneralRegion")
+    generalRegion.notifyOnEntry = true
+    generalRegion.notifyOnExit  = true
+    generalRegion.notifyEntryStateOnDisplay = true
+
+    beaconManager.startMonitoring(for: generalRegion)
+    beaconManager.startRangingBeacons(in: generalRegion)
+
+    print("🎯 SpotnySDK: Monitoring UUID \(beaconUUID.uuidString)")
+  }
+
+  // MARK: - Helpers
+
+  private func beaconKey(major: Int, minor: Int) -> String { "\(major)_\(minor)" }
+
+  private func getDeviceId() -> String {
+    if let stored = UserDefaults.standard.string(forKey: "SpotnySDK_deviceId") {
+      return stored
+    }
+    let id = UIDevice.current.identifierForVendor?.uuidString ?? UUID().uuidString
+    UserDefaults.standard.set(id, forKey: "SpotnySDK_deviceId")
+    UserDefaults.standard.synchronize()
+    return id
+  }
+
+  private func proximityLabel(from distance: Double) -> String {
+    if distance < 0    { return "unknown"   }
+    if distance < 0.5  { return "immediate" }
+    if distance < 3.0  { return "near"      }
+    return "far"
+  }
+
+  private func logToFile(_ message: String) {
+    guard let docsURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first else { return }
+    let logURL = docsURL.appendingPathComponent("spotny_beacon_debug.log")
+    let ts = DateFormatter.localizedString(from: Date(), dateStyle: .short, timeStyle: .medium)
+    let entry = "[\(ts)] \(message)\n"
+    guard let data = entry.data(using: .utf8) else { return }
+    if FileManager.default.fileExists(atPath: logURL.path),
+       let handle = try? FileHandle(forWritingTo: logURL) {
+      handle.seekToEndOfFile(); handle.write(data); handle.closeFile()
+    } else {
+      try? data.write(to: logURL)
+    }
+  }
+
+  // MARK: - Backend API
+
+  private func post(
+    endpoint: String,
+    payload: [String: Any],
+    completion: @escaping (Result<(Int, Data), Error>) -> Void
+  ) {
+    guard let url = URL(string: "\(backendURL)\(endpoint)") else {
+      completion(.failure(NSError(domain: "SpotnySDK", code: -1,
+        userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(backendURL)\(endpoint)"])))
+      return
+    }
+    var req = URLRequest(url: url)
+    req.httpMethod = "POST"
+    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+    req.timeoutInterval = 10.0
+
+    var bg: UIBackgroundTaskIdentifier = .invalid
+    bg = UIApplication.shared.beginBackgroundTask { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+
+    do {
+      req.httpBody = try JSONSerialization.data(withJSONObject: payload)
+    } catch {
+      UIApplication.shared.endBackgroundTask(bg)
+      completion(.failure(error)); return
+    }
+
+    URLSession.shared.dataTask(with: req) { data, response, error in
+      DispatchQueue.main.async {
+        if bg != .invalid { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+        if let error = error { completion(.failure(error)); return }
+        guard let http = response as? HTTPURLResponse, let data = data else {
+          completion(.failure(NSError(domain: "SpotnySDK", code: -2,
+            userInfo: [NSLocalizedDescriptionKey: "Bad response"]))); return
+        }
+        completion(.success((http.statusCode, data)))
+      }
+    }.resume()
+  }
+
+  // MARK: - Campaign Fetching
+
+  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 }
+
+    if let last = lastCampaignFetchAttempt[key],
+       Date().timeIntervalSince(last) < campaignFetchCooldown { return }
+
+    lastCampaignFetchAttempt[key] = Date()
+    fetchInProgress[key] = true
+
+    var payload: [String: Any] = ["beacon_id": key, "device_id": deviceId]
+    if let uid = userId { payload["user_id"] = uid }
+
+    post(endpoint: "/api/app/campaigns/beacon", payload: payload) { [weak self] result in
+      guard let self = self else { return }
+      defer { self.fetchInProgress[key] = false }
+
+      guard case .success(let (status, data)) = result, status == 200 else {
+        if case .success(let (s, _)) = result {
+          print("❌ SpotnySDK: Campaign fetch status \(s) for beacon \(key)")
+        }
+        return
+      }
+      do {
+        guard let json = try JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let dataObj = json["data"]     as? [String: Any],
+              let screen  = dataObj["screen"] as? [String: Any],
+              let screenId = screen["id"]    as? Int else {
+          print("⚠️ SpotnySDK: Unexpected campaign response format for \(key)")
+          return
+        }
+        var campaignId: Int?
+        var inQueue = false
+        if let campaignObj = dataObj["campaign"] as? [String: Any],
+           let cid = campaignObj["id"] as? Int {
+          campaignId = cid
+          inQueue = campaignObj["inQueue"] as? Bool ?? false
+        }
+        self.activeCampaigns[key] = CampaignData(
+          campaignId: campaignId, screenId: screenId,
+          sessionId: nil, inQueue: inQueue, major: major, minor: minor)
+        print("✅ SpotnySDK: Campaign loaded for beacon \(key) — screenId=\(screenId)")
+      } catch {
+        print("❌ SpotnySDK: JSON parse error for beacon \(key): \(error)")
+      }
+    }
+  }
+
+  // MARK: - Tracking
+
+  private func sendTracking(
+    eventType: String,
+    key: String,
+    distance: Double,
+    deviceId: String,
+    endpoint: String
+  ) {
+    let isImpression = eventType == "IMPRESSION_HEARTBEAT"
+    let inProg = isImpression ? impressionEventInProgress[key] : proximityEventInProgress[key]
+    guard inProg != true else { return }
+
+    if isImpression { impressionEventInProgress[key] = true }
+    else            { proximityEventInProgress[key]  = true }
+
+    guard let campaign = activeCampaigns[key] else {
+      if isImpression { impressionEventInProgress[key] = false }
+      else            { proximityEventInProgress[key]  = false }
+      return
+    }
+    if isImpression {
+      guard let _ = campaign.campaignId, !campaign.inQueue else {
+        impressionEventInProgress[key] = false; return
+      }
+    }
+
+    var payload: [String: Any] = [
+      "event_type": eventType,
+      "device_id":  deviceId,
+      "distance":   distance,
+      "screen_id":  campaign.screenId
+    ]
+    if let cid = campaign.campaignId  { payload["campaign_id"] = cid }
+    if let sid = campaign.sessionId   { payload["session_id"]  = sid }
+    if let uid = userId               { payload["user_id"]     = uid }
+
+    post(endpoint: endpoint, payload: payload) { [weak self] result in
+      guard let self = self else { return }
+      switch result {
+      case .success(let (status, data)):
+        if 200...299 ~= status {
+          print("✅ SpotnySDK: \(eventType) sent — distance \(String(format: "%.2f", distance))m")
+          if !isImpression, campaign.sessionId == nil,
+             let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+             let dObj = json["data"] as? [String: Any],
+             let ev   = dObj["event"] as? [String: Any],
+             let sid  = ev["session_id"] as? String {
+            let updated = CampaignData(
+              campaignId: campaign.campaignId, screenId: campaign.screenId,
+              sessionId: sid, inQueue: campaign.inQueue,
+              major: campaign.major, minor: campaign.minor)
+            self.activeCampaigns[key] = updated
+            print("✅ SpotnySDK: session_id = \(sid)")
+          }
+        } else if status == 429 {
+          let penalty = Date().addingTimeInterval(10)
+          if isImpression { self.lastImpressionEventSent[key] = penalty }
+          else            { self.lastProximityEventSent[key]  = penalty }
+          print("⚠️ SpotnySDK: \(eventType) rate-limited (429)")
+        } else {
+          print("❌ SpotnySDK: \(eventType) failed — status \(status)")
+        }
+      case .failure(let error):
+        print("❌ SpotnySDK: \(eventType) error — \(error.localizedDescription)")
+      }
+      if isImpression { self.impressionEventInProgress[key] = false }
+      else            { self.proximityEventInProgress[key]  = false }
+    }
+  }
+
+  private func sendProximity(eventType: String, key: String, distance: Double, deviceId: String) {
+    sendTracking(eventType: eventType, key: key, distance: distance,
+                 deviceId: deviceId, endpoint: "/api/app/impressions/proximity")
+  }
+
+  private func sendImpression(key: String, distance: Double, deviceId: String) {
+    sendTracking(eventType: "IMPRESSION_HEARTBEAT", key: key, distance: distance,
+                 deviceId: deviceId, endpoint: "/api/app/impressions/track")
+  }
+
+  // MARK: - State Cleanup
+
+  private func cleanupBeacon(_ key: String, deviceId: String, distance: Double = 0) {
+    sendProximity(eventType: "PROXIMITY_EXIT", key: key, distance: distance, deviceId: deviceId)
+    activeCampaigns.removeValue(forKey: key)
+    lastProximityEventSent.removeValue(forKey: key)
+    lastProximityDistance.removeValue(forKey: key)
+    lastImpressionEventSent.removeValue(forKey: key)
+    lastCampaignFetchAttempt.removeValue(forKey: key)
+    fetchInProgress.removeValue(forKey: key)
+    proximityEventInProgress.removeValue(forKey: key)
+    impressionEventInProgress.removeValue(forKey: key)
+    print("🧹 SpotnySDK: Cleaned up state for beacon \(key)")
+  }
+
+  private func cleanupAllProximityState() {
+    let deviceId = getDeviceId()
+    for key in activeCampaigns.keys { cleanupBeacon(key, deviceId: deviceId) }
+  }
+}
+
+// MARK: - CLLocationManagerDelegate
+
+extension SpotnyBeaconScanner: CLLocationManagerDelegate {
+  public func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus) {
+    switch status {
+    case .authorizedAlways:    print("✅ SpotnySDK: Location → ALWAYS")
+    case .authorizedWhenInUse: print("⚠️ SpotnySDK: Location → WHEN IN USE (limited background)")
+    case .denied, .restricted: print("❌ SpotnySDK: Location → DENIED")
+    case .notDetermined:       print("⏳ SpotnySDK: Location → not determined")
+    @unknown default:          break
+    }
+  }
+}
+
+// MARK: - KTKBeaconManagerDelegate
+
+extension SpotnyBeaconScanner: KTKBeaconManagerDelegate {
+
+  public func beaconManager(
+    _ manager: KTKBeaconManager,
+    didRangeBeacons beacons: [CLBeacon],
+    in region: KTKBeaconRegion
+  ) {
+    let deviceId = getDeviceId()
+    let now = Date()
+
+    // Build the JS event payload for ALL ranged beacons
+    let beaconPayload: [[String: Any]] = beacons.compactMap { beacon in
+      let raw = beacon.accuracy
+      let adjusted = raw * 0.5  // compensate for low TX power (-12 dBm)
+      guard adjusted > 0 && adjusted <= maxDetectionDistance else { return nil }
+      return [
+        "uuid":      beacon.proximityUUID.uuidString,
+        "major":     beacon.major.intValue,
+        "minor":     beacon.minor.intValue,
+        "distance":  adjusted,
+        "rssi":      beacon.rssi,
+        "proximity": proximityLabel(from: adjusted)
+      ]
+    }
+
+    if !beaconPayload.isEmpty {
+      eventCallback?("onBeaconsRanged", ["beacons": beaconPayload, "region": region.identifier])
+    }
+
+    // Per-beacon campaign & proximity logic
+    for beacon in beacons {
+      let major     = beacon.major.intValue
+      let minor     = beacon.minor.intValue
+      let key       = beaconKey(major: major, minor: minor)
+      let raw       = beacon.accuracy
+      let distance  = raw * 0.5
+
+      guard distance > 0 && distance <= maxDetectionDistance else { continue }
+
+      if let campaign = activeCampaigns[key] {
+        let isFirst = lastProximityEventSent[key] == nil
+
+        if isFirst {
+          sendProximity(eventType: "NEARBY", key: key, distance: distance, deviceId: deviceId)
+          lastProximityDistance[key] = distance
+          lastProximityEventSent[key] = now
+        } else if distance >= 1.0,
+                  let lastDist = lastProximityDistance[key],
+                  abs(distance - lastDist) >= proximityDistanceThreshold {
+          sendProximity(eventType: "NEARBY", key: key, distance: distance, deviceId: deviceId)
+          lastProximityDistance[key] = distance
+          lastProximityEventSent[key] = now
+        }
+
+        // Impression heartbeat when user is very close
+        if let _ = campaign.campaignId, !campaign.inQueue, distance <= impressionDistance {
+          if let last = lastImpressionEventSent[key] {
+            if now.timeIntervalSince(last) >= impressionEventInterval {
+              sendImpression(key: key, distance: distance, deviceId: deviceId)
+              lastImpressionEventSent[key] = now
+            }
+          } else {
+            sendImpression(key: key, distance: distance, deviceId: deviceId)
+            lastImpressionEventSent[key] = now
+          }
+        }
+      } else {
+        fetchCampaign(major: major, minor: minor, deviceId: deviceId)
+      }
+    }
+  }
+
+  public func beaconManager(_ manager: KTKBeaconManager, didEnter region: KTKBeaconRegion) {
+    print("🎯 SpotnySDK: Entered region \(region.identifier)")
+
+    eventCallback?("onBeaconRegionEvent", ["region": region.identifier, "event": "enter"])
+
+    var bg: UIBackgroundTaskIdentifier = .invalid
+    bg = UIApplication.shared.beginBackgroundTask { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+
+    beaconManager.startRangingBeacons(in: region)
+
+    // Parse major/minor from named regions (e.g. "SpotnySDK_52885_35127")
+    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)
+      lastCampaignFetchAttempt.removeValue(forKey: key)
+      if activeCampaigns[key] == nil {
+        fetchCampaign(major: major, minor: minor, deviceId: getDeviceId())
+      }
+    }
+
+    DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) {
+      if bg != .invalid { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+    }
+  }
+
+  public func beaconManager(_ manager: KTKBeaconManager, didExitRegion region: KTKBeaconRegion) {
+    print("🚪 SpotnySDK: Exited region \(region.identifier)")
+
+    eventCallback?("onBeaconRegionEvent", ["region": region.identifier, "event": "exit"])
+
+    var bg: UIBackgroundTaskIdentifier = .invalid
+    bg = UIApplication.shared.beginBackgroundTask { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+
+    let parts = region.identifier.components(separatedBy: "_")
+    if parts.count == 3, let major = Int(parts[1]), let minor = Int(parts[2]) {
+      cleanupBeacon(beaconKey(major: major, minor: minor), deviceId: getDeviceId())
+    }
+
+    beaconManager.stopRangingBeacons(in: region)
+
+    DispatchQueue.main.asyncAfter(deadline: .now() + 2.0) {
+      if bg != .invalid { UIApplication.shared.endBackgroundTask(bg); bg = .invalid }
+    }
+  }
+
+  public func beaconManager(
+    _ manager: KTKBeaconManager,
+    didDetermineState state: CLRegionState,
+    for region: KTKBeaconRegion
+  ) {
+    let label: String
+    switch state {
+    case .inside:  label = "inside"
+    case .outside: label = "outside"
+    case .unknown: label = "unknown"
+    @unknown default: label = "unknown"
+    }
+    eventCallback?("onBeaconRegionEvent", ["region": region.identifier, "event": "determined", "state": label])
+    print("📊 SpotnySDK: Region \(region.identifier) → \(label)")
+  }
+
+  public func beaconManager(
+    _ manager: KTKBeaconManager,
+    monitoringDidFailFor region: KTKBeaconRegion?,
+    withError error: Error?
+  ) {
+    print("❌ SpotnySDK: Monitoring failed for \(region?.identifier ?? "?") — \(error?.localizedDescription ?? "unknown error")")
+  }
+}

package/ios/SpotnySdk-Bridging-Header.h

@@ -0,0 +1,8 @@
+//
+//  SpotnySdk-Bridging-Header.h
+//  Makes React Native and Kontakt.io SDK types visible to Swift.
+//
+
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+#import <KontaktSDK/KontaktSDK.h>

package/ios/SpotnySdk.h

@@ -0,0 +1,10 @@
+#import <SpotnySdkSpec/SpotnySdkSpec.h>
+#import <React/RCTEventEmitter.h>
+
+/**
+ * SpotnySdk is both a Turbo Module (NativeSpotnySdkSpec) and an RCTEventEmitter
+ * so it can push beacon events to JavaScript via NativeEventEmitter.
+ */
+@interface SpotnySdk : RCTEventEmitter <NativeSpotnySdkSpec>
+
+@end