@advenue/react-native 0.9.0 → 1.0.0

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

@@ -0,0 +1,136 @@
+package io.advenue.core
+
+/**
+ * The wire envelope, mirroring `clientEventSchema` in
+ * `packages/shared/src/events.ts` and `ClientEvent` in the Swift port.
+ *
+ * Every optional is genuinely optional on the wire: the server uses zod
+ * `.optional()`, which accepts a missing key and **rejects** an explicit
+ * `null`. [writeCanonicalJson] omits null object entries, which is exactly the
+ * behaviour required — a serialiser emitting `null` would 400 the whole batch,
+ * every event in it.
+ */
+internal data class ClientEvent(
+  public val id: String,
+  public val deviceId: String,
+  public val type: String,
+  public val name: String,
+  public val timestamp: String,
+  public val platform: String,
+  public val installationId: String? = null,
+  public val osVersion: String? = null,
+  public val appVersion: String? = null,
+  public val sdkVersion: String? = null,
+  public val network: String? = null,
+  public val campaign: String? = null,
+  public val country: String? = null,
+  public val idfa: String? = null,
+  public val gaid: String? = null,
+  public val limitAdTracking: Boolean? = null,
+  public val vendorId: String? = null,
+  public val androidId: String? = null,
+  public val customerUserId: String? = null,
+  public val appInstanceId: String? = null,
+  public val consent: Map<String, Any?>? = null,
+  public val properties: Map<String, Any?>? = null,
+  public val pushToken: String? = null,
+  public val pushProvider: String? = null,
+  public val attestationToken: String? = null,
+  public val attestationType: String? = null,
+  public val attestationChallenge: String? = null,
+  public val adservicesToken: String? = null,
+) {
+  internal fun toMap(): Map<String, Any?> =
+    mapOf(
+      "id" to id,
+      "deviceId" to deviceId,
+      "type" to type,
+      "name" to name,
+      "timestamp" to timestamp,
+      "platform" to platform,
+      "installationId" to installationId,
+      "osVersion" to osVersion,
+      "appVersion" to appVersion,
+      "sdkVersion" to sdkVersion,
+      "network" to network,
+      "campaign" to campaign,
+      "country" to country,
+      "idfa" to idfa,
+      "gaid" to gaid,
+      "limitAdTracking" to limitAdTracking,
+      "vendorId" to vendorId,
+      "androidId" to androidId,
+      "customerUserId" to customerUserId,
+      "appInstanceId" to appInstanceId,
+      "consent" to consent,
+      "properties" to properties,
+      "pushToken" to pushToken,
+      "pushProvider" to pushProvider,
+      "attestationToken" to attestationToken,
+      "attestationType" to attestationType,
+      "attestationChallenge" to attestationChallenge,
+      "adservicesToken" to adservicesToken,
+    )
+
+  /** The exact bytes this event puts on the wire. */
+  public fun encodeCanonical(): String = writeCanonicalJson(toMap())
+
+  public companion object {
+    /**
+     * The queue's reload path — and `properties` is restored with everything
+     * else, which it was not.
+     *
+     * It used to be dropped, on the premise that "a reloaded event is only ever
+     * re-sent as the bytes already written". The bytes are not re-sent: the
+     * object is. `EventQueue` assigns `events = load(store)` and `peek()`
+     * returns from `events`, so a reloaded event is exactly what the transport
+     * re-encodes. An app killed before flushing therefore sent every buffered
+     * event with no payload — no revenue, no currency, no sku. The writer had
+     * always written them; only this refused to read them.
+     *
+     * A queue conformance vector now pins it in both SDKs at once.
+     */
+    internal fun fromMap(map: Map<*, *>): ClientEvent? {
+      fun str(key: String): String? = map[key] as? String
+      val id = str("id") ?: return null
+      val deviceId = str("deviceId") ?: return null
+      val type = str("type") ?: return null
+      val name = str("name") ?: return null
+      val timestamp = str("timestamp") ?: return null
+      val platform = str("platform") ?: return null
+      return ClientEvent(
+        id = id,
+        deviceId = deviceId,
+        type = type,
+        name = name,
+        timestamp = timestamp,
+        platform = platform,
+        installationId = str("installationId"),
+        osVersion = str("osVersion"),
+        appVersion = str("appVersion"),
+        sdkVersion = str("sdkVersion"),
+        network = str("network"),
+        campaign = str("campaign"),
+        country = str("country"),
+        idfa = str("idfa"),
+        gaid = str("gaid"),
+        limitAdTracking = map["limitAdTracking"] as? Boolean,
+        vendorId = str("vendorId"),
+        androidId = str("androidId"),
+        customerUserId = str("customerUserId"),
+        appInstanceId = str("appInstanceId"),
+        // parseJson already yields the nested Map/List shape this field holds,
+        // so there is nothing to convert — only to stop discarding.
+        properties = (map["properties"] as? Map<*, *>)?.entries?.associate {
+          (it.key as String) to it.value
+        },
+        pushToken = str("pushToken"),
+        pushProvider = str("pushProvider"),
+        attestationToken = str("attestationToken"),
+        attestationType = str("attestationType"),
+        attestationChallenge = str("attestationChallenge"),
+        adservicesToken = str("adservicesToken"),
+      )
+    }
+  }
+}

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

