@billdog.io/react-native 1.0.0-beta.2

package/ios/BillDogBridge.swift

@@ -0,0 +1,715 @@
+//
+//  BillDogBridge.swift
+//  @billdog.io/react-native
+//
+//  Core BillDog React Native module — REAL native delegation to the BillDog iOS
+//  SDK (JS accesses this as `NativeModules.BillDog`; the objc name is pinned via
+//  `@objc(BillDog)`).
+//
+//  This bridges the ~40 `native.<method>(...)` calls in `../src/BillDog.ts` to
+//  `BillDog.shared` (native BillDog iOS SDK, vended by the `BillDog` pod — see the
+//  podspec `s.dependency 'BillDog'`, Phase 0). CocoaPods compiles every BillDog
+//  subspec (Core, Paywall, …) into a SINGLE Clang module named `BillDog`, so one
+//  `import BillDog` exposes every public symbol used below (BillDog, BillDogConfig,
+//  ConsentManager, CustomerInfo, EntitlementInfo, PlacementResult, PresentationResult,
+//  RestoreResult, PurchaseResult, PurchaseParams, CacheFetchPolicy, InterfaceStyle).
+//  Because this Swift class is named `BillDogBridge` (only its objc export is
+//  `BillDog`), the bare `BillDog` identifier below unambiguously resolves to the
+//  SDK class, never to this bridge.
+//
+//  ⚠️ VERIFICATION: there is no iOS/CocoaPods/Xcode toolchain in the authoring
+//  environment. This file is written to be internally consistent and compile-ready
+//  against the verified native signatures (cited inline as `BillDog.swift:<line>`
+//  etc.), but it REQUIRES a `pod install` + Xcode build in a host RN app to
+//  actually compile and run.
+//
+//  Method names + argument shapes are the AUTHORITATIVE contract from
+//  `../src/BillDog.ts`. The result maps mirror the same model shapes the JS side
+//  parses (PurchaseResult / RestoreResult / CustomerInfo / PlacementResult /
+//  PresentationResult), matching `BillDogFlutterPlugin.swift`'s serialization.
+//
+
+import Foundation
+import React
+import BillDogFull
+
+@objc(BillDog)
+class BillDogBridge: NSObject {
+
+    override static func requiresMainQueueSetup() -> Bool {
+        return false
+    }
+
+    /// native.configure(apiKey, options) → BillDog.shared.configure(config:)
+    /// (BillDog.swift:338). Without this the native SDK is unconfigured and every
+    /// delegating call fails; this is what makes the thin bridge usable.
+    @objc
+    func configure(_ apiKey: String,
+                   options: NSDictionary?,
+                   resolver resolve: @escaping RCTPromiseResolveBlock,
+                   rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let enableLogging = (options?["enableLogging"] as? Bool) ?? true
+        let localeOverride = options?["localeOverride"] as? String
+        let config = BillDogConfig(
+            apiKey: apiKey,
+            enableLogging: enableLogging,
+            environment: .production,
+            localeOverride: localeOverride
+        )
+        BillDog.shared.configure(config: config)
+        BillDogBridge.registerOptionalModules()
+        resolve(true)
+    }
+
+    /// Guards `registerOptionalModules()` — `use(module:)` does not de-dupe.
+    private static var modulesRegistered = false
+
+    /// Register the optional native submodules with the core SDK.
+    ///
+    /// WHY THIS EXISTS: the iOS SDK keeps an OPT-IN module registry —
+    /// `BillDog.shared.use(module:)` is the only way to populate it, and
+    /// `configure(config:)` registers nothing. Every bridge here resolves its
+    /// manager per-call out of `BillDog.shared.getModules()` (BillDog.swift:579),
+    /// so with an empty registry `BillDogAnalytics` / `BillDogABTest` resolve nil
+    /// and silently NO-OP — `track()` reports success and delivers nothing.
+    /// Confirmed on the Android twin of this bug 2026-07-21: events never reached
+    /// ClickHouse.
+    ///
+    /// A native Swift host does this itself (see the iOS Inspector's
+    /// BillDogBootstrap.swift:42-56) — but an RN app has no Swift bootstrap, so the
+    /// bridge IS the host. Mirrors that reference sequence. Unlike Android, the
+    /// iOS analytics manager needs no Application context and no separate
+    /// persistence-init call (`init(directoryURL:)` defaults).
+    static func registerOptionalModules() {
+        guard !modulesRegistered else { return }
+        modulesRegistered = true
+        BillDog.shared.use(module: BillDogAnalyticsManager())
+        BillDog.shared.use(module: BillDogABTestManager())
+    }
+
+    /// PUR-364 — Whether a JS-side host PurchaseController is registered.
+    ///
+    /// NOTE: full JS-PurchaseController callback bridging (invoking a JS
+    /// `purchase(productId)` from native and awaiting its typed result) is
+    /// DEFERRED. For now we only store the flag; `purchase(_:)` always routes
+    /// through the SDK's own native controller via `BillDog.shared.purchase(params:)`
+    /// (the JS facade already short-circuits to the JS controller before ever
+    /// reaching this bridge — see BillDog.ts:209 — so this flag is currently
+    /// informational only).
+    private var purchaseControllerActive = false
+
+    // MARK: - Async helpers
+
+    /// Run an async throwing block; resolve its value or reject on throw.
+    private func runThrowing(_ resolve: @escaping RCTPromiseResolveBlock,
+                             _ reject: @escaping RCTPromiseRejectBlock,
+                             _ work: @escaping () async throws -> Any?) {
+        Task {
+            do {
+                let value = try await work()
+                resolve(value)
+            } catch {
+                reject("BILLDOG_ERROR", error.localizedDescription, error)
+            }
+        }
+    }
+
+    /// Run an async non-throwing block and resolve its value.
+    private func runValue(_ resolve: @escaping RCTPromiseResolveBlock,
+                          _ work: @escaping () async -> Any?) {
+        Task {
+            let value = await work()
+            resolve(value)
+        }
+    }
+
+    // MARK: - Purchases
+
+    /// BillDog.ts:221 — params is `{ ...PurchaseParams, source }`. We map every
+    /// PurchaseParams field onto the native `PurchaseParams.Builder`
+    /// (PurchaseParams.swift:67) and call `purchase(params:)` (BillDog.swift:1697),
+    /// which returns the canonical 5-case PurchaseResult.
+    @objc(purchase:resolver:rejecter:)
+    func purchase(_ params: NSDictionary,
+                  resolver resolve: @escaping RCTPromiseResolveBlock,
+                  rejecter reject: @escaping RCTPromiseRejectBlock) {
+        guard let productId = params["productId"] as? String else {
+            reject("BILLDOG_ERROR", "purchase: missing productId", nil)
+            return
+        }
+        // PurchaseParams.Builder — PurchaseParams.swift:67.
+        let builder = PurchaseParams.Builder(productId: productId)
+        if let promo = params["promoOfferId"] as? String { builder.with(promoOfferId: promo) }
+        if let winBack = params["winBackOfferId"] as? String { builder.with(winBackOfferId: winBack) }
+        if let token = params["appAccountToken"] as? String, let uuid = UUID(uuidString: token) {
+            builder.with(appAccountToken: uuid)
+        }
+        if let qty = params["quantity"] as? Int { builder.with(quantity: qty) }
+        if let personalized = params["isPersonalizedOffer"] as? Bool { builder.with(isPersonalizedOffer: personalized) }
+        if let mode = params["replacementMode"] as? String { builder.with(replacementMode: mode) }
+        let built = builder.build()
+
+        runThrowing(resolve, reject) {
+            // BillDog.swift:1697 — purchase(params:) async throws -> PurchaseResult.
+            let result = try await BillDog.shared.purchase(params: built)
+            return Self.serialize(result)
+        }
+    }
+
+    /// BillDog.ts:266 — store the flag only (JS-controller bridging deferred; see
+    /// `purchaseControllerActive` doc above). No native equivalent needed here.
+    @objc(setPurchaseControllerActive:)
+    func setPurchaseControllerActive(_ active: Bool) {
+        purchaseControllerActive = active
+        NSLog("[BillDog] setPurchaseControllerActive(\(active)) — flag stored; JS PurchaseController bridging is deferred")
+    }
+
+    /// BillDog.ts:296 — restorePurchases() async throws -> RestoreResult. BillDog.swift:1507.
+    @objc(restore:rejecter:)
+    func restore(_ resolve: @escaping RCTPromiseResolveBlock,
+                 rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runValue(resolve) {
+            do {
+                let result = try await BillDog.shared.restorePurchases()
+                return Self.serialize(result)
+            } catch {
+                return ["type": "failed",
+                        "error": ["category": "unknown", "message": error.localizedDescription]]
+            }
+        }
+    }
+
+    // MARK: - CustomerInfo
+
+    /// BillDog.ts:320 — getCustomerInfo(fetchPolicy:) async throws -> CustomerInfo. BillDog.swift:2640.
+    @objc(getCustomerInfo:resolver:rejecter:)
+    func getCustomerInfo(_ policy: String,
+                         resolver resolve: @escaping RCTPromiseResolveBlock,
+                         rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let fetchPolicy = Self.mapCacheFetchPolicy(policy)
+        runThrowing(resolve, reject) {
+            let info = try await BillDog.shared.getCustomerInfo(fetchPolicy: fetchPolicy)
+            return Self.serialize(info)
+        }
+    }
+
+    /// BillDog.ts:792 — invalidateCustomerInfoCache() async throws. BillDog.swift:1813.
+    @objc(invalidateCustomerInfoCache:rejecter:)
+    func invalidateCustomerInfoCache(_ resolve: @escaping RCTPromiseResolveBlock,
+                                     rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runThrowing(resolve, reject) {
+            try await BillDog.shared.invalidateCustomerInfoCache()
+            return nil
+        }
+    }
+
+    // MARK: - Store capability surface
+
+    /// BillDog.ts:350 — static canMakePayments() async -> Bool. BillDog.swift:2616.
+    @objc(canMakePayments:rejecter:)
+    func canMakePayments(_ resolve: @escaping RCTPromiseResolveBlock,
+                         rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runValue(resolve) {
+            await BillDog.canMakePayments()
+        }
+    }
+
+    /// BillDog.ts:359 — presentCodeRedemptionSheet() async throws. BillDog.swift:1656.
+    @objc(presentCodeRedemptionSheet:rejecter:)
+    func presentCodeRedemptionSheet(_ resolve: @escaping RCTPromiseResolveBlock,
+                                    rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runThrowing(resolve, reject) {
+            try await BillDog.shared.presentCodeRedemptionSheet()
+            return nil
+        }
+    }
+
+    /// BillDog.ts:375 — NO native equivalent on BillDog.shared (searched the whole
+    /// paywall SDK: no `checkTrialOrIntroDiscountEligibility` / intro-eligibility
+    /// query API). Resolve all ids `unknown` (the JS fallback shape) + NSLog.
+    @objc(checkTrialOrIntroDiscountEligibility:resolver:rejecter:)
+    func checkTrialOrIntroDiscountEligibility(_ productIds: NSArray,
+                                              resolver resolve: @escaping RCTPromiseResolveBlock,
+                                              rejecter reject: @escaping RCTPromiseRejectBlock) {
+        NSLog("[BillDog] checkTrialOrIntroDiscountEligibility — no native SDK query; returning 'unknown' for all ids")
+        var out: [String: String] = [:]
+        for case let id as String in productIds { out[id] = "unknown" }
+        resolve(out)
+    }
+
+    /// BillDog.ts:388 — the SDK exposes storefront changes only as an AsyncSequence
+    /// (StorefrontManager.swift:30) and this bridge is a plain NSObject with no
+    /// RCTEventEmitter channel, so there is no way to push updates back to JS yet.
+    /// Documented no-op (the JS facade keeps its listeners locally).
+    @objc(subscribeStorefront)
+    func subscribeStorefront() {
+        NSLog("[BillDog] subscribeStorefront — no event channel on this NSObject module; no-op (storefront push deferred)")
+    }
+
+    // MARK: - Self-hosted proxy
+
+    /// BillDog.ts:404 — setProxyURL(_:). BillDog.swift:1185.
+    @objc(setProxyURL:)
+    func setProxyURL(_ url: String?) {
+        BillDog.shared.setProxyURL(url)
+    }
+
+    /// BillDog.ts:453 — SYNCHRONOUS read. BillDogConfig.getProxyURL() static. BillDogConfig.swift:76.
+    @objc(getProxyURL)
+    func getProxyURL() -> Any? {
+        return BillDogConfig.getProxyURL()
+    }
+
+    // MARK: - Consent
+
+    /// BillDog.ts:419 — ConsentManager.setConsentRequired(_:). ConsentManager.swift:42
+    /// (also re-exposed on BillDog.shared at BillDog.swift:460).
+    @objc(setConsentRequired:)
+    func setConsentRequired(_ required: Bool) {
+        ConsentManager.shared.setConsentRequired(required)
+    }
+
+    /// BillDog.ts:428 — granular per-purpose consent. ConsentManager.setConsent(for:granted:).
+    /// ConsentManager.swift:53. Purpose enum: analytics|replay|messaging|survey (ConsentManager.swift:16).
+    @objc(setConsent:granted:)
+    func setConsent(_ purpose: String, granted: Bool) {
+        guard let p = ConsentManager.Purpose(rawValue: purpose) else {
+            NSLog("[BillDog] setConsent — unknown purpose '\(purpose)'; ignored")
+            return
+        }
+        ConsentManager.shared.setConsent(for: p, granted: granted)
+    }
+
+    /// BillDog.ts:437 — ConsentManager.setConsentGiven(_:). ConsentManager.swift:46
+    /// (also BillDog.swift:464).
+    @objc(setConsentGiven:)
+    func setConsentGiven(_ given: Bool) {
+        ConsentManager.shared.setConsentGiven(given)
+    }
+
+    /// BillDog.ts:446 — ConsentManager.consentHeaderValue() -> String?. ConsentManager.swift:75.
+    /// Sync accessor; the JS facade awaits it, so we surface it as a Promise.
+    @objc(consentHeaderValue:rejecter:)
+    func consentHeaderValue(_ resolve: @escaping RCTPromiseResolveBlock,
+                            rejecter reject: @escaping RCTPromiseRejectBlock) {
+        resolve(ConsentManager.shared.consentHeaderValue())
+    }
+
+    // MARK: - Attribution
+
+    /// BillDog.ts:484 — collectDeviceIdentifiers() async -> DeviceIdentifiers. BillDog.swift:2480.
+    /// JS calls this fire-and-forget; collect on a Task and log.
+    @objc(collectDeviceIdentifiers)
+    func collectDeviceIdentifiers() {
+        Task {
+            _ = await BillDog.shared.collectDeviceIdentifiers()
+            NSLog("[BillDog] collectDeviceIdentifiers — device identifiers collected")
+        }
+    }
+
+    /// native.setAttribution({ key: id, … }) → the matching native provider setter
+    /// (BillDog.swift:3388+). Keys are provider attribution keys; each maps 1:1 to
+    /// a consent-gated native setter. Unknown keys are ignored. The JS facade's
+    /// named setters (setMixpanelDistinctID etc.) all funnel through here.
+    @objc
+    func setAttribution(_ data: NSDictionary,
+                        resolver resolve: @escaping RCTPromiseResolveBlock,
+                        rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let entries = (data as? [String: String]) ?? [:]
+        Task {
+            do {
+                for (key, value) in entries {
+                    switch key {
+                    case "cleverTapId": try await BillDog.shared.setCleverTapID(value)
+                    case "mixpanelDistinctId": try await BillDog.shared.setMixpanelDistinctID(value)
+                    case "onesignalId": try await BillDog.shared.setOnesignalID(value)
+                    case "fbAnonymousId": try await BillDog.shared.setFBAnonymousID(value)
+                    case "airshipChannelId": try await BillDog.shared.setAirshipChannelID(value)
+                    case "moEngageAnonymousId": try await BillDog.shared.setMoEngageAnonymousID(value)
+                    case "mparticleId": try await BillDog.shared.setMparticleID(value)
+                    case "kochavaId": try await BillDog.shared.setKochavaDeviceID(value)
+                    case "tenjinId": try await BillDog.shared.setTenjinAnalyticsInstallationID(value)
+                    case "iterableId": try await BillDog.shared.setIterableUserID(value)
+                    case "segmentId": try await BillDog.shared.setSegmentAnonymousID(value)
+                    // MMP providers — dedicated native setters.
+                    case "adjustId": try await BillDog.shared.setAdjustId(value)
+                    case "appsflyerId": try await BillDog.shared.setAppsflyerId(value)
+                    case "firebaseAppInstanceId": try await BillDog.shared.setFirebaseAppInstanceId(value)
+                    default: break // unknown provider key — ignore
+                    }
+                }
+                resolve(nil)
+            } catch {
+                reject("ATTRIBUTION_ERROR", error.localizedDescription, error)
+            }
+        }
+    }
+
+    // MARK: - Identity
+
+    /// BillDog.ts:513 — logIn(_:) async throws -> LogInResult. BillDog.swift:2529.
+    /// JS ignores the return value; resolve nil on success.
+    @objc(logIn:resolver:rejecter:)
+    func logIn(_ appUserId: String,
+               resolver resolve: @escaping RCTPromiseResolveBlock,
+               rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runThrowing(resolve, reject) {
+            _ = try await BillDog.shared.logIn(appUserId)
+            return nil
+        }
+    }
+
+    /// BillDog.ts:536 — logOut() (synchronous on the SDK). BillDog.swift:2547.
+    @objc(logOut:rejecter:)
+    func logOut(_ resolve: @escaping RCTPromiseResolveBlock,
+                rejecter reject: @escaping RCTPromiseRejectBlock) {
+        BillDog.shared.logOut()
+        resolve(nil)
+    }
+
+    /// BillDog.ts:589 — NO native runtime toggle (sandbox derives from API-key
+    /// prefix at configure time — same finding as BillDogFlutterPlugin.swift:381).
+    @objc(setSandboxMode:)
+    func setSandboxMode(_ enabled: Bool) {
+        NSLog("[BillDog] setSandboxMode(\(enabled)) — no native runtime toggle (sandbox derives from API-key prefix); no-op")
+    }
+
+    // MARK: - Placements
+
+    /// BillDog.ts:634 — args is `{ placementId, params }`. FULL-SCREEN PRESENT via
+    /// register(placement:params:) async throws -> PlacementResult. BillDog.swift:2899.
+    @objc(registerPlacement:resolver:rejecter:)
+    func registerPlacement(_ args: NSDictionary,
+                           resolver resolve: @escaping RCTPromiseResolveBlock,
+                           rejecter reject: @escaping RCTPromiseRejectBlock) {
+        guard let placementId = args["placementId"] as? String else {
+            reject("BILLDOG_ERROR", "registerPlacement: missing placementId", nil)
+            return
+        }
+        let params = args["params"] as? [String: Any]
+        runValue(resolve) {
+            do {
+                let result = try await BillDog.shared.register(placement: placementId, params: params)
+                return Self.serialize(result)
+            } catch {
+                return ["type": "error", "message": error.localizedDescription]
+            }
+        }
+    }
+
+    /// BillDog.ts:679 — SYNCHRONOUS entitlement probe. hasAccessForPlacement(_:) -> Bool.
+    /// BillDog.swift:2213.
+    @objc(hasAccessForPlacement:)
+    func hasAccessForPlacement(_ placementId: String) -> NSNumber {
+        return NSNumber(value: BillDog.shared.hasAccessForPlacement(placementId))
+    }
+
+    /// BillDog.ts:878 — getPresentationResult(forPlacement:) async -> PresentationResult.
+    /// BillDog.swift:3319.
+    @objc(getPresentationResult:resolver:rejecter:)
+    func getPresentationResult(_ placementId: String,
+                               resolver resolve: @escaping RCTPromiseResolveBlock,
+                               rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runValue(resolve) {
+            let result = await BillDog.shared.getPresentationResult(forPlacement: placementId)
+            return Self.serialize(result)
+        }
+    }
+
+    // Experiments & feature flags: the paywall-facade shim was removed. Use the
+    // standalone BillDogABTestManager (bridged via BillDogABTestModule) instead.
+
+    // MARK: - In-app messages
+
+    /// BillDog.ts:722 — NO native equivalent on BillDog.shared (same finding as
+    /// BillDogFlutterPlugin.swift:389 — in-app messages dispatch internally / via
+    /// journeys, not through a paywall-channel call). Resolve nil + NSLog.
+    @objc(showInAppMessages:resolver:rejecter:)
+    func showInAppMessages(_ placementId: String?,
+                           resolver resolve: @escaping RCTPromiseResolveBlock,
+                           rejecter reject: @escaping RCTPromiseRejectBlock) {
+        NSLog("[BillDog] showInAppMessages(\(placementId ?? "nil")) — no native SDK method on BillDog.shared; no-op")
+        resolve(nil)
+    }
+
+    // MARK: - Deep linking
+
+    /// BillDog.ts:731 — handleDeepLink(_: URL) -> String? (non-nil route id when
+    /// handled). BillDog.swift:2876. JS wants a bool.
+    @objc(handleDeepLink:resolver:rejecter:)
+    func handleDeepLink(_ uri: String,
+                        resolver resolve: @escaping RCTPromiseResolveBlock,
+                        rejecter reject: @escaping RCTPromiseRejectBlock) {
+        guard let url = URL(string: uri) else {
+            resolve(false)
+            return
+        }
+        resolve(BillDog.shared.handleDeepLink(url) != nil)
+    }
+
+    // MARK: - Component selection state
+
+    /// BillDog.ts:740 — SYNCHRONOUS. getSelectedProductIndex(componentId:) -> Int?
+    /// (nil is a valid response → JS null). BillDog.swift:1889.
+    @objc(getSelectedProductIndex:)
+    func getSelectedProductIndex(_ componentId: String) -> Any? {
+        if let index = BillDog.shared.getSelectedProductIndex(componentId: componentId) {
+            return NSNumber(value: index)
+        }
+        return nil
+    }
+
+    /// BillDog.ts:747 — setSelectedProductIndex(componentId:index:). BillDog.swift:1895.
+    @objc(setSelectedProductIndex:index:)
+    func setSelectedProductIndex(_ componentId: String, index: NSNumber) {
+        BillDog.shared.setSelectedProductIndex(componentId: componentId, index: index.intValue)
+    }
+
+    // MARK: - Theming
+
+    /// BillDog.ts:755 — updateTheme(_: [String: String]?). BillDog.swift:1174.
+    @objc(updateTheme:)
+    func updateTheme(_ overrides: NSDictionary) {
+        BillDog.shared.updateTheme(overrides as? [String: String])
+    }
+
+    /// BillDog.ts:762 — setInterfaceStyle(_: InterfaceStyle?). BillDog.swift:3333.
+    /// InterfaceStyle: light/dark/system; nil == follow system.
+    @objc(setInterfaceStyle:)
+    func setInterfaceStyle(_ style: String?) {
+        BillDog.shared.setInterfaceStyle(Self.mapInterfaceStyle(style))
+    }
+
+    // MARK: - Subscription management
+
+    /// BillDog.ts:776 — showManageSubscriptions() async (takes no argument; Apple
+    /// resolves the active subscription — the JS `subscriptionId` is ignored, same
+    /// as BillDogFlutterPlugin.swift:344). BillDog.swift:3182.
+    @objc(showManageSubscriptions:resolver:rejecter:)
+    func showManageSubscriptions(_ subscriptionId: String?,
+                                 resolver resolve: @escaping RCTPromiseResolveBlock,
+                                 rejecter reject: @escaping RCTPromiseRejectBlock) {
+        runValue(resolve) {
+            await BillDog.shared.showManageSubscriptions()
+            return nil
+        }
+    }
+
+    // MARK: - Cache control
+
+    /// BillDog.ts:785 — clearCache() (synchronous on the SDK). BillDog.swift:1914.
+    @objc(clearCache:rejecter:)
+    func clearCache(_ resolve: @escaping RCTPromiseResolveBlock,
+                    rejecter reject: @escaping RCTPromiseRejectBlock) {
+        BillDog.shared.clearCache()
+        resolve(nil)
+    }
+
+    // MARK: - User attributes
+
+    /// BillDog.ts:801 — setUserAttributes(_: [String: Any?]) async throws. BillDog.swift:3344.
+    @objc(setUserAttributes:resolver:rejecter:)
+    func setUserAttributes(_ attributes: NSDictionary,
+                           resolver resolve: @escaping RCTPromiseResolveBlock,
+                           rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let dict = (attributes as? [String: Any]) ?? [:]
+        runThrowing(resolve, reject) {
+            try await BillDog.shared.setUserAttributes(dict)
+            return nil
+        }
+    }
+
+    /// BillDog.ts:812 — getUserAttributes() -> [String: Any] (synchronous on the
+    /// SDK; the JS facade awaits it). BillDog.swift:3358.
+    @objc(getUserAttributes:rejecter:)
+    func getUserAttributes(_ resolve: @escaping RCTPromiseResolveBlock,
+                           rejecter reject: @escaping RCTPromiseRejectBlock) {
+        resolve(BillDog.shared.getUserAttributes())
+    }
+
+    // MARK: - External-purchase observation
+
+    /// BillDog.ts:822 — observePurchaseStart(productId:). BillDog.swift:3568.
+    @objc(observePurchaseStart:)
+    func observePurchaseStart(_ productId: String) {
+        BillDog.shared.observePurchaseStart(productId: productId)
+    }
+
+    /// BillDog.ts:829 — observePurchaseResult(productId:orderId:...). BillDog.swift:3583.
+    @objc(observePurchaseResult:orderId:)
+    func observePurchaseResult(_ productId: String, orderId: String?) {
+        BillDog.shared.observePurchaseResult(productId: productId, orderId: orderId)
+    }
+
+    /// BillDog.ts:835 — observePurchaseError(productId:error:). BillDog.swift:3610.
+    /// JS passes an error string; wrap it in an NSError (same as the Flutter plugin).
+    @objc(observePurchaseError:error:)
+    func observePurchaseError(_ productId: String, error: String) {
+        let nsError = NSError(domain: "io.billdog.reactnative", code: -1,
+                              userInfo: [NSLocalizedDescriptionKey: error])
+        BillDog.shared.observePurchaseError(productId: productId, error: nsError)
+    }
+
+    // MARK: - Server-side actions
+
+    /// BillDog.ts:900 — executeAction(paywallId:componentId:actionType:idempotencyKey:metadata:)
+    /// async throws -> [String: Any]. BillDog.swift:231.
+    @objc(executeAction:componentId:actionType:idempotencyKey:metadata:resolver:rejecter:)
+    func executeAction(_ paywallId: String?,
+                       componentId: String,
+                       actionType: String,
+                       idempotencyKey: String?,
+                       metadata: NSDictionary?,
+                       resolver resolve: @escaping RCTPromiseResolveBlock,
+                       rejecter reject: @escaping RCTPromiseRejectBlock) {
+        let meta = metadata as? [String: Any]
+        runThrowing(resolve, reject) {
+            try await BillDog.shared.executeAction(paywallId: paywallId,
+                                                   componentId: componentId,
+                                                   actionType: actionType,
+                                                   idempotencyKey: idempotencyKey,
+                                                   metadata: meta)
+        }
+    }
+
+    // MARK: - Enum mapping
+
+    /// CacheFetchPolicy (CustomerManager.swift:4); JS wire names from CacheFetchPolicy.ts.
+    private static func mapCacheFetchPolicy(_ raw: String?) -> CacheFetchPolicy {
+        switch raw {
+        case "FROM_CACHE_ONLY": return .fromCacheOnly
+        case "FETCH_CURRENT": return .fetchCurrent
+        case "NOT_STALE_CACHED_OR_CURRENT": return .notStaleCachedOrCurrent
+        default: return .cachedOrFetched // PUR-141 default (CACHED_OR_FETCHED)
+        }
+    }
+
+    /// InterfaceStyle (InterfaceStyle.swift); JS passes 'light' | 'dark' | null.
+    private static func mapInterfaceStyle(_ raw: String?) -> InterfaceStyle? {
+        switch raw?.lowercased() {
+        case "light": return .light
+        case "dark": return .dark
+        case "system": return .system
+        default: return nil // nil == follow system
+        }
+    }
+
+    // MARK: - Serialization (mirrors BillDogFlutterPlugin.swift; matches BillDog.ts model shapes)
+
+    /// PurchaseResult (PurchaseResult.swift:24) → PurchaseResult.ts 5-case union.
+    private static func serialize(_ r: PurchaseResult) -> [String: Any] {
+        switch r {
+        case .purchased(let transactionId, let productId, let originalTransactionId):
+            var m: [String: Any] = ["type": "purchased",
+                                    "transactionId": transactionId,
+                                    "productId": productId]
+            if let orig = originalTransactionId { m["originalTransactionId"] = orig }
+            return m
+        case .cancelled:
+            return ["type": "cancelled"]
+        case .pending:
+            return ["type": "pending"]
+        case .failed(let error):
+            return ["type": "failed",
+                    "error": ["category": "unknown", "message": error.localizedDescription]]
+        case .restored(let transactionId, let productId, let originalTransactionId):
+            var m: [String: Any] = ["type": "restored",
+                                    "transactionId": transactionId,
+                                    "productId": productId]
+            if let orig = originalTransactionId { m["originalTransactionId"] = orig }
+            return m
+        }
+    }
+
+    /// RestoreResult (PurchaseResult.swift:52) → RestoreResult.ts.
+    /// Each item carries `status` per RestoredItem.ts (per-transaction success).
+    private static func serialize(_ r: RestoreResult) -> [String: Any] {
+        switch r {
+        case .restored(let items):
+            let mapped: [[String: Any]] = items.map { p in
+                var m: [String: Any] = [
+                    "productId": p.productId,
+                    "transactionId": p.transactionId,
+                    "status": ["type": "restored"]
+                ]
+                if let orig = p.originalTransactionId { m["originalTransactionId"] = orig }
+                return m
+            }
+            return ["type": "restored", "items": mapped]
+        case .failed(let error):
+            return ["type": "failed",
+                    "error": ["category": "unknown", "message": error.localizedDescription]]
+        }
+    }
+
+    /// PlacementResult (PlacementManager) → Placement.ts PlacementResult.
+    private static func serialize(_ r: PlacementResult) -> [String: Any] {
+        switch r {
+        case .entitled:
+            return ["type": "entitled"]
+        case .purchased(let productId):
+            return ["type": "purchased", "productId": productId]
+        case .dismissed:
+            return ["type": "dismissed"]
+        case .restored:
+            return ["type": "restored"]
+        case .oauthSuccess:
+            // No JS PlacementResult case for OAuth sign-in — map to neutral `dismissed`
+            // so the caller resumes without a spurious error (parity with Flutter).
+            return ["type": "dismissed"]
+        case .error(let err):
+            return ["type": "error", "message": err.localizedDescription]
+        }
+    }
+
+    /// PresentationResult (BillDog.swift:3844) → Placement.ts PresentationResult.
+    private static func serialize(_ r: PresentationResult) -> [String: Any] {
+        switch r {
+        case .paywall:
+            return ["type": "paywall"]
+        case .userSubscribed:
+            return ["type": "userSubscribed"]
+        case .holdout:
+            return ["type": "holdout"]
+        case .noPaywall(let reason):
+            return ["type": "noPaywall", "reason": reason]
+        case .error(let err):
+            return ["type": "error", "message": err.localizedDescription]
+        }
+    }
+
+    /// CustomerInfo (CustomerInfo.swift:169) → CustomerInfo.ts shape.
+    private static func serialize(_ info: CustomerInfo) -> [String: Any] {
+        var m: [String: Any] = [
+            "userId": info.userId,
+            "entitlements": info.entitlements.map { serialize($0) },
+            "activeSubscriptions": info.activeSubscriptions,
+            "productEntitlementMapping": info.productEntitlementMapping,
+            "isInTrial": info.isInTrial,
+            "isInGracePeriod": info.isInGracePeriod,
+            "hasExpiredSubscription": info.hasExpiredSubscription
+        ]
+        if let orig = info.originalAppUserId { m["originalAppUserId"] = orig }
+        return m
+    }
+
+    /// EntitlementInfo (CustomerInfo.swift:77) → EntitlementInfo.ts shape.
+    private static func serialize(_ e: EntitlementInfo) -> [String: Any] {
+        var m: [String: Any] = [
+            "identifier": e.identifier,
+            "isActive": e.isActive,
+            "willRenew": e.willRenew,
+            "isLifetime": e.isLifetime,
+            "productIds": e.productIds
+        ]
+        if let v = e.expiresAt { m["expiresAt"] = v }
+        if let v = e.store { m["store"] = v }
+        if let v = e.grantedAt { m["grantedAt"] = v }
+        if let v = e.displayName { m["displayName"] = v }
+        if let v = e.state { m["state"] = v }
+        if let v = e.startsAt { m["startsAt"] = v }
+        if let v = e.renewedAt { m["renewedAt"] = v }
+        if let v = e.latestProductId { m["latestProductId"] = v }
+        return m
+    }
+}