@use-voltra/ios-client 1.4.0 → 2.0.0-rc.1

package/ios/app/NativeVoltra.mm

@@ -0,0 +1,211 @@
+#import "NativeVoltra.h"
+
+#if __has_include("Voltra/Voltra-Swift.h")
+#import "Voltra/Voltra-Swift.h"
+#else
+#import "Voltra-Swift.h"
+#endif
+
+@interface NativeVoltra () {
+  VoltraModule *_module;
+}
+@end
+
+@implementation NativeVoltra
+
+- (void)setEventEmitterCallback:(EventEmitterCallbackWrapper *_Nonnull)eventEmitterCallbackWrapper
+{
+  [super setEventEmitterCallback:eventEmitterCallbackWrapper];
+
+  [self.module startMonitoringWithEventHandler:^(NSString *eventName, NSDictionary *eventData) {
+    if ([eventName isEqualToString:@"interaction"]) {
+      [self emitOnInteraction:eventData];
+    } else if ([eventName isEqualToString:@"stateChange"]) {
+      [self emitOnStateChanged:eventData];
+    } else if ([eventName isEqualToString:@"activityTokenReceived"]) {
+      [self emitOnActivityTokenReceived:eventData];
+    } else if ([eventName isEqualToString:@"activityPushToStartTokenReceived"]) {
+      [self emitOnActivityPushToStartTokenReceived:eventData];
+    }
+  }];
+}
+
+- (VoltraModule *)module
+{
+  if (!_module) {
+    _module = [VoltraModule new];
+  }
+  return _module;
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params
+{
+  return std::make_shared<facebook::react::NativeVoltraSpecJSI>(params);
+}
+
++ (NSString *)moduleName
+{
+  return @"NativeVoltra";
+}
+
+#pragma mark - NativeVoltraSpec
+
+- (void)startLiveActivity:(NSString *)jsonString
+                  options:(JS::NativeVoltra::StartVoltraOptions &)options
+                  resolve:(RCTPromiseResolveBlock)resolve
+                   reject:(RCTPromiseRejectBlock)reject
+{
+  StartVoltraOptions *opts = [StartVoltraOptions new];
+  opts.activityName = options.activityName();
+  opts.deepLinkUrl = options.deepLinkUrl();
+  opts.channelId = options.channelId();
+  if (auto v = options.staleDate()) opts.staleDate = @(v.value());
+  if (auto v = options.relevanceScore()) opts.relevanceScore = @(v.value());
+  [self.module startLiveActivity:jsonString options:opts completion:^(NSString *activityId, NSError *error) {
+    if (error) { reject(@"startLiveActivity", error.localizedDescription, error); } else { resolve(activityId); }
+  }];
+}
+
+- (void)updateLiveActivity:(NSString *)activityId
+                jsonString:(NSString *)jsonString
+                   options:(JS::NativeVoltra::UpdateVoltraOptions &)options
+                   resolve:(RCTPromiseResolveBlock)resolve
+                    reject:(RCTPromiseRejectBlock)reject
+{
+  UpdateVoltraOptions *opts = [UpdateVoltraOptions new];
+  if (auto v = options.staleDate()) opts.staleDate = @(v.value());
+  if (auto v = options.relevanceScore()) opts.relevanceScore = @(v.value());
+  [self.module updateLiveActivity:activityId jsonString:jsonString options:opts completion:^(NSError *error) {
+    if (error) { reject(@"updateLiveActivity", error.localizedDescription, error); } else { resolve(nil); }
+  }];
+}
+
+- (void)endLiveActivity:(NSString *)activityId
+                options:(JS::NativeVoltra::EndVoltraOptions &)options
+                resolve:(RCTPromiseResolveBlock)resolve
+                 reject:(RCTPromiseRejectBlock)reject
+{
+  EndVoltraOptions *opts = [EndVoltraOptions new];
+  if (auto dismissal = options.dismissalPolicy()) {
+    DismissalPolicyOptions *policy = [DismissalPolicyOptions new];
+    policy.type = dismissal->type();
+    if (auto date = dismissal->date()) policy.date = @(date.value());
+    opts.dismissalPolicy = policy;
+  }
+  [self.module endLiveActivity:activityId options:opts completion:^(NSError *error) {
+    if (error) { reject(@"endLiveActivity", error.localizedDescription, error); } else { resolve(nil); }
+  }];
+}
+
+- (void)endAllLiveActivities:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module endAllLiveActivities:^(NSError *error) {
+    if (error) { reject(@"endAllLiveActivities", error.localizedDescription, error); } else { resolve(nil); }
+  }];
+}
+
+- (void)getLatestVoltraActivityId:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  resolve([self.module getLatestVoltraActivityId]);
+}
+
+- (void)listVoltraActivityIds:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  resolve([self.module listVoltraActivityIds]);
+}
+
+- (NSNumber *)isLiveActivityActive:(NSString *)activityName
+{
+  return @([self.module isLiveActivityActive:activityName]);
+}
+
+- (NSNumber *)isHeadless
+{
+  return @([self.module isHeadless]);
+}
+
+- (void)preloadImages:(NSArray *)images resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module preloadImages:images completion:^(NSDictionary *result, NSError *error) {
+    if (error) { reject(@"preloadImages", error.localizedDescription, error); } else { resolve(result); }
+  }];
+}
+
+- (void)reloadLiveActivities:(NSArray *)activityNames resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module reloadLiveActivities:activityNames completion:^(NSError *error) {
+    if (error) { reject(@"reloadLiveActivities", error.localizedDescription, error); } else { resolve(nil); }
+  }];
+}
+
+- (void)clearPreloadedImages:(NSArray *)keys resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module clearPreloadedImages:keys completion:^{ resolve(nil); }];
+}
+
+- (void)updateWidget:(NSString *)widgetId
+          jsonString:(NSString *)jsonString
+             options:(JS::NativeVoltra::UpdateWidgetOptions &)options
+             resolve:(RCTPromiseResolveBlock)resolve
+              reject:(RCTPromiseRejectBlock)reject
+{
+  UpdateWidgetOptions *opts = [UpdateWidgetOptions new];
+  opts.deepLinkUrl = options.deepLinkUrl();
+  [self.module updateWidget:widgetId jsonString:jsonString options:opts completion:^(NSError *error) {
+    if (error) { reject(@"updateWidget", error.localizedDescription, error); } else { resolve(nil); }
+  }];
+}
+
+- (void)scheduleWidget:(NSString *)widgetId
+          timelineJson:(NSString *)timelineJson
+               resolve:(RCTPromiseResolveBlock)resolve
+                reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module scheduleWidget:widgetId timelineJson:timelineJson completion:^(NSError *error) {
+    if (error) { reject(@"scheduleWidget", error.localizedDescription, error); } else { resolve(nil); }
+  }];
+}
+
+- (void)reloadWidgets:(NSArray *)widgetIds resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module reloadWidgets:widgetIds completion:^{ resolve(nil); }];
+}
+
+- (void)clearWidget:(NSString *)widgetId resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module clearWidget:widgetId completion:^{ resolve(nil); }];
+}
+
+- (void)clearAllWidgets:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module clearAllWidgets:^{ resolve(nil); }];
+}
+
+- (void)getActiveWidgets:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module getActiveWidgets:^(NSArray *result, NSError *error) {
+    if (error) { reject(@"getActiveWidgets", error.localizedDescription, error); } else { resolve(result); }
+  }];
+}
+
+- (void)setWidgetServerCredentials:(JS::NativeVoltra::WidgetServerCredentials &)credentials
+                           resolve:(RCTPromiseResolveBlock)resolve
+                            reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module setWidgetServerCredentials:credentials.token() headers:(NSDictionary *)credentials.headers()];
+  resolve(nil);
+}
+
+- (void)clearWidgetServerCredentials:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module clearWidgetServerCredentials];
+  resolve(nil);
+}
+
+- (void)dealloc
+{
+  [self.module stopMonitoring];
+}
+
+@end

