@advenue/react-native 0.9.0 → 1.0.1

package/ios/vendor/Advenue/AdvenueConfig.swift

@@ -0,0 +1,89 @@
+import Foundation
+
+public struct AdvenueConfig: Sendable {
+  public var apiKey: String
+  public var endpoint: String
+  /// Ignored: the SDK reads the app version from the bundle itself. Setting it
+  /// reports `config.ignored:appVersion` through `onError`. Removed in the next major.
+  public var appVersion: String?
+  public var requireConsent: Bool
+  public var sessionWindowMs: Int64
+  /// Events per request. Matches sdk-core.
+  public var batchSize: Int
+  /// Auto-flush period. Zero disables the timer, which is what tests want and
+  /// no shipping app does.
+  public var flushIntervalMs: Int
+
+  /// Per-key HMAC secret. **Read this before setting it.** The signature
+  /// provides integrity and replay protection, not authentication: anything
+  /// shipped inside an app binary can be extracted from it, exactly as it can
+  /// from a JavaScript bundle. Leaving it nil sends unsigned requests, which
+  /// the server accepts unless the app enforces signatures.
+  public var signingSecret: String?
+
+  /// SKAdNetwork conversion values. Absent means SKAN is not armed at all —
+  /// there is nothing to report without rules, so the machine is not built
+  /// rather than built and idle.
+  public var conversionValues: ConversionValueConfig?
+
+  /// Called when the SDK swallows a best-effort failure. Never receives PII.
+  public var onError: @Sendable (String, any Error) -> Void
+
+  /// Overrides the version stamped on every event. Set by a WRAPPER SDK, never
+  /// by an app.
+  ///
+  /// An event stamped with the Swift SDK's own version says the same thing for
+  /// every install and answers nothing. The useful answer is which wrapper
+  /// produced it — a React Native or Flutter release pins the native snapshot
+  /// inside it, so the wrapper's version identifies both, and wrapper-specific
+  /// bugs are the ones that need identifying. Adjust and AppsFlyer report the
+  /// wrapper for the same reason.
+  ///
+  /// Capped at 32 characters by the ingest schema; a longer value would take
+  /// the whole batch down with a 400, so it is truncated rather than sent.
+  public var sdkVersion: String?
+
+  /// B5: `https://` şema kuralı. Fail-fast `precondition` ile kurulumda
+  /// yakalanır; kuralın kendisi test edilebilir saf fonksiyondur.
+  public static func isSecureEndpoint(_ endpoint: String) -> Bool {
+    endpoint.lowercased().hasPrefix("https://")
+  }
+
+  public init(
+    apiKey: String,
+    endpoint: String = DEFAULT_ENDPOINT,
+    appVersion: String? = nil,
+    requireConsent: Bool = false,
+    sessionWindowMs: Int64 = DEFAULT_SESSION_WINDOW_MS,
+    batchSize: Int = 20,
+    flushIntervalMs: Int = 15_000,
+    signingSecret: String? = nil,
+    conversionValues: ConversionValueConfig? = nil,
+    onError: @escaping @Sendable (String, any Error) -> Void = { _, _ in },
+    sdkVersion: String? = nil,
+    allowInsecureHttp: Bool = false
+  ) {
+    precondition(
+      allowInsecureHttp || Self.isSecureEndpoint(endpoint),
+      "Advenue endpoint must use https:// (allowInsecureHttp is test-only)")
+    self.apiKey = apiKey
+    self.endpoint = endpoint
+    self.appVersion = appVersion
+    self.requireConsent = requireConsent
+    self.sessionWindowMs = sessionWindowMs
+    self.batchSize = batchSize
+    self.flushIntervalMs = flushIntervalMs
+    self.signingSecret = signingSecret
+    self.conversionValues = conversionValues
+    self.onError = onError
+    self.sdkVersion = sdkVersion
+  }
+}
+
+/// Stamped on every event as `sdkVersion`. Swift has no runtime access to its
+/// package version, so this is a constant — and a constant drifts from the
+/// release tag unless something checks. CI does, because the first question
+/// every field report raises is which build produced the event.
+public enum AdvenueVersion {
+  public static let current = "1.0.0"
+}

package/ios/vendor/AdvenueCore/AdvenueValue.swift

