@virex-tech/paywallo-sdk 2.2.3 → 2.2.5

package/android/build.gradle

@@ -8,7 +8,7 @@ buildscript {
     }
     dependencies {
         classpath("com.android.tools.build:gradle:${safeExtGet('androidGradlePluginVersion', '7.4.2')}")
-        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '1.9.22')}")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${safeExtGet('kotlinVersion', '2.0.21')}")
     }
 }
 
@@ -48,12 +48,14 @@ repositories {
 
 dependencies {
     implementation "com.facebook.react:react-native:+"
-    implementation "org.jetbrains.kotlin:kotlin-stdlib:${safeExtGet('kotlinVersion', '1.9.22')}"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:${safeExtGet('kotlinVersion', '2.0.21')}"
     implementation "com.android.billingclient:billing-ktx:7.0.0"
     implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
     implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
     compileOnly "com.facebook.android:facebook-android-sdk:17.+"
     compileOnly "com.google.firebase:firebase-messaging:24.0.0"
-    implementation "androidx.security:security-crypto:1.0.0"
+    // 1.1.0+ required for MasterKey.Builder API used in PaywalloStorageModule.
+    // 1.0.0 only ships the deprecated MasterKeys.getOrCreate(...) static helper.
+    implementation "androidx.security:security-crypto:1.1.0"
     implementation "com.android.installreferrer:installreferrer:2.2"
 }

package/android/src/main/AndroidManifest.xml

@@ -1,6 +1,13 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.paywallo.sdk">
 
+    <!--
+        Google Play Billing — required by PaywalloStoreKitModule (BillingClient).
+        Merged into the host app manifest automatically. Without this permission,
+        BillingClient.startConnection() fails silently at runtime.
+    -->
+    <uses-permission android:name="com.android.vending.BILLING" />
+
     <application>
         <!--
             PaywalloFirebaseMessagingService handles FCM token refresh and message delivery.

package/android/src/main/java/com/paywallo/sdk/PaywalloFirebaseMessagingService.kt

@@ -2,6 +2,7 @@ package com.paywallo.sdk
 
 import com.google.firebase.messaging.FirebaseMessagingService
 import com.google.firebase.messaging.RemoteMessage
+import com.facebook.react.bridge.ReactContext
 import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.facebook.react.ReactApplication
@@ -46,10 +47,7 @@ class PaywalloFirebaseMessagingService : FirebaseMessagingService() {
 
     private fun emitEvent(eventName: String, data: WritableNativeMap) {
         try {
-            val reactContext = (application as? ReactApplication)
-                ?.reactNativeHost
-                ?.reactInstanceManager
-                ?.currentReactContext
+            val reactContext = resolveReactContext()
             if (reactContext != null) {
                 reactContext
                     .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java)
@@ -58,10 +56,40 @@ class PaywalloFirebaseMessagingService : FirebaseMessagingService() {
                 // Cold start: React context not ready — buffer for getInitialNotification()
                 pendingMessage = data
             }
-        } catch (_: Exception) {
+        } catch (_: Throwable) {
             if (eventName == MESSAGE_RECEIVED_EVENT) {
                 pendingMessage = data
             }
         }
     }
+
+    /**
+     * Resolves the active ReactContext across both architectures:
+     *   - New Architecture (bridgeless): ReactApplication.reactHost.currentReactContext
+     *   - Legacy bridge: ReactApplication.reactNativeHost.reactInstanceManager.currentReactContext
+     *
+     * Note: in the New Architecture, accessing `reactNativeHost` throws
+     * RuntimeException("You should not use ReactNativeHost directly in the New Architecture"),
+     * so we MUST try `reactHost` first and only fall back to the legacy path when reactHost is null.
+     * Each path is guarded by try/catch so a throw on one doesn't break the other.
+     */
+    private fun resolveReactContext(): ReactContext? {
+        val app = application as? ReactApplication ?: return null
+
+        // New Architecture path (RN 0.74+ bridgeless)
+        try {
+            val ctx = app.reactHost?.currentReactContext
+            if (ctx != null) return ctx
+        } catch (_: Throwable) {
+            // fall through to legacy
+        }
+
+        // Legacy bridge path (Old Architecture)
+        return try {
+            @Suppress("DEPRECATION")
+            app.reactNativeHost.reactInstanceManager.currentReactContext
+        } catch (_: Throwable) {
+            null
+        }
+    }
 }

package/android/src/main/java/com/paywallo/sdk/PaywalloNotificationsModule.kt

@@ -3,10 +3,10 @@ package com.paywallo.sdk
 import android.Manifest
 import android.content.pm.PackageManager
 import android.os.Build
-import androidx.core.app.ActivityCompat
 import androidx.core.content.ContextCompat
 import com.facebook.react.bridge.*
-import com.facebook.react.modules.core.DeviceEventManagerModule
+import com.facebook.react.modules.core.PermissionAwareActivity
+import com.facebook.react.modules.core.PermissionListener
 
 class PaywalloNotificationsModule(private val reactContext: ReactApplicationContext) :
     ReactContextBaseJavaModule(reactContext) {
@@ -14,26 +14,21 @@ class PaywalloNotificationsModule(private val reactContext: ReactApplicationCont
     private var permissionPromise: Promise? = null
     private val PERMISSION_REQUEST_CODE = 1001
 
-    private val activityEventListener = object : BaseActivityEventListener() {
-        override fun onRequestPermissionsResult(
-            requestCode: Int,
-            permissions: Array<out String>,
-            grantResults: IntArray
-        ) {
-            if (requestCode != PERMISSION_REQUEST_CODE) return
-            val promise = permissionPromise ?: return
-            permissionPromise = null
+    private val permissionListener = PermissionListener { requestCode, _, grantResults ->
+        if (requestCode != PERMISSION_REQUEST_CODE) {
+            return@PermissionListener false
+        }
+        val promise = permissionPromise
+        permissionPromise = null
 
+        if (promise != null) {
             if (grantResults.isNotEmpty() && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
                 promise.resolve("granted")
             } else {
                 promise.resolve("denied")
             }
         }
-    }
-
-    init {
-        reactContext.addActivityEventListener(activityEventListener)
+        true
     }
 
     override fun getName() = "PaywalloNotifications"
@@ -79,7 +74,10 @@ class PaywalloNotificationsModule(private val reactContext: ReactApplicationCont
     fun requestPermission(options: ReadableMap?, promise: Promise) {
         // Android 13+ (API 33) requires POST_NOTIFICATIONS runtime permission
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
-            val activity = currentActivity
+            // RN 0.80+ removed the synthetic `currentActivity` property on
+            // ReactContextBaseJavaModule (base class was rewritten in Kotlin).
+            // Reach it via the ReactContext, which is still Java-backed.
+            val activity = reactContext.currentActivity
             if (activity == null) {
                 promise.resolve("denied")
                 return
@@ -90,23 +88,41 @@ class PaywalloNotificationsModule(private val reactContext: ReactApplicationCont
 
             if (granted) {
                 promise.resolve("granted")
-            } else {
-                // If there's already a pending promise, reject it before storing the new one
-                permissionPromise?.reject("PERMISSION_SUPERSEDED", "New permission request superseded this one")
-                // Store promise and wait for onRequestPermissionsResult callback
-                permissionPromise = promise
-                ActivityCompat.requestPermissions(
-                    activity,
-                    arrayOf(Manifest.permission.POST_NOTIFICATIONS),
-                    PERMISSION_REQUEST_CODE
-                )
+                return
+            }
+
+            val permissionAware = activity as? PermissionAwareActivity
+            if (permissionAware == null) {
+                promise.resolve("denied")
+                return
             }
+
+            // If there's already a pending promise, reject it before storing the new one
+            permissionPromise?.reject("PERMISSION_SUPERSEDED", "New permission request superseded this one")
+            // Store promise and wait for permission listener callback
+            permissionPromise = promise
+            permissionAware.requestPermissions(
+                arrayOf(Manifest.permission.POST_NOTIFICATIONS),
+                PERMISSION_REQUEST_CODE,
+                permissionListener
+            )
         } else {
             // Pre-Android 13: notifications always allowed
             promise.resolve("granted")
         }
     }
 
+    // iOS calls UIApplication.registerForRemoteNotifications() here to obtain
+    // an APNS token. On Android there's no equivalent: FCM tokens are minted
+    // automatically by Firebase and surfaced via FirebaseMessagingService.onNewToken.
+    // Exposing this as a no-op keeps the cross-platform bridge contract and
+    // silences the "method not found" warning from NativeModules when the JS
+    // bridge calls it after permission is granted.
+    @ReactMethod
+    fun registerForPush(promise: Promise) {
+        promise.resolve(null)
+    }
+
     @ReactMethod
     fun hasPermission(promise: Promise) {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
@@ -130,7 +146,7 @@ class PaywalloNotificationsModule(private val reactContext: ReactApplicationCont
         }
 
         // Check if the app was opened from a notification tap
-        val activity = currentActivity
+        val activity = reactContext.currentActivity
         val intent = activity?.intent
         val extras = intent?.extras
 
@@ -161,9 +177,10 @@ class PaywalloNotificationsModule(private val reactContext: ReactApplicationCont
         }
     }
 
-    override fun onCatalystInstanceDestroy() {
-        reactContext.removeActivityEventListener(activityEventListener)
+    // invalidate() is the post-TurboModule replacement for onCatalystInstanceDestroy.
+    // The latter is @Deprecated(forRemoval = true) since RN 0.74 and will be removed.
+    override fun invalidate() {
         permissionPromise = null
-        super.onCatalystInstanceDestroy()
+        super.invalidate()
     }
 }

package/android/src/main/java/com/paywallo/sdk/PaywalloStoreKitModule.kt

@@ -195,7 +195,9 @@ class PaywalloStoreKitModule(private val reactContext: ReactApplicationContext)
                 }
 
                 val client = billingClient!!
-                val activity = currentActivity
+                // RN 0.80+ removed the synthetic `currentActivity` property on
+                // ReactContextBaseJavaModule. Reach it via ReactContext instead.
+                val activity = reactContext.currentActivity
 
                 if (activity == null) {
                     promise.reject("NO_ACTIVITY", "No current activity")
@@ -427,13 +429,15 @@ class PaywalloStoreKitModule(private val reactContext: ReactApplicationContext)
         }
     }
 
-    override fun onCatalystInstanceDestroy() {
+    // invalidate() is the post-TurboModule replacement for onCatalystInstanceDestroy.
+    // The latter is @Deprecated(forRemoval = true) since RN 0.74 and will be removed.
+    override fun invalidate() {
         // Reject any pending purchase promise so the JS side doesn't hang forever
         purchasePromise?.reject("MODULE_DESTROYED", "Module was destroyed before purchase completed")
         purchasePromise = null
         scope.cancel()
         billingClient?.endConnection()
         billingClient = null
-        super.onCatalystInstanceDestroy()
+        super.invalidate()
     }
 }

package/android/src/main/java/com/paywallo/sdk/PaywalloWebViewEvent.kt

@@ -10,11 +10,13 @@ import com.facebook.react.uimanager.events.Event
 class PaywalloWebViewEvent(
     surfaceId: Int,
     viewId: Int,
-    private val eventName: String,
+    // RN 0.81 `Event.eventName` is now an open `val` on the base class.
+    // Using `eventName` as a constructor parameter would shadow it.
+    private val name: String,
     private val payload: WritableMap
 ) : Event<PaywalloWebViewEvent>(surfaceId, viewId) {
 
-    override fun getEventName(): String = eventName
+    override fun getEventName(): String = name
 
     override fun getEventData(): WritableMap = payload
 }

package/dist/index.d.mts

@@ -378,7 +378,7 @@ declare const PaywalloContext: React.Context<PaywalloContextValue | null>;
  * event in the V2 ingest envelope. The provider is called at flush time so
  * each field reflects the most recent SDK state.
  *
- * The shape mirrors the server-side `/api/v2/ingest/batch` contract (Phase
+ * The shape mirrors the server-side `/sdk/ingest/batch` contract (Phase
  * 3.1). Fields declared here are deduplicated across the batch — they exist
  * once on the envelope instead of `N` times on each `events[]` entry.
  */
@@ -410,11 +410,9 @@ interface EventContext {
  *   `lifecycle` (foreground/background/session), `onboarding`,
  *   `notification`, `custom`.
  *
- * Both priorities post to `/sdk/ingest/batch` (Phase 3.1 envelope) with
- * automatic fallback to `/sdk/events/batch` when the V2 endpoint is
- * absent (old server) or rejects the request. `OfflineQueue` handles
- * network-failure durability for both queues via the `PostFn` injected by
- * `ApiClient.postWithQueue`.
+ * Both priorities post to `/sdk/ingest/batch`. On 4xx the event is dropped.
+ * On 5xx or network failure, `OfflineQueue` handles durability via the
+ * `PostFn` injected by `ApiClient.postWithQueue`.
  */
 type EventPriority = "critical" | "normal";
 interface TrackOptions {
@@ -588,6 +586,68 @@ declare const networkMonitor: NetworkMonitorClass;
  */
 type DistinctIdProvider = () => string;
 
+/**
+ * Attribution data captured at first touch (UTM params, click IDs, referrer).
+ * `capturedAt` is ISO 8601 UTC — generated automatically by `capture()`.
+ */
+interface AttributionCapture {
+    readonly utmSource?: string;
+    readonly utmMedium?: string;
+    readonly utmCampaign?: string;
+    readonly utmContent?: string;
+    readonly utmTerm?: string;
+    readonly fbclid?: string;
+    readonly gclid?: string;
+    readonly ttclid?: string;
+    readonly tiktokCampaignId?: string;
+    readonly tiktokAdgroupId?: string;
+    readonly tiktokAdId?: string;
+    readonly installReferrerRaw?: string;
+    readonly installReferrerSource?: string;
+    readonly referrer?: string;
+    readonly capturedAt: string;
+}
+type AttributionInput = Omit<AttributionCapture, "capturedAt">;
+/**
+ * Attribution module — first-write-wins persistence of UTM / click-ID data.
+ *
+ * Once a capture is stored, subsequent `capture()` calls are silently ignored.
+ * Use `clear()` to reset (e.g. on logout or in tests).
+ *
+ * @example
+ * await attributionTracker.capture({ utmSource: "google", gclid: "Cj0KCQ..." });
+ * const attr = attributionTracker.get(); // { utmSource: "google", capturedAt: "..." }
+ */
+declare class AttributionTracker {
+    private cache;
+    private captureInProgress;
+    private readonly storage;
+    constructor(debug?: boolean);
+    /**
+     * Load persisted attribution from storage into in-memory cache.
+     * Called once on SDK init. Subsequent `get()` reads are synchronous.
+     */
+    loadFromStorage(): Promise<void>;
+    /**
+     * Persist attribution data. First-write wins — ignores if already captured
+     * or if all fields are absent (empty capture).
+     *
+     * @param data - Attribution fields without `capturedAt` (generated internally).
+     */
+    capture(data: AttributionInput): Promise<void>;
+    /**
+     * Returns the persisted attribution capture, or `null` if none exists.
+     * Synchronous — reads from in-memory cache (populated via `loadFromStorage()`).
+     */
+    get(): AttributionCapture | null;
+    /**
+     * Clears the persisted attribution from storage and in-memory cache.
+     * After `clear()`, `get()` returns `null` and the next `capture()` writes normally.
+     */
+    clear(): Promise<void>;
+}
+declare const attributionTracker: AttributionTracker;
+
 declare class IdentityError extends PaywalloError {
     constructor(code: string, message: string);
 }
@@ -661,7 +721,11 @@ interface FcmRemoteMessage {
     notification?: {
         title?: string;
         body?: string;
+        imageUrl?: string;
     };
+    title?: string;
+    body?: string;
+    imageUrl?: string;
     sentTime?: number;
 }
 /**
@@ -734,7 +798,7 @@ type PushPermissionStatus = "granted" | "denied" | "provisional" | "notDetermine
  */
 type NotificationEventType = "notification_sent" | "notification_delivered" | "notification_displayed" | "notification_clicked" | "notification_dismissed" | "notification_failed" | "notification_converted";
 /**
- * Payload sent to `POST /api/v2/push-tokens`. Server schema matches 1:1:
+ * Payload sent to `POST /sdk/push-tokens`. Server schema matches 1:1:
  * `{ token, platform, distinct_id, app_version, sdk_version }`.
  *
  * Optional client-side extras (deviceId/locale/timezone) are kept for context
@@ -753,6 +817,7 @@ interface DeviceTokenRegistration {
 }
 interface NotificationPayload {
     notificationId: string;
+    messageId?: string;
     campaignId: string;
     variantKey?: string;
     title: string;
@@ -1440,7 +1505,7 @@ declare const ONBOARDING_ERROR_CODES: {
 /**
  * Minimal surface the OnboardingManager needs from the unified event pipeline.
  * `PaywalloClient` satisfies this interface (forwarding to
- * `ApiClient.trackEvent` → `EventBatcher` → `/api/v1/events/batch`).
+ * `ApiClient.trackEvent` → `EventBatcher` → `/sdk/ingest/batch`).
  */
 interface OnboardingEventPipeline {
     trackEvent(eventName: string, distinctId: string, properties?: Record<string, unknown>, timestamp?: number): Promise<void>;
@@ -1785,4 +1850,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { type AllPlansResponse, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };
+export { type AllPlansResponse, ApiClient, type ApiClientConfig, type AttributionCapture, AttributionTracker, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, attributionTracker, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };

package/dist/index.d.ts

@@ -378,7 +378,7 @@ declare const PaywalloContext: React.Context<PaywalloContextValue | null>;
  * event in the V2 ingest envelope. The provider is called at flush time so
  * each field reflects the most recent SDK state.
  *
- * The shape mirrors the server-side `/api/v2/ingest/batch` contract (Phase
+ * The shape mirrors the server-side `/sdk/ingest/batch` contract (Phase
  * 3.1). Fields declared here are deduplicated across the batch — they exist
  * once on the envelope instead of `N` times on each `events[]` entry.
  */
@@ -410,11 +410,9 @@ interface EventContext {
  *   `lifecycle` (foreground/background/session), `onboarding`,
  *   `notification`, `custom`.
  *
- * Both priorities post to `/sdk/ingest/batch` (Phase 3.1 envelope) with
- * automatic fallback to `/sdk/events/batch` when the V2 endpoint is
- * absent (old server) or rejects the request. `OfflineQueue` handles
- * network-failure durability for both queues via the `PostFn` injected by
- * `ApiClient.postWithQueue`.
+ * Both priorities post to `/sdk/ingest/batch`. On 4xx the event is dropped.
+ * On 5xx or network failure, `OfflineQueue` handles durability via the
+ * `PostFn` injected by `ApiClient.postWithQueue`.
  */
 type EventPriority = "critical" | "normal";
 interface TrackOptions {
@@ -588,6 +586,68 @@ declare const networkMonitor: NetworkMonitorClass;
  */
 type DistinctIdProvider = () => string;
 
+/**
+ * Attribution data captured at first touch (UTM params, click IDs, referrer).
+ * `capturedAt` is ISO 8601 UTC — generated automatically by `capture()`.
+ */
+interface AttributionCapture {
+    readonly utmSource?: string;
+    readonly utmMedium?: string;
+    readonly utmCampaign?: string;
+    readonly utmContent?: string;
+    readonly utmTerm?: string;
+    readonly fbclid?: string;
+    readonly gclid?: string;
+    readonly ttclid?: string;
+    readonly tiktokCampaignId?: string;
+    readonly tiktokAdgroupId?: string;
+    readonly tiktokAdId?: string;
+    readonly installReferrerRaw?: string;
+    readonly installReferrerSource?: string;
+    readonly referrer?: string;
+    readonly capturedAt: string;
+}
+type AttributionInput = Omit<AttributionCapture, "capturedAt">;
+/**
+ * Attribution module — first-write-wins persistence of UTM / click-ID data.
+ *
+ * Once a capture is stored, subsequent `capture()` calls are silently ignored.
+ * Use `clear()` to reset (e.g. on logout or in tests).
+ *
+ * @example
+ * await attributionTracker.capture({ utmSource: "google", gclid: "Cj0KCQ..." });
+ * const attr = attributionTracker.get(); // { utmSource: "google", capturedAt: "..." }
+ */
+declare class AttributionTracker {
+    private cache;
+    private captureInProgress;
+    private readonly storage;
+    constructor(debug?: boolean);
+    /**
+     * Load persisted attribution from storage into in-memory cache.
+     * Called once on SDK init. Subsequent `get()` reads are synchronous.
+     */
+    loadFromStorage(): Promise<void>;
+    /**
+     * Persist attribution data. First-write wins — ignores if already captured
+     * or if all fields are absent (empty capture).
+     *
+     * @param data - Attribution fields without `capturedAt` (generated internally).
+     */
+    capture(data: AttributionInput): Promise<void>;
+    /**
+     * Returns the persisted attribution capture, or `null` if none exists.
+     * Synchronous — reads from in-memory cache (populated via `loadFromStorage()`).
+     */
+    get(): AttributionCapture | null;
+    /**
+     * Clears the persisted attribution from storage and in-memory cache.
+     * After `clear()`, `get()` returns `null` and the next `capture()` writes normally.
+     */
+    clear(): Promise<void>;
+}
+declare const attributionTracker: AttributionTracker;
+
 declare class IdentityError extends PaywalloError {
     constructor(code: string, message: string);
 }
@@ -661,7 +721,11 @@ interface FcmRemoteMessage {
     notification?: {
         title?: string;
         body?: string;
+        imageUrl?: string;
     };
+    title?: string;
+    body?: string;
+    imageUrl?: string;
     sentTime?: number;
 }
 /**
@@ -734,7 +798,7 @@ type PushPermissionStatus = "granted" | "denied" | "provisional" | "notDetermine
  */
 type NotificationEventType = "notification_sent" | "notification_delivered" | "notification_displayed" | "notification_clicked" | "notification_dismissed" | "notification_failed" | "notification_converted";
 /**
- * Payload sent to `POST /api/v2/push-tokens`. Server schema matches 1:1:
+ * Payload sent to `POST /sdk/push-tokens`. Server schema matches 1:1:
  * `{ token, platform, distinct_id, app_version, sdk_version }`.
  *
  * Optional client-side extras (deviceId/locale/timezone) are kept for context
@@ -753,6 +817,7 @@ interface DeviceTokenRegistration {
 }
 interface NotificationPayload {
     notificationId: string;
+    messageId?: string;
     campaignId: string;
     variantKey?: string;
     title: string;
@@ -1440,7 +1505,7 @@ declare const ONBOARDING_ERROR_CODES: {
 /**
  * Minimal surface the OnboardingManager needs from the unified event pipeline.
  * `PaywalloClient` satisfies this interface (forwarding to
- * `ApiClient.trackEvent` → `EventBatcher` → `/api/v1/events/batch`).
+ * `ApiClient.trackEvent` → `EventBatcher` → `/sdk/ingest/batch`).
  */
 interface OnboardingEventPipeline {
     trackEvent(eventName: string, distinctId: string, properties?: Record<string, unknown>, timestamp?: number): Promise<void>;
@@ -1785,4 +1850,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { type AllPlansResponse, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };
+export { type AllPlansResponse, ApiClient, type ApiClientConfig, type AttributionCapture, AttributionTracker, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedOfferings, type CachedPlans, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type Offering, type OfferingProduct, OfferingService, type OfferingServiceConfig, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type Plan, PlanCache, type PlanProduct, PlanService, type PlanServiceConfig, type PlansResponse, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult$1 as RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, attributionTracker, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offeringService, offlineQueue, onboardingManager, parseVariables, planCache, planService, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOfferingPurchase, useOfferings, useOnboarding, usePaywallContext, usePaywallo, usePlanPurchase, usePlans, useProducts, usePurchase, useSubscription };