@use-voltra/ios-client 2.2.0 → 2.3.0

package/ios/shared/WidgetServer/WidgetServerSettingsValidator.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// Call-time rules for `setWidgetServerUpdate`. Rejecting here rather than at fetch time means the
+/// app learns about a bad setting from the promise it just awaited, instead of from a widget that
+/// quietly stops updating hours later.
+public enum WidgetServerSettingsValidator {
+  /// Hosts reachable over plain http, so a debug build can talk to a dev server.
+  static let localHttpHosts: Set<String> = ["localhost", "127.0.0.1", "::1", "10.0.2.2", "10.0.3.2"]
+
+  /// - Parameter isDebugBuild: whether plain http to a local dev host is allowed. Release builds
+  ///   have App Transport Security blocking it anyway, so allowing it there would only defer the
+  ///   failure.
+  /// - Returns: an error message, or nil when the settings are usable.
+  public static func validate(_ settings: WidgetServerUpdateSettings, isDebugBuild: Bool) -> String? {
+    if let url = settings.url, let error = validateUrl(url, isDebugBuild: isDebugBuild) {
+      return error
+    }
+
+    if let interval = settings.intervalMinutes, interval <= 0 {
+      return "intervalMinutes must be a positive number of minutes"
+    }
+
+    if let method = settings.method,
+       !WidgetServerUpdateDefaults.supportedMethods.contains(method.uppercased())
+    {
+      let supported = WidgetServerUpdateDefaults.supportedMethods.sorted().joined(separator: ", ")
+      return "method '\(method)' is not supported. Use one of \(supported)"
+    }
+
+    for key in settings.query?.keys ?? [String: String]().keys
+      where WidgetServerUpdateDefaults.reservedQueryKeys.contains(key)
+    {
+      return "query key '\(key)' is reserved by Voltra and is sent on every request"
+    }
+
+    if let encoded = WidgetServerSettingsCodec.encode(settings),
+       encoded.count > WidgetServerUpdateDefaults.maxLayerBytes
+    {
+      return "settings are larger than \(WidgetServerUpdateDefaults.maxLayerBytes) bytes once serialized"
+    }
+
+    return nil
+  }
+
+  private static func validateUrl(_ url: String, isDebugBuild: Bool) -> String? {
+    if url.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      return "url must not be empty"
+    }
+
+    guard let components = URLComponents(string: url),
+          let scheme = components.scheme?.lowercased(),
+          let host = components.host,
+          !host.isEmpty
+    else {
+      return "url '\(url)' must be an absolute http(s) URL"
+    }
+
+    if scheme == "https" {
+      return nil
+    }
+
+    if scheme != "http" {
+      return "url '\(url)' must be an absolute http(s) URL"
+    }
+
+    if isDebugBuild, localHttpHosts.contains(host) {
+      return nil
+    }
+
+    let hosts = localHttpHosts.sorted().joined(separator: ", ")
+    return "url '\(url)' must use https. Plain http is allowed only in a debug build, and only for \(hosts)."
+  }
+}

package/ios/shared/WidgetServer/WidgetServerUpdateSettings.swift

