@advenue/react-native 0.9.0 → 1.0.1

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

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

@@ -0,0 +1,272 @@
+package io.advenue.core
+
+/**
+ * Canonical JSON, written by hand.
+ *
+ * Three reasons, each sufficient on its own. `org.json` is a stub in JVM unit
+ * tests — calling it throws unless the test is mocked or run under Robolectric.
+ * Gson, Moshi and kotlinx.serialization are each a dependency an SDK would push
+ * into the host app's version resolution, and kotlinx.serialization is also a
+ * compiler plugin. And none of the three guarantees key order, which the
+ * byte-exact `envelope/` conformance vectors require.
+ *
+ * A fourth reason emerged from writing it: no reflection, so consumers need no
+ * `keep` rules for model classes. Gson or Moshi would push those rules into
+ * every consumer's build.
+ */
+
+/**
+ * Serialises [value] with sorted object keys, omitting null object entries.
+ *
+ * Accepted types are String, Boolean, Int, Long, Double, List and Map with
+ * String keys. Anything else throws, rather than being coerced to something
+ * plausible: a silently mangled property is worse than a rejected event,
+ * because it reaches the warehouse looking correct.
+ */
+internal fun writeCanonicalJson(value: Any?): String {
+  val out = StringBuilder()
+  writeValue(value, out)
+  return out.toString()
+}
+
+private fun writeValue(value: Any?, out: StringBuilder) {
+  when (value) {
+    null -> out.append("null")
+    is String -> writeString(value, out)
+    is Boolean -> out.append(if (value) "true" else "false")
+    is Int -> out.append(value.toString())
+    is Long -> out.append(value.toString())
+    is Double -> out.append(formatDouble(value))
+    is Float -> out.append(formatDouble(value.toDouble()))
+    is Map<*, *> -> writeObject(value, out)
+    is List<*> -> {
+      out.append('[')
+      value.forEachIndexed { index, element ->
+        if (index > 0) out.append(',')
+        // A null inside an ARRAY has no key to omit, so it is serialised.
+        writeValue(element, out)
+      }
+      out.append(']')
+    }
+    else -> throw IllegalArgumentException(
+      "unencodable JSON value: ${value::class.java.simpleName}",
+    )
+  }
+}
+
+private fun writeObject(map: Map<*, *>, out: StringBuilder) {
+  out.append('{')
+  var first = true
+  // Sorted so output is byte-comparable with the conformance vectors and with
+  // what Swift's .sortedKeys and the TypeScript snapshots produce.
+  val keys = map.keys.map { it as? String ?: throw IllegalArgumentException("non-string JSON key") }
+  for (key in keys.sorted()) {
+    val entry = map[key]
+    // zod .optional() accepts a missing key and rejects an explicit null.
+    if (entry == null) continue
+    if (!first) out.append(',')
+    first = false
+    writeString(key, out)
+    out.append(':')
+    writeValue(entry, out)
+  }
+  out.append('}')
+}
+
+/**
+ * `JSON.stringify` prints an integral number without a decimal point: `1`, not
+ * `1.0`. Below 2^53 a double is exactly integral or it is not, so the check is
+ * safe; above it the plain representation is used, as JavaScript does.
+ */
+private fun formatDouble(value: Double): String {
+  if (!value.isFinite()) throw IllegalArgumentException("non-finite JSON number: $value")
+  if (value == Math.floor(value) && Math.abs(value) < 9_007_199_254_740_992.0) {
+    return value.toLong().toString()
+  }
+  return value.toString()
+}
+
+private fun writeString(value: String, out: StringBuilder) {
+  out.append('"')
+  for (char in value) {
+    when (char) {
+      '"' -> out.append("\\\"")
+      '\\' -> out.append("\\\\")
+      '\b' -> out.append("\\b")
+      '\n' -> out.append("\\n")
+      '\r' -> out.append("\\r")
+      '\t' -> out.append("\\t")
+      '\u000C' -> out.append("\\f")
+      // A forward slash is NOT escaped: JSON.stringify leaves it, and Swift is
+      // configured with .withoutEscapingSlashes to match.
+      else ->
+        if (char < ' ') {
+          out.append(String.format("\\u%04x", char.code))
+        } else {
+          out.append(char)
+        }
+    }
+  }
+  out.append('"')
+}
+
+/**
+ * Parses JSON into Map/List/String/Boolean/Long/Double/null.
+ *
+ * Returns null on malformed input rather than throwing. This only ever reads
+ * data the SDK itself wrote — the persisted queue and session blobs — plus one
+ * diagnostic field from an ingest response, and a corrupt blob must cost the
+ * offline buffer rather than brick the SDK on every launch.
+ */
+internal fun parseJson(text: String): Any? =
+  try {
+    val parser = JsonParser(text)
+    val value = parser.parseValue()
+    parser.skipWhitespace()
+    if (!parser.atEnd()) null else value
+  } catch (_: Exception) {
+    null
+  }
+
+private class JsonParser(private val text: String) {
+  private var index = 0
+
+  fun atEnd(): Boolean = index >= text.length
+
+  fun skipWhitespace() {
+    while (index < text.length && text[index].isWhitespace()) index++
+  }
+
+  fun parseValue(): Any? {
+    skipWhitespace()
+    if (atEnd()) throw IllegalStateException("unexpected end")
+    return when (text[index]) {
+      '{' -> parseObject()
+      '[' -> parseArray()
+      '"' -> parseString()
+      't' -> literal("true", true)
+      'f' -> literal("false", false)
+      'n' -> literal("null", null)
+      else -> parseNumber()
+    }
+  }
+
+  private fun literal(token: String, value: Any?): Any? {
+    if (!text.startsWith(token, index)) throw IllegalStateException("bad literal")
+    index += token.length
+    return value
+  }
+
+  private fun parseObject(): Map<String, Any?> {
+    index++ // {
+    val result = LinkedHashMap<String, Any?>()
+    skipWhitespace()
+    if (text[index] == '}') {
+      index++
+      return result
+    }
+    while (true) {
+      skipWhitespace()
+      val key = parseString()
+      skipWhitespace()
+      if (text[index] != ':') throw IllegalStateException("expected :")
+      index++
+      result[key] = parseValue()
+      skipWhitespace()
+      when (text[index]) {
+        ',' -> index++
+        '}' -> {
+          index++
+          return result
+        }
+        else -> throw IllegalStateException("expected , or }")
+      }
+    }
+  }
+
+  private fun parseArray(): List<Any?> {
+    index++ // [
+    val result = ArrayList<Any?>()
+    skipWhitespace()
+    if (text[index] == ']') {
+      index++
+      return result
+    }
+    while (true) {
+      result.add(parseValue())
+      skipWhitespace()
+      when (text[index]) {
+        ',' -> index++
+        ']' -> {
+          index++
+          return result
+        }
+        else -> throw IllegalStateException("expected , or ]")
+      }
+    }
+  }
+
+  private fun parseString(): String {
+    if (text[index] != '"') throw IllegalStateException("expected string")
+    index++
+    val out = StringBuilder()
+    while (true) {
+      val char = text[index]
+      when {
+        char == '"' -> {
+          index++
+          return out.toString()
+        }
+        char == '\\' -> {
+          index++
+          when (val escape = text[index]) {
+            '"' -> out.append('"')
+            '\\' -> out.append('\\')
+            '/' -> out.append('/')
+            'b' -> out.append('\b')
+            'f' -> out.append('\u000C')
+            'n' -> out.append('\n')
+            'r' -> out.append('\r')
+            't' -> out.append('\t')
+            'u' -> {
+              out.append(text.substring(index + 1, index + 5).toInt(16).toChar())
+              index += 4
+            }
+            else -> throw IllegalStateException("bad escape $escape")
+          }
+          index++
+        }
+        else -> {
+          out.append(char)
+          index++
+        }
+      }
+    }
+  }
+
+  /**
+   * A number with no `.`, `e` or `E` parses as Long. That distinction is not
+   * cosmetic: session numbers and epoch timestamps are integers, and reloading
+   * them as doubles would rewrite the persisted blob with decimal points the
+   * TypeScript reader has never seen.
+   */
+  private fun parseNumber(): Any {
+    val start = index
+    if (text[index] == '-' || text[index] == '+') index++
+    var floating = false
+    while (index < text.length) {
+      val char = text[index]
+      if (char in '0'..'9') {
+        index++
+      } else if (char == '.' || char == 'e' || char == 'E' || char == '+' || char == '-') {
+        floating = floating || char == '.' || char == 'e' || char == 'E'
+        index++
+      } else {
+        break
+      }
+    }
+    val token = text.substring(start, index)
+    if (token.isEmpty()) throw IllegalStateException("expected number")
+    return if (floating) token.toDouble() else token.toLong()
+  }
+}

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

