@namiml/expo-nami-iap 3.4.0-dev.202605060437

package/ios/PromotionalOfferSigner.swift

@@ -0,0 +1,78 @@
+//
+//  PromotionalOfferSigner.swift
+//  ExpoNamiIap
+//
+//  Copyright (c) 2024 Nami ML Inc. All rights reserved.
+//
+
+import Foundation
+import StoreKit
+
+/// Parses a server-provided promotional offer signature blob into a
+/// `Product.PurchaseOption.promotionalOffer(...)` option.
+///
+/// The signature is expected to be a Base64-encoded JSON object with the
+/// following structure (matching the Nami Apple SDK's `NamiApplePromo`):
+///
+/// ```json
+/// {
+///   "key_id": "<App Store Connect key identifier>",
+///   "nonce": "<UUID string>",
+///   "signature": "<Base64-encoded ECDSA signature>",
+///   "timestamp": <Unix epoch in milliseconds>
+/// }
+/// ```
+///
+/// This mirrors the format used by `NamiApplePromo.applyPromotionalOffer`
+/// in `sdk/apple/Nami/Models/NamiApplePromo.swift`. The caller passes
+/// the opaque Base64 string received from the Nami backend and this helper
+/// decodes it into the parameters Apple's StoreKit 2 API requires.
+@available(iOS 15.0, tvOS 15.0, *)
+enum PromotionalOfferSigner {
+
+    /// Build a `Product.PurchaseOption` for a promotional offer from a
+    /// Base64-encoded JSON signature blob.
+    ///
+    /// - Parameters:
+    ///   - product: The StoreKit `Product` (unused directly but kept for
+    ///     API parity with `NamiApplePromo.applyPromotionalOffer`).
+    ///   - offerId: The promotional offer identifier configured in App Store Connect.
+    ///   - signature: Base64-encoded JSON blob containing `key_id`, `nonce`,
+    ///     `signature`, and `timestamp`.
+    /// - Returns: A `.promotionalOffer` purchase option, or `nil` if the
+    ///   signature blob is malformed or missing required fields.
+    static func option(
+        product: Product,
+        offerId: String,
+        signature: String
+    ) -> Product.PurchaseOption? {
+        // Decode the Base64 wrapper
+        guard let jsonData = Data(base64Encoded: signature) else {
+            return nil
+        }
+
+        // Parse JSON
+        guard let json = try? JSONSerialization.jsonObject(with: jsonData) as? [String: Any] else {
+            return nil
+        }
+
+        // Extract required fields
+        guard let keyID = json["key_id"] as? String,
+              let nonceString = json["nonce"] as? String,
+              let nonce = UUID(uuidString: nonceString),
+              let sigBase64 = json["signature"] as? String,
+              let sigData = Data(base64Encoded: sigBase64),
+              let timestamp = json["timestamp"] as? Int
+        else {
+            return nil
+        }
+
+        return .promotionalOffer(
+            offerID: offerId,
+            keyID: keyID,
+            nonce: nonce,
+            signature: sigData,
+            timestamp: timestamp
+        )
+    }
+}

package/ios/StoreKit2Helper.swift

