@use-voltra/ios-client 2.2.0 → 2.3.0

package/ios/app/NativeVoltra.mm

@@ -1,12 +1,25 @@
 #import "NativeVoltra.h"
 #import <UIKit/UIKit.h>
 
-#if __has_include("Voltra/Voltra-Swift.h")
-#import "Voltra/Voltra-Swift.h"
+#if __has_include("Voltra/VoltraRuntime-Swift.h")
+#import "Voltra/VoltraRuntime-Swift.h"
 #else
-#import "Voltra-Swift.h"
+#import "VoltraRuntime-Swift.h"
 #endif
 
+static NSString *VoltraPromiseErrorCode(NSString *fallbackCode, NSError *error)
+{
+  if ([error.domain isEqualToString:@"com.callstack.voltra"] && error.code == 4) {
+    return @"VOLTRA_RENDERER_MISMATCH";
+  }
+  return fallbackCode;
+}
+
+static void VoltraRejectPromise(RCTPromiseRejectBlock reject, NSString *fallbackCode, NSError *error)
+{
+  reject(VoltraPromiseErrorCode(fallbackCode, error), error.localizedDescription, error);
+}
+
 @interface VoltraLaunchObserver : NSObject
 @end
 
@@ -65,6 +78,8 @@
 
     if ([eventName isEqualToString:@"interaction"]) {
       [strongSelf emitOnInteraction:eventData];
+    } else if ([eventName isEqualToString:@"dynamicLiveActivityRenderFailed"]) {
+      [strongSelf emitOnDynamicLiveActivityRenderFailed:eventData];
     } else if ([eventName isEqualToString:@"stateChange"]) {
       [strongSelf emitOnStateChanged:eventData];
     } else if ([eventName isEqualToString:@"activityTokenReceived"]) {
@@ -86,9 +101,20 @@
 - (void)applicationWillEnterForeground
 {
   [self.module clearHeadless];
+  [self.module drainDynamicLiveActivityRenderFailures];
   [self updateRootAppPropertiesHeadless:NO];
 }
 
+- (void)drainDynamicLiveActivityRenderFailures
+{
+  [self.module drainDynamicLiveActivityRenderFailures];
+}
+
+- (void)setDynamicLiveActivityRenderFailureListenerActive:(BOOL)active
+{
+  [self.module setDynamicLiveActivityRenderFailureListenerActive:active];
+}
+
 - (UIView *)reactRootViewInView:(UIView *)view
 {
   if ([view respondsToSelector:NSSelectorFromString(@"appProperties")] &&
@@ -193,7 +219,7 @@
   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); }
+    if (error) { VoltraRejectPromise(reject, @"startLiveActivity", error); } else { resolve(activityId); }
   }];
 }
 
@@ -207,7 +233,38 @@
   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); }
+    if (error) { VoltraRejectPromise(reject, @"updateLiveActivity", error); } else { resolve(nil); }
+  }];
+}
+
+- (void)startDynamicLiveActivity:(NSString *)definitionId
+                       propsJson:(NSString *)propsJson
+                         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 startDynamicLiveActivity:definitionId propsJson:propsJson options:opts completion:^(NSString *activityId, NSError *error) {
+    if (error) { VoltraRejectPromise(reject, @"startDynamicLiveActivity", error); } else { resolve(activityId); }
+  }];
+}
+
+- (void)updateDynamicLiveActivity:(NSString *)activityId
+                        propsJson:(NSString *)propsJson
+                          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 updateDynamicLiveActivity:activityId propsJson:propsJson options:opts completion:^(NSError *error) {
+    if (error) { VoltraRejectPromise(reject, @"updateDynamicLiveActivity", error); } else { resolve(nil); }
   }];
 }
 
@@ -224,14 +281,14 @@
     opts.dismissalPolicy = policy;
   }
   [self.module endLiveActivity:activityId options:opts completion:^(NSError *error) {
-    if (error) { reject(@"endLiveActivity", error.localizedDescription, error); } else { resolve(nil); }
+    if (error) { VoltraRejectPromise(reject, @"endLiveActivity", 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); }
+    if (error) { VoltraRejectPromise(reject, @"endAllLiveActivities", error); } else { resolve(nil); }
   }];
 }
 
@@ -245,6 +302,11 @@
   resolve([self.module listVoltraActivityIds]);
 }
 
