From 88ea953b88b387bfafce17bd6c0586a0e5290fb0 Mon Sep 17 00:00:00 2001
From: xyzcancer <xyzcancer@gmail.com>
Date: Tue, 21 Apr 2026 11:49:39 +0400
Subject: [PATCH] DEV-4091: strict contract for order tracking + deprcation
 warnings

---
 .../demo/TrackPurchaseDemoE2ETest.kt          |  29 ++++
 .../com/personalization/demo/MainActivity.kt  | 114 ++++++++++++
 .../src/main/res/layout/activity_main.xml     |  14 ++
 demo-app/src/main/res/values/strings.xml      |   4 +
 personalization-sdk/CHANGELOG.md              |  15 ++
 ...haseTrackingJsonBuilderInstrumentedTest.kt |  81 +++++++++
 .../main/kotlin/com/personalization/Params.kt |   4 +
 .../main/kotlin/com/personalization/SDK.kt    |  13 ++
 .../api/managers/TrackEventManager.kt         |   9 +
 .../models/purchase/PurchaseItemRequest.kt    |  16 ++
 .../purchase/PurchaseTrackingRequest.kt       |  31 ++++
 .../purchase/PurchaseTrackingWireKeys.kt      |  30 ++++
 .../impl/PurchaseTrackingJsonBuilder.kt       | 162 ++++++++++++++++++
 .../trackEvent/impl/TrackEventManagerImpl.kt  |  35 ++++
 .../network/NetworkRepositoryImpl.kt          |  32 +++-
 .../PurchaseTrackingJsonBuilderJvmTest.kt     |  36 ++++
 16 files changed, 623 insertions(+), 2 deletions(-)
 create mode 100644 demo-app/src/androidTest/java/com/personalization/demo/TrackPurchaseDemoE2ETest.kt
 create mode 100644 personalization-sdk/CHANGELOG.md
 create mode 100644 personalization-sdk/src/androidTest/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderInstrumentedTest.kt
 create mode 100644 personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseItemRequest.kt
 create mode 100644 personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingRequest.kt
 create mode 100644 personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingWireKeys.kt
 create mode 100644 personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilder.kt
 create mode 100644 personalization-sdk/src/test/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderJvmTest.kt

diff --git a/demo-app/src/androidTest/java/com/personalization/demo/TrackPurchaseDemoE2ETest.kt b/demo-app/src/androidTest/java/com/personalization/demo/TrackPurchaseDemoE2ETest.kt
new file mode 100644
index 00000000..ad9175b2
--- /dev/null
+++ b/demo-app/src/androidTest/java/com/personalization/demo/TrackPurchaseDemoE2ETest.kt
@@ -0,0 +1,29 @@
+package com.personalization.demo
+
+import androidx.test.espresso.Espresso.onView
+import androidx.test.espresso.action.ViewActions.click
+import androidx.test.espresso.matcher.ViewMatchers.withId
+import androidx.test.ext.junit.rules.ActivityScenarioRule
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class TrackPurchaseDemoE2ETest {
+
+    @get:Rule
+    val activityRule = ActivityScenarioRule(MainActivity::class.java)
+
+    @Test
+    fun trackPurchaseMinimal_tapButton_noCrash() {
+        onView(withId(R.id.btnTrackPurchaseMinimal)).perform(click())
+        Thread.sleep(800)
+    }
+
+    @Test
+    fun trackPurchaseFull_tapButton_noCrash() {
+        onView(withId(R.id.btnTrackPurchaseFull)).perform(click())
+        Thread.sleep(800)
+    }
+}
diff --git a/demo-app/src/main/java/com/personalization/demo/MainActivity.kt b/demo-app/src/main/java/com/personalization/demo/MainActivity.kt
index 3975207a..f210c8fe 100644
--- a/demo-app/src/main/java/com/personalization/demo/MainActivity.kt
+++ b/demo-app/src/main/java/com/personalization/demo/MainActivity.kt
@@ -9,6 +9,8 @@ import com.personalization.Params
 import com.personalization.Params.TrackEvent
 import com.personalization.SDK
 import com.personalization.api.OnApiCallbackListener
+import com.personalization.api.models.purchase.PurchaseItemRequest
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
 import com.personalization.api.params.ProductItemParams
 import com.personalization.api.params.PurchasePredictParams
 import com.personalization.demo.BuildConfig
@@ -42,6 +44,16 @@ class MainActivity : AppCompatActivity() {
         const val DEMO_AMOUNT = 1
     }
 
