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

package/ios-extension/Sources/BubblCore/Notification/BubblNotification.swift

@@ -0,0 +1,137 @@
+import Foundation
+
+/// A notification as the device API returns it (the contract's Notification: from a geofence
+/// event, a push, a pull or a fetch). `json` is kept whole: it's what an app's own handler is
+/// given, and what the notification screen and the wrappers are handed.
+///
+/// Read leniently, as on Android: media of an unknown type and questions of an unknown type are
+/// left out (a newer server), and only a missing id makes it no notification at all.
+package struct BubblNotification: Sendable, Hashable {
+    package let json: JSONValue
+    package let campaignNotificationId: String
+    package let locationId: String?
+    package let isSurvey: Bool
+    package let headline: String
+    package let body: String
+    package let media: Media?
+    package let cta: Cta?
+    package let questions: [Question]
+    /// From a Sandbox workspace: Bubbl's screen shows a SANDBOX ribbon on it.
+    package let sandbox: Bool
+
+    package struct Cta: Sendable, Hashable {
+        package let label: String
+        package let url: String
+
+        package init(label: String, url: String) {
+            self.label = label
+            self.url = url
+        }
+    }
+
+    package struct Media: Sendable, Hashable {
+        package enum Kind: String, Sendable, CaseIterable {
+            case image, video, audio, youtube, application, text, file
+        }
+
+        package let kind: Kind
+        package let url: String?
+        package let mimeType: String?
+        package let thumbnailUrl: String?
+
+        /// The picture to show for it: the image itself, or a video's thumbnail.
+        package var pictureUrl: String? { kind == .image ? url ?? thumbnailUrl : thumbnailUrl }
+    }
+
+    package struct Choice: Sendable, Hashable {
+        package let id: String
+        package let text: String
+    }
+
+    package struct Question: Sendable, Hashable {
+        package enum Kind: String, Sendable, CaseIterable {
+            case openEnded = "open_ended"
+            case singleChoice = "single_choice"
+            case multipleChoice = "multiple_choice"
+            case rating, boolean, number, slider
+        }
+
+        package let id: String
+        package let text: String
+        package let kind: Kind
+        package let required: Bool
+        package let choices: [Choice]
+    }
+
+    /// Nil when `json` isn't a notification this SDK can show (no id).
+    package init?(_ json: JSONValue) {
+        guard let id = json["campaign_notification_id"]?.nonEmptyString else {
+            BubblLog.warning("A notification without a campaign_notification_id was left out")
+            return nil
+        }
+        self.json = json
+        campaignNotificationId = id
+        locationId = json["location_id"]?.nonEmptyString
+        isSurvey = json["type"]?.stringValue == "survey"
+        headline = json["headline"]?.stringValue ?? ""
+        body = json["body"]?.stringValue ?? ""
+        sandbox = json["sandbox"] == .bool(true)
+
+        if let media = json["media"], media != .null {
+            let type = media["type"]?.stringValue ?? ""
+            if let kind = Media.Kind(rawValue: type.lowercased()) {
+                self.media = Media(kind: kind, url: media["url"]?.nonEmptyString, mimeType: media["mime_type"]?.nonEmptyString, thumbnailUrl: media["thumbnail_url"]?.nonEmptyString)
+            } else {
+                BubblLog.warning("Media of unknown type \"\(type)\" left out of notification \(id) (a newer SDK shows it)")
+                self.media = nil
+            }
+        } else {
+            media = nil
+        }
+
+        if let url = json["cta"]?["url"]?.nonEmptyString {
+            cta = Cta(label: json["cta"]?["label"]?.nonEmptyString ?? url, url: url)
+        } else {
+            cta = nil
+        }
+
+        if case .array(let items)? = json["survey"]?["questions"] {
+            questions = items.compactMap { item in
+                let type = item["type"]?.stringValue ?? ""
+                guard let questionId = item["id"]?.nonEmptyString, let kind = Question.Kind(rawValue: type.lowercased()) else {
+                    BubblLog.warning("A question of type \"\(type)\" left out of notification \(id) (a newer SDK asks it)")
+                    return nil
+                }
+                var choices: [Choice] = []
+                if case .array(let options)? = item["choices"] {
+                    choices = options.compactMap { option in
+                        option["id"]?.nonEmptyString.map { Choice(id: $0, text: option["text"]?.stringValue ?? "") }
+                    }
+                }
+                let required = if case .bool(let value)? = item["required"] { value } else { false }
+                return Question(id: questionId, text: item["text"]?.stringValue ?? "", kind: kind, required: required, choices: choices)
+            }
+        } else {
+            questions = []
+        }
+    }
+
+    /// From the notification's JSON text; nil when it isn't one.
+    package init?(json text: String) {
+        guard let value = try? JSONDecoder().decode(JSONValue.self, from: Data(text.utf8)) else { return nil }
+        self.init(value)
+    }
+
+    /// The JSON text, as the device API sent it (key order aside).
+    package var jsonText: String {
+        (try? JSONEncoder().encode(json)).map { String(decoding: $0, as: UTF8.self) } ?? "{}"
+    }
+}
+
+extension JSONValue {
+    /// A string that isn't empty; nil for anything else.
+    package var nonEmptyString: String? {
+        guard case .string(let value) = self, !value.isEmpty else { return nil }
+        return value
+    }
+}