@@ -0,0 +1,103 @@
+import Foundation
+
+/// A JSON value an event property may hold.
+///
+/// The server accepts `z.record(z.string(), z.unknown())`, and Swift has no
+/// safe `[String: Any]` Codable — an unencodable value would trap at runtime,
+/// inside the SDK, in someone else's app. A closed enum makes that a compile
+/// error instead, and the literal conformances keep the call site looking like
+/// the dictionary a caller expects to write:
+///
+///     Advenue.track("purchase", properties: ["price": 9.99, "tier": "gold"])
+public enum AdvenueValue: Sendable, Equatable {
+  case string(String)
+  case int(Int)
+  case double(Double)
+  case bool(Bool)
+  case array([AdvenueValue])
+  case object([String: AdvenueValue])
+  case null
+}
+
+extension AdvenueValue: ExpressibleByStringLiteral {
+  public init(stringLiteral value: String) { self = .string(value) }
+}
+extension AdvenueValue: ExpressibleByIntegerLiteral {
+  public init(integerLiteral value: Int) { self = .int(value) }
+}
+extension AdvenueValue: ExpressibleByFloatLiteral {
+  public init(floatLiteral value: Double) { self = .double(value) }
+}
+extension AdvenueValue: ExpressibleByBooleanLiteral {
+  public init(booleanLiteral value: Bool) { self = .bool(value) }
+}
+extension AdvenueValue: ExpressibleByNilLiteral {
+  public init(nilLiteral: ()) { self = .null }
+}
+extension AdvenueValue: ExpressibleByArrayLiteral {
+  public init(arrayLiteral elements: AdvenueValue...) { self = .array(elements) }
+}
+extension AdvenueValue: ExpressibleByDictionaryLiteral {
+  public init(dictionaryLiteral elements: (String, AdvenueValue)...) {
+    self = .object(Dictionary(uniqueKeysWithValues: elements))
+  }
+}
+
+extension AdvenueValue: Encodable {
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case .string(let v): try container.encode(v)
+    case .int(let v): try container.encode(v)
+    case .double(let v): try container.encode(v)
+    case .bool(let v): try container.encode(v)
+    case .array(let v): try container.encode(v)
+    // Null-valued keys are dropped, exactly as an absent optional is. For an
+    // event property `{"x":null}` and `{}` say the same thing to every
+    // consumer, and the server's 8 KB properties cap makes the difference pure
+    // cost. Kotlin's canonical writer has always done this; Swift did not, so
+    // the same call produced different warehouse rows by platform.
+    //
+    // Only in OBJECTS. The `.array` case above keeps its nulls, because there
+    // is no key to omit and dropping one would shift every element after it.
+    case .object(let v): try container.encode(v.filter { $0.value != .null })
+    case .null: try container.encodeNil()
+    }
+  }
+}
+
+/// Reads back exactly what `Encodable` above writes, and refuses anything else.
+///
+/// The closed type exists to protect the CALL SITE — a caller must not be able
+/// to hand the SDK a value it cannot encode. Decoding is the other direction:
+/// these bytes were written from an `AdvenueValue`, so accepting the shapes it
+/// can represent takes nothing away from that guarantee. Anything outside them
+/// throws, and `EventQueue.load` already turns a throwing blob into an empty
+/// queue rather than bricking the SDK.
+///
+/// Order matters. `Int` is tried before `Double`, because a decoder that read
+/// `3` as `3.0` would restore the property and silently change its type on the
+/// wire — a quieter version of the bug this conformance exists to fix.
+extension AdvenueValue: Decodable {
+  public init(from decoder: Decoder) throws {
+    let container = try decoder.singleValueContainer()
+    if container.decodeNil() {
+      self = .null
+    } else if let v = try? container.decode(Bool.self) {
+      self = .bool(v)
+    } else if let v = try? container.decode(Int.self) {
+      self = .int(v)
+    } else if let v = try? container.decode(Double.self) {
+      self = .double(v)
+    } else if let v = try? container.decode(String.self) {
+      self = .string(v)
+    } else if let v = try? container.decode([AdvenueValue].self) {
+      self = .array(v)
+    } else if let v = try? container.decode([String: AdvenueValue].self) {
+      self = .object(v)
+    } else {
+      throw DecodingError.dataCorruptedError(
+        in: container, debugDescription: "not a value AdvenueValue can represent")
+    }
+  }
+}

