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

package/ios-extension/Sources/BubblCore/Engine/Sandbox.swift

@@ -0,0 +1,149 @@
+import Foundation
+
+/// The workspace an API key belongs to, from POST /installs and GET /config (`workspace`):
+/// Sandbox (a pk_test_ key: free, and only approved test devices get anything) or Production
+/// (pk_live_). In Sandbox, `testDevice` says where this device stands: pending until someone
+/// approves it (with the short `code` the dashboard lists it under), then approved.
+package struct Workspace: Sendable, Equatable {
+    package struct TestDevice: Sendable, Equatable {
+        /// pending or approved (as the server says; a newer server may add others). An approved phone
+        /// unused for 30 days goes back to pending; a revoked one registers again as pending.
+        package let status: String
+        /// While pending: the short code the dashboard lists this device under (e.g. K7Q-2MX).
+        package let code: String?
+
+        package init(status: String, code: String?) {
+            self.status = status
+            self.code = code
+        }
+    }
+
+    /// "sandbox" or "production".
+    package let environment: String
+    package let testDevice: TestDevice?
+
+    package init(environment: String, testDevice: TestDevice?) {
+        self.environment = environment
+        self.testDevice = testDevice
+    }
+
+    package var isSandbox: Bool { environment == "sandbox" }
+
+    /// What the log says about it, at start and when it changes: in Sandbox, how to get this device
+    /// approved; nothing in Production (or from a server that predates Sandbox).
+    package var announcement: (warning: Bool, message: String)? {
+        guard isSandbox, let testDevice else { return nil }
+        switch testDevice.status {
+        case "pending":
+            guard let code = testDevice.code else { return (true, "Bubbl sandbox: this device is waiting to be approved as a test device (Test devices in the dashboard)") }
+            return (true, "Bubbl sandbox: approve this device with code \(code)")
+        case "approved":
+            return (false, "Bubbl sandbox: this device is an approved test device")
+        default:
+            return nil
+        }
+    }
+}
+
+extension SdkConfig {
+    /// Nil from a server that predates Sandbox (every workspace was Production then).
+    package var workspace: Workspace? {
+        guard let block = json["workspace"], let environment = block["environment"]?.nonEmptyString else { return nil }
+        let device = block["test_device"]
+        let testDevice = device?["status"]?.nonEmptyString.map { Workspace.TestDevice(status: $0, code: device?["code"]?.nonEmptyString) }
+        return Workspace(environment: environment, testDevice: testDevice)
+    }
+}
+
+extension EngineStart {
+    /// The console's warning for a key that doesn't suit the build: a Sandbox key in a release
+    /// build (only approved test devices would get anything), or a Production key in a debug build
+    /// (development should go to Sandbox). Nil when they suit, or for a key without a prefix.
+    package static func keyWarning(apiKey: String, debugBuild: Bool) -> String? {
+        if apiKey.hasPrefix("pk_test_") && !debugBuild {
+            return "Bubbl: a Sandbox key (pk_test_) in a release build. Only approved test devices get anything from Sandbox: to go live, use the Production key (pk_live_) and https://api.bubbl.tech"
+        }
+        if apiKey.hasPrefix("pk_live_") && debugBuild {
+            return "Bubbl: a Production key (pk_live_) in a debug build. Develop against Sandbox: its key (pk_test_) and https://api.sandbox.bubbl.tech"
+        }
+        return nil
+    }
+}
+
+extension EngineCore {
+    /// The workspace this key belongs to, as last heard; nil before the first registration.
+    package var workspace: Workspace? { configSync.current?.workspace }
+
+    /// Says in the log where this device stands in Sandbox (its approval code while pending), once
+    /// per status and code in a process: at start, and when a registration or the config brings a
+    /// change.
+    package func announceSandbox() {
+        guard let workspace, let said = workspace.announcement else { return }
+        guard sandboxAnnounced.changed(to: said.message) else { return }
+        if said.warning { BubblLog.warning(said.message) } else { BubblLog.info(said.message) }
+    }
+
+    /// POST /test-device: approves this device in Sandbox with a registration code from the
+    /// dashboard (single-use, 24 hours). Approved, with the workspace block the server returns kept
+    /// at once; or not, with why: the server's message (a wrong, used or expired code, the Sandbox
+    /// full), or the SDK's (not running, an empty code, no network). Said in the log too; the code
+    /// itself never is.
+    package func registerTestDevice(_ code: String) async -> TestDeviceResult {
+        func refused(_ why: String) -> TestDeviceResult {
+            BubblLog.warning("Bubbl.registerTestDevice: \(why)")
+            return TestDeviceResult(approved: false, message: why)
+        }
+        guard isActive else { return refused("Bubbl isn't running (consent, a pause, or the SDK's minimum version)") }
+        let trimmed = code.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return refused("the code is empty") }
+
+        let response: ApiResponse
+        do {
+            response = try await api.request("POST", "api/v1/test-device", body: JSON.string(["code": trimmed]))
+        } catch {
+            return refused("the device API couldn't be reached; try again")
+        }
+        guard response.isSuccessful else {
+            let message = (response.json?["message"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+            return refused(message ?? "not approved (\(response.code ?? "HTTP \(response.status)"))")
+        }
+        struct Body: Decodable {
+            struct Content: Decodable { let workspace: JSONValue }
+            let data: Content
+        }
+        if let workspace = response.decode(Body.self)?.data.workspace {
+            try? await configSync.setWorkspace(workspace)
+        } else {
+            _ = await configSync.refresh(force: true)
+        }
+        announceSandbox()
+        return TestDeviceResult(approved: true, message: nil)
+    }
+}
+
+/// What `registerTestDevice` came to.
+package struct TestDeviceResult: Sendable, Equatable {
+    package let approved: Bool
+    /// Why not, when not approved.
+    package let message: String?
+
+    package init(approved: Bool, message: String?) {
+        self.approved = approved
+        self.message = message
+    }
+}
+
+/// The last thing said, so a message is logged once until it changes.
+final class LastSaid: @unchecked Sendable {
+    private let lock = NSLock()
+    private var last: String?
+
+    /// True, and remembered, when `message` differs from the last one.
+    func changed(to message: String) -> Bool {
+        lock.sync {
+            guard message != last else { return false }
+            last = message
+            return true
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/Events/EventQueue.swift

@@ -0,0 +1,207 @@
+import Foundation
+
+/// How a flush ended, so whoever scheduled it (a background task, an app resume) knows what next.
+package enum FlushResult: Sendable, Equatable {
+    /// Everything queued was sent (accepted, a duplicate, or rejected for good).
+    case done(sent: Int, rejected: [Rejection])
+    /// Stopped part way; what's left stays queued.
+    case failed(ApiFailure)
+}
+
+/// An event that can never be sent as it is (its data has a NaN or infinite number, which JSON
+/// can't carry): refused by enqueue rather than queued.
+package struct InvalidEvent: Error, Equatable {
+    package let type: String
+
+    package init(type: String) {
+        self.type = type
+    }
+}
+
+/// An event the server refused for good, with its reasons: logged, never retried.
+package struct Rejection: Sendable, Equatable {
+    package let id: String
+    package let type: String
+    /// The server's reasons, as JSON.
+    package let errors: String
+    /// The names of the fields it refused, for the log.
+    package let fields: [String]
+}
+
+/// The offline event queue behind POST /events. Events are stored the moment they happen and sent
+/// in batches of `batchSize` (at most 100), oldest first. Each carries its own id, which the server
+/// de-duplicates on, so a batch whose answer was lost can simply be sent again.
+///
+/// Capped at `maxEvents` and `maxAgeMillis`: past either, the oldest go (analytics from days ago
+/// isn't worth unbounded storage). One flush at a time. A request that couldn't be made (offline,
+/// the Keychain or the store not readable yet) never drops anything: it's "try again later".
+package final class EventQueue: Sendable {
+    package static let batchSize = 100
+    package static let maxEvents = 1_000
+    package static let maxAgeMillis: Int64 = 72 * 60 * 60 * 1000
+
+    private let store: any EventStore
+    private let api: DeviceApiClient
+    private let clock: ServerClock
+    private let batchSize: @Sendable () -> Int
+    private let newId: @Sendable () -> String
+    private let flushing = AsyncMutex()
+
+    /// - Parameter batchSize: GET /config's max_events_per_request, once known; never more than 100.
+    package init(
+        store: any EventStore,
+        api: DeviceApiClient,
+        clock: ServerClock,
+        batchSize: @escaping @Sendable () -> Int = { EventQueue.batchSize },
+        newId: @escaping @Sendable () -> String = { UUID().uuidString.lowercased() }
+    ) {
+        self.store = store
+        self.api = api
+        self.clock = clock
+        self.batchSize = batchSize
+        self.newId = newId
+    }
+
+    /// Queue an event of `type` ("notification.displayed", …) with its `data`, as happening now on
+    /// the server's clock. Returns the event's id. Throws InvalidEvent when it can never be sent
+    /// (a NaN or infinite number), and EventStoreUnavailable when it can't be stored yet.
+    @discardableResult
+    package func enqueue(_ type: String, data: [String: JSONValue] = [:], occurredAtMillis: Int64? = nil) async throws -> String {
+        // Refused here, before the store: stored, it would stop every flush of its batch.
+        guard JSONValue.object(data).isEncodable else {
+            BubblLog.warning("Event \(type) refused: its data has a number JSON can't carry (NaN or infinite)")
+            throw InvalidEvent(type: type)
+        }
+
+        let id = newId()
+        try await store.add(QueuedEvent(id: id, type: type, occurredAtMillis: occurredAtMillis ?? clock.nowSeconds() * 1000, data: data))
+
+        let overflow = try await store.count() - Self.maxEvents
+        if overflow > 0 { try await store.dropOldest(overflow) }
+        return id
+    }
+
+    /// Send everything queued, batch by batch, until the queue is empty or the server says stop.
+    package func flush() async -> FlushResult {
+        await flushing.withLock { await self.flushLocked() }
+    }
+
+    /// How many events are waiting to be sent.
+    package func size() async throws -> Int { try await store.count() }
+
+    /// Drop everything queued (opt-out, deleteMyData).
+    package func clear() async throws { try await store.clear() }
+
+    private func flushLocked() async -> FlushResult {
+        var sent = 0
+        var rejected: [Rejection] = []
+        let size = min(max(batchSize(), 1), Self.batchSize)
+
+        do {
+            try await store.dropOccurred(before: clock.nowSeconds() * 1000 - Self.maxAgeMillis)
+
+            while true {
+                let batch = try await store.oldest(size)
+                if batch.isEmpty { return .done(sent: sent, rejected: rejected) }
+
+                let body: String
+                do {
+                    body = try Self.body(batch)
+                } catch {
+                    // Can't be written as JSON (enqueue refuses such events, so only a store
+                    // filled some other way): drop the batch rather than retry it forever.
+                    BubblLog.warning("Dropped \(batch.count) queued event(s) that can't be written as JSON")
+                    try await store.remove(Set(batch.map(\.id)))
+                    continue
+                }
+
+                let response = try await api.request("POST", "api/v1/events", body: body)
+
+                // 202 is the contract's answer; any 2xx (a proxy's 200) settles the batch too.
+                if (200...299).contains(response.status) {
+                    let refused = Self.rejections(batch, response)
+                    // Field names only: the errors can quote what was sent.
+                    refused.forEach { BubblLog.warning("Event \($0.type) \($0.id) rejected by the server (fields: \($0.fields.joined(separator: ", ")))") }
+                    rejected += refused
+                    // Accepted, duplicate or rejected: each has had its answer, so none is resent.
+                    try await store.remove(Set(batch.map(\.id)))
+                    sent += batch.count
+                    continue
+                }
+
+                let failure = ApiFailure.of(response)
+                // Only a malformed batch gets a 422, and resending it can't help: drop it rather
+                // than wedge the queue behind it.
+                guard case .drop(_, let status, let code) = failure else { return .failed(failure) }
+                BubblLog.warning("Dropped a batch of \(batch.count) event(s) the server refused (HTTP \(status) \(code ?? ""))")
+                try await store.remove(Set(batch.map(\.id)))
+            }
+        } catch {
+            // Offline, the credential or the store not readable yet: nothing refused, all kept.
+            return .failed(.backoff)
+        }
+    }
+
+    // MARK: - The wire format (contracts/v1: POST /events)
+
+    private struct Body: Encodable {
+        let events: [Event]
+
+        struct Event: Encodable {
+            let id: String
+            let type: String
+            let occurred_at: String
+            let data: [String: JSONValue]
+        }
+    }
+
+    private struct Response: Decodable {
+        let data: Results
+
+        struct Results: Decodable {
+            let results: [Result]
+        }
+
+        struct Result: Decodable {
+            let id: String
+            let status: String
+            let errors: JSONValue?
+        }
+    }
+
+    private static func body(_ batch: [QueuedEvent]) throws -> String {
+        let events = batch.map { Body.Event(id: $0.id, type: $0.type, occurred_at: isoTimestamp($0.occurredAtMillis), data: $0.data) }
+        return String(decoding: try JSONEncoder().encode(Body(events: events)), as: UTF8.self)
+    }
+
+    /// The events a 202 marked rejected, with the server's reasons.
+    private static func rejections(_ batch: [QueuedEvent], _ response: ApiResponse) -> [Rejection] {
+        guard let results = response.decode(Response.self)?.data.results else { return [] }
+        let types = Dictionary(batch.map { ($0.id, $0.type) }, uniquingKeysWith: { first, _ in first })
+
+        return results.filter { $0.status == "rejected" }.map { result in
+            let errors = result.errors.flatMap { try? JSONEncoder().encode($0) }.map { String(decoding: $0, as: UTF8.self) } ?? ""
+            let fields = if case .object(let byField)? = result.errors { byField.keys.sorted() } else { [String]() }
+            return Rejection(id: result.id, type: types[result.id] ?? "", errors: errors, fields: fields)
+        }
+    }
+
+    /// Unix milliseconds as ISO 8601 in UTC ("2026-09-24T10:15:30Z", with milliseconds when there
+    /// are any), as the contract's occurred_at.
+    package static func isoTimestamp(_ millis: Int64) -> String {
+        var calendar = Calendar(identifier: .gregorian)
+        calendar.timeZone = TimeZone(identifier: "UTC") ?? TimeZone(secondsFromGMT: 0) ?? calendar.timeZone
+        let date = Date(timeIntervalSince1970: TimeInterval(millis / 1000))
+        let parts = calendar.dateComponents([.year, .month, .day, .hour, .minute, .second], from: date)
+        let day = "\(pad(parts.year ?? 0, 4))-\(pad(parts.month ?? 0, 2))-\(pad(parts.day ?? 0, 2))"
+        let time = "\(pad(parts.hour ?? 0, 2)):\(pad(parts.minute ?? 0, 2)):\(pad(parts.second ?? 0, 2))"
+        let fraction = Int(millis % 1000)
+        return "\(day)T\(time)" + (fraction == 0 ? "Z" : ".\(pad(fraction, 3))Z")
+    }
+
+    /// `value` with leading zeros to `width` digits.
+    private static func pad(_ value: Int, _ width: Int) -> String {
+        let digits = String(value)
+        return String(repeating: "0", count: max(width - digits.count, 0)) + digits
+    }
+}

package/ios-extension/Sources/BubblCore/Events/EventStore.swift

@@ -0,0 +1,159 @@
+import Foundation
+
+/// One event waiting to be sent to POST /events: the id the server de-duplicates on, its type,
+/// when it happened (unix milliseconds, on the server's clock) and its `data` object.
+package struct QueuedEvent: Sendable, Equatable, Codable {
+    package let id: String
+    package let type: String
+    package let occurredAtMillis: Int64
+    package let data: [String: JSONValue]
+
+    package init(id: String, type: String, occurredAtMillis: Int64, data: [String: JSONValue] = [:]) {
+        self.id = id
+        self.type = type
+        self.occurredAtMillis = occurredAtMillis
+        self.data = data
+    }
+}
+
+/// The store couldn't be read or written, so it did neither: nothing was lost or overwritten.
+/// Before the first unlock after a reboot iOS keeps protected files closed; try again later.
+package struct EventStoreUnavailable: Error {
+    package let underlying: any Error
+}
+
+/// Where queued events wait: on disk on a device, so they survive the app being killed and the
+/// phone being offline. Oldest first throughout (id breaks ties).
+package protocol EventStore: Actor {
+    func add(_ event: QueuedEvent) throws
+    /// Up to `limit` of the oldest events, oldest first.
+    func oldest(_ limit: Int) throws -> [QueuedEvent]
+    func remove(_ ids: Set<String>) throws
+    func count() throws -> Int
+    /// Drops the `count` oldest events (the queue's size cap).
+    func dropOldest(_ count: Int) throws
+    /// Drops events that happened before `millis` (the queue's age cap); returns how many.
+    @discardableResult func dropOccurred(before millis: Int64) throws -> Int
+    /// Drops everything (opt-out, deleteMyData).
+    func clear() throws
+}
+
+/// The events themselves, however they're kept: shared by the memory and file stores.
+private struct Events {
+    var all: [QueuedEvent] = []
+
+    mutating func add(_ event: QueuedEvent) {
+        if !all.contains(where: { $0.id == event.id }) { all.append(event) }
+    }
+
+    func oldest(_ limit: Int) -> [QueuedEvent] { Array(sorted().prefix(max(limit, 0))) }
+
+    mutating func remove(_ ids: Set<String>) { all.removeAll { ids.contains($0.id) } }
+
+    mutating func dropOldest(_ count: Int) { remove(Set(oldest(count).map(\.id))) }
+
+    mutating func dropOccurred(before millis: Int64) -> Int {
+        let before = all.count
+        all.removeAll { $0.occurredAtMillis < millis }
+        return before - all.count
+    }
+
+    /// By when they happened; events of the same millisecond in the order they were recorded (not
+    /// by id, which is random).
+    private func sorted() -> [QueuedEvent] {
+        all.enumerated()
+            .sorted { ($0.element.occurredAtMillis, $0.offset) < ($1.element.occurredAtMillis, $1.offset) }
+            .map(\.element)
+    }
+}
+
+/// An EventStore in memory: for tests.
+package actor InMemoryEventStore: EventStore {
+    private var events = Events()
+
+    package init() {}
+
+    package func add(_ event: QueuedEvent) { events.add(event) }
+    package func oldest(_ limit: Int) -> [QueuedEvent] { events.oldest(limit) }
+    package func remove(_ ids: Set<String>) { events.remove(ids) }
+    package func count() -> Int { events.all.count }
+    package func dropOldest(_ count: Int) { events.dropOldest(count) }
+    @discardableResult package func dropOccurred(before millis: Int64) -> Int { events.dropOccurred(before: millis) }
+    package func clear() { events.all.removeAll() }
+}
+
+/// An EventStore in one JSON file, written whole and atomically on every change (the queue is
+/// capped at 1000 small events). Loaded on first use.
+///
+/// A file that exists but can't be read (protected before the first unlock) is never taken for
+/// an empty queue: every call throws EventStoreUnavailable and nothing is written over it until
+/// it can be read. A missing file is an empty queue.
+///
+/// One process only: the file is cached in memory and rewritten whole from that cache, so a
+/// second writer's events would be lost. The notification service extension (a separate process)
+/// must never share this file; anything it reports goes its own way (its own file, merged by the
+/// app, or a request of its own).
+package actor FileEventStore: EventStore {
+    private let url: URL
+    private let writeOptions: Data.WritingOptions
+    private var loaded: Events?
+
+    /// - Parameter writeOptions: added to `.atomic`; on iOS, the file protection class.
+    package init(url: URL, writeOptions: Data.WritingOptions = []) {
+        self.url = url
+        self.writeOptions = writeOptions.union(.atomic)
+    }
+
+    package func add(_ event: QueuedEvent) throws { try change { $0.add(event) } }
+    package func oldest(_ limit: Int) throws -> [QueuedEvent] { try events().oldest(limit) }
+    package func remove(_ ids: Set<String>) throws { try change { $0.remove(ids) } }
+    package func count() throws -> Int { try events().all.count }
+    package func dropOldest(_ count: Int) throws { try change { $0.dropOldest(count) } }
+
+    @discardableResult
+    package func dropOccurred(before millis: Int64) throws -> Int {
+        var dropped = 0
+        try change { dropped = $0.dropOccurred(before: millis) }
+        return dropped
+    }
+
+    package func clear() throws { try change { $0.all.removeAll() } }
+
+    private func events() throws -> Events {
+        if let loaded { return loaded }
+
+        var events = Events()
+        if FileManager.default.fileExists(atPath: url.path) {
+            let data: Data
+            do {
+                data = try Data(contentsOf: url)
+            } catch {
+                // Can't be read yet (protected until the first unlock): wait, don't overwrite.
+                throw EventStoreUnavailable(underlying: error)
+            }
+            // Read but not understood (corrupt, or from an incompatible build): starting afresh
+            // loses some analytics; keeping it would stop the queue for good.
+            if let decoded = try? JSONDecoder().decode([QueuedEvent].self, from: data) {
+                events = Events(all: decoded)
+            }
+        }
+        loaded = events
+        return events
+    }
+
+    /// Applies `body` and writes the result; memory changes only once the file has. Only reading
+    /// or writing the file counts as "unavailable": an event that can't be encoded throws its
+    /// EncodingError, since trying again later can't help it.
+    private func change(_ body: (inout Events) -> Void) throws {
+        var events = try events()
+        body(&events)
+        let data = try JSONEncoder().encode(events.all)
+        do {
+            try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+            try data.write(to: url, options: writeOptions)
+        } catch {
+            throw EventStoreUnavailable(underlying: error)
+        }
+        loaded = events
+    }
+}

package/ios-extension/Sources/BubblCore/Geofence/Geofence.swift

@@ -0,0 +1,160 @@
+import Foundation
+
+package struct LatLng: Sendable, Hashable, Codable {
+    package let latitude: Double
+    package let longitude: Double
+
+    package init(_ latitude: Double, _ longitude: Double) {
+        self.latitude = latitude
+        self.longitude = longitude
+    }
+}
+
+/// Where the device is, as a location fix gives it. `timeMillis` is on the device's clock.
+package struct Fix: Sendable, Hashable, Codable {
+    package let position: LatLng
+    package let accuracyMeters: Double?
+    package let timeMillis: Int64
+
+    package init(_ position: LatLng, accuracyMeters: Double?, timeMillis: Int64) {
+        self.position = position
+        self.accuracyMeters = accuracyMeters
+        self.timeMillis = timeMillis
+    }
+}
+
+/// One geofence from GET /geofences. A polygon is watched through the circle around it
+/// (`center`, `radiusMeters`); only being inside the polygon itself counts as being there.
+package struct Geofence: Sendable, Hashable, Codable {
+    package let id: String
+    package let name: String
+    package let center: LatLng
+    package let radiusMeters: Int
+    /// Nil for a circle. A ring, not closed: the last point joins the first.
+    package let polygon: [LatLng]?
+    package let reportsEnter: Bool
+    package let reportsExit: Bool
+
+    package init(id: String, name: String, center: LatLng, radiusMeters: Int, polygon: [LatLng]?, reportsEnter: Bool, reportsExit: Bool) {
+        self.id = id
+        self.name = name
+        self.center = center
+        self.radiusMeters = radiusMeters
+        self.polygon = polygon
+        self.reportsEnter = reportsEnter
+        self.reportsExit = reportsExit
+    }
+
+    package var isPolygon: Bool { polygon != nil }
+}
+
+/// What GET /geofences last returned, with where and when it was asked from: the device asks
+/// again after `refreshSeconds`, or once it has moved `refreshDistanceMeters` from `origin`.
+package struct GeofenceSet: Sendable, Hashable, Codable {
+    package var geofences: [Geofence]
+    package var refreshSeconds: Int64
+    package var refreshDistanceMeters: Int
+    package var origin: LatLng
+    /// On the server's clock.
+    package var fetchedAtSeconds: Int64
+    package var etag: String?
+
+    package init(geofences: [Geofence], refreshSeconds: Int64, refreshDistanceMeters: Int, origin: LatLng, fetchedAtSeconds: Int64, etag: String?) {
+        self.geofences = geofences
+        self.refreshSeconds = refreshSeconds
+        self.refreshDistanceMeters = refreshDistanceMeters
+        self.origin = origin
+        self.fetchedAtSeconds = fetchedAtSeconds
+        self.etag = etag
+    }
+
+    /// From a GET /geofences 200 body; nil when it isn't one. Geofences this SDK can't watch (an
+    /// unknown shape, a ring of fewer than three points) are left out.
+    package static func fromResponse(_ body: Data, origin: LatLng, fetchedAtSeconds: Int64, etag: String?) -> GeofenceSet? {
+        guard let response = try? JSONDecoder().decode(GeofencesResponse.self, from: body) else { return nil }
+        return GeofenceSet(
+            geofences: response.data.compactMap(\.geofence),
+            refreshSeconds: response.meta.refresh_seconds,
+            refreshDistanceMeters: response.meta.refresh_distance_meters,
+            origin: origin,
+            fetchedAtSeconds: fetchedAtSeconds,
+            etag: etag
+        )
+    }
+}
+
+/// GET /geofences as the contract describes it (contracts/v1: Geofence, GeofencesMeta).
+private struct GeofencesResponse: Decodable {
+    let data: [Item]
+    let meta: Meta
+
+    struct Meta: Decodable {
+        let refresh_seconds: Int64
+        let refresh_distance_meters: Int
+    }
+
+    struct Item: Decodable {
+        let id: String
+        let name: String?
+        let shape: String
+        let center: LatLng
+        let radius_meters: Int
+        let polygon: [LatLng]?
+        let triggers: [String]
+
+        var geofence: Geofence? {
+            let ring: [LatLng]?
+            switch shape {
+            case "circle":
+                ring = nil
+            case "polygon":
+                guard let polygon, polygon.count >= 3 else { return nil }
+                ring = polygon
+            default:
+                return nil
+            }
+            return Geofence(
+                id: id,
+                name: name ?? "",
+                center: center,
+                radiusMeters: radius_meters,
+                polygon: ring,
+                reportsEnter: triggers.contains("enter"),
+                reportsExit: triggers.contains("exit")
+            )
+        }
+    }
+}
+
+package enum Geo {
+    private static let earthRadiusMeters = 6_371_008.8
+
+    /// Great-circle distance (haversine).
+    package static func distanceMeters(_ a: LatLng, _ b: LatLng) -> Double {
+        let radians = Double.pi / 180
+        let dLat = (b.latitude - a.latitude) * radians
+        let dLng = (b.longitude - a.longitude) * radians
+        let sinLat = sin(dLat / 2)
+        let sinLng = sin(dLng / 2)
+        let h = sinLat * sinLat + cos(a.latitude * radians) * cos(b.latitude * radians) * sinLng * sinLng
+        return 2 * earthRadiusMeters * asin(min(1, h.squareRoot()))
+    }
+
+    /// Whether `point` is inside `ring` (even-odd ray casting on latitude/longitude). Exact enough
+    /// at geofence scale; not for rings that cross the antimeridian or a pole, which a shop or a
+    /// venue never does.
+    package static func contains(_ ring: [LatLng], _ point: LatLng) -> Bool {
+        var inside = false
+        var j = ring.count - 1
+        for i in ring.indices {
+            let a = ring[i]
+            let b = ring[j]
+            if (a.latitude > point.latitude) != (b.latitude > point.latitude) {
+                let crossing = (b.longitude - a.longitude) * (point.latitude - a.latitude) / (b.latitude - a.latitude) + a.longitude
+                if point.longitude < crossing { inside.toggle() }
+            }
+            j = i
+        }
+        return inside
+    }
+}