@@ -0,0 +1,123 @@
+import Foundation
+
+/// Server-update settings as one layer holds them: every field is optional, and an unset field
+/// means "this layer has no opinion, ask the layer below".
+///
+/// `body` is kept as the raw JSON text the app supplied rather than a parsed tree, because Voltra
+/// never inspects it — it only forwards it as the request body.
+public struct WidgetServerUpdateSettings: Equatable, Sendable {
+  public var url: String?
+  public var intervalMinutes: Int?
+  public var enabled: Bool?
+  public var method: String?
+  public var query: [String: String]?
+  public var headers: [String: String]?
+  public var body: String?
+
+  public init(
+    url: String? = nil,
+    intervalMinutes: Int? = nil,
+    enabled: Bool? = nil,
+    method: String? = nil,
+    query: [String: String]? = nil,
+    headers: [String: String]? = nil,
+    body: String? = nil
+  ) {
+    self.url = url
+    self.intervalMinutes = intervalMinutes
+    self.enabled = enabled
+    self.method = method
+    self.query = query
+    self.headers = headers
+    self.body = body
+  }
+
+  public var isEmpty: Bool {
+    url == nil && intervalMinutes == nil && enabled == nil && method == nil
+      && query == nil && headers == nil && body == nil
+  }
+
+  public static let empty = WidgetServerUpdateSettings()
+}
+
+/// The flattened settings a fetch actually runs on. Every field is decided: `intervalMinutes` has
+/// the floor and ceiling applied, `enabled` and `method` have their defaults filled in, and `query`
+/// and `headers` are the per-key merge of every layer.
+///
+/// `url` is the one field that can still be absent, and it means the widget is server-driven but
+/// has nowhere to fetch from yet — the app is expected to supply one with `setWidgetServerUpdate`.
+public struct ResolvedWidgetServerSettings: Equatable, Sendable {
+  public let url: String?
+  public let intervalMinutes: Int
+  public let enabled: Bool
+  public let method: String
+  public let query: [String: String]
+  public let headers: [String: String]
+  public let body: String?
+
+  public init(
+    url: String?,
+    intervalMinutes: Int,
+    enabled: Bool,
+    method: String,
+    query: [String: String],
+    headers: [String: String],
+    body: String?
+  ) {
+    self.url = url
+    self.intervalMinutes = intervalMinutes
+    self.enabled = enabled
+    self.method = method
+    self.query = query
+    self.headers = headers
+    self.body = body
+  }
+
+  /// True when this widget has both a URL to fetch and permission to do it.
+  public var shouldFetch: Bool {
+    guard enabled, let url, !url.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
+      return false
+    }
+
+    return true
+  }
+}
+
+public enum WidgetServerUpdateDefaults {
+  /// WidgetKit stretches a timeline asking for entries much closer together than five minutes, and
+  /// the reload budget is shared across every widget in the app, so a smaller number would only
+  /// misreport what the widget actually does. Matches Android's WorkManager floor.
+  public static let minIntervalMinutes = 15
+
+  /// A day. Past this the widget is effectively not server-driven, and `Cache-Control: max-age`
+  /// from a misconfigured server should not be able to park a widget for a week.
+  public static let maxIntervalMinutes = 24 * 60
+
+  public static let defaultIntervalMinutes = minIntervalMinutes
+
+  public static let defaultMethod = "GET"
+
+  /// Methods either platform's HTTP stack can send.
+  public static let supportedMethods: Set<String> = ["GET", "POST", "PUT", "PATCH", "DELETE"]
+
+  /// Methods that cannot carry a body. A body set alongside one of these is dropped.
+  public static let bodylessMethods: Set<String> = ["GET", "HEAD"]
+
+  /// Query keys Voltra puts on every request. An app that set one of these would silently shadow
+  /// what the server relies on, so `setWidgetServerUpdate` rejects them.
+  public static let reservedQueryKeys: Set<String> = [
+    "widgetId", "platform", "family", "theme", "locale", "instance", "configuration",
+  ]
+
+  /// Serialized size cap for one layer, so a runaway `body` cannot fill the settings store.
+  public static let maxLayerBytes = 16 * 1024
+
+  /// Response bodies larger than this are refused. The widget extension has a 30 MB ceiling for
+  /// the whole render, and a widget needing a quarter of a megabyte of props will not fit on a
+  /// home screen either.
+  public static let maxBodyBytes = 256 * 1024
+
+  public static func clampIntervalMinutes(_ intervalMinutes: Int) -> Int {
+    min(max(intervalMinutes, minIntervalMinutes), maxIntervalMinutes)
+  }
+}

package/ios/shared/WidgetServer/WidgetServerUpdateSettingsJson.swift

