@wwdrew/expo-spotify-sdk 0.5.0 → 0.6.0

package/android/src/main/java/expo/modules/spotifysdk/ExpoSpotifySDKModule.kt

@@ -1,179 +1,164 @@
 package expo.modules.spotifysdk
 
 import android.content.pm.PackageManager
-import expo.modules.kotlin.Promise
-import expo.modules.kotlin.modules.Module
-import expo.modules.kotlin.modules.ModuleDefinition
-import com.spotify.sdk.android.auth.AuthorizationClient
-import com.spotify.sdk.android.auth.AuthorizationRequest
 import com.spotify.sdk.android.auth.AuthorizationResponse
-import com.spotify.sdk.android.auth.app.SpotifyNativeAuthUtil
+import expo.modules.kotlin.activityresult.AppContextActivityResultLauncher
 import expo.modules.kotlin.exception.Exceptions
-import expo.modules.kotlin.records.Field
-import expo.modules.kotlin.records.Record
+import expo.modules.kotlin.functions.Coroutine
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
 
-import okhttp3.OkHttpClient
-import okhttp3.FormBody
-import okhttp3.Request
-import okhttp3.Callback
-import okhttp3.Call
-import okhttp3.Response
+private const val SDK_VERSION = "0.5.0"
+private const val EVENT_SESSION_CHANGE = "onSessionChange"
 