+    private object DemoPurchaseTrackingConstants {
+        const val ORDER_ID_MINIMAL = "android-demo-order-minimal"
+        const val ORDER_ID_FULL = "android-demo-order-full"
+        const val ORDER_PRICE_MINIMAL = 199.0
+        const val ORDER_PRICE_FULL = 999.0
+        const val ITEM_ID = "android-demo-sku-001"
+        const val ITEM_AMOUNT = 1
+        const val ITEM_PRICE = 99.0
+    }
+
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         setContentView(R.layout.activity_main)
@@ -101,6 +113,108 @@ class MainActivity : AppCompatActivity() {
                 PurchasePredictParams(email = getString(R.string.predict_demo_email))
             )
         }
+
+        findViewById<Button>(R.id.btnTrackPurchaseMinimal).setOnClickListener {
+            trackPurchaseMinimal()
+        }
+
+        findViewById<Button>(R.id.btnTrackPurchaseFull).setOnClickListener {
+            trackPurchaseFull()
+        }
+    }
+
+    private fun trackPurchaseMinimal() {
+        val request = PurchaseTrackingRequest(
+            orderId = DemoPurchaseTrackingConstants.ORDER_ID_MINIMAL,
+            orderPrice = DemoPurchaseTrackingConstants.ORDER_PRICE_MINIMAL,
+            items = listOf(
+                PurchaseItemRequest(
+                    id = DemoPurchaseTrackingConstants.ITEM_ID,
+                    amount = DemoPurchaseTrackingConstants.ITEM_AMOUNT,
+                    price = DemoPurchaseTrackingConstants.ITEM_PRICE,
+                ),
+            ),
+        )
+        sdk.trackPurchase(
+            request,
+            object : OnApiCallbackListener() {
+                override fun onSuccess(response: JSONObject?) {
+                    runOnUiThread {
+                        Toast.makeText(
+                            this@MainActivity,
+                            getString(R.string.track_purchase_ok),
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    }
+                }
+
+                override fun onError(code: Int, msg: String?) {
+                    runOnUiThread {
+                        Toast.makeText(
+                            this@MainActivity,
+                            "${getString(R.string.track_purchase_fail)}: $msg",
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    }
+                }
+            },
+        )
+    }
+
+    private fun trackPurchaseFull() {
+        val request = PurchaseTrackingRequest(
+            orderId = DemoPurchaseTrackingConstants.ORDER_ID_FULL,
+            orderPrice = DemoPurchaseTrackingConstants.ORDER_PRICE_FULL,
+            items = listOf(
+                PurchaseItemRequest(
+                    id = DemoPurchaseTrackingConstants.ITEM_ID,
+                    amount = 2,
+                    price = 49.99,
+                    quantity = 2,
+                    lineId = "demo-line-1",
+                    fashionSize = "L",
+                ),
+            ),
+            deliveryType = "courier",
+            deliveryAddress = "Demo address",
+            paymentType = "card",
+            isTaxFree = true,
+            promocode = "DEMO10",
+            orderCash = 100.0,
+            orderBonuses = 10.0,
+            orderDelivery = 5.0,
+            orderDiscount = 15.0,
+            channel = "mobile",
+            custom = mapOf("demo_custom" to "android_demo"),
+            recommendedBy = Params.RecommendedBy(Params.RecommendedBy.TYPE.RECOMMENDATION, "demo-block"),
+            recommendedSource = JSONObject().put("source_key", "source_value"),
+            stream = "demo-stream",
+            segment = "A",
+        )
+        sdk.trackPurchase(
+            request,
+            object : OnApiCallbackListener() {
+                override fun onSuccess(response: JSONObject?) {
+                    runOnUiThread {
+                        Toast.makeText(
+                            this@MainActivity,
+                            getString(R.string.track_purchase_ok),
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    }
+                }
+
+                override fun onError(code: Int, msg: String?) {
+                    runOnUiThread {
+                        Toast.makeText(
+                            this@MainActivity,
+                            "${getString(R.string.track_purchase_fail)}: $msg",
+                            Toast.LENGTH_LONG,
+                        ).show()
+                    }
+                }
+            },
+        )
     }
 
     private fun predictPurchase(params: PurchasePredictParams) {
diff --git a/demo-app/src/main/res/layout/activity_main.xml b/demo-app/src/main/res/layout/activity_main.xml
index 8f22069f..09a45912 100644
--- a/demo-app/src/main/res/layout/activity_main.xml
+++ b/demo-app/src/main/res/layout/activity_main.xml
@@ -55,6 +55,20 @@
         android:text="@string/predict_with_email"
         android:layout_marginTop="16dp" />
 
+    <Button
+        android:id="@+id/btnTrackPurchaseMinimal"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/track_purchase_minimal"
+        android:layout_marginTop="24dp" />
+
+    <Button
+        android:id="@+id/btnTrackPurchaseFull"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="@string/track_purchase_full"
+        android:layout_marginTop="16dp" />
+
 </LinearLayout>
 
 
diff --git a/demo-app/src/main/res/values/strings.xml b/demo-app/src/main/res/values/strings.xml
index 6086bdbe..2a2fc6b0 100644
--- a/demo-app/src/main/res/values/strings.xml
+++ b/demo-app/src/main/res/values/strings.xml
@@ -18,6 +18,10 @@
     <string name="predict_demo_email">predict-demo@example.com</string>
     <string name="predict_ok">probability=%1$.4f client_id=%2$s</string>
     <string name="predict_fail">predict failed: %1$d %2$s</string>
+    <string name="track_purchase_minimal">Track purchase (minimal)</string>
+    <string name="track_purchase_full">Track purchase (full)</string>
+    <string name="track_purchase_ok">trackPurchase: sent</string>
+    <string name="track_purchase_fail">trackPurchase failed</string>
 </resources>
 
 
diff --git a/personalization-sdk/CHANGELOG.md b/personalization-sdk/CHANGELOG.md
new file mode 100644
index 00000000..b1618067
--- /dev/null
+++ b/personalization-sdk/CHANGELOG.md
@@ -0,0 +1,15 @@
+# personalization-sdk changelog
+
+## Unreleased
+
+### Features
+
+* Strict purchase tracking: `SDK.trackPurchase(PurchaseTrackingRequest, …)` with `PurchaseItemRequest` / `PurchaseTrackingRequest` (camelCase in public API; wire keys snake_case inside serialization). Client validation before network; `tax_free` only when `isTaxFree` is true; optional fields omitted when unset. Demo app and Espresso e2e taps for minimal and full payloads.
+
+### Deprecations
+
+* `TrackEvent.PURCHASE` (and `track(TrackEvent.PURCHASE, Params, ...)`) — use `SDK.trackPurchase(PurchaseTrackingRequest, ...)` instead.
+
+## Earlier releases
+
+See the repository root and release tags for history prior to this file.
diff --git a/personalization-sdk/src/androidTest/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderInstrumentedTest.kt b/personalization-sdk/src/androidTest/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderInstrumentedTest.kt
new file mode 100644
index 00000000..f33b93b1
--- /dev/null
+++ b/personalization-sdk/src/androidTest/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderInstrumentedTest.kt
@@ -0,0 +1,81 @@
+package com.personalization.features.trackEvent.impl
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import com.personalization.Params
+import com.personalization.api.models.purchase.PurchaseItemRequest
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
+import com.personalization.api.models.purchase.PurchaseTrackingWireKeys
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@RunWith(AndroidJUnit4::class)
+class PurchaseTrackingJsonBuilderInstrumentedTest {
+
+    @Test
+    fun buildOrError_minimal_containsRequiredKeysAndOmitsOptionals() {
+        val request = PurchaseTrackingRequest(
+            orderId = "order-1",
+            orderPrice = 99.5,
+            items = listOf(
+                PurchaseItemRequest(id = "p1", amount = 2, price = 10.0),
+            ),
+        )
+        val json = PurchaseTrackingJsonBuilder.buildOrError(request).getOrThrow()
+        assertEquals("purchase", json.getString(PurchaseTrackingWireKeys.EVENT))
+        assertEquals("order-1", json.getString(PurchaseTrackingWireKeys.ORDER_ID))
+        assertEquals(99.5, json.getDouble(PurchaseTrackingWireKeys.ORDER_PRICE), 0.0001)
+        assertFalse(json.has(PurchaseTrackingWireKeys.TAX_FREE))
+        assertFalse(json.has(PurchaseTrackingWireKeys.CUSTOM))
+        val items = json.getJSONArray(PurchaseTrackingWireKeys.ITEMS)
+        assertEquals(1, items.length())
+        val row = items.getJSONObject(0)
+        assertEquals("p1", row.getString(PurchaseTrackingWireKeys.ID))
+        assertEquals(2, row.getInt(PurchaseTrackingWireKeys.AMOUNT))
+        assertEquals(10.0, row.getDouble(PurchaseTrackingWireKeys.PRICE), 0.0001)
+        assertFalse(row.has(PurchaseTrackingWireKeys.QUANTITY))
+    }
+
+    @Test
+    fun buildOrError_full_includesOptionalFields() {
+        val request = PurchaseTrackingRequest(
+            orderId = "order-2",
+            orderPrice = 200.0,
+            items = listOf(
+                PurchaseItemRequest(
+                    id = "p2",
+                    amount = 1,
+                    price = 50.0,
+                    quantity = 1,
+                    lineId = "line-1",
+                    fashionSize = "M",
+                ),
+            ),
+            deliveryType = "pickup",
+            deliveryAddress = "Street 1",
+            paymentType = "cash",
+            isTaxFree = true,
+            promocode = "PROMO",
+            orderCash = 10.0,
+            orderBonuses = 5.0,
+            orderDelivery = 2.0,
+            orderDiscount = 1.0,
+            channel = "mobile",
+            custom = mapOf("k" to "v"),
+            recommendedBy = Params.RecommendedBy(Params.RecommendedBy.TYPE.RECOMMENDATION, "code-1"),
+            recommendedSource = JSONObject().put("src", 1),
+            stream = "s1",
+            segment = "B",
+        )
+        val json = PurchaseTrackingJsonBuilder.buildOrError(request).getOrThrow()
+        assertTrue(json.getBoolean(PurchaseTrackingWireKeys.TAX_FREE))
+        assertEquals("pickup", json.getString(PurchaseTrackingWireKeys.DELIVERY_TYPE))
+        assertTrue(json.has(PurchaseTrackingWireKeys.CUSTOM))
+        assertTrue(json.has(PurchaseTrackingWireKeys.RECOMMENDED_SOURCE))
+        assertEquals("dynamic", json.getString(Params.InternalParameter.RECOMMENDED_BY.value))
+        assertEquals("code-1", json.getString(Params.InternalParameter.RECOMMENDED_CODE.value))
+    }
+}
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/Params.kt b/personalization-sdk/src/main/kotlin/com/personalization/Params.kt
index 830cd9d7..c20f69e5 100644
--- a/personalization-sdk/src/main/kotlin/com/personalization/Params.kt
+++ b/personalization-sdk/src/main/kotlin/com/personalization/Params.kt
@@ -135,6 +135,10 @@ class Params : AbstractParams<Params>() {
         CATEGORY("category"),
         CART("cart"),
         REMOVE_FROM_CART("remove_from_cart"),
+        @Deprecated(
+            message = "Use SDK.trackPurchase(PurchaseTrackingRequest, listener) instead of track(TrackEvent.PURCHASE, Params).",
+            level = DeprecationLevel.WARNING,
+        )
         PURCHASE("purchase"),
         SEARCH("search"),
         WISH("wish"),
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/SDK.kt b/personalization-sdk/src/main/kotlin/com/personalization/SDK.kt
index e0cd2af8..d6261e62 100644
--- a/personalization-sdk/src/main/kotlin/com/personalization/SDK.kt
+++ b/personalization-sdk/src/main/kotlin/com/personalization/SDK.kt
@@ -9,6 +9,7 @@ import com.google.firebase.messaging.RemoteMessage
 import com.personalization.Params.InternalParameter
 import com.personalization.Params.TrackEvent
 import com.personalization.api.OnApiCallbackListener
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
 import com.personalization.api.managers.CartManager
 import com.personalization.api.managers.InAppNotificationManager
 import com.personalization.api.managers.ProductsManager
@@ -529,6 +530,18 @@ open class SDK {
         )
     }
 
+    /**
+     * Strict purchase tracking (`push`, event = `purchase`).
+     *
+     * Prefer this over [track] with [TrackEvent.PURCHASE] and manual [Params] assembly.
+     */
+    fun trackPurchase(
+        request: PurchaseTrackingRequest,
+        listener: OnApiCallbackListener? = null,
+    ) {
+        trackEventManager.trackPurchase(request, listener)
+    }
+
     /**
      * Tracking custom events
      *
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/api/managers/TrackEventManager.kt b/personalization-sdk/src/main/kotlin/com/personalization/api/managers/TrackEventManager.kt
index fc0d40bd..19de60ae 100644
--- a/personalization-sdk/src/main/kotlin/com/personalization/api/managers/TrackEventManager.kt
+++ b/personalization-sdk/src/main/kotlin/com/personalization/api/managers/TrackEventManager.kt
@@ -3,6 +3,7 @@ package com.personalization.api.managers
 import com.personalization.Params
 import com.personalization.Params.TrackEvent
 import com.personalization.api.OnApiCallbackListener
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
 
 interface TrackEventManager {
 
@@ -27,6 +28,14 @@ interface TrackEventManager {
         listener: OnApiCallbackListener? = null
     )
 
+    /**
+     * Strict purchase tracking (`event` = `purchase`) with typed request (parity with iOS / React Native).
+     */
+    fun trackPurchase(
+        request: PurchaseTrackingRequest,
+        listener: OnApiCallbackListener? = null,
+    )
+
     /**
      * Custom event tracking (aligned with the iOS SDK `trackEvent`).
      *
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseItemRequest.kt b/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseItemRequest.kt
new file mode 100644
index 00000000..968363f8
--- /dev/null
+++ b/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseItemRequest.kt
@@ -0,0 +1,16 @@
+package com.personalization.api.models.purchase
+
+/**
+ * One purchased line item (strict mobile contract).
+ *
+ * Required: [id], [amount], [price].
+ * Optional: [quantity], [lineId], [fashionSize] — omit from the constructor when not needed (defaults).
+ */
+data class PurchaseItemRequest(
+    val id: String,
+    val amount: Int,
+    val price: Double,
+    val quantity: Int? = null,
+    val lineId: String? = null,
+    val fashionSize: String? = null,
+)
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingRequest.kt b/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingRequest.kt
new file mode 100644
index 00000000..bba29a08
--- /dev/null
+++ b/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingRequest.kt
@@ -0,0 +1,31 @@
+package com.personalization.api.models.purchase
+
+import com.personalization.Params
+import org.json.JSONObject
+
+/**
+ * Strict purchase tracking request for `push` (event = `purchase`).
+ *
+ * Required: [orderId], [orderPrice], [items].
+ * All other fields are optional — omit them from the constructor when unused (no need to pass `null`).
+ */
+data class PurchaseTrackingRequest(
+    val orderId: String,
+    val orderPrice: Double,
+    val items: List<PurchaseItemRequest>,
+    val deliveryType: String? = null,
+    val deliveryAddress: String? = null,
+    val paymentType: String? = null,
+    val isTaxFree: Boolean = false,
+    val promocode: String? = null,
+    val orderCash: Double? = null,
+    val orderBonuses: Double? = null,
+    val orderDelivery: Double? = null,
+    val orderDiscount: Double? = null,
+    val channel: String? = null,
+    val custom: Map<String, Any?>? = null,
+    val recommendedBy: Params.RecommendedBy? = null,
+    val recommendedSource: JSONObject? = null,
+    val stream: String? = null,
+    val segment: String? = null,
+)
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingWireKeys.kt b/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingWireKeys.kt
new file mode 100644
index 00000000..6a096ea1
--- /dev/null
+++ b/personalization-sdk/src/main/kotlin/com/personalization/api/models/purchase/PurchaseTrackingWireKeys.kt
@@ -0,0 +1,30 @@
+package com.personalization.api.models.purchase
+
+/**
+ * Wire (JSON) keys for `push` purchase tracking. Public API uses camelCase; these are snake_case only here.
+ */
+internal object PurchaseTrackingWireKeys {
+    const val EVENT = "event"
+    const val PURCHASE_EVENT_VALUE = "purchase"
+    const val ITEMS = "items"
+    const val ID = "id"
+    const val AMOUNT = "amount"
+    const val PRICE = "price"
+    const val QUANTITY = "quantity"
+    const val LINE_ID = "line_id"
+    const val FASHION_SIZE = "fashion_size"
+    const val ORDER_ID = "order_id"
+    const val ORDER_PRICE = "order_price"
+    const val DELIVERY_TYPE = "delivery_type"
+    const val DELIVERY_ADDRESS = "delivery_address"
+    const val PAYMENT_TYPE = "payment_type"
+    const val TAX_FREE = "tax_free"
+    const val PROMOCODE = "promocode"
+    const val ORDER_CASH = "order_cash"
+    const val ORDER_BONUSES = "order_bonuses"
+    const val ORDER_DELIVERY = "order_delivery"
+    const val ORDER_DISCOUNT = "order_discount"
+    const val CHANNEL = "channel"
+    const val CUSTOM = "custom"
+    const val RECOMMENDED_SOURCE = "recommended_source"
+}
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilder.kt b/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilder.kt
new file mode 100644
index 00000000..22dd2dd4
--- /dev/null
+++ b/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilder.kt
@@ -0,0 +1,162 @@
+package com.personalization.features.trackEvent.impl
+
+import com.personalization.Params
+import com.personalization.api.models.purchase.PurchaseItemRequest
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
+import com.personalization.api.models.purchase.PurchaseTrackingWireKeys
+import com.personalization.sdk.data.models.params.UserBasicParams
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+internal object PurchaseTrackingJsonBuilder {
+
+    const val CLIENT_VALIDATION_ERROR_CODE: Int = -2
+
+    private val RESERVED_CUSTOM_KEYS: Set<String> = buildSet {
+        addAll(TrackCustomEventPayloadHelper.RESERVED_CUSTOM_EVENT_KEYS)
+        add(PurchaseTrackingWireKeys.EVENT)
+        add(PurchaseTrackingWireKeys.ITEMS)
+        add(PurchaseTrackingWireKeys.ORDER_ID)
+        add(PurchaseTrackingWireKeys.ORDER_PRICE)
+        add(PurchaseTrackingWireKeys.DELIVERY_TYPE)
+        add(PurchaseTrackingWireKeys.DELIVERY_ADDRESS)
+        add(PurchaseTrackingWireKeys.PAYMENT_TYPE)
+        add(PurchaseTrackingWireKeys.TAX_FREE)
+        add(PurchaseTrackingWireKeys.PROMOCODE)
+        add(PurchaseTrackingWireKeys.ORDER_CASH)
+        add(PurchaseTrackingWireKeys.ORDER_BONUSES)
+        add(PurchaseTrackingWireKeys.ORDER_DELIVERY)
+        add(PurchaseTrackingWireKeys.ORDER_DISCOUNT)
+        add(PurchaseTrackingWireKeys.CHANNEL)
+        add(PurchaseTrackingWireKeys.CUSTOM)
+        add(PurchaseTrackingWireKeys.RECOMMENDED_SOURCE)
+        add(Params.InternalParameter.RECOMMENDED_BY.value)
+        add(Params.InternalParameter.RECOMMENDED_CODE.value)
+    }
+
+    fun buildOrError(request: PurchaseTrackingRequest): Result<JSONObject> {
+        if (request.orderId.isBlank()) {
+            return Result.failure(IllegalArgumentException("trackPurchase: orderId must be non-empty"))
+        }
+        if (request.items.isEmpty()) {
+            return Result.failure(IllegalArgumentException("trackPurchase: items must not be empty"))
+        }
+        for (item in request.items) {
+            if (item.id.isBlank()) {
+                return Result.failure(IllegalArgumentException("trackPurchase: each item.id must be non-empty"))
+            }
+            if (item.amount <= 0) {
+                return Result.failure(IllegalArgumentException("trackPurchase: each item.amount must be > 0"))
+            }
+            if (!item.price.isFinite()) {
+                return Result.failure(IllegalArgumentException("trackPurchase: each item.price must be a finite number"))
+            }
+        }
+        if (!request.orderPrice.isFinite()) {
+            return Result.failure(IllegalArgumentException("trackPurchase: orderPrice must be a finite number"))
+        }
+
+        val effectiveCustom = TrackCustomEventPayloadHelper.effectiveCustomFields(request.custom)
+        if (effectiveCustom.isNotEmpty()) {
+            val collisions = effectiveCustom.keys.intersect(RESERVED_CUSTOM_KEYS)
+            if (collisions.isNotEmpty()) {
+                return Result.failure(
+                    IllegalArgumentException(
+                        "trackPurchase: custom contains reserved keys: ${collisions.toSortedSet().joinToString(", ")}"
+                    )
+                )
+            }
+        }
+
+        return try {
+            Result.success(buildJson(request, effectiveCustom))
+        } catch (e: JSONException) {
+            Result.failure(IllegalArgumentException("trackPurchase: failed to build JSON: ${e.message}", e))
+        }
+    }
+
+    private fun buildJson(
+        request: PurchaseTrackingRequest,
+        effectiveCustom: Map<String, Any>,
+    ): JSONObject {
+        val root = JSONObject()
+        root.put(PurchaseTrackingWireKeys.EVENT, PurchaseTrackingWireKeys.PURCHASE_EVENT_VALUE)
+        root.put(PurchaseTrackingWireKeys.ORDER_ID, request.orderId)
+        root.put(PurchaseTrackingWireKeys.ORDER_PRICE, request.orderPrice)
+
+        val itemsArray = JSONArray()
+        for (item in request.items) {
+            itemsArray.put(itemToJson(item))
+        }
+        root.put(PurchaseTrackingWireKeys.ITEMS, itemsArray)
+
+        request.deliveryType?.takeIf { it.isNotBlank() }?.let {
+            root.put(PurchaseTrackingWireKeys.DELIVERY_TYPE, it)
+        }
+        request.deliveryAddress?.takeIf { it.isNotBlank() }?.let {
+            root.put(PurchaseTrackingWireKeys.DELIVERY_ADDRESS, it)
+        }
+        request.paymentType?.takeIf { it.isNotBlank() }?.let {
+            root.put(PurchaseTrackingWireKeys.PAYMENT_TYPE, it)
+        }
+        if (request.isTaxFree) {
+            root.put(PurchaseTrackingWireKeys.TAX_FREE, true)
+        }
+        request.promocode?.takeIf { it.isNotBlank() }?.let {
+            root.put(PurchaseTrackingWireKeys.PROMOCODE, it)
+        }
+        request.orderCash?.let { root.put(PurchaseTrackingWireKeys.ORDER_CASH, it) }
+        request.orderBonuses?.let { root.put(PurchaseTrackingWireKeys.ORDER_BONUSES, it) }
+        request.orderDelivery?.let { root.put(PurchaseTrackingWireKeys.ORDER_DELIVERY, it) }
+        request.orderDiscount?.let { root.put(PurchaseTrackingWireKeys.ORDER_DISCOUNT, it) }
+        request.channel?.takeIf { it.isNotBlank() }?.let {
+            root.put(PurchaseTrackingWireKeys.CHANNEL, it)
+        }
+
+        if (effectiveCustom.isNotEmpty()) {
+            val customJson = JSONObject()
+            for ((key, value) in effectiveCustom) {
+                TrackCustomEventPayloadHelper.putJsonValue(customJson, key, value)
+            }
+            root.put(PurchaseTrackingWireKeys.CUSTOM, customJson)
+        }
+
+        request.recommendedSource?.let { root.put(PurchaseTrackingWireKeys.RECOMMENDED_SOURCE, it) }
+
+        request.stream?.takeIf { it.isNotBlank() }?.let {
+            root.put(UserBasicParams.STREAM, it)
+        }
+        request.segment?.takeIf { it.isNotBlank() }?.let {
+            root.put(UserBasicParams.SEGMENT, it)
+        }
+
+        if (request.recommendedBy != null) {
+            val rbJson = Params().put(request.recommendedBy).build()
+            mergeInto(root, rbJson)
+        }
+
+        return root
+    }
+
+    private fun itemToJson(item: PurchaseItemRequest): JSONObject {
+        val row = JSONObject()
+        row.put(PurchaseTrackingWireKeys.ID, item.id)
+        row.put(PurchaseTrackingWireKeys.AMOUNT, item.amount)
+        row.put(PurchaseTrackingWireKeys.PRICE, item.price)
+        item.quantity?.let { row.put(PurchaseTrackingWireKeys.QUANTITY, it) }
+        item.lineId?.takeIf { it.isNotBlank() }?.let { row.put(PurchaseTrackingWireKeys.LINE_ID, it) }
+        item.fashionSize?.takeIf { it.isNotBlank() }?.let {
+            row.put(PurchaseTrackingWireKeys.FASHION_SIZE, it)
+        }
+        return row
+    }
+
+    fun mergeInto(target: JSONObject, source: JSONObject) {
+        val keys = source.keys() ?: return
+        while (keys.hasNext()) {
+            val key = keys.next()
+            target.put(key, source.get(key))
+        }
+    }
+}
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/TrackEventManagerImpl.kt b/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/TrackEventManagerImpl.kt
index f7876ec0..d3748e5f 100644
--- a/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/TrackEventManagerImpl.kt
+++ b/personalization-sdk/src/main/kotlin/com/personalization/features/trackEvent/impl/TrackEventManagerImpl.kt
@@ -5,6 +5,7 @@ import com.personalization.Params.TrackEvent
 import com.personalization.api.OnApiCallbackListener
 import com.personalization.api.managers.InAppNotificationManager
 import com.personalization.api.managers.TrackEventManager
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
 import com.personalization.api.params.ProductItemParams
 import com.personalization.sdk.data.mappers.popup.PopupDtoMapper
 import com.personalization.sdk.data.models.params.SdkInitializationParams.PARAM_POPUP
@@ -57,6 +58,40 @@ internal class TrackEventManagerImpl @Inject constructor(
         )
     }
 
+    override fun trackPurchase(request: PurchaseTrackingRequest, listener: OnApiCallbackListener?) {
+        val jsonResult = PurchaseTrackingJsonBuilder.buildOrError(request)
+        if (jsonResult.isFailure) {
+            listener?.onError(
+                PurchaseTrackingJsonBuilder.CLIENT_VALIDATION_ERROR_CODE,
+                jsonResult.exceptionOrNull()?.message,
+            )
+            return
+        }
+        val body = jsonResult.getOrNull()!!
+        if (request.recommendedBy == null) {
+            val lastRecommendedBy = getRecommendedByUseCase()
+            if (lastRecommendedBy != null) {
+                PurchaseTrackingJsonBuilder.mergeInto(body, Params().put(lastRecommendedBy).build())
+                setRecommendedByUseCase(null)
+            }
+        }
+
+        val internalListener = object : OnApiCallbackListener() {
+            override fun onSuccess(response: JSONObject?) {
+                response?.let {
+                    handlePopup(response)
+                }
+                listener?.onSuccess(response)
+            }
+        }
+
+        sendNetworkMethodUseCase.postAsync(
+            PUSH_REQUEST,
+            body,
+            internalListener,
+        )
+    }
+
     override fun trackEvent(
         event: String,
         time: Int?,
diff --git a/personalization-sdk/src/main/kotlin/com/personalization/sdk/data/repositories/network/NetworkRepositoryImpl.kt b/personalization-sdk/src/main/kotlin/com/personalization/sdk/data/repositories/network/NetworkRepositoryImpl.kt
index 02032f84..86639ce4 100644
--- a/personalization-sdk/src/main/kotlin/com/personalization/sdk/data/repositories/network/NetworkRepositoryImpl.kt
+++ b/personalization-sdk/src/main/kotlin/com/personalization/sdk/data/repositories/network/NetworkRepositoryImpl.kt
@@ -190,8 +190,16 @@ class NetworkRepositoryImpl @Inject constructor(
                 UserBasicParams.DID to userSettingsRepository.getDid(),
                 UserBasicParams.SID to userSettingsRepository.getSid(),
                 UserBasicParams.SEANCE to userSettingsRepository.getSid(),
-                UserBasicParams.SEGMENT to userSettingsRepository.getSegmentForABTesting(),
-                UserBasicParams.STREAM to userSettingsRepository.getStream(),
+                UserBasicParams.SEGMENT to resolveClientOrRepoString(
+                    params = params,
+                    key = UserBasicParams.SEGMENT,
+                    repoValue = userSettingsRepository.getSegmentForABTesting(),
+                ),
+                UserBasicParams.STREAM to resolveClientOrRepoString(
+                    params = params,
+                    key = UserBasicParams.STREAM,
+                    repoValue = userSettingsRepository.getStream(),
+                ),
                 UserBasicParams.SOURCE_FROM to notificationSource?.type,
                 UserBasicParams.SOURCE_CODE to notificationSource?.id
             )
@@ -199,6 +207,26 @@ class NetworkRepositoryImpl @Inject constructor(
         return params
     }
 
+    /**
+     * If the request body already contains a non-blank [key] (e.g. strict `trackPurchase` override), keep it;
+     * otherwise use [repoValue].
+     */
+    private fun resolveClientOrRepoString(
+        params: JSONObject,
+        key: String,
+        repoValue: String,
+    ): String {
+        if (!params.has(key) || params.isNull(key)) {
+            return repoValue
+        }
+        val raw = params.get(key)
+        val asString = when (raw) {
+            is String -> raw
+            else -> raw.toString()
+        }
+        return asString.ifBlank { repoValue }
+    }
+
     private fun executeMethod(
         networkMethod: NetworkMethod,
         params: JSONObject,
diff --git a/personalization-sdk/src/test/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderJvmTest.kt b/personalization-sdk/src/test/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderJvmTest.kt
new file mode 100644
index 00000000..7eb90794
--- /dev/null
+++ b/personalization-sdk/src/test/kotlin/com/personalization/features/trackEvent/impl/PurchaseTrackingJsonBuilderJvmTest.kt
@@ -0,0 +1,36 @@
+package com.personalization.features.trackEvent.impl
+
+import com.personalization.api.models.purchase.PurchaseItemRequest
+import com.personalization.api.models.purchase.PurchaseTrackingRequest
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * JVM-only checks that do not require a real [org.json.JSONObject] implementation (AGP stubs break JSON in unit tests).
+ */
+class PurchaseTrackingJsonBuilderJvmTest {
+
+    @Test
+    fun buildOrError_rejectsEmptyOrderId() {
+        val r = PurchaseTrackingJsonBuilder.buildOrError(
+            PurchaseTrackingRequest(
+                orderId = " ",
+                orderPrice = 1.0,
+                items = listOf(PurchaseItemRequest("x", 1, 1.0)),
+            ),
+        )
+        assertTrue(r.isFailure)
+    }
+
+    @Test
+    fun buildOrError_rejectsEmptyItems() {
+        val r = PurchaseTrackingJsonBuilder.buildOrError(
+            PurchaseTrackingRequest(
+                orderId = "a",
+                orderPrice = 1.0,
+                items = emptyList(),
+            ),
+        )
+        assertTrue(r.isFailure)
+    }
+}