@advenue/react-native 0.8.0 → 1.0.0

package/android/src/main/kotlin/io/advenue/Advenue.kt

@@ -0,0 +1,549 @@
+package io.advenue
+
+import android.app.Application
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.Build
+import io.advenue.core.AdvenueEngine
+import io.advenue.core.Command
+import io.advenue.core.CommandPipe
+import io.advenue.core.Consent
+import io.advenue.core.DeepLink
+import io.advenue.core.resolveDeferredDeepLink
+import io.advenue.core.EngineConfig
+import io.advenue.core.EventTransport
+import io.advenue.core.IngestError
+import io.advenue.core.SystemClock
+import io.advenue.core.SystemUuids
+import io.advenue.core.TimerScheduler
+import io.advenue.platform.HttpConversionFetcher
+import io.advenue.platform.HttpUrlTransport
+import io.advenue.platform.IdentityResolution
+import io.advenue.platform.EnrichmentSources
+import io.advenue.platform.InstallScopedStore
+import io.advenue.platform.LifecycleBridge
+import io.advenue.platform.CompositeStore
+import io.advenue.platform.PreferencesStore
+import io.advenue.core.extractAemCampaignIds
+import io.advenue.core.tcfToConsent
+import io.advenue.platform.collectDeviceInfo
+import io.advenue.platform.readTcf
+import io.advenue.platform.collectEnrichment
+import io.advenue.platform.sha256Hex
+import io.advenue.platform.resolveIdentity
+import io.advenue.platform.systemUnlockProbe
+import java.util.Timer
+import java.util.TimerTask
+
+/**
+ * The public SDK. A static facade matching the React Native and iOS SDKs' names,
+ * so a developer moving between them reads the same API, delegating to state
+ * that is replaceable and inspectable rather than to a hidden singleton.
+ */
+public object Advenue {
+  private val state = FacadeState()
+
+  /**
+   * Starts the SDK. Safe to call from `Application.onCreate`, and safe to call
+   * twice: the previous instance is shut down first. Without that, a second call
+   * would leave two consumer threads draining one queue, so events would be
+   * processed twice or lost.
+   *
+   * Takes the `Application` explicitly. ContentProvider auto-initialisation —
+   * the Firebase pattern — is rejected: it charges every cold start and hides
+   * initialisation order.
+   */
+  @JvmStatic
+  public fun initialize(application: Application, config: AdvenueConfig) {
+    state.start(application, config)
+  }
+
+  /** Records an event. Synchronous, non-blocking and ordered. */
+  @JvmStatic
+  @JvmOverloads
+  public fun track(name: String, properties: Map<String, Any?>? = null) {
+    state.submit(Command.Track(name, properties, "custom"))
+  }
+
+  @JvmStatic
+  public fun setUserId(id: String?) {
+    state.submit(Command.SetUserId(id))
+  }
+
+  /**
+   * Granular ad-platform consent (Google DMA), forwarded by server-side
+   * postbacks as gdpr_applies / ad_user_data / ad_personalization / ad_storage.
+   *
+   * Leave a field null when the user has not been asked: "not stated" is not
+   * "denied", and inventing false on their behalf records a refusal that never
+   * happened.
+   */
+  @JvmStatic
+  @JvmOverloads
+  public fun setConsentData(
+    isUserSubjectToGDPR: Boolean,
+    hasConsentForDataUsage: Boolean? = null,
+    hasConsentForAdsPersonalization: Boolean? = null,
+    hasConsentForAdStorage: Boolean? = null,
+  ) {
+    val consent =
+      Consent(
+        isUserSubjectToGDPR,
+        hasConsentForDataUsage,
+        hasConsentForAdsPersonalization,
+        hasConsentForAdStorage,
+      )
+    state.consentDataMirror = consent
+    state.submit(Command.SetConsentData(consent))
+  }
+
+  /**
+   * Registers the device's push token for uninstall measurement.
+   *
+   * Advenue never asks for the notification permission and never displays
+   * anything. Pass the token your push library already gives you, on every
+   * launch: the OS can rotate it, and a stale token is what makes uninstall
+   * measurement report churn that did not happen. Pass null to stop.
+   */
+  @JvmStatic
+  @JvmOverloads
+  public fun setPushToken(token: String?, provider: String? = null) {
+    state.submit(Command.SetPushToken(token, provider))
+  }
+
+  /**
+   * The app the ingestion service resolved this API key to, or null until a
+   * batch has been accepted.
+   *
+   * The API key is the SDK's entire app identity, so pasting the wrong one is
+   * silent: events are still accepted, just recorded against another app, and
+   * every screen the integrator checks is the one they believe they configured.
+   * This is the answer to "which app am I actually writing to", read from the
+   * device rather than inferred from the dashboard.
+   */
+  @JvmStatic public fun resolvedAppId(): String? = state.resolvedAppId
+
+  @JvmStatic
+  public fun setConsent(granted: Boolean) {
+    state.consentMirror = granted
+    state.submit(Command.SetConsent(granted))
+  }
+
+  /**
+   * Whether tracking consent is currently granted. Persisted, so this is the
+   * answer after a restart too — a caller that defaulted to false on every cold
+   * start would silently discard a preference the user gave.
+   */
+  @JvmStatic public fun trackingConsent(): Boolean = state.consentMirror
+
+  /** The granular DMA consent last set, or null if none has been. */
+  @JvmStatic public fun consentData(): Consent? = state.consentDataMirror
+
+  /**
+   * The Firebase App Instance ID, when the app resolves it itself rather than
+   * through the `advenue-firebase` plugin. Does not disturb the advertising
+   * identity.
+   */
+  @JvmStatic
+  public fun setAppInstanceId(id: String?) {
+    state.submit(Command.SetAppInstanceId(id))
+  }
+
+  /** Sends what is buffered. A no-op when the queue is empty or a backoff is open. */
+  @JvmStatic
+  public fun flush() {
+    state.submit(Command.Flush)
+  }
+
+  /**
+   * Forward from `onCreate` and `onNewIntent`. Callable **before** `initialize`:
+   * a cold start from a link runs the launcher activity first, and the links
+   * that carry attribution are precisely the ones that would be lost.
+   *
+   * `Intent.EXTRA_REFERRER` is deliberately not read here — it is not the Play
+   * install referrer, and conflating them would make a warm-start deep link look
+   * like one.
+   */
+  @JvmStatic
+  public fun processDeepLink(intent: Intent?) {
+    intent?.data?.toString()?.let { state.deepLink(it) }
+  }
+
+  /** Erasure. Spans both stores — see [FacadeState.forgetMe]. */
+  @JvmStatic
+  public fun forgetMe() {
+    state.forgetMe()
+  }
+
+  /**
+   * The device identifier, or **null** while identity is deferred.
+   *
+   * sdk-core's getter is non-null; this one is not, and that is a real API
+   * difference rather than an oversight. Identity can be deferred while
+   * credential-encrypted storage is unreadable (Direct Boot), and blocking until
+   * it resolves could block indefinitely. Returning an invented id is the
+   * phantom-device bug the design exists to prevent.
+   */
+  @JvmStatic public fun deviceId(): String? = state.currentDeviceId
+
+  @JvmStatic public fun pendingCount(): Int = state.pendingCount()
+
+  /**
+   * Resolves the deferred deep link for this install, or null for an organic
+   * one — which is most of them. Safe to call once on first launch; the app
+   * routes on the result.
+   *
+   * Blocking, and deliberately so: it polls with backoff, and hiding that
+   * behind a callback would invite calling it on the main thread. Run it on
+   * your own background thread.
+   */
+  @JvmStatic public fun resolveDeferredDeepLink(): DeepLink? = state.resolveDeferredDeepLink()
+
+  @JvmStatic
+  public fun shutdown() {
+    state.stop()
+  }
+}
+
+/**
+ * Holds what a static facade cannot: the live engine, the command pipe, the
+ * pre-init deep-link buffer and the resolved identity.
+ */
+internal class FacadeState {
+  private val lock = Any()
+  private var pipe: CommandPipe? = null
+  private var engine: AdvenueEngine? = null
+  private var scoped: InstallScopedStore? = null
+  private var prefs: PreferencesStore? = null
+  private var bridge: LifecycleBridge? = null
+  private var flushTimer: Timer? = null
+  private var unlockReceiver: BroadcastReceiver? = null
+  private var app: Application? = null
+  private var pendingDeepLinks = mutableListOf<String>()
+  private val seenAemUrlHashes = mutableSetOf<String>()
+
+  /**
+   * Read caches for the two consent values. The engine owns persistence; these
+   * exist so a synchronous getter can answer without a round trip through the
+   * pipe, and so a caller reading back its own `setConsent` never sees the
+   * value it just replaced.
+   */
+  @Volatile internal var consentMirror: Boolean = false
+
+  @Volatile internal var consentDataMirror: Consent? = null
+
+  @Volatile private var resolvedDeviceId: String? = null
+
+  /** Set by the transport after a batch is accepted; diagnostics only. */
+  @Volatile internal var resolvedAppId: String? = null
+  private var startedEndpoint: String? = null
+  private var startedApiKey: String? = null
+
+  /**
+   * `transport` is a parameter, not a hidden construction, because an unwired
+   * transport is otherwise invisible: every component of the send path can be
+   * green while nothing joins them. That is the defect the iOS SDK shipped with,
+   * and `FacadeSeamTest` injects a recorder here to make sure this one cannot.
+   */
+  fun start(
+    application: Application,
+    config: AdvenueConfig,
+    transport: EventTransport? = null,
+    sources: EnrichmentSources? = null,
+  ) {
+    // Replace-and-shut-down, never add.
+    stop()
+
+    val scoped = InstallScopedStore(application)
+    val prefs = PreferencesStore(application)
+    val uuid = SystemUuids()
+
+    val identity = resolveIdentity(scoped, systemUnlockProbe(application), uuid)
+    if (identity !is IdentityResolution.Resolved) {
+      // Deferred: credential-encrypted storage is unreadable. Nothing is minted
+      // and nothing starts, so no event carries an invented identifier. The
+      // receiver below is the exit — without it the deferral would trade a
+      // phantom id for permanent silence.
+      config.onError("identity.deferred", IngestError(0))
+      registerUnlockRetry(application, config, transport, sources)
+      return
+    }
+
+    val eventTransport =
+      transport
+        ?: HttpUrlTransport(
+          endpoint = config.endpoint,
+          apiKey = config.apiKey,
+          signingSecret = config.signingSecret,
+          clock = SystemClock(),
+          // Diagnostics only: it runs after the batch is already accepted, so
+          // nothing it does can turn a successful ingest into a failure.
+          onAccepted = { appId -> resolvedAppId = appId },
+        )
+
+    val scheduler = TimerScheduler()
+    val engine =
+      AdvenueEngine(
+        config =
+          EngineConfig(
+            apiKey = config.apiKey,
+            platform = "android",
+            deviceId = identity.deviceId,
+            installationId = identity.installationId,
+            appVersion = config.appVersion,
+            osVersion = Build.VERSION.RELEASE,
+            sdkVersion = (config.sdkVersion ?: AdvenueVersion.CURRENT).take(32),
+            requireConsent = config.requireConsent,
+            sessionWindowMs = config.sessionWindowMs,
+            batchSize = config.batchSize,
+          ),
+        store = CompositeStore(prefs, scoped),
+        clock = SystemClock(),
+        scheduler = scheduler,
+        uuid = uuid,
+        transport = eventTransport,
+        onError = config.onError,
+      )
+    val pipe = CommandPipe(engine, config.onError)
+    // The debounce timer may only WAKE; the work itself touches the event list,
+    // which belongs to the engine's thread.
+    scheduler.dispatcher = { work -> pipe.submit(Command.RunScheduled(work)) }
+
+    val buffered: List<String>
+    synchronized(lock) {
+      this.app = application
+      this.scoped = scoped
+      this.prefs = prefs
+      this.engine = engine
+      // Seeded from the same persisted values the engine loads, so consent
+      // granted in a previous run is still granted after a cold start.
+      this.consentMirror = engine.getConsent()
+      this.consentDataMirror = engine.getConsentData()
+      this.pipe = pipe
+      this.resolvedDeviceId = identity.deviceId
+      this.startedEndpoint = config.endpoint
+      this.startedApiKey = config.apiKey
+      buffered = pendingDeepLinks.toList()
+      pendingDeepLinks = mutableListOf()
+    }
+
+    // Replayed in arrival order, before the first session, so a deferred deep
+    // link is attributed to the launch it belongs to.
+    buffered.forEach { sendDeepLink(it) }
+
+    val bridge =
+      LifecycleBridge(
+        application,
+        onForeground = { pipe.submit(Command.Foreground) },
+        onBackground = {
+          pipe.submit(Command.Background)
+          // A batch stranded when the app leaves the foreground may not be sent
+          // for hours.
+          pipe.submit(Command.Flush)
+        },
+      )
+    bridge.start()
+    // Application.onCreate runs before the first activity starts, so the
+    // foreground signal arrives from the bridge; a cold start where the SDK is
+    // initialised from an already-running activity still needs this.
+    pipe.submit(Command.Foreground)
+
+    // Enrichment then install, off the caller's thread. initialize() returns
+    // synchronously — an SDK that blocks Application.onCreate for five seconds
+    // is one nobody ships.
+    val installSources = sources ?: EnrichmentSources.discovered()
+    Thread(
+        {
+          val enrichment =
+            collectEnrichment(
+              application,
+              identity.deviceId,
+              installSources,
+              fbAppId = config.fbAppId,
+            )
+          pipe.submit(
+            Command.SetIdentity(
+              gaid = enrichment.gaid,
+              androidId = null,
+              appInstanceId = enrichment.appInstanceId,
+            ),
+          )
+          // Device metadata rides the install, where Meta CAPI reads it.
+          // Merged under the referrer properties: an attribution field wins
+          // over a descriptive one if they ever collide.
+          val installProperties =
+            collectDeviceInfo(application) +
+              (enrichment.referrerProperties ?: emptyMap()) +
+              (enrichment.metaProperties ?: emptyMap())
+          // The CMP writes TCF to the platform's default preferences, and
+          // reading it is the difference between shipping a real consent
+          // signal and shipping none. Submitted before the install so the
+          // first event carries it.
+          readTcf(application)?.let { tcf ->
+            tcfToConsent(
+              tcf["gdprApplies"] as? Int,
+              tcf["purposeConsents"] as? String,
+            )
+              ?.let { pipe.submit(Command.SetConsentData(it)) }
+          }
+          pipe.submit(Command.TrackInstall(installProperties))
+          pipe.submit(Command.Flush)
+        },
+        "advenue-install",
+      )
+      .apply { isDaemon = true }
+      .start()
+
+    val timer =
+      if (config.flushIntervalMs > 0) {
+        Timer("advenue-flush", true).also {
+          it.scheduleAtFixedRate(
+            object : TimerTask() {
+              override fun run() {
+                pipe.submit(Command.Flush)
+              }
+            },
+            config.flushIntervalMs,
+            config.flushIntervalMs,
+          )
+        }
+      } else {
+        null
+      }
+
+    synchronized(lock) {
+      this.bridge = bridge
+      this.flushTimer = timer
+    }
+  }
+
+  /**
+   * The exit from a deferred identity. Registered only when identity could not
+   * be resolved; unregistered on the first successful start.
+   */
+  private fun registerUnlockRetry(
+    application: Application,
+    config: AdvenueConfig,
+    transport: EventTransport?,
+    sources: EnrichmentSources?,
+  ) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) return
+    val receiver =
+      object : BroadcastReceiver() {
+        override fun onReceive(context: Context, intent: Intent) {
+          runCatching { application.unregisterReceiver(this) }
+          synchronized(lock) { unlockReceiver = null }
+          start(application, config, transport, sources)
+        }
+      }
+    runCatching {
+      application.registerReceiver(receiver, IntentFilter(Intent.ACTION_USER_UNLOCKED))
+      synchronized(lock) { unlockReceiver = receiver }
+    }
+  }
+
+  fun submit(command: Command) {
+    synchronized(lock) { pipe }?.submit(command)
+  }
+
+  fun deepLink(url: String) {
+    val started = synchronized(lock) {
+      val running = pipe != null
+      if (!running) pendingDeepLinks.add(url)
+      running
+    }
+    if (started) sendDeepLink(url)
+  }
+
+  private fun sendDeepLink(url: String) {
+    submit(Command.Track("deep_link", mapOf("url" to url), "custom"))
+
+    // Meta AEM: a link from Meta carries al_applink_data with an opaque,
+    // Meta-encrypted campaign_ids blob. Emitted at most once per URL — the
+    // same link re-opened is not a second measurement, and the server dedups
+    // on this hash too.
+    val applink = queryValue(url, "al_applink_data") ?: return
+    val campaignIds = extractAemCampaignIds(applink) ?: return
+    val hash = sha256Hex(url)
+    val fresh = synchronized(lock) { seenAemUrlHashes.add(hash) }
+    if (!fresh) return
+    submit(
+      Command.Track(
+        "adv_meta_aem",
+        mapOf("campaignIds" to campaignIds, "sourceUrlHash" to hash),
+        "custom",
+      ),
+    )
+  }
+
+  /** Decoded value of one query parameter, or null. */
+  private fun queryValue(url: String, name: String): String? =
+    runCatching { android.net.Uri.parse(url).getQueryParameter(name) }.getOrNull()
+
+  /** Test surface: how many links are waiting for `initialize`. */
+  val bufferedDeepLinkCount: Int
+    get() = synchronized(lock) { pendingDeepLinks.size }
+
+  val currentDeviceId: String?
+    get() = resolvedDeviceId
+
+  fun pendingCount(): Int = synchronized(lock) { engine }?.pendingEventIds()?.size ?: 0
+
+  /** Polls the conversion lookup. Null for an organic install. */
+  fun resolveDeferredDeepLink(): DeepLink? {
+    val (endpoint, apiKey, deviceId) =
+      synchronized(lock) {
+        Triple(startedEndpoint, startedApiKey, resolvedDeviceId)
+      }
+    if (endpoint == null || apiKey == null || deviceId == null) return null
+    return resolveDeferredDeepLink(
+      HttpConversionFetcher(endpoint = endpoint, apiKey = apiKey, deviceId = deviceId))
+  }
+
+  /**
+   * Erasure spans BOTH stores. The engine clears what lives in
+   * SharedPreferences; the install-scoped identifiers live in
+   * `noBackupFilesDir` and are wiped here. Calling only the engine's `forgetMe`
+   * is the layering trap the spec recorded — an erasure that leaves the
+   * identifiers behind, and looks finished.
+   */
+  fun forgetMe() {
+    // Both stores are wiped by the engine, on the pipe's thread, so the wipe is
+    // ordered behind any command already queued — a wipe performed here would
+    // race a pending trackInstall and the flag would be written back after it.
+    submit(Command.ForgetMe)
+    synchronized(lock) { resolvedDeviceId = null }
+    // Erasure clears the read caches too: a getter still answering "granted"
+    // after forgetMe would report a consent the device no longer holds.
+    consentMirror = false
+    consentDataMirror = null
+  }
+
+  fun stop() {
+    val (pipe, bridge, timer, receiver, application) =
+      synchronized(lock) {
+        val snapshot =
+          Quintuple(this.pipe, this.bridge, this.flushTimer, this.unlockReceiver, this.app)
+        this.pipe = null
+        this.engine = null
+        this.bridge = null
+        this.flushTimer = null
+        this.unlockReceiver = null
+        snapshot
+      }
+    timer?.cancel()
+    bridge?.stop()
+    receiver?.let { r -> application?.let { runCatching { it.unregisterReceiver(r) } } }
+    pipe?.shutdown()
+  }
+
+  private data class Quintuple(
+    val pipe: CommandPipe?,
+    val bridge: LifecycleBridge?,
+    val timer: Timer?,
+    val receiver: BroadcastReceiver?,
+    val app: Application?,
+  )
+}