+- (void)getDynamicLiveActivityDefinitionIds:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  resolve([self.module getDynamicLiveActivityDefinitionIds]);
+}
+
 - (NSNumber *)isLiveActivityActive:(NSString *)activityName
 {
   return @([self.module isLiveActivityActive:activityName]);
@@ -271,6 +333,11 @@
   }];
 }
 
+- (void)reloadDynamicLiveActivities:(NSArray *)definitionIds resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
+{
+  [self.module reloadDynamicLiveActivities:definitionIds completion:^{ resolve(nil); }];
+}
+
 - (void)clearPreloadedImages:(NSArray *)keys resolve:(RCTPromiseResolveBlock)resolve reject:(RCTPromiseRejectBlock)reject
 {
   [self.module clearPreloadedImages:keys completion:^{ resolve(nil); }];
@@ -340,6 +407,39 @@
   }];
 }
 
+- (void)setWidgetServerUpdate:(NSString *)settingsJson
+                     widgetId:(NSString *)widgetId
+                      resolve:(RCTPromiseResolveBlock)resolve
+                       reject:(RCTPromiseRejectBlock)reject
+{
+  NSString *error = [self.module setWidgetServerUpdate:settingsJson widgetId:widgetId];
+  if (error) {
+    reject(@"VOLTRA_INVALID_SERVER_UPDATE_SETTINGS", error, nil);
+  } else {
+    resolve(nil);
+  }
+}
+
+- (void)clearWidgetServerUpdate:(NSString *)widgetId
+                        resolve:(RCTPromiseResolveBlock)resolve
+                         reject:(RCTPromiseRejectBlock)reject
+{
+  NSString *error = [self.module clearWidgetServerUpdate:widgetId];
+  if (error) {
+    reject(@"VOLTRA_INVALID_SERVER_UPDATE_SETTINGS", error, nil);
+  } else {
+    resolve(nil);
+  }
+}
+
+- (void)getWidgetServerUpdate:(NSString *)widgetId
+                       resolve:(RCTPromiseResolveBlock)resolve
+                        reject:(RCTPromiseRejectBlock)reject
+{
+  NSString *json = [self.module getWidgetServerUpdate:widgetId];
+  resolve(json);
+}
+
 - (void)setWidgetServerCredentials:(JS::NativeVoltra::WidgetServerCredentials &)credentials
                            resolve:(RCTPromiseResolveBlock)resolve
                             reject:(RCTPromiseRejectBlock)reject

package/ios/app/VoltraLiveActivityManager.swift

