Add sync version of methods, update KDoc and hide internals

superwall/src/main/java/com/superwall/sdk/analytics/internal/Tracking.kt

@@ -23,9 +23,16 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withContext
 import java.util.Date
 
+/**
+ * Tracks an analytical event by sending it to the server and, for internal Superwall events, the delegate.
+ *
+ * @param event The event you want to track.
+ * @return TrackingResult The result of the tracking operation.
+ */
 suspend fun Superwall.track(event: Trackable): TrackingResult {
     return withErrorTrackingAsync {
         // Wait for the SDK to be fully initialized
@@ -104,6 +111,24 @@ suspend fun Superwall.track(event: Trackable): TrackingResult {
     }
 }
 
+/**
+ * Tracks an analytical event synchronously.
+ * Warning: This blocks the calling thread.
+ * @param event The event you want to track.
+ * @return TrackingResult The result of the tracking operation.
+ */
+fun Superwall.trackSync(event: Trackable): TrackingResult =
+    runBlocking {
+        track(event)
+    }
+
+/**
+ * Attempts to implicitly trigger a paywall for a given analytical event.
+ *
+ * @param event The tracked event.
+ * @param eventData The event data that could trigger a paywall.
+ */
+
 suspend fun Superwall.handleImplicitTrigger(
     event: Trackable,
     eventData: EventData,

superwall/src/main/java/com/superwall/sdk/models/paywall/PaywallPresentationStyle.kt

@@ -14,7 +14,7 @@ enum class PaywallPresentationStyle(
     FULLSCREEN("FULLSCREEN"),
 
     @SerialName("NO_ANIMATION")
-    FULLSCREEN_NO_ANIMATION("NO_ANIMATION"),
+    FULLSCREEN_NO_ANIMATION("FULLSCREEN_NO_ANIMATION"),
 
     @SerialName("PUSH")
     PUSH("PUSH"),

superwall/src/main/java/com/superwall/sdk/paywall/presentation/PublicPresentation.kt

@@ -23,8 +23,12 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withContext
 
+/**
+ * Dismisses the presented paywall, if one exists.
+ */
 suspend fun Superwall.dismiss() =
     withContext(Dispatchers.Main) {
         val completionSignal = CompletableDeferred<Unit>()
@@ -40,6 +44,19 @@ suspend fun Superwall.dismiss() =
         completionSignal.await()
     }
 
+/**
+ * Dismisses the presented paywall synchronously, if one exists.
+ * Warning: This blocks the calling thread.
+ */
+fun Superwall.dismissSync() {
+    runBlocking {
+        dismiss()
+    }
+}
+
+/**
+ * Dismisses the presented paywall, if it exists, in order to present a different one.
+ */
 suspend fun Superwall.dismissForNextPaywall() =
     withContext(Dispatchers.Main) {
         val completionSignal = CompletableDeferred<Unit>()
@@ -58,6 +75,37 @@ suspend fun Superwall.dismissForNextPaywall() =
         completionSignal.await()
     }
 
+/**
+ * Dismisses the presented paywall synchronously, if it exists, in order to present a different one.
+ * Warning: This blocks the calling thread.
+ */
+fun Superwall.dismissSyncForNextPaywall() =
+    runBlocking {
+        dismissForNextPaywall()
+    }
+
+/**
+ * Registers an event to access a feature. When the event is added to a campaign on the Superwall dashboard, it can show a paywall.
+ *
+ * This shows a paywall to the user when: An event you provide is added to a campaign on the [Superwall Dashboard](https://superwall.com/dashboard);
+ * the user matches a rule in the campaign; and the user doesn't have an active subscription.
+ *
+ * Before using this method, you'll first need to create a campaign and add the event to the campaign on the [Superwall Dashboard](https://superwall.com/dashboard).
+ *
+ * The paywall shown to the user is determined by the rules defined in the campaign. When a user is assigned a paywall within a rule,
+ * they will continue to see that paywall unless you remove the paywall from the rule or reset assignments to the paywall.
+ *
+ * @param event The name of the event you wish to register.
+ * @param params Optional parameters you'd like to pass with your event. These can be referenced within the rules of your campaign.
+ *               Keys beginning with `$` are reserved for Superwall and will be dropped. Values can be any JSON encodable value, URLs or Dates.
+ *               Arrays and dictionaries as values are not supported at this time, and will be dropped. Defaults to `null`.
+ * @param handler An optional handler whose functions provide status updates for a paywall. Defaults to `null`.
+ * @param feature A completion block containing a feature that you wish to paywall. Access to this block is remotely configurable via the
+ *                [Superwall Dashboard](https://superwall.com/dashboard). If the paywall is set to _Non Gated_, this will be called when
+ *                the paywall is dismissed or if the user is already paying. If the paywall is _Gated_, this will be called only if the user
+ *                is already paying or if they begin paying. If no paywall is configured, this gets called immediately. This will not be called
+ *                in the event of an error, which you can detect via the `handler`.
+ */
 fun Superwall.register(
     event: String,
     params: Map<String, Any>? = null,

superwall/src/main/java/com/superwall/sdk/paywall/presentation/get_paywall/InternalGetPaywall.kt

@@ -9,6 +9,9 @@ import com.superwall.sdk.paywall.presentation.internal.state.PaywallState
 import com.superwall.sdk.paywall.presentation.rule_logic.RuleEvaluationOutcome
 import com.superwall.sdk.paywall.vc.PaywallView
 import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.collectLatest
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
 
 data class PaywallComponents(
     val view: PaywallView,
@@ -20,6 +23,14 @@ data class PaywallComponents(
     val viewController: PaywallView = view
 }
 
+/**
+ * Gets a paywall to present, publishing [PaywallState] objects that provide updates on the lifecycle of the paywall.
+ *
+ * @param request A presentation request of type [PresentationRequest] to feed into a presentation pipeline.
+ * @param publisher A [MutableSharedFlow] that emits [PaywallState] objects.
+ * @return A [PaywallView] to present.
+ * @throws Throwable if an error occurs during the process.
+ */
 @Throws(Throwable::class)
 suspend fun Superwall.getPaywall(
     request: PresentationRequest,
@@ -40,3 +51,29 @@ suspend fun Superwall.getPaywall(
 //        throw mapError(error, toObjc = toObjc)
         throw error
     }
+
+/**
+ * Gets a paywall to present synchronously, providing updates on the lifecycle of the paywall through a callback.
+ * Warning: This blocks the calling thread until the paywall is returned.
+ *
+ * @param request A presentation request of type [PresentationRequest] to feed into a presentation pipeline.
+ * @param onStateChanged A callback function that receives [PaywallState] updates.
+ * @return A [PaywallView] to present.
+ * @throws Throwable if an error occurs during the process.
+ */
+@Throws(Throwable::class)
+fun Superwall.getPaywallSync(
+    request: PresentationRequest,
+    onStateChanged: (PaywallState) -> Unit = {},
+): PaywallView {
+    val scope = Superwall.instance.ioScope
+    val publisher = MutableSharedFlow<PaywallState>()
+    scope.launch {
+        publisher.collectLatest {
+            onStateChanged(it)
+        }
+    }
+    return runBlocking {
+        getPaywall(request, publisher)
+    }
+}

superwall/src/main/java/com/superwall/sdk/paywall/presentation/get_presentation_result/PublicGetPresentationResult.kt

@@ -8,9 +8,23 @@ import com.superwall.sdk.models.events.EventData
 import com.superwall.sdk.paywall.presentation.internal.PresentationRequestType
 import com.superwall.sdk.paywall.presentation.internal.request.PresentationInfo
 import com.superwall.sdk.paywall.presentation.result.PresentationResult
+import kotlinx.coroutines.runBlocking
 import java.util.Date
 import java.util.HashMap
 
+/**
+ * Preemptively gets the result of registering an event.
+ *
+ * This helps you determine whether a particular event will present a paywall
+ * in the future.
+ *
+ * Note that this method does not present a paywall. To do that, use
+ * `register(event:params:handler:feature:)`.
+ *
+ * @param event The name of the event you want to register.
+ * @param params Optional parameters you'd like to pass with your event.
+ * @return A [PresentationResult] that indicates the result of registering an event.
+ */
 suspend fun Superwall.getPresentationResult(
     event: String,
     params: Map<String, Any>? = null,
@@ -29,6 +43,32 @@ suspend fun Superwall.getPresentationResult(
     )
 }
 
+/**
+ * Synchronously preemptively gets the result of registering an event.
+ *
+ * This helps you determine whether a particular event will present a paywall
+ * in the future.
+ *
+ * Note that this method does not present a paywall. To do that, use
+ * `register(event:params:handler:feature:)`.
+ *
+ * Warning: This blocks the calling thread.
+ *
+ * @param event The name of the event you want to register.
+ * @param params Optional parameters you'd like to pass with your event.
+ * @return A [PresentationResult] that indicates the result of registering an event.
+ */
+fun Superwall.getPresentationResultSync(
+    event: String,
+    params: Map<String, Any>? = null,
+): PresentationResult =
+    runBlocking {
+        getPresentationResult(
+            event,
+            params,
+        )
+    }
+
 internal suspend fun Superwall.internallyGetPresentationResult(
     event: Trackable,
     isImplicit: Boolean,

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/GetPaywallComponents.kt

@@ -12,6 +12,7 @@ import com.superwall.sdk.paywall.presentation.internal.operators.getPresenterIfN
 import com.superwall.sdk.paywall.presentation.internal.operators.waitForSubsStatusAndConfig
 import com.superwall.sdk.paywall.presentation.internal.state.PaywallState
 import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.runBlocking
 
 /**
  * Runs a pipeline of operations to get a paywall to present and associated components.
@@ -57,3 +58,21 @@ suspend fun Superwall.getPaywallComponents(
         debugInfo = debugInfo,
     )
 }
+
+/**
+ * Synchronously runs a pipeline of operations to get a paywall to present and associated components.
+ *
+ * @param request The presentation request.
+ * @param publisher A `MutableStateFlow` that gets sent `PaywallState` objects.
+ * @return A `PaywallComponents` object that contains objects associated with the
+ * paywall view controller.
+ * @throws PresentationPipelineError object associated with stages of the pipeline.
+ */
+
+fun Superwall.getPaywallComponentsSync(
+    request: PresentationRequest,
+    publisher: MutableSharedFlow<PaywallState>? = null,
+): PaywallComponents =
+    runBlocking {
+        getPaywallComponents(request, publisher)
+    }

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/InternalPresentation.kt

@@ -13,8 +13,15 @@ import kotlinx.coroutines.withContext
 
 typealias PaywallStatePublisher = Flow<PaywallState>
 
+/**
+ * Runs a background task to present a paywall, publishing [PaywallState] objects that provide updates on the lifecycle of the paywall.
+ *
+ * @param request A presentation request of type [PresentationRequest] to feed into a presentation pipeline.
+ * @param publisher A publisher fed into the pipeline that sends state updates.
+ */
+
 @Throws(Throwable::class)
-suspend fun Superwall.internallyPresent(
+internal suspend fun Superwall.internallyPresent(
     request: PresentationRequest,
     publisher: MutableSharedFlow<PaywallState>,
 ) {
@@ -48,7 +55,7 @@ suspend fun Superwall.internallyPresent(
     }
 }
 
-suspend fun Superwall.dismiss(
+internal suspend fun Superwall.dismiss(
     paywallView: PaywallView,
     result: PaywallResult,
     closeReason: PaywallCloseReason = PaywallCloseReason.SystemLogic,

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/PresentationErrors.kt

@@ -5,7 +5,7 @@ import com.superwall.sdk.paywall.presentation.internal.state.PaywallSkippedReaso
 import com.superwall.sdk.paywall.presentation.internal.state.PaywallState
 import kotlinx.coroutines.flow.MutableSharedFlow
 
-suspend fun Superwall.userIsSubscribed(paywallStatePublisher: MutableSharedFlow<PaywallState>?): PresentationPipelineError {
+internal suspend fun Superwall.userIsSubscribed(paywallStatePublisher: MutableSharedFlow<PaywallState>?): PresentationPipelineError {
     val state = PaywallState.Skipped(PaywallSkippedReason.UserIsSubscribed())
     paywallStatePublisher?.emit(state)
     return PaywallPresentationRequestStatusReason.UserIsSubscribed()

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/CheckDebuggerPresentation.kt

@@ -10,6 +10,12 @@ import com.superwall.sdk.paywall.presentation.internal.PresentationRequest
 import com.superwall.sdk.paywall.presentation.internal.state.PaywallState
 import kotlinx.coroutines.flow.MutableSharedFlow
 
+/**
+ * Cancels the state publisher if the debugger is already launched.
+ *
+ * @param request The presentation request.
+ * @param paywallStatePublisher A [MutableSharedFlow] that gets sent [PaywallState] objects.
+ */
 suspend fun Superwall.checkDebuggerPresentation(
     request: PresentationRequest,
     paywallStatePublisher: MutableSharedFlow<PaywallState>?,

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/CheckNoPaywallAlreadyPresented.kt

@@ -10,7 +10,7 @@ import com.superwall.sdk.paywall.presentation.internal.PresentationRequest
 import com.superwall.sdk.paywall.presentation.internal.state.PaywallState
 import kotlinx.coroutines.flow.MutableSharedFlow
 
-suspend fun Superwall.checkNoPaywallAlreadyPresented(
+internal suspend fun Superwall.checkNoPaywallAlreadyPresented(
     request: PresentationRequest,
     paywallStatePublisher: MutableSharedFlow<PaywallState>,
 ) {

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/CheckUserSubscription.kt

@@ -10,7 +10,7 @@ import com.superwall.sdk.paywall.presentation.internal.state.PaywallState
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.first
 
-suspend fun Superwall.checkUserSubscription(
+internal suspend fun Superwall.checkUserSubscription(
     request: PresentationRequest,
     triggerResult: InternalTriggerResult,
     paywallStatePublisher: MutableSharedFlow<PaywallState>? = null,

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/EvaluateRules.kt

@@ -17,6 +17,13 @@ data class AssignmentPipelineOutput(
     val debugInfo: Map<String, Any>,
 )
 
+/**
+ * Evaluates the rules from the campaign that the event belongs to.
+ *
+ * @param request The presentation request
+ * @return A [RuleEvaluationOutcome] object containing the trigger result,
+ * confirmable assignment, and unsaved occurrence.
+ */
 suspend fun Superwall.evaluateRules(request: PresentationRequest): RuleEvaluationOutcome {
     val eventData = request.presentationInfo.eventData
 

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/GetExperiment.kt

@@ -30,7 +30,7 @@ import kotlinx.coroutines.flow.MutableSharedFlow
  * @return A data class that contains info for the next operation.
  */
 @Throws(Throwable::class)
-suspend fun Superwall.getExperiment(
+internal suspend fun Superwall.getExperiment(
     request: PresentationRequest,
     rulesOutcome: RuleEvaluationOutcome,
     debugInfo: Map<String, Any>,

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/GetPresenter.kt

@@ -29,7 +29,18 @@ data class PresentablePipelineOutput(
     val confirmableAssignment: ConfirmableAssignment?,
 )
 
-suspend fun Superwall.getPresenterIfNecessary(
+/**
+ * Checks conditions for whether the paywall can present before accessing a window on
+ * which the paywall can present.
+ *
+ * @param paywallView The [PaywallView] to present.
+ * @param rulesOutcome The output from evaluating rules.
+ * @param request The presentation request.
+ * @param paywallStatePublisher A [MutableSharedFlow] that gets sent [PaywallState] objects.
+ *
+ * @return An [Activity] to present on, or null if presentation is not necessary.
+ */
+internal suspend fun Superwall.getPresenterIfNecessary(
     paywallView: PaywallView,
     rulesOutcome: RuleEvaluationOutcome,
     request: PresentationRequest,
@@ -95,7 +106,7 @@ suspend fun Superwall.getPresenterIfNecessary(
     return currentActivity
 }
 
-suspend fun Superwall.attemptTriggerFire(
+internal suspend fun Superwall.attemptTriggerFire(
     request: PresentationRequest,
     triggerResult: InternalTriggerResult,
 ) {

superwall/src/main/java/com/superwall/sdk/paywall/presentation/internal/operators/LogErrors.kt

@@ -13,7 +13,7 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
-suspend fun Superwall.logErrors(
+internal suspend fun Superwall.logErrors(
     request: PresentationRequest,
     error: Throwable,
 ) {