package/android/src/main/kotlin/io/advenue/AdvenueConfig.kt

@@ -0,0 +1,114 @@
+package io.advenue
+
+import io.advenue.core.DEFAULT_SESSION_WINDOW_MS
+import io.advenue.platform.DEFAULT_ENDPOINT
+
+/**
+ * SDK configuration. Defaults match sdk-core exactly, so an app moving from the
+ * React Native SDK gets the same behaviour without restating anything.
+ */
+public data class AdvenueConfig
+@JvmOverloads
+constructor(
+  val apiKey: String,
+  val endpoint: String = DEFAULT_ENDPOINT,
+  val appVersion: String? = null,
+  val requireConsent: Boolean = false,
+  val sessionWindowMs: Long = DEFAULT_SESSION_WINDOW_MS,
+  val batchSize: Int = 20,
+  /** Auto-flush period. Zero disables the timer, which is what tests want and no
+   *  shipping app does. */
+  val flushIntervalMs: Long = 15_000,
+  /**
+   * 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 null sends unsigned requests, which the server accepts
+   * unless the app enforces signatures.
+   */
+  val signingSecret: String? = null,
+  /** Called when the SDK swallows a best-effort failure. Never receives PII. */
+  val onError: (String, Throwable) -> Unit = { _, _ -> },
+  /**
+   * Overrides the version stamped on every event. Set by a WRAPPER SDK, never
+   * by an app.
+   *
+   * An event stamped with this 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. 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.
+   */
+  val sdkVersion: String? = null,
+  /**
+   * Meta app id from the Meta App Dashboard, enabling the Meta install
+   * referrer. Not a secret — the decryption key stays server-side and the
+   * device only ever carries ciphertext. Leave it null and no Meta content
+   * provider is queried at all.
+   *
+   * Android only: the Meta install referrer is a content-provider read, and
+   * iOS has no equivalent. A field on the Swift config would do nothing.
+   */
+  val fbAppId: String? = null,
+) {
+  /**
+   * Java-friendly builder. Kotlin's named and default arguments are invisible
+   * from Java, and both incumbents are Java-first — a Kotlin SDK that is painful
+   * from Java excludes a large share of Android apps.
+   */
+  public class Builder(private val apiKey: String) {
+    private var config = AdvenueConfig(apiKey)
+
+    public fun endpoint(value: String): Builder = apply { config = config.copy(endpoint = value) }
+
+    public fun appVersion(value: String?): Builder = apply {
+      config = config.copy(appVersion = value)
+    }
+
+    public fun requireConsent(value: Boolean): Builder = apply {
+      config = config.copy(requireConsent = value)
+    }
+
+    public fun sessionWindowMs(value: Long): Builder = apply {
+      config = config.copy(sessionWindowMs = value)
+    }
+
+    public fun batchSize(value: Int): Builder = apply { config = config.copy(batchSize = value) }
+
+    public fun flushIntervalMs(value: Long): Builder = apply {
+      config = config.copy(flushIntervalMs = value)
+    }
+
+    public fun signingSecret(value: String?): Builder = apply {
+      config = config.copy(signingSecret = value)
+    }
+
+    public fun onError(value: (String, Throwable) -> Unit): Builder = apply {
+      config = config.copy(onError = value)
+    }
+
+    public fun sdkVersion(value: String?): Builder = apply {
+      config = config.copy(sdkVersion = value)
+    }
+
+    public fun fbAppId(value: String?): Builder = apply {
+      config = config.copy(fbAppId = value)
+    }
+
+    public fun build(): AdvenueConfig = config
+  }
+}
+
+/**
+ * Stamped on every event as `sdkVersion`. An Android library has no runtime
+ * access to its own Gradle version without reflection, 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 object AdvenueVersion {
+  public const val CURRENT: String = "0.1.0"
+}

package/android/src/main/kotlin/io/advenue/core/Backoff.kt

@@ -0,0 +1,28 @@
+package io.advenue.core
+
+/**
+ * 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.
+ */
+internal class IngestError(public val status: Int) : Exception("advenue ingest failed: $status") {
+  public val isRetryable: Boolean
+    get() = 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.
+ */
+internal fun backoffDelayMs(
+  failures: Int,
+  baseMs: Double,
+  capMs: Double,
+  random: Double,
+): Double {
+  val exponential = Math.min(baseMs * Math.pow(2.0, (failures - 1).toDouble()), capMs)
+  return exponential + exponential * 0.2 * random
+}