@@ -0,0 +1,252 @@
+//
+//  StoreKit2Helper.swift
+//  ExpoNamiIap
+//
+//  Copyright (c) 2024 Nami ML Inc. All rights reserved.
+//
+
+import StoreKit
+
+/// Actor that wraps StoreKit 2 `Product` APIs, providing an order-preserving
+/// product lookup with caching and subscription eligibility checks.
+///
+/// Includes restore (Task 9), connection lifecycle via
+/// `TransactionObserver` (Task 10), and caching.
+@available(iOS 15.0, tvOS 15.0, *)
+actor StoreKit2Helper {
+
+    static let shared = StoreKit2Helper()
+
+    private var productCache: [String: Product] = [:]
+    private var unfinishedTransactions: [UInt64: Transaction] = [:]
+    private let observer = TransactionObserver()
+
+    // MARK: - getProducts
+
+    /// Fetch StoreKit products for the given SKU IDs and return them as
+    /// bridgeable dictionaries, preserving the input order.
+    ///
+    /// Products are cached after fetch so subsequent calls for the same IDs
+    /// avoid a round-trip to the App Store.
+    ///
+    /// - Parameter skuIds: Array of product identifiers.
+    /// - Returns: Array of dictionaries matching `ExpoNamiIapProduct` TypeScript shape.
+    /// - Throws: `ExpoNamiIapError.itemUnavailable` when no products are found.
+    func getProducts(_ skuIds: [String]) async throws -> [[String: Any]] {
+        let products = try await Product.products(for: skuIds)
+        guard !products.isEmpty else {
+            throw ExpoNamiIapError.itemUnavailable(message: "No products found for \(skuIds)")
+        }
+
+        // Cache fetched products
+        for p in products {
+            productCache[p.id] = p
+        }
+
+        // Preserve input order
+        let byId = Dictionary(uniqueKeysWithValues: products.map { ($0.id, $0) })
+        var results: [[String: Any]] = []
+        for skuId in skuIds {
+            if let p = byId[skuId] {
+                results.append(await ProductMapper.toDict(p))
+            }
+        }
+        return results
+    }
+
+    // MARK: - checkEligibility
+
+    /// Check intro-offer and promotional-offer eligibility for the given SKU IDs.
+    ///
+    /// For subscription products, `introEligible` reflects `isEligibleForIntroOffer`
+    /// and `promoEligible` is `true` when no active entitlement exists in the same
+    /// subscription group.  Non-subscription products always return `false` for both.
+    ///
+    /// - Parameter skuIds: Array of product identifiers to check.
+    /// - Returns: Array of dictionaries with `skuId`, `introEligible`, and `promoEligible`.
+    /// - Throws: `ExpoNamiIapError.itemUnavailable` if a product cannot be found.
+    func checkEligibility(_ skuIds: [String]) async throws -> [[String: Any]] {
+        var results: [[String: Any]] = []
+        for skuId in skuIds {
+            let product = try await fetchProduct(skuId)
+
+            let introEligible: Bool
+            let promoEligible: Bool
+
+            if let sub = product.subscription {
+                introEligible = await sub.isEligibleForIntroOffer
+                promoEligible = await promoEligibleFor(subscription: sub)
+            } else {
+                introEligible = false
+                promoEligible = false
+            }
+
+            results.append([
+                "skuId": skuId,
+                "introEligible": introEligible,
+                "promoEligible": promoEligible,
+            ])
+        }
+        return results
+    }
+
+    // MARK: - purchase
+
+    /// Execute a purchase for the given SKU ID, optionally applying an
+    /// `appAccountToken` and/or a promotional offer.
+    ///
+    /// - Parameters:
+    ///   - skuId: The product identifier to purchase.
+    ///   - offerId: Promotional offer identifier (from App Store Connect), or `nil`.
+    ///   - offerSignature: Base64-encoded JSON blob with signing parameters
+    ///     (`key_id`, `nonce`, `signature`, `timestamp`), or `nil`.
+    ///   - appAccountToken: A UUID string to associate with the transaction, or `nil`.
+    /// - Returns: A dictionary matching the `ExpoNamiIapTransaction` TypeScript shape.
+    /// - Throws: `ExpoNamiIapError.userCancelled` if the user cancels, or
+    ///   `ExpoNamiIapError.unknown` for verification failures and pending results.
+    func purchase(
+        skuId: String,
+        offerId: String?,
+        offerSignature: String?,
+        appAccountToken: String?
+    ) async throws -> [String: Any] {
+        let product = try await fetchProduct(skuId)
+        var options: Set<Product.PurchaseOption> = []
+
+        if let tokenStr = appAccountToken, let uuid = UUID(uuidString: tokenStr) {
+            options.insert(.appAccountToken(uuid))
+        }
+
+        if let offerId = offerId, let sig = offerSignature {
+            if let promoOpt = PromotionalOfferSigner.option(
+                product: product,
+                offerId: offerId,
+                signature: sig
+            ) {
+                options.insert(promoOpt)
+            }
+        }
+
+        let result = try await product.purchase(options: options)
+        switch result {
+        case .success(let verification):
+            let jws = verification.jwsRepresentation
+            switch verification {
+            case .verified(let txn):
+                unfinishedTransactions[txn.id] = txn
+                return StoreKit2Helper.txnToDict(txn, jwsRepresentation: jws)
+            case .unverified(_, let err):
+                throw ExpoNamiIapError.unknown(message: "Unverified transaction: \(err)")
+            }
+        case .userCancelled:
+            throw ExpoNamiIapError.userCancelled()
+        case .pending:
+            throw ExpoNamiIapError.unknown(message: "Purchase pending")
+        @unknown default:
+            throw ExpoNamiIapError.unknown(message: "Unknown purchase result")
+        }
+    }
+
+    // MARK: - finishTransaction
+
+    /// Finish (acknowledge) a transaction so it is no longer returned by
+    /// `Transaction.unfinished`.
+    ///
+    /// - Parameter transactionId: The numeric transaction ID as a string.
+    func finishTransaction(transactionId: String) async throws {
+        guard let id = UInt64(transactionId),
+              let txn = unfinishedTransactions[id] else { return }
+        await txn.finish()
+        unfinishedTransactions.removeValue(forKey: id)
+    }
+
+    // MARK: - restorePurchases
+
+    /// Return all currently entitled (active) transactions as bridgeable
+    /// dictionaries.  This iterates `Transaction.currentEntitlements` and
+    /// includes only verified entries.
+    ///
+    /// - Returns: Array of dictionaries matching `ExpoNamiIapTransaction` TypeScript shape.
+    func restorePurchases() async throws -> [[String: Any]] {
+        var results: [[String: Any]] = []
+        for await result in Transaction.currentEntitlements {
+            if case .verified(let txn) = result {
+                results.append(StoreKit2Helper.txnToDict(txn, jwsRepresentation: result.jwsRepresentation))
+            }
+        }
+        return results
+    }
+
+    // MARK: - txnToDict
+
+    /// Convert a verified `Transaction` to a bridgeable dictionary matching the
+    /// `ExpoNamiIapTransaction` TypeScript shape.
+    ///
+    /// Marked `nonisolated` and `static` so it can be called from both the actor
+    /// and non-isolated contexts such as `TransactionObserver` (Task 10).
+    ///
+    /// - Parameters:
+    ///   - txn: The verified transaction.
+    ///   - jwsRepresentation: The JWS receipt string from `VerificationResult.jwsRepresentation`.
+    ///     Pass `nil` if unavailable; the `receipt` key will be omitted.
+    nonisolated static func txnToDict(_ txn: Transaction, jwsRepresentation: String? = nil) -> [String: Any] {
+        var dict: [String: Any] = [
+            "skuId": txn.productID,
+            "transactionId": String(txn.id),
+            "originalTransactionId": String(txn.originalID),
+            "purchaseTime": Int(txn.purchaseDate.timeIntervalSince1970 * 1000),
+        ]
+        if let jws = jwsRepresentation {
+            dict["receipt"] = jws
+        }
+        return dict
+    }
+
+    // MARK: - Connection lifecycle
+
+    /// Start observing `Transaction.updates` via the internal `TransactionObserver`.
+    ///
+    /// Each verified transaction is forwarded to `onUpdate` as a bridgeable
+    /// dictionary matching the `ExpoNamiIapTransaction` TypeScript shape.
+    ///
+    /// - Parameter onUpdate: Closure invoked for each verified transaction.
+    func initConnection(onUpdate: @escaping @Sendable ([String: Any]) -> Void) async {
+        await observer.start(onUpdate: onUpdate)
+    }
+
+    /// Stop observing `Transaction.updates`.
+    func endConnection() async {
+        await observer.stop()
+    }
+
+    // MARK: - Private helpers
+
+    /// Retrieve a product from cache or fetch it from StoreKit.
+    private func fetchProduct(_ skuId: String) async throws -> Product {
+        if let cached = productCache[skuId] {
+            return cached
+        }
+        let products = try await Product.products(for: [skuId])
+        guard let p = products.first else {
+            throw ExpoNamiIapError.itemUnavailable(message: "No product for \(skuId)")
+        }
+        productCache[skuId] = p
+        return p
+    }
+
+    /// Determine promotional-offer eligibility by checking whether any active
+    /// entitlement exists in the same subscription group.
+    ///
+    /// If an active (non-revoked) transaction exists in the same group the user
+    /// is not eligible for a promotional offer.
+    private func promoEligibleFor(subscription sub: Product.SubscriptionInfo) async -> Bool {
+        for await result in Transaction.currentEntitlements {
+            if case .verified(let txn) = result,
+               txn.subscriptionGroupID == sub.subscriptionGroupID,
+               txn.revocationDate == nil {
+                return false
+            }
+        }
+        return true
+    }
+}

