@advenue/react-native 0.9.0 → 1.0.1

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
+}

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

@@ -0,0 +1,436 @@
+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,
+  /** B1: track properties PII scrub'u. Varsayılan-açık; yalnızca açık bayrakla
+   *  kapatılır (opt-out) ve bu dokümante risklidir. Swift EngineConfig ile aynı. */
+  val piiScrubEnabled: Boolean = true,
+)
+
+/**
+ * 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
+  /** B2: rıza bayrağı — her olaya işlenir, persist edilmez (kimlik gibi). */
+  private var limitAdTracking: Boolean? = 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
+    }
+    // B1: PII scrub (Swift PIIScrub ile aynı sözleşme).
+    val scrubbed = if (config.piiScrubEnabled) PiiScrub.scrub(properties) else properties
+    queue.enqueue(newEvent(type = type, name = name, properties = scrubbed))
+    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?) {
+    // B6: 128 üstü id tüm batch'i 400'e düşürür (ingest bütün-batch ayrıştırır).
+    // Reddet, persist etme, onError ile bildir (Limits.kt deseni).
+    if (id != null && id.length > MAX_USER_ID_LENGTH) {
+      onError("account.setUserId:id_too_long", IngestError(400))
+      return
+    }
+    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,
+    limitAdTracking: Boolean? = null,
+  ) {
+    this.gaid = gaid
+    this.androidId = androidId
+    this.appInstanceId = appInstanceId
+    this.idfa = idfa
+    this.limitAdTracking = limitAdTracking
+  }
+
+  /**
+   * 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
+    // B1: install properties de scrub kapsamındadır.
+    val scrubbed = if (config.piiScrubEnabled) PiiScrub.scrub(properties) else properties
+    queue.enqueue(newEvent(type = "install", name = "install", properties = scrubbed))
+    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,
+        // queue.clear() above persists an empty blob synchronously; remove it
+        // so erasure leaves no queue file behind either. Safe to do last:
+        // `forgotten` stops every later enqueue, so nothing rewrites it.
+        QUEUE_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,
+      limitAdTracking = limitAdTracking,
+      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()
+  }
+}