@@ -0,0 +1,50 @@
+package io.advenue.core
+
+/**
+ * Client-side enforcement of the ingest schema's input budgets.
+ *
+ * Without this the SDK enqueues an event the server is guaranteed to reject,
+ * and the rejection is not per-event: `apps/ingestion/src/app.ts` parses the
+ * batch as a whole and answers 400 on any single invalid event.
+ *
+ * No valid events are lost — `flush()` answers a non-retryable 4xx by isolating
+ * the batch one event at a time. What it costs is that isolation pass: one
+ * failed batch POST followed by up to `batchSize` individual POSTs, on a mobile
+ * radio, to deliver events that would have gone in a single request. The
+ * offending event is discarded either way.
+ *
+ * Rejecting here loses exactly the same one event, spends no requests, and
+ * tells the app through `onError` instead of failing silently.
+ *
+ * The values mirror `packages/shared/src/events.ts`, which is the authority.
+ */
+
+/** `clientEventSchema.name` — z.string().min(1).max(128). */
+internal const val MAX_NAME_LENGTH: Int = 128
+
+/** `customerUserId` — z.string().max(128). Üstü batch'i 400'e düşürür. */
+internal const val MAX_USER_ID_LENGTH: Int = 128
+
+/** `propertiesSchema` — at most this many keys. */
+internal const val MAX_PROPERTIES_KEYS: Int = 50
+
+/** `propertiesSchema` — the serialised length must not exceed this. */
+internal const val MAX_PROPERTIES_BYTES: Int = 8192
+
+/** Stable reason string, or null when the input is acceptable. */
+internal fun checkTrackInput(name: String, properties: Map<String, Any?>? = null): String? {
+  if (name.isEmpty()) return "name_empty"
+  if (name.length > MAX_NAME_LENGTH) return "name_too_long"
+  if (properties == null) return null
+  if (properties.size > MAX_PROPERTIES_KEYS) return "properties_too_many_keys"
+  val serialised =
+    try {
+      writeCanonicalJson(properties)
+    } catch (_: IllegalArgumentException) {
+      // A value the writer refuses would otherwise throw inside the transport,
+      // after it had already displaced a queue slot.
+      return "properties_unserialisable"
+    }
+  if (serialised.length > MAX_PROPERTIES_BYTES) return "properties_too_large"
+  return null
+}

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