package/ios/Tests/ErrorsTests.swift

@@ -0,0 +1,189 @@
+//
+//  ErrorsTests.swift
+//  ExpoNamiIap
+//
+//  Copyright (c) 2024 Nami ML Inc. All rights reserved.
+//
+
+import XCTest
+import StoreKit
+@testable import ExpoNamiIap
+
+@available(iOS 15.0, tvOS 15.0, *)
+final class ErrorsTests: XCTestCase {
+
+    // MARK: - ExpoNamiIapError.toDict()
+
+    func testUserCancelledToDictReturnsCorrectShape() {
+        let error = ExpoNamiIapError.userCancelled()
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "user_cancelled")
+        XCTAssertNotNil(dict["message"] as? String)
+        XCTAssertNil(dict["nativeCode"], "nativeCode should be absent when nil")
+    }
+
+    func testUserCancelledWithNativeCodeIncludesIt() {
+        let error = ExpoNamiIapError.userCancelled(nativeCode: "SKError.userCancelled")
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "user_cancelled")
+        XCTAssertEqual(dict["nativeCode"] as? String, "SKError.userCancelled")
+    }
+
+    func testNetworkToDictReturnsCorrectShape() {
+        let error = ExpoNamiIapError.network(message: "Connection timed out", nativeCode: "NSURLError -1001")
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "network")
+        XCTAssertEqual(dict["message"] as? String, "Connection timed out")
+        XCTAssertEqual(dict["nativeCode"] as? String, "NSURLError -1001")
+    }
+
+    func testItemUnavailableToDictReturnsCorrectShape() {
+        let error = ExpoNamiIapError.itemUnavailable(message: "No products found for [\"com.nami.missing\"]")
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "item_unavailable")
+        XCTAssertEqual(dict["message"] as? String, "No products found for [\"com.nami.missing\"]")
+        XCTAssertNil(dict["nativeCode"])
+    }
+
+    func testAlreadyOwnedToDictReturnsCorrectShape() {
+        let error = ExpoNamiIapError.alreadyOwned()
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "already_owned")
+        XCTAssertNotNil(dict["message"] as? String)
+    }
+
+    func testNotAllowedToDictReturnsCorrectShape() {
+        let error = ExpoNamiIapError.notAllowed(message: "Not available in storefront")
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "not_allowed")
+        XCTAssertEqual(dict["message"] as? String, "Not available in storefront")
+    }
+
+    func testUnknownToDictReturnsCorrectShape() {
+        let error = ExpoNamiIapError.unknown(message: "Something went wrong", nativeCode: "systemError(42)")
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "unknown")
+        XCTAssertEqual(dict["message"] as? String, "Something went wrong")
+        XCTAssertEqual(dict["nativeCode"] as? String, "systemError(42)")
+    }
+
+    // MARK: - Errors.toExpoNamiIapError (StoreKitError mapping)
+
+    func testStoreKitErrorUserCancelledMapsCorrectly() {
+        let storeKitError = StoreKitError.userCancelled
+        let result = Errors.toExpoNamiIapError(storeKitError)
+
+        XCTAssertEqual(result.code, "user_cancelled")
+    }
+
+    func testStoreKitErrorNetworkErrorMapsCorrectly() {
+        let urlError = URLError(.notConnectedToInternet)
+        let storeKitError = StoreKitError.networkError(urlError)
+        let result = Errors.toExpoNamiIapError(storeKitError)
+
+        XCTAssertEqual(result.code, "network")
+        XCTAssertNotNil(result.nativeCode)
+    }
+
+    func testStoreKitErrorNotAvailableInStorefrontMapsToNotAllowed() {
+        let storeKitError = StoreKitError.notAvailableInStorefront
+        let result = Errors.toExpoNamiIapError(storeKitError)
+
+        XCTAssertEqual(result.code, "not_allowed")
+    }
+
+    func testStoreKitErrorNotEntitledMapsToNotAllowed() {
+        let storeKitError = StoreKitError.notEntitled
+        let result = Errors.toExpoNamiIapError(storeKitError)
+
+        XCTAssertEqual(result.code, "not_allowed")
+    }
+
+    func testStoreKitErrorSystemErrorMapsToUnknown() {
+        let underlying = NSError(domain: "TestDomain", code: 42, userInfo: nil)
+        let storeKitError = StoreKitError.systemError(underlying)
+        let result = Errors.toExpoNamiIapError(storeKitError)
+
+        XCTAssertEqual(result.code, "unknown")
+        XCTAssertNotNil(result.nativeCode)
+    }
+
+    func testStoreKitErrorUnknownCaseMapsToUnknown() {
+        let storeKitError = StoreKitError.unknown
+        let result = Errors.toExpoNamiIapError(storeKitError)
+
+        XCTAssertEqual(result.code, "unknown")
+    }
+
+    func testArbitraryErrorMapsToUnknown() {
+        let error = NSError(domain: "SomeOther", code: 99, userInfo: [NSLocalizedDescriptionKey: "Boom"])
+        let result = Errors.toExpoNamiIapError(error)
+
+        XCTAssertEqual(result.code, "unknown")
+        XCTAssertNotNil(result.nativeCode)
+    }
+
+    func testExpoNamiIapErrorPassesThroughUnchanged() {
+        let original = ExpoNamiIapError.network(message: "Offline", nativeCode: "NSURLError")
+        let result = Errors.toExpoNamiIapError(original)
+
+        XCTAssertEqual(result.code, "network")
+        XCTAssertEqual(result.message, "Offline")
+        XCTAssertEqual(result.nativeCode, "NSURLError")
+    }
+
+    // MARK: - Errors.fromPurchaseResult
+
+    func testPurchaseResultUserCancelledReturnsCancelledError() async throws {
+        let result = Errors.fromPurchaseResult(.userCancelled)
+
+        let error = try XCTUnwrap(result, "userCancelled must return non-nil")
+        XCTAssertEqual(error.code, "user_cancelled")
+    }
+
+    func testPurchaseResultPendingReturnsPendingAsUnknown() async throws {
+        let result = Errors.fromPurchaseResult(.pending)
+
+        let error = try XCTUnwrap(result, "pending must return non-nil")
+        XCTAssertEqual(error.code, "unknown")
+        XCTAssertTrue(error.message.lowercased().contains("pending"))
+    }
+
+    // NOTE: Product.PurchaseResult.success cannot be constructed in tests without
+    // a real VerificationResult<Transaction>. We verify nil-return via integration tests.
+
+    // MARK: - Dict round-trip
+
+    func testToDictRoundTripPreservesAllFields() {
+        let error = ExpoNamiIapError.network(message: "Timeout", nativeCode: "NSURLError -1001")
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict["code"] as? String, "network")
+        XCTAssertEqual(dict["message"] as? String, "Timeout")
+        XCTAssertEqual(dict["nativeCode"] as? String, "NSURLError -1001")
+        XCTAssertEqual(dict.count, 3, "Dict should have exactly code, message, nativeCode")
+    }
+
+    func testToDictOmitsNativeCodeWhenNil() {
+        let error = ExpoNamiIapError.userCancelled()
+        let dict = error.toDict()
+
+        XCTAssertEqual(dict.count, 2, "Dict should have only code and message when nativeCode is nil")
+        XCTAssertNil(dict["nativeCode"])
+    }
+
+    // MARK: - Errors.itemUnavailable helper
+
+    func testItemUnavailableHelperProducesCorrectCode() {
+        let error = Errors.itemUnavailable("No products found for requested IDs")
+        XCTAssertEqual(error.code, "item_unavailable")
+        XCTAssertEqual(error.message, "No products found for requested IDs")
+    }
+}