@@ -0,0 +1,186 @@
+package io.advenue.core
+
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.atomic.AtomicBoolean
+
+/** A command submitted to the engine through the ordered ingress. */
+internal sealed class Command {
+  public data class Track(
+    val name: String,
+    val properties: Map<String, Any?>?,
+    val type: String,
+  ) : Command()
+
+  public data class SetConsent(val granted: Boolean) : Command()
+
+  public data class SetUserId(val id: String?) : Command()
+
+  public data class SetIdentity(
+    val gaid: String?,
+    val androidId: String?,
+    val appInstanceId: String?,
+  ) : Command()
+
+  internal data class SetAppInstanceId(val id: String?) : Command()
+
+  public data class TrackInstall(val properties: Map<String, Any?>?) : Command()
+
+  internal data class SetConsentData(val consent: Consent?) : Command()
+
+  internal data class SetPushToken(val token: String?, val provider: String?) : Command()
+
+  public object ForgetMe : Command()
+
+  public object Foreground : Command()
+
+  public object Background : Command()
+
+  public object Flush : Command()
+
+  /** Posted back by the io thread; carries what the network said. */
+  internal data class BatchOutcome(val error: Throwable?) : Command()
+
+  internal data class SingleOutcome(val event: ClientEvent, val error: Throwable?) : Command()
+
+  /** Deferred work hopped back onto the engine's thread — see TimerScheduler. */
+  internal data class RunScheduled(val work: () -> Unit) : Command()
+
+  internal object Shutdown : Command()
+}
+
+/**
+ * The ordered ingress: a synchronous, non-blocking [submit] feeding one
+ * consumer thread.
+ *
+ * Why a queue and not a thread per call: a thread pool does not preserve
+ * submission order, so an event could overtake its own `session_start` and be
+ * attributed to the wrong session. Adding to a `LinkedBlockingQueue` is
+ * non-blocking and ordered, which is exactly the property `AsyncStream.yield`
+ * gives the Swift port.
+ *
+ * **Two threads, on purpose.** `advenue-core` owns all state; `advenue-io`
+ * performs the transport call. In Swift, `flush` awaited inside an actor and
+ * reentrancy let other work proceed. A single blocking thread has no such
+ * property: a 15-second HTTP timeout would block every lifecycle command queued
+ * behind it.
+ */
+internal class CommandPipe(
+  private val engine: AdvenueEngine,
+  private val onError: (String, Throwable) -> Unit = { _, _ -> },
+) {
+  /** A send the io thread must perform, and the events it covers. */
+  private class Send(val events: List<ClientEvent>, val single: ClientEvent?)
+
+  private val commands = LinkedBlockingQueue<Command>()
+  private val sends = LinkedBlockingQueue<Send>()
+  private val running = AtomicBoolean(true)
+
+  private val core =
+    thread("advenue-core") {
+      while (running.get()) {
+        val command = commands.take()
+        if (command === Command.Shutdown) break
+        // Each command is handled inside its own try/catch. An uncaught throw
+        // would END this thread: the queue would stop draining, submit() would
+        // keep accepting, nothing would send, nothing would error, and the app
+        // would not crash — attribution would simply stop. Silent total failure
+        // is the worst mode available, so this loop must be unkillable.
+        try {
+          handle(command)
+        } catch (error: Throwable) {
+          onError("engine.command", error)
+        }
+      }
+    }
+
+  /**
+   * Performs network calls and nothing else. It never touches engine state: the
+   * decision of what to send and what to do with the answer stays on the core
+   * thread, which is what keeps the queue confined to one thread while still
+   * letting a 15-second request run without blocking anything.
+   */
+  private val io =
+    thread("advenue-io") {
+      while (running.get()) {
+        val send = sends.take()
+        if (!running.get()) break
+        val error = engine.send(send.events)
+        commands.put(
+          if (send.single != null) {
+            Command.SingleOutcome(send.single, error)
+          } else {
+            Command.BatchOutcome(error)
+          },
+        )
+      }
+    }
+
+  private fun handle(command: Command) {
+    when (command) {
+      is Command.Track -> engine.track(command.name, command.properties, command.type)
+      is Command.SetConsent -> engine.setConsent(command.granted)
+      is Command.SetUserId -> engine.setUserId(command.id)
+      is Command.SetIdentity ->
+        engine.setIdentity(command.gaid, command.androidId, command.appInstanceId)
+      is Command.SetAppInstanceId -> engine.setAppInstanceId(command.id)
+      is Command.TrackInstall -> engine.trackInstall(command.properties)
+      is Command.SetConsentData -> engine.setConsentData(command.consent)
+      is Command.SetPushToken -> engine.setPushToken(command.token, command.provider)
+      Command.ForgetMe -> engine.forgetMe()
+      Command.Foreground -> engine.notifyForeground()
+      Command.Background -> engine.notifyBackground()
+      Command.Flush -> engine.beginFlush()?.let { sends.put(Send(it, single = null)) }
+      is Command.BatchOutcome ->
+        engine.onBatchOutcome(command.error)?.let { sends.put(Send(listOf(it), single = it)) }
+      is Command.SingleOutcome ->
+        engine.onSingleOutcome(command.event, command.error)?.let {
+          sends.put(Send(listOf(it), single = it))
+        }
+      is Command.RunScheduled -> command.work()
+      Command.Shutdown -> Unit
+    }
+  }
+
+  /**
+   * Synchronous, non-blocking and **ordered** — the entire reason the ingress
+   * is a queue.
+   */
+  public fun submit(command: Command) {
+    if (!running.get()) return
+    commands.put(command)
+  }
+
+  public fun shutdown() {
+    if (!running.compareAndSet(true, false)) return
+    commands.put(Command.Shutdown)
+    sends.put(Send(emptyList(), single = null))
+  }
+
+  /** Test surface: block until both queues are empty or the deadline passes. */
+  internal fun drain(timeoutMs: Long = 2_000) {
+    val deadline = System.currentTimeMillis() + timeoutMs
+    while (
+      (commands.isNotEmpty() || sends.isNotEmpty()) && System.currentTimeMillis() < deadline
+    ) {
+      Thread.sleep(5)
+    }
+    Thread.sleep(20)
+  }
+
+  private fun thread(name: String, body: () -> Unit): Thread =
+    Thread(
+        {
+          try {
+            body()
+          } catch (_: InterruptedException) {
+            // shutdown
+          }
+        },
+        name,
+      )
+      .apply {
+        // Daemon: the SDK must never hold a process open.
+        isDaemon = true
+        start()
+      }
+}

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