package/ios-extension/Sources/BubblCore/Notification/NotificationEvents.swift

@@ -0,0 +1,160 @@
+import Foundation
+
+/// The events a notification's life produces, in the contract's shapes (events.json), handed to
+/// `enqueue` (the event queue). Each carries the campaign_notification_id, as the contract asks.
+package struct NotificationEvents: Sendable {
+    private let observe: @Sendable (_ type: String, _ notification: BubblNotification) -> Void
+    private let enqueue: @Sendable (_ type: String, _ data: [String: JSONValue]) async throws -> Void
+
+    /// - Parameter observe: told of each event as it's recorded (the app's event listeners).
+    package init(
+        observe: @escaping @Sendable (String, BubblNotification) -> Void = { _, _ in },
+        enqueue: @escaping @Sendable (String, [String: JSONValue]) async throws -> Void
+    ) {
+        self.observe = observe
+        self.enqueue = enqueue
+    }
+
+    package func displayed(_ n: BubblNotification) async throws {
+        var data = base(n)
+        if let location = n.locationId { data["location_id"] = .string(location) }
+        try await record("notification.displayed", n, data)
+    }
+
+    package func opened(_ n: BubblNotification) async throws { try await record("notification.opened", n, base(n)) }
+    package func dismissed(_ n: BubblNotification) async throws { try await record("notification.dismissed", n, base(n)) }
+    package func ctaClicked(_ n: BubblNotification) async throws { try await record("notification.cta_clicked", n, base(n)) }
+    package func surveyStarted(_ n: BubblNotification) async throws { try await record("notification.survey_started", n, base(n)) }
+
+    /// Throws SurveyProblem when the form isn't complete: nothing is recorded.
+    package func surveySubmitted(_ n: BubblNotification, _ form: SurveyForm) async throws {
+        guard let data = form.eventData(n.campaignNotificationId) else {
+            throw SurveyProblem("\"\(form.missing.first?.text ?? "")\" needs an answer")
+        }
+        try await record("survey.submitted", n, data)
+    }
+
+    package func mediaViewed(_ n: BubblNotification, positionSeconds: Double) async throws {
+        var data = base(n)
+        data["position_seconds"] = .double(positionSeconds)
+        try await record("media.viewed", n, data)
+    }
+
+    package func mediaCompleted(_ n: BubblNotification, positionSeconds: Double) async throws {
+        var data = base(n)
+        data["position_seconds"] = .double(positionSeconds)
+        try await record("media.completed", n, data)
+    }
+
+    private func record(_ type: String, _ n: BubblNotification, _ data: [String: JSONValue]) async throws {
+        try await enqueue(type, data)
+        observe(type, n)
+    }
+
+    private func base(_ n: BubblNotification) -> [String: JSONValue] {
+        ["campaign_notification_id": .string(n.campaignNotificationId)]
+    }
+}
+
+/// The notifications shown lately, so one that arrives twice (a push and then a pull, a push
+/// retried) is only shown once. Keeps the most recent `capacity`.
+package final class RecentNotifications: Sendable {
+    private let store: any ValueStore<[String]>
+    private let capacity: Int
+    private let lock = NSLock()
+
+    package init(store: any ValueStore<[String]>, capacity: Int = 200) {
+        self.store = store
+        self.capacity = capacity
+    }
+
+    /// True the first time `campaignNotificationId` is seen; false after that. When the list can't
+    /// be read (before the first unlock) it's taken as the first time: showing a notification
+    /// twice beats losing it.
+    package func firstTime(_ campaignNotificationId: String) -> Bool {
+        lock.sync {
+            guard let ids = try? store.load() ?? [] else { return true }
+            if ids.contains(campaignNotificationId) { return false }
+            try? store.save(Array((ids + [campaignNotificationId]).suffix(capacity)))
+            return true
+        }
+    }
+}
+
+/// Which links from a campaign (a CTA, a media link) the SDK opens: web links and app links,
+/// never schemes that reach into the device or run code.
+package enum LinkPolicy {
+    /// Android's, and iOS's enterprise app-install scheme.
+    private static let blocked: Set<String> = ["javascript", "file", "content", "intent", "data", "android-app", "about", "itms-services"]
+
+    package static func canOpen(_ url: String) -> Bool {
+        guard let scheme = scheme(of: url.trimmingCharacters(in: .whitespaces)) else { return false }
+        return !blocked.contains(scheme)
+    }
+
+    /// The URL's scheme (RFC 3986: a letter, then letters, digits, + - .), lower-cased; nil when
+    /// it has none. Read here rather than by URL(string:), whose leniency differs by platform.
+    private static func scheme(of url: String) -> String? {
+        guard let colon = url.firstIndex(of: ":") else { return nil }
+        let scheme = url[..<colon]
+        guard let first = scheme.unicodeScalars.first, first.isASCII, CharacterSet.letters.contains(first),
+              scheme.unicodeScalars.allSatisfy({ $0.isASCII && (CharacterSet.alphanumerics.contains($0) || "+-.".unicodeScalars.contains($0)) }),
+              !url[url.index(after: colon)...].contains(" ")
+        else { return nil }
+        return scheme.lowercased()
+    }
+}
+
+/// Embedding a YouTube video in the notification screen.
+package enum YouTube {
+    private static let hosts: Set<String> = ["youtube.com", "www.youtube.com", "m.youtube.com", "music.youtube.com", "youtube-nocookie.com", "www.youtube-nocookie.com"]
+
+    /// The video id in a YouTube link (watch?v=, youtu.be/, /embed/, /shorts/, /live/), or nil when
+    /// it isn't one. Only a well-formed id comes back, since it goes into the embed page.
+    package static func videoId(_ url: String) -> String? {
+        guard let components = URLComponents(string: url.trimmingCharacters(in: .whitespaces)),
+              let scheme = components.scheme?.lowercased(), scheme == "http" || scheme == "https",
+              let host = components.host?.lowercased()
+        else { return nil }
+        let segments = components.path.split(separator: "/").map(String.init)
+
+        let candidate: String?
+        if host == "youtu.be" {
+            candidate = segments.first
+        } else if hosts.contains(host), segments.first == "watch" {
+            candidate = components.queryItems?.first { $0.name == "v" }?.value
+        } else if hosts.contains(host), let first = segments.first, ["embed", "shorts", "live", "v"].contains(first), segments.count > 1 {
+            candidate = segments[1]
+        } else {
+            candidate = nil
+        }
+        return candidate.flatMap { isVideoId($0) ? $0 : nil }
+    }
+
+    /// The page the embedded player lives in: YouTube's privacy-enhanced player (no cookies until
+    /// the video plays) filling the frame, starting at once since the person has just tapped Play.
+    /// `origin` identifies the app to YouTube, which refuses embeds that don't say where they are
+    /// (load the page with that origin as its base URL). Nil when `videoId` isn't one.
+    package static func embedHtml(videoId: String, origin: String) -> String? {
+        guard isVideoId(videoId) else { return nil }
+        // RFC 3986 unreserved characters stay as they are; everything else is escaped.
+        let unreserved = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "-._~"))
+        let encodedOrigin = origin.addingPercentEncoding(withAllowedCharacters: unreserved) ?? ""
+        let src = "https://www.youtube-nocookie.com/embed/\(videoId)?autoplay=1&playsinline=1&rel=0&origin=\(encodedOrigin)"
+        return """
+            <!doctype html><html><head>
+            <meta name="viewport" content="width=device-width,initial-scale=1">
+            <style>html,body{margin:0;height:100%;background:#000;overflow:hidden}iframe{position:absolute;inset:0;width:100%;height:100%;border:0}</style>
+            </head><body>
+            <iframe src="\(src)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowfullscreen referrerpolicy="strict-origin-when-cross-origin"></iframe>
+            </body></html>
+            """
+    }
+
+    /// Eleven of A–Z a–z 0–9 _ -.
+    private static func isVideoId(_ value: String) -> Bool {
+        value.unicodeScalars.count == 11 && value.unicodeScalars.allSatisfy {
+            $0.isASCII && (CharacterSet.alphanumerics.contains($0) || $0 == "_" || $0 == "-")
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/Notification/Push.swift

@@ -0,0 +1,134 @@
+import Foundation
+
+/// A push's data, read as the contract's push.json describes it. Only pushes marked bubbl=1 are
+/// Bubbl's; everything else is the app's own and is left alone. On iOS the data keys sit beside
+/// `aps` in the payload (FCM-relayed pushes too); the iOS layer turns the payload into
+/// JSONValue once and hands its top level here.
+package enum PushMessage: Sendable, Equatable {
+    /// The whole notification came in the push.
+    case full(campaignNotificationId: String, notification: JSONValue)
+    /// Too big for the push: fetch it with GET /notifications/{id}.
+    case reference(campaignNotificationId: String)
+    /// A dashboard test push: no campaign behind it, so nothing to fetch or report.
+    case test(title: String, body: String)
+    /// Bubbl's, but not something this SDK can show (a newer format): not the app's to handle either.
+    case unsupported(version: String)
+
+    package static let version = "1"
+    /// The data keys a Bubbl push carries (push.json).
+    package static let keys = ["bubbl", "bubbl_v", "campaign_notification_id", "notification", "test", "title", "body", "image_url"]
+
+    /// The picture for the system notification (image_url), for the notification service
+    /// extension: there even when the notification itself was too big to come in the push. Only
+    /// https, and only in Bubbl's pushes of a format this SDK reads.
+    package static func imageUrl(_ data: [String: JSONValue]) -> String? {
+        guard isBubbl(data), (data["bubbl_v"].flatMap(text) ?? version) == version,
+              let url = data["image_url"]?.nonEmptyString, url.lowercased().hasPrefix("https://")
+        else { return nil }
+        return url
+    }
+
+    /// The contract's push data is all strings (FCM's data is, and the APNs sender puts the same
+    /// string map beside aps). Flags are also taken as 1 or true, so a backend change can't make
+    /// pushes vanish silently.
+    package static func isBubbl(_ data: [String: JSONValue]) -> Bool {
+        isSet(data["bubbl"])
+    }
+
+    /// Nil when the push isn't Bubbl's.
+    package static func parse(_ data: [String: JSONValue]) -> PushMessage? {
+        guard isBubbl(data) else { return nil }
+        let version = data["bubbl_v"].flatMap(text) ?? Self.version
+        guard version == Self.version else {
+            BubblLog.warning("A push in data format \(version) was left alone: this SDK reads format \(Self.version)")
+            return .unsupported(version: version)
+        }
+        if isSet(data["test"]) {
+            return .test(title: data["title"]?.stringValue ?? "", body: data["body"]?.stringValue ?? "")
+        }
+
+        guard let id = data["campaign_notification_id"]?.nonEmptyString else {
+            BubblLog.warning("A Bubbl push with no campaign_notification_id was left alone")
+            return .unsupported(version: version)
+        }
+        // A notification that doesn't parse is fetched instead, rather than lost.
+        switch data["notification"] {
+        case .object?:
+            return .full(campaignNotificationId: id, notification: data["notification"] ?? .null)
+        case .string(let text)?:
+            if let notification = try? JSONDecoder().decode(JSONValue.self, from: Data(text.utf8)), case .object = notification {
+                return .full(campaignNotificationId: id, notification: notification)
+            }
+            return .reference(campaignNotificationId: id)
+        default:
+            return .reference(campaignNotificationId: id)
+        }
+    }
+
+    /// "1", 1 or true.
+    private static func isSet(_ value: JSONValue?) -> Bool {
+        switch value {
+        case .string("1")?, .int(1)?, .bool(true)?: true
+        default: false
+        }
+    }
+
+    /// A string, or a whole number as one ("1" or 1).
+    private static func text(_ value: JSONValue) -> String? {
+        switch value {
+        case .string(let text): text
+        case .int(let number): String(number)
+        default: nil
+        }
+    }
+}
+
+package enum NotificationsResult: Sendable, Equatable {
+    case found([JSONValue])
+    /// The notification no longer exists (deleted, or the campaign ended).
+    case gone
+    case failed(ApiFailure)
+}
+
+/// GET /notifications/{id} and POST /notifications/pull.
+package struct NotificationSource: Sendable {
+    private let api: DeviceApiClient
+
+    package init(api: DeviceApiClient) {
+        self.api = api
+    }
+
+    /// One notification a push referred to without carrying it.
+    package func fetch(_ campaignNotificationId: String) async -> NotificationsResult {
+        let response: ApiResponse
+        do {
+            let id = campaignNotificationId.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed.subtracting(["/"])) ?? campaignNotificationId
+            response = try await api.request("GET", "api/v1/notifications/\(id)")
+        } catch {
+            return .failed(.backoff)
+        }
+
+        struct One: Decodable { let data: JSONValue }
+        if (200...299).contains(response.status) {
+            guard let one = response.decode(One.self), case .object = one.data else { return .failed(.backoff) }
+            return .found([one.data])
+        }
+        if response.status == 404 { return .gone }
+        return .failed(ApiFailure.of(response))
+    }
+
+    /// Scheduled pushes this device hasn't had (a safety net for pushes the OS dropped). Each is
+    /// claimed by the call, so a notification comes back from here at most once.
+    package func pull() async -> NotificationsResult {
+        let response: ApiResponse
+        do {
+            response = try await api.request("POST", "api/v1/notifications/pull")
+        } catch {
+            return .failed(.backoff)
+        }
+
+        struct Many: Decodable { let data: [JSONValue]? }
+        guard (200...299).contains(response.status) else { return .failed(ApiFailure.of(response)) }
+        return .found((response.decode(Many.self)?.data ?? []).filter { if case .object = $0 { true } else { false } })
+    }
+}

package/ios-extension/Sources/BubblCore/Notification/SurveyForm.swift

@@ -0,0 +1,185 @@
+import Foundation
+
+/// The answers to a survey as they're given, checked by the same rules the server applies to
+/// survey.submitted (DeviceEvents::answer), as on Android: choices by id, one for a single
+/// choice; a rating a whole number from 1 to 5; true/false; a number; text of at most 2000
+/// characters. Every required question needs an answer before it can be sent.
+package struct SurveyForm: Sendable {
+    package typealias Question = BubblNotification.Question
+
+    package static let maxText = 2000
+    /// The contract leaves the slider's range open; 0–10 in halves, like a recommend score.
+    package static let sliderMin = 0.0
+    package static let sliderMax = 10.0
+    package static let sliderStep = 0.5
+
+    package let questions: [Question]
+    private var answers: [String: JSONValue] = [:]
+
+    package init(_ questions: [Question]) {
+        self.questions = questions
+    }
+
+    package func answer(_ questionId: String) -> JSONValue? { answers[questionId] }
+
+    package mutating func setText(_ question: Question, _ text: String) {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        set(question, trimmed.isEmpty ? nil : .string(String(String.UnicodeScalarView(trimmed.unicodeScalars.prefix(Self.maxText)))))
+    }
+
+    package mutating func setChoice(_ question: Question, _ choiceId: String) {
+        set(question, .string(choiceId))
+    }
+
+    package mutating func toggleChoice(_ question: Question, _ choiceId: String, chosen: Bool) {
+        var current: [String] = []
+        if case .array(let values)? = answers[question.id] { current = values.compactMap(\.stringValue) }
+        let next = chosen ? current + [choiceId] : current.filter { $0 != choiceId }
+        // Keep the question's own order, whatever order they were ticked in.
+        let ordered = question.choices.map(\.id).filter(next.contains)
+        set(question, ordered.isEmpty ? nil : .array(ordered.map(JSONValue.string)))
+    }
+
+    package mutating func setRating(_ question: Question, _ stars: Int) {
+        set(question, .int(Int64(min(max(stars, 1), 5))))
+    }
+
+    package mutating func setBoolean(_ question: Question, _ value: Bool) {
+        set(question, .bool(value))
+    }
+
+    /// A number typed in; anything that isn't one clears the answer.
+    package mutating func setNumber(_ question: Question, _ text: String) {
+        set(question, Self.parseNumber(text))
+    }
+
+    package mutating func setSlider(_ question: Question, _ value: Double) {
+        set(question, Self.normalise(min(max(value, Self.sliderMin), Self.sliderMax)))
+    }
+
+    /// Required questions still without an answer.
+    package var missing: [Question] { questions.filter { $0.required && answers[$0.id] == nil } }
+
+    package var isComplete: Bool { missing.isEmpty }
+
+    /// survey.submitted's data, in the contract's shape (events.json); nil until complete. (Never a
+    /// trap: an SDK must not bring down the app it's in.)
+    package func eventData(_ campaignNotificationId: String) -> [String: JSONValue]? {
+        guard isComplete else { return nil }
+        let list = questions.compactMap { question in
+            answers[question.id].map { JSONValue.object(["question_id": .string(question.id), "value": $0]) }
+        }
+        return ["campaign_notification_id": .string(campaignNotificationId), "answers": .array(list)]
+    }
+
+    /// Answers `question` (or clears it, for nil). A question of another survey is ignored.
+    private mutating func set(_ question: Question, _ value: JSONValue?) {
+        guard questions.contains(question) else {
+            BubblLog.warning("An answer to \"\(question.id)\", which isn't a question of this survey, was ignored")
+            return
+        }
+        answers[question.id] = value
+    }
+
+    /// A form filled from an app's own survey UI: `answers` by question id, as a choice id (single
+    /// choice), choice ids (multiple), a whole number 1–5 (rating), true/false, a number (number,
+    /// slider within its range) or text. Returns the form, or why it can't be sent.
+    package static func fromAnswers(_ questions: [Question], _ answers: [String: JSONValue]) -> Result<SurveyForm, SurveyProblem> {
+        var form = SurveyForm(questions)
+        let byId = Dictionary(questions.map { ($0.id, $0) }, uniquingKeysWith: { first, _ in first })
+
+        for (id, value) in answers.sorted(by: { $0.key < $1.key }) {
+            guard let question = byId[id] else { return .failure(SurveyProblem("\"\(id)\" isn't a question of this survey")) }
+            if value == .null { continue }
+            let choiceIds = Set(question.choices.map(\.id))
+            let problem: String?
+
+            switch question.kind {
+            case .singleChoice:
+                if let choice = value.stringValue, choiceIds.contains(choice) {
+                    form.setChoice(question, choice)
+                    problem = nil
+                } else {
+                    problem = "one of its choice ids"
+                }
+            case .multipleChoice:
+                if case .array(let items) = value, items.allSatisfy({ $0.stringValue.map(choiceIds.contains) == true }) {
+                    items.compactMap(\.stringValue).forEach { form.toggleChoice(question, $0, chosen: true) }
+                    problem = nil
+                } else {
+                    problem = "a list of its choice ids"
+                }
+            case .rating:
+                if let stars = value.number, stars == stars.rounded(), (1...5).contains(stars) {
+                    form.setRating(question, Int(stars))
+                    problem = nil
+                } else {
+                    problem = "a whole number from 1 to 5"
+                }
+            case .boolean:
+                if case .bool(let answer) = value {
+                    form.setBoolean(question, answer)
+                    problem = nil
+                } else {
+                    problem = "true or false"
+                }
+            case .number:
+                if let number = value.number, number.isFinite {
+                    form.set(question, normalise(number))
+                    problem = nil
+                } else {
+                    problem = "a number"
+                }
+            case .slider:
+                if let number = value.number, (sliderMin...sliderMax).contains(number) {
+                    form.setSlider(question, number)
+                    problem = nil
+                } else {
+                    problem = "a number from \(sliderMin) to \(sliderMax)"
+                }
+            case .openEnded:
+                if let text = value.stringValue, text.unicodeScalars.count <= maxText {
+                    form.setText(question, text)
+                    problem = nil
+                } else {
+                    problem = "text of at most \(maxText) characters"
+                }
+            }
+
+            if let problem { return .failure(SurveyProblem("the answer to \"\(question.text)\" must be \(problem)")) }
+        }
+
+        if let missing = form.missing.first { return .failure(SurveyProblem("\"\(missing.text)\" needs an answer")) }
+        return .success(form)
+    }
+
+    /// A number as a person types it ("3", " 2,5 "); nil for anything else.
+    package static func parseNumber(_ text: String) -> JSONValue? {
+        let trimmed = text.trimmingCharacters(in: .whitespaces).replacingOccurrences(of: ",", with: ".")
+        guard !trimmed.isEmpty, let value = Double(trimmed), value.isFinite else { return nil }
+        return normalise(value)
+    }
+
+    /// Whole numbers are sent as integers (4, not 4.0), as a person would expect to see them.
+    private static func normalise(_ value: Double) -> JSONValue {
+        if value == value.rounded(), abs(value) < 9.0e15 { return .int(Int64(value)) }
+        return .double(value)
+    }
+}
+
+/// Why a survey's answers can't be sent, in words fit for a developer's log.
+package struct SurveyProblem: Error, Equatable, CustomStringConvertible {
+    package let description: String
+    package init(_ description: String) { self.description = description }
+}
+
+extension JSONValue {
+    /// A number, whole or not; nil for anything else (true/false included).
+    package var number: Double? {
+        switch self {
+        case .int(let value): Double(value)
+        case .double(let value): value
+        default: nil
+        }
+    }
+}

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

@@ -0,0 +1,56 @@
+#if canImport(CryptoKit)
+import CryptoKit
+#else
+import Crypto
+#endif
+import Foundation
+
+/// Signs device API v1 requests the way the backend verifies them (bubbl's
+/// `App\Services\Api\ApiRequestSigner`): the hex HMAC-SHA256, keyed with the install's secret,
+/// of `METHOD \n path \n canonical query \n timestamp \n body`. The contract's signing vectors
+/// (contracts/v1/fixtures/v1/signing.json) pin every step, and RequestSignerContractTests
+/// checks this file against them. CryptoKit on Apple platforms; swift-crypto (the same API)
+/// where the core is built elsewhere.
+package enum RequestSigner {
+    /// The X-Bubbl-Signature value. `path` has no leading slash ("api/v1/config"), `query` holds
+    /// the decoded values as they appear in the URL, and `body` is the exact bytes sent (empty
+    /// for a GET), since the server signs the raw body it receives.
+    package static func sign(secret: String, method: String, path: String, timestamp: Int, body: String, query: [String: String] = [:]) -> String {
+        let key = SymmetricKey(data: Data(secret.utf8))
+        let message = Data(stringToSign(method: method, path: path, timestamp: timestamp, body: body, query: query).utf8)
+
+        return HMAC<SHA256>.authenticationCode(for: message, using: key)
+            .map { String(format: "%02x", $0) }
+            .joined()
+    }
+
+    /// What gets signed: the five parts joined by newlines, the method upper-cased.
+    package static func stringToSign(method: String, path: String, timestamp: Int, body: String, query: [String: String] = [:]) -> String {
+        [method.uppercased(), path, canonicalQuery(query), String(timestamp), body].joined(separator: "\n")
+    }
+
+    /// The query parameters sorted by name and RFC 3986-encoded (a space is %20, not +; only
+    /// A–Z a–z 0–9 - . _ ~ are left as they are), so the order they were sent in doesn't matter.
+    /// The SDK only sends flat, lower-case ASCII names, for which sorting by code point matches
+    /// the server's ksort().
+    package static func canonicalQuery(_ query: [String: String]) -> String {
+        query.keys.sorted()
+            .map { "\(encode($0))=\(encode(query[$0] ?? ""))" }
+            .joined(separator: "&")
+    }
+
+    /// RFC 3986 percent-encoding of a string's UTF-8 bytes, hex in upper case (PHP's rawurlencode).
+    private static func encode(_ value: String) -> String {
+        var encoded = ""
+        for byte in value.utf8 {
+            switch byte {
+            case UInt8(ascii: "A")...UInt8(ascii: "Z"), UInt8(ascii: "a")...UInt8(ascii: "z"), UInt8(ascii: "0")...UInt8(ascii: "9"),
+                 UInt8(ascii: "-"), UInt8(ascii: "."), UInt8(ascii: "_"), UInt8(ascii: "~"):
+                encoded.append(Character(UnicodeScalar(byte)))
+            default:
+                encoded += String(format: "%%%02X", byte)
+            }
+        }
+        return encoded
+    }
+}