Deprecate usesStoreKit2IfAvailable (#2293)

There's been a lot of customer confusion with the use SK2 parameter. 
In order to reduce confusion, and to improve the overall experience,
we're moving into a more opinionated approach.
Currently, we're defaulting to SK1-only. 

Once we get diagnostics data in, we'll be able to get more visibility
into real-world, production performance of StoreKit 1 vs StoreKit 2 on a
per-API basis. Using this data, we will implement remote configuration
to ensure that the best implementation is utilized for each specific
functionality, optimizing for maximum stability and performance.

Until then, we can save our customers from confusion and headache by
going back to the simplest approach.

### What this looks like at the callsite

<img width="1152" alt="Screenshot 2023-02-17 at 2 38 02 PM"
src="https://user-images.githubusercontent.com/3922667/219732743-a974a641-f716-49e9-ad66-d6e3d77328eb.png">

### What the relevant DocC page looks like

<img width="1028" alt="Screenshot 2023-02-17 at 2 28 20 PM"
src="https://user-images.githubusercontent.com/3922667/219732706-fd48dd6d-3071-48b9-83e7-cb138a443155.png">

---------

Co-authored-by: NachoSoto <NachoSoto@users.noreply.github.com>

Sources/Misc/Deprecations.swift

@@ -14,7 +14,7 @@
 import Foundation
 import StoreKit
 
-// swiftlint:disable line_length missing_docs
+// swiftlint:disable line_length missing_docs file_length
 
 public extension Purchases {
 
@@ -389,3 +389,29 @@ extension CustomerInfo {
     }
 
 }
+
+public extension Configuration.Builder {
+
+    /// Set `usesStoreKit2IfAvailable`. If `true`, the SDK will use StoreKit 2 APIs internally. If disabled, it will use StoreKit 1 APIs instead.
+    /// - Parameter usesStoreKit2IfAvailable: enable StoreKit 2 on devices that support it.
+    /// Defaults to  `false`.
+    /// - Important: This configuration flag has been deprecated, and will be replaced by automatic remote configuration in the future.
+    /// However, apps using it should work correctly.
+    ///
+    @available(*, deprecated, message: """
+    RevenueCat currently uses StoreKit 1 for purchases, as its stability in production scenarios has
+    proven to be more performant than StoreKit 2.
+
+    We're collecting more data on the best approach, but StoreKit 1 vs StoreKit 2 is an implementation detail
+    that you shouldn't need to care about.
+
+    Simply remove this method call to let RevenueCat decide for you which StoreKit implementation to use.
+    """)
+    @objc func with(usesStoreKit2IfAvailable: Bool) -> Configuration.Builder {
+        self.storeKit2Setting = .init(useStoreKit2IfAvailable: usesStoreKit2IfAvailable)
+        return self
+    }
+
+}
+
+// swiftlint:enable line_length missing_docs file_length

Sources/Purchasing/Configuration.swift

@@ -31,7 +31,6 @@ import Foundation
  *                                  .with(userDefaults: myUserDefaults)
  *                                  .with(networkTimeout: 15)
  *                                  .with(storeKit1Timeout: 15)
- *                                  .with(usesStoreKit2IfAvailable: true)
  *                                  .build()
  *  Purchases.configure(with: configuration)
  * ```
@@ -75,13 +74,15 @@ import Foundation
     /// The Builder for ```Configuration```.
     @objc(RCConfigurationBuilder) public class Builder: NSObject {
 
+        // made internal to access it in Deprecations.swift
+        var storeKit2Setting: StoreKit2Setting = .default
+
         private static let minimumTimeout: TimeInterval = 5
 
         private(set) var apiKey: String
         private(set) var appUserID: String?
         private(set) var observerMode: Bool = false
         private(set) var userDefaults: UserDefaults?
-        private(set) var storeKit2Setting: StoreKit2Setting = .default
         private(set) var dangerousSettings: DangerousSettings?
         private(set) var networkTimeout = Configuration.networkTimeoutDefault
         private(set) var storeKit1Timeout = Configuration.storeKitRequestTimeoutDefault
@@ -136,16 +137,6 @@ import Foundation
             return self
         }
 
-        /**
-         * Set `usesStoreKit2IfAvailable`.
-         * - Parameter usesStoreKit2IfAvailable: opt in using StoreKit 2 on devices that support it.
-         * Defaults to  `false`.
-         */
-        @objc public func with(usesStoreKit2IfAvailable: Bool) -> Builder {
-            self.storeKit2Setting = .init(useStoreKit2IfAvailable: usesStoreKit2IfAvailable)
-            return self
-        }
-
         /**
          * Set `dangerousSettings`.
          * - Parameter dangerousSettings: Only use if suggested by RevenueCat support team.

Sources/Purchasing/Purchases/Purchases.swift

@@ -894,7 +894,6 @@ public extension Purchases {
      * ```swift
      *  Purchases.configure(
      *      with: Configuration.Builder(withAPIKey: Constants.apiKey)
-     *               .with(usesStoreKit2IfAvailable: true)
      *               .with(observerMode: false)
      *               .with(appUserID: "<app_user_id>")
      *               .build()
@@ -933,7 +932,6 @@ public extension Purchases {
      * ```swift
      *  Purchases.configure(
      *      with: .init(withAPIKey: Constants.apiKey)
-     *               .with(usesStoreKit2IfAvailable: true)
      *               .with(observerMode: false)
      *               .with(appUserID: "<app_user_id>")
      *      )

Tests/APITesters/SwiftAPITester/SwiftAPITester/ConfigurationAPI.swift

@@ -19,7 +19,6 @@ func checkConfigurationAPI() {
         .with(dangerousSettings: DangerousSettings())
         .with(networkTimeout: 1)
         .with(storeKit1Timeout: 1)
-        .with(usesStoreKit2IfAvailable: false)
         .with(platformInfo: Purchases.PlatformInfo(flavor: "", version: ""))
         .with(entitlementVerificationMode: .enforced)
         .build()

Tests/UnitTests/Purchasing/Purchases/PurchasesConfiguringTests.swift

@@ -324,6 +324,7 @@ class PurchasesConfiguringTests: BasePurchasesTests {
         expect(self.storeKit1Wrapper.delegate) === self.purchasesOrchestrator
     }
 
+    @available(*, deprecated) // Ignore deprecation warnings
     func testSetsSelfAsStoreKit1WrapperDelegateForSK1() {
         let configurationBuilder = Configuration.Builder(withAPIKey: "")
             .with(usesStoreKit2IfAvailable: false)
@@ -332,6 +333,7 @@ class PurchasesConfiguringTests: BasePurchasesTests {
         expect(purchases.isStoreKit1Configured) == true
     }
 
+    @available(*, deprecated) // Ignore deprecation warnings
     func testDoesNotInitializeSK1IfSK2Enabled() throws {
         try AvailabilityChecks.iOS15APIAvailableOrSkipTest()