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

package/ios/shared/BrotliCompression.swift

@@ -0,0 +1,81 @@
+import Compression
+import Foundation
+
+public enum BrotliCompressionError: Error {
+  case encodingFailed
+  case compressionFailed(Int)
+  case base64DecodingFailed
+  case decompressionFailed
+  case stringConversionFailed
+}
+
+public enum BrotliCompression {
+  /// Compresses a JSON string using brotli compression and returns a base64-encoded string
+  /// - Parameter jsonString: The JSON string to compress
+  /// - Returns: Base64-encoded compressed data
+  /// - Throws: BrotliCompressionError if compression fails
+  public static func compress(jsonString: String) throws -> String {
+    guard let jsonData = jsonString.data(using: .utf8) else {
+      throw BrotliCompressionError.encodingFailed
+    }
+
+    let buffer = UnsafeMutablePointer<UInt8>.allocate(capacity: jsonData.count * 2)
+    defer { buffer.deallocate() }
+
+    // Compress using brotli level 2 (iOS only supports level 2)
+    let compressedSize = compression_encode_buffer(
+      buffer,
+      jsonData.count * 2,
+      jsonData.withUnsafeBytes { $0.baseAddress!.assumingMemoryBound(to: UInt8.self) },
+      jsonData.count,
+      nil,
+      COMPRESSION_BROTLI
+    )
+
+    guard compressedSize > 0 else {
+      throw BrotliCompressionError.compressionFailed(jsonData.count)
+    }
+
+    // Convert compressed data to base64 string
+    let compressedData = Data(bytes: buffer, count: compressedSize)
+    return compressedData.base64EncodedString()
+  }
+
+  /// Decompresses a base64-encoded brotli-compressed string
+  /// - Parameter base64String: Base64-encoded compressed data
+  /// - Returns: Decompressed JSON string
+  /// - Throws: BrotliCompressionError if decompression fails
+  public static func decompress(base64String: String) throws -> String {
+    // Decode base64 to Data
+    guard let compressedData = Data(base64Encoded: base64String) else {
+      throw BrotliCompressionError.base64DecodingFailed
+    }
+
+    // Estimate decompressed size (brotli typically compresses to 20-30% of original)
+    // Using 8x to ensure we have enough buffer space
+    let estimatedSize = compressedData.count * 8
+    let buffer = UnsafeMutablePointer<UInt8>.allocate(capacity: estimatedSize)
+    defer { buffer.deallocate() }
+
+    // Decompress using brotli algorithm
+    let decompressedSize = compression_decode_buffer(
+      buffer,
+      estimatedSize,
+      compressedData.withUnsafeBytes { $0.baseAddress!.assumingMemoryBound(to: UInt8.self) },
+      compressedData.count,
+      nil,
+      COMPRESSION_BROTLI
+    )
+
+    guard decompressedSize > 0 else {
+      throw BrotliCompressionError.decompressionFailed
+    }
+
+    // Convert decompressed data to String
+    let decompressedData = Data(bytes: buffer, count: decompressedSize)
+    guard let jsonString = String(data: decompressedData, encoding: .utf8) else {
+      throw BrotliCompressionError.stringConversionFailed
+    }
+    return jsonString
+  }
+}

package/ios/shared/ComponentTypeID.swift