@@ -0,0 +1,80 @@
+package io.advenue.core
+
+/**
+ * A Meta install referrer, parsed.
+ *
+ * [encryptedData] and [nonce] are the claim the server decrypts with the app's
+ * Meta decryption key; the key never reaches the device, so the SDK carries the
+ * ciphertext and nothing more.
+ */
+internal data class MetaReferrer(
+  val source: String?,
+  val campaign: String?,
+  val isClickThrough: Boolean,
+  /** Meta's own click/view time, in seconds. */
+  val timestamp: Long,
+  val encryptedData: String?,
+  val nonce: String?,
+  /** The provider's string, verbatim, for diagnostics. */
+  val raw: String,
+)
+
+/**
+ * Parses what the Meta install-referrer provider returned.
+ *
+ * Meta ships two shapes through the same column and the difference is not
+ * documented as a version: a JSON object when the referrer carries an encrypted
+ * claim, and a plain utm query string otherwise. Reading only the first would
+ * drop every organic-looking Meta install; reading only the second would drop
+ * every claim the server can actually decrypt.
+ *
+ * The JSON branch is tried first and, when the blob parses as an object, it
+ * OWNS the result — falling through to the query-string parser on a JSON object
+ * that merely lacks a claim would read the whole blob as one malformed key and
+ * report a campaign that does not exist.
+ *
+ * `network` is deliberately not derived here. The server assigns it from the
+ * decrypted claim (`meta_referrer` for a click, `meta_referrer_view` for a
+ * view), and a second answer set on the device would compete with the one that
+ * actually knows.
+ */
+internal fun parseMetaInstallReferrer(
+  raw: String,
+  isClickThrough: Boolean,
+  actualTimestamp: Long,
+): MetaReferrer? {
+  if (raw.isEmpty()) return null
+
+  val json = parseJson(raw) as? Map<*, *>
+  if (json != null) {
+    val claim = ((json["utm_content"] as? Map<*, *>)?.get("source")) as? Map<*, *>
+    // All or nothing. The server needs BOTH halves to decrypt, so a lone nonce
+    // is not half a claim — it is noise on the event that nothing will read.
+    val data = claim?.get("data") as? String
+    val nonce = claim?.get("nonce") as? String
+    val paired = if (!data.isNullOrEmpty() && !nonce.isNullOrEmpty()) data to nonce else null
+    return MetaReferrer(
+      source = json["utm_source"] as? String,
+      campaign = json["utm_campaign"] as? String,
+      isClickThrough = isClickThrough,
+      timestamp = actualTimestamp,
+      // Strings only. A number where `data` belongs is a shape the server
+      // cannot decrypt, and sending it credits the install to nobody — worse
+      // than reporting no claim at all.
+      encryptedData = paired?.first,
+      nonce = paired?.second,
+      raw = raw,
+    )
+  }
+
+  val parsed = parseInstallReferrer(raw)
+  return MetaReferrer(
+    source = parsed.source,
+    campaign = parsed.campaign,
+    isClickThrough = isClickThrough,
+    timestamp = actualTimestamp,
+    encryptedData = null,
+    nonce = null,
+    raw = raw,
+  )
+}

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

