@advenue/react-native 0.9.0 → 1.0.1

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

@@ -0,0 +1,141 @@
+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,
+  /** Ignored: the SDK reads the app version from the package itself. Setting it reports `config.ignored:appVersion` through [onError]. Removed in the next major. */
+  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,
+  /**
+   * B1: track properties PII scrub'u. Varsayılan-açık; yalnızca açıkça
+   * kapatın (dokümante risk — ham PII ingest'e gider). Swift ile aynı.
+   */
+  val piiScrubEnabled: Boolean = true,
+  /**
+   * B5: testler için `http://` izni. Üretimde kapalı tutun — açık `http://`
+   * API anahtarı dahil tüm olayları şifresiz taşır.
+   */
+  val allowInsecureHttp: Boolean = false,
+) {
+  init {
+    // B5: şemasız endpoint fail-fast — geçersiz şema transportta değil,
+    // kurulumda yakalanır.
+    require(allowInsecureHttp || endpoint.startsWith("https://")) {
+      "Advenue endpoint must use https:// (set allowInsecureHttp only for tests)"
+    }
+  }
+  /**
+   * 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) }
+
+    /** Ignored — see [AdvenueConfig.appVersion]. */
+    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 piiScrubEnabled(value: Boolean): Builder = apply {
+      config = config.copy(piiScrubEnabled = value)
+    }
+
+    public fun allowInsecureHttp(value: Boolean): Builder = apply {
+      config = config.copy(allowInsecureHttp = 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
+}

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,193 @@
+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?,
+    /** B2: reklam kimliği rıza bayrağı — toplanıp düşürülüyordu. */
+    val limitAdTracking: Boolean? = null,
+  ) : 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,
+          limitAdTracking = command.limitAdTracking,
+        )
+      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>)
+}