-import java.io.IOException
-import org.json.JSONObject
+class ExpoSpotifySDKModule : Module() {
 
-class SpotifyConfigOptions : Record {
-  @Field
-  val scopes: List<String> = emptyList()
+  private lateinit var authLauncher: AppContextActivityResultLauncher<SpotifyAuthInput, AuthorizationResponse>
+  private val coordinator = SpotifyAuthCoordinator()
 
-  @Field
-  val tokenSwapURL: String? = null
+  private val context
+    get() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
 
-  @Field
-  val tokenRefreshURL: String? = null
-}
+  private fun readManifestConfig(): SpotifyManifestConfig {
+    val packageInfo = try {
+      context.packageManager.getPackageInfo(
+        context.packageName,
+        PackageManager.GET_META_DATA,
+      )
+    } catch (e: PackageManager.NameNotFoundException) {
+      throw InvalidConfigException("Failed to read application meta-data", e)
+    }
+    val metaData = packageInfo.applicationInfo?.metaData
+      ?: throw InvalidConfigException("Application meta-data is missing")
+    val clientId = metaData.getString("spotifyClientId")
+      ?: throw InvalidConfigException(
+        "Missing meta-data 'spotifyClientId' in AndroidManifest.xml. " +
+          "Did you add @wwdrew/expo-spotify-sdk to your Expo plugins?",
+      )
+    val redirectUri = metaData.getString("spotifyRedirectUri")
+      ?: throw InvalidConfigException(
+        "Missing meta-data 'spotifyRedirectUri' in AndroidManifest.xml.",
+      )
+    return SpotifyManifestConfig(clientId = clientId, redirectUri = redirectUri)
+  }
 
-class ExpoSpotifySDKModule : Module() {
+  private fun isSpotifyInstalled(): Boolean {
+    return try {
+      context.packageManager.getPackageInfo("com.spotify.music", 0)
+      true
+    } catch (_: PackageManager.NameNotFoundException) {
+      false
+    }
+  }
 
-  private val requestCode = 2095
-  private var requestConfig: SpotifyConfigOptions? = null
-  private var authPromise: Promise? = null
-  private val context
-    get() = appContext.reactContext ?: throw Exceptions.ReactContextLost()
-  private val currentActivity
-    get() = appContext.currentActivity ?: throw Exceptions.MissingActivity()
+  private fun emitSession(type: String, payload: SpotifySessionPayload) {
+    sendEvent(
+      EVENT_SESSION_CHANGE,
+      mapOf("type" to type, "session" to payload.toMap()),
+    )
+  }
 
-  override fun definition() = ModuleDefinition {
+  private fun emitError(type: String, code: String, message: String) {
+    sendEvent(
+      EVENT_SESSION_CHANGE,
+      mapOf("type" to type, "error" to mapOf("code" to code, "message" to message)),
+    )
+  }
 
+  override fun definition() = ModuleDefinition {
     Name("ExpoSpotifySDK")
 
+    Events(EVENT_SESSION_CHANGE)
+
     Function("isAvailable") {
-      return@Function SpotifyNativeAuthUtil.isSpotifyInstalled(context)
+      isSpotifyInstalled()
     }
 
-    AsyncFunction("authenticateAsync") { config: SpotifyConfigOptions, promise: Promise ->
-      try {
-        val packageInfo =
-          context.packageManager.getPackageInfo(context.packageName, PackageManager.GET_META_DATA)
-        val applicationInfo = packageInfo.applicationInfo
-        val metaData = applicationInfo?.metaData
-        val clientId = metaData?.getString("spotifyClientId")
-        val redirectUri = metaData?.getString("spotifyRedirectUri")
-
-        requestConfig = config
-
-        if (clientId == null || redirectUri == null) {
-          promise.reject(
-            "ERR_EXPO_SPOTIFY_SDK",
-            "Missing Spotify configuration in AndroidManifest.xml. Ensure SPOTIFY_CLIENT_ID and SPOTIFY_REDIRECT_URI are set.",
-            null
-          )
-          return@AsyncFunction
-        }
+    RegisterActivityContracts {
+      authLauncher = registerForActivityResult(SpotifyAuthorizationContract())
+    }
 
-        val responseType = if (config.tokenSwapURL != null || config.tokenRefreshURL != null) {
-          AuthorizationResponse.Type.CODE
-        } else {
-          AuthorizationResponse.Type.TOKEN
+    AsyncFunction("authenticateAsync") Coroutine { config: SpotifyAuthenticateOptions ->
+      try {
+        if (config.scopes.isEmpty()) {
+          throw InvalidConfigException("`scopes` must contain at least one entry")
         }
+        val manifest = readManifestConfig()
 
-        val request = AuthorizationRequest.Builder(
-          clientId,
-          responseType,
-          redirectUri
-        )
-          .setScopes(config.scopes.toTypedArray())
-          .build()
-
-        authPromise = promise
-        AuthorizationClient.openLoginActivity(currentActivity, requestCode, request)
+        val responseType =
+          if (config.tokenSwapURL != null) AuthorizationResponse.Type.CODE
+          else AuthorizationResponse.Type.TOKEN
 
-      } catch (e: PackageManager.NameNotFoundException) {
-        promise.reject(
-          "ERR_EXPO_SPOTIFY_SDK",
-          "Missing Spotify configuration in AndroidManifest.xml",
-          e
+        val input = SpotifyAuthInput(
+          clientId = manifest.clientId,
+          redirectUri = manifest.redirectUri,
+          responseType = responseType,
+          scopes = config.scopes.toTypedArray(),
         )
-      }
-    }
-
-    OnActivityResult { _, payload ->
-      if (payload.requestCode == requestCode) {
-        val authResponse = AuthorizationClient.getResponse(payload.resultCode, payload.data)
 
-        when (authResponse.type) {
-          AuthorizationResponse.Type.TOKEN -> {
-            val expirationDate = System.currentTimeMillis() + authResponse.expiresIn * 1000
+        val response = coordinator.authenticate(authLauncher, input)
 
-            authPromise?.resolve(
-              mapOf(
-                "accessToken" to authResponse.accessToken,
-                "refreshToken" to null, // Spotify SDK does not return refresh token
-                "expirationDate" to expirationDate,
-                "scope" to requestConfig?.scopes
+        val payload = when (response.type) {
+          AuthorizationResponse.Type.TOKEN -> SpotifySessionPayload(
+            accessToken = response.accessToken
+              ?: throw TokenSwapParseException("Spotify returned TOKEN without an access token"),
+            refreshToken = null,
+            expirationDate = System.currentTimeMillis() + response.expiresIn * 1000L,
+            scopes = config.scopes,
+          )
+          AuthorizationResponse.Type.CODE -> {
+            val swapURL = config.tokenSwapURL
+              ?: throw InvalidConfigException(
+                "Received CODE response but no tokenSwapURL was configured",
               )
+            val client = SpotifyTokenSwapClient(SDK_VERSION, manifest.clientId)
+            client.swap(
+              code = response.code
+                ?: throw TokenSwapParseException("Spotify returned CODE without a code"),
+              redirectUri = manifest.redirectUri,
+              tokenSwapURL = swapURL,
+              requestedScopes = config.scopes,
             )
           }
+          AuthorizationResponse.Type.CANCELLED -> throw UserCancelledException()
+          AuthorizationResponse.Type.EMPTY -> throw UnknownSpotifyException(
+            "Spotify returned an empty response (auth activity may have been killed)",
+          )
+          AuthorizationResponse.Type.ERROR -> throw SpotifyAuthErrorException(
+            response.error ?: "Spotify returned an unspecified error",
+          )
+          AuthorizationResponse.Type.UNKNOWN, null -> throw UnknownSpotifyException(
+            "Unknown Spotify authorization response type",
+          )
+        }
+        emitSession("didInitiate", payload)
+        payload.toMap()
+      } catch (e: expo.modules.kotlin.exception.CodedException) {
+        emitError("didFail", e.code ?: "UNKNOWN", e.localizedMessage ?: e.code ?: "Unknown error")
+        throw e
+      }
+    }
 
-          AuthorizationResponse.Type.CODE -> {
-            val client = OkHttpClient()
-            val requestBody = FormBody.Builder()
-              .add("code", authResponse.code)
-              .build()
-
-            val request = Request.Builder()
-              .url(requestConfig?.tokenSwapURL!!)
-              .post(requestBody)
-              .header("Content-Type", "application/x-www-form-urlencoded")
-              .build()
-
-            client.newCall(request).enqueue(object : Callback {
-              override fun onFailure(call: Call, e: IOException) {
-                authPromise?.reject("ERR_EXPO_SPOTIFY_SDK", e.message, e)
-                authPromise = null
-              }
-
-              override fun onResponse(call: Call, response: Response) {
-                if (!response.isSuccessful) {
-                  authPromise?.reject("ERR_EXPO_SPOTIFY_SDK", "Failed to swap code for token", null)
-                  authPromise = null
-                  return
-                }
-
-                response.body?.string()?.let { body ->
-                  val json = JSONObject(body)
-                  val accessToken = json.getString("access_token")
-                  val refreshToken = json.getString("refresh_token")
-                  val expiresIn = json.getInt("expires_in")
-                  val scope = json.getString("scope")
-                  val expirationDate = System.currentTimeMillis() + expiresIn * 1000
-
-                  authPromise?.resolve(
-                    mapOf(
-                      "accessToken" to accessToken,
-                      "refreshToken" to refreshToken,
-                      "expirationDate" to expirationDate,
-                      "scope" to scope.split(' ')
-                    )
-                  )
-                } ?: run {
-                  authPromise?.reject("ERR_EXPO_SPOTIFY_SDK", "Empty response body", null)
-                }
-                authPromise = null
-              }
-            })
-          }
-
-          AuthorizationResponse.Type.ERROR -> {
-            authPromise?.reject("ERR_EXPO_SPOTIFY_SDK", authResponse.error, null)
-            authPromise = null
-          }
-
-          else -> {
-            authPromise?.reject("ERR_EXPO_SPOTIFY_SDK", "Unknown response type", null)
-            authPromise = null
-          }
+    AsyncFunction("refreshSessionAsync") Coroutine { options: SpotifyRefreshOptions ->
+      try {
+        if (options.refreshToken.isBlank()) {
+          throw InvalidConfigException("`refreshToken` is required")
         }
+        if (options.tokenRefreshURL.isBlank()) {
+          throw InvalidConfigException("`tokenRefreshURL` is required")
+        }
+        val manifest = readManifestConfig()
+        val client = SpotifyTokenSwapClient(SDK_VERSION, manifest.clientId)
+        val payload = client.refresh(
+          refreshToken = options.refreshToken,
+          tokenRefreshURL = options.tokenRefreshURL,
+          previousScopes = emptyList(),
+        )
+        emitSession("didRenew", payload)
+        payload.toMap()
+      } catch (e: expo.modules.kotlin.exception.CodedException) {
+        emitError("didFail", e.code ?: "UNKNOWN", e.localizedMessage ?: e.code ?: "Unknown error")
+        throw e
       }
     }
   }

package/android/src/main/java/expo/modules/spotifysdk/SpotifyAuthCoordinator.kt

@@ -0,0 +1,36 @@
+package expo.modules.spotifysdk
+
+import com.spotify.sdk.android.auth.AuthorizationResponse
+import expo.modules.kotlin.activityresult.AppContextActivityResultLauncher
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+
+/**
+ * Guards against concurrent Spotify auth calls.
+ *
+ * `AppContextActivityResultLauncher.launch(input)` is already a `suspend`
+ * function that bridges the activity-result callback into a coroutine, so we
+ * no longer need `suspendCancellableCoroutine` here. The only responsibility
+ * of this class is to enforce the single-in-flight constraint via `Mutex`.
+ */
+class SpotifyAuthCoordinator {
+  private val mutex = Mutex()
+
+  /**
+   * Launches the Spotify auth flow and suspends until the activity returns a
+   * result. Re-entry while a call is in flight rejects with [AuthInProgressException].
+   */
+  suspend fun authenticate(
+    launcher: AppContextActivityResultLauncher<SpotifyAuthInput, AuthorizationResponse>,
+    input: SpotifyAuthInput,
+  ): AuthorizationResponse {
+    if (!mutex.tryLock()) {
+      throw AuthInProgressException()
+    }
+    return try {
+      launcher.launch(input)
+    } finally {
+      mutex.unlock()
+    }
+  }
+}

package/android/src/main/java/expo/modules/spotifysdk/SpotifyAuthorizationContract.kt

@@ -0,0 +1,45 @@
+package expo.modules.spotifysdk
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import com.spotify.sdk.android.auth.AuthorizationClient
+import com.spotify.sdk.android.auth.AuthorizationRequest
+import com.spotify.sdk.android.auth.AuthorizationResponse
+import expo.modules.kotlin.activityresult.AppContextActivityResultContract
+
+/**
+ * Expo-compatible wrapper around Spotify's auth flow.
+ *
+ * `AppContextActivityResultContract<I, O>` is the Expo Modules Core version of
+ * AndroidX's `ActivityResultContract`. The key difference is that:
+ *  - `I` must implement `Serializable` (for state preservation across process death)
+ *  - `parseResult` receives the original `input` as its first argument
+ *
+ * We use `SpotifyAuthInput` as our serializable input type to work around
+ * `AuthorizationRequest` only implementing `Parcelable`.
+ */
+class SpotifyAuthorizationContract :
+  AppContextActivityResultContract<SpotifyAuthInput, AuthorizationResponse> {
+
+  override fun createIntent(context: Context, input: SpotifyAuthInput): Intent {
+    val activity = context as? Activity
+      ?: throw IllegalStateException(
+        "SpotifyAuthorizationContract requires an Activity context, got ${context.javaClass.name}"
+      )
+    val request = AuthorizationRequest.Builder(
+      input.clientId,
+      input.responseType,
+      input.redirectUri,
+    )
+      .setScopes(input.scopes)
+      .build()
+    return AuthorizationClient.createLoginActivityIntent(activity, request)
+  }
+
+  override fun parseResult(
+    input: SpotifyAuthInput,
+    resultCode: Int,
+    intent: Intent?,
+  ): AuthorizationResponse = AuthorizationClient.getResponse(resultCode, intent)
+}

package/android/src/main/java/expo/modules/spotifysdk/SpotifyConfig.kt

@@ -0,0 +1,80 @@
+package expo.modules.spotifysdk
+
+import com.spotify.sdk.android.auth.AuthorizationResponse
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+import java.io.Serializable
+
+/**
+ * JS-facing input for `authenticateAsync`.
+ */
+class SpotifyAuthenticateOptions : Record {
+  @Field val scopes: List<String> = emptyList()
+  @Field val tokenSwapURL: String? = null
+  @Field val tokenRefreshURL: String? = null
+}
+
+/**
+ * JS-facing input for `refreshSessionAsync`. Phase 1 ships the Kotlin support;
+ * the public JS function is added in Phase 3.
+ */
+class SpotifyRefreshOptions : Record {
+  @Field val refreshToken: String = ""
+  @Field val tokenRefreshURL: String = ""
+}
+
+/**
+ * Result shape returned to JS. Mirrors `SpotifySession` in the TypeScript layer.
+ */
+data class SpotifySessionPayload(
+  val accessToken: String,
+  val refreshToken: String?,
+  val expirationDate: Long,
+  val scopes: List<String>,
+) {
+  fun toMap(): Map<String, Any?> = mapOf(
+    "accessToken" to accessToken,
+    "refreshToken" to refreshToken,
+    "expirationDate" to expirationDate,
+    "scopes" to scopes,
+  )
+}
+
+/**
+ * Native config read from `AndroidManifest.xml` meta-data placeholders set
+ * by the Expo config plugin.
+ */
+data class SpotifyManifestConfig(
+  val clientId: String,
+  val redirectUri: String,
+)
+
+/**
+ * Serializable input for the `AppContextActivityResultContract`. We need our
+ * own class because `AuthorizationRequest` is only `Parcelable`, not
+ * `Serializable`, and Expo's `AppContextActivityResultContract<I, O>` requires
+ * `I : Serializable`.
+ */
+data class SpotifyAuthInput(
+  val clientId: String,
+  val redirectUri: String,
+  val responseType: AuthorizationResponse.Type,
+  val scopes: Array<String>,
+) : Serializable {
+  override fun equals(other: Any?): Boolean {
+    if (this === other) return true
+    if (other !is SpotifyAuthInput) return false
+    return clientId == other.clientId &&
+      redirectUri == other.redirectUri &&
+      responseType == other.responseType &&
+      scopes.contentEquals(other.scopes)
+  }
+
+  override fun hashCode(): Int {
+    var result = clientId.hashCode()
+    result = 31 * result + redirectUri.hashCode()
+    result = 31 * result + responseType.hashCode()
+    result = 31 * result + scopes.contentHashCode()
+    return result
+  }
+}

package/android/src/main/java/expo/modules/spotifysdk/SpotifyErrors.kt

@@ -0,0 +1,34 @@
+package expo.modules.spotifysdk
+
+import expo.modules.kotlin.exception.CodedException
+
+class UserCancelledException(message: String = "Authentication was cancelled by the user") :
+  CodedException("USER_CANCELLED", message, null)
+
+class AuthInProgressException(message: String = "Another authentication request is already in progress") :
+  CodedException("AUTH_IN_PROGRESS", message, null)
+
+class InvalidConfigException(message: String, cause: Throwable? = null) :
+  CodedException("INVALID_CONFIG", message, cause)
+
+class NetworkException(message: String, cause: Throwable? = null) :
+  CodedException("NETWORK_ERROR", message, cause)
+
+class TokenSwapFailedException(status: Int, body: String?) :
+  CodedException(
+    "TOKEN_SWAP_FAILED",
+    "Token swap server returned HTTP $status${if (!body.isNullOrBlank()) ": ${body.take(512)}" else ""}",
+    null,
+  )
+
+class TokenSwapParseException(message: String, cause: Throwable? = null) :
+  CodedException("TOKEN_SWAP_PARSE_ERROR", message, cause)
+
+class SpotifyNotInstalledException(message: String = "The Spotify app is not installed on this device") :
+  CodedException("SPOTIFY_NOT_INSTALLED", message, null)
+
+class SpotifyAuthErrorException(error: String) :
+  CodedException("AUTH_ERROR", error, null)
+
+class UnknownSpotifyException(message: String, cause: Throwable? = null) :
+  CodedException("UNKNOWN", message, cause)

package/android/src/main/java/expo/modules/spotifysdk/SpotifyTokenSwapClient.kt

@@ -0,0 +1,154 @@
+package expo.modules.spotifysdk
+
+import kotlinx.coroutines.suspendCancellableCoroutine
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.FormBody
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import org.json.JSONException
+import org.json.JSONObject
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/**
+ * Performs the OAuth Authorization Code -> token swap and the refresh-token
+ * exchange against a user-provided server.
+ *
+ * Server contract:
+ *   POST {tokenSwapURL}
+ *     body: code=<auth-code>&redirect_uri=<redirect-uri>&client_id=<client-id>
+ *     200 -> { access_token, expires_in, refresh_token?, scope? }
+ *
+ *   POST {tokenRefreshURL}
+ *     body: refresh_token=<token>&client_id=<client-id>
+ *     200 -> { access_token, expires_in, refresh_token?, scope? }
+ */
+class SpotifyTokenSwapClient(
+  private val sdkVersion: String,
+  private val clientId: String,
+) {
+  private val client: OkHttpClient = OkHttpClient.Builder()
+    .connectTimeout(30, TimeUnit.SECONDS)
+    .readTimeout(30, TimeUnit.SECONDS)
+    .writeTimeout(30, TimeUnit.SECONDS)
+    .build()
+
+  private val userAgent: String = "expo-spotify-sdk/$sdkVersion"
+
+  suspend fun swap(
+    code: String,
+    redirectUri: String,
+    tokenSwapURL: String,
+    requestedScopes: List<String>,
+  ): SpotifySessionPayload {
+    val body = FormBody.Builder()
+      .add("code", code)
+      .add("redirect_uri", redirectUri)
+      .add("client_id", clientId)
+      .build()
+    val request = Request.Builder()
+      .url(tokenSwapURL)
+      .header("User-Agent", userAgent)
+      .post(body)
+      .build()
+    val json = executeJson(request)
+    return parseSessionPayload(json, fallbackScopes = requestedScopes, fallbackRefreshToken = null)
+  }
+
+  suspend fun refresh(
+    refreshToken: String,
+    tokenRefreshURL: String,
+    previousScopes: List<String>,
+  ): SpotifySessionPayload {
+    val body = FormBody.Builder()
+      .add("refresh_token", refreshToken)
+      .add("client_id", clientId)
+      .build()
+    val request = Request.Builder()
+      .url(tokenRefreshURL)
+      .header("User-Agent", userAgent)
+      .post(body)
+      .build()
+    val json = executeJson(request)
+    return parseSessionPayload(
+      json,
+      fallbackScopes = previousScopes,
+      fallbackRefreshToken = refreshToken,
+    )
+  }
+
+  private suspend fun executeJson(request: Request): JSONObject {
+    val response = try {
+      client.executeAsync(request)
+    } catch (e: IOException) {
+      throw NetworkException("Network failure contacting ${request.url}", e)
+    }
+    response.use { res ->
+      val raw = res.body?.string()
+      if (!res.isSuccessful) {
+        throw TokenSwapFailedException(res.code, raw)
+      }
+      if (raw.isNullOrBlank()) {
+        throw TokenSwapParseException("Empty response body from ${request.url}")
+      }
+      return try {
+        JSONObject(raw)
+      } catch (e: JSONException) {
+        throw TokenSwapParseException("Response was not valid JSON: ${raw.take(256)}", e)
+      }
+    }
+  }
+
+  private fun parseSessionPayload(
+    json: JSONObject,
+    fallbackScopes: List<String>,
+    fallbackRefreshToken: String?,
+  ): SpotifySessionPayload {
+    val accessToken = json.optString("access_token").takeIf { it.isNotEmpty() }
+      ?: throw TokenSwapParseException("Response missing required field: access_token")
+    val expiresIn = json.optInt("expires_in", -1)
+    if (expiresIn < 0) {
+      throw TokenSwapParseException("Response missing required field: expires_in")
+    }
+    val refreshToken = json.optString("refresh_token").takeIf { it.isNotEmpty() }
+      ?: fallbackRefreshToken
+    val scopes = json.optString("scope").takeIf { it.isNotEmpty() }
+      ?.split(' ')
+      ?.filter { it.isNotEmpty() }
+      ?: fallbackScopes
+    val expirationDate = System.currentTimeMillis() + expiresIn * 1000L
+    return SpotifySessionPayload(
+      accessToken = accessToken,
+      refreshToken = refreshToken,
+      expirationDate = expirationDate,
+      scopes = scopes,
+    )
+  }
+}
+
+/**
+ * Suspend wrapper around `OkHttpClient.newCall(...).enqueue(...)`. Cancellation
+ * of the surrounding coroutine cancels the in-flight call.
+ */
+internal suspend fun OkHttpClient.executeAsync(request: Request): Response =
+  suspendCancellableCoroutine { cont ->
+    val call = newCall(request)
+    cont.invokeOnCancellation {
+      try {
+        call.cancel()
+      } catch (_: Throwable) { /* best-effort */ }
+    }
+    call.enqueue(object : Callback {
+      override fun onFailure(call: Call, e: IOException) {
+        if (cont.isActive) cont.resumeWithException(e)
+      }
+
+      override fun onResponse(call: Call, response: Response) {
+        if (cont.isActive) cont.resume(response)
+      }
+    })
+  }