@@ -0,0 +1,77 @@
+package io.advenue.core
+
+/**
+ * B1: track properties PII scrubbing (varsayılan-açık) — Swift `PIIScrub`
+ * ile aynı sözleşme. Anahtar-adı tabanlı + değer-örüntü tabanlı eşleşen
+ * değerler gönderilmeden önce kaldırılır; ham değer ağa çıkmaz.
+ */
+internal object PiiScrub {
+  private val blockedKeys: Set<String> = setOf(
+    "email", "emailaddress", "emailadres", "eposta", "mail",
+    "phone", "phonenumber", "mobile", "mobilenumber", "mobil",
+    "telefon", "telefonno", "tel", "telno", "gsm",
+    "firstname", "lastname", "ad", "soyad", "adsoyad", "adisoyadi",
+    "fullname", "namesurname", "isim", "isimsoyisim",
+  )
+
+  private val blockedSubstrings: List<String> = listOf(
+    "email", "phone", "telefon", "soyad", "adsoyad", "firstname", "lastname",
+    "fullname",
+  )
+
+  private val emailRegex =
+    Regex("[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}", RegexOption.IGNORE_CASE)
+
+  private val phoneChars: Set<Char> = "+0123456789 \t.-()".toSet()
+
+  internal fun normalizeKey(key: String): String =
+    key.lowercase().filter { it.isLetterOrDigit() }
+
+  internal fun isSensitiveKey(key: String): Boolean {
+    val normalized = normalizeKey(key)
+    if (blockedKeys.contains(normalized)) return true
+    return blockedSubstrings.any { normalized.contains(it) }
+  }
+
+  /**
+   * Telefon sezgiseli (Swift ile aynı): çapasız alt-dize araması YOK.
+   * Değerin TÜMÜ telefon karakterlerinden oluşmalı ve rakam sayısı
+   * E.164 aralığında (10–15) olmalı.
+   */
+  internal fun looksLikePhone(value: String): Boolean {
+    val trimmed = value.trim()
+    if (trimmed.isEmpty()) return false
+    if (!trimmed.all { phoneChars.contains(it) }) return false
+    val first = trimmed.first()
+    val last = trimmed.last()
+    if (!(first == '+' || first.isDigit()) || !last.isDigit()) return false
+    return trimmed.count { it.isDigit() } in 10..15
+  }
+
+  internal fun isSensitiveValue(value: String): Boolean =
+    emailRegex.containsMatchIn(value) || looksLikePhone(value)
+
+  private fun scrubValue(value: Any?): Any? =
+    when (value) {
+      is String -> if (isSensitiveValue(value)) null else value
+      is Map<*, *> -> {
+        @Suppress("UNCHECKED_CAST")
+        val cleaned = scrub(value as Map<String, Any?>) ?: return null
+        cleaned
+      }
+      is List<*> -> value.mapNotNull { scrubValue(it) }
+      else -> value
+    }
+
+  /** PII taşıyan girdileri kaldırır. Girdi null ise null döner. */
+  internal fun scrub(properties: Map<String, Any?>?): Map<String, Any?>? {
+    if (properties == null) return null
+    val kept = LinkedHashMap<String, Any?>(properties.size)
+    for ((key, value) in properties) {
+      if (isSensitiveKey(key)) continue
+      val cleaned = scrubValue(value) ?: continue
+      kept[key] = cleaned
+    }
+    return kept
+  }
+}