package/ios/app/VoltraActivity.swift

@@ -0,0 +1,5 @@
+import ActivityKit
+import Foundation
+
+/// Type alias for Live Activity with unified attributes
+public typealias VoltraActivity = Activity<VoltraAttributes>

package/ios/app/VoltraImagePreload.swift

@@ -0,0 +1,154 @@
+import Foundation
+import os
+import UIKit
+
+// MARK: - Types
+
+public struct PreloadImageOptions {
+  public var url: String
+  public var key: String
+  public var method: String?
+  public var headers: [String: String]?
+
+  public init(_ dict: NSDictionary) {
+    url = dict["url"] as? String ?? ""
+    key = dict["key"] as? String ?? ""
+    method = dict["method"] as? String
+    headers = dict["headers"] as? [String: String]
+  }
+}
+
+public struct PreloadImageFailure {
+  public var key: String
+  public var error: String
+
+  public init(key: String, error: String) {
+    self.key = key
+    self.error = error
+  }
+
+  public func toDictionary() -> NSDictionary {
+    ["key": key, "error": error]
+  }
+}
+
+public struct PreloadImagesResult {
+  public var succeeded: [String]
+  public var failed: [PreloadImageFailure]
+
+  public init(succeeded: [String], failed: [PreloadImageFailure]) {
+    self.succeeded = succeeded
+    self.failed = failed
+  }
+
+  public func toDictionary() -> NSDictionary {
+    ["succeeded": succeeded, "failed": failed.map { $0.toDictionary() }]
+  }
+}
+
+// MARK: - Errors
+
+/// Errors that can occur during image preloading
+enum PreloadError: Error, LocalizedError {
+  case invalidURL(String)
+  case invalidResponse
+  case httpError(statusCode: Int)
+  case imageTooLarge(key: String, size: Int)
+  case invalidImageData(key: String)
+  case appGroupNotConfigured
+
+  var errorDescription: String? {
+    switch self {
+    case let .invalidURL(url):
+      return "Invalid URL: \(url)"
+    case .invalidResponse:
+      return "Invalid response from server"
+    case let .httpError(statusCode):
+      return "HTTP error: \(statusCode)"
+    case let .imageTooLarge(key, size):
+      return "Image '\(key)' is too large: \(size) bytes (max \(VoltraImagePreload.maxImageSizeInBytes) bytes for Live Activities)"
+    case let .invalidImageData(key):
+      return "Invalid image data for '\(key)'"
+    case .appGroupNotConfigured:
+      return "App Group not configured. Set 'groupIdentifier' in the Voltra config plugin."
+    }
+  }
+}
+
+// MARK: - Namespace
+
+enum VoltraImagePreload {
+  static let maxImageSizeInBytes = 4096
+
+  static func preloadImages(images: [PreloadImageOptions]) async throws -> PreloadImagesResult {
+    var succeeded: [String] = []
+    var failed: [PreloadImageFailure] = []
+
+    for imageOptions in images {
+      do {
+        try await downloadAndSaveImage(imageOptions)
+        succeeded.append(imageOptions.key)
+      } catch {
+        failed.append(PreloadImageFailure(key: imageOptions.key, error: error.localizedDescription))
+      }
+    }
+
+    return PreloadImagesResult(succeeded: succeeded, failed: failed)
+  }
+
+  static func clearPreloadedImages(keys: [String]?) async {
+    if let keys = keys, !keys.isEmpty {
+      VoltraImageStore.removeImages(keys: keys)
+      VoltraLogger.image.info("Cleared preloaded images: \(keys.joined(separator: ", "))")
+    } else {
+      VoltraImageStore.clearAll()
+      VoltraLogger.image.info("Cleared all preloaded images")
+    }
+  }
+
+  // MARK: - Private
+
+  private static func downloadAndSaveImage(_ options: PreloadImageOptions) async throws {
+    guard let url = URL(string: options.url) else {
+      throw PreloadError.invalidURL(options.url)
+    }
+
+    var request = URLRequest(url: url)
+    request.httpMethod = options.method ?? "GET"
+
+    if let headers = options.headers {
+      for (key, value) in headers {
+        request.setValue(value, forHTTPHeaderField: key)
+      }
+    }
+
+    let (data, response) = try await URLSession.shared.data(for: request)
+
+    guard let httpResponse = response as? HTTPURLResponse else {
+      throw PreloadError.invalidResponse
+    }
+
+    guard (200 ... 299).contains(httpResponse.statusCode) else {
+      throw PreloadError.httpError(statusCode: httpResponse.statusCode)
+    }
+
+    if let contentLengthString = httpResponse.value(forHTTPHeaderField: "Content-Length"),
+       let contentLength = Int(contentLengthString)
+    {
+      if contentLength >= maxImageSizeInBytes {
+        throw PreloadError.imageTooLarge(key: options.key, size: contentLength)
+      }
+    }
+
+    if data.count >= maxImageSizeInBytes {
+      throw PreloadError.imageTooLarge(key: options.key, size: data.count)
+    }
+
+    guard UIImage(data: data) != nil else {
+      throw PreloadError.invalidImageData(key: options.key)
+    }
+
+    try VoltraImageStore.saveImage(data, key: options.key)
+    VoltraLogger.image.info("Preloaded '\(options.key)' (\(data.count) bytes)")
+  }
+}

