tests and documentation

Author: davedelong

Sources/Purchasing/Purchases/Purchases.swift

@@ -1720,9 +1720,27 @@ public extension Purchases {
     @objc func invalidateVirtualCurrenciesCache() {
         self.virtualCurrencyManager.invalidateVirtualCurrenciesCache()
     }
-
+    
+    /// Spend virtual currency
+    ///
+    /// Spending virtual currency is only allowed when the SDK is configured using ``Configuration.Builder.with(iamEnabled:)``.
+    /// Attempting to spend virtual currency without enabling IAM will result in a thrown error.
+    ///
+    /// - Parameters:
+    ///   - amounts: A dictionary containing the amounts of each currency to spend. The key is virtual currency's `code`,
+    ///   and the value is how much of that currency to spend. All values should be greater than zero. Values equal to zero are ignored,
+    ///   and values less than zero will be interpreted as positive.
+    ///
+    ///   In other words, `["VC_CODE": -42]` and `["VC_CODE": 42]` will be interpreted as equivalent.
+    ///
+    ///   If the dictionary is empty or all values are zero, then no currencies will be spent,
+    ///   and this will return the result of invoking ``virtualCurrencies()``.
+    ///
+    ///   You may specify multiple currencies to spend in a single transaction.
+    ///   - reference: An optional app-specific reference string that refers to this transaction.
+    /// - Returns: The latest ``VirtualCurrencies`` for the user after the transaction has processed
     @_spi(Internal)
-    func spendVirtualCurrencies(amounts: [String: Int], reference: String?) async throws -> VirtualCurrencies {
+    func spendVirtualCurrencies(amounts: [String: Int], reference: String? = nil) async throws -> VirtualCurrencies {
         guard self.tokenManager.enabled else {
             let message = "Spending virtual currencies requires .with(iamEnabled: true)"
             let error = NewErrorUtils.unsupportedError(message: message)
@@ -1737,11 +1755,34 @@ public extension Purchases {
             throw publicError
         }
     }
-
+    
+    /// Spend virtual currency
+    ///
+    /// - SeeAlso: ``spendVirtualCurrencies(amounts:reference:)``
     @_spi(Internal)
-    func spendVirtualCurrency(code: String, amount: Int, reference: String?) async throws -> VirtualCurrencies {
+    func spendVirtualCurrency(code: String, amount: Int, reference: String? = nil) async throws -> VirtualCurrencies {
         return try await spendVirtualCurrencies(amounts: [code: amount], reference: reference)
     }
+
+    @_spi(Internal)
+    @objc
+    func spendVirtualCurrency(amounts: [String: Int],
+                              reference: String?,
+                              completion: @escaping (VirtualCurrencies?, PublicError?) -> Void) {
+        Task {
+            do {
+                let virtualCurrencies = try await self.spendVirtualCurrencies(amounts: amounts, reference: reference)
+                OperationDispatcher.dispatchOnMainActor {
+                    completion(virtualCurrencies, nil)
+                }
+            } catch {
+                let publicError = NewErrorUtils.purchasesError(withUntypedError: error).asPublicError
+                OperationDispatcher.dispatchOnMainActor {
+                    completion(nil, publicError)
+                }
+            }
+        }
+    }
 }
 #endif
 

Sources/Purchasing/Purchases/PurchasesType.swift

@@ -1009,6 +1009,22 @@ public protocol PurchasesType: AnyObject {
             completion: @escaping @Sendable (VirtualCurrencies?, PublicError?) -> Void
         )
 
+        /**
+         * Spends virtual currencies
+         *
+         * - Parameter amounts: A dictionary key by ``VirtualCurrency`` codes with values corresponding
+         * to the amount of that currency to spend. Values must be positive non-zero numbers. Negative values will
+         * be interpreted as positive. Zero values are ignored.
+         * - Parameter reference: An app-specified string to refer to this transaction
+         * - Parameter completion: The callback that is invoked with the request is complete
+         * - Warning: Using this method requires enabling IAM.
+         */
+        @objc
+        @_spi(Internal)
+        func spendVirtualCurrency(amounts: [String: Int],
+                                  reference: String?,
+                                  completion: @escaping (VirtualCurrencies?, PublicError?) -> Void)
+
         /**
          * The currently cached ``VirtualCurrencies`` if one is available.
          * This is synchronous, and therefore useful for contexts where an app needs a `VirtualCurrencies`

Tests/UnitTests/Mocks/MockPurchases.swift

@@ -490,6 +490,12 @@ extension MockPurchases: PurchasesType {
         self.unimplemented()
     }
 
+    func spendVirtualCurrencies(amount: [String: Int],
+                                reference: String?,
+                                completion: @escaping (RevenueCat.VirtualCurrencies?, RevenueCat.PublicError?) -> Void) {
+        self.unimplemented()
+    }
+
     func invalidateVirtualCurrenciesCache() {
         self.unimplemented()
     }

Tests/UnitTests/Mocks/MockVirtualCurrenciesAPI.swift

@@ -37,4 +37,22 @@ class MockVirtualCurrenciesAPI: VirtualCurrenciesAPI {
 
         completion(stubbedGetVirtualCurrenciesResult ?? .failure(.missingAppUserID()))
     }
+
+    var invokedSpendVirtualCurrencies = false
+    var invokedSpendVirtualCurrenciesCount = 0
+    var invokedSpendVirtualCurrenciesParameters: (amounts: [String: Int], reference: String?)?
+
+    var stubbedSpendVirtualCurrenciesResult: Result<VirtualCurrenciesResponse, BackendError>?
+
+    override func spendVirtualCurrencies(
+        amounts: [String: Int],
+        reference: String?,
+        completion: @escaping VirtualCurrenciesResponseHandler
+    ) {
+        invokedSpendVirtualCurrencies = true
+        invokedSpendVirtualCurrenciesCount += 1
+        invokedSpendVirtualCurrenciesParameters = (amounts, reference)
+
+        completion(stubbedSpendVirtualCurrenciesResult ?? .failure(.missingAppUserID()))
+    }
 }

Tests/UnitTests/Mocks/MockVirtualCurrencyManager.swift

@@ -29,6 +29,21 @@ class MockVirtualCurrencyManager: VirtualCurrencyManagerType {
         return try stubbedVirtualCurrenciesResult.get()
     }
 
+    var stubbedSpendVirtualCurrenciesResult: Result<RevenueCat.VirtualCurrencies, Error> = .success(VirtualCurrencies(
+        virtualCurrencies: [:]
+    ))
+
+    var spendVirtualCurrenciesCallCount = 0
+    var spendVirtualCurrenciesCalled = false
+    var invokedSpendVirtualCurrenciesParametersList: [(amounts: [String: Int], reference: String?)] = []
+    func spendVirtualCurrencies(amounts: [String: Int], reference: String?) async throws -> RevenueCat.VirtualCurrencies {
+        self.spendVirtualCurrenciesCallCount += 1
+        self.spendVirtualCurrenciesCalled = true
+        self.invokedSpendVirtualCurrenciesParametersList.append((amounts, reference))
+
+        return try stubbedSpendVirtualCurrenciesResult.get()
+    }
+
     var invalidateVirtualCurrenciesCacheCallCount = 0
     var invalidateVirtualCurrenciesCacheCalled = false
     func invalidateVirtualCurrenciesCache() {

Tests/UnitTests/Networking/BackendErrorCodeTests.swift

@@ -46,4 +46,46 @@ class BackendErrorCodeTests: TestCase {
         expect(BackendErrorCode.cannotAliasToAuthenticatedUser.toPurchasesErrorCode()) == .configurationError
     }
 
+    // MARK: - unknownVirtualCurrencyCode
+
+    func testUnknownVirtualCurrencyCodeDecodesFromItsRawIntValue() {
+        expect(BackendErrorCode(code: 7870)) == .unknownVirtualCurrencyCode
+    }
+
+    func testUnknownVirtualCurrencyCodeDecodesFromItsRawStringValue() {
+        expect(BackendErrorCode(code: "7870")) == .unknownVirtualCurrencyCode
+    }
+
+    func testUnknownVirtualCurrencyCodeMapsToPurchaseInvalidError() {
+        expect(BackendErrorCode.unknownVirtualCurrencyCode.toPurchasesErrorCode()) == .purchaseInvalidError
+    }
+
+    // MARK: - duplicateVirtualCurrencyTransaction
+
+    func testDuplicateVirtualCurrencyTransactionDecodesFromItsRawIntValue() {
+        expect(BackendErrorCode(code: 8139)) == .duplicateVirtualCurrencyTransaction
+    }
+
+    func testDuplicateVirtualCurrencyTransactionDecodesFromItsRawStringValue() {
+        expect(BackendErrorCode(code: "8139")) == .duplicateVirtualCurrencyTransaction
+    }
+
+    func testDuplicateVirtualCurrencyTransactionMapsToPurchaseInvalidError() {
+        expect(BackendErrorCode.duplicateVirtualCurrencyTransaction.toPurchasesErrorCode()) == .purchaseInvalidError
+    }
+
+    // MARK: - invalidIdempotencyKey
+
+    func testInvalidIdempotencyKeyDecodesFromItsRawIntValue() {
+        expect(BackendErrorCode(code: 8140)) == .invalidIdempotencyKey
+    }
+
+    func testInvalidIdempotencyKeyDecodesFromItsRawStringValue() {
+        expect(BackendErrorCode(code: "8140")) == .invalidIdempotencyKey
+    }
+
+    func testInvalidIdempotencyKeyMapsToPurchaseInvalidError() {
+        expect(BackendErrorCode.invalidIdempotencyKey.toPurchasesErrorCode()) == .purchaseInvalidError
+    }
+
 }

Tests/UnitTests/Networking/Requests/SpendVirtualCurrenciesOperationBodyTests.swift

@@ -0,0 +1,67 @@
+//
+//  Copyright RevenueCat Inc. All Rights Reserved.
+//
+//  Licensed under the MIT License (the "License");
+//  you may not use this file except in compliance with the License.
+//  You may obtain a copy of the License at
+//
+//      https://opensource.org/licenses/MIT
+//
+//  SpendVirtualCurrenciesOperationBodyTests.swift
+//
+//  Created by RevenueCat on 8/25/26.
+
+import Nimble
+import XCTest
+
+@testable import RevenueCat
+
+// NOTE: These tests intentionally exercise `SpendVirtualCurrenciesOperation.Body`'s `Encodable`
+// conformance directly rather than driving the operation through `MockHTTPClient`. As written,
+// `HTTPRequestPath.pathComponent`'s `.spendVirtualCurrencies` case calls `assertionFailure(...)`,
+// and `MockHTTPClient.perform` always resolves the mock lookup URL with `preferIAMPath: false`
+// (see `HTTPRequestPath.url(preferIAMPath:)`), which means `pathComponent` (not `iamPathComponent`)
+// is always evaluated. Any test that performs an actual `.spendVirtualCurrencies` HTTP request
+// through `MockHTTPClient` would therefore always hit that `assertionFailure`, crashing the test
+// process. Until the test double is updated to honor `tokenManager.enabled` (mirroring what
+// `HTTPClient.perform` does in production), the network round-trip for this operation can't be
+// safely exercised with the existing test infrastructure.
+class SpendVirtualCurrenciesOperationBodyTests: TestCase {
+
+    func testBodyEncodesAdjustmentsAndReference() throws {
+        let body = SpendVirtualCurrenciesOperation.Body(
+            adjustments: ["GLD": 50, "SLV": 10],
+            reference: "order-123"
+        )
+
+        let data = try JSONEncoder().encode(body)
+        let json = try XCTUnwrap(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+
+        let adjustments = try XCTUnwrap(json["adjustments"] as? [String: Int])
+        expect(adjustments) == ["GLD": 50, "SLV": 10]
+        expect(json["reference"] as? String) == "order-123"
+    }
+
+    func testBodyOmitsReferenceKeyWhenNil() throws {
+        let body = SpendVirtualCurrenciesOperation.Body(
+            adjustments: ["GLD": 50],
+            reference: nil
+        )
+
+        let data = try JSONEncoder().encode(body)
+        let json = try XCTUnwrap(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+
+        expect(json["adjustments"] as? [String: Int]) == ["GLD": 50]
+        expect(json.keys.contains("reference")).to(beFalse())
+    }
+
+    func testBodyEncodesEmptyAdjustments() throws {
+        let body = SpendVirtualCurrenciesOperation.Body(adjustments: [:], reference: nil)
+
+        let data = try JSONEncoder().encode(body)
+        let json = try XCTUnwrap(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+
+        expect(json["adjustments"] as? [String: Int]) == [:]
+    }
+
+}

Tests/UnitTests/Purchasing/Purchases/PurchasesVirtualCurrenciesTests.swift

@@ -139,4 +139,90 @@ class PurchasesVirtualCurrenciesTests: BasePurchasesTests {
         expect(self.mockVirtualCurrencyManager.cachedVirtualCurrenciesCallCount).to(equal(1))
         expect(Thread.isMainThread).to(beTrue())
     }
+
+    // MARK: - spendVirtualCurrencies() Tests
+
+    func testSpendVirtualCurrenciesThrowsUnsupportedErrorWhenIAMIsNotEnabled() async throws {
+        // `self.tokenManager` defaults to disabled in `BasePurchasesTests.setUpWithError()`.
+        var thrown: Error?
+        do {
+            _ = try await self.purchases.spendVirtualCurrencies(amounts: ["GLD": 10], reference: nil)
+        } catch {
+            thrown = error
+        }
+
+        expect(thrown).to(matchError(ErrorCode.unsupportedError))
+        expect(self.mockVirtualCurrencyManager.spendVirtualCurrenciesCalled).to(beFalse())
+    }
+
+    func testSpendVirtualCurrencyThrowsUnsupportedErrorWhenIAMIsNotEnabled() async throws {
+        var thrown: Error?
+        do {
+            _ = try await self.purchases.spendVirtualCurrency(code: "GLD", amount: 10, reference: nil)
+        } catch {
+            thrown = error
+        }
+
+        expect(thrown).to(matchError(ErrorCode.unsupportedError))
+        expect(self.mockVirtualCurrencyManager.spendVirtualCurrenciesCalled).to(beFalse())
+    }
+
+    func testSpendVirtualCurrenciesForwardsSuccessWhenIAMIsEnabled() async throws {
+        self.tokenManager = MockTokenManager(enabled: true)
+        self.setupPurchases()
+        self.mockVirtualCurrencyManager.stubbedSpendVirtualCurrenciesResult = .success(Self.mockVirtualCurrencies)
+
+        let vcs = try await self.purchases.spendVirtualCurrencies(amounts: ["GLD": 10], reference: "ref-1")
+
+        expect(vcs).to(equal(Self.mockVirtualCurrencies))
+        expect(self.mockVirtualCurrencyManager.spendVirtualCurrenciesCalled).to(beTrue())
+        expect(self.mockVirtualCurrencyManager.spendVirtualCurrenciesCallCount).to(equal(1))
+        expect(self.mockVirtualCurrencyManager.invokedSpendVirtualCurrenciesParametersList.first?.amounts)
+            == ["GLD": 10]
+        expect(self.mockVirtualCurrencyManager.invokedSpendVirtualCurrenciesParametersList.first?.reference)
+            == "ref-1"
+    }
+
+    func testSpendVirtualCurrenciesForwardsErrorWhenIAMIsEnabled() async throws {
+        self.tokenManager = MockTokenManager(enabled: true)
+        self.setupPurchases()
+        let backendError: BackendError = .networkError(.offlineConnection())
+        self.mockVirtualCurrencyManager.stubbedSpendVirtualCurrenciesResult = .failure(backendError)
+
+        do {
+            _ = try await self.purchases.spendVirtualCurrencies(amounts: ["GLD": 10], reference: nil)
+            fail("An error should have been thrown")
+        } catch {
+            expect(error).to(matchError(backendError.asPurchasesError))
+        }
+    }
+
+    func testSpendVirtualCurrencyConvenienceMethodForwardsSingleAmountWhenIAMIsEnabled() async throws {
+        self.tokenManager = MockTokenManager(enabled: true)
+        self.setupPurchases()
+        self.mockVirtualCurrencyManager.stubbedSpendVirtualCurrenciesResult = .success(Self.mockVirtualCurrencies)
+
+        let vcs = try await self.purchases.spendVirtualCurrency(code: "GLD", amount: 25, reference: "ref-2")
+
+        expect(vcs).to(equal(Self.mockVirtualCurrencies))
+        expect(self.mockVirtualCurrencyManager.spendVirtualCurrenciesCallCount).to(equal(1))
+        expect(self.mockVirtualCurrencyManager.invokedSpendVirtualCurrenciesParametersList.first?.amounts)
+            == ["GLD": 25]
+        expect(self.mockVirtualCurrencyManager.invokedSpendVirtualCurrenciesParametersList.first?.reference)
+            == "ref-2"
+    }
+
+    func testSpendVirtualCurrencyConvenienceMethodForwardsErrorWhenIAMIsEnabled() async throws {
+        self.tokenManager = MockTokenManager(enabled: true)
+        self.setupPurchases()
+        let backendError: BackendError = .networkError(.offlineConnection())
+        self.mockVirtualCurrencyManager.stubbedSpendVirtualCurrenciesResult = .failure(backendError)
+
+        do {
+            _ = try await self.purchases.spendVirtualCurrency(code: "GLD", amount: 25, reference: nil)
+            fail("An error should have been thrown")
+        } catch {
+            expect(error).to(matchError(backendError.asPurchasesError))
+        }
+    }
 }