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

package/ios/shared/VoltraElement.swift

@@ -0,0 +1,153 @@
+import Foundation
+
+/// A single component element in the Voltra UI tree
+public struct VoltraElement: Hashable {
+  /// Component type name (e.g., "VStack", "Text", "Button")
+  public let type: String
+
+  /// Optional identifier for the element
+  public let id: String?
+
+  /// Child nodes or text content
+  public let children: VoltraNode?
+
+  /// Raw properties (stored as JSONValue for type safety)
+  private let _props: [String: JSONValue]?
+
+  /// Optional stylesheet for resolving style references
+  public let stylesheet: [[String: JSONValue]]?
+
+  /// Optional shared elements for resolving element references
+  public let sharedElements: [JSONValue]?
+
+  // MARK: - Hashable
+
+  public func hash(into hasher: inout Hasher) {
+    hasher.combine(type)
+    hasher.combine(id)
+    hasher.combine(children)
+    hasher.combine(_props)
+  }
+
+  public static func == (lhs: VoltraElement, rhs: VoltraElement) -> Bool {
+    lhs.type == rhs.type &&
+      lhs.id == rhs.id &&
+      lhs.children == rhs.children &&
+      lhs._props == rhs._props
+  }
+
+  // MARK: - Computed Properties
+
+  /// Expanded props with full property names
+  public var props: [String: JSONValue]? {
+    guard let props = _props else { return nil }
+    var expanded: [String: JSONValue] = [:]
+    for (key, value) in props {
+      // Expand short key to full name using unified ShortNames mapping
+      let fullKey = ShortNames.expand(key)
+      expanded[fullKey] = value
+    }
+    return expanded.isEmpty ? nil : expanded
+  }
+
+  /// Style dictionary with expanded keys
+  public var style: [String: JSONValue]? {
+    guard let styleValue = props?["style"] else {
+      return nil
+    }
+
+    let styleDict: [String: JSONValue]
+
+    // Handle stylesheet reference (integer index)
+    if let index = styleValue.intValue,
+       let stylesheet = stylesheet,
+       index >= 0, index < stylesheet.count
+    {
+      styleDict = stylesheet[index]
+    }
+    // Handle inline style (object)
+    else if let objectValue = styleValue.objectValue {
+      styleDict = objectValue
+    } else {
+      return nil
+    }
+
+    var expanded: [String: JSONValue] = [:]
+    for (key, value) in styleDict {
+      // Use unified ShortNames mapping for style properties
+      let expandedKey = ShortNames.expand(key)
+      expanded[expandedKey] = value
+    }
+
+    return expanded
+  }
+
+  // MARK: - Initialization
+
+  /// Initialize from JSONValue (no serialization roundtrip)
+  /// - 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) {
+    guard case let .object(dict) = json else {
+      return nil
+    }
+
+    // Decode component type as Int (numeric ID) and convert to component name
+    guard case let .int(typeID) = dict["t"],
+          let componentTypeID = ComponentTypeID(rawValue: typeID)
+    else {
+      return nil
+    }
+    type = componentTypeID.componentName
+
+    // Extract id
+    id = dict["i"]?.stringValue
+
+    // Extract children
+    if let childrenValue = dict["c"] {
+      children = VoltraNode(from: childrenValue, stylesheet: stylesheet, sharedElements: sharedElements)
+    } else {
+      children = nil
+    }
+
+    // Extract props
+    if let propsValue = dict["p"], case let .object(propsDict) = propsValue {
+      _props = propsDict
+    } else {
+      _props = nil
+    }
+
+    // Store stylesheet reference
+    self.stylesheet = stylesheet
+
+    // Store shared elements reference
+    self.sharedElements = sharedElements
+  }
+
+  /// Get component prop by name - handles both single component and array
+  public func componentProp(_ propName: String) -> VoltraNode {
+    guard let propValue = props?[propName] else { return .empty }
+
+    return VoltraNode(from: propValue, stylesheet: stylesheet, sharedElements: sharedElements)
+  }
+
+  /// Decode parameters from props
+  public func parameters<T: Decodable>(_: T.Type) -> T {
+    guard let props = props else {
+      // Return default instance if decoding fails
+      return try! JSONDecoder().decode(T.self, from: "{}".data(using: .utf8)!)
+    }
+
+    do {
+      // Convert JSONValue dictionary to [String: Any] for JSONSerialization
+      let dict = props.mapValues { $0.toAny() }
+      let jsonData = try JSONSerialization.data(withJSONObject: dict, options: [])
+      return try JSONDecoder().decode(T.self, from: jsonData)
+    } catch {
+      // Return default instance if decoding fails
+      return try! JSONDecoder().decode(T.self, from: "{}".data(using: .utf8)!)
+    }
+  }
+}

package/ios/shared/VoltraEvent.swift

@@ -0,0 +1,72 @@
+import Foundation
+
+// MARK: - Event Types
+
+/// All Voltra event types with their associated data
+public enum VoltraEventType {
+  /// Persistent events (widget → app, survives app death)
+  case interaction(source: String, identifier: String, payload: String?)
+
+  // Transient events (main app only, in-memory)
+  case stateChange(activityName: String, state: String)
+  case tokenReceived(activityName: String, pushToken: String)
+  case pushToStartTokenReceived(token: String)
+
+  /// Whether this event should be persisted to UserDefaults (survives app death)
+  var isPersistent: Bool {
+    switch self {
+    case .interaction:
+      return true
+    default:
+      return false
+    }
+  }
+
+  /// The event name used for JS bridge
+  var name: String {
+    switch self {
+    case .interaction:
+      return "interaction"
+    case .stateChange:
+      return "stateChange"
+    case .tokenReceived:
+      return "activityTokenReceived"
+    case .pushToStartTokenReceived:
+      return "activityPushToStartTokenReceived"
+    }
+  }
+
+  /// Convert to dictionary for JS bridge
+  var asDictionary: [String: Any] {
+    var dict: [String: Any] = ["type": name]
+
+    switch self {
+    case let .interaction(source, identifier, payload):
+      dict["source"] = source
+      dict["timestamp"] = Date().timeIntervalSince1970
+      dict["identifier"] = identifier
+      dict["payload"] = payload ?? ""
+
+    case let .stateChange(activityName, state):
+      dict["timestamp"] = Date().timeIntervalSince1970
+      dict["activityName"] = activityName
+      dict["activityState"] = state
+
+    case let .tokenReceived(activityName, pushToken):
+      dict["timestamp"] = Date().timeIntervalSince1970
+      dict["activityName"] = activityName
+      dict["pushToken"] = pushToken
+
+    case let .pushToStartTokenReceived(token):
+      dict["pushToStartToken"] = token
+    }
+
+    return dict
+  }
+}
+
+// MARK: - Notification Name
+
+extension Notification.Name {
+  static let voltraEvent = Notification.Name("voltraEvent")
+}

package/ios/shared/VoltraEventBus.swift

@@ -0,0 +1,80 @@
+import Foundation
+import os
+
+/// A centralized event bus that manages Voltra events
+/// - Persistent events (interactions): routed through UserDefaults for cross-process delivery
+/// - Transient events (state changes, tokens): routed through NotificationCenter for in-process delivery
+public class VoltraEventBus {
+  public static let shared = VoltraEventBus()
+
+  private var observer: NSObjectProtocol?
+  private let lock = NSLock()
+
+  private init() {}
+
+  /// Send an event. Routing is automatic based on event type:
+  /// - Persistent events → UserDefaults (survives app death, cross-process) + NotificationCenter (hot delivery)
+  /// - Transient events → NotificationCenter only (in-memory, same process)
+  public func send(_ event: VoltraEventType) {
+    // Compute dictionary once to ensure consistent timestamp across all delivery paths
+    let eventData = event.asDictionary
+
+    if event.isPersistent {
+      // Persistent: write to UserDefaults first (for widget → app communication, survives app death)
+      VoltraPersistentEventQueue.write(eventData)
+    }
+
+    // Always post to NotificationCenter for immediate delivery when app is running
+    NotificationCenter.default.post(
+      name: .voltraEvent,
+      object: nil,
+      userInfo: eventData
+    )
+  }
+
+  /// Subscribe to Voltra events. This will:
+  /// 1. Replay any persisted events from UserDefaults (cold start)
+  /// 2. Set up a NotificationCenter observer for all events (hot delivery)
+  ///
+  /// - Parameter handler: A closure that receives the event name and event data dictionary
+  public func subscribe(handler: @escaping (String, [String: Any]) -> Void) {
+    lock.lock()
+    defer { lock.unlock() }
+
+    // 1. Replay persisted events from UserDefaults (interactions from widget)
+    let persistedEvents = VoltraPersistentEventQueue.popAll()
+    for event in persistedEvents {
+      handler(event.name, event.data)
+    }
+    VoltraLogger.event.info("Replayed \(persistedEvents.count) persisted events")
+
+    // 2. Listen for all events via NotificationCenter (hot delivery)
+    observer = NotificationCenter.default.addObserver(
+      forName: .voltraEvent,
+      object: nil,
+      queue: .main
+    ) { notification in
+      guard let userInfo = notification.userInfo as? [String: Any],
+            let eventName = userInfo["type"] as? String
+      else {
+        return
+      }
+      handler(eventName, userInfo)
+    }
+  }
+
+  /// Unsubscribe from Voltra events
+  public func unsubscribe() {
+    lock.lock()
+    defer { lock.unlock() }
+
+    if let observer = observer {
+      NotificationCenter.default.removeObserver(observer)
+      self.observer = nil
+    }
+  }
+
+  deinit {
+    unsubscribe()
+  }
+}

package/ios/shared/VoltraImageStore.swift

@@ -0,0 +1,119 @@
+import Foundation
+import UIKit
+
+/// Utility for reading/writing preloaded images to App Group shared storage
+public enum VoltraImageStore {
+  private static let imageDirectoryName = "voltra_images"
+
+  /// Get the shared container URL for storing images
+  public static func imageDirectory() -> URL? {
+    guard let groupId = VoltraConfig.groupIdentifier(),
+          let containerURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: groupId)
+    else { return nil }
+
+    return containerURL.appendingPathComponent(imageDirectoryName, isDirectory: true)
+  }
+
+  /// Ensure the image directory exists
+  private static func ensureDirectoryExists() throws {
+    guard let directory = imageDirectory() else {
+      throw VoltraImageStoreError.appGroupNotConfigured
+    }
+
+    if !FileManager.default.fileExists(atPath: directory.path) {
+      try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    }
+  }
+
+  /// Save image data to App Group storage
+  /// - Parameters:
+  ///   - data: The image data to save
+  ///   - key: The key/name to use for the image (will be used as assetName)
+  public static func saveImage(_ data: Data, key: String) throws {
+    try ensureDirectoryExists()
+
+    guard let directory = imageDirectory() else {
+      throw VoltraImageStoreError.appGroupNotConfigured
+    }
+
+    let sanitizedKey = sanitizeKey(key)
+    let fileURL = directory.appendingPathComponent(sanitizedKey)
+
+    // Write atomically to ensure the file is fully written before it becomes visible
+    try data.write(to: fileURL, options: .atomic)
+  }
+
+  /// Load a preloaded image from App Group storage
+  /// - Parameter key: The key/name of the image
+  /// - Returns: The UIImage if found, nil otherwise
+  public static func loadImage(key: String) -> UIImage? {
+    guard let directory = imageDirectory() else { return nil }
+
+    let sanitizedKey = sanitizeKey(key)
+    let fileURL = directory.appendingPathComponent(sanitizedKey)
+
+    guard FileManager.default.fileExists(atPath: fileURL.path),
+          let data = try? Data(contentsOf: fileURL),
+          let image = UIImage(data: data)
+    else { return nil }
+
+    return image
+  }
+
+  /// Check if a preloaded image exists
+  /// - Parameter key: The key/name of the image
+  /// - Returns: true if the image exists in App Group storage
+  public static func imageExists(key: String) -> Bool {
+    guard let directory = imageDirectory() else { return false }
+
+    let sanitizedKey = sanitizeKey(key)
+    let fileURL = directory.appendingPathComponent(sanitizedKey)
+
+    return FileManager.default.fileExists(atPath: fileURL.path)
+  }
+
+  /// Remove a preloaded image from App Group storage
+  /// - Parameter key: The key/name of the image to remove
+  public static func removeImage(key: String) {
+    guard let directory = imageDirectory() else { return }
+
+    let sanitizedKey = sanitizeKey(key)
+    let fileURL = directory.appendingPathComponent(sanitizedKey)
+
+    try? FileManager.default.removeItem(at: fileURL)
+  }
+
+  /// Remove multiple preloaded images
+  /// - Parameter keys: The keys/names of the images to remove
+  public static func removeImages(keys: [String]) {
+    for key in keys {
+      removeImage(key: key)
+    }
+  }
+
+  /// Clear all preloaded images from App Group storage
+  public static func clearAll() {
+    guard let directory = imageDirectory() else { return }
+
+    try? FileManager.default.removeItem(at: directory)
+  }
+
+  /// Sanitize the key to be a valid filename
+  private static func sanitizeKey(_ key: String) -> String {
+    // Replace any characters that might cause issues in filenames
+    let invalidChars = CharacterSet(charactersIn: "/\\:*?\"<>|")
+    return key.components(separatedBy: invalidChars).joined(separator: "_")
+  }
+}
+
+/// Errors that can occur during image store operations
+public enum VoltraImageStoreError: Error, LocalizedError {
+  case appGroupNotConfigured
+
+  public var errorDescription: String? {
+    switch self {
+    case .appGroupNotConfigured:
+      return "App Group not configured. Set 'groupIdentifier' in the Voltra config plugin."
+    }
+  }
+}

package/ios/shared/VoltraInitialStateLocale.swift

@@ -0,0 +1,54 @@
+import Foundation
+
+/// Matches `@use-voltra/expo-plugin` `localePick` fallback order for bundled widget initial JSON.
+public enum VoltraInitialStateLocale {
+  public static func pickJson(from perLocale: [String: String], preferredLanguages: [String]) -> String? {
+    let entries = perLocale.filter { !$0.value.isEmpty }
+    if entries.isEmpty {
+      return nil
+    }
+
+    func normalize(_ tag: String) -> String {
+      tag.trimmingCharacters(in: .whitespacesAndNewlines)
+        .lowercased()
+        .replacingOccurrences(of: "_", with: "-")
+    }
+
+    var byNorm: [String: String] = [:]
+    for (k, v) in entries {
+      byNorm[normalize(k)] = v
+    }
+
+    for pref in preferredLanguages {
+      let n = normalize(pref)
+      if let direct = byNorm[n] {
+        return direct
+      }
+      let lang = n.split(separator: "-").first.map(String.init) ?? n
+      for (key, val) in entries {
+        let kn = normalize(key)
+        let keyLang = kn.split(separator: "-").first.map(String.init) ?? kn
+        if keyLang == lang {
+          return val
+        }
+      }
+    }
+
+    if let en = byNorm["en"] {
+      return en
+    }
+    if let def = byNorm["__default"] {
+      return def
+    }
+
+    let sorted = entries.keys.sorted()
+    guard let firstKey = sorted.first else {
+      return nil
+    }
+    return entries[firstKey]
+  }
+
+  public static func preferredLanguageTags() -> [String] {
+    Locale.preferredLanguages
+  }
+}

package/ios/shared/VoltraInteractionIntent.swift

@@ -0,0 +1,39 @@
+import ActivityKit
+import AppIntents
+
+public struct VoltraInteractionIntent: LiveActivityIntent {
+  public static var title: LocalizedStringResource = "Interact"
+  public static var isDiscoverable: Bool = false
+
+  /// The ID of the activity
+  @Parameter(title: "Activity ID")
+  var activityId: String
+
+  /// The ID of the component in your JSON (e.g., "button_1", "pause_btn")
+  @Parameter(title: "Component ID")
+  var componentId: String
+
+  // Optional: Only if you need to pass extra data (like "true/false" or "toggle")
+  @Parameter(title: "Payload")
+  var payload: String?
+
+  public init() {}
+
+  public init(activityId: String, componentId: String, payload: String? = nil) {
+    self.activityId = activityId
+    self.componentId = componentId
+    self.payload = payload
+  }
+
+  public func perform() async throws -> some IntentResult {
+    VoltraEventBus.shared.send(
+      .interaction(
+        source: activityId,
+        identifier: componentId,
+        payload: payload
+      )
+    )
+
+    return .result()
+  }
+}

package/ios/shared/VoltraKeychainHelper.swift

@@ -0,0 +1,178 @@
+import Foundation
+import os
+import Security
+
+/// Shared Keychain helper for securely storing and reading widget server credentials.
+/// Used by both the main app (to write credentials) and the widget extension (to read them).
+public enum VoltraKeychainHelper {
+  /// Keychain service identifier for Voltra widget credentials
+  private static let service = "voltra-widget-server-credentials"
+
+  /// Key for the auth token
+  private static let tokenKey = "auth_token"
+
+  /// Key for additional headers (stored as JSON)
+  private static let headersKey = "custom_headers"
+
+  /// Get the Keychain Access Group from Info.plist (set by the config plugin)
+  private static func keychainGroup() -> String? {
+    VoltraConfig.keychainGroup()
+  }
+
+  // MARK: - Token Storage
+
+  /// Save an auth token to the shared Keychain.
+  /// Called from the main app after user login.
+  @discardableResult
+  public static func saveToken(_ token: String) -> Bool {
+    guard let data = token.data(using: .utf8) else { return false }
+
+    // Delete existing token first
+    deleteToken()
+
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: tokenKey,
+      kSecValueData as String: data,
+      kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
+    ]
+
+    // Add access group if configured (for sharing between app and extension)
+    if let group = keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    let status = SecItemAdd(query as CFDictionary, nil)
+    if status != errSecSuccess {
+      VoltraLogger.keychain.error("Failed to save token: \(status)")
+    }
+    return status == errSecSuccess
+  }
+
+  /// Read the auth token from the shared Keychain.
+  /// Called from the widget extension's TimelineProvider.
+  public static func readToken() -> String? {
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: tokenKey,
+      kSecReturnData as String: true,
+      kSecMatchLimit as String: kSecMatchLimitOne,
+    ]
+
+    if let group = keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    var item: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+    guard status == errSecSuccess, let data = item as? Data else {
+      if status != errSecItemNotFound {
+        VoltraLogger.keychain.error("Failed to read token: \(status)")
+      }
+      return nil
+    }
+
+    return String(data: data, encoding: .utf8)
+  }
+
+  /// Delete the auth token from the shared Keychain.
+  @discardableResult
+  public static func deleteToken() -> Bool {
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: tokenKey,
+    ]
+
+    if let group = keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    let status = SecItemDelete(query as CFDictionary)
+    return status == errSecSuccess || status == errSecItemNotFound
+  }
+
+  // MARK: - Custom Headers Storage
+
+  /// Save additional custom headers to the shared Keychain.
+  @discardableResult
+  public static func saveHeaders(_ headers: [String: String]) -> Bool {
+    guard let data = try? JSONSerialization.data(withJSONObject: headers) else { return false }
+
+    // Delete existing headers first
+    deleteHeaders()
+
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: headersKey,
+      kSecValueData as String: data,
+      kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
+    ]
+
+    if let group = keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    let status = SecItemAdd(query as CFDictionary, nil)
+    if status != errSecSuccess {
+      VoltraLogger.keychain.error("Failed to save headers: \(status)")
+    }
+    return status == errSecSuccess
+  }
+
+  /// Read custom headers from the shared Keychain.
+  public static func readHeaders() -> [String: String]? {
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: headersKey,
+      kSecReturnData as String: true,
+      kSecMatchLimit as String: kSecMatchLimitOne,
+    ]
+
+    if let group = keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    var item: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &item)
+
+    guard status == errSecSuccess,
+          let data = item as? Data,
+          let headers = try? JSONSerialization.jsonObject(with: data) as? [String: String]
+    else {
+      return nil
+    }
+
+    return headers
+  }
+
+  /// Delete custom headers from the shared Keychain.
+  @discardableResult
+  public static func deleteHeaders() -> Bool {
+    var query: [String: Any] = [
+      kSecClass as String: kSecClassGenericPassword,
+      kSecAttrService as String: service,
+      kSecAttrAccount as String: headersKey,
+    ]
+
+    if let group = keychainGroup() {
+      query[kSecAttrAccessGroup as String] = group
+    }
+
+    let status = SecItemDelete(query as CFDictionary)
+    return status == errSecSuccess || status == errSecItemNotFound
+  }
+
+  // MARK: - Convenience
+
+  /// Clear all Voltra widget server credentials from the Keychain.
+  public static func clearAll() {
+    deleteToken()
+    deleteHeaders()
+  }
+}