package/ios/Tests/ProductMapperTests.swift

@@ -0,0 +1,165 @@
+//
+//  ProductMapperTests.swift
+//  ExpoNamiIap
+//
+//  Copyright (c) 2024 Nami ML Inc. All rights reserved.
+//
+
+import XCTest
+import StoreKit
+@testable import ExpoNamiIap
+
+@available(iOS 15.0, tvOS 15.0, *)
+final class ProductMapperTests: XCTestCase {
+
+    private var session: SKTestSession!
+
+    override func setUp() async throws {
+        try await super.setUp()
+        session = try SKTestSession(configurationFileNamed: "Products")
+        session.disableDialogs = true
+        session.clearTransactions()
+    }
+
+    override func tearDown() async throws {
+        session = nil
+        try await super.tearDown()
+    }
+
+    // MARK: - Helper
+
+    private func product(for id: String) async throws -> Product {
+        let products = try await Product.products(for: [id])
+        return try XCTUnwrap(products.first, "Product \(id) not found in StoreKit config")
+    }
+
+    // MARK: - Consumable maps to one_time_purchase
+
+    func testConsumableProductMapsToOneTimePurchase() async throws {
+        let p = try await product(for: "com.nami.test.consumable")
+        let dict = await ProductMapper.toDict(p)
+
+        XCTAssertEqual(dict["product_ref_id"] as? String, "com.nami.test.consumable")
+        XCTAssertEqual(dict["product_type"] as? String, "one_time_purchase")
+        XCTAssertNotNil(dict["name"] as? String)
+        XCTAssertNotNil(dict["description"] as? String)
+        XCTAssertNil(dict["subscription_period"], "Consumable must not have subscription_period")
+    }
+
+    // MARK: - Non-consumable maps to one_time_purchase
+
+    func testNonConsumableProductMapsToOneTimePurchase() async throws {
+        let p = try await product(for: "com.nami.test.lifetime")
+        let dict = await ProductMapper.toDict(p)
+
+        XCTAssertEqual(dict["product_ref_id"] as? String, "com.nami.test.lifetime")
+        XCTAssertEqual(dict["product_type"] as? String, "one_time_purchase")
+        XCTAssertNil(dict["subscription_period"])
+    }
+
+    // MARK: - Subscription with weekly period
+
+    func testWeeklySubscriptionPeriod() async throws {
+        let p = try await product(for: "com.nami.test.weekly")
+        let dict = await ProductMapper.toDict(p)
+
+        XCTAssertEqual(dict["product_type"] as? String, "subscription")
+
+        let period = try XCTUnwrap(dict["subscription_period"] as? [String: Any])
+        XCTAssertEqual(period["type"] as? String, "week")
+        XCTAssertEqual(period["count"] as? Int, 1)
+    }
+
+    // MARK: - Default offer contains base price and currency
+
+    func testDefaultOfferContainsPriceAndCurrency() async throws {
+        let p = try await product(for: "com.nami.test.weekly")
+        let dict = await ProductMapper.toDict(p)
+
+        let offers = try XCTUnwrap(dict["offers"] as? [[String: Any]])
+        XCTAssertGreaterThanOrEqual(offers.count, 1, "Must have at least a default offer")
+
+        let defaultOffer = try XCTUnwrap(offers.first(where: { ($0["offer_type"] as? String) == "default" }))
+        let price = try XCTUnwrap(defaultOffer["price"] as? Double)
+        XCTAssertEqual(price, 9.99, accuracy: 0.001)
+
+        let currency = try XCTUnwrap(defaultOffer["currency"] as? String)
+        XCTAssertFalse(currency.isEmpty, "Currency code must not be empty")
+    }
+
+    // MARK: - Free trial intro offer maps to free_trial offer_type
+
+    func testFreeTrialIntroOfferMapsToFreeTrialType() async throws {
+        let p = try await product(for: "com.nami.test.monthly.trial")
+        let dict = await ProductMapper.toDict(p)
+
+        let offers = try XCTUnwrap(dict["offers"] as? [[String: Any]])
+        let trialOffer = offers.first(where: { ($0["offer_type"] as? String) == "free_trial" })
+        let trial = try XCTUnwrap(trialOffer, "Expected a free_trial offer")
+
+        let trialPrice = try XCTUnwrap(trial["price"] as? Double)
+        XCTAssertEqual(trialPrice, 0.0, accuracy: 0.001, "Free trial price must be 0")
+
+        let promoPeriod = try XCTUnwrap(trial["promo_period"] as? [String: Any])
+        XCTAssertNotNil(promoPeriod["type"] as? String)
+        XCTAssertNotNil(promoPeriod["count"] as? Int)
+    }
+
+    // MARK: - Pay-as-you-go intro offer maps to intro with promo_period
+
+    func testPayAsYouGoIntroOfferMapsCorrectly() async throws {
+        let p = try await product(for: "com.nami.test.monthly.intro")
+        let dict = await ProductMapper.toDict(p)
+
+        let offers = try XCTUnwrap(dict["offers"] as? [[String: Any]])
+        let introOffer = offers.first(where: { ($0["offer_type"] as? String) == "intro" })
+        let intro = try XCTUnwrap(introOffer, "Expected an intro offer")
+
+        let introPrice = try XCTUnwrap(intro["price"] as? Double)
+        XCTAssertGreaterThan(introPrice, 0.0, "Intro price must be > 0")
+
+        let promoPeriod = try XCTUnwrap(intro["promo_period"] as? [String: Any])
+        XCTAssertEqual(promoPeriod["type"] as? String, "week")
+        XCTAssertEqual(promoPeriod["count"] as? Int, 1)
+
+        let currency = try XCTUnwrap(intro["currency"] as? String)
+        XCTAssertFalse(currency.isEmpty)
+    }
+
+    // MARK: - Subscription period for monthly product
+
+    func testMonthlySubscriptionPeriod() async throws {
+        let p = try await product(for: "com.nami.test.monthly.trial")
+        let dict = await ProductMapper.toDict(p)
+
+        let period = try XCTUnwrap(dict["subscription_period"] as? [String: Any])
+        XCTAssertEqual(period["type"] as? String, "month")
+        XCTAssertEqual(period["count"] as? Int, 1)
+    }
+
+    // MARK: - All required keys present for subscription
+
+    func testAllRequiredKeysPresent() async throws {
+        let p = try await product(for: "com.nami.test.weekly")
+        let dict = await ProductMapper.toDict(p)
+
+        // Keys from NamiProductDetails
+        XCTAssertNotNil(dict["product_ref_id"])
+        XCTAssertNotNil(dict["product_type"])
+        XCTAssertNotNil(dict["offers"])
+        XCTAssertNotNil(dict["name"])
+        XCTAssertNotNil(dict["description"])
+        XCTAssertNotNil(dict["subscription_period"])
+    }
+
+    // MARK: - Consumable has exactly one default offer
+
+    func testConsumableHasExactlyOneDefaultOffer() async throws {
+        let p = try await product(for: "com.nami.test.consumable")
+        let dict = await ProductMapper.toDict(p)
+
+        let offers = try XCTUnwrap(dict["offers"] as? [[String: Any]])
+        XCTAssertEqual(offers.count, 1, "Consumable must have exactly one offer")
+        XCTAssertEqual(offers[0]["offer_type"] as? String, "default")
+    }
+}