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

package/ios/app/VoltraModuleImpl.swift

@@ -0,0 +1,331 @@
+import ActivityKit
+import Compression
+import Foundation
+import os
+import UIKit
+
+/// Implementation details for VoltraModule to keep the main module file clean
+public class VoltraModuleImpl {
+  private let liveActivityService = VoltraLiveActivityService()
+
+  public init() {
+    // Clean up data for widgets that are no longer installed
+    VoltraWidgetService.cleanupOrphanedData()
+  }
+
+  func isHeadless() -> Bool {
+    if Thread.isMainThread {
+      return UIApplication.shared.applicationState == .background
+    }
+    return DispatchQueue.main.sync {
+      UIApplication.shared.applicationState == .background
+    }
+  }
+
+  var pushNotificationsEnabled: Bool {
+    // Support both keys for compatibility with older plugin and new Voltra naming
+    let main = Bundle.main
+    return main.object(forInfoDictionaryKey: VoltraStorageKeys.enablePushNotifications) as? Bool ?? false
+  }
+
+  // MARK: - Lifecycle & Monitoring
+
+  func startMonitoring(handler: @escaping (String, [String: Any]) -> Void) {
+    VoltraEventBus.shared.subscribe(handler: handler)
+    liveActivityService.startMonitoring(enablePush: pushNotificationsEnabled)
+  }
+
+  func stopMonitoring() {
+    VoltraEventBus.shared.unsubscribe()
+    liveActivityService.stopMonitoring()
+  }
+
+  // MARK: - Live Activities
+
+  func startLiveActivity(jsonString: String, options: StartVoltraOptions?) async throws -> String {
+    guard #available(iOS 16.2, *) else { throw VoltraErrors.unsupportedOS }
+    guard VoltraLiveActivityService.areActivitiesEnabled() else {
+      throw VoltraErrors.liveActivitiesNotEnabled
+    }
+
+    do {
+      // Compress JSON using brotli level 2
+      let compressedJson = try BrotliCompression.compress(jsonString: jsonString)
+      try validatePayloadSize(compressedJson, operation: "start")
+
+      let activityName = options?.activityName?.trimmingCharacters(in: .whitespacesAndNewlines)
+
+      // Extract staleDate and relevanceScore from options
+      let staleDate: Date? = {
+        if let staleDateMs = options?.staleDate?.doubleValue {
+          return Date(timeIntervalSince1970: staleDateMs / 1000.0)
+        }
+        return nil
+      }()
+      let relevanceScore: Double = options?.relevanceScore?.doubleValue ?? 0.0
+
+      let pushType = try resolvePushType(channelId: options?.channelId)
+
+      // Create request struct with compressed JSON
+      let createRequest = CreateActivityRequest(
+        activityId: activityName,
+        deepLinkUrl: options?.deepLinkUrl,
+        jsonString: compressedJson,
+        staleDate: staleDate,
+        relevanceScore: relevanceScore,
+        pushType: pushType,
+        endExistingWithSameName: true
+      )
+
+      // Create activity using service
+      return try await liveActivityService.createActivity(createRequest)
+    } catch {
+      VoltraLogger.module.error("startLiveActivity failed: \(error)")
+      throw mapError(error)
+    }
+  }
+
+  func updateLiveActivity(activityId: String, jsonString: String, options: UpdateVoltraOptions?) async throws {
+    guard #available(iOS 16.2, *) else { throw VoltraErrors.unsupportedOS }
+
+    // Compress JSON using brotli level 2
+    let compressedJson = try BrotliCompression.compress(jsonString: jsonString)
+    try validatePayloadSize(compressedJson, operation: "update")
+
+    // Extract staleDate and relevanceScore from options
+    let staleDate: Date? = {
+      if let staleDateMs = options?.staleDate?.doubleValue {
+        return Date(timeIntervalSince1970: staleDateMs / 1000.0)
+      }
+      return nil
+    }()
+    let relevanceScore: Double = options?.relevanceScore?.doubleValue ?? 0.0
+
+    // Create update request struct with compressed JSON
+    let updateRequest = UpdateActivityRequest(
+      jsonString: compressedJson,
+      staleDate: staleDate,
+      relevanceScore: relevanceScore
+    )
+
+    do {
+      try await liveActivityService.updateActivity(byName: activityId, request: updateRequest)
+    } catch {
+      throw mapError(error)
+    }
+  }
+
+  func endLiveActivity(activityId: String, options: EndVoltraOptions?) async throws {
+    guard #available(iOS 16.2, *) else { throw VoltraErrors.unsupportedOS }
+
+    // Convert dismissal policy options to ActivityKit type
+    let dismissalPolicy = convertToActivityKitDismissalPolicy(options?.dismissalPolicy)
+
+    do {
+      try await liveActivityService.endActivity(byName: activityId, dismissalPolicy: dismissalPolicy)
+    } catch {
+      throw mapError(error)
+    }
+  }
+
+  func endAllLiveActivities() async throws {
+    guard #available(iOS 16.2, *) else { throw VoltraErrors.unsupportedOS }
+    await liveActivityService.endAllActivities()
+  }
+
+  func getLatestVoltraActivityId() -> String? {
+    guard #available(iOS 16.2, *) else { return nil }
+    return liveActivityService.getLatestActivity()?.id
+  }
+
+  func listVoltraActivityIds() -> [String] {
+    guard #available(iOS 16.2, *) else { return [] }
+    return liveActivityService.getAllActivities().map(\.id)
+  }
+
+  func isLiveActivityActive(name: String) -> Bool {
+    guard #available(iOS 16.2, *) else { return false }
+    return liveActivityService.isActivityActive(name: name)
+  }
+
+  func reloadLiveActivities(activityNames: [String]?) async throws {
+    guard #available(iOS 16.2, *) else { throw VoltraErrors.unsupportedOS }
+
+    let activities = liveActivityService.getAllActivities()
+
+    for activity in activities {
+      // If activityNames is provided, only reload those specific activities
+      if let names = activityNames, !names.isEmpty {
+        guard names.contains(activity.attributes.name) else { continue }
+      }
+
+      do {
+        let newState = try VoltraAttributes.ContentState(
+          uiJsonData: activity.content.state.uiJsonData
+        )
+
+        await activity.update(
+          ActivityContent(
+            state: newState,
+            staleDate: nil,
+            relevanceScore: 0.0
+          )
+        )
+        VoltraLogger.activity.info("Reloaded Live Activity '\(activity.attributes.name)'")
+      } catch {
+        VoltraLogger.activity.error("Failed to reload Live Activity '\(activity.attributes.name)': \(error)")
+      }
+    }
+  }
+
+  // MARK: - Image Preloading
+
+  func preloadImages(images: [PreloadImageOptions]) async throws -> PreloadImagesResult {
+    try await VoltraImagePreload.preloadImages(images: images)
+  }
+
+  func clearPreloadedImages(keys: [String]?) async {
+    await VoltraImagePreload.clearPreloadedImages(keys: keys)
+  }
+
+  // MARK: - Widgets
+
+  func updateWidget(widgetId: String, jsonString: String, options: UpdateWidgetOptions?) async throws {
+    try VoltraWidgetService.setWidgetData(widgetId: widgetId, jsonString: jsonString, deepLinkUrl: options?.deepLinkUrl)
+
+    // Clear any scheduled timeline so single-entry data takes effect
+    VoltraWidgetService.removeTimeline(for: widgetId)
+
+    // Reload the widget timeline
+    VoltraWidgetService.reloadTimeline(for: widgetId)
+  }
+
+  func scheduleWidget(widgetId: String, timelineJson: String) async throws {
+    try VoltraWidgetService.setTimeline(widgetId: widgetId, timelineJson: timelineJson)
+
+    // Reload the widget timeline to pick up scheduled entries
+    VoltraWidgetService.reloadTimeline(for: widgetId)
+  }
+
+  func reloadWidgets(widgetIds: [String]?) async {
+    if let ids = widgetIds, !ids.isEmpty {
+      for widgetId in ids {
+        VoltraWidgetService.reloadTimeline(for: widgetId)
+      }
+    } else {
+      VoltraWidgetService.reloadAllTimelines()
+    }
+  }
+
+  func clearWidget(widgetId: String) async {
+    VoltraWidgetService.removeAllData(for: widgetId)
+    VoltraWidgetService.reloadTimeline(for: widgetId)
+  }
+
+  func clearAllWidgets() async {
+    VoltraWidgetService.removeAllWidgets()
+    VoltraWidgetService.reloadAllTimelines()
+  }
+
+  func getActiveWidgets() async throws -> [[String: String]] {
+    try await VoltraWidgetService.getActiveWidgets()
+  }
+
+  func setWidgetServerCredentials(token: String, headers: [String: String]?) {
+    VoltraWidgetService.setWidgetServerCredentials(token: token, headers: headers)
+  }
+
+  func clearWidgetServerCredentials() {
+    VoltraWidgetService.clearWidgetServerCredentials()
+  }
+
+  // MARK: - Private Helpers
+
+  private func mapError(_ error: Error) -> Error {
+    if let moduleError = error as? VoltraErrors {
+      return moduleError
+    }
+
+    if let serviceError = error as? VoltraLiveActivityError {
+      switch serviceError {
+      case .unsupportedOS:
+        return VoltraErrors.unsupportedOS
+      case .liveActivitiesNotEnabled:
+        return VoltraErrors.liveActivitiesNotEnabled
+      case .notFound:
+        return VoltraErrors.notFound
+      }
+    }
+    return VoltraErrors.unexpectedError(error)
+  }
+
+  private func resolvePushType(channelId rawChannelId: String?) throws -> PushType? {
+    guard let rawChannelId else {
+      return pushNotificationsEnabled ? .token : nil
+    }
+
+    let channelId = rawChannelId.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !channelId.isEmpty else {
+      throw VoltraErrors.unexpectedError(
+        NSError(
+          domain: "VoltraModule",
+          code: -20,
+          userInfo: [NSLocalizedDescriptionKey: "channelId must be a non-empty string."]
+        )
+      )
+    }
+
+    guard pushNotificationsEnabled else {
+      throw VoltraErrors.unexpectedError(
+        NSError(
+          domain: "VoltraModule",
+          code: -21,
+          userInfo: [NSLocalizedDescriptionKey: "channelId requires enablePushNotifications: true in the Voltra plugin config."]
+        )
+      )
+    }
+
+    if #available(iOS 18.0, *) {
+      return .channel(channelId)
+    }
+
+    // On iOS <18, broadcast channels are unavailable, so fall back to token-based updates.
+    return .token
+  }
+
+  private func validatePayloadSize(_ compressedPayload: String, operation: String) throws {
+    let dataSize = compressedPayload.utf8.count
+    let safeBudget = VoltraConstants.compressedPayloadSafeBudget
+    let hardCap = VoltraConstants.maxPayloadSizeBytes
+    VoltraLogger.module.debug("Compressed payload: \(dataSize)B (budget \(safeBudget)B, hard cap \(hardCap)B)")
+
+    if dataSize > safeBudget {
+      throw VoltraErrors.unexpectedError(
+        NSError(
+          domain: "VoltraModule",
+          code: operation == "start" ? -10 : -11,
+          userInfo: [NSLocalizedDescriptionKey: "Compressed payload too large: \(dataSize)B (safe budget \(safeBudget)B, hard cap \(hardCap)B). Reduce the UI before \(operation == "start" ? "starting" : "updating") the Live Activity."]
+        )
+      )
+    }
+  }
+
+  private func convertToActivityKitDismissalPolicy(_ options: DismissalPolicyOptions?) -> ActivityUIDismissalPolicy {
+    guard let options = options else {
+      return .immediate
+    }
+
+    switch options.type {
+    case "immediate":
+      return .immediate
+    case "after":
+      if let timestamp = options.date?.doubleValue {
+        let date = Date(timeIntervalSince1970: timestamp / 1000.0)
+        return .after(date)
+      }
+      return .immediate
+    default:
+      return .immediate
+    }
+  }
+}

package/ios/app/VoltraOptions.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+@objc public final class StartVoltraOptions: NSObject {
+  @objc public var activityName: String?
+  @objc public var deepLinkUrl: String?
+  @objc public var staleDate: NSNumber?
+  @objc public var relevanceScore: NSNumber?
+  @objc public var channelId: String?
+}
+
+@objc public final class UpdateVoltraOptions: NSObject {
+  @objc public var staleDate: NSNumber?
+  @objc public var relevanceScore: NSNumber?
+}
+
+@objc public final class DismissalPolicyOptions: NSObject {
+  @objc public var type: String = "immediate"
+  @objc public var date: NSNumber?
+}
+
+@objc public final class EndVoltraOptions: NSObject {
+  @objc public var dismissalPolicy: DismissalPolicyOptions?
+}
+
+@objc public final class UpdateWidgetOptions: NSObject {
+  @objc public var deepLinkUrl: String?
+}

package/ios/app/VoltraViewComponentView.h

@@ -0,0 +1,10 @@
+#import <React/RCTViewComponentView.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface VoltraViewComponentView : RCTViewComponentView
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/app/VoltraViewComponentView.mm

@@ -0,0 +1,67 @@
+#import "VoltraViewComponentView.h"
+
+#if __has_include("Voltra/Voltra-Swift.h")
+#import "Voltra/Voltra-Swift.h"
+#else
+#import "Voltra-Swift.h"
+#endif
+
+#import <react/renderer/components/VoltraSpec/ComponentDescriptors.h>
+#import <react/renderer/components/VoltraSpec/Props.h>
+#import <react/renderer/components/VoltraSpec/RCTComponentViewHelpers.h>
+
+using namespace facebook::react;
+
+@interface VoltraViewComponentView () <RCTVoltraViewViewProtocol>
+@end
+
+@implementation VoltraViewComponentView {
+  VoltraViewRoot *_contentView;
+}
+
+- (instancetype)initWithFrame:(CGRect)frame {
+  if (self = [super initWithFrame:frame]) {
+    _contentView = [[VoltraViewRoot alloc] initWithFrame:CGRectZero];
+    [self addSubview:_contentView];
+  }
+  return self;
+}
+
+- (instancetype)init {
+  return [self initWithFrame:CGRectZero];
+}
+
+- (void)updateProps:(Props::Shared const &)props
+           oldProps:(Props::Shared const &)oldProps {
+  const auto &oldViewProps =
+      *std::static_pointer_cast<const VoltraViewProps>(_props);
+  const auto &newViewProps =
+      *std::static_pointer_cast<const VoltraViewProps>(props);
+
+  if (oldViewProps.viewId != newViewProps.viewId) {
+    NSString *viewId =
+        [[NSString alloc] initWithUTF8String:newViewProps.viewId.c_str()]
+            ?: @"";
+    [_contentView setViewId:viewId];
+  }
+
+  if (oldViewProps.payload != newViewProps.payload) {
+    NSString *payload =
+        [[NSString alloc] initWithUTF8String:newViewProps.payload.c_str()]
+            ?: @"";
+    [_contentView setPayload:payload];
+  }
+
+  [super updateProps:props oldProps:oldProps];
+}
+
+- (void)layoutSubviews {
+  [super layoutSubviews];
+  _contentView.frame = self.bounds;
+}
+
++ (ComponentDescriptorProvider)componentDescriptorProvider {
+  return concreteComponentDescriptorProvider<VoltraViewComponentDescriptor>();
+}
+
+@end

package/ios/app/VoltraViewRoot.swift

@@ -0,0 +1,63 @@
+import os
+import SwiftUI
+import UIKit
+
+@objc public class VoltraViewRoot: UIView {
+  private var hostingController: UIHostingController<AnyView>?
+  private var root: VoltraNode = .empty
+  private var viewId: String = UUID().uuidString
+
+  override public init(frame: CGRect) {
+    super.init(frame: frame)
+    clipsToBounds = true
+    setupHostingController()
+  }
+
+  public required init?(coder: NSCoder) {
+    super.init(coder: coder)
+    clipsToBounds = true
+    setupHostingController()
+  }
+
+  private func setupHostingController() {
+    let view = Voltra(root: .empty, activityId: viewId)
+    let hostingController = UIHostingController(rootView: AnyView(view))
+    hostingController.view.backgroundColor = .clear
+    addSubview(hostingController.view)
+    self.hostingController = hostingController
+  }
+
+  override public func layoutSubviews() {
+    super.layoutSubviews()
+    hostingController?.view.frame = bounds
+  }
+
+  @objc public func setViewId(_ id: String) {
+    guard !id.isEmpty else { return }
+    viewId = id
+    updateView()
+  }
+
+  @objc public func setPayload(_ jsonString: String) {
+    do {
+      let json = try JSONValue.parse(from: jsonString)
+      root = VoltraNode.parse(from: json)
+    } catch {
+      VoltraLogger.module.error("Failed to parse payload in VoltraView: \(error)")
+      root = .empty
+    }
+    updateView()
+  }
+
+  private func updateView() {
+    hostingController?.view.removeFromSuperview()
+
+    let newView = Voltra(root: root, activityId: viewId)
+    let newHostingController = UIHostingController(rootView: AnyView(newView))
+    newHostingController.view.backgroundColor = .clear
+    newHostingController.view.frame = bounds
+    addSubview(newHostingController.view)
+
+    hostingController = newHostingController
+  }
+}

package/ios/app/VoltraWidgetService.swift

@@ -0,0 +1,154 @@
+import Foundation
+import os
+import WidgetKit
+
+/// App-side facade for all widget operations.
+///
+/// Delegates persistence to `VoltraWidgetDefaults` and system reload notifications
+/// to `WidgetCenter`, so callers have a single collaborator and the storage layer
+/// can be swapped without touching orchestration code.
+///
+/// Note: `VoltraWidgetDefaults` intentionally remains in `ios/shared/` because the
+/// widget extension target reads from it directly — this service is app-target only.
+enum VoltraWidgetService {
+  // MARK: - Storage (write)
+
+  static func setWidgetData(widgetId: String, jsonString: String, deepLinkUrl: String?) throws {
+    try VoltraWidgetDefaults.setWidgetJson(jsonString, for: widgetId, deepLinkUrl: deepLinkUrl)
+    VoltraLogger.widget.info("Widget data stored for '\(widgetId)'")
+  }
+
+  static func setTimeline(widgetId: String, timelineJson: String) throws {
+    try VoltraWidgetDefaults.setTimeline(timelineJson, for: widgetId)
+    VoltraLogger.widget.info("Timeline stored for '\(widgetId)'")
+  }
+
+  // MARK: - Storage (remove)
+
+  static func removeAllData(for widgetId: String) {
+    VoltraWidgetDefaults.removeAllData(for: widgetId)
+  }
+
+  static func removeTimeline(for widgetId: String) {
+    VoltraWidgetDefaults.removeTimeline(for: widgetId)
+  }
+
+  static func removeAllWidgets() {
+    VoltraWidgetDefaults.removeAllWidgets()
+  }
+
+  // MARK: - Reload
+
+  static func reloadTimeline(for widgetId: String) {
+    WidgetCenter.shared.reloadTimelines(ofKind: "\(VoltraStorageKeys.widgetKindPrefix)\(widgetId)")
+    VoltraLogger.widget.info("Reloaded timeline for '\(widgetId)'")
+  }
+
+  static func reloadAllTimelines() {
+    WidgetCenter.shared.reloadAllTimelines()
+    VoltraLogger.widget.info("Reloaded all timelines")
+  }
+
+  // MARK: - Server credentials
+
+  /// Saves widget server credentials to the Keychain and reloads all widget timelines
+  /// so extensions can use them on the next fetch.
+  static func setWidgetServerCredentials(token: String, headers: [String: String]?) {
+    VoltraKeychainHelper.saveToken(token)
+    if let headers = headers {
+      VoltraKeychainHelper.saveHeaders(headers)
+    } else {
+      VoltraKeychainHelper.deleteHeaders()
+    }
+    VoltraLogger.widget.info("Server credentials saved")
+    reloadAllTimelines()
+  }
+
+  /// Clears widget server credentials from the Keychain and reloads all widget timelines.
+  static func clearWidgetServerCredentials() {
+    VoltraKeychainHelper.clearAll()
+    VoltraLogger.widget.info("Server credentials cleared")
+    reloadAllTimelines()
+  }
+
+  // MARK: - Query
+
+  /// Returns active widgets as dictionaries with `name`, `kind`, and `family` keys.
+  static func getActiveWidgets() async throws -> [[String: String]] {
+    try await withCheckedThrowingContinuation { continuation in
+      WidgetCenter.shared.getCurrentConfigurations { result in
+        switch result {
+        case let .success(widgetInfos):
+          let mapped = widgetInfos.map { widget -> [String: String] in
+            let prefix = VoltraStorageKeys.widgetKindPrefix
+            let name = widget.kind.hasPrefix(prefix)
+              ? String(widget.kind.dropFirst(prefix.count))
+              : widget.kind
+
+            return [
+              "name": name,
+              "kind": widget.kind,
+              "family": mapWidgetFamily(widget.family),
+            ]
+          }
+          continuation.resume(returning: mapped)
+        case let .failure(error):
+          continuation.resume(throwing: error)
+        }
+      }
+    }
+  }
+
+  /// Returns the set of widget IDs currently installed on the device.
+  /// Only IDs whose kind carries the Voltra prefix are included.
+  static func getInstalledWidgetIds() async throws -> Set<String> {
+    try await withCheckedThrowingContinuation { continuation in
+      WidgetCenter.shared.getCurrentConfigurations { result in
+        switch result {
+        case let .success(configs):
+          let ids = Set(configs.compactMap { config -> String? in
+            let prefix = VoltraStorageKeys.widgetKindPrefix
+            guard config.kind.hasPrefix(prefix) else { return nil }
+            return String(config.kind.dropFirst(prefix.count))
+          })
+          continuation.resume(returning: ids)
+        case let .failure(error):
+          continuation.resume(throwing: error)
+        }
+      }
+    }
+  }
+
+  // MARK: - Maintenance
+
+  /// Removes persisted data for any widget that is known to the app but no longer
+  /// installed on the device. Safe to call fire-and-forget from app startup.
+  static func cleanupOrphanedData() {
+    let knownWidgetIds = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetIds) as? [String] ?? []
+    guard !knownWidgetIds.isEmpty else { return }
+
+    Task {
+      guard let installedIds = try? await getInstalledWidgetIds() else { return }
+
+      for widgetId in knownWidgetIds where !installedIds.contains(widgetId) {
+        VoltraWidgetDefaults.removeAllData(for: widgetId)
+        VoltraLogger.widget.info("Cleaned up orphaned data for '\(widgetId)'")
+      }
+    }
+  }
+
+  // MARK: - Private helpers
+
+  private static func mapWidgetFamily(_ family: WidgetFamily) -> String {
+    switch family {
+    case .systemSmall: return "systemSmall"
+    case .systemMedium: return "systemMedium"
+    case .systemLarge: return "systemLarge"
+    case .systemExtraLarge: return "systemExtraLarge"
+    case .accessoryCircular: return "accessoryCircular"
+    case .accessoryRectangular: return "accessoryRectangular"
+    case .accessoryInline: return "accessoryInline"
+    @unknown default: return "unknown"
+    }
+  }
+}