react-native-nami-sdk 3.4.4-dev.202606241952 → 3.4.4-dev.202606260324

package/android/build.gradle

@@ -85,8 +85,8 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
 
-    playImplementation "com.namiml:sdk-android:3.4.4-dev.202606241952"
-    amazonImplementation "com.namiml:sdk-amazon:3.4.4-dev.202606241952"
+    playImplementation "com.namiml:sdk-android:3.4.4-dev.202606260324"
+    amazonImplementation "com.namiml:sdk-amazon:3.4.4-dev.202606260324"
 
     implementation "com.facebook.react:react-native:+"  // From node_modules
     coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.4"

package/android/src/main/java/com/namiml/reactnative/{NamiCampaignManagerBridge.kt → NamiCampaignManagerBridgeModule.kt}

@@ -4,7 +4,17 @@ import android.app.Activity
 import android.net.Uri
 import android.util.Log
 import androidx.core.net.toUri
-import com.facebook.react.bridge.*
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Callback
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.ReadableType
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.bridge.WritableNativeArray
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.facebook.react.turbomodule.core.interfaces.TurboModule
@@ -106,7 +116,15 @@ class NamiCampaignManagerBridgeModule internal constructor(
                                             attr.getDouble(key)
                                         }
                                     }
-                                    ReadableType.Null -> ""
+                                    ReadableType.Null -> {
+                                        // A JSON null from JS must stay "not set". Coercing it to
+                                        // "" makes the launch-context presence check (raw != null)
+                                        // report it as "set" and reroutes flow branches (NAM-2227).
+                                        // Omit the key so it resolves to null, matching sdk/core and
+                                        // the Apple NSNull->nil normalization (NAM-1368).
+                                        Log.d(NAME, "customAttribute '$key' is null; omitting (treated as not set)")
+                                        continue
+                                    }
                                     ReadableType.Array -> attr.getArray(key)?.toArrayList() ?: emptyList<Any>()
                                     ReadableType.Map -> attr.getMap(key)?.toHashMap() ?: emptyMap<String, Any>()
                                 }
@@ -140,9 +158,15 @@ class NamiCampaignManagerBridgeModule internal constructor(
             }
 
             if (context.hasKey("productGroups")) {
-                paywallLaunchContext = PaywallLaunchContext(productGroups = productGroups.toList(), customAttributes = customAttributes, customObject = customObject)
+                paywallLaunchContext =
+                    PaywallLaunchContext(
+                        productGroups = productGroups.toList(),
+                        customAttributes = customAttributes,
+                        customObject = customObject,
+                    )
             } else {
-                paywallLaunchContext = PaywallLaunchContext(productGroups = null, customAttributes = customAttributes, customObject = customObject)
+                paywallLaunchContext =
+                    PaywallLaunchContext(productGroups = null, customAttributes = customAttributes, customObject = customObject)
             }
         }
 

package/android/src/main/java/com/namiml/reactnative/NamiFlowManagerBridgeModule.kt

@@ -8,11 +8,22 @@ import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.modules.core.DeviceEventManagerModule
 import com.facebook.react.turbomodule.core.interfaces.TurboModule
 import com.namiml.flow.NamiFlowManager
