[EXTERNAL] Add ExperimentalPreviewRevenueCatPurchasesAPI opt-in req…

…uirement to `Purchases.awaitCustomerInfo()` (#1060)

<!-- Thank you for contributing to Purchases! Before pressing the
"Create Pull Request" button, please provide the following: -->

### Checklist
- [ ] If applicable, unit tests
- [ ] If applicable, create follow-up issues for `purchases-ios` and
hybrids

### Motivation
**Why is this change required? What problem does it solve?**

Follow up from
https://github.com/RevenueCat/purchases-android/pull/1012/files#r1223917692

Instead of only noting that `Purchases.awaitCustomerInfo()` is
experimental in the docs (which are often overlooked 😬), we can be more
explicit and add an opt-in requirement annotation
`ExperimentalPreviewRevenueCatPurchasesAPI`.

Capturing from the [Kotlin Opt-in requirements
docs](https://kotlinlang.org/docs/opt-in-requirements.html):

> The Kotlin standard library provides a mechanism for requiring and
giving explicit consent for using certain elements of APIs. This
mechanism lets library developers inform users of their APIs about
specific conditions that require opt-in, for example, if an API is in
the experimental state and is likely to change in the future.
>
> To prevent potential issues, the compiler warns users of such APIs
about these conditions and requires them to opt in before using the API.

This opens the door to use this annotation in any other APIs which are
experimental, in preview or under cooking, to get initial feedback and
iterate "without" breaking SemVer 🚀

<!-- Please link to issues following this format: Resolves #999999 -->

### Description
**Describe your changes in detail**

- Create `ExperimentalPreviewRevenueCatPurchasesAPI` opt-in requirement
annotation
- Opt in to using `ExperimentalPreviewRevenueCatPurchasesAPI` wherever
`Purchases.awaitCustomerInfo()` is called

**Please describe in detail how you tested your changes**
- Run `purchases` tests
- Run `examples.purchase-test` app

cc @tonidero @vegaro

api-tester/src/main/java/com/revenuecat/apitester/kotlin/PurchasesAPI.kt

@@ -4,6 +4,7 @@ import android.app.Activity
 import android.content.Context
 import com.revenuecat.purchases.CacheFetchPolicy
 import com.revenuecat.purchases.CustomerInfo
+import com.revenuecat.purchases.ExperimentalPreviewRevenueCatPurchasesAPI
 import com.revenuecat.purchases.LogHandler
 import com.revenuecat.purchases.LogLevel
 import com.revenuecat.purchases.Offerings
@@ -38,6 +39,7 @@ import com.revenuecat.purchases.syncPurchasesWith
 import java.net.URL
 import java.util.concurrent.ExecutorService
 
+@OptIn(ExperimentalPreviewRevenueCatPurchasesAPI::class)
 @Suppress("unused", "UNUSED_VARIABLE", "EmptyFunctionBlock", "RemoveExplicitTypeArguments", "RedundantLambdaArrow")
 private class PurchasesAPI {
     @SuppressWarnings("LongParameterList")

examples/purchase-tester/src/main/java/com/revenuecat/purchasetester/OverviewViewModel.kt

@@ -8,6 +8,7 @@ import androidx.lifecycle.ViewModel
 import androidx.lifecycle.viewModelScope
 import com.revenuecat.purchases.CustomerInfo
 import com.revenuecat.purchases.EntitlementInfo
+import com.revenuecat.purchases.ExperimentalPreviewRevenueCatPurchasesAPI
 import com.revenuecat.purchases.Purchases
 import com.revenuecat.purchases.PurchasesError
 import com.revenuecat.purchases.PurchasesException
@@ -16,6 +17,7 @@ import com.revenuecat.purchases.awaitCustomerInfo
 import com.revenuecat.purchases.restorePurchasesWith
 import kotlinx.coroutines.launch
 
+@OptIn(ExperimentalPreviewRevenueCatPurchasesAPI::class)
 class OverviewViewModel(private val interactionHandler: OverviewInteractionHandler) : ViewModel() {
 
     val customerInfo: MutableLiveData<CustomerInfo?> by lazy {

public/src/main/java/com/revenuecat/purchases/ExperimentalPreviewRevenueCatPurchasesAPI.kt

@@ -0,0 +1,19 @@
+package com.revenuecat.purchases
+
+/**
+ * This annotation marks the experimental preview of the RevenueCat Purchases API.
+ * This API is in a preview state and has a very high chance of being changed in the future.
+ *
+ * Any usage of a declaration annotated with `@ExperimentalPreviewRevenueCatPurchasesAPI` must be
+ * accepted either by annotating that usage with the [OptIn] annotation,
+ * e.g. `@OptIn(ExperimentalPreviewRevenueCatPurchasesAPI::class)`, or by using the compiler argument
+ * `-Xopt-in=kotlin.time.ExperimentalPreviewRevenueCatPurchasesAPI`.
+ */
+@Retention(value = AnnotationRetention.BINARY)
+@RequiresOptIn(level = RequiresOptIn.Level.ERROR)
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY,
+)
+annotation class ExperimentalPreviewRevenueCatPurchasesAPI

purchases/src/main/kotlin/com/revenuecat/purchases/coroutinesExtensions.kt

@@ -8,11 +8,12 @@ import kotlin.coroutines.suspendCoroutine
  * Get latest available customer info.
  * Coroutine friendly version of [Purchases.getCustomerInfo].
  *
- * @warning This function is experimental and may change in the future.
+ * @warning This function is marked as [ExperimentalPreviewRevenueCatPurchasesAPI] and may change in the future.
  *
  * @throws [PurchasesException] with a [PurchasesError] if there's an error retrieving the customer info.
  * @return The [CustomerInfo] or a [PurchasesException] with the [PurchasesError]
  */
+@ExperimentalPreviewRevenueCatPurchasesAPI
 suspend fun Purchases.awaitCustomerInfo(): CustomerInfo {
     return suspendCoroutine { continuation ->
         getCustomerInfoWith(

purchases/src/test/java/com/revenuecat/purchases/PurchasesCoroutinesTest.kt

@@ -2,12 +2,14 @@ package com.revenuecat.purchases
 
 import androidx.test.ext.junit.runners.AndroidJUnit4
 import io.mockk.verify
+import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.test.runTest
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.Test
 import org.junit.runner.RunWith
 import org.robolectric.annotation.Config
 
+@OptIn(ExperimentalPreviewRevenueCatPurchasesAPI::class, ExperimentalCoroutinesApi::class)
 @RunWith(AndroidJUnit4::class)
 @Config(manifest = Config.NONE)
 class PurchasesCoroutinesTest : BasePurchasesTest() {