@@ -0,0 +1,52 @@
+package io.advenue.core
+
+/**
+ * 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 canonical writer omits nulls, which is what
+ * keeps the distinction on the wire.
+ */
+// Public because the facade both takes and returns it: an app that calls
+// setConsentData must be able to read back what it set, and the iOS SDK's
+// Consent is public for the same reason.
+public data class Consent(
+  val isUserSubjectToGDPR: Boolean,
+  val hasConsentForDataUsage: Boolean? = null,
+  val hasConsentForAdsPersonalization: Boolean? = null,
+  val hasConsentForAdStorage: Boolean? = null,
+) {
+  internal fun toMap(): Map<String, Any?> =
+    mapOf(
+      "isUserSubjectToGDPR" to isUserSubjectToGDPR,
+      "hasConsentForDataUsage" to hasConsentForDataUsage,
+      "hasConsentForAdsPersonalization" to hasConsentForAdsPersonalization,
+      "hasConsentForAdStorage" to hasConsentForAdStorage,
+    )
+
+  internal companion object {
+    internal fun fromMap(map: Map<*, *>): Consent? {
+      val gdpr = map["isUserSubjectToGDPR"] as? Boolean ?: return null
+      return Consent(
+        isUserSubjectToGDPR = gdpr,
+        hasConsentForDataUsage = map["hasConsentForDataUsage"] as? Boolean,
+        hasConsentForAdsPersonalization = map["hasConsentForAdsPersonalization"] as? Boolean,
+        hasConsentForAdStorage = map["hasConsentForAdStorage"] as? Boolean,
+      )
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+internal fun isValidPushToken(token: String): Boolean =
+  token.isNotEmpty() && token.length <= 512 && token.all { it.isLetterOrDigit() || it in "_:.-" }

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

@@ -0,0 +1,80 @@
+package io.advenue.core
+
+/**
+ * Synchronous key/value storage. On Android this is a `SharedPreferences` file;
+ * in tests it is a map. Mirrors `StorageAdapter` in sdk-core and `KeyValueStore`
+ * in the Swift port.
+ */
+internal interface KeyValueStore {
+  public fun getString(key: String): String?
+
+  public fun setString(key: String, value: String)
+
+  public fun remove(key: String)
+}
+
+/** Milliseconds since the Unix epoch. Injected so vectors are deterministic. */
+internal interface Clock {
+  public fun nowMs(): Long
+}
+
+/** Opaque handle returned by [Scheduler.schedule]. */
+internal typealias CancelToken = Long
+
+/**
+ * Deferred execution, injected so the queue's persist debounce is observable
+ * without waiting for it.
+ *
+ * **Isolation contract.** The scheduled work touches state confined to the
+ * engine's thread, so an implementation must run it on that same thread. The
+ * production scheduler satisfies this by posting back onto the command pipe;
+ * the test scheduler satisfies it by running inline.
+ */
+internal interface Scheduler {
+  public fun schedule(afterMs: Int, work: () -> Unit): CancelToken
+
+  public fun cancel(token: CancelToken)
+}
+
+/** Event, session and device id source. Injected for the same reason. */
+internal interface UuidSource {
+  public fun next(): String
+}
+
+/**
+ * HMAC-SHA256. An interface rather than a bare function so tests can pin the
+ * digest, but unlike the Swift port there is only ever one implementation:
+ * `javax.crypto` is in every JDK and every Android runtime, so the core can own
+ * it without taking a dependency.
+ */
+internal interface Signer {
+  /** Lowercase hex digest of [message] under [secret], both UTF-8. */
+  public fun hmacSha256Hex(secret: String, message: String): 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.
+ */
+internal fun signRequest(
+  signer: Signer,
+  secret: String,
+  timestamp: String,
+  body: String,
+): String = signer.hmacSha256Hex(secret, "$timestamp.$body")
+
+/**
+ * What the core needs from a transport, and no more.
+ *
+ * Declared in the core rather than the platform layer because the flush loop is
+ * behaviour the `flush/` conformance vectors bind, and a rule the vectors cannot
+ * reach is a rule three implementations can each interpret differently.
+ */
+internal interface EventTransport {
+  /**
+   * Delivers one batch. Throws [IngestError] on a non-2xx response, and on a
+   * transport failure, which maps to 408.
+   */
+  public fun send(events: List<ClientEvent>)
+}

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

@@ -0,0 +1,69 @@
+package io.advenue.core
+
+/**
+ * Deferred deep linking: the install that came from a link carrying a
+ * destination, where the destination has to survive the trip through the store.
+ *
+ * The device asks the server what it was attributed to. An organic install is
+ * never attributed, so the lookup is *expected* to come back pending forever for
+ * most devices — which is why the loop gives up rather than polling on.
+ */
+public data class DeepLink(
+  val deepLinkValue: String? = null,
+  val campaign: String? = null,
+  val network: String? = null,
+  val influencerId: String? = null,
+  val params: Map<String, Any?>? = null,
+  val isDeferred: Boolean = true,
+  val isFirstLaunch: Boolean = true,
+)
+
+/** What a lookup returned: still deciding, decided, or refused. */
+public sealed class ConversionResult {
+  public object Pending : ConversionResult()
+
+  public data class Resolved(val link: DeepLink) : ConversionResult()
+}
+
+public interface ConversionFetcher {
+  /** Throws [IngestError] on a non-2xx; [IngestError.isRetryable] decides. */
+  public fun fetch(): ConversionResult
+}
+
+/** Copied from `packages/sdk-core/src/conversion.ts`, not chosen here. */
+public val DEFAULT_CONVERSION_BACKOFF_MS: List<Long> = listOf(500L, 1_000L, 2_000L, 4_000L)
+
+/**
+ * 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 it 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 fun resolveDeferredDeepLink(
+  fetcher: ConversionFetcher,
+  maxAttempts: Int = 5,
+  backoffMs: List<Long> = DEFAULT_CONVERSION_BACKOFF_MS,
+  sleep: (Long) -> Unit = { Thread.sleep(it) },
+): DeepLink? {
+  for (attempt in 0 until maxAttempts) {
+    try {
+      when (val result = fetcher.fetch()) {
+        is ConversionResult.Resolved -> return result.link
+        ConversionResult.Pending -> Unit
+      }
+    } catch (error: Throwable) {
+      val ingest = error as? IngestError
+      if (ingest != null && !ingest.isRetryable) return null
+      // Retryable, or a transport failure: fall through to the backoff.
+    }
+
+    if (attempt < maxAttempts - 1) {
+      sleep(backoffMs.getOrElse(attempt) { backoffMs.lastOrNull() ?: 0L })
+    }
+  }
+  return null
+}