@@ -0,0 +1,117 @@
+//
+//  ComponentTypeID.swift
+//
+//  AUTO-GENERATED from data/components.json
+//  DO NOT EDIT MANUALLY - Changes will be overwritten
+//  Schema version: 1.0.0
+
+import Foundation
+
+/// Component type IDs mapped from data/components.json
+/// IDs are assigned sequentially based on order in components.json (0-indexed)
+public enum ComponentTypeID: Int, Codable {
+  case TEXT = 0
+  case BUTTON = 1
+  case LABEL = 2
+  case IMAGE = 3
+  case SYMBOL = 4
+  case TOGGLE = 5
+  case LINEAR_PROGRESS_VIEW = 6
+  case CIRCULAR_PROGRESS_VIEW = 7
+  case GAUGE = 8
+  case TIMER = 9
+  case LINEAR_GRADIENT = 10
+  case V_STACK = 11
+  case H_STACK = 12
+  case Z_STACK = 13
+  case GROUP_BOX = 14
+  case GLASS_CONTAINER = 15
+  case SPACER = 16
+  case DIVIDER = 17
+  case MASK = 18
+  case LINK = 19
+  case VIEW = 20
+  case CHART = 21
+
+  /// Get the component name string for this ID
+  public var componentName: String {
+    switch self {
+    case .TEXT:
+      return "Text"
+    case .BUTTON:
+      return "Button"
+    case .LABEL:
+      return "Label"
+    case .IMAGE:
+      return "Image"
+    case .SYMBOL:
+      return "Symbol"
+    case .TOGGLE:
+      return "Toggle"
+    case .LINEAR_PROGRESS_VIEW:
+      return "LinearProgressView"
+    case .CIRCULAR_PROGRESS_VIEW:
+      return "CircularProgressView"
+    case .GAUGE:
+      return "Gauge"
+    case .TIMER:
+      return "Timer"
+    case .LINEAR_GRADIENT:
+      return "LinearGradient"
+    case .V_STACK:
+      return "VStack"
+    case .H_STACK:
+      return "HStack"
+    case .Z_STACK:
+      return "ZStack"
+    case .GROUP_BOX:
+      return "GroupBox"
+    case .GLASS_CONTAINER:
+      return "GlassContainer"
+    case .SPACER:
+      return "Spacer"
+    case .DIVIDER:
+      return "Divider"
+    case .MASK:
+      return "Mask"
+    case .LINK:
+      return "Link"
+    case .VIEW:
+      return "View"
+    case .CHART:
+      return "Chart"
+    }
+  }
+
+  /// Initialize from component name string
+  /// - Parameter name: Component name (e.g., "Text", "VStack")
+  /// - Returns: ComponentTypeID if found, nil otherwise
+  public init?(componentName: String) {
+    switch componentName {
+    case "Text": self = .TEXT
+    case "Button": self = .BUTTON
+    case "Label": self = .LABEL
+    case "Image": self = .IMAGE
+    case "Symbol": self = .SYMBOL
+    case "Toggle": self = .TOGGLE
+    case "LinearProgressView": self = .LINEAR_PROGRESS_VIEW
+    case "CircularProgressView": self = .CIRCULAR_PROGRESS_VIEW
+    case "Gauge": self = .GAUGE
+    case "Timer": self = .TIMER
+    case "LinearGradient": self = .LINEAR_GRADIENT
+    case "VStack": self = .V_STACK
+    case "HStack": self = .H_STACK
+    case "ZStack": self = .Z_STACK
+    case "GroupBox": self = .GROUP_BOX
+    case "GlassContainer": self = .GLASS_CONTAINER
+    case "Spacer": self = .SPACER
+    case "Divider": self = .DIVIDER
+    case "Mask": self = .MASK
+    case "Link": self = .LINK
+    case "View": self = .VIEW
+    case "Chart": self = .CHART
+    default:
+      return nil
+    }
+  }
+}

package/ios/shared/Data+hexString.swift

@@ -0,0 +1,8 @@
+import Foundation
+
+extension Data {
+  /// Converts the data to a hexadecimal string representation.
+  var hexString: String {
+    map { String(format: "%02x", $0) }.joined()
+  }
+}

package/ios/shared/Date+toTimerInterval.swift

@@ -0,0 +1,25 @@
+import SwiftUI
+
+extension Date {
+  static func toTimerInterval(milliseconds: Double) -> ClosedRange<Self> {
+    now ... max(now, Date(timeIntervalSince1970: milliseconds / 1000))
+  }
+
+  static func toTimerInterval(startAtMs: Double?, endAtMs: Double) -> ClosedRange<Self> {
+    let end = Date(timeIntervalSince1970: endAtMs / 1000)
+    let start: Date
+    if let s = startAtMs {
+      start = Date(timeIntervalSince1970: s / 1000)
+    } else {
+      start = .now
+    }
+    // Handle countdown case: if start > end, swap them for countdown behavior
+    if start > end {
+      // For countdown, range should be end...start (swapped)
+      // Clamp to now if end is in the past
+      return end ... max(.now, start)
+    }
+    // If end is in the past, clamp to now to avoid negative intervals
+    return start ... max(.now, end)
+  }
+}

package/ios/shared/JSONValue.swift