+import com.namiml.flow.NamiHandoffComplete
+import com.namiml.flow.NamiHandoffOutcome
+import com.namiml.flow.NamiLoginOutcome
+import com.namiml.flow.NamiLoginSuccess
+import com.namiml.flow.NamiPermissionOutcome
+import com.namiml.flow.NamiPurchaseOutcome
+import com.namiml.paywall.NamiSKU
+import com.namiml.paywall.model.NamiPurchaseSuccess
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
 
 @ReactModule(name = NamiFlowManagerBridgeModule.NAME)
 class NamiFlowManagerBridgeModule internal constructor(
@@ -31,13 +42,20 @@ class NamiFlowManagerBridgeModule internal constructor(
     @Volatile
     private var stepHandoffActive: Boolean = false
 
+    /** Pending handoff tokens keyed by handoffId. Thread-safe for concurrent complete() calls. */
+    private val pendingHandoffs = ConcurrentHashMap<String, NamiHandoffComplete>()
+
     @ReactMethod
     fun registerStepHandoff() {
         stepHandoffActive = true
-        NamiFlowManager.registerStepHandoff { handoffTag, handoffData ->
+        NamiFlowManager.registerStepHandoff { handoffTag, handoffData, complete ->
             if (!stepHandoffActive) return@registerStepHandoff
+            val handoffId = UUID.randomUUID().toString()
+            pendingHandoffs[handoffId] = complete
+
             val payload =
                 Arguments.createMap().apply {
+                    putString("handoffId", handoffId)
                     putString("handoffTag", handoffTag)
                     if (handoffData != null) {
                         try {
@@ -54,6 +72,30 @@ class NamiFlowManagerBridgeModule internal constructor(
         }
     }
 
+    /**
+     * Called from JS to complete a pending handoff with a typed outcome.
+     *
+     * The [outcome] map must include a "kind" key with one of: "done", "permission", "purchase",
+     * "login". Unknown kinds or malformed payloads emit a loud dev error and leave the token
+     * unconsumed (caller should call resume() to fall back to the legacy degrade path).
+     *
+     * A missing [handoffId] (e.g. after a Metro reload) logs a warning and returns — no crash.
+     */
+    @ReactMethod
+    fun completeHandoff(
+        handoffId: String,
+        outcome: ReadableMap,
+    ) {
+        val complete = pendingHandoffs.remove(handoffId)
+        if (complete == null) {
+            Log.w(NAME, "completeHandoff: no pending token for handoffId=$handoffId — ignoring (Metro reload?)")
+            return
+        }
+
+        val decoded = decodeOutcome(outcome) ?: return
+        complete(decoded)
+    }
+
     @ReactMethod
     fun unregisterStepHandoff() {
         stepHandoffActive = false
@@ -104,6 +146,224 @@ class NamiFlowManagerBridgeModule internal constructor(
         promise.resolve(NamiFlowManager.isFlowOpen())
     }
 
+    /**
+     * Decodes a JS outcome dict into the typed [NamiHandoffOutcome] sealed class.
+     *
+     * Returns null and emits a [Log.e] dev error on any validation failure; the caller must
+     * NOT invoke the completion token in that case.
+     */
+    private fun decodeOutcome(outcome: ReadableMap): NamiHandoffOutcome? {
+        val kind = outcome.getString("kind")
+        return when (kind) {
+            "done" -> NamiHandoffOutcome.Done
+
+            "permission" -> {
+                val permissionStr = outcome.getString("permission")
+                if (permissionStr == null) {
+                    Log.e(NAME, "completeHandoff: 'permission' field is required for kind='permission'")
+                    return null
+                }
+                val permissionType = resolvePermissionOutcome(permissionStr) ?: return null
+                val granted =
+                    if (outcome.hasKey("granted")) {
+                        outcome.getBoolean("granted")
+                    } else {
+                        Log.e(NAME, "completeHandoff: 'granted' field is required for kind='permission'")
+                        return null
+                    }
+                val detail = if (outcome.hasKey("detail")) outcome.getString("detail") else null
+                NamiHandoffOutcome.Permission(permissionType, granted, detail)
+            }
+
+            "purchase" -> {
+                val result = outcome.getString("result")
+                when (result) {
+                    "success" -> {
+                        val detailsMap = if (outcome.hasKey("details")) outcome.getMap("details") else null
+                        if (detailsMap == null) {
+                            Log.e(NAME, "completeHandoff: 'details' map is required for kind='purchase', result='success'")
+                            return null
+                        }
+                        val purchaseSuccess = decodePurchaseSuccess(detailsMap) ?: return null
+                        NamiHandoffOutcome.Purchase(NamiPurchaseOutcome.Success(purchaseSuccess))
+                    }
+                    "cancelled" -> NamiHandoffOutcome.Purchase(NamiPurchaseOutcome.Cancelled)
+                    "failed" -> NamiHandoffOutcome.Purchase(NamiPurchaseOutcome.Failed())
+                    else -> {
+                        Log.e(NAME, "completeHandoff: unknown purchase result='$result'; expected 'success', 'cancelled', or 'failed'")
+                        null
+                    }
+                }
+            }
+
+            "login" -> {
+                val result = outcome.getString("result")
+                when (result) {
+                    "success" -> {
+                        val detailsMap = if (outcome.hasKey("details")) outcome.getMap("details") else null
+                        if (detailsMap == null) {
+                            Log.e(NAME, "completeHandoff: 'details' map is required for kind='login', result='success'")
+                            return null
+                        }
+                        val loginSuccess = decodeLoginSuccess(detailsMap) ?: return null
+                        NamiHandoffOutcome.Login(NamiLoginOutcome.Success(loginSuccess))
+                    }
+                    "cancelled" -> NamiHandoffOutcome.Login(NamiLoginOutcome.Cancelled)
+                    "failed" -> NamiHandoffOutcome.Login(NamiLoginOutcome.Failed())
+                    else -> {
+                        Log.e(NAME, "completeHandoff: unknown login result='$result'; expected 'success', 'cancelled', or 'failed'")
+                        null
+                    }
+                }
+            }
+
+            else -> {
+                Log.e(NAME, "completeHandoff: unknown kind='$kind'; expected 'done', 'permission', 'purchase', or 'login'")
+                null
+            }
+        }
+    }
+
+    /**
+     * Maps a wire permission string (case-insensitive) to [NamiPermissionOutcome].
+     * Unknown values emit a [Log.e] and return null.
+     */
+    private fun resolvePermissionOutcome(wire: String): NamiPermissionOutcome? {
+        // Case-insensitive match against enum entry names (Push, Location, Tracking, …)
+        return NamiPermissionOutcome.entries.firstOrNull {
+            it.name.equals(wire, ignoreCase = true)
+        } ?: run {
+            val valid = NamiPermissionOutcome.entries.joinToString { it.name.lowercase() }
+            Log.e(NAME, "completeHandoff: unknown permission='$wire'; valid values: $valid")
+            null
+        }
+    }
+
+    /**
+     * Decodes the `details` sub-map for a purchase/success outcome into [NamiPurchaseSuccess].
+     *
+     * Mirrors the field layout already used by [NamiPaywallManagerBridgeModule.buySkuComplete]:
+     * - `product.id`  → skuId (the Nami reference ID)
+     * - `product.skuId` → skuRefId (the store product ID)
+     * - `storeType` → "GooglePlay" or "Amazon"
+     * - GooglePlay: `orderId`, `purchaseToken`
+     * - Amazon: `receiptId`, `localizedPrice`, `userId`, `marketplace`
+     */
+    private fun decodePurchaseSuccess(details: ReadableMap): NamiPurchaseSuccess? {
+        val productMap = if (details.hasKey("product")) details.getMap("product") else null
+        val productId = productMap?.getString("id")
+        val skuRefId = productMap?.getString("skuId")
+
+        if (productId == null || skuRefId == null) {
+            // TODO(NAM-1560): construct NamiPurchaseSuccess from map — product.id and product.skuId
+            //   are required but missing or null. The JS caller must supply a NamiSKU-shaped product
+            //   map with at least {id, skuId} fields (matching the buySkuComplete wire format).
+            Log.e(NAME, "completeHandoff: purchase/success 'details.product' must include 'id' and 'skuId'")
+            return null
+        }
+
+        val namiSku =
+            NamiSKU.create(
+                skuId = productId,
+                skuRefId = skuRefId,
+            )
+
+        val storeType = details.getString("storeType") ?: "GooglePlay"
+
+        return when (storeType) {
+            "GooglePlay" -> {
+                val orderId = details.getString("orderId")
+                val purchaseToken = details.getString("purchaseToken")
+                if (orderId == null || purchaseToken == null) {
+                    Log.e(NAME, "completeHandoff: purchase/success GooglePlay requires 'orderId' and 'purchaseToken'")
+                    return null
+                }
+                NamiPurchaseSuccess.GooglePlay(
+                    product = namiSku,
+                    orderId = orderId,
+                    purchaseToken = purchaseToken,
+                )
+            }
+            "Amazon" -> {
+                val receiptId = details.getString("receiptId")
+                val localizedPrice = details.getString("localizedPrice")
+                val userId = details.getString("userId")
+                val marketplace = details.getString("marketplace")
+                if (receiptId == null || localizedPrice == null || userId == null || marketplace == null) {
+                    Log.e(
+                        NAME,
+                        "completeHandoff: purchase/success Amazon requires 'receiptId', 'localizedPrice', 'userId', and 'marketplace'",
+                    )
+                    return null
+                }
+                NamiPurchaseSuccess.Amazon(
+                    product = namiSku,
+                    receiptId = receiptId,
+                    localizedPrice = localizedPrice,
+                    userId = userId,
+                    marketplace = marketplace,
+                )
+            }
+            else -> {
+                Log.e(NAME, "completeHandoff: unknown storeType='$storeType'; expected 'GooglePlay' or 'Amazon'")
+                null
+            }
+        }
+    }
+
+    /**
+     * Decodes the `details` sub-map for a login/success outcome into [NamiLoginSuccess].
+     *
+     * The `attributes` map must contain only primitive values (String, Number, Boolean).
+     * Non-primitive values emit a [Log.e] and abort the decode — [NamiLoginSuccess.init]
+     * would throw on them anyway; we surface a clean dev error instead.
+     */
+    private fun decodeLoginSuccess(details: ReadableMap): NamiLoginSuccess? {
+        val loginId = details.getString("loginId")
+        if (loginId.isNullOrEmpty()) {
+            Log.e(NAME, "completeHandoff: login/success 'details.loginId' is required and must be non-empty")
+            return null
+        }
+
+        val cdpId = if (details.hasKey("cdpId")) details.getString("cdpId") else null
+
+        val attributes: Map<String, Any>? =
+            if (details.hasKey("attributes")) {
+                val attrsMap = details.getMap("attributes")
+                if (attrsMap != null) {
+                    val raw = attrsMap.toHashMap()
+                    // Validate that all values are primitives before handing to NamiLoginSuccess.
+                    val invalid = raw.entries.firstOrNull { (_, v) -> v !is String && v !is Number && v !is Boolean }
+                    if (invalid != null) {
+                        Log.e(
+                            NAME,
+                            "completeHandoff: login/success attributes['${invalid.key}'] must be a primitive " +
+                                "(String/Number/Boolean); got ${invalid.value?.let { it::class.simpleName } ?: "null"}",
+                        )
+                        return null
+                    }
+                    @Suppress("UNCHECKED_CAST")
+                    raw as Map<String, Any>
+                } else {
+                    null
+                }
+            } else {
+                null
+            }
+
+        return try {
+            NamiLoginSuccess(
+                loginId = loginId,
+                cdpId = cdpId,
+                attributes = attributes,
+            )
+        } catch (e: IllegalArgumentException) {
+            // NamiLoginSuccess.init validates attribute primitives — surface the message clearly.
+            Log.e(NAME, "completeHandoff: NamiLoginSuccess rejected attributes — ${e.message}")
+            null
+        }
+    }
+
     private fun sendEvent(
         eventName: String,
         params: WritableMap?,

package/dist/specs/NativeNamiFlowManager.d.ts

@@ -1,9 +1,11 @@
 import type { TurboModule } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
 export interface Spec extends TurboModule {
     finish(): void;
     isFlowOpen(): Promise<boolean>;
     registerStepHandoff(): void;
     unregisterStepHandoff(): void;
+    completeHandoff(handoffId: string, outcome: UnsafeObject): void;
     resume(): void;
     pause(): void;
     registerEventHandler(): void;

package/dist/src/NamiFlowManager.d.ts

@@ -1,11 +1,12 @@
 import { NativeEventEmitter } from 'react-native';
+import type { NamiFlowHandoffStepHandler } from './types';
 export declare enum NamiFlowManagerEvents {
     Handoff = "Handoff",
     FlowEvent = "FlowEvent"
 }
 export declare const NamiFlowManager: {
     emitter: NativeEventEmitter;
-    registerStepHandoff: (callback: (handoffTag: string, handoffData?: Record<string, unknown>) => void) => (() => void);
+    registerStepHandoff: (callback: NamiFlowHandoffStepHandler) => (() => void);
     resume: () => void;
     pause: () => void;
     registerEventHandler: (callback: (payload: Record<string, unknown>) => void) => (() => void);

package/dist/src/types.d.ts

@@ -127,7 +127,15 @@ export type NamiEntitlement = {
     referenceId: string;
     relatedSkus: NamiSKU[];
 };
-export type NamiPurchaseDetails = {
+/**
+ * Host-managed purchase payload handed back to the SDK on a successful
+ * `buysku` handoff (`complete({ kind: 'purchase', result: 'success', details })`).
+ * Fields are a superset across stores; the native bridge maps them onto the
+ * platform's own `NamiPurchaseSuccess` (Apple flat class / Android sealed
+ * GooglePlay|Amazon) at the boundary. Renamed from `NamiPurchaseDetails` for
+ * cross-SDK naming consistency (NAM-1560 §2.3).
+ */
+export type NamiPurchaseSuccess = {
     product: NamiSKU;
     transactionID?: string;
     originalTransactionID?: string;
@@ -141,6 +149,12 @@ export type NamiPurchaseDetails = {
     marketplace?: string;
     storeType?: string;
 };
+/**
+ * @deprecated Renamed to {@link NamiPurchaseSuccess} for cross-SDK naming
+ * consistency. Structurally identical; kept so existing host code keeps
+ * compiling. Prefer `NamiPurchaseSuccess` in new code.
+ */
+export type NamiPurchaseDetails = NamiPurchaseSuccess;
 export type NamiPurchaseSuccessApple = {
     product: NamiSKU;
     transactionID: string;
@@ -244,10 +258,107 @@ export type NamiPaywallEventVideoMetadata = {
     contentTimecode?: number;
     contentDuration?: number;
 };
+/**
+ * Native → JS handoff delivery payload. `handoffId` correlates the eventual
+ * `complete(outcome)` back to the native pending handoff (NAM-1560 §2.8).
+ */
 export type NamiFlowHandoffPayload = {
+    handoffId: string;
     handoffTag: string;
     handoffData?: Record<string, unknown>;
 };
+/** Open-ended host-asserted attribute values — primitives only (no nesting). */
+export type NamiHandoffAttributeValue = string | number | boolean;
+/**
+ * Host-asserted login result. Only `loginId` is required. `attributes` is
+ * open-ended experience data (e.g. `{ subscriberStatus, subscribedTier }`) read
+ * by branch conditions and smart text via `login.<hostKey>`; never merged into
+ * Nami subscriber state and never touches entitlements.
+ */
+export type NamiLoginSuccess = {
+    loginId: string;
+    cdpId?: string;
+    attributes?: Record<string, NamiHandoffAttributeValue>;
+};
+/** Permission types reportable from a handoff. Tier-1 (push/location/tracking)
+ *  carry completion wire values natively; the rest are state/lifecycle only. */
+export declare const NamiPermissionOutcome: {
+    readonly Push: "push";
+    readonly Location: "location";
+    readonly Tracking: "tracking";
+    readonly Camera: "camera";
+    readonly Microphone: "microphone";
+    readonly Photos: "photos";
+    readonly Contacts: "contacts";
+    readonly Bluetooth: "bluetooth";
+    readonly Calendar: "calendar";
+    readonly Biometrics: "biometrics";
+    readonly Health: "health";
+    readonly Motion: "motion";
+    readonly Speech: "speech";
+    readonly LocalNetwork: "localNetwork";
+};
+export type NamiPermissionOutcome = (typeof NamiPermissionOutcome)[keyof typeof NamiPermissionOutcome];
+/** Typed outcome reported by the host's `complete(...)`. Discriminated on `kind`
+ *  (purchase/login further discriminated on `result`). */
+export type NamiHandoffOutcome = {
+    kind: 'done';
+} | {
+    kind: 'permission';
+    permission: NamiPermissionOutcome;
+    granted: boolean;
+    detail?: string;
+} | {
+    kind: 'purchase';
+    result: 'success';
+    details: NamiPurchaseSuccess;
+} | {
+    kind: 'purchase';
+    result: 'cancelled';
+} | {
+    kind: 'purchase';
+    result: 'failed';
+    error?: unknown;
+} | {
+    kind: 'login';
+    result: 'success';
+    details: NamiLoginSuccess;
+} | {
+    kind: 'login';
+    result: 'cancelled';
+} | {
+    kind: 'login';
+    result: 'failed';
+    error?: unknown;
+};
+/** Per-handoff completion callback. Bare `complete()` ≙ `complete({kind:'done'})`. */
+export type NamiHandoffComplete = (outcome?: NamiHandoffOutcome) => void;
+/** The single handoff handler shape (NAM-1560 §2.1 — no dual registration). */
+export type NamiFlowHandoffStepHandler = (handoffTag: string, handoffData: Record<string, unknown> | undefined, complete: NamiHandoffComplete) => void;
+/** Closed-but-extensible handoff tag vocabulary (mirrors the builder's
+ *  `FlowHandoffTag`, minus `__*__` internals). Unknown future tags still pass. */
+export declare const NamiHandoffTag: {
+    readonly Push: "push";
+    readonly Location: "location";
+    readonly Tracking: "att";
+    readonly Deeplink: "deeplink";
+    readonly Complete: "complete";
+    readonly SignIn: "signin";
+    readonly Restore: "restore";
+    readonly SignInMvpd: "signin_mvpd";
+    readonly BuySku: "buysku";
+    readonly UserData: "userdata";
+};
+export type NamiKnownHandoffTag = (typeof NamiHandoffTag)[keyof typeof NamiHandoffTag];
+export type NamiHandoffTagValue = NamiKnownHandoffTag | (string & {});
+/** Outbound `userdata` envelope (Nami → customer) delivered with the `userdata` tag. */
+export type NamiUserDataEnvelope = {
+    form_id: string;
+    step_id: string;
+    /** ISO-8601 UTC timestamp of delivery. */
+    collected_at: string;
+    fields: Record<string, boolean | string>;
+};
 export type NamiAccountStateEvent = {
     action: AccountStateAction;
     success: boolean;

package/dist/src/version.d.ts

@@ -2,4 +2,4 @@
  * Auto-generated file. Do not edit manually.
  * React Native Nami SDK version.
  */
-export declare const NAMI_REACT_NATIVE_VERSION = "3.4.4-dev.202606241952";
+export declare const NAMI_REACT_NATIVE_VERSION = "3.4.4-dev.202606260324";

package/ios/NamiFlowManagerBridge.m

@@ -17,6 +17,7 @@ RCT_EXTERN_METHOD(resume)
 RCT_EXTERN_METHOD(pause)
 RCT_EXTERN_METHOD(finish)
 RCT_EXTERN_METHOD(isFlowOpen:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(completeHandoff:(NSString *)handoffId outcome:(NSDictionary *)outcome)
 
 + (BOOL)requiresMainQueueSetup {
   return YES;

package/ios/NamiFlowManagerBridge.swift

@@ -11,7 +11,7 @@ import React
 
 @objc(RNNamiFlowManager)
 class RNNamiFlowManager: RCTEventEmitter {
-    public static var shared: RNNamiFlowManager?
+    static var shared: RNNamiFlowManager?
 
     override init() {
         super.init()
@@ -44,11 +44,28 @@ class RNNamiFlowManager: RCTEventEmitter {
         return ["Handoff", "FlowEvent"]
     }
 
+    // MARK: - Pending handoff completion token storage
+
+    /// Serial queue used to synchronise all reads/writes of `pendingHandoffs`.
+    private let handoffQueue = DispatchQueue(label: "com.namiml.rn.flow-manager.handoffs")
+    /// Maps handoff UUID strings to their in-flight completion tokens.
+    private var pendingHandoffs: [String: NamiHandoffCompletion] = [:]
+
+    // MARK: - Step-handoff registration
+
     @objc func registerStepHandoff() {
         stepHandoffActive = true
-        NamiFlowManager.registerStepHandoff { [weak self] tag, data in
+        NamiFlowManager.registerStepHandoff { [weak self] tag, data, complete in
             guard let self = self, self.stepHandoffActive else { return }
+
+            // Generate a UUID and store the completion token thread-safely.
+            let handoffId = UUID().uuidString
+            self.handoffQueue.sync {
+                self.pendingHandoffs[handoffId] = complete
+            }
+
             var payload: [String: Any] = [
+                "handoffId": handoffId,
                 "handoffTag": tag,
             ]
             if let data = data {
@@ -63,6 +80,217 @@ class RNNamiFlowManager: RCTEventEmitter {
         stepHandoffActive = false
     }
 
+    // MARK: - Complete handoff (called from JS)
+
+    /**
+     Resolves a pending handoff by decoding the outcome dict sent from JavaScript
+     and calling the stored `NamiHandoffCompletion` token.
+
+     - Parameter handoffId: The UUID string previously emitted in the `Handoff` event.
+     - Parameter outcome: Discriminated-union dict produced by the TS bridge, e.g.
+       `{ "kind": "done" }` or `{ "kind": "login", "result": "success", … }`.
+     */
+    @objc func completeHandoff(_ handoffId: String, outcome: NSDictionary) {
+        // Look up and remove the token atomically so it can only fire once.
+        var token: NamiHandoffCompletion?
+        handoffQueue.sync {
+            token = pendingHandoffs.removeValue(forKey: handoffId)
+        }
+
+        guard let complete = token else {
+            // Stale call — harmless after a Metro reload or duplicate invocation.
+            print("[RNNamiFlowManager] Warning: completeHandoff called with unknown or already-consumed handoffId '\(handoffId)'. Ignoring.")
+            return
+        }
+
+        guard let decoded = decodeOutcome(outcome, handoffId: handoffId) else {
+            // decodeOutcome already logged the error; do NOT call complete.
+            return
+        }
+
+        complete(decoded)
+    }
+
+    // MARK: - Outcome decoder
+
+    /**
+     Decodes a JS outcome dict into a typed `NamiHandoffOutcome`.
+
+     Returns `nil` and logs a loud dev-mode error for any invalid payload so that
+     `completeHandoff` never delivers a malformed outcome to the flow engine.
+     */
+    private func decodeOutcome(_ outcome: NSDictionary, handoffId: String) -> NamiHandoffOutcome? {
+        guard let kind = outcome["kind"] as? String else {
+            logDecodeError(handoffId: handoffId, message: "outcome dict is missing required 'kind' field. Received: \(outcome)")
+            return nil
+        }
+
+        switch kind {
+        case "done":
+            return .done
+
+        case "permission":
+            guard let permissionString = outcome["permission"] as? String else {
+                logDecodeError(handoffId: handoffId, message: "'permission' kind requires a 'permission' String field. Received: \(outcome)")
+                return nil
+            }
+            guard let perm = NamiPermissionOutcome(rawValue: permissionString) else {
+                logDecodeError(handoffId: handoffId, message: "Unknown NamiPermissionOutcome rawValue '\(permissionString)'. Received: \(outcome)")
+                return nil
+            }
+            guard let granted = outcome["granted"] as? Bool else {
+                logDecodeError(handoffId: handoffId, message: "'permission' kind requires a 'granted' Bool field. Received: \(outcome)")
+                return nil
+            }
+            let detail = outcome["detail"] as? String
+            return .permission(perm, granted: granted, detail: detail)
+
+        case "purchase":
+            guard let result = outcome["result"] as? String else {
+                logDecodeError(handoffId: handoffId, message: "'purchase' kind requires a 'result' String field. Received: \(outcome)")
+                return nil
+            }
+            switch result {
+            case "success":
+                guard let details = outcome["details"] as? [String: Any] else {
+                    logDecodeError(handoffId: handoffId, message: "'purchase/success' requires a 'details' dict. Received: \(outcome)")
+                    return nil
+                }
+                guard let purchaseSuccess = buildPurchaseSuccess(from: details, handoffId: handoffId) else {
+                    // buildPurchaseSuccess already logged the specific error.
+                    return nil
+                }
+                return .purchase(.success(purchaseSuccess))
+            case "cancelled":
+                return .purchase(.cancelled)
+            case "failed":
+                return .purchase(.failed(nil))
+            default:
+                logDecodeError(handoffId: handoffId, message: "Unknown 'purchase' result '\(result)'. Expected 'success', 'cancelled', or 'failed'. Received: \(outcome)")
+                return nil
+            }
+
+        case "login":
+            guard let result = outcome["result"] as? String else {
+                logDecodeError(handoffId: handoffId, message: "'login' kind requires a 'result' String field. Received: \(outcome)")
+                return nil
+            }
+            switch result {
+            case "success":
+                guard let details = outcome["details"] as? [String: Any] else {
+                    logDecodeError(handoffId: handoffId, message: "'login/success' requires a 'details' dict. Received: \(outcome)")
+                    return nil
+                }
+                guard let loginId = details["loginId"] as? String else {
+                    logDecodeError(handoffId: handoffId, message: "'login/success' details missing required 'loginId' String. Received: \(details)")
+                    return nil
+                }
+                let cdpId = details["cdpId"] as? String
+                let rawAttrs = details["attributes"] as? [String: Any] ?? [:]
+
+                // Validate that every attribute value is a supported primitive.
+                for (key, value) in rawAttrs {
+                    guard NamiHandoffAttributeValue(value) != nil else {
+                        logDecodeError(handoffId: handoffId, message: "Login attribute '\(key)' has unsupported value type \(type(of: value)). Only String, Bool, Int, and Double are allowed. Received: \(value)")
+                        return nil
+                    }
+                }
+
+                let loginSuccess = NamiLoginSuccess(loginId: loginId, cdpId: cdpId, attributes: rawAttrs)
+                return .login(.success(loginSuccess))
+            case "cancelled":
+                return .login(.cancelled)
+            case "failed":
+                return .login(.failed(nil))
+            default:
+                logDecodeError(handoffId: handoffId, message: "Unknown 'login' result '\(result)'. Expected 'success', 'cancelled', or 'failed'. Received: \(outcome)")
+                return nil
+            }
+
+        default:
+            logDecodeError(handoffId: handoffId, message: "Unknown outcome 'kind' '\(kind)'. Expected 'done', 'permission', 'purchase', or 'login'. Received: \(outcome)")
+            return nil
+        }
+    }
+
+    // MARK: - NamiPurchaseSuccess builder
+
+    /**
+     Builds a `NamiPurchaseSuccess` from the 'details' sub-dict of a purchase/success outcome.
+
+     Mirrors the construction logic already used by `RNNamiPaywallManager.buySkuComplete`.
+     Returns `nil` and logs a dev error on any missing or invalid field.
+     */
+    private func buildPurchaseSuccess(from details: [String: Any], handoffId: String) -> NamiPurchaseSuccess? {
+        guard let product = details["product"] as? [String: Any] else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' details missing 'product' dict. Received: \(details)")
+            return nil
+        }
+        guard let storeId = product["skuId"] as? String else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' product missing 'skuId' String. Received: \(product)")
+            return nil
+        }
+        guard let namiId = product["id"] as? String else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' product missing 'id' String. Received: \(product)")
+            return nil
+        }
+        let skuTypeString = product["type"] as? String ?? "unknown"
+        let namiSkuType: NamiSKUType
+        switch skuTypeString {
+        case "one_time_purchase":
+            namiSkuType = .one_time_purchase
+        case "subscription":
+            namiSkuType = .subscription
+        default:
+            namiSkuType = .unknown
+        }
+        let namiSku = NamiSKU(namiId: namiId, storeId: storeId, skuType: namiSkuType)
+
+        guard let transactionID = details["transactionID"] as? String else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' details missing 'transactionID' String. Received: \(details)")
+            return nil
+        }
+        guard let originalTransactionID = details["originalTransactionID"] as? String else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' details missing 'originalTransactionID' String. Received: \(details)")
+            return nil
+        }
+        guard let currencyCode = details["currencyCode"] as? String else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' details missing 'currencyCode' String. Received: \(details)")
+            return nil
+        }
+
+        // Accept price as either a Decimal-bridged NSDecimalNumber, a Double, or a String.
+        let price: Decimal
+        if let decimalNumber = details["price"] as? NSDecimalNumber {
+            price = decimalNumber as Decimal
+        } else if let doubleValue = details["price"] as? Double {
+            price = Decimal(doubleValue)
+        } else if let priceString = details["price"] as? String, let parsed = Decimal(string: priceString) {
+            price = parsed
+        } else {
+            logDecodeError(handoffId: handoffId, message: "'purchase/success' details missing or unparseable 'price'. Received: \(details)")
+            return nil
+        }
+
+        return NamiPurchaseSuccess(
+            product: namiSku,
+            transactionID: transactionID,
+            originalTransactionID: originalTransactionID,
+            price: price,
+            currencyCode: currencyCode
+        )
+    }
+
+    // MARK: - Error logging helper
+
+    private func logDecodeError(handoffId: String, message: String) {
+        let fullMessage = "[RNNamiFlowManager] completeHandoff decode error (handoffId='\(handoffId)'): \(message)"
+        print(fullMessage)
+        #if DEBUG
+            assertionFailure(fullMessage)
+        #endif
+    }
+
     @objc func registerEventHandler() {
         eventHandlerActive = true
         NamiFlowManager.registerEventHandler { [weak self] payload in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nami-sdk",
-  "version": "3.4.4-dev.202606241952",
+  "version": "3.4.4-dev.202606260324",
   "description": "React Native SDK for Nami - No-code paywall and onboarding flows with A/B testing.",
   "main": "index.ts",
   "types": "dist/index.d.ts",

package/react-native-nami-sdk.podspec

@@ -21,7 +21,7 @@ Pod::Spec.new do |s|
   s.requires_arc  = true
   s.swift_version = '5.0'  # or your supported version
 
-  s.dependency 'Nami', '3.4.4-dev.202606241952'
+  s.dependency 'Nami', '3.4.4-dev.202606260324'
 
   pod_target_xcconfig = {
     'DEFINES_MODULE' => 'YES',

package/specs/NativeNamiFlowManager.ts

@@ -1,5 +1,6 @@
 import type { TurboModule } from 'react-native';
 import { TurboModuleRegistry } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
 
 export interface Spec extends TurboModule {
   finish(): void;
@@ -7,6 +8,12 @@ export interface Spec extends TurboModule {
 
   registerStepHandoff(): void;
   unregisterStepHandoff(): void;
+  // Reports a typed handoff outcome for a specific delivered handoff and resumes
+  // the flow. `handoffId` correlates the call back to the native pending handoff
+  // (TurboModule callbacks can't hold per-call closures). `outcome` is always
+  // required on the wire — the bare `complete()` case is normalized to
+  // `{ kind: 'done' }` in the JS wrapper before crossing the bridge (NAM-1560 §2.8).
+  completeHandoff(handoffId: string, outcome: UnsafeObject): void;
   resume(): void;
   pause(): void;
   registerEventHandler(): void;

package/src/NamiFlowManager.ts

@@ -4,7 +4,12 @@ import {
   NativeEventEmitter,
 } from 'react-native';
 import type { Spec } from '../specs/NativeNamiFlowManager';
-import type { NamiFlowHandoffPayload } from '../src/types';
+import type {
+  NamiFlowHandoffPayload,
+  NamiFlowHandoffStepHandler,
+  NamiHandoffComplete,
+  NamiHandoffOutcome,
+} from './types';
 
 const RNNamiFlowManager: Spec =
   TurboModuleRegistry.getEnforcing?.<Spec>('RNNamiFlowManager') ??
@@ -20,19 +25,39 @@ export enum NamiFlowManagerEvents {
 export const NamiFlowManager = {
   emitter,
 
-  registerStepHandoff: (
-    callback: (
-      handoffTag: string,
-      handoffData?: Record<string, unknown>,
-    ) => void,
-  ): (() => void) => {
+  registerStepHandoff: (callback: NamiFlowHandoffStepHandler): (() => void) => {
     console.info('[NamiFlowManager] Registering step handoff listener...');
 
     const sub = emitter.addListener(
       NamiFlowManagerEvents.Handoff,
       (event: NamiFlowHandoffPayload) => {
         console.info('[NamiFlowManager] Received handoff event:', event);
-        callback(event.handoffTag, event.handoffData);
+
+        // Manufacture the per-handoff completion callback. The native event
+        // carries a `handoffId` that correlates this call back to the native
+        // pending handoff (TurboModule callbacks can't hold per-call closures).
+        let completed = false;
+        const complete: NamiHandoffComplete = (
+          outcome?: NamiHandoffOutcome,
+        ) => {
+          if (completed) {
+            console.warn(
+              `[NamiFlowManager] complete() called more than once for handoff '${event.handoffTag}' — ignored`,
+            );
+            return;
+          }
+          completed = true;
+          // The ONE bridge-side defaulting point: bare complete() ≙ done.
+          // `outcome` stays required on the wire (native never sees a null).
+          const normalized: NamiHandoffOutcome = outcome ?? { kind: 'done' };
+          RNNamiFlowManager.completeHandoff?.(event.handoffId, normalized);
+        };
+
+        // Single handler shape `(tag, data, complete)`. Legacy `(tag, data)`
+        // handlers still run — the extra arg is ignored — and their `resume()`
+        // degrades to done-with-warning natively (the native pending token owns
+        // that, surviving Metro fast-refresh wiping this closure).
+        callback(event.handoffTag, event.handoffData, complete);
       },
     );
 

package/src/__tests__/NamiFlowManager.test.ts

@@ -6,13 +6,21 @@ const registerStepHandoff = jest.fn();
 const unregisterStepHandoff = jest.fn();
 const registerEventHandler = jest.fn();
 const unregisterEventHandler = jest.fn();
+const completeHandoff = jest.fn();
 const finishMock = jest.fn();
 const isFlowOpenMock = jest.fn().mockResolvedValue(false);
 const resumeMock = jest.fn();
 const pauseMock = jest.fn();
 
 const subRemove = jest.fn();
-const addListener = jest.fn(() => ({ remove: subRemove }));
+// Capture the registered listener per event name so tests can fire native events.
+const listeners: Record<string, (event: unknown) => void> = {};
+const addListener = jest.fn(
+  (eventName: string, handler: (e: unknown) => void) => {
+    listeners[eventName] = handler;
+    return { remove: subRemove };
+  },
+);
 
 jest.mock('react-native', () => ({
   TurboModuleRegistry: {
@@ -21,6 +29,7 @@ jest.mock('react-native', () => ({
       unregisterStepHandoff,
       registerEventHandler,
       unregisterEventHandler,
+      completeHandoff,
       finish: finishMock,
       isFlowOpen: isFlowOpenMock,
       resume: resumeMock,
@@ -33,6 +42,7 @@ jest.mock('react-native', () => ({
       unregisterStepHandoff,
       registerEventHandler,
       unregisterEventHandler,
+      completeHandoff,
     },
   },
   NativeEventEmitter: jest.fn().mockImplementation(() => ({
@@ -41,6 +51,16 @@ jest.mock('react-native', () => ({
 }));
 
 import { NamiFlowManager } from '../NamiFlowManager';
+import type { NamiHandoffOutcome } from '../types';
+
+/** Fire a native `Handoff` event into the captured emitter listener. */
+function fireHandoff(event: {
+  handoffId: string;
+  handoffTag: string;
+  handoffData?: Record<string, unknown>;
+}) {
+  listeners.Handoff?.(event);
+}
 
 describe('NamiFlowManager (React Native bridge)', () => {
   beforeEach(() => {
@@ -48,6 +68,8 @@ describe('NamiFlowManager (React Native bridge)', () => {
     unregisterStepHandoff.mockClear();
     registerEventHandler.mockClear();
     unregisterEventHandler.mockClear();
+    completeHandoff.mockClear();
+    resumeMock.mockClear();
     subRemove.mockClear();
     addListener.mockClear();
   });
@@ -69,6 +91,98 @@ describe('NamiFlowManager (React Native bridge)', () => {
     });
   });
 
+  describe('handoff outcome token bridge', () => {
+    it('delivers (tag, data, complete) and correlates complete() back to the handoffId', () => {
+      const handler = jest.fn(
+        (_tag: string, _data: unknown, complete: () => void) => complete(),
+      );
+      NamiFlowManager.registerStepHandoff(handler);
+
+      fireHandoff({
+        handoffId: 'h1',
+        handoffTag: 'signin',
+        handoffData: { a: 1 },
+      });
+
+      expect(handler).toHaveBeenCalledWith(
+        'signin',
+        { a: 1 },
+        expect.any(Function),
+      );
+      // Bare complete() is normalized to {kind:'done'} before crossing the bridge.
+      expect(completeHandoff).toHaveBeenCalledTimes(1);
+      expect(completeHandoff).toHaveBeenCalledWith('h1', { kind: 'done' });
+    });
+
+    it('forwards an explicit outcome verbatim (incl. primitive login attributes)', () => {
+      const outcome: NamiHandoffOutcome = {
+        kind: 'login',
+        result: 'success',
+        details: {
+          loginId: 'user-123',
+          attributes: { subscriberStatus: 'active', seats: 3, trial: false },
+        },
+      };
+      NamiFlowManager.registerStepHandoff((_t, _d, complete) =>
+        complete(outcome),
+      );
+
+      fireHandoff({ handoffId: 'h2', handoffTag: 'signin' });
+
+      expect(completeHandoff).toHaveBeenCalledWith('h2', outcome);
+    });
+
+    it('is once-only per handoff — a second complete() warns and does not re-cross the bridge', () => {
+      const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+      NamiFlowManager.registerStepHandoff((_t, _d, complete) => {
+        complete({ kind: 'purchase', result: 'cancelled' });
+        complete(); // duplicate — must be ignored
+      });
+
+      fireHandoff({ handoffId: 'h3', handoffTag: 'buysku' });
+
+      expect(completeHandoff).toHaveBeenCalledTimes(1);
+      expect(completeHandoff).toHaveBeenCalledWith('h3', {
+        kind: 'purchase',
+        result: 'cancelled',
+      });
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('called more than once'),
+      );
+      warn.mockRestore();
+    });
+
+    it('correlates concurrent handoffs to their own ids independently', () => {
+      const completes: Record<string, () => void> = {};
+      NamiFlowManager.registerStepHandoff((tag, _d, complete) => {
+        completes[tag] = complete;
+      });
+
+      fireHandoff({ handoffId: 'hA', handoffTag: 'push' });
+      fireHandoff({ handoffId: 'hB', handoffTag: 'location' });
+
+      completes.location();
+      completes.push();
+
+      expect(completeHandoff).toHaveBeenCalledWith('hB', { kind: 'done' });
+      expect(completeHandoff).toHaveBeenCalledWith('hA', { kind: 'done' });
+    });
+
+    it('legacy (tag, data) handler that calls resume() still works (degrades natively, no completeHandoff)', () => {
+      // Old-shape handler ignores the third arg and calls resume() directly.
+      const legacy = (_tag: string, _data?: Record<string, unknown>) => {
+        NamiFlowManager.resume();
+      };
+      // Cast at the call site only — the public signature is the 3-arg shape.
+      NamiFlowManager.registerStepHandoff(legacy as never);
+
+      fireHandoff({ handoffId: 'h4', handoffTag: 'complete' });
+
+      expect(resumeMock).toHaveBeenCalledTimes(1);
+      expect(completeHandoff).not.toHaveBeenCalled();
+    });
+  });
+
   describe('registerEventHandler', () => {
     it('returns a function and triggers native register', () => {
       const unsubscribe = NamiFlowManager.registerEventHandler(() => {});

package/src/types.ts

@@ -259,7 +259,15 @@ export type NamiEntitlement = {
   relatedSkus: NamiSKU[];
 };
 
-export type NamiPurchaseDetails = {
+/**
+ * Host-managed purchase payload handed back to the SDK on a successful
+ * `buysku` handoff (`complete({ kind: 'purchase', result: 'success', details })`).
+ * Fields are a superset across stores; the native bridge maps them onto the
+ * platform's own `NamiPurchaseSuccess` (Apple flat class / Android sealed
+ * GooglePlay|Amazon) at the boundary. Renamed from `NamiPurchaseDetails` for
+ * cross-SDK naming consistency (NAM-1560 §2.3).
+ */
+export type NamiPurchaseSuccess = {
   product: NamiSKU;
   transactionID?: string;
   originalTransactionID?: string;
@@ -274,6 +282,13 @@ export type NamiPurchaseDetails = {
   storeType?: string; // 'Apple', 'GooglePlay', 'Amazon'
 };
 
+/**
+ * @deprecated Renamed to {@link NamiPurchaseSuccess} for cross-SDK naming
+ * consistency. Structurally identical; kept so existing host code keeps
+ * compiling. Prefer `NamiPurchaseSuccess` in new code.
+ */
+export type NamiPurchaseDetails = NamiPurchaseSuccess;
+
 export type NamiPurchaseSuccessApple = {
   product: NamiSKU;
   transactionID: string;
@@ -398,11 +413,113 @@ export type NamiPaywallEventVideoMetadata = {
   contentDuration?: number;
 };
 
+/**
+ * Native → JS handoff delivery payload. `handoffId` correlates the eventual
+ * `complete(outcome)` back to the native pending handoff (NAM-1560 §2.8).
+ */
 export type NamiFlowHandoffPayload = {
+  handoffId: string;
   handoffTag: string;
   handoffData?: Record<string, unknown>;
 };
 
+// ---------------------------------------------------------------------------
+// Variant D — structured handoff outcomes (NAM-1560). Mirrors the core TS
+// reference (sdk/core, NAM-1557 / PR #392). Keep the shapes in sync; the native
+// bridges decode these dicts into the platform `NamiHandoffOutcome`.
+// ---------------------------------------------------------------------------
+
+/** Open-ended host-asserted attribute values — primitives only (no nesting). */
+export type NamiHandoffAttributeValue = string | number | boolean;
+
+/**
+ * Host-asserted login result. Only `loginId` is required. `attributes` is
+ * open-ended experience data (e.g. `{ subscriberStatus, subscribedTier }`) read
+ * by branch conditions and smart text via `login.<hostKey>`; never merged into
+ * Nami subscriber state and never touches entitlements.
+ */
+export type NamiLoginSuccess = {
+  loginId: string;
+  cdpId?: string;
+  attributes?: Record<string, NamiHandoffAttributeValue>;
+};
+
+/** Permission types reportable from a handoff. Tier-1 (push/location/tracking)
+ *  carry completion wire values natively; the rest are state/lifecycle only. */
+export const NamiPermissionOutcome = {
+  Push: 'push',
+  Location: 'location',
+  Tracking: 'tracking',
+  Camera: 'camera',
+  Microphone: 'microphone',
+  Photos: 'photos',
+  Contacts: 'contacts',
+  Bluetooth: 'bluetooth',
+  Calendar: 'calendar',
+  Biometrics: 'biometrics',
+  Health: 'health',
+  Motion: 'motion',
+  Speech: 'speech',
+  LocalNetwork: 'localNetwork',
+} as const;
+export type NamiPermissionOutcome =
+  (typeof NamiPermissionOutcome)[keyof typeof NamiPermissionOutcome];
+
+/** Typed outcome reported by the host's `complete(...)`. Discriminated on `kind`
+ *  (purchase/login further discriminated on `result`). */
+export type NamiHandoffOutcome =
+  | { kind: 'done' }
+  | {
+      kind: 'permission';
+      permission: NamiPermissionOutcome;
+      granted: boolean;
+      detail?: string;
+    }
+  | { kind: 'purchase'; result: 'success'; details: NamiPurchaseSuccess }
+  | { kind: 'purchase'; result: 'cancelled' }
+  | { kind: 'purchase'; result: 'failed'; error?: unknown }
+  | { kind: 'login'; result: 'success'; details: NamiLoginSuccess }
+  | { kind: 'login'; result: 'cancelled' }
+  | { kind: 'login'; result: 'failed'; error?: unknown };
+
+/** Per-handoff completion callback. Bare `complete()` ≙ `complete({kind:'done'})`. */
+export type NamiHandoffComplete = (outcome?: NamiHandoffOutcome) => void;
+
+/** The single handoff handler shape (NAM-1560 §2.1 — no dual registration). */
+export type NamiFlowHandoffStepHandler = (
+  handoffTag: string,
+  handoffData: Record<string, unknown> | undefined,
+  complete: NamiHandoffComplete,
+) => void;
+
+/** Closed-but-extensible handoff tag vocabulary (mirrors the builder's
+ *  `FlowHandoffTag`, minus `__*__` internals). Unknown future tags still pass. */
+export const NamiHandoffTag = {
+  Push: 'push',
+  Location: 'location',
+  Tracking: 'att',
+  Deeplink: 'deeplink',
+  Complete: 'complete',
+  SignIn: 'signin',
+  Restore: 'restore',
+  SignInMvpd: 'signin_mvpd',
+  BuySku: 'buysku',
+  UserData: 'userdata',
+} as const;
+export type NamiKnownHandoffTag =
+  (typeof NamiHandoffTag)[keyof typeof NamiHandoffTag];
+// eslint-disable-next-line @typescript-eslint/ban-types
+export type NamiHandoffTagValue = NamiKnownHandoffTag | (string & {});
+
+/** Outbound `userdata` envelope (Nami → customer) delivered with the `userdata` tag. */
+export type NamiUserDataEnvelope = {
+  form_id: string;
+  step_id: string;
+  /** ISO-8601 UTC timestamp of delivery. */
+  collected_at: string;
+  fields: Record<string, boolean | string>;
+};
+
 export type NamiAccountStateEvent = {
   action: AccountStateAction;
   success: boolean;

package/src/version.ts

@@ -2,4 +2,4 @@
  * Auto-generated file. Do not edit manually.
  * React Native Nami SDK version.
  */
-export const NAMI_REACT_NATIVE_VERSION = '3.4.4-dev.202606241952';
+export const NAMI_REACT_NATIVE_VERSION = '3.4.4-dev.202606260324';