@@ -0,0 +1,115 @@
+import Foundation
+
+/// Reads the settings object an app passes to `setWidgetServerUpdate`.
+///
+/// Separate from `WidgetServerSettingsCodec`, which is the versioned storage format: what the app
+/// sends and what Voltra persists are allowed to diverge, and conflating them would make either one
+/// hard to change. The one real difference today is `body`, which arrives as arbitrary JSON and is
+/// kept as text because Voltra only forwards it.
+public enum WidgetServerUpdateSettingsJson {
+  public enum Result: Equatable {
+    case parsed(WidgetServerUpdateSettings)
+    case invalid(reason: String)
+  }
+
+  public static func parse(_ json: String) -> Result {
+    guard let object = try? JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any] else {
+      return .invalid(reason: "settings must be a JSON object")
+    }
+
+    guard let query = stringMap(object, "query") else {
+      return .invalid(reason: "query must be an object of strings")
+    }
+
+    guard let headers = stringMap(object, "headers") else {
+      return .invalid(reason: "headers must be an object of strings")
+    }
+
+    var body: String?
+
+    if let rawBody = object["body"], !(rawBody is NSNull) {
+      guard let text = jsonText(rawBody) else {
+        return .invalid(reason: "body must be a JSON value")
+      }
+
+      body = text
+    }
+
+    return .parsed(
+      WidgetServerUpdateSettings(
+        url: object["url"] as? String,
+        intervalMinutes: object["intervalMinutes"] as? Int,
+        enabled: object["enabled"] as? Bool,
+        method: (object["method"] as? String)?.uppercased(),
+        query: object["query"] == nil ? nil : query,
+        headers: object["headers"] == nil ? nil : headers,
+        body: body
+      )
+    )
+  }
+
+  /// The other direction of `parse`: serializes settings back to the same JSON shape, for
+  /// `getWidgetServerUpdate` to hand across the bridge. No envelope — that is
+  /// `WidgetServerSettingsCodec`'s job for storage, not this one's for a single read.
+  public static func stringify(_ settings: WidgetServerUpdateSettings) -> String? {
+    var object: [String: Any] = [:]
+
+    if let url = settings.url {
+      object["url"] = url
+    }
+    if let intervalMinutes = settings.intervalMinutes {
+      object["intervalMinutes"] = intervalMinutes
+    }
+    if let enabled = settings.enabled {
+      object["enabled"] = enabled
+    }
+    if let method = settings.method {
+      object["method"] = method
+    }
+    if let query = settings.query {
+      object["query"] = query
+    }
+    if let headers = settings.headers {
+      object["headers"] = headers
+    }
+
+    if let body = settings.body {
+      guard let bodyData = body.data(using: .utf8),
+            let bodyValue = try? JSONSerialization.jsonObject(with: bodyData, options: [.fragmentsAllowed])
+      else {
+        return nil
+      }
+
+      object["body"] = bodyValue
+    }
+
+    guard let data = try? JSONSerialization.data(withJSONObject: object) else { return nil }
+
+    return String(data: data, encoding: .utf8)
+  }
+
+  /// Re-serializes a parsed value back to JSON text. A string body has to keep its quotes: without
+  /// them the request would carry something that is not JSON at all.
+  private static func jsonText(_ value: Any) -> String? {
+    if JSONSerialization.isValidJSONObject(value) {
+      return (try? JSONSerialization.data(withJSONObject: value)).flatMap { String(data: $0, encoding: .utf8) }
+    }
+
+    // A top-level scalar is not a valid JSON *object*, so it is wrapped, encoded and unwrapped.
+    guard let wrapped = try? JSONSerialization.data(withJSONObject: ["v": value]),
+          let text = String(data: wrapped, encoding: .utf8),
+          let start = text.firstIndex(of: ":")
+    else {
+      return nil
+    }
+
+    return String(text[text.index(after: start) ..< text.index(before: text.endIndex)])
+  }
+
+  /// Returns an empty map when the key is absent, and nil when it is present but not usable.
+  private static func stringMap(_ object: [String: Any], _ key: String) -> [String: String]? {
+    guard let raw = object[key], !(raw is NSNull) else { return [:] }
+
+    return raw as? [String: String]
+  }
+}

package/ios/shared/dynamic-live-activity/DynamicLiveActivityPropsCodec.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+enum DynamicLiveActivityPropsCodec {
+  static func encode(_ props: [String: VoltraDynamicLiveActivityJSONValue]) -> String? {
+    guard
+      let data = try? JSONEncoder().encode(props),
+      let json = String(data: data, encoding: .utf8)
+    else {
+      return nil
+    }
+    return json
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityBundleSource.swift

@@ -0,0 +1,156 @@
+import Foundation
+
+enum VoltraDynamicLiveActivityBundleSource {
+  private static let metroTimeout: TimeInterval = 1
+
+  enum LoadError: LocalizedError {
+    case metroHTTP(Int)
+    case metroTimeout
+    case nonUTF8
+    case bakedBundleNotFound(definitionId: String)
+    case cacheUnavailable
+
+    var errorDescription: String? {
+      switch self {
+      case let .metroHTTP(status):
+        return "Metro HTTP \(status) while loading a Dynamic Live Activity bundle"
+      case .metroTimeout:
+        return "Metro timed out while loading a Dynamic Live Activity bundle"
+      case .nonUTF8:
+        return "Dynamic Live Activity bundle was not UTF-8 text"
+      case let .bakedBundleNotFound(definitionId):
+        return "Production Dynamic Live Activity bundle missing for definitionId=\(definitionId)"
+      case .cacheUnavailable:
+        return "Dynamic Live Activity debug cache is unavailable"
+      }
+    }
+  }
+
+  static func load(definitionId: String) throws -> String {
+    #if DEBUG
+      if let cached = try? loadFromDebugCache(definitionId: definitionId) {
+        return cached
+      }
+      return try loadFromMetroBounded(definitionId: definitionId)
+    #else
+      return try loadFromBakedAsset(definitionId: definitionId)
+    #endif
+  }
+
+  /// App-side preflight and Fast Refresh use an asynchronous fetch, then publish
+  /// the source into the App Group cache consumed by the extension process.
+  static func loadForApp(definitionId: String) async throws -> String {
+    #if DEBUG
+      let request = try metroRequest(definitionId: definitionId)
+      let (data, response) = try await URLSession.shared.data(for: request)
+      let source = try validateMetroResponse(data: data, response: response)
+      try saveToDebugCache(source, definitionId: definitionId)
+      return source
+    #else
+      return try loadFromBakedAsset(definitionId: definitionId)
+    #endif
+  }
+
+  /// A cheap token that changes whenever the bytes behind `load` change, used to
+  /// invalidate the render cache. In DEBUG it is the debug-cache file's
+  /// modification time, which the app process rewrites on every hot reload; the
+  /// extension reads only the file's metadata, never decoding the whole bundle.
+  /// In release the baked asset never changes at runtime, so the token is
+  /// constant and the render cache stays valid for the process lifetime.
+  static func revision(definitionId: String) -> String {
+    #if DEBUG
+      guard
+        let url = try? debugCacheURL(definitionId: definitionId),
+        let modified = (try? FileManager.default.attributesOfItem(atPath: url.path))?[.modificationDate] as? Date
+      else {
+        return ""
+      }
+      return String(modified.timeIntervalSince1970)
+    #else
+      return "baked"
+    #endif
+  }
+
+  private static func metroRequest(definitionId: String) throws -> URLRequest {
+    let base = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    guard let url = URL(string: "\(base)/voltra/live-activities/\(definitionId).bundle?platform=ios&dev=true") else {
+      throw LoadError.metroHTTP(-1)
+    }
+    var request = URLRequest(url: url)
+    request.timeoutInterval = metroTimeout
+    return request
+  }
+
+  /// WidgetKit rendering is synchronous. On a cold debug process we permit one
+  /// short, bounded bootstrap request; all subsequent renders read the App Group
+  /// cache and never wait on the network.
+  private static func loadFromMetroBounded(definitionId: String) throws -> String {
+    let request = try metroRequest(definitionId: definitionId)
+    let semaphore = DispatchSemaphore(value: 0)
+    var result: Result<(Data, URLResponse), Error>?
+    let configuration = URLSessionConfiguration.ephemeral
+    configuration.timeoutIntervalForRequest = metroTimeout
+    configuration.timeoutIntervalForResource = metroTimeout
+    let session = URLSession(configuration: configuration)
+    let task = session.dataTask(with: request) { data, response, error in
+      if let error {
+        result = .failure(error)
+      } else if let data, let response {
+        result = .success((data, response))
+      } else {
+        result = .failure(LoadError.metroHTTP(-1))
+      }
+      semaphore.signal()
+    }
+    task.resume()
+    guard semaphore.wait(timeout: .now() + metroTimeout) == .success else {
+      task.cancel()
+      session.invalidateAndCancel()
+      throw LoadError.metroTimeout
+    }
+    session.finishTasksAndInvalidate()
+    guard let result else { throw LoadError.metroTimeout }
+    let (data, response) = try result.get()
+    let source = try validateMetroResponse(data: data, response: response)
+    try saveToDebugCache(source, definitionId: definitionId)
+    return source
+  }
+
+  private static func validateMetroResponse(data: Data, response: URLResponse) throws -> String {
+    if let httpResponse = response as? HTTPURLResponse, !(200 ... 299).contains(httpResponse.statusCode) {
+      throw LoadError.metroHTTP(httpResponse.statusCode)
+    }
+    guard let source = String(data: data, encoding: .utf8) else {
+      throw LoadError.nonUTF8
+    }
+    return source
+  }
+
+  private static func loadFromDebugCache(definitionId: String) throws -> String {
+    try String(contentsOf: debugCacheURL(definitionId: definitionId), encoding: .utf8)
+  }
+
+  private static func saveToDebugCache(_ source: String, definitionId: String) throws {
+    try Data(source.utf8).write(to: debugCacheURL(definitionId: definitionId), options: .atomic)
+  }
+
+  private static func debugCacheURL(definitionId: String) throws -> URL {
+    guard
+      let group = VoltraConfig.groupIdentifier(),
+      let container = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: group)
+    else {
+      throw LoadError.cacheUnavailable
+    }
+    return container.appendingPathComponent("voltra-live-activity-debug-\(definitionId).bundle")
+  }
+
+  private static func loadFromBakedAsset(definitionId: String) throws -> String {
+    guard
+      let url = Bundle.main.url(forResource: "voltra-live-activity-\(definitionId)", withExtension: "bundle"),
+      let source = try? String(contentsOf: url, encoding: .utf8)
+    else {
+      throw LoadError.bakedBundleNotFound(definitionId: definitionId)
+    }
+    return source
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityObserver.swift

@@ -0,0 +1,97 @@
+import ActivityKit
+import Foundation
+
+/// Observes every concrete generated Dynamic Live Activity type. ActivityKit's
+/// activity streams are type-specific, so the generated catalog invokes this
+/// observer once for each bundled attributes type.
+public actor VoltraDynamicLiveActivityObserver {
+  private let onActivityDiscovered: (@Sendable (String) -> Void)?
+  private let onTokenUpdated: (@Sendable (String, String) -> Void)?
+  private let onStateChanged: (@Sendable (String, String) -> Void)?
+
+  private var definitionTasks: [String: Task<Void, Never>] = [:]
+  private var tokenTasks: [String: Task<Void, Never>] = [:]
+  private var stateTasks: [String: Task<Void, Never>] = [:]
+
+  public init(
+    onActivityDiscovered: (@Sendable (String) -> Void)? = nil,
+    onTokenUpdated: (@Sendable (String, String) -> Void)? = nil,
+    onStateChanged: (@Sendable (String, String) -> Void)? = nil
+  ) {
+    self.onActivityDiscovered = onActivityDiscovered
+    self.onTokenUpdated = onTokenUpdated
+    self.onStateChanged = onStateChanged
+  }
+
+  public func observe<Attributes: VoltraDynamicLiveActivityDefinition>(_: Attributes.Type) {
+    let definitionId = Attributes.definitionId
+    guard definitionTasks[definitionId] == nil else { return }
+
+    definitionTasks[definitionId] = Task { [weak self] in
+      for activity in Activity<Attributes>.activities {
+        await self?.observe(activity, definitionId: definitionId)
+      }
+      for await activity in Activity<Attributes>.activityUpdates {
+        await self?.observe(activity, definitionId: definitionId)
+      }
+      await self?.removeDefinitionTask(for: definitionId)
+    }
+  }
+
+  public func stopObserving() {
+    for task in definitionTasks.values {
+      task.cancel()
+    }
+    for task in tokenTasks.values {
+      task.cancel()
+    }
+    for task in stateTasks.values {
+      task.cancel()
+    }
+    definitionTasks.removeAll()
+    tokenTasks.removeAll()
+    stateTasks.removeAll()
+  }
+
+  private func observe<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _ activity: Activity<Attributes>,
+    definitionId: String
+  ) {
+    let key = "\(definitionId):\(activity.id)"
+    let name = activity.attributes.name
+    onActivityDiscovered?(activity.id)
+
+    if let onTokenUpdated, tokenTasks[key] == nil {
+      tokenTasks[key] = Task { [weak self] in
+        for await token in activity.pushTokenUpdates {
+          onTokenUpdated(name, token.hexString)
+        }
+        await self?.removeTokenTask(for: key)
+      }
+    }
+
+    if let onStateChanged, stateTasks[key] == nil {
+      stateTasks[key] = Task { [weak self] in
+        for await state in activity.activityStateUpdates {
+          onStateChanged(name, String(describing: state))
+        }
+        await self?.removeStateTask(for: key)
+      }
+    }
+  }
+
+  private func removeDefinitionTask(for definitionId: String) {
+    definitionTasks[definitionId]?.cancel()
+    definitionTasks.removeValue(forKey: definitionId)
+  }
+
+  private func removeTokenTask(for key: String) {
+    tokenTasks[key]?.cancel()
+    tokenTasks.removeValue(forKey: key)
+  }
+
+  private func removeStateTask(for key: String) {
+    stateTasks[key]?.cancel()
+    stateTasks.removeValue(forKey: key)
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityOperations.swift

@@ -0,0 +1,105 @@
+import ActivityKit
+import Foundation
+
+public struct VoltraDynamicLiveActivityCreateRequest {
+  public let definitionId: String
+  public let name: String
+  public let deepLinkUrl: String?
+  public let props: [String: VoltraDynamicLiveActivityJSONValue]
+  public let staleDate: Date?
+  public let relevanceScore: Double
+  public let pushType: PushType?
+}
+
+public struct VoltraDynamicLiveActivityUpdateRequest {
+  public let props: [String: VoltraDynamicLiveActivityJSONValue]
+  public let staleDate: Date?
+  public let relevanceScore: Double
+}
+
+public struct VoltraDynamicLiveActivityReference: Hashable {
+  public let id: String
+  public let name: String
+  public let definitionId: String
+}
+
+/// Generic ActivityKit operations called by the generated catalog. The catalog
+/// supplies the concrete generated Attributes type without exposing it to the
+/// legacy service or the React Native bridge.
+public enum VoltraDynamicLiveActivityOperations {
+  public static func create<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    request: VoltraDynamicLiveActivityCreateRequest
+  ) async throws -> VoltraDynamicLiveActivityReference {
+    let attributes = Attributes(name: request.name, deepLinkUrl: request.deepLinkUrl)
+    let state = VoltraDynamicLiveActivityContentState(props: request.props)
+    let activity = try Activity.request(
+      attributes: attributes,
+      content: ActivityContent(state: state, staleDate: request.staleDate, relevanceScore: request.relevanceScore),
+      pushType: request.pushType
+    )
+    return VoltraDynamicLiveActivityReference(
+      id: activity.id,
+      name: activity.attributes.name,
+      definitionId: Attributes.definitionId
+    )
+  }
+
+  public static func update<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    byName name: String,
+    request: VoltraDynamicLiveActivityUpdateRequest
+  ) async -> Bool {
+    let activities = Activity<Attributes>.activities.filter { $0.attributes.name == name }
+    for activity in activities {
+      // State is deliberately replaced in full; V1 does not merge props.
+      await activity.update(ActivityContent(
+        state: VoltraDynamicLiveActivityContentState(props: request.props),
+        staleDate: request.staleDate,
+        relevanceScore: request.relevanceScore
+      ))
+    }
+    return !activities.isEmpty
+  }
+
+  public static func end<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    byName name: String,
+    dismissalPolicy: ActivityUIDismissalPolicy
+  ) async -> Bool {
+    let activities = Activity<Attributes>.activities.filter { $0.attributes.name == name }
+    for activity in activities {
+      await activity.end(ActivityContent(state: activity.content.state, staleDate: nil), dismissalPolicy: dismissalPolicy)
+    }
+    return !activities.isEmpty
+  }
+
+  public static func endAll<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    dismissalPolicy: ActivityUIDismissalPolicy
+  ) async {
+    for activity in Activity<Attributes>.activities {
+      await activity.end(ActivityContent(state: activity.content.state, staleDate: nil), dismissalPolicy: dismissalPolicy)
+    }
+  }
+
+  public static func activities<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type
+  ) -> [VoltraDynamicLiveActivityReference] {
+    Activity<Attributes>.activities.map {
+      VoltraDynamicLiveActivityReference(id: $0.id, name: $0.attributes.name, definitionId: Attributes.definitionId)
+    }
+  }
+
+  public static func reload<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type
+  ) async {
+    for activity in Activity<Attributes>.activities {
+      await activity.update(ActivityContent(
+        state: activity.content.state,
+        staleDate: activity.content.staleDate,
+        relevanceScore: activity.content.relevanceScore
+      ))
+    }
+  }
+}