@@ -13,6 +13,9 @@ public actor VoltraLiveActivityManager {
   // Callbacks are `let` + `@Sendable` so they are immutable after init and safe
   // to call from any concurrency context without capturing `self`.
 
+  /// Called when ActivityKit exposes an activity instance to this process.
+  private let onActivityDiscovered: (@Sendable (String) -> Void)?
+
   /// Called when a push token is received or rotated for a specific activity.
   /// Parameters: (activityName, hexToken)
   private let onTokenUpdated: (@Sendable (String, String) -> Void)?
@@ -30,6 +33,7 @@ public actor VoltraLiveActivityManager {
   /// 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>?
+  private var isObserving = false
 
   /// Drives the `Activity.pushToStartTokenUpdates` loop (iOS 17.2+ only).
   private var pushToStartTask: Task<Void, Never>?
@@ -42,6 +46,11 @@ public actor VoltraLiveActivityManager {
   /// One lifecycle-state observer task per live activity, keyed by `activity.id`.
   private var stateTasks: [String: Task<Void, Never>] = [:]
 
+  /// Generated Dynamic Live Activity types require separate ActivityKit streams.
+  /// This observer owns those streams while this manager continues to own the
+  /// unchanged legacy and app-wide push-to-start contracts.
+  private let dynamicObserver: VoltraDynamicLiveActivityObserver
+
   /// 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
@@ -52,13 +61,20 @@ public actor VoltraLiveActivityManager {
   // MARK: - Init
 
   public init(
+    onActivityDiscovered: (@Sendable (String) -> Void)? = nil,
     onTokenUpdated: (@Sendable (String, String) -> Void)? = nil,
     onPushToStartUpdated: (@Sendable (String) -> Void)? = nil,
     onStateChanged: (@Sendable (String, String) -> Void)? = nil
   ) {
+    self.onActivityDiscovered = onActivityDiscovered
     self.onTokenUpdated = onTokenUpdated
     self.onPushToStartUpdated = onPushToStartUpdated
     self.onStateChanged = onStateChanged
+    dynamicObserver = VoltraDynamicLiveActivityObserver(
+      onActivityDiscovered: onActivityDiscovered,
+      onTokenUpdated: onTokenUpdated,
+      onStateChanged: onStateChanged
+    )
   }
 
   // MARK: - Public API
@@ -69,9 +85,14 @@ public actor VoltraLiveActivityManager {
   /// To restart observation, call `stopObserving()` first.
   public func startObserving() {
     guard activityUpdatesTask == nil else { return }
+    isObserving = true
 
     startActivityUpdatesObservation()
     startPushToStartObservation()
+    Task { [weak self, dynamicObserver] in
+      guard await self?.currentlyObserving() == true else { return }
+      await VoltraDynamicLiveActivityRegistry.shared.startObserving(with: dynamicObserver)
+    }
   }
 
   /// Stop all observation and cancel every outstanding task.
@@ -79,6 +100,7 @@ public actor VoltraLiveActivityManager {
   /// 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() {
+    isObserving = false
     activityUpdatesTask?.cancel()
     activityUpdatesTask = nil
 
@@ -88,6 +110,13 @@ public actor VoltraLiveActivityManager {
     lastPushToStartToken = nil
 
     cancelAllPerActivityTasks()
+    Task { [dynamicObserver] in
+      await dynamicObserver.stopObserving()
+    }
+  }
+
+  private func currentlyObserving() -> Bool {
+    isObserving
   }
 
   // MARK: - deinit
@@ -169,6 +198,7 @@ public actor VoltraLiveActivityManager {
   private func observe(_ activity: Activity<VoltraAttributes>) {
     let activityId = activity.id
     let activityName = activity.attributes.name
+    onActivityDiscovered?(activityId)
 
     // Token observation
     if let onTokenUpdated, tokenTasks[activityId] == nil {

package/ios/app/VoltraLiveActivityService.swift

@@ -78,6 +78,9 @@ public struct UpdateActivityRequest {
 
 /// Service for managing Voltra Live Activities
 public class VoltraLiveActivityService {
+  private let chronology = VoltraLiveActivityChronology.shared
+  private let dynamicService = VoltraDynamicLiveActivityService()
+
   // MARK: - Availability Checks
 
   /// Check if Live Activities are supported on this OS version
@@ -113,7 +116,7 @@ public class VoltraLiveActivityService {
     return Array(Activity<VoltraAttributes>.activities)
   }
 
-  /// Get the latest (most recently created) activity across both types
+  /// Get the latest legacy activity.
   public func getLatestActivity() -> VoltraActivity? {
     guard Self.isSupported() else { return nil }
     let allActivities = getAllActivities()
@@ -122,7 +125,30 @@ public class VoltraLiveActivityService {
 
   /// Check if an activity with the given name exists across both types
   public func isActivityActive(name: String) -> Bool {
-    findActivity(byName: name) != nil
+    findActivity(byName: name) != nil || dynamicService.isActive(name: name)
+  }
+
+  /// The unified list intentionally erases each engine's concrete attributes type.
+  public func getAllActivityReferences() -> [VoltraDynamicLiveActivityReference] {
+    guard Self.isSupported() else { return [] }
+    let legacy = getAllActivities().map {
+      VoltraDynamicLiveActivityReference(id: $0.id, name: $0.attributes.name, definitionId: "legacy")
+    }
+    return chronology.order(legacy + dynamicService.activityReferences())
+  }
+
+  public func latestActivityId() -> String? {
+    guard Self.isSupported() else { return nil }
+    let legacy = getAllActivities().map {
+      VoltraDynamicLiveActivityReference(id: $0.id, name: $0.attributes.name, definitionId: "legacy")
+    }
+    return chronology.latest(legacy + dynamicService.activityReferences())?.id
+  }
+
+  /// The installed capability list is generated during prebuild and does not
+  /// depend on Metro, the app group, or a server connection.
+  public func dynamicLiveActivityDefinitionIds() -> [String] {
+    dynamicService.definitionIds()
   }
 
   // MARK: - Create Operations
@@ -154,7 +180,7 @@ public class VoltraLiveActivityService {
     let initialState = try VoltraAttributes.ContentState(uiJsonData: request.jsonString)
 
     // Request the activity
-    _ = try Activity.request(
+    let activity = try Activity.request(
       attributes: attributes,
       content: .init(
         state: initialState,
@@ -163,6 +189,7 @@ public class VoltraLiveActivityService {
       ),
       pushType: request.pushType
     )
+    chronology.record(activity.id)
 
     return finalActivityId
   }
@@ -202,6 +229,9 @@ public class VoltraLiveActivityService {
     request: UpdateActivityRequest
   ) async throws {
     guard let activity = findActivity(byName: name) else {
+      if dynamicService.isActive(name: name) {
+        throw VoltraLiveActivityError.rendererMismatch
+      }
       throw VoltraLiveActivityError.notFound
     }
     try await updateActivity(activity, request: request)
@@ -231,10 +261,15 @@ public class VoltraLiveActivityService {
     byName name: String,
     dismissalPolicy: ActivityUIDismissalPolicy = .immediate
   ) async throws {
-    guard let activity = findActivity(byName: name) else {
+    if let activity = findActivity(byName: name) {
+      await endActivity(activity, dismissalPolicy: dismissalPolicy)
+      // Names can collide across engines after a remote start. Shared ending covers both.
+      _ = await dynamicService.end(byName: name, dismissalPolicy: dismissalPolicy)
+      return
+    }
+    guard await dynamicService.end(byName: name, dismissalPolicy: dismissalPolicy) else {
       throw VoltraLiveActivityError.notFound
     }
-    await endActivity(activity, dismissalPolicy: dismissalPolicy)
   }
 
   /// End all activities with the same name
@@ -245,6 +280,7 @@ public class VoltraLiveActivityService {
     for activity in activities {
       await endActivity(activity)
     }
+    _ = await dynamicService.end(byName: name, dismissalPolicy: .immediate)
   }
 
   /// End all Voltra Live Activities
@@ -254,6 +290,38 @@ public class VoltraLiveActivityService {
     for activity in activities {
       await endActivity(activity)
     }
+    await dynamicService.endAll(dismissalPolicy: .immediate)
+  }
+
+  // MARK: - Dynamic operations
+
+  public func createDynamicActivity(_ request: VoltraDynamicLiveActivityCreateRequest) async throws -> String {
+    guard Self.isSupported() else { throw VoltraLiveActivityError.unsupportedOS }
+    guard Self.areActivitiesEnabled() else { throw VoltraLiveActivityError.liveActivitiesNotEnabled }
+    if request.name.isEmpty == false {
+      try await endActivities(byName: request.name)
+    }
+    return try await dynamicService.create(request)
+  }
+
+  public func updateDynamicActivity(byName name: String, request: VoltraDynamicLiveActivityUpdateRequest) async throws {
+    guard Self.isSupported() else { throw VoltraLiveActivityError.unsupportedOS }
+    if try await dynamicService.update(byName: name, request: request) {
+      return
+    }
+    if findActivity(byName: name) != nil {
+      throw VoltraDynamicLiveActivityError.rendererMismatch
+    }
+    throw VoltraLiveActivityError.notFound
+  }
+
+  /// Refetch and re-evaluate only invalidated Dynamic Live Activity definitions,
+  /// then update their active instances with their current state to trigger a
+  /// WidgetKit render. Legacy activities are deliberately untouched.
+  public func reloadDynamicActivities(definitionIds: [String]?) async {
+    #if DEBUG
+      await dynamicService.reload(definitionIds: definitionIds)
+    #endif
   }
 
   // MARK: - Monitoring
@@ -280,6 +348,9 @@ public class VoltraLiveActivityService {
     }
 
     let manager = VoltraLiveActivityManager(
+      onActivityDiscovered: { [chronology] activityId in
+        chronology.record(activityId)
+      },
       onTokenUpdated: onTokenUpdated,
       onPushToStartUpdated: onPushToStartUpdated,
       onStateChanged: { activityName, state in
@@ -305,4 +376,5 @@ public enum VoltraLiveActivityError: Error {
   case unsupportedOS
   case notFound
   case liveActivitiesNotEnabled
+  case rendererMismatch
 }

package/ios/app/VoltraModule.swift

@@ -1,10 +1,42 @@
 import Foundation
 
-public enum VoltraErrors: Error {
+public enum VoltraErrors: Error, CustomNSError {
   case unsupportedOS
   case notFound
   case liveActivitiesNotEnabled
+  case rendererMismatch
   case unexpectedError(Error)
+
+  public static let errorDomain = "com.callstack.voltra"
+
+  public var errorCode: Int {
+    switch self {
+    case .unexpectedError: 0
+    case .unsupportedOS: 1
+    case .notFound: 2
+    case .liveActivitiesNotEnabled: 3
+    case .rendererMismatch: 4
+    }
+  }
+
+  public var errorUserInfo: [String: Any] {
+    [NSLocalizedDescriptionKey: errorDescription]
+  }
+
+  private var errorDescription: String {
+    switch self {
+    case .unsupportedOS:
+      "Live Activities require iOS 16.4 or newer."
+    case .notFound:
+      "The requested Live Activity was not found."
+    case .liveActivitiesNotEnabled:
+      "Live Activities are disabled for this app."
+    case .rendererMismatch:
+      "The Live Activity belongs to a different renderer."
+    case let .unexpectedError(error):
+      error.localizedDescription
+    }
+  }
 }
 
 @objc public final class VoltraModule: NSObject {
@@ -59,6 +91,37 @@ public enum VoltraErrors: Error {
     }
   }
 
+  @objc public func startDynamicLiveActivity(
+    _ definitionId: String,
+    propsJson: String,
+    options: StartVoltraOptions?,
+    completion: @escaping (String?, Error?) -> Void
+  ) {
+    Task {
+      do {
+        try completion(await impl.startDynamicLiveActivity(definitionId: definitionId, propsJson: propsJson, options: options), nil)
+      } catch {
+        completion(nil, error)
+      }
+    }
+  }
+
+  @objc public func updateDynamicLiveActivity(
+    _ activityId: String,
+    propsJson: String,
+    options: UpdateVoltraOptions?,
+    completion: @escaping (Error?) -> Void
+  ) {
+    Task {
+      do {
+        try await impl.updateDynamicLiveActivity(activityId: activityId, propsJson: propsJson, options: options)
+        completion(nil)
+      } catch {
+        completion(error)
+      }
+    }
+  }
+
   @objc public func endLiveActivity(
     _ activityId: String,
     options: EndVoltraOptions?,
@@ -93,6 +156,10 @@ public enum VoltraErrors: Error {
     impl.listVoltraActivityIds()
   }
 
+  @objc public func getDynamicLiveActivityDefinitionIds() -> [String] {
+    impl.getDynamicLiveActivityDefinitionIds()
+  }
+
   @objc public func isLiveActivityActive(_ activityName: String) -> Bool {
     impl.isLiveActivityActive(name: activityName)
   }
@@ -105,6 +172,14 @@ public enum VoltraErrors: Error {
     impl.clearHeadless()
   }
 
+  @objc public func drainDynamicLiveActivityRenderFailures() {
+    impl.drainDynamicLiveActivityRenderFailures()
+  }
+
+  @objc public func setDynamicLiveActivityRenderFailureListenerActive(_ active: Bool) {
+    impl.setDynamicLiveActivityRenderFailureListenerActive(active)
+  }
+
   // MARK: - Images
 
   @objc public func preloadImages(
@@ -136,6 +211,13 @@ public enum VoltraErrors: Error {
     }
   }
 
+  @objc public func reloadDynamicLiveActivities(_ definitionIds: NSArray?, completion: @escaping () -> Void) {
+    Task {
+      await impl.reloadDynamicLiveActivities(definitionIds: definitionIds?.compactMap { $0 as? String })
+      completion()
+    }
+  }
+
   @objc public func clearPreloadedImages(_ keys: NSArray?, completion: @escaping () -> Void) {
     Task {
       await impl.clearPreloadedImages(keys: keys?.compactMap { $0 as? String })
@@ -225,6 +307,22 @@ public enum VoltraErrors: Error {
     }
   }
 
+  // MARK: - Widget Server Update Settings
+
+  /// - Returns: an error message when the settings were rejected, or nil when they were applied.
+  @objc public func setWidgetServerUpdate(_ settingsJson: String, widgetId: String?) -> NSString? {
+    impl.setWidgetServerUpdate(settingsJson: settingsJson, widgetId: widgetId) as NSString?
+  }
+
+  @objc public func clearWidgetServerUpdate(_ widgetId: String?) -> NSString? {
+    impl.clearWidgetServerUpdate(widgetId: widgetId) as NSString?
+  }
+
+  /// - Returns: settings as JSON (resolved for a `widgetId`, raw global otherwise), or nil.
+  @objc public func getWidgetServerUpdate(_ widgetId: String?) -> NSString? {
+    impl.getWidgetServerUpdate(widgetId: widgetId) as NSString?
+  }
+
   // MARK: - Widget Server Credentials
 
   @objc public func setWidgetServerCredentials(_ token: String, headers: NSDictionary?) {