package/ios/vendor/AdvenueCore/Attestation.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+/// What App Attest produces: the key Apple minted and the CBOR attestation
+/// object the server verifies against it.
+public struct AttestationResult: Equatable, Sendable {
+  public let keyId: String
+  /// Base64. Passed straight through to the server's verifier.
+  public let attestationObject: String
+
+  public init(keyId: String, attestationObject: String) {
+    self.keyId = keyId
+    self.attestationObject = attestationObject
+  }
+}
+
+public enum AttestationError: Error, Equatable, CustomStringConvertible {
+  /// The device cannot attest at all — every simulator, and every Mac. Distinct
+  /// from a failure so the caller can omit the fields quietly rather than retry
+  /// something that can never work.
+  case unsupported
+  case badChallenge
+  case keyGeneration
+  case attestFailed
+
+  public var description: String {
+    switch self {
+    case .unsupported: return "device attestation is not supported here"
+    case .badChallenge: return "the challenge could not be encoded as UTF-8"
+    case .keyGeneration: return "App Attest key generation failed"
+    case .attestFailed: return "attestKey failed"
+    }
+  }
+}
+
+/// Device attestation, injected so the install path can be tested without a
+/// device — which is the only way it can be tested, since
+/// `DCAppAttestService.isSupported` is false in every simulator.
+public protocol Attestation: Sendable {
+  /// Attests a server-issued challenge. Throws rather than returning nil so the
+  /// caller can tell "cannot" from "did not".
+  func attest(challenge: String) async throws -> AttestationResult
+
+  /// The legacy DeviceCheck token: two bits of per-device state Apple keeps
+  /// across reinstalls, which is what makes it useful for reinstall abuse.
+  func deviceCheckToken() async throws -> String
+}
+
+/// Where the one-time challenge comes from. It is server-issued and single-use,
+/// so it cannot be generated on the device.
+public protocol ChallengeSource: Sendable {
+  func challenge(deviceId: String) async throws -> String
+}

package/ios/vendor/AdvenueCore/Backoff.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+/// A non-2xx ingest response. `isRetryable` separates a transient failure from
+/// a poison payload: retrying a 400 forever would block the queue head, and
+/// dropping a 429 would discard events over a throttle.
+public struct IngestError: Error, Equatable, Sendable {
+  public let status: Int
+  public init(status: Int) { self.status = status }
+
+  public var isRetryable: Bool {
+    status == 408 || status == 429 || status >= 500
+  }
+}
+
+/// The delay armed after the Nth consecutive transient failure.
+///
+/// Mirrors sdk-core's `armBackoff`: the cap applies to the exponential term
+/// BEFORE the jitter is added, so the true maximum is `capMs * 1.2`, not
+/// `capMs`. `random` is injected so the schedule is a pure function.
+public func backoffDelayMs(
+  failures: Int,
+  baseMs: Double,
+  capMs: Double,
+  random: Double
+) -> Double {
+  let exponential = min(baseMs * pow(2, Double(failures - 1)), capMs)
+  return exponential + exponential * 0.2 * random
+}

package/ios/vendor/AdvenueCore/ClientEvent.swift