@@ -0,0 +1,128 @@
+import Foundation
+
+/// A type-safe representation of JSON values that supports polymorphism
+/// and direct decoding without unnecessary serialization roundtrips
+public enum JSONValue: Codable, Hashable {
+  case null
+  case bool(Bool)
+  case int(Int)
+  case double(Double)
+  case string(String)
+  case array([JSONValue])
+  case object([String: JSONValue])
+
+  /// Parse JSON string into JSONValue
+  public static func parse(from jsonString: String) throws -> JSONValue {
+    guard let data = jsonString.data(using: .utf8) else {
+      throw NSError(domain: "JSONValue", code: -1, userInfo: [NSLocalizedDescriptionKey: "Invalid UTF-8 string"])
+    }
+    return try JSONDecoder().decode(JSONValue.self, from: data)
+  }
+
+  /// Convenience accessors
+  public var stringValue: String? {
+    guard case let .string(value) = self else { return nil }
+    return value
+  }
+
+  public var intValue: Int? {
+    guard case let .int(value) = self else { return nil }
+    return value
+  }
+
+  public var doubleValue: Double? {
+    guard case let .double(value) = self else { return nil }
+    return value
+  }
+
+  public var boolValue: Bool? {
+    guard case let .bool(value) = self else { return nil }
+    return value
+  }
+
+  public var arrayValue: [JSONValue]? {
+    guard case let .array(value) = self else { return nil }
+    return value
+  }
+
+  public var objectValue: [String: JSONValue]? {
+    guard case let .object(value) = self else { return nil }
+    return value
+  }
+
+  /// Access object properties by key
+  public subscript(key: String) -> JSONValue? {
+    guard case let .object(dict) = self else { return nil }
+    return dict[key]
+  }
+
+  /// Convert to Any for legacy compatibility
+  public func toAny() -> Any {
+    switch self {
+    case .null:
+      return NSNull()
+    case let .bool(value):
+      return value
+    case let .int(value):
+      return value
+    case let .double(value):
+      return value
+    case let .string(value):
+      return value
+    case let .array(value):
+      return value.map { $0.toAny() }
+    case let .object(value):
+      return value.mapValues { $0.toAny() }
+    }
+  }
+}
+
+// MARK: - Codable
+
+public extension JSONValue {
+  init(from decoder: Decoder) throws {
+    let container = try decoder.singleValueContainer()
+
+    if container.decodeNil() {
+      self = .null
+    } else if let bool = try? container.decode(Bool.self) {
+      self = .bool(bool)
+    } else if let int = try? container.decode(Int.self) {
+      self = .int(int)
+    } else if let double = try? container.decode(Double.self) {
+      self = .double(double)
+    } else if let string = try? container.decode(String.self) {
+      self = .string(string)
+    } else if let array = try? container.decode([JSONValue].self) {
+      self = .array(array)
+    } else if let object = try? container.decode([String: JSONValue].self) {
+      self = .object(object)
+    } else {
+      throw DecodingError.dataCorruptedError(
+        in: container,
+        debugDescription: "JSONValue cannot decode this value"
+      )
+    }
+  }
+
+  func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+
+    switch self {
+    case .null:
+      try container.encodeNil()
+    case let .bool(value):
+      try container.encode(value)
+    case let .int(value):
+      try container.encode(value)
+    case let .double(value):
+      try container.encode(value)
+    case let .string(value):
+      try container.encode(value)
+    case let .array(value):
+      try container.encode(value)
+    case let .object(value):
+      try container.encode(value)
+    }
+  }
+}

package/ios/shared/ShortNames.swift