package/ios/app/VoltraLiveActivityManager.swift

@@ -0,0 +1,228 @@
+import ActivityKit
+import Foundation
+
+//  The underlying ActivityKit APIs deliver updates via async for-await loops that
+//  run on arbitrary tasks. Without synchronization, dictionaries and sets mutated
+//  from those tasks are data races. Making this type an `actor` ensures every read
+//  and write to its stored properties is serialized automatically by the Swift
+//  concurrency runtime -- no locks required.
+
+public actor VoltraLiveActivityManager {
+  // MARK: - Callbacks
+
+  // Callbacks are `let` + `@Sendable` so they are immutable after init and safe
+  // to call from any concurrency context without capturing `self`.
+
+  /// Called when a push token is received or rotated for a specific activity.
+  /// Parameters: (activityName, hexToken)
+  private let onTokenUpdated: (@Sendable (String, String) -> Void)?
+
+  /// Called when the push-to-start token is received or rotated (iOS 17.2+).
+  /// Parameter: hexToken
+  private let onPushToStartUpdated: (@Sendable (String) -> Void)?
+
+  /// Called when an activity transitions to a new lifecycle state.
+  /// Parameters: (activityName, stateDescription)
+  private let onStateChanged: (@Sendable (String, String) -> Void)?
+
+  // MARK: - Internal Task State
+
+  /// Drives the main `Activity.activityUpdates` loop. When this task is cancelled,
+  /// the loop exits and no new per-activity observers are created.
+  private var activityUpdatesTask: Task<Void, Never>?
+
+  /// Drives the `Activity.pushToStartTokenUpdates` loop (iOS 17.2+ only).
+  private var pushToStartTask: Task<Void, Never>?
+
+  /// One push-token observer task per live activity, keyed by `activity.id`.
+  /// Using a dictionary (rather than a flat array) lets us deduplicate and cancel
+  /// individual tasks when an activity ends.
+  private var tokenTasks: [String: Task<Void, Never>] = [:]
+
+  /// One lifecycle-state observer task per live activity, keyed by `activity.id`.
+  private var stateTasks: [String: Task<Void, Never>] = [:]
+
+  /// The last push-to-start token we forwarded to the callback.
+  /// ActivityKit re-delivers the current token whenever a live activity starts or
+  /// ends (the push-to-start eligibility state has changed), even if the token
+  /// itself hasn't rotated. We track the last value so we only forward genuine
+  /// token changes and suppress duplicate deliveries.
+  private var lastPushToStartToken: String?
+
+  // MARK: - Init
+
+  public init(
+    onTokenUpdated: (@Sendable (String, String) -> Void)? = nil,
+    onPushToStartUpdated: (@Sendable (String) -> Void)? = nil,
+    onStateChanged: (@Sendable (String, String) -> Void)? = nil
+  ) {
+    self.onTokenUpdated = onTokenUpdated
+    self.onPushToStartUpdated = onPushToStartUpdated
+    self.onStateChanged = onStateChanged
+  }
+
+  // MARK: - Public API
+
+  /// Begin observing all live activities and tokens.
+  ///
+  /// This method is idempotent: calling it while already observing is a no-op.
+  /// To restart observation, call `stopObserving()` first.
+  public func startObserving() {
+    guard activityUpdatesTask == nil else { return }
+
+    startActivityUpdatesObservation()
+    startPushToStartObservation()
+  }
+
+  /// Stop all observation and cancel every outstanding task.
+  ///
+  /// Safe to call from any context. After this returns the actor holds no running
+  /// tasks; calling `startObserving()` again creates a fresh set.
+  public func stopObserving() {
+    activityUpdatesTask?.cancel()
+    activityUpdatesTask = nil
+
+    pushToStartTask?.cancel()
+    pushToStartTask = nil
+
+    lastPushToStartToken = nil
+
+    cancelAllPerActivityTasks()
+  }
+
+  // MARK: - deinit
+
+  /// Safety net: if the manager is deallocated without stopObserving() being called
+  /// (e.g. during app shutdown), cancel every task so no coroutine keeps running as
+  /// an orphan. SE-0371 (Swift 5.9) allows actors to access their stored properties
+  /// in deinit because no other reference can exist at that point.
+  deinit {
+    activityUpdatesTask?.cancel()
+    pushToStartTask?.cancel()
+    for task in tokenTasks.values {
+      task.cancel()
+    }
+    for task in stateTasks.values {
+      task.cancel()
+    }
+  }
+
+  // MARK: - Activity Updates Loop
+
+  private func startActivityUpdatesObservation() {
+    activityUpdatesTask = Task { [weak self] in
+      // Observe activities that were already running when we started --
+      // `Activity.activityUpdates` only yields *newly created* activities,
+      // so we must handle pre-existing ones explicitly.
+      for activity in Activity<VoltraAttributes>.activities {
+        await self?.observe(activity)
+      }
+
+      // Then listen for any activities created from this point onward.
+      for await activity in Activity<VoltraAttributes>.activityUpdates {
+        await self?.observe(activity)
+      }
+    }
+  }
+
+  // MARK: - Push-to-Start Token Loop (iOS 17.2+)
+
+  private func startPushToStartObservation() {
+    guard #available(iOS 17.2, *), let onPushToStartUpdated else { return }
+
+    // Read the token that may already be available before the async stream fires.
+    if let existingTokenData = Activity<VoltraAttributes>.pushToStartToken {
+      deliverPushToStartToken(existingTokenData.hexString, via: onPushToStartUpdated)
+    }
+
+    // Capture the callback locally so the task does not need to hop back to the
+    // actor on every token delivery -- callbacks are @Sendable and safe to call
+    // from any context.
+    let callback = onPushToStartUpdated
+
+    pushToStartTask = Task { [weak self] in
+      for await tokenData in Activity<VoltraAttributes>.pushToStartTokenUpdates {
+        await self?.deliverPushToStartToken(tokenData.hexString, via: callback)
+      }
+    }
+  }
+
+  /// Forward `token` to `callback` only if it differs from the last token we sent.
+  /// ActivityKit re-delivers the same token when a live activity starts or ends,
+  /// so this guard prevents spurious duplicate events on the JS side.
+  private func deliverPushToStartToken(
+    _ token: String,
+    via callback: @Sendable (String) -> Void
+  ) {
+    guard token != lastPushToStartToken else { return }
+    lastPushToStartToken = token
+    callback(token)
+  }
+
+  // MARK: - Per-Activity Observation
+
+  /// Start observing a single activity's push token and state changes.
+  ///
+  /// Deduplication: if we are already watching this activity (same `id`), this
+  /// is a no-op. `activityUpdates` can re-yield the same activity after updates,
+  /// so deduplication here prevents duplicate concurrent observers.
+  private func observe(_ activity: Activity<VoltraAttributes>) {
+    let activityId = activity.id
+    let activityName = activity.attributes.name
+
+    // Token observation
+    if let onTokenUpdated, tokenTasks[activityId] == nil {
+      // Capture the callback locally to avoid an actor hop on every token delivery.
+      let callback = onTokenUpdated
+
+      let tokenTask = Task { [weak self] in
+        for await tokenData in activity.pushTokenUpdates {
+          callback(activityName, tokenData.hexString)
+        }
+        // The async sequence ends when the activity is dismissed or ended.
+        // Clean up our entry so we don't hold a reference to the finished task.
+        await self?.removeTokenTask(for: activityId)
+      }
+
+      tokenTasks[activityId] = tokenTask
+    }
+
+    // State observation
+    if let onStateChanged, stateTasks[activityId] == nil {
+      let callback = onStateChanged
+
+      let stateTask = Task { [weak self] in
+        for await state in activity.activityStateUpdates {
+          callback(activityName, String(describing: state))
+        }
+        await self?.removeStateTask(for: activityId)
+      }
+
+      stateTasks[activityId] = stateTask
+    }
+  }
+
+  // MARK: - Task Cleanup Helpers
+
+  private func removeTokenTask(for activityId: String) {
+    tokenTasks[activityId]?.cancel()
+    tokenTasks.removeValue(forKey: activityId)
+  }
+
+  private func removeStateTask(for activityId: String) {
+    stateTasks[activityId]?.cancel()
+    stateTasks.removeValue(forKey: activityId)
+  }
+
+  private func cancelAllPerActivityTasks() {
+    for task in tokenTasks.values {
+      task.cancel()
+    }
+    tokenTasks.removeAll()
+
+    for task in stateTasks.values {
+      task.cancel()
+    }
+    stateTasks.removeAll()
+  }
+}