@advenue/react-native 0.8.0 → 1.0.0

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

@@ -0,0 +1,414 @@
+package io.advenue.core
+
+/**
+ * The three install-scoped keys. All of them die with the app: Android has no
+ * reinstall-durable store, so a reinstall is legitimately a new install and the
+ * Keychain asymmetry the iOS SDK relies on does not exist here.
+ */
+internal const val DEVICE_ID_KEY: String = "advenue.device_id"
+
+internal const val INSTALLATION_ID_KEY: String = "advenue.installation_id"
+
+internal const val INSTALL_SENT_KEY: String = "advenue.install_sent"
+/**
+ * The server rejects a batch of more than this: `eventBatchSchema` in
+ * `packages/shared/src/events.ts` is
+ * `z.array(clientEventSchema).min(1).max(100)`.
+ *
+ * It lives in the core rather than beside the transport because it is a fact
+ * about the wire, not about any one way of reaching it — and because the engine
+ * has to clamp to it, which the transport cannot do from where it sits.
+ */
+internal const val MAX_BATCH_SIZE: Int = 100
+
+internal const val CONSENT_KEY: String = "advenue.consent"
+internal const val CONSENT_DATA_KEY: String = "advenue.consent_data"
+internal const val USER_ID_KEY: String = "advenue.user_id"
+
+internal data class EngineConfig(
+  val apiKey: String,
+  val platform: String = "android",
+  val deviceId: String,
+  val installationId: String? = null,
+  val appVersion: String? = null,
+  val osVersion: String? = null,
+  val sdkVersion: String? = null,
+  val requireConsent: Boolean = false,
+  val sessionWindowMs: Long = DEFAULT_SESSION_WINDOW_MS,
+  val maxQueueSize: Int = 10_000,
+  val batchSize: Int = 20,
+  val retryBaseMs: Double = 1_000.0,
+  val retryCapMs: Double = 60_000.0,
+)
+
+/**
+ * Owns every piece of mutable SDK state.
+ *
+ * **Confinement, not locking.** Commands arrive through [CommandPipe] and are
+ * handled one at a time on a single thread, which reproduces sdk-core's
+ * single-threaded semantics — the property that makes the conformance vectors
+ * meaningful in the first place. This class takes no locks deliberately: a lock
+ * here would hide a confinement violation rather than prevent one.
+ */
+internal class AdvenueEngine(
+  private val config: EngineConfig,
+  private val store: KeyValueStore,
+  private val clock: Clock,
+  scheduler: Scheduler,
+  private val uuid: UuidSource,
+  private val transport: EventTransport? = null,
+  private val onDrop: (List<ClientEvent>) -> Unit = {},
+  private val random: () -> Double = { Math.random() },
+  private val onError: (String, Throwable) -> Unit = { _, _ -> },
+) {
+  private val queue = EventQueue(store, config.maxQueueSize, scheduler)
+  private val sessions =
+    SessionTracker(store, clock, config.sessionWindowMs, uuid)
+
+  private var consent: Boolean = store.getString(CONSENT_KEY) == "granted"
+  private var forgotten = false
+  private var customerUserId: String? = store.getString(USER_ID_KEY)
+  private var idfa: String? = null
+  private var gaid: String? = null
+  private var androidId: String? = null
+  private var appInstanceId: String? = null
+  private var consentData: Consent? = readConsentData()
+  private var pushToken: String? = null
+  private var pushProvider: String? = null
+  private var flushing = false
+  private var consecutiveFailures = 0
+  private var backoffUntilMs = 0L
+
+  /** Enqueues an event, or refuses it and says why. Mirrors sdk-core's `track()`. */
+  public fun track(
+    name: String,
+    properties: Map<String, Any?>? = null,
+    type: String = "custom",
+  ): Boolean {
+    if (forgotten || (config.requireConsent && !consent)) return false
+    checkTrackInput(name, properties)?.let { rejection ->
+      onError("track.rejected:$rejection", IngestError(400))
+      return false
+    }
+    queue.enqueue(newEvent(type = type, name = name, properties = properties))
+    return true
+  }
+
+  public fun setConsent(granted: Boolean) {
+    consent = granted
+    store.setString(CONSENT_KEY, if (granted) "granted" else "denied")
+  }
+
+  /**
+   * Records granular ad-platform consent. Last write wins, and it is persisted,
+   * so it survives restarts — a stated preference silently reverting on
+   * relaunch is the failure this guards.
+   */
+  internal fun setConsentData(consent: Consent?) {
+    if (forgotten) return
+    consentData = consent
+    if (consent == null) store.remove(CONSENT_DATA_KEY)
+    else store.setString(CONSENT_DATA_KEY, writeCanonicalJson(consent.toMap()))
+  }
+
+  internal fun getConsentData(): Consent? = consentData
+
+  internal fun getConsent(): Boolean = consent
+
+  /**
+   * Registers the device's push token for uninstall measurement (#26).
+   *
+   * The host app owns push registration: the SDK 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 at
+   * any time, and a stale token is the one thing that makes uninstall
+   * measurement report churn that did not happen.
+   */
+  internal fun setPushToken(token: String?, provider: String? = null) {
+    if (forgotten) return
+    if (token == null) {
+      pushToken = null
+      pushProvider = null
+      return
+    }
+    val trimmed = token.trim()
+    if (!isValidPushToken(trimmed)) {
+      pushToken = null
+      pushProvider = null
+      onError("push.setPushToken", IngestError(400))
+      return
+    }
+    pushToken = trimmed
+    pushProvider = provider ?: if (config.platform == "android") "fcm" else "apns"
+  }
+
+  private fun readConsentData(): Consent? =
+    (parseJson(store.getString(CONSENT_DATA_KEY) ?: "") as? Map<*, *>)?.let(Consent::fromMap)
+
+  public fun setUserId(id: String?) {
+    customerUserId = id
+    if (id != null) store.setString(USER_ID_KEY, id) else store.remove(USER_ID_KEY)
+  }
+
+  /**
+   * Identity attached to every subsequent event. Not persisted: it is
+   * re-resolved each launch, because the advertising id and its limit flag can
+   * both change between them.
+   */
+  public fun setIdentity(
+    gaid: String?,
+    androidId: String?,
+    appInstanceId: String?,
+    idfa: String? = null,
+  ) {
+    this.gaid = gaid
+    this.androidId = androidId
+    this.appInstanceId = appInstanceId
+    this.idfa = idfa
+  }
+
+  /**
+   * The Firebase App Instance ID alone. Separate from [setIdentity] because it
+   * arrives on its own schedule — an app can set it at any point, and folding
+   * it into the multi-field setter would clear the advertising identity the
+   * install enrichment resolved.
+   */
+  public fun setAppInstanceId(id: String?) {
+    this.appInstanceId = id
+  }
+
+  /**
+   * The first-open event, at most once per installation.
+   *
+   * Ordering is deliberate. The consent gate comes first, so a refused install
+   * leaves no flag and can still fire once consent arrives. The flag is written
+   * last, so a crash between the event and the flag costs a duplicate the
+   * backend dedup window absorbs — a permanently missing install is the worse
+   * failure.
+   */
+  public fun trackInstall(properties: Map<String, Any?>? = null): Boolean {
+    if (forgotten || (config.requireConsent && !consent)) return false
+    if (store.getString(INSTALL_SENT_KEY) == "1") return false
+    queue.enqueue(newEvent(type = "install", name = "install", properties = properties))
+    store.setString(INSTALL_SENT_KEY, "1")
+    return true
+  }
+
+  /**
+   * Erasure, including the install-scoped identifiers.
+   *
+   * They are wiped HERE rather than by the facade, and the ordering is the
+   * reason. The facade's caller runs on its own thread while the pipe may still
+   * be holding a queued `trackInstall`; a wipe performed outside the pipe races
+   * that command and the flag is written back after the erasure. Routing it
+   * through the same ordered ingress puts the wipe behind everything already
+   * submitted.
+   *
+   * The store routes these three keys to `noBackupFilesDir` — see
+   * `CompositeStore`. Clearing only the preferences half is the layering trap
+   * the spec recorded: an erasure that leaves the identifiers behind and looks
+   * finished.
+   */
+  public fun forgetMe() {
+    forgotten = true
+    queue.clear()
+    sessions.reset()
+    consent = false
+    consentData = null
+    pushToken = null
+    pushProvider = null
+    customerUserId = null
+    idfa = null
+    gaid = null
+    androidId = null
+    appInstanceId = null
+    for (key in
+      listOf(
+        CONSENT_KEY,
+        CONSENT_DATA_KEY,
+        SESSION_STATE_KEY,
+        USER_ID_KEY,
+        DEVICE_ID_KEY,
+        INSTALLATION_ID_KEY,
+        INSTALL_SENT_KEY,
+      )) {
+      store.remove(key)
+    }
+  }
+
+  public fun notifyForeground() {
+    if (forgotten || (config.requireConsent && !consent)) return
+    sessions.handleForeground().forEach { track(it.name, it.properties, type = "session") }
+  }
+
+  public fun notifyBackground() {
+    if (forgotten || (config.requireConsent && !consent)) return
+    sessions.handleBackground()?.let { track(it.name, it.properties, type = "session") }
+  }
+
+  public fun pendingEventIds(): List<String> = queue.peek(Int.MAX_VALUE).map { it.id }
+
+  /** Test surface: the ids alone cannot say what a field carries. */
+  public fun pendingEvents(): List<ClientEvent> = queue.peek(Int.MAX_VALUE)
+
+  // ---------------------------------------------------------------------------
+  // Flush.
+  //
+  // The DECISION logic below runs on the engine's thread and nowhere else; the
+  // network call is the only part that may run elsewhere. That split is why the
+  // three steps are separate methods rather than one loop: `CommandPipe` drives
+  // them across two threads so a stalled request cannot block the commands
+  // queued behind it, while `flush()` drives the same three methods inline for
+  // callers and for the vectors. One implementation of the decisions, two
+  // drivers — a second copy is exactly the drift the vectors exist to prevent.
+  // ---------------------------------------------------------------------------
+
+  private var inFlight: List<ClientEvent>? = null
+  private var isolationCursor: MutableList<ClientEvent>? = null
+
+  /** Whether a transport is wired at all. */
+  internal fun canFlush(): Boolean = transport != null
+
+  /** Decides what to send. Null means there is nothing to do. */
+  internal fun beginFlush(): List<ClientEvent>? {
+    if (transport == null || flushing || queue.size == 0 || clock.nowMs() < backoffUntilMs) {
+      return null
+    }
+    // Clamped to the wire's limit, not trusted. The server answers 400 for a
+    // larger batch and a 400 is not retryable, so an app that set 200 would
+    // have every batch rejected and then re-sent one event at a time by the
+    // poison-isolation path: nothing lost, and every flush costing 1 + N
+    // requests forever. The constant said 100 and enforced nothing until now.
+    val events = queue.peek(minOf(config.batchSize, MAX_BATCH_SIZE))
+    if (events.isEmpty()) return null
+    flushing = true
+    inFlight = events
+    return events
+  }
+
+  /**
+   * Consumes the outcome of the batch send. Returns the first event to isolate,
+   * or null when the flush is finished.
+   */
+  internal fun onBatchOutcome(error: Throwable?): ClientEvent? {
+    val events = inFlight ?: return null
+    if (error == null) {
+      queue.ack(events)
+      consecutiveFailures = 0
+      backoffUntilMs = 0L
+      endFlush()
+      return null
+    }
+
+    val ingest = error as? IngestError
+    if (ingest != null && !ingest.isRetryable) {
+      // Poison payload. Ingest parses a batch as a whole and answers one 400 for
+      // all of it, so the offender has to be found rather than the batch
+      // discarded. A 4xx is not an outage, so it does not arm the backoff.
+      onError("flush.poison", error)
+      val cursor = events.toMutableList()
+      isolationCursor = cursor
+      return cursor.removeAt(0)
+    }
+
+    // Transient (network, 5xx, 429): keep the batch and back off, so a fleet
+    // recovering from an outage does not retry in lockstep.
+    onError("flush.transport", error)
+    armBackoff()
+    endFlush()
+    return null
+  }
+
+  /**
+   * Consumes the outcome of one isolated event and returns the next, or null
+   * when isolation is over. Stops at the first transient error, so a network
+   * drop mid-isolation cannot turn deliverable events into dropped ones.
+   */
+  internal fun onSingleOutcome(event: ClientEvent, error: Throwable?): ClientEvent? {
+    if (error == null) {
+      queue.ack(listOf(event))
+    } else {
+      val ingest = error as? IngestError
+      if (ingest == null || ingest.isRetryable) {
+        endFlush()
+        return null
+      }
+      queue.ack(listOf(event))
+      onDrop(listOf(event))
+    }
+
+    val cursor = isolationCursor
+    if (cursor == null || cursor.isEmpty()) {
+      endFlush()
+      return null
+    }
+    return cursor.removeAt(0)
+  }
+
+  private fun endFlush() {
+    flushing = false
+    inFlight = null
+    isolationCursor = null
+  }
+
+  /**
+   * Inline driver: sends on the calling thread. Used by callers without a pipe
+   * and by the conformance vectors. Never throws — a timer-driven call is not
+   * awaited, so a transient failure simply leaves the batch buffered.
+   */
+  public fun flush() {
+    val batch = beginFlush() ?: return
+    var next = onBatchOutcome(send(batch))
+    while (next != null) {
+      next = onSingleOutcome(next, send(listOf(next)))
+    }
+  }
+
+  /** The single network call, returning its failure rather than throwing. */
+  internal fun send(events: List<ClientEvent>): Throwable? =
+    try {
+      transport?.send(events)
+      null
+    } catch (error: Throwable) {
+      error
+    }
+
+  private fun armBackoff() {
+    consecutiveFailures += 1
+    val delay =
+      backoffDelayMs(consecutiveFailures, config.retryBaseMs, config.retryCapMs, random())
+    backoffUntilMs = clock.nowMs() + delay.toLong()
+  }
+
+  /** Test surface: the `flush/` vectors assert that a 4xx leaves this at zero. */
+  public fun consecutiveFailureCount(): Int = consecutiveFailures
+
+  private fun newEvent(
+    type: String,
+    name: String,
+    properties: Map<String, Any?>?,
+  ): ClientEvent =
+    ClientEvent(
+      id = uuid.next(),
+      deviceId = config.deviceId,
+      type = type,
+      name = name,
+      timestamp = iso8601(clock.nowMs()),
+      platform = config.platform,
+      installationId = config.installationId,
+      appVersion = config.appVersion,
+      osVersion = config.osVersion,
+      sdkVersion = config.sdkVersion,
+      customerUserId = customerUserId,
+      idfa = idfa,
+      gaid = gaid,
+      androidId = androidId,
+      appInstanceId = appInstanceId,
+      consent = consentData?.toMap(),
+      // Lifecycle events only. A push token is ~180 bytes and the registry
+      // needs it periodically, not on every custom event in a 100-event batch.
+      pushToken = if (type == "install" || type == "session") pushToken else null,
+      pushProvider = if (type == "install" || type == "session") pushProvider else null,
+      properties = properties,
+    )
+}

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