@@ -0,0 +1,180 @@
+//
+//  ShortNames.swift
+//
+//  AUTO-GENERATED from data/components.json
+//  DO NOT EDIT MANUALLY - Changes will be overwritten
+//  Schema version: 1.0.0
+
+import Foundation
+
+/// Unified short name mappings for props and style properties
+/// Used to expand compressed payload keys back to their full names
+public enum ShortNames {
+  /// Mapping from short names to full names
+  private static let shortToName: [String: String] = [
+    "ap": "absolutePosition",
+    "ai": "alignItems",
+    "al": "alignment",
+    "as": "alignSelf",
+    "ar": "aspectRatio",
+    "an": "assetName",
+    "bkg": "background",
+    "bg": "backgroundColor",
+    "bgs": "backgroundStyle",
+    "b64": "base64",
+    "bd": "border",
+    "bc": "borderColor",
+    "br": "borderRadius",
+    "bw": "borderWidth",
+    "b": "bottom",
+    "bs": "buttonStyle",
+    "csa": "chartScrollableAxes",
+    "chk": "checked",
+    "clip": "clipped",
+    "c": "color",
+    "cls": "colors",
+    "ca": "contentAlignment",
+    "cc": "contentColor",
+    "cdesc": "contentDescription",
+    "cr": "cornerRadius",
+    "cd": "countDown",
+    "cvl": "currentValueLabel",
+    "dlu": "deepLinkUrl",
+    "dv": "defaultValue",
+    "dest": "destination",
+    "dir": "direction",
+    "dth": "dither",
+    "dur": "durationMs",
+    "en": "enabled",
+    "end": "endAtMs",
+    "ep": "endPoint",
+    "flb": "fallback",
+    "fmh": "fillMaxHeight",
+    "fmw": "fillMaxWidth",
+    "fsh": "fixedSizeHorizontal",
+    "fsv": "fixedSizeVertical",
+    "fl": "flex",
+    "fb": "flexBasis",
+    "fdir": "flexDirection",
+    "fg": "flexGrow",
+    "fgw": "flexGrowWidth",
+    "fk": "flexShrink",
+    "fnt": "font",
+    "ff": "fontFamily",
+    "fs": "fontSize",
+    "fvar": "fontVariant",
+    "fw": "fontWeight",
+    "fgs": "foregroundStyle",
+    "fss": "foregroundStyleScale",
+    "f": "frame",
+    "g": "gap",
+    "gs": "gaugeStyle",
+    "ge": "glassEffect",
+    "h": "height",
+    "halig": "horizontalAlignment",
+    "hp": "horizontalPadding",
+    "ic": "icon",
+    "id": "id",
+    "it": "italic",
+    "jc": "justifyContent",
+    "kern": "kerning",
+    "lbl": "label",
+    "ly": "layout",
+    "lp": "layoutPriority",
+    "l": "left",
+    "lgv": "legendVisibility",
+    "ls": "letterSpacing",
+    "lh": "lineHeight",
+    "ll": "lineLimit",
+    "lsp": "lineSpacing",
+    "lw": "lineWidth",
+    "m": "margin",
+    "mb": "marginBottom",
+    "mh": "marginHorizontal",
+    "ml": "marginLeft",
+    "mr": "marginRight",
+    "mt": "marginTop",
+    "mv": "marginVertical",
+    "mrk": "marks",
+    "me": "maskElement",
+    "maxh": "maxHeight",
+    "max": "maximumValue",
+    "maxl": "maximumValueLabel",
+    "mxl": "maxLines",
+    "maxw": "maxWidth",
+    "minh": "minHeight",
+    "min": "minimumValue",
+    "minvl": "minimumValueLabel",
+    "minl": "minLength",
+    "minw": "minWidth",
+    "md": "monospacedDigit",
+    "mta": "multilineTextAlignment",
+    "n": "name",
+    "nol": "numberOfLines",
+    "off": "offset",
+    "ox": "offsetX",
+    "oy": "offsetY",
+    "op": "opacity",
+    "ov": "overflow",
+    "pad": "padding",
+    "pb": "paddingBottom",
+    "ph": "paddingHorizontal",
+    "pl": "paddingLeft",
+    "pr": "paddingRight",
+    "pt": "paddingTop",
+    "pv": "paddingVertical",
+    "pos": "position",
+    "pc": "progressColor",
+    "rm": "resizeMode",
+    "r": "right",
+    "re": "rotationEffect",
+    "sc": "scale",
+    "sce": "scaleEffect",
+    "sh": "shadow",
+    "shc": "shadowColor",
+    "sho": "shadowOffset",
+    "shop": "shadowOpacity",
+    "shr": "shadowRadius",
+    "shrs": "showHours",
+    "sz": "size",
+    "smc": "smallCaps",
+    "src": "source",
+    "sp": "spacing",
+    "start": "startAtMs",
+    "stp": "startPoint",
+    "sts": "stops",
+    "st": "strikethrough",
+    "s": "style",
+    "si": "systemImage",
+    "txt": "text",
+    "ta": "textAlign",
+    "tdl": "textDecorationLine",
+    "ts": "textStyle",
+    "tt": "textTemplates",
+    "th": "thumb",
+    "tnt": "tint",
+    "tc": "tintColor",
+    "ttl": "title",
+    "t": "top",
+    "trc": "trackColor",
+    "tf": "transform",
+    "typ": "type",
+    "ul": "underline",
+    "v": "value",
+    "valig": "verticalAlignment",
+    "wt": "weight",
+    "w": "width",
+    "xgs": "xAxisGridStyle",
+    "xav": "xAxisVisibility",
+    "ygs": "yAxisGridStyle",
+    "yav": "yAxisVisibility",
+    "zi": "zIndex",
+  ]
+
+  /// Expand a short name to its full form
+  /// - Parameter short: The short name (e.g., "bg", "al", "sp")
+  /// - Returns: The full name (e.g., "backgroundColor", "alignment", "spacing"), or the input if no mapping exists
+  public static func expand(_ short: String) -> String {
+    shortToName[short] ?? short
+  }
+}

package/ios/shared/VoltraAttributes.swift

@@ -0,0 +1,58 @@
+import ActivityKit
+import Compression
+import Foundation
+
+public enum ContentStateParsingError: Error {
+  case invalidJsonString
+  case jsonDeserializationFailed(Error)
+  case invalidRootType
+  case componentsParsingFailed(Error)
+  case regionParsingFailed(VoltraRegion, Error)
+}
+
+public struct VoltraAttributes: ActivityAttributes {
+  public struct ContentState: Codable, Hashable {
+    public let uiJsonData: String
+
+    /// Parsed payload (computed once, cached)
+    public let payload: VoltraLiveActivityPayload
+
+    private enum CodingKeys: String, CodingKey {
+      case uiJsonData
+    }
+
+    /// Initialize with compressed JSON data
+    public init(uiJsonData: String) throws {
+      self.uiJsonData = uiJsonData
+
+      // Decompress and parse once
+      let decompressedJson = try BrotliCompression.decompress(base64String: uiJsonData)
+      payload = try VoltraLiveActivityPayload(jsonString: decompressedJson)
+    }
+
+    // MARK: - Convenience Accessors
+
+    public var regions: [VoltraRegion: [VoltraNode]] {
+      payload.regions
+    }
+
+    public var keylineTint: String? {
+      payload.keylineTint
+    }
+
+    public var activityBackgroundTint: String? {
+      payload.activityBackgroundTint
+    }
+
+    // MARK: - Codable
+
+    public init(from decoder: Decoder) throws {
+      let container = try decoder.container(keyedBy: CodingKeys.self)
+      let compressedJson = try container.decode(String.self, forKey: .uiJsonData)
+      try self.init(uiJsonData: compressedJson)
+    }
+  }
+
+  var name: String
+  var deepLinkUrl: String?
+}

package/ios/shared/VoltraConfig.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+/// Shared configuration utilities for Voltra
+/// Centralizes access to App Group identifiers and other configuration
+public enum VoltraConfig {
+  /// Get the App Group identifier from Info.plist
+  /// Checks both `Voltra_AppGroupIdentifier` and legacy `AppGroupIdentifier` keys
+  public static func groupIdentifier() -> String? {
+    Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.appGroupIdentifier) as? String
+      ?? Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.legacyAppGroupIdentifier) as? String
+  }
+
+  /// Get the Keychain Access Group from Info.plist
+  /// Used for sharing credentials between the main app and widget extension
+  public static func keychainGroup() -> String? {
+    Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.keychainGroup) as? String
+  }
+}

package/ios/shared/VoltraConstants.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+/// Numeric thresholds and configuration values used across Voltra targets
+public enum VoltraConstants {
+  public static let maxPayloadSizeBytes = 4096
+  public static let compressedPayloadSafeBudget = 3345
+  public static let widgetJsonWarningSizeBytes = 50000
+  public static let timelineWarningSizeBytes = 100_000
+}
+
+/// All UserDefaults keys and Info.plist key names used across Voltra targets
+public enum VoltraStorageKeys {
+  // MARK: - UserDefaults keys (shared: app + widget targets)
+
+  public static func widgetJson(_ widgetId: String) -> String {
+    "Voltra_Widget_JSON_\(widgetId)"
+  }
+
+  public static func widgetDeepLinkUrl(_ widgetId: String) -> String {
+    "Voltra_Widget_DeepLinkURL_\(widgetId)"
+  }
+
+  public static func widgetTimeline(_ widgetId: String) -> String {
+    "Voltra_Widget_Timeline_\(widgetId)"
+  }
+
+  public static func widgetServerUrl(_ widgetId: String) -> String {
+    "Voltra_Widget_ServerUrl_\(widgetId)"
+  }
+
+  // MARK: - Prefixes / kind identifiers
+
+  public static let widgetKindPrefix = "Voltra_Widget_"
+
+  // MARK: - Info.plist keys
+
+  public static let widgetIds = "Voltra_WidgetIds"
+  public static let enablePushNotifications = "Voltra_EnablePushNotifications"
+  public static let widgetServerUrls = "Voltra_WidgetServerUrls"
+  public static let widgetServerIntervals = "Voltra_WidgetServerIntervals"
+  public static let widgetServerRefresh = "Voltra_WidgetServerRefresh"
+  public static let appGroupIdentifier = "Voltra_AppGroupIdentifier"
+  public static let legacyAppGroupIdentifier = "AppGroupIdentifier"
+  public static let keychainGroup = "Voltra_KeychainGroup"
+}