therms-device-tracker 1.0.0-rc.1

package/ios/SyncManager.swift

@@ -0,0 +1,186 @@
+import Foundation
+
+/// Simple protocol for Sync data source seam (testability, mirrors GeofenceRegionMonitoring).
+/// Allows injecting mock stores in SyncManager tests without concrete LocationStore dep.
+/// Both batch and immediate use live getAll() at perform time.
+protocol SyncDataSource: AnyObject {
+  func getAll() -> [[String: Any]]
+}
+
+/// Focused manager for opt-in native background HTTP data sync.
+/// Mirrors GeofenceManager + ScheduleManager seams for consistency (callbacks, injection, testability).
+///
+/// Responsibilities:
+/// - Accept sync config (url, method, batch/immediate, interval, etc.) from JS via module.
+/// - Pull data from injected LocationStore (primarily locations; geofence data not included in sync payloads).
+/// - Perform native HTTP POST/PUT using URLSession (background config + temp file body for suspended/killed app durability).
+/// - Support immediate (on data) or periodic batch.
+/// - Emit via onSync callback (success/fail, count, etc.). No direct sendEvent coupling.
+///
+/// Key invariants (do not regress):
+/// - Live `getAll()` from the injected SyncDataSource at perform time for both batch and immediate.
+/// - Consumer responsibility: on success we only emit; caller decides to destroyLocations().
+/// - onSync callback only; module owns sendEvent.
+///
+/// This keeps ThermsDeviceTrackerModule thin. Callback pattern: owner (module) sets `onSync` closure;
+/// manager never calls sendEvent directly. See GeofenceManager/ScheduleManager for same seam.
+///
+/// Config (from ThermsConfig.sync):
+/// - enabled, url (required), method, headers, batch, interval, maxBatchSize.
+///
+/// Data: reuses persisted records from LocationStore (see insert/getAll). Module controls when
+/// to call syncNow() (e.g. after location insert if immediate, or on schedule heartbeat).
+///
+/// ---
+/// iOS PERIODIC BATCH LIMITATIONS + REQUIREMENTS (CRITICAL - READ):
+/// - **Current impl**: periodic batch uses a repeating `Timer` (scheduled in `start`). This ONLY fires
+///   while the app process is alive (foreground, or limited bg execution after user activity).
+///   It does NOT wake a suspended or terminated app.
+/// - **For true background periodic sync on iOS** (while suspended/killed):
+///   1. Ensure "Background fetch" capability / UIBackgroundModes includes "fetch" (config plugin adds this
+///      automatically when isIosBackgroundLocationEnabled, along with 'location').
+///   2. Pass `iosBackgroundTaskIdentifier` (e.g. "com.yourcompany.therms.sync") to the config plugin in app.json.
+///      The plugin (see plugin/src/index.ts + ThermsDeviceTrackerPluginProps) appends it to BGTaskSchedulerPermittedIdentifiers.
+///   3. In your AppDelegate (or SceneDelegate equivalent), BEFORE app finishes launching:
+///      `BGTaskScheduler.shared.register(forTaskWithIdentifier: "com.yourcompany.therms.sync", using: nil) { task in
+///         // Your handler: call into your extended module or use expo-task-manager + JS ThermsDeviceTracker.startSync().
+///         // Then: task.setTaskCompleted(success: true)
+///         // Optionally schedule next: let req = BGAppRefreshTaskRequest(identifier: ...); try? BGTaskScheduler.shared.submit(req)
+///      }`
+///      The identifier **must match exactly** the iosBackgroundTaskIdentifier supplied to the plugin.
+///   4. Submit a refresh task request from active code or prior handler.
+/// - The `performSync` itself *does* use a background-configured URLSession (uploadTask with temp file body), which CAN continue
+///   uploads even if the app is suspended/killed (OS will manage the session). But *scheduling* the batch
+///   call requires BGTaskScheduler (or the demo Timer).
+/// - See Apple "BGTaskScheduler", "Background Modes", "URLSessionConfiguration.background".
+/// - In practice for Expo apps, many use expo-task-manager or a host AppDelegate wrapper for registration.
+///   Without the above, batch falls back to Timer-only behavior.
+/// - Registration seam notes: See the full AppDelegate Swift example + expo-task-manager alternative in README.md
+///   ("iOS Background Sync..." section, which includes use of the identifier and cross-refs example/App.tsx).
+///   The example/App.tsx has explicit comments + small helper demonstrating registration using iosBackgroundTaskIdentifier.
+///   The module does not expose a public `shared` singleton or direct `syncManager` by default (thin coordinator design).
+///   For pure native BGTask handlers you would extend the native module yourself to add static access + a trigger.
+///   Recommended for Expo/JS apps: use expo-task-manager + ThermsDeviceTracker.startSync() (wakes JS, calls through public API).
+///   This triggers the manager (see example/App.tsx).
+/// ---
+final class SyncManager {
+  // Callback supplied by owner (module) for events like onSync.
+  // Pattern: consistent onSync callback (no direct sendEvent). Mirrors other *Manager seams.
+  var onSync: (([String: Any]) -> Void)?
+
+  // Injected for data access + test seams (like store in GeofenceManager).
+  private weak var store: SyncDataSource?
+
+  private var config: [String: Any]?
+  private var isEnabled = false
+  private var timer: Timer? // fallback/demo; real bg uses BGTaskScheduler
+
+  init(store: SyncDataSource? = nil) {
+    self.store = store
+  }
+
+  /// Start/configure sync. Called from module on ready/start when sync.enabled.
+  /// Mirrors scheduleManager.start(config).
+  func start(config: [String: Any]?) {
+    stop()
+    self.config = config
+    isEnabled = (config?["enabled"] as? Bool) ?? false
+    guard isEnabled, let url = config?["url"] as? String, !url.isEmpty else {
+      onSync?(["state": "disabled", "reason": "no url or disabled"])
+      return
+    }
+    onSync?(["state": "started", "url": url])
+
+    let batch = (config?["batch"] as? Bool) ?? true
+    if batch {
+      let interval = (config?["interval"] as? TimeInterval) ?? 60.0
+      // Demo/fallback periodic via Timer (process must be alive). See top-of-file CRITICAL section (updated)
+      // for full BGTaskScheduler + iosBackgroundTaskIdentifier (via plugin) + AppDelegate registration requirements
+      // to get OS bg periodic execution. (Without host registration, this Timer path is the only periodic mechanism.)
+      // Note: unlike Android WorkManager (15min min for periodic), Timer accepts small intervals here.
+      timer = Timer.scheduledTimer(withTimeInterval: interval, repeats: true) { [weak self] _ in
+        self?.performSync()
+      }
+    } else {
+      // Immediate mode: caller (module) should invoke syncNow() after data events.
+    }
+  }
+
+  func stop() {
+    timer?.invalidate()
+    timer = nil
+    isEnabled = false
+    config = nil
+    onSync?(["state": "stopped"])
+  }
+
+  /// Trigger a sync (called by module on location if immediate, or from schedule).
+  /// Pulls from store (locations primarily).
+  func syncNow() {
+    guard isEnabled else { return }
+    performSync()
+  }
+
+  private func performSync() {
+    guard let urlStr = config?["url"] as? String,
+          let url = URL(string: urlStr),
+          let store = store else { return }
+
+    let items = store.getAll()
+    guard !items.isEmpty else {
+      onSync?(["state": "noop", "count": 0])
+      return
+    }
+
+    let maxBatchSize = (config?["maxBatchSize"] as? Int) ?? 0
+    let payload: [[String: Any]] = maxBatchSize > 0 ? Array(items.prefix(maxBatchSize)) : items
+    // maxBatchSize <= 0 (or absent) means "send all available" (matches Android SyncWorker behavior).
+
+    let method = (config?["method"] as? String)?.uppercased() ?? "POST"
+    var req = URLRequest(url: url)
+    req.httpMethod = method
+    if let headers = config?["headers"] as? [String: String] {
+      for (k, v) in headers { req.setValue(v, forHTTPHeaderField: k) }
+    }
+    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+
+    // Serialize payload. For background URLSession uploads (esp. when app may suspend/kill),
+    // write to a temp file and use uploadTask(with:fromFile:) instead of in-memory body.
+    // This follows Apple guidance for background transfer service durability.
+    let fileURL: URL
+    do {
+      let bodyData = try JSONSerialization.data(withJSONObject: payload)
+      let tmpDir = FileManager.default.temporaryDirectory
+      fileURL = tmpDir.appendingPathComponent("therms-sync-\(UUID().uuidString).json")
+      try bodyData.write(to: fileURL)
+    } catch {
+      onSync?(["state": "error", "message": "serialize failed"])
+      return
+    }
+
+    // Use background-capable session for bg execution.
+    let bgConfig = URLSessionConfiguration.background(withIdentifier: "therms.sync.\(UUID().uuidString)")
+    let session = URLSession(configuration: bgConfig)
+
+    let task = session.uploadTask(with: req, fromFile: fileURL) { [weak self] data, response, error in
+      let httpResp = response as? HTTPURLResponse
+      let success = (error == nil) && (httpResp?.statusCode ?? 500) < 300
+      self?.onSync?([
+        "state": success ? "success" : "error",
+        "success": success,
+        "status": httpResp?.statusCode ?? -1,
+        "count": payload.count,
+        "message": error?.localizedDescription
+      ])
+
+      // Best-effort cleanup of temp body file (harmless if already removed).
+      try? FileManager.default.removeItem(at: fileURL)
+
+      if success {
+        // Best-effort: after successful send of batch prefix, caller/module can destroy if desired.
+        // For now emit; consumer decides (or future auto after ack).
+      }
+    }
+    task.resume()
+  }
+}

package/ios/ThermsDeviceTracker.podspec

@@ -0,0 +1,24 @@
+Pod::Spec.new do |s|
+  s.name           = 'ThermsDeviceTracker'
+  s.version        = '1.0.0'
+  s.summary        = 'Device physical activity and geolocation tracking for THERMS'
+  s.description    = 'Expo native module providing unified access to location updates, physical activity recognition (walking/running/etc), and pedometer data with foreground and background support.'
+  s.author         = 'Cory Robinson <cory@therms.io>'
+  s.homepage       = 'https://www.therms.io'
+  s.platforms      = {
+    :ios => '16.4',
+    :tvos => '16.4'
+  }
+  s.source         = { git: '' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  # Swift/Objective-C compatibility
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+  s.exclude_files = "**/*Tests.{swift,h,m,mm}"
+end