@@ -0,0 +1,89 @@
+package io.advenue.core
+
+internal const val QUEUE_KEY: String = "advenue.queue"
+
+/** Persist debounce window. Bursts inside it coalesce into one write. */
+internal const val PERSIST_DEBOUNCE_MS: Int = 100
+
+/**
+ * Durable FIFO event buffer, mirroring sdk-core's `EventQueue` including its
+ * persisted blob shape — the RN inversion has to read what TypeScript wrote.
+ *
+ * Persist strategy: `enqueue` debounces so a burst costs one write; `ack` and
+ * `clear` are flush boundaries and write synchronously, because stale storage
+ * at those points means event loss on ack or a double send after a crash.
+ *
+ * Confined to the engine's single thread. Not thread-safe, and deliberately so:
+ * a lock here would hide a confinement mistake rather than prevent one.
+ */
+internal class EventQueue(
+  private val store: KeyValueStore,
+  private val maxSize: Int = 10_000,
+  private val scheduler: Scheduler,
+) {
+  private val events: MutableList<ClientEvent> = load(store).toMutableList()
+  private var persistToken: CancelToken? = null
+
+  public val size: Int
+    get() = events.size
+
+  public fun enqueue(event: ClientEvent) {
+    events.add(event)
+    // Bound the buffer: a long offline period on a chatty app must not grow the
+    // persisted blob without limit. Recent events are the ones worth keeping.
+    while (events.size > maxSize) events.removeAt(0)
+    schedulePersist()
+  }
+
+  public fun peek(max: Int): List<ClientEvent> = events.take(max)
+
+  public fun ack(sent: List<ClientEvent>) {
+    if (sent.isEmpty()) return
+    val ids = sent.map { it.id }.toHashSet()
+    events.removeAll { it.id in ids }
+    forcePersist()
+  }
+
+  public fun clear() {
+    events.clear()
+    forcePersist()
+  }
+
+  private fun schedulePersist() {
+    if (persistToken != null) return
+    persistToken =
+      scheduler.schedule(PERSIST_DEBOUNCE_MS) {
+        persistToken = null
+        write()
+      }
+  }
+
+  private fun forcePersist() {
+    persistToken?.let {
+      scheduler.cancel(it)
+      persistToken = null
+    }
+    write()
+  }
+
+  private fun write() {
+    try {
+      store.setString(QUEUE_KEY, writeCanonicalJson(events.map { it.toMap() }))
+    } catch (_: Exception) {
+      // A failed write costs the offline buffer, not the process. The in-memory
+      // list stays authoritative for this launch.
+    }
+  }
+
+  private companion object {
+    /**
+     * A corrupt blob loads as empty rather than throwing: bricking the SDK on
+     * every launch is worse than losing an offline buffer.
+     */
+    private fun load(store: KeyValueStore): List<ClientEvent> {
+      val raw = store.getString(QUEUE_KEY) ?: return emptyList()
+      val parsed = parseJson(raw) as? List<*> ?: return emptyList()
+      return parsed.mapNotNull { (it as? Map<*, *>)?.let(ClientEvent::fromMap) }
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+package io.advenue.core
+
+import javax.crypto.Mac
+import javax.crypto.spec.SecretKeySpec
+
+/**
+ * Production signing. `javax.crypto` is part of every JDK and every Android
+ * runtime, so unlike the Swift port — where `AdvenueCore` had to stay free of a
+ * crypto library to build on Linux — the core can own this outright. One HMAC
+ * implementation, not two.
+ */
+internal class JvmHmacSigner : Signer {
+  override fun hmacSha256Hex(secret: String, message: String): String {
+    val mac = Mac.getInstance("HmacSHA256")
+    mac.init(SecretKeySpec(secret.toByteArray(Charsets.UTF_8), "HmacSHA256"))
+    // UTF-8, not UTF-16: TextEncoder in the TypeScript original encodes UTF-8,
+    // and a port hashing UTF-16 code units would agree on every ASCII body and
+    // diverge on exactly the ones with emoji in them.
+    val digest = mac.doFinal(message.toByteArray(Charsets.UTF_8))
+    val out = StringBuilder(digest.size * 2)
+    for (byte in digest) {
+      out.append(HEX[(byte.toInt() shr 4) and 0xF])
+      out.append(HEX[byte.toInt() and 0xF])
+    }
+    return out.toString()
+  }
+
+  private companion object {
+    private val HEX = "0123456789abcdef".toCharArray()
+  }
+}

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

@@ -0,0 +1,146 @@
+package io.advenue.core
+
+import java.net.URLDecoder
+
+/**
+ * A parsed Play Install Referrer. Ported field for field from
+ * `packages/install-referrer/src/index.ts`, which is the authority — the server
+ * attributes on these names.
+ */
+internal data class ParsedReferrer(
+  val network: String?,
+  val source: String?,
+  val medium: String?,
+  val campaign: String?,
+  val content: String?,
+  val term: String?,
+  /** Google click id (paid Google/UAC). */
+  val gclid: String?,
+  /** Meta/Facebook click id. */
+  val fbclid: String?,
+  /** Full decoded key/value map, for anything non-standard. */
+  val params: Map<String, String>,
+  val raw: String,
+)
+
+private val SOURCE_NETWORK =
+  mapOf(
+    "google" to "google",
+    "google-play" to "google",
+    "googleads" to "google",
+    "google-ads" to "google",
+    "adwords" to "google",
+    "uac" to "google",
+    "admob" to "admob",
+    "facebook" to "meta",
+    "facebook-ads" to "meta",
+    "fb" to "meta",
+    "instagram" to "meta",
+    "ig" to "meta",
+    "meta" to "meta",
+    "meta-ads" to "meta",
+    "tiktok" to "tiktok",
+    "tiktok-ads" to "tiktok",
+    "tiktokads" to "tiktok",
+    "apple-search-ads" to "apple",
+    "apple_search_ads" to "apple",
+    "apple-ads" to "apple",
+    "asa" to "apple",
+    "snapchat" to "snapchat",
+    "x" to "x",
+    "twitter" to "x",
+    "youtube" to "youtube",
+  )
+
+/**
+ * Parses a Play Install Referrer string (or any utm-tagged referrer) into
+ * normalised attribution params.
+ */
+internal fun parseInstallReferrer(raw: String): ParsedReferrer {
+  // A fully percent-encoded referrer has no literal '='; decode it once first.
+  // An already-decoded referrer keeps its '=' and is decoded per key/value
+  // below — decoding the whole string would turn an encoded '&' or '=' inside a
+  // value into a false separator.
+  val decoded = if (raw.contains('=')) raw else safeDecode(raw)
+
+  val params = LinkedHashMap<String, String>()
+  for (pair in decoded.split('&')) {
+    if (pair.isEmpty()) continue
+    val eq = pair.indexOf('=')
+    val key = if (eq >= 0) pair.substring(0, eq) else pair
+    val value = if (eq >= 0) pair.substring(eq + 1) else ""
+    if (key.isNotEmpty()) params[safeDecode(key)] = safeDecode(value.replace("+", " "))
+  }
+
+  return ParsedReferrer(
+    network = inferNetwork(params),
+    source = params["utm_source"],
+    medium = params["utm_medium"],
+    campaign = params["utm_campaign"] ?: params["campaign"],
+    content = params["utm_content"],
+    term = params["utm_term"],
+    gclid = params["gclid"],
+    fbclid = params["fbclid"],
+    params = params,
+    raw = raw,
+  )
+}
+
+private fun inferNetwork(params: Map<String, String>): String? {
+  if (params["gclid"] != null) return "google"
+  val source = params["utm_source"]?.trim()?.lowercase()
+  if (source.isNullOrEmpty()) return null
+
+  // The Play Store's DEFAULT referrer for an organic install is
+  // "utm_source=google-play&utm_medium=organic" — the store itself, not Google
+  // Ads. Without a paid click id (gclid, above) or a paid medium these MUST
+  // stay organic, or every organic Android install is credited to paid Google.
+  // That is a financial misattribution, not a reporting nuance.
+  val medium = params["utm_medium"]?.trim()?.lowercase()
+  if (medium == "organic") return null
+  if ((source == "google-play" || source == "com.android.vending") && medium.isNullOrEmpty()) {
+    return null
+  }
+
+  // Exact token match against known networks; anything else passes through as
+  // its own lower-cased key. An unknown utm_source is a real source, it just is
+  // not one we can canonicalise.
+  return SOURCE_NETWORK[source] ?: source
+}
+
+/**
+ * The referrer fields that ride the install event.
+ *
+ * Device-clock values always travel under the client-trust keys. The
+ * server-trusted keys are populated **only** from Play's genuine server-clock
+ * getters and only when non-zero, because Play returns 0 for an unverified
+ * install. Aliasing a device clock into a server key would hand the fraud
+ * scorer a trust signal the device could forge.
+ */
+internal fun referrerProperties(
+  referrer: String,
+  clickTimestamp: Long,
+  installTimestamp: Long,
+  clickServerTimestamp: Long,
+  installServerTimestamp: Long,
+  googlePlayInstant: Boolean,
+): Map<String, Any?> {
+  val props =
+    linkedMapOf<String, Any?>(
+      "installReferrer" to referrer,
+      "referrerClickTimestamp" to clickTimestamp,
+      "installBeginTimestamp" to installTimestamp,
+      "googlePlayInstant" to googlePlayInstant,
+    )
+  if (clickServerTimestamp != 0L) props["referrerClickServerTimestamp"] = clickServerTimestamp
+  if (installServerTimestamp != 0L) props["installBeginServerTimestamp"] = installServerTimestamp
+  return props
+}
+
+private fun safeDecode(value: String): String =
+  try {
+    URLDecoder.decode(value, "UTF-8")
+  } catch (_: Exception) {
+    // A malformed escape must cost the decoding, not the install.
+    value
+  }