@@ -0,0 +1,154 @@
+import Foundation
+
+/// The wire envelope, mirroring `clientEventSchema` in
+/// `packages/shared/src/events.ts`.
+///
+/// Every optional is genuinely optional on the wire: the server uses zod
+/// `.optional()`, which accepts a missing key and **rejects** an explicit
+/// `null`. Swift's synthesised encoder omits nil for optional properties,
+/// which is the behaviour required here — a hand-written encoder emitting
+/// `null` would 400 the whole batch.
+public struct ClientEvent: Codable, Sendable, Equatable {
+  public var id: String
+  public var deviceId: String
+  public var installationId: String?
+  public var type: String
+  public var name: String
+  public var timestamp: String
+  public var platform: String
+  public var osVersion: String?
+  public var appVersion: String?
+  public var sdkVersion: String?
+  public var network: String?
+  public var campaign: String?
+  public var country: String?
+  public var idfa: String?
+  public var gaid: String?
+  public var limitAdTracking: Bool?
+  public var vendorId: String?
+  public var androidId: String?
+  public var customerUserId: String?
+  public var appInstanceId: String?
+  public var consent: Consent?
+  /// Null-valued keys are dropped on assignment, not at encode time.
+  ///
+  /// The nested case is handled by `AdvenueValue`'s encoder, but this
+  /// dictionary is encoded by the SYNTHESISED encoder — which must stay
+  /// synthesised, because it is what omits the two dozen optional envelope
+  /// fields the server rejects an explicit null for. So the filter lives here,
+  /// on the way in, which also means the persisted queue blob matches what is
+  /// sent rather than carrying keys the wire will not.
+  ///
+  /// A property observer rather than three call sites: `track` and
+  /// `trackInstall` both assign, and a fourth path added later would otherwise
+  /// reintroduce the divergence silently. Observers do not fire during
+  /// initialisation, so the decode path is untouched — it reads data already
+  /// filtered when it was written.
+  public var properties: [String: AdvenueValue]? {
+    didSet {
+      if let current = properties, current.values.contains(.null) {
+        properties = current.filter { $0.value != .null }
+      }
+    }
+  }
+  public var pushToken: String?
+  public var pushProvider: String?
+  public var attestationToken: String?
+  public var attestationType: String?
+  public var attestationKeyId: String?
+  public var attestationChallenge: String?
+  public var deviceCheckToken: String?
+  public var adservicesToken: String?
+
+  public init(
+    id: String, deviceId: String, type: String, name: String, timestamp: String, platform: String
+  ) {
+    self.id = id
+    self.deviceId = deviceId
+    self.type = type
+    self.name = name
+    self.timestamp = timestamp
+    self.platform = platform
+  }
+
+  /// Required for the queue's reload path — and `properties` is decoded with
+  /// everything else, which it was not.
+  ///
+  /// It used to be dropped, on the premise that "nothing reads it back". The
+  /// premise was false: `EventQueue` assigns `events = load(store)` and
+  /// `peek()` returns from `events`, so a reloaded object is exactly what the
+  /// transport re-encodes and sends. An app killed before flushing therefore
+  /// sent every buffered event with no payload — no revenue, no currency, no
+  /// sku. The encoder had always written them; only this refused to read them.
+  ///
+  /// A queue conformance vector now pins it in both SDKs at once.
+  public init(from decoder: Decoder) throws {
+    let c = try decoder.container(keyedBy: CodingKeys.self)
+    id = try c.decode(String.self, forKey: .id)
+    deviceId = try c.decode(String.self, forKey: .deviceId)
+    type = try c.decode(String.self, forKey: .type)
+    name = try c.decode(String.self, forKey: .name)
+    timestamp = try c.decode(String.self, forKey: .timestamp)
+    platform = try c.decode(String.self, forKey: .platform)
+    installationId = try c.decodeIfPresent(String.self, forKey: .installationId)
+    osVersion = try c.decodeIfPresent(String.self, forKey: .osVersion)
+    appVersion = try c.decodeIfPresent(String.self, forKey: .appVersion)
+    sdkVersion = try c.decodeIfPresent(String.self, forKey: .sdkVersion)
+    network = try c.decodeIfPresent(String.self, forKey: .network)
+    campaign = try c.decodeIfPresent(String.self, forKey: .campaign)
+    country = try c.decodeIfPresent(String.self, forKey: .country)
+    idfa = try c.decodeIfPresent(String.self, forKey: .idfa)
+    gaid = try c.decodeIfPresent(String.self, forKey: .gaid)
+    limitAdTracking = try c.decodeIfPresent(Bool.self, forKey: .limitAdTracking)
+    vendorId = try c.decodeIfPresent(String.self, forKey: .vendorId)
+    androidId = try c.decodeIfPresent(String.self, forKey: .androidId)
+    customerUserId = try c.decodeIfPresent(String.self, forKey: .customerUserId)
+    appInstanceId = try c.decodeIfPresent(String.self, forKey: .appInstanceId)
+    pushToken = try c.decodeIfPresent(String.self, forKey: .pushToken)
+    pushProvider = try c.decodeIfPresent(String.self, forKey: .pushProvider)
+    attestationToken = try c.decodeIfPresent(String.self, forKey: .attestationToken)
+    attestationType = try c.decodeIfPresent(String.self, forKey: .attestationType)
+    attestationKeyId = try c.decodeIfPresent(String.self, forKey: .attestationKeyId)
+    attestationChallenge = try c.decodeIfPresent(String.self, forKey: .attestationChallenge)
+    deviceCheckToken = try c.decodeIfPresent(String.self, forKey: .deviceCheckToken)
+    adservicesToken = try c.decodeIfPresent(String.self, forKey: .adservicesToken)
+    consent = try c.decodeIfPresent(Consent.self, forKey: .consent)
+    properties = try c.decodeIfPresent([String: AdvenueValue].self, forKey: .properties)
+  }
+}
+
+public enum EventEncoding {
+  /// Milliseconds-since-epoch to the exact form TypeScript's `toISOString()`
+  /// produces: always three fractional digits, always `Z`. Foundation's
+  /// `.iso8601` strategy drops fractional seconds entirely, which would change
+  /// every timestamp on the wire.
+  public static func iso8601(ms: Int64) -> String {
+    // Floor to the second so a negative millisecond remainder cannot borrow
+    // from the second field.
+    let wholeSeconds = Int64((Double(ms) / 1000.0).rounded(.down))
+    let millis = ms - wholeSeconds * 1000
+    let date = Date(timeIntervalSince1970: Double(wholeSeconds))
+    var calendar = Calendar(identifier: .gregorian)
+    calendar.timeZone = TimeZone(secondsFromGMT: 0)!
+    let c = calendar.dateComponents([.year, .month, .day, .hour, .minute, .second], from: date)
+    return String(
+      format: "%04d-%02d-%02dT%02d:%02d:%02d.%03dZ",
+      c.year!, c.month!, c.day!, c.hour!, c.minute!, c.second!, Int(millis))
+  }
+
+  /// The canonical JSON encoder: keys sorted so output is byte-comparable with
+  /// the conformance snapshots, and nothing pretty-printed on the wire.
+  public static func canonicalEncoder() -> JSONEncoder {
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+    return encoder
+  }
+}
+
+extension ClientEvent {
+  /// The exact bytes this event puts on the wire.
+  public func encodeCanonical() throws -> String {
+    let data = try EventEncoding.canonicalEncoder().encode(self)
+    return String(decoding: data, as: UTF8.self)
+  }
+}

package/ios/vendor/AdvenueCore/Consent.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+/// Granular ad-platform consent (Google DMA), forwarded to Google and Meta by
+/// server-side postbacks as `gdpr_applies`, `ad_user_data`, `ad_personalization`
+/// and `ad_storage`.
+///
+/// Three of the four fields are optional, and that is the point rather than
+/// laxity: **"not stated" is not "denied".** A CMP that has not asked about ad
+/// storage yet must not have `false` invented on its behalf, because downstream
+/// that is a recorded refusal. The encoder omits nil, which is what keeps the
+/// distinction on the wire.
+public struct Consent: Codable, Equatable, Sendable {
+  public var isUserSubjectToGDPR: Bool
+  public var hasConsentForDataUsage: Bool?
+  public var hasConsentForAdsPersonalization: Bool?
+  public var hasConsentForAdStorage: Bool?
+
+  public init(
+    isUserSubjectToGDPR: Bool,
+    hasConsentForDataUsage: Bool? = nil,
+    hasConsentForAdsPersonalization: Bool? = nil,
+    hasConsentForAdStorage: Bool? = nil
+  ) {
+    self.isUserSubjectToGDPR = isUserSubjectToGDPR
+    self.hasConsentForDataUsage = hasConsentForDataUsage
+    self.hasConsentForAdsPersonalization = hasConsentForAdsPersonalization
+    self.hasConsentForAdStorage = hasConsentForAdStorage
+  }
+}
+
+/// Validates a push token against the server's bound and charset.
+///
+/// Rejecting here costs one dropped registration; letting it through costs
+/// every event in the batch it would have ridden in, because ingest parses a
+/// batch as a whole.
+public func isValidPushToken(_ token: String) -> Bool {
+  guard !token.isEmpty, token.count <= 512 else { return false }
+  let allowed = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "_:.-"))
+  return token.unicodeScalars.allSatisfy { allowed.contains($0) }
+}

package/ios/vendor/AdvenueCore/Contracts.swift

@@ -0,0 +1,59 @@
+import Foundation
+
+/// Synchronous key/value storage. On iOS this is a `UserDefaults` suite; in
+/// tests it is an in-memory dictionary. Mirrors `StorageAdapter` in sdk-core.
+public protocol KeyValueStore: Sendable {
+  func string(forKey key: String) -> String?
+  func set(_ value: String, forKey key: String)
+  func removeObject(forKey key: String)
+}
+
+/// HMAC-SHA256, injected so `AdvenueCore` never imports a crypto library and
+/// therefore builds anywhere. Production supplies CryptoKit; the Linux test
+/// path supplies swift-crypto.
+public protocol Signer: Sendable {
+  /// Lowercase hex digest of `message` under `secret`, both UTF-8.
+  func hmacSHA256Hex(secret: String, message: String) -> String
+}
+
+/// Milliseconds since the Unix epoch. Injected so vectors are deterministic.
+public protocol Clock: Sendable {
+  func nowMs() -> Int64
+}
+
+/// Opaque handle returned by `Scheduler.schedule`.
+public typealias CancelToken = UInt64
+
+/// Deferred execution, injected so the persist debounce is observable without
+/// waiting for it.
+///
+/// **Isolation contract.** `work` is NOT `@Sendable`: an implementation must
+/// run it in the same isolation domain that called `schedule`. The iOS
+/// scheduler satisfies this by hopping back onto the engine actor before
+/// invoking it; the test scheduler satisfies it by running it inline.
+///
+/// The alternative — marking it `@Sendable` and declaring the queue
+/// `@unchecked Sendable` so it can be captured — would compile by asserting
+/// thread safety the queue does not have. This way the requirement is on the
+/// scheduler, where it can actually be met.
+public protocol Scheduler: Sendable {
+  func schedule(afterMs: Int, _ work: @escaping () -> Void) -> CancelToken
+  func cancel(_ token: CancelToken)
+}
+
+/// Event, session and device id source. Injected for the same reason.
+public protocol UUIDSource: Sendable {
+  func next() -> String
+}
+
+/// HMAC over `"\(timestamp).\(body)"` — the Stripe-style construction in
+/// `packages/signing`. Binding the timestamp is what makes replay detectable,
+/// so the separator and the order are part of the contract, not a detail.
+public func signRequest(
+  _ signer: Signer,
+  secret: String,
+  timestamp: String,
+  body: String
+) -> String {
+  signer.hmacSHA256Hex(secret: secret, message: "\(timestamp).\(body)")
+}

package/ios/vendor/AdvenueCore/Conversion.swift

@@ -0,0 +1,74 @@
+import Foundation
+
+/// Deferred deep linking: the install that came from a link carrying a
+/// destination, where the destination has to survive the trip through the App
+/// Store.
+///
+/// The device asks the server what it was attributed to. An organic install is
+/// never attributed, so the lookup is *expected* to answer pending forever for
+/// most devices — which is why the loop gives up rather than polling on.
+public struct DeepLink: Equatable, Sendable {
+  public var deepLinkValue: String?
+  public var campaign: String?
+  public var network: String?
+  public var influencerId: String?
+  public var isDeferred: Bool
+  public var isFirstLaunch: Bool
+
+  public init(
+    deepLinkValue: String? = nil, campaign: String? = nil, network: String? = nil,
+    influencerId: String? = nil, isDeferred: Bool = true, isFirstLaunch: Bool = true
+  ) {
+    self.deepLinkValue = deepLinkValue
+    self.campaign = campaign
+    self.network = network
+    self.influencerId = influencerId
+    self.isDeferred = isDeferred
+    self.isFirstLaunch = isFirstLaunch
+  }
+}
+
+/// What a lookup returned: still deciding, or decided.
+public enum ConversionResult: Equatable, Sendable {
+  case pending
+  case resolved(DeepLink)
+}
+
+public protocol ConversionFetcher: Sendable {
+  /// Throws `IngestError` on a non-2xx; `isRetryable` decides what happens next.
+  func fetch() async throws -> ConversionResult
+}
+
+/// Copied from `packages/sdk-core/src/conversion.ts`, not chosen here.
+public let DEFAULT_CONVERSION_BACKOFF_MS: [Int] = [500, 1000, 2000, 4000]
+
+/// Polls the conversion lookup until it resolves, the budget runs out, or the
+/// server says never.
+///
+/// The three exits are deliberately different. A **pending** answer means the
+/// pipeline has not decided yet, so it is worth waiting. A **non-retryable**
+/// error is the server saying it never will, and retrying is pure battery cost
+/// on a device that will never get an answer. A **transient** error is
+/// indistinguishable from pending, so it falls through to the same backoff.
+public func resolveDeferredDeepLink(
+  fetcher: any ConversionFetcher,
+  maxAttempts: Int = 5,
+  backoffMs: [Int] = DEFAULT_CONVERSION_BACKOFF_MS,
+  sleep: @Sendable (Int) async -> Void = { ms in
+    try? await Task.sleep(nanoseconds: UInt64(ms) * 1_000_000)
+  }
+) async -> DeepLink? {
+  for attempt in 0..<maxAttempts {
+    do {
+      if case .resolved(let link) = try await fetcher.fetch() { return link }
+    } catch {
+      if let ingest = error as? IngestError, !ingest.isRetryable { return nil }
+      // Retryable, or a transport failure: fall through to the backoff.
+    }
+
+    if attempt < maxAttempts - 1 {
+      await sleep(attempt < backoffMs.count ? backoffMs[attempt] : (backoffMs.last ?? 0))
+    }
+  }
+  return nil
+}