@bubblsdk/react-native-sdk 4.1.7 → 5.0.0-alpha.2

package/ios-sdk/BubblCore/API/DeviceApiClient.swift

@@ -0,0 +1,239 @@
+import Foundation
+
+/// Why a request wasn't made, other than having no network. Both mean "later": nothing was
+/// refused, and the install keeps its identity.
+package enum DeviceApiError: Error {
+    /// The credential can't be read yet (the device hasn't been unlocked since it started).
+    /// Registering now would replace a working credential, so the request waits instead.
+    case credentialsLocked
+    /// POST /installs succeeded but its credential couldn't be kept, so it doesn't count.
+    case credentialNotSaved(any Error)
+}
+
+/// The engine's client for the device API v1 (contracts/v1/device-api-v1.yaml): registers the
+/// install, signs every other request with its credential, and deals with the errors that have
+/// one right answer, so callers only see the rest:
+///
+///  - no credential yet: POST /installs first;
+///  - timestamp_out_of_range: take the server's clock, retry once;
+///  - invalid_key / invalid_signature / credential_revoked: register again, once, then retry
+///    once (a second failure is returned as it is, so this can never loop).
+///
+/// Every response's Date header keeps the clock in step. Registering is serialised: requests
+/// that find the credential missing or refused wait for one registration rather than each
+/// doing one (found on a device: sync, config and geofences all start at once on first launch).
+package final class DeviceApiClient: Sendable {
+    private let baseUrl: String
+    /// Nil for a device started with a credential issued outside the app: it never registers.
+    private let apiKey: String?
+    private let onCredentialRejected: @Sendable () -> Void
+    private let userAgent: String
+    private let http: any HttpClient
+    private let credentials: any CredentialStore
+    private let clock: ServerClock
+    private let installBody: @Sendable () throws -> [String: Any]
+    private let onRegistered: @Sendable ([String: Any]) -> Void
+    private let registration = AsyncMutex()
+
+    /// - Parameters:
+    ///   - installBody: what POST /installs sends (api_key is added here): the install id the SDK
+    ///     keeps for this installation, and what the device says about itself. It throws when the
+    ///     install id can't be read yet (before the first unlock): nothing is sent then.
+    ///   - onRegistered: told the install response's `data` (device and config) after each
+    ///     successful registration.
+    package init(
+        baseUrl: String,
+        apiKey: String?,
+        sdkVersion: String,
+        http: any HttpClient,
+        credentials: any CredentialStore,
+        clock: ServerClock,
+        installBody: @escaping @Sendable () throws -> [String: Any],
+        onRegistered: @escaping @Sendable ([String: Any]) -> Void = { _ in },
+        onCredentialRejected: @escaping @Sendable () -> Void = {}
+    ) {
+        var trimmed = baseUrl
+        while trimmed.hasSuffix("/") { trimmed.removeLast() }
+        self.baseUrl = trimmed
+        self.apiKey = apiKey
+        userAgent = "Bubbl-iOS-SDK/\(sdkVersion)"
+        self.http = http
+        self.credentials = credentials
+        self.clock = clock
+        self.installBody = installBody
+        self.onRegistered = onRegistered
+        self.onCredentialRejected = onCredentialRejected
+    }
+
+    /// POST /installs: registers (or registers again) and keeps the credential it returns.
+    /// Unsigned; the public API key identifies the company. The response tells the caller why
+    /// when it failed (e.g. own_app_not_in_plan, or a wrong API key).
+    package func register() async throws -> ApiResponse {
+        try await registration.withLock { try await self.registerLocked() }
+    }
+
+    /// A signed request to `path` (from the API root, no leading slash: "api/v1/geofences").
+    /// `query` values are sent as given; `body` is sent and signed byte for byte; `headers` are
+    /// added as they are (e.g. Idempotency-Key, If-None-Match).
+    ///
+    /// Throws when the request couldn't be made at all: no response (offline), or a
+    /// `DeviceApiError` (the credential can't be read yet, or couldn't be kept). Either way it's
+    /// worth trying again later; nothing was refused.
+    package func request(
+        _ method: String,
+        _ path: String,
+        query: [String: String] = [:],
+        body: String? = nil,
+        headers: [String: String] = [:]
+    ) async throws -> ApiResponse {
+        if try credentialKeyId() == nil {
+            // The first to get here registers; the rest wait, find the credential, and use it.
+            let registered = try await registration.withLock { () async throws -> ApiResponse? in
+                try self.credentialKeyId() != nil ? nil : try await self.registerLocked()
+            }
+            if let registered, !registered.isSuccessful { return registered }
+        }
+
+        var sent = try await send(method, path, query: query, body: body, headers: headers)
+
+        if sent.response.handling?.action == .correctClockAndRetry {
+            if let serverTime = JSON.int64(sent.response.json?["server_time"]), serverTime > 0 {
+                clock.sync(serverSeconds: serverTime)
+            }
+            sent = try await send(method, path, query: query, body: body, headers: headers)
+        }
+
+        if sent.response.handling?.action == .reRegister {
+            let refusedKeyId = sent.keyId
+            let registered = try await registration.withLock { () async throws -> ApiResponse? in
+                // Another request may have registered again since this one was signed (it was
+                // refused for the same reason): use that credential rather than replace it.
+                try self.credentialKeyId() != refusedKeyId ? nil : try await self.registerLocked()
+            }
+            if let registered, !registered.isSuccessful { return registered }
+            sent = try await send(method, path, query: query, body: body, headers: headers)
+        }
+
+        return sent.response
+    }
+
+    /// The credential's key id, nil when there's none; throws when it can't be read yet (never
+    /// "none" for a locked Keychain, or a working credential would be replaced).
+    private func credentialKeyId() throws -> String? {
+        switch credentials.read() {
+        case .present(let credential): credential.keyId
+        case .missing: nil
+        case .unavailable: throw DeviceApiError.credentialsLocked
+        }
+    }
+
+    /// A response, and the key id the request was signed with (nil if it couldn't be signed).
+    private struct Sent: Sendable {
+        let response: ApiResponse
+        let keyId: String?
+    }
+
+    /// What a device started with a credential gets where an install would register.
+    static let credentialRejected = #"{"message":"The device's credential was refused: start Bubbl with a new one.","code":"credential_rejected"}"#
+
+    private func registerLocked() async throws -> ApiResponse {
+        // Started with a credential issued outside the app: nothing here can renew it (there's no
+        // API key), so where an install would register, the app is told and has to start Bubbl
+        // with a new one.
+        guard let apiKey else {
+            onCredentialRejected()
+            return ApiResponse(HttpResponse(status: 401, body: Self.credentialRejected)).handled(as: ErrorHandling(.stopAndReport))
+        }
+        var install: [String: Any]
+        do {
+            install = try installBody()
+        } catch {
+            throw DeviceApiError.credentialsLocked
+        }
+        install["api_key"] = apiKey
+        let body = JSON.string(install)
+        let response = try await execute(HttpRequest(method: "POST", url: url("api/v1/installs"), headers: jsonHeaders(body: body), body: body))
+
+        if response.isSuccessful,
+           let data = response.json?["data"] as? [String: Any],
+           let credential = data["credential"] as? [String: Any],
+           let keyId = credential["key_id"] as? String, !keyId.isEmpty,
+           let secret = credential["secret"] as? String, !secret.isEmpty {
+            // Not kept, not registered: the next request registers again rather than carry on
+            // with a credential this install no longer has.
+            do {
+                try credentials.save(keyId: keyId, secret: secret)
+            } catch {
+                throw DeviceApiError.credentialNotSaved(error)
+            }
+            onRegistered(data)
+        }
+
+        // invalid_key here means the public API key itself is wrong: registering again can't fix
+        // that, so it's reported rather than retried.
+        if response.handling?.action == .reRegister {
+            return response.handled(as: ErrorHandling(.stopAndReport))
+        }
+        return response
+    }
+
+    private func send(_ method: String, _ path: String, query: [String: String], body: String?, headers: [String: String]) async throws -> Sent {
+        let credential: SigningCredential
+        switch credentials.read() {
+        case .present(let current):
+            credential = current
+        case .missing:
+            // The credential vanished (cleared mid-request): the server's answer would be
+            // missing_signature, so say that without a round trip.
+            return Sent(response: ApiResponse(HttpResponse(status: 401, body: #"{"message":"Not registered.","code":"missing_signature"}"#)), keyId: nil)
+        case .unavailable:
+            throw DeviceApiError.credentialsLocked
+        }
+
+        let fullUrl = url(path, query: query)
+        let timestamp = clock.nowSeconds()
+        // The server signs the request path it sees, which includes any prefix in the base URL.
+        let signedPath = String((URLComponents(string: fullUrl)?.percentEncodedPath ?? "").drop { $0 == "/" })
+        let signature = RequestSigner.sign(secret: credential.secret, method: method, path: signedPath, timestamp: Int(timestamp), body: body ?? "", query: query)
+
+        var allHeaders = jsonHeaders(body: body)
+        allHeaders.merge(headers) { _, new in new }
+        allHeaders["X-Bubbl-Key-Id"] = credential.keyId
+        allHeaders["X-Bubbl-Timestamp"] = String(timestamp)
+        allHeaders["X-Bubbl-Signature"] = signature
+
+        let response = try await execute(HttpRequest(method: method, url: fullUrl, headers: allHeaders, body: body))
+        return Sent(response: response, keyId: credential.keyId)
+    }
+
+    private func execute(_ request: HttpRequest) async throws -> ApiResponse {
+        let response = try await http.execute(request)
+        clock.sync(dateHeader: response.header("Date"))
+        let result = ApiResponse(response)
+        if let said = Self.wrongEnvironment(result) { BubblLog.error(said) }
+        return result
+    }
+
+    /// What the log says for wrong_environment (a pk_test_ key at the Production address, or the
+    /// other way round): the server's message, and the address the key belongs to (`base_url`).
+    package static func wrongEnvironment(_ response: ApiResponse) -> String? {
+        guard response.code == "wrong_environment" else { return nil }
+        let json = response.json
+        let message = (json?["message"] as? String).flatMap { $0.isEmpty ? nil : $0 } ?? "The API key and the address are for different workspaces."
+        let address = (json?["base_url"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+        return "Bubbl: the API key and baseUrl don't match (wrong_environment). \(message)" + (address.map { " Use baseUrl \($0) with this key." } ?? "")
+    }
+
+    /// The URL for `path`, with `query` in canonical order (the same encoding that's signed).
+    private func url(_ path: String, query: [String: String] = [:]) -> String {
+        let canonical = RequestSigner.canonicalQuery(query)
+        let relative = path.hasPrefix("/") ? String(path.dropFirst()) : path
+        return "\(baseUrl)/\(relative)" + (canonical.isEmpty ? "" : "?\(canonical)")
+    }
+
+    private func jsonHeaders(body: String?) -> [String: String] {
+        var headers = ["Accept": "application/json", "User-Agent": userAgent]
+        if body != nil { headers["Content-Type"] = "application/json" }
+        return headers
+    }
+}

package/ios-sdk/BubblCore/API/ErrorActions.swift

@@ -0,0 +1,68 @@
+/// What the engine does about a failed request. The device API contract's errors fixture
+/// (contracts/v1/fixtures/v1/errors.json) is the source of truth for which code gets which
+/// action, and ErrorActionsContractTests checks this against it. Raw values are the fixture's.
+package enum ErrorAction: String, Sendable, CaseIterable {
+    /// POST /installs again, once and one at a time, then retry.
+    case reRegister = "re_register"
+    /// Take the clock offset from server_time (or the Date header) and retry once.
+    case correctClockAndRetry = "correct_clock_and_retry"
+    /// Stop calling the API for a while (ErrorHandling.pauseHours); keep queuing.
+    case pause
+    /// PUT /device, then retry.
+    case describeDevice = "describe_device"
+    /// Drop the item and fetch geofences again: the location is gone.
+    case dropAndRefreshGeofences = "drop_and_refresh_geofences"
+    /// Discard the request or item (it can never succeed as sent) and log it.
+    case drop
+    /// Wait for Retry-After, then retry.
+    case waitAndRetry = "wait_and_retry"
+    /// Stop and surface it in diagnostics: something is misconfigured.
+    case stopAndReport = "stop_and_report"
+    /// The pairing UI shows the server's message.
+    case showMessage = "show_message"
+    /// 5xx or network failure: exponential backoff with jitter.
+    case backoff
+}
+
+/// An ErrorAction, with how long to pause for `.pause`.
+package struct ErrorHandling: Sendable, Equatable {
+    package let action: ErrorAction
+    package let pauseHours: Int?
+
+    package init(_ action: ErrorAction, pauseHours: Int? = nil) {
+        self.action = action
+        self.pauseHours = pauseHours
+    }
+}
+
+package enum ErrorActions {
+    /// The handling for a response's status and error `code` (nil when the body had none). An
+    /// unknown code falls back on its status, so a newer server can't wedge an older SDK.
+    package static func forResponse(status: Int, code: String?) -> ErrorHandling {
+        switch code {
+        case "missing_signature": ErrorHandling(.stopAndReport)
+        case "timestamp_out_of_range": ErrorHandling(.correctClockAndRetry)
+        case "invalid_key", "invalid_signature", "credential_revoked": ErrorHandling(.reRegister)
+        case "workspace_paused": ErrorHandling(.pause, pauseHours: 6)
+        case "own_app_not_in_plan": ErrorHandling(.pause, pauseHours: 24)
+        // Sandbox: no room for another device awaiting approval; back off as for a paused workspace.
+        case "sandbox_pending_full": ErrorHandling(.pause, pauseHours: 6)
+        // A Sandbox key at the Production address or the other way round: only the app can fix it.
+        case "wrong_environment": ErrorHandling(.stopAndReport)
+        case "showcase_only", "unknown_notification": ErrorHandling(.drop)
+        case "device_not_registered": ErrorHandling(.describeDevice)
+        case "request_in_progress", "too_many_failed_attempts": ErrorHandling(.waitAndRetry)
+        case "unknown_location": ErrorHandling(.dropAndRefreshGeofences)
+        // The message goes back to whoever asked (pairing; Bubbl.registerTestDevice).
+        case "invalid_pairing_code", "invalid_test_device_code", "test_devices_full": ErrorHandling(.showMessage)
+        case "rate_limited": ErrorHandling(.waitAndRetry)
+        default:
+            switch status {
+            case 422: ErrorHandling(.drop)
+            case 429: ErrorHandling(.waitAndRetry)
+            case 500...: ErrorHandling(.backoff)
+            default: ErrorHandling(.stopAndReport)
+            }
+        }
+    }
+}

package/ios-sdk/BubblCore/API/Http.swift

@@ -0,0 +1,39 @@
+/// One HTTP request as the engine sends it: the full URL, and the body's exact text.
+package struct HttpRequest: Sendable, Equatable {
+    package var method: String
+    package var url: String
+    package var headers: [String: String]
+    package var body: String?
+
+    package init(method: String, url: String, headers: [String: String] = [:], body: String? = nil) {
+        self.method = method
+        self.url = url
+        self.headers = headers
+        self.body = body
+    }
+}
+
+/// The response: status, body text and headers (names as the server sent them).
+package struct HttpResponse: Sendable, Equatable {
+    package var status: Int
+    package var body: String
+    package var headers: [String: [String]]
+
+    package init(status: Int, body: String, headers: [String: [String]] = [:]) {
+        self.status = status
+        self.body = body
+        self.headers = headers
+    }
+
+    /// A header's first value, matched without regard to case (HTTP header names aren't).
+    package func header(_ name: String) -> String? {
+        headers.first { $0.key.caseInsensitiveCompare(name) == .orderedSame }?.value.first
+    }
+}
+
+/// Sends one request. The engine's only way out to the network, so tests swap it for a fake
+/// and no HTTP library is forced on the app. Throws when there's no response at all (offline,
+/// timed out); any HTTP status is a response.
+package protocol HttpClient: Sendable {
+    func execute(_ request: HttpRequest) async throws -> HttpResponse
+}

package/ios-sdk/BubblCore/API/ServerClock.swift

@@ -0,0 +1,69 @@
+import Foundation
+
+/// The server's idea of "now", for request timestamps: a signed request is refused when its
+/// timestamp is more than 300 s from the server's clock, and phone clocks drift or are set by
+/// hand. The offset comes from each response's Date header, and from the server_time a
+/// timestamp_out_of_range error carries.
+package final class ServerClock: @unchecked Sendable {
+    /// Offset changes smaller than this are ignored: the Date header has one-second resolution
+    /// and a response takes time to arrive.
+    private static let toleranceSeconds: Int64 = 5
+
+    private let lock = NSLock()
+    private var offset: Int64
+    private let deviceNowSeconds: @Sendable () -> Int64
+    private let onChange: @Sendable (Int64) -> Void
+
+    /// - Parameter onChange: told each new offset, so it can be kept across launches.
+    package init(
+        initialOffsetSeconds: Int64 = 0,
+        deviceNowSeconds: @escaping @Sendable () -> Int64 = { Int64(Date().timeIntervalSince1970) },
+        onChange: @escaping @Sendable (Int64) -> Void = { _ in }
+    ) {
+        offset = initialOffsetSeconds
+        self.deviceNowSeconds = deviceNowSeconds
+        self.onChange = onChange
+    }
+
+    package var offsetSeconds: Int64 {
+        lock.sync { offset }
+    }
+
+    /// Unix seconds as the server would read them now.
+    package func nowSeconds() -> Int64 {
+        deviceNowSeconds() + offsetSeconds
+    }
+
+    /// Adopt the server's time.
+    package func sync(serverSeconds: Int64) {
+        let candidate = serverSeconds - deviceNowSeconds()
+        let changed: Bool = lock.sync {
+            guard abs(candidate - offset) >= Self.toleranceSeconds else { return false }
+            offset = candidate
+            return true
+        }
+        if changed { onChange(candidate) }
+    }
+
+    /// sync(serverSeconds:) from an HTTP Date header (RFC 1123); an absent or unreadable one
+    /// changes nothing.
+    package func sync(dateHeader: String?) {
+        guard let dateHeader, let date = Self.httpDate(dateHeader) else { return }
+        sync(serverSeconds: Int64(date.timeIntervalSince1970))
+    }
+
+    /// Parses "Sun, 06 Nov 1994 08:49:37 GMT". One formatter for every response, used one at a
+    /// time (DateFormatter isn't safe to share across threads everywhere the core runs).
+    package static func httpDate(_ value: String) -> Date? {
+        httpDateLock.sync { httpDateFormatter.date(from: value.trimmingCharacters(in: .whitespaces)) }
+    }
+
+    private static let httpDateLock = NSLock()
+    private static let httpDateFormatter: DateFormatter = {
+        let formatter = DateFormatter()
+        formatter.locale = Locale(identifier: "en_US_POSIX")
+        formatter.timeZone = TimeZone(identifier: "GMT")
+        formatter.dateFormat = "EEE, dd MMM yyyy HH:mm:ss zzz"
+        return formatter
+    }()
+}

package/ios-sdk/BubblCore/BubblVersion.swift

@@ -0,0 +1,5 @@
+/// The SDK's version, sent as X-Bubbl-SDK-Version. Stamped from version.txt by
+/// scripts/sync-version.mjs; don't edit it by hand.
+package enum BubblVersion {
+    package static let sdk = "5.0.0-alpha.2"
+}

package/ios-sdk/BubblCore/Device/ConfigSync.swift

@@ -0,0 +1,216 @@
+import Foundation
+
+/// GET /config's data (every field is always present, per the contract), read leniently.
+package struct SdkConfig: Sendable, Hashable {
+    package static let defaultRefreshSeconds: Int64 = 3_600
+
+    package let json: JSONValue
+
+    package init(_ json: JSONValue) {
+        self.json = json
+    }
+
+    package var enabled: Bool {
+        if case .bool(let value)? = json["enabled"] { value } else { true }
+    }
+
+    /// Whether the server has this device's push token (device.push_token_registered). False while
+    /// the app holds one means the server dropped it (Apple or FCM called it dead, or it was sent
+    /// for the wrong APNs environment); nil before the device has described itself.
+    package var pushTokenRegistered: Bool? {
+        if case .bool(let value)? = json["device"]?["push_token_registered"] { value } else { nil }
+    }
+
+    package var minimumVersion: String? { json["sdk"]?["minimum_version"]?.nonEmptyString }
+
+    package var logLevel: String { json["sdk"]?["log_level"]?.nonEmptyString ?? "warning" }
+
+    /// From one minute to a week, whatever the server says.
+    package var configRefreshSeconds: Int64 {
+        json["sync"]?["config_refresh_seconds"]?.int64(in: 60...604_800) ?? Self.defaultRefreshSeconds
+    }
+
+    /// From 1 to the queue's 100.
+    package var maxEventsPerRequest: Int {
+        json["sync"]?["max_events_per_request"]?.int64(in: 1...Int64(EventQueue.batchSize)).map { Int($0) } ?? EventQueue.batchSize
+    }
+
+    /// The dashboard's privacy view: when to explain before asking for a permission.
+    package var privacyNotice: String {
+        let notice = json["privacy"]?["notice"]?.stringValue ?? ""
+        return ["automatic", "always", "never"].contains(notice) ? notice : "automatic"
+    }
+
+    /// The dashboard's own words for the privacy view, if it has set any.
+    package var privacyText: String? {
+        json["privacy"]?["text"]?.nonEmptyString.flatMap { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? nil : $0 }
+    }
+
+    /// The workspace's privacy policy, linked from the privacy view.
+    package var privacyUrl: String? {
+        json["privacy"]?["callback_url"]?.nonEmptyString.flatMap { $0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? nil : $0 }
+    }
+
+    /// Whether `sdkVersion` is at least the minimum the workspace allows (none: any).
+    package func supports(_ sdkVersion: String) -> Bool {
+        guard let minimumVersion else { return true }
+        return Versions.compare(sdkVersion, minimumVersion) >= 0
+    }
+}
+
+package enum ConfigResult: Sendable, Equatable {
+    case updated
+    case unchanged
+    case notDue
+    case failed(ApiFailure)
+}
+
+/// The runtime configuration: what POST /installs returned, then GET /config every
+/// config_refresh_seconds (conditional, If-None-Match). Kept on disk, so the engine starts with the
+/// last known configuration when offline.
+package final class ConfigSync: Sendable {
+    package struct Saved: Codable, Sendable, Equatable {
+        package var config: JSONValue
+        package var etag: String?
+        package var fetchedAtSeconds: Int64
+    }
+
+    private let api: DeviceApiClient
+    private let clock: ServerClock
+    private let store: any ValueStore<Saved>
+    private let lock = AsyncMutex()
+    /// The saved config, once read (it's asked for often: enabled, the log level, the batch size).
+    private let cache = Cached<Saved>()
+
+    package init(api: DeviceApiClient, clock: ServerClock, store: any ValueStore<Saved>) {
+        self.api = api
+        self.clock = clock
+        self.store = store
+    }
+
+    /// The last known configuration; nil before the first, or while it can't be read.
+    package var current: SdkConfig? {
+        (try? load())?.map { SdkConfig($0.config) }
+    }
+
+    /// The config that came with a registration.
+    package func registered(_ config: JSONValue) throws {
+        try save(Saved(config: config, etag: nil, fetchedAtSeconds: clock.nowSeconds()))
+    }
+
+    /// The workspace block from POST /test-device, put into the saved config (where GET /config
+    /// would bring it), so the device reads as approved without another request.
+    package func setWorkspace(_ workspace: JSONValue) async throws {
+        try await lock.withLock {
+            guard var saved = try self.load(), case .object(var fields) = saved.config else { return }
+            fields["workspace"] = workspace
+            saved.config = .object(fields)
+            try self.save(saved)
+        }
+    }
+
+    /// Forget it (deleteMyData): the next registration brings the config afresh.
+    package func forget() throws {
+        try store.delete()
+        cache.set(nil)
+    }
+
+    private func load() throws -> Saved? {
+        try cache.value { try store.load() }
+    }
+
+    private func save(_ saved: Saved) throws {
+        try store.save(saved)
+        cache.set(saved)
+    }
+
+    /// GET /config when it's due: every config_refresh_seconds, or sooner with `maxAgeSeconds` (the
+    /// app coming to the front, so a change such as a Sandbox approval is seen on the next open).
+    /// Conditional, so an unchanged config costs a 304.
+    package func refresh(force: Bool = false, maxAgeSeconds: Int64? = nil) async -> ConfigResult {
+        await lock.withLock { await self.refreshLocked(force: force, maxAgeSeconds: maxAgeSeconds) }
+    }
+
+    private func refreshLocked(force: Bool, maxAgeSeconds: Int64?) async -> ConfigResult {
+        let saved: Saved?
+        do {
+            saved = try load()
+        } catch {
+            return .failed(.backoff)
+        }
+        let refreshSeconds = SdkConfig(saved?.config ?? .null).configRefreshSeconds
+        if !force, let saved, clock.nowSeconds() - saved.fetchedAtSeconds < min(refreshSeconds, maxAgeSeconds ?? refreshSeconds) {
+            return .notDue
+        }
+
+        let response: ApiResponse
+        do {
+            response = try await api.request("GET", "api/v1/config", headers: saved?.etag.map { ["If-None-Match": $0] } ?? [:])
+        } catch {
+            return .failed(.backoff)
+        }
+
+        do {
+            if response.status == 304, var saved {
+                saved.fetchedAtSeconds = clock.nowSeconds()
+                try save(saved)
+                return .unchanged
+            }
+            struct Body: Decodable { let data: JSONValue }
+            if response.status == 200, let body = response.decode(Body.self), case .object = body.data {
+                try save(Saved(config: body.data, etag: response.header("ETag"), fetchedAtSeconds: clock.nowSeconds()))
+                return .updated
+            }
+        } catch {
+            return .failed(.backoff)
+        }
+        return response.isSuccessful ? .failed(.backoff) : .failed(ApiFailure.of(response))
+    }
+}
+
+/// Semantic version order: numbers compared numerically, and a pre-release before its release.
+package enum Versions {
+    package static func compare(_ a: String, _ b: String) -> Int {
+        let (coreA, preA) = split(a)
+        let (coreB, preB) = split(b)
+        for i in 0..<max(coreA.count, coreB.count) {
+            let x = i < coreA.count ? coreA[i] : 0
+            let y = i < coreB.count ? coreB[i] : 0
+            if x != y { return x < y ? -1 : 1 }
+        }
+        switch (preA, preB) {
+        case (nil, nil): return 0
+        case (nil, _): return 1
+        case (_, nil): return -1
+        case let (a?, b?): return comparePre(a, b)
+        }
+    }
+
+    private static func split(_ version: String) -> ([Int], String?) {
+        var clean = version.trimmingCharacters(in: .whitespaces)
+        if clean.hasPrefix("v") { clean.removeFirst() }
+        if let plus = clean.firstIndex(of: "+") { clean = String(clean[..<plus]) }
+        let parts = clean.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)
+        let core = parts[0].split(separator: ".").map { Int($0) ?? 0 }
+        let pre = parts.count > 1 && !parts[1].isEmpty ? String(parts[1]) : nil
+        return (core, pre)
+    }
+
+    private static func comparePre(_ a: String, _ b: String) -> Int {
+        let partsA = a.split(separator: ".")
+        let partsB = b.split(separator: ".")
+        for i in 0..<min(partsA.count, partsB.count) {
+            let x = Int(partsA[i])
+            let y = Int(partsB[i])
+            let diff: Int
+            switch (x, y) {
+            case let (x?, y?): diff = x == y ? 0 : (x < y ? -1 : 1)
+            case (_?, nil): diff = -1
+            case (nil, _?): diff = 1
+            default: diff = partsA[i] == partsB[i] ? 0 : (partsA[i] < partsB[i] ? -1 : 1)
+            }
+            if diff != 0 { return diff }
+        }
+        return partsA.count == partsB.count ? 0 : (partsA.count < partsB.count ? -1 : 1)
+    }
+}