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

package/ios/shared/VoltraLiveActivityPayload.swift

@@ -0,0 +1,113 @@
+import Foundation
+
+/// The parsed root payload for a Live Activity update
+/// Handles the one-time JSON parsing and region extraction
+public struct VoltraLiveActivityPayload: Hashable {
+  /// Parsed UI trees for each region
+  public let regions: [VoltraRegion: [VoltraNode]]
+
+  /// Optional tint color for Dynamic Island keyline
+  public let keylineTint: String?
+
+  /// Optional background tint for Lock Screen
+  public let activityBackgroundTint: String?
+
+  /// Whether this payload represents an unsupported version (renders empty)
+  public let isUnsupportedVersion: Bool
+
+  /// Parse from decompressed JSON string (called once per update)
+  public init(jsonString: String) throws {
+    let root = try JSONValue.parse(from: jsonString)
+
+    // Migrate to current version if needed
+    guard let migrated = try VoltraPayloadMigrator.migrateToCurrentVersion(root) else {
+      // Unsupported version (future version) - render empty
+      regions = [:]
+      keylineTint = nil
+      activityBackgroundTint = nil
+      isUnsupportedVersion = true
+      return
+    }
+
+    // Extract regions directly from the parsed tree
+    regions = try Self.extractRegions(from: migrated)
+    keylineTint = migrated["isl_keyline_tint"]?.stringValue
+    activityBackgroundTint = migrated["ls_background_tint"]?.stringValue
+    isUnsupportedVersion = false
+  }
+
+  /// Extract regions from the parsed JSON tree
+  private static func extractRegions(from root: JSONValue) throws -> [VoltraRegion: [VoltraNode]] {
+    var regions: [VoltraRegion: [VoltraNode]] = [:]
+
+    // Handle array case (same UI for all regions)
+    if case .array = root {
+      let nodes = try parseNodes(from: root, stylesheet: nil, sharedElements: nil)
+      for region in VoltraRegion.allCases {
+        regions[region] = nodes
+      }
+      return regions
+    }
+
+    // Handle object case (region-specific UIs)
+    guard case let .object(rootObject) = root else {
+      throw NSError(domain: "VoltraLiveActivityPayload",
+                    code: -1,
+                    userInfo: [NSLocalizedDescriptionKey: "Invalid root JSON type"])
+    }
+
+    // Extract the shared stylesheet from root (key "s")
+    let stylesheet = extractStylesheet(from: rootObject)
+
+    // Extract the shared elements from root (key "e") for element deduplication
+    let sharedElements = extractSharedElements(from: rootObject)
+
+    // Extract components for each region
+    for region in VoltraRegion.allCases {
+      if let regionValue = rootObject[region.jsonKey] {
+        let nodes = try parseNodes(from: regionValue, stylesheet: stylesheet, sharedElements: sharedElements)
+        regions[region] = nodes
+      }
+    }
+
+    return regions
+  }
+
+  /// Parse an array of JSON values into VoltraNodes
+  private static func parseNodes(from value: JSONValue, stylesheet: [[String: JSONValue]]?, sharedElements: [JSONValue]?) throws -> [VoltraNode] {
+    if case let .array(nodeArray) = value {
+      return try nodeArray.compactMap { nodeJson in
+        guard case .object = nodeJson else { return nil }
+        return try VoltraNode(from: nodeJson, stylesheet: stylesheet, sharedElements: sharedElements)
+      }
+    } else if case .object = value {
+      // Single node wrapped in array
+      return try [VoltraNode(from: value, stylesheet: stylesheet, sharedElements: sharedElements)]
+    } else {
+      return []
+    }
+  }
+
+  /// Extract the shared stylesheet from root
+  private static func extractStylesheet(from root: [String: JSONValue]) -> [[String: JSONValue]]? {
+    guard case let .array(stylesheetArray) = root["s"] else {
+      return nil
+    }
+
+    // Convert JSONValue array to [[String: JSONValue]]
+    return stylesheetArray.compactMap { item in
+      if case let .object(dict) = item {
+        return dict
+      }
+      return nil
+    }
+  }
+
+  /// Extract the shared elements array from root (for element deduplication)
+  private static func extractSharedElements(from root: [String: JSONValue]) -> [JSONValue]? {
+    guard case let .array(elementsArray) = root["e"] else {
+      return nil
+    }
+    return elementsArray
+  }
+}

package/ios/shared/VoltraLogger.swift

@@ -0,0 +1,30 @@
+import os
+
+/// Centralized loggers for the Voltra module.
+///
+/// Each category maps to a distinct domain of concern so logs can be filtered
+/// independently in Console.app or via `log stream --predicate 'subsystem == "com.voltra"'`.
+enum VoltraLogger {
+  private static let subsystem = "com.voltra"
+
+  /// Expo module boundary (JS → native calls, error remapping)
+  static let module = Logger(subsystem: subsystem, category: "module")
+
+  /// Widget data, timelines, server credentials, WidgetCenter reloads
+  static let widget = Logger(subsystem: subsystem, category: "widget")
+
+  /// Live Activity lifecycle (create, update, end, reload)
+  static let activity = Logger(subsystem: subsystem, category: "liveActivity")
+
+  /// Image preloading and the shared image store
+  static let image = Logger(subsystem: subsystem, category: "image")
+
+  /// VoltraEventBus and VoltraPersistentEventQueue
+  static let event = Logger(subsystem: subsystem, category: "event")
+
+  /// Keychain reads and writes
+  static let keychain = Logger(subsystem: subsystem, category: "keychain")
+
+  /// UserDefaults / shared storage (VoltraWidgetDefaults)
+  static let storage = Logger(subsystem: subsystem, category: "storage")
+}

package/ios/shared/VoltraNode.swift

@@ -0,0 +1,194 @@
+import Foundation
+import SwiftUI
+
+/// Represents anything that can be rendered (like ReactNode)
+public indirect enum VoltraNode: Hashable, View {
+  /// A component element
+  case element(VoltraElement)
+
+  /// Multiple nodes (fragment/array)
+  case array([VoltraNode])
+
+  /// Plain text content
+  case text(String)
+
+  /// Nothing to render
+  case empty
+
+  // MARK: - Initialization
+
+  /// Initialize from JSONValue (handles all types)
+  /// - Parameters:
+  ///   - json: The JSON value to parse
+  ///   - stylesheet: Optional shared stylesheet for style deduplication
+  ///   - sharedElements: Optional shared elements array for element deduplication
+  public init(from json: JSONValue, stylesheet: [[String: JSONValue]]? = nil, sharedElements: [JSONValue]? = nil) {
+    switch json {
+    case let .string(text):
+      self = .text(text)
+    case let .int(num):
+      self = .text(String(num))
+    case let .double(num):
+      self = .text(String(num))
+    case let .bool(val):
+      self = .text(String(val))
+    case .null:
+      self = .empty
+    case let .array(items):
+      let nodes = items.map { VoltraNode(from: $0, stylesheet: stylesheet, sharedElements: sharedElements) }.filter { !$0.isEmpty }
+      self = nodes.isEmpty ? .empty : .array(nodes)
+    case let .object(dict):
+      // Check for element reference ($r key) and resolve from shared elements
+      if let refIndex = dict["$r"]?.intValue,
+         let sharedElements = sharedElements,
+         refIndex >= 0, refIndex < sharedElements.count
+      {
+        // Resolve reference by parsing the shared element
+        self = VoltraNode(from: sharedElements[refIndex], stylesheet: stylesheet, sharedElements: sharedElements)
+      } else if let element = VoltraElement(from: json, stylesheet: stylesheet, sharedElements: sharedElements) {
+        self = .element(element)
+      } else {
+        self = .empty
+      }
+    }
+  }
+
+  /// Check if node represents nothing
+  public var isEmpty: Bool {
+    if case .empty = self { return true }
+    return false
+  }
+
+  /// Parse a VoltraNode from JSON, extracting stylesheet and sharedElements if present
+  /// This is a convenience factory that handles the common pattern of extracting
+  /// stylesheet ("s") and sharedElements ("e") from the root JSON object.
+  /// - Parameter json: The JSON value to parse
+  /// - Returns: A parsed VoltraNode
+  public static func parse(from json: JSONValue) -> VoltraNode {
+    var stylesheet: [[String: JSONValue]]? = nil
+    var sharedElements: [JSONValue]? = nil
+
+    if case let .object(rootObject) = json {
+      // Extract stylesheet (key "s")
+      if case let .array(stylesheetArray) = rootObject["s"] {
+        stylesheet = stylesheetArray.compactMap { item in
+          if case let .object(dict) = item { return dict }
+          return nil
+        }
+      }
+      // Extract shared elements (key "e")
+      if case let .array(elementsArray) = rootObject["e"] {
+        sharedElements = elementsArray
+      }
+    }
+
+    return VoltraNode(from: json, stylesheet: stylesheet, sharedElements: sharedElements)
+  }
+
+  // MARK: - View conformance
+
+  public var body: some View {
+    switch self {
+    case let .element(element):
+      VoltraElementView(element: element)
+    case let .array(nodes):
+      // Use stable identifiers: prefer element.id, fall back to index
+      let items: [(id: String, node: VoltraNode)] = nodes.enumerated().map { offset, node in
+        let id: String
+        if case let .element(element) = node, let elementId = element.id {
+          id = elementId
+        } else {
+          id = "idx_\(offset)"
+        }
+        return (id: id, node: node)
+      }
+      ForEach(items, id: \.id) { item in
+        item.node
+      }
+    case let .text(text):
+      Text(text)
+    case .empty:
+      EmptyView()
+    }
+  }
+}
+
+/// View that renders a VoltraElement based on its type
+struct VoltraElementView: View {
+  let element: VoltraElement
+
+  var body: some View {
+    switch element.type {
+    case "Button":
+      VoltraButton(element)
+
+    case "Link":
+      VoltraLink(element)
+
+    case "VStack":
+      VoltraVStack(element)
+
+    case "HStack":
+      VoltraHStack(element)
+
+    case "View":
+      VoltraFlexView(element)
+
+    case "ZStack":
+      VoltraZStack(element)
+
+    case "Text":
+      VoltraText(element)
+
+    case "Image":
+      VoltraImage(element)
+
+    case "Symbol":
+      VoltraSymbol(element)
+
+    case "Divider":
+      VoltraDivider(element)
+
+    case "Spacer":
+      VoltraSpacer(element)
+
+    case "Label":
+      VoltraLabel(element)
+
+    case "Toggle":
+      VoltraToggle(element)
+
+    case "Gauge":
+      VoltraGauge(element)
+
+    case "LinearProgressView":
+      VoltraLinearProgressView(element)
+
+    case "CircularProgressView":
+      VoltraCircularProgressView(element)
+
+    case "Timer":
+      VoltraTimer(element)
+
+    case "GroupBox":
+      VoltraGroupBox(element)
+
+    case "LinearGradient":
+      VoltraLinearGradient(element)
+
+    case "GlassContainer":
+      VoltraGlassContainer(element)
+
+    case "Mask":
+      VoltraMask(element)
+
+    case "Chart":
+      if #available(iOS 16.0, macOS 13.0, *) {
+        VoltraChart(element)
+      }
+
+    default:
+      EmptyView()
+    }
+  }
+}

package/ios/shared/VoltraPayloadMigrator.swift

@@ -0,0 +1,63 @@
+import Foundation
+
+/// Error types for payload migration
+public enum VoltraPayloadError: Error {
+  case missingVersion
+  case invalidPayloadStructure
+}
+
+/// Protocol for migrating payloads from one version to the next
+public protocol VoltraPayloadMigration {
+  /// The source version this migration upgrades FROM
+  static var fromVersion: Int { get }
+
+  /// The target version this migration upgrades TO
+  static var toVersion: Int { get }
+
+  /// Migrate the raw JSON from the source version to the target version
+  static func migrate(_ json: JSONValue) throws -> JSONValue
+}
+
+/// Manages payload version migrations
+public enum VoltraPayloadMigrator {
+  /// Current (latest) payload version
+  public static let currentVersion = 1
+
+  /// Registered migrations, keyed by source version
+  /// When adding a new version:
+  /// 1. Increment currentVersion
+  /// 2. Add migration: [oldVersion: VOldToVNewMigration.self]
+  private static let migrations: [Int: any VoltraPayloadMigration.Type] = [:
+    // Empty for v1, add as needed:
+    // 1: V1ToV2Migration.self,
+  ]
+
+  /// Migrate a payload to the current version
+  /// - Parameter json: The raw parsed JSON payload
+  /// - Returns: Migrated JSON, or nil if version is unsupported (future version)
+  public static func migrateToCurrentVersion(_ json: JSONValue) throws -> JSONValue? {
+    guard let version = json["v"]?.intValue else {
+      throw VoltraPayloadError.missingVersion
+    }
+
+    // Future version we don't understand - silently ignore
+    if version > currentVersion {
+      return nil
+    }
+
+    var currentJson = json
+    var currentVer = version
+
+    // Apply migrations sequentially until we reach the current version
+    while currentVer < currentVersion {
+      guard let migration = migrations[currentVer] else {
+        // Gap in migration chain - shouldn't happen if migrations are maintained properly
+        return nil
+      }
+      currentJson = try migration.migrate(currentJson)
+      currentVer = migration.toVersion
+    }
+
+    return currentJson
+  }
+}

package/ios/shared/VoltraPersistentEventQueue.swift

@@ -0,0 +1,67 @@
+import Foundation
+import os
+
+/// Persistent event queue for events that must survive app death (e.g., interactions from widget)
+/// Uses UserDefaults with App Group for cross-process communication
+public enum VoltraPersistentEventQueue {
+  private static let queueKey = "Voltra_EventsQueue"
+
+  /// Write an event to the persistent queue (UserDefaults)
+  static func write(_ payload: [String: Any]) {
+    guard let group = VoltraConfig.groupIdentifier(),
+          let defaults = UserDefaults(suiteName: group),
+          JSONSerialization.isValidJSONObject(payload),
+          let data = try? JSONSerialization.data(withJSONObject: payload, options: [])
+    else {
+      VoltraLogger.event.error("Failed to write event — no group identifier or invalid payload")
+      return
+    }
+
+    let jsonString = String(data: data, encoding: .utf8) ?? "{}"
+
+    var queue = defaults.array(forKey: queueKey) as? [String] ?? []
+    queue.append(jsonString)
+    defaults.set(queue, forKey: queueKey)
+    defaults.synchronize()
+
+    let eventName = payload["type"] as? String ?? "unknown"
+    VoltraLogger.event.debug("Wrote event: \(eventName)")
+  }
+
+  /// Read all events from the persistent queue and clear it
+  /// Returns an array of (eventName, eventData) tuples
+  static func popAll() -> [(name: String, data: [String: Any])] {
+    guard let group = VoltraConfig.groupIdentifier() else {
+      VoltraLogger.event.error("popAll: No group identifier found")
+      return []
+    }
+    guard let defaults = UserDefaults(suiteName: group) else {
+      VoltraLogger.event.error("popAll: Could not access UserDefaults for group '\(group)'")
+      return []
+    }
+
+    let queue = defaults.array(forKey: queueKey) as? [String] ?? []
+    let eventCount = queue.count
+    VoltraLogger.event.debug("popAll: Found \(eventCount) events in queue")
+
+    // Clear the queue first
+    defaults.set([String](), forKey: queueKey)
+    defaults.synchronize()
+
+    // Skip processing if queue is excessively large (stale data)
+    if eventCount > 1000 {
+      VoltraLogger.event.warning("popAll: Skipping \(eventCount) stale events")
+      return []
+    }
+
+    // Parse JSON strings into event tuples
+    return queue.compactMap { jsonString -> (name: String, data: [String: Any])? in
+      guard let data = jsonString.data(using: .utf8),
+            let dict = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+            let eventName = dict["type"] as? String
+      else { return nil }
+
+      return (name: eventName, data: dict)
+    }
+  }
+}

package/ios/shared/VoltraRefreshIntent.swift

@@ -0,0 +1,29 @@
+import AppIntents
+import WidgetKit
+
+/// An AppIntent that triggers an immediate widget timeline reload.
+/// Used by the native refresh button overlay on server-driven widgets.
+@available(iOS 17.0, *)
+public struct VoltraRefreshIntent: AppIntent {
+  public static var title: LocalizedStringResource = "Refresh Widget"
+  public static var isDiscoverable: Bool = false
+
+  @Parameter(title: "Widget ID")
+  public var widgetId: String?
+
+  public init() {}
+
+  public init(widgetId: String) {
+    self.widgetId = widgetId
+  }
+
+  public func perform() async throws -> some IntentResult {
+    if let widgetId = widgetId {
+      let kind = "\(VoltraStorageKeys.widgetKindPrefix)\(widgetId)"
+      WidgetCenter.shared.reloadTimelines(ofKind: kind)
+    } else {
+      WidgetCenter.shared.reloadAllTimelines()
+    }
+    return .result()
+  }
+}

package/ios/shared/VoltraRegion.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+public enum VoltraRegion: String, Codable, Hashable, CaseIterable {
+  case lockScreen
+  case islandExpandedCenter
+  case islandExpandedLeading
+  case islandExpandedTrailing
+  case islandExpandedBottom
+  case islandCompactLeading
+  case islandCompactTrailing
+  case islandMinimal
+  case supplementalActivityFamiliesSmall
+
+  /// The JSON key for this region in the payload
+  public var jsonKey: String {
+    switch self {
+    case .lockScreen:
+      return "ls"
+    case .islandExpandedCenter:
+      return "isl_exp_c"
+    case .islandExpandedLeading:
+      return "isl_exp_l"
+    case .islandExpandedTrailing:
+      return "isl_exp_t"
+    case .islandExpandedBottom:
+      return "isl_exp_b"
+    case .islandCompactLeading:
+      return "isl_cmp_l"
+    case .islandCompactTrailing:
+      return "isl_cmp_t"
+    case .islandMinimal:
+      return "isl_min"
+    case .supplementalActivityFamiliesSmall:
+      return "saf_sm"
+    }
+  }
+}

package/ios/shared/VoltraWidgetDefaults.swift

@@ -0,0 +1,114 @@
+import Foundation
+import os
+
+/// Errors that can occur during widget persistence operations.
+public enum WidgetError: Error, LocalizedError {
+  case appGroupNotConfigured
+  case userDefaultsUnavailable
+
+  public var errorDescription: String? {
+    switch self {
+    case .appGroupNotConfigured:
+      return "App Group not configured. Set 'groupIdentifier' in the Voltra config plugin to use widgets."
+    case .userDefaultsUnavailable:
+      return "Unable to access UserDefaults for the app group."
+    }
+  }
+}
+
+/// Low-level UserDefaults CRUD for widget keys.
+/// Shared between the app target (write/clear) and the widget extension target (read).
+///
+/// Write methods throw `WidgetError` to surface configuration problems to the caller.
+/// Read and remove methods are non-throwing: they return nil / no-op when the app group
+/// is not configured, since the widget extension has no way to propagate errors.
+public enum VoltraWidgetDefaults {
+  // MARK: - Read
+
+  public static func widgetJson(for widgetId: String) -> String? {
+    try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetJson(widgetId))
+  }
+
+  public static func deepLinkUrl(for widgetId: String) -> String? {
+    try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
+  }
+
+  public static func timelineString(for widgetId: String) -> String? {
+    try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+  }
+
+  // MARK: - Write
+
+  public static func setWidgetJson(_ json: String, for widgetId: String, deepLinkUrl: String?) throws {
+    let defaults = try resolvedDefaults()
+
+    let dataSize = json.utf8.count
+    if dataSize > VoltraConstants.widgetJsonWarningSizeBytes {
+      VoltraLogger.storage.warning("Large widget payload for '\(widgetId)': \(dataSize) bytes (threshold: \(VoltraConstants.widgetJsonWarningSizeBytes) bytes)")
+    }
+
+    defaults.set(json, forKey: VoltraStorageKeys.widgetJson(widgetId))
+
+    if let url = deepLinkUrl, !url.isEmpty {
+      defaults.set(url, forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
+    } else {
+      defaults.removeObject(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
+    }
+
+    defaults.synchronize()
+  }
+
+  public static func setTimeline(_ timeline: String, for widgetId: String) throws {
+    let defaults = try resolvedDefaults()
+
+    let dataSize = timeline.utf8.count
+    if dataSize > VoltraConstants.timelineWarningSizeBytes {
+      VoltraLogger.storage.warning("Large timeline for '\(widgetId)': \(dataSize) bytes (threshold: \(VoltraConstants.timelineWarningSizeBytes) bytes)")
+    }
+
+    defaults.set(timeline, forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+    defaults.synchronize()
+  }
+
+  // MARK: - Remove
+
+  /// Removes all persisted data (json, deepLinkUrl, timeline) for a single widget.
+  /// This is the single source of truth for which keys exist per widget.
+  public static func removeAllData(for widgetId: String) {
+    guard let defaults = try? resolvedDefaults() else { return }
+    defaults.removeObject(forKey: VoltraStorageKeys.widgetJson(widgetId))
+    defaults.removeObject(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
+    defaults.removeObject(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+    defaults.synchronize()
+  }
+
+  public static func removeTimeline(for widgetId: String) {
+    guard let defaults = try? resolvedDefaults() else { return }
+    defaults.removeObject(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+    defaults.synchronize()
+  }
+
+  /// Removes all persisted data for every widget listed in the app's Info.plist.
+  public static func removeAllWidgets() {
+    guard let defaults = try? resolvedDefaults() else { return }
+    let widgetIds = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetIds) as? [String] ?? []
+    for widgetId in widgetIds {
+      defaults.removeObject(forKey: VoltraStorageKeys.widgetJson(widgetId))
+      defaults.removeObject(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
+      defaults.removeObject(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+    }
+    defaults.synchronize()
+  }
+
+  // MARK: - Private
+
+  private static func resolvedDefaults() throws -> UserDefaults {
+    guard let groupId = VoltraConfig.groupIdentifier() else {
+      throw WidgetError.appGroupNotConfigured
+    }
+    guard let defaults = UserDefaults(suiteName: groupId) else {
+      throw WidgetError.userDefaultsUnavailable
+    }
+    return defaults
+  }
+}