@wwdrew/expo-spotify-sdk 0.7.0 → 0.8.0

package/README.md

@@ -15,6 +15,7 @@ An Expo module that wraps the native [Spotify iOS SDK](https://github.com/spotif
 | `isAvailable()`                               | ✅  | ✅           | ✅ (always `false`) |
 | `authenticateAsync` — CODE flow (recommended) | ✅  | ✅           | —                   |
 | `authenticateAsync` — TOKEN flow (implicit)   | ✅  | ⚠️ see below | —                   |
+| `cancelPendingAuthAsync()`                    | ✅  | no-op        | no-op               |
 | `refreshSessionAsync`                         | ✅  | ✅           | —                   |
 | Auth via installed Spotify app                | ✅  | ✅           | —                   |
 | Auth via Spotify web fallback                 | ✅  | ✅           | —                   |
@@ -80,7 +81,7 @@ android {
             spotifyRedirectUri:    "myapp://spotify-auth",
             redirectSchemeName:    "myapp",
             redirectHostName:      "spotify-auth",
-            redirectPathPattern:   "/.*"
+            redirectPathPattern:   ".*"
         ]
     }
 }
@@ -107,16 +108,23 @@ export default {
         clientID: "your-spotify-client-id",
         scheme: "myapp",
         host: "spotify-auth",
-        // Optional: path pattern accepted by the Spotify Android SDK redirect.
-        // Defaults to "/.*" (matches any path). Change this only if you have a
-        // specific redirect path registered in your Spotify app settings.
-        redirectPathPattern: "/.*",
       },
     ],
   ],
 };
 ```
 
+`redirectPathPattern` is optional and defaults to `".*"`, which matches every redirect URI shape Spotify will hand back. Only set it if you have a specific path registered in your Spotify app settings:
+
+```ts
+{
+  clientID: "your-spotify-client-id",
+  scheme: "myapp",
+  host: "spotify-auth",
+  redirectPathPattern: "/auth/.*",
+}
+```
+
 ### Plugin options
 
 | Option                | Type     | Required | Description                                                |
@@ -124,7 +132,7 @@ export default {
 | `clientID`            | `string` | ✅       | Your Spotify application's Client ID                       |
 | `scheme`              | `string` | ✅       | URL scheme registered for your app (e.g. `"myapp"`)        |
 | `host`                | `string` | ✅       | Host component of the redirect URI (e.g. `"spotify-auth"`) |
-| `redirectPathPattern` | `string` | —        | Android redirect path regex. Defaults to `"/.*"`           |
+| `redirectPathPattern` | `string` | —        | Android redirect path regex. Defaults to `".*"`            |
 
 The redirect URI registered in your [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) must match `{scheme}://{host}` exactly (e.g. `myapp://spotify-auth`).
 
@@ -207,19 +215,56 @@ Starts a Spotify OAuth flow. If the Spotify app is installed it authenticates na
 
 ---
 
+### `cancelPendingAuthAsync(): Promise<void>`
+
+Forcibly cancels any in-flight `authenticateAsync` call. Resolves once the native coordinator's pending state is cleared. No-op when nothing is in flight.
+
+**Why this exists:** the iOS `SPTSessionManager` delegate callbacks (`didInitiate` / `didFailWith`) are not guaranteed to fire — for example when Spotify never redirects back to the host app, or the host process is backgrounded mid-flow. When that happens the coordinator's pending continuation leaks and every subsequent `authenticateAsync` rejects immediately with `AUTH_IN_PROGRESS` until the process restarts.
+
+**When to call it:** defensively, before each `authenticateAsync`, so retries always start from a clean slate. The cost is one cheap async hop when nothing is leaked.
+
+```ts
+import {
+  authenticateAsync,
+  cancelPendingAuthAsync,
+} from "@wwdrew/expo-spotify-sdk";
+
+async function login() {
+  await cancelPendingAuthAsync();
+  return authenticateAsync({ scopes: ["user-read-email", "streaming"] });
+}
+```
+
+If a pending call is cancelled this way, its original `authenticateAsync` promise rejects with `SpotifyError` `code: "USER_CANCELLED"`.
+
+**Platform notes:** no-op on Android (the Kotlin coordinator self-cleans via structured concurrency) and on web. Safe to call unconditionally.
+
+---
+
 ### `refreshSessionAsync(options): Promise<SpotifySession>`
 
 Exchanges a refresh token for a new access token via your token refresh server.
 
 **Parameters:**
 
-| Field             | Type     | Description                                                 |
-| ----------------- | -------- | ----------------------------------------------------------- |
-| `refreshToken`    | `string` | The refresh token from a previous `authenticateAsync` call. |
-| `tokenRefreshURL` | `string` | URL of your token refresh server endpoint.                  |
+| Field             | Type             | Required | Description                                                                                                                                                                              |
+| ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `refreshToken`    | `string`         | ✅       | The refresh token from a previous `authenticateAsync` call.                                                                                                                              |
+| `tokenRefreshURL` | `string`         | ✅       | URL of your token refresh server endpoint.                                                                                                                                               |
+| `scopes`          | `SpotifyScope[]` | —        | Previously-granted scopes. Used as a fallback when the refresh response omits the `scope` field. **Pass through the previous session's `scopes`** to avoid silently losing scope info.   |
 
 **Returns** a fresh `SpotifySession` with an updated `accessToken` and `expirationDate`. If the server rotates the refresh token the new one is returned in `refreshToken`; otherwise the original token is returned so you can continue refreshing.
 
+**Why pass `scopes`:** Spotify's refresh endpoint only returns `scope` when the granted scope set has changed since the last issuance — most refresh responses omit it. Without `scopes` plumbed through, the returned session's `scopes` will be `[]` on every refresh that doesn't include the field, even though the access token itself still carries the same scopes.
+
+```ts
+const refreshed = await refreshSessionAsync({
+  refreshToken: previous.refreshToken,
+  tokenRefreshURL: "https://your-server.example.com/refresh",
+  scopes: previous.scopes,
+});
+```
+
 ---
 
 ### `addSessionChangeListener(listener): Subscription`
@@ -270,7 +315,7 @@ try {
   if (e instanceof SpotifyError) {
     switch (e.code) {
       case "USER_CANCELLED": // user closed the auth screen — benign
-      case "AUTH_IN_PROGRESS": // concurrent call — benign
+      case "AUTH_IN_PROGRESS": // concurrent call, or iOS stuck state — see cancelPendingAuthAsync
         return;
       case "INVALID_CONFIG": // missing clientID / scopes / tokenSwapURL
       case "NETWORK_ERROR": // connectivity failure during token swap
@@ -389,7 +434,9 @@ Android 11+ requires a `<queries>` element to inspect other apps' package names.
 Ensure your app's URL scheme is registered in Xcode under **Info → URL Types** and that it matches the `scheme` in the plugin config. The `expo prebuild` step does this automatically; if you have a bare workflow, check `CFBundleURLSchemes` in `Info.plist`.
 
 **`AUTH_IN_PROGRESS`**
-`authenticateAsync` was called while a previous call was still pending. Wait for the first call to resolve or reject before calling again.
+`authenticateAsync` was called while a previous call was still pending. Usually this means a concurrent call — wait for the first one to resolve.
+
+On iOS this can also be a stuck state: the SPTSessionManager delegate callbacks aren't guaranteed to fire (e.g. Spotify never redirected back to the app), so the previous call's continuation leaks and every retry rejects immediately. Call [`cancelPendingAuthAsync()`](#cancelpendingauthasync-promisevoid) before retrying — or, defensively, before every `authenticateAsync`.
 
 ## Acknowledgements
 

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

@@ -8,7 +8,7 @@ import expo.modules.kotlin.functions.Coroutine
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 
-private const val SDK_VERSION = "0.5.0"
+private const val SDK_VERSION = "0.8.0" // x-release-please-version
 private const val EVENT_SESSION_CHANGE = "onSessionChange"
 
 class ExpoSpotifySDKModule : Module() {
@@ -122,8 +122,8 @@ class ExpoSpotifySDKModule : Module() {
             )
           }
           AuthorizationResponse.Type.CANCELLED -> throw UserCancelledException()
-          AuthorizationResponse.Type.EMPTY -> throw UnknownSpotifyException(
-            "Spotify returned an empty response (auth activity may have been killed)",
+          AuthorizationResponse.Type.EMPTY -> throw UserCancelledException(
+            "Spotify returned an empty response (auth activity dismissed before completion)",
           )
           AuthorizationResponse.Type.ERROR -> throw SpotifyAuthErrorException(
             response.error ?: "Spotify returned an unspecified error",
@@ -153,7 +153,7 @@ class ExpoSpotifySDKModule : Module() {
         val payload = client.refresh(
           refreshToken = options.refreshToken,
           tokenRefreshURL = options.tokenRefreshURL,
-          previousScopes = emptyList(),
+          previousScopes = options.scopes,
         )
         emitSession("didRenew", payload)
         payload.toMap()

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

@@ -22,6 +22,7 @@ class SpotifyAuthenticateOptions : Record {
 class SpotifyRefreshOptions : Record {
   @Field val refreshToken: String = ""
   @Field val tokenRefreshURL: String = ""
+  @Field val scopes: List<String> = emptyList()
 }
 
 /**

package/build/ExpoSpotifySDK.types.d.ts

@@ -28,6 +28,18 @@ export interface SpotifyRefreshConfig {
     refreshToken: string;
     /** URL of your token refresh server endpoint. */
     tokenRefreshURL: string;
+    /**
+     * Scopes that were granted by the previous session. Used as a fallback
+     * when the refresh response omits the `scope` field (which most
+     * `accounts.spotify.com` refresh responses do — Spotify only returns
+     * `scope` when the granted scope set has changed).
+     *
+     * If omitted, the returned `SpotifySession.scopes` will be `[]` whenever
+     * the refresh response also omits `scope` — silently losing scope
+     * information you held a moment ago. Pass through the previous session's
+     * `scopes` to avoid that.
+     */
+    scopes?: SpotifyScope[];
 }
 /**
  * Configuration accepted by `authenticateAsync`.

package/build/ExpoSpotifySDK.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoSpotifySDK.types.d.ts","sourceRoot":"","sources":["../src/ExpoSpotifySDK.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,0BAA0B,GAC1B,4BAA4B,GAC5B,6BAA6B,GAC7B,oBAAoB,GACpB,WAAW,GACX,uBAAuB,GACvB,6BAA6B,GAC7B,yBAAyB,GACzB,wBAAwB,GACxB,oBAAoB,GACpB,kBAAkB,GAClB,eAAe,GACf,2BAA2B,GAC3B,qBAAqB,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,wBAAwB,GACxB,uBAAuB,GACvB,YAAY,GACZ,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE5E;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,IAAI,EAAE,gBAAgB,CAAC;gBAE3B,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM;CAKpD"}
+{"version":3,"file":"ExpoSpotifySDK.types.d.ts","sourceRoot":"","sources":["../src/ExpoSpotifySDK.types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,0BAA0B,GAC1B,4BAA4B,GAC5B,6BAA6B,GAC7B,oBAAoB,GACpB,WAAW,GACX,uBAAuB,GACvB,6BAA6B,GAC7B,yBAAyB,GACzB,wBAAwB,GACxB,oBAAoB,GACpB,kBAAkB,GAClB,eAAe,GACf,2BAA2B,GAC3B,qBAAqB,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,wBAAwB,GACxB,uBAAuB,GACvB,YAAY,GACZ,SAAS,CAAC;AAEd;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAE5E;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,IAAI,EAAE,gBAAgB,CAAC;gBAE3B,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM;CAKpD"}

package/build/ExpoSpotifySDK.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoSpotifySDK.types.js","sourceRoot":"","sources":["../src/ExpoSpotifySDK.types.ts"],"names":[],"mappings":"AA+GA;;;GAGG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrB,IAAI,CAAmB;IAEvC,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["/**\n * Result of a successful Spotify authentication.\n *\n * The shape is identical across iOS and Android. On the Android implicit\n * (TOKEN) flow `refreshToken` is `null` and `scopes` reflects what was\n * *requested*, not granted — see the README's \"Android implicit flow is not\n * recommended\" section.\n */\nexport interface SpotifySession {\n  /** OAuth access token. */\n  accessToken: string;\n  /**\n   * OAuth refresh token. `null` on Android when no `tokenSwapURL` is provided\n   * (the Spotify Android SDK does not expose a refresh token for implicit\n   * grants — see the README).\n   */\n  refreshToken: string | null;\n  /** Expiration timestamp as Unix epoch milliseconds. */\n  expirationDate: number;\n  /** Scopes the access token was granted (or requested, on Android implicit). */\n  scopes: SpotifyScope[];\n}\n\n/**\n * Configuration accepted by `refreshSessionAsync`.\n */\nexport interface SpotifyRefreshConfig {\n  /** The refresh token from a previous `authenticateAsync` call. */\n  refreshToken: string;\n  /** URL of your token refresh server endpoint. */\n  tokenRefreshURL: string;\n}\n\n/**\n * Configuration accepted by `authenticateAsync`.\n */\nexport interface SpotifyConfig {\n  /** OAuth scopes to request. Must contain at least one entry. */\n  scopes: SpotifyScope[];\n  /**\n   * If supplied, requests an authorization code rather than an implicit\n   * token, then POSTs the code to this URL to exchange it for tokens.\n   * **Required on Android** to receive a usable `refreshToken`.\n   */\n  tokenSwapURL?: string;\n  /**\n   * Used by the iOS SDK to refresh access tokens automatically, and by\n   * `refreshSessionAsync` on both platforms.\n   */\n  tokenRefreshURL?: string;\n  /**\n   * If `true`, forces Spotify to show the authorization dialog even when\n   * the user already has an active session. Defaults to `false`.\n   *\n   * Maps to `SPTSessionManager.alwaysShowAuthorizationDialog` on iOS and\n   * `AuthorizationRequest.Builder.setShowDialog(true)` on Android.\n   */\n  showDialog?: boolean;\n}\n\n/**\n * Spotify OAuth scope identifiers that are valid through the iOS, Android\n * and Web auth flows. See https://developer.spotify.com/documentation/web-api/concepts/scopes\n */\nexport type SpotifyScope =\n  | \"ugc-image-upload\"\n  | \"user-read-playback-state\"\n  | \"user-modify-playback-state\"\n  | \"user-read-currently-playing\"\n  | \"app-remote-control\"\n  | \"streaming\"\n  | \"playlist-read-private\"\n  | \"playlist-read-collaborative\"\n  | \"playlist-modify-private\"\n  | \"playlist-modify-public\"\n  | \"user-follow-modify\"\n  | \"user-follow-read\"\n  | \"user-top-read\"\n  | \"user-read-recently-played\"\n  | \"user-library-modify\"\n  | \"user-library-read\"\n  | \"user-read-email\"\n  | \"user-read-private\";\n\n/**\n * JS-side error code constants thrown via `Promise.reject(new Error(...))`\n * by the native modules.\n */\nexport type SpotifyErrorCode =\n  | \"USER_CANCELLED\"\n  | \"AUTH_IN_PROGRESS\"\n  | \"INVALID_CONFIG\"\n  | \"NETWORK_ERROR\"\n  | \"TOKEN_SWAP_FAILED\"\n  | \"TOKEN_SWAP_PARSE_ERROR\"\n  | \"SPOTIFY_NOT_INSTALLED\"\n  | \"AUTH_ERROR\"\n  | \"UNKNOWN\";\n\n/**\n * Payload delivered to `addSessionChangeListener` subscribers.\n *\n * - `didInitiate` — a new session was created by `authenticateAsync`\n * - `didRenew`    — an existing session was refreshed by `refreshSessionAsync`\n * - `didFail`     — an auth or refresh attempt failed\n */\nexport type SpotifySessionChangeEvent =\n  | { type: \"didInitiate\"; session: SpotifySession }\n  | { type: \"didRenew\"; session: SpotifySession }\n  | { type: \"didFail\"; error: { code: SpotifyErrorCode; message: string } };\n\n/**\n * Error subclass thrown by `authenticateAsync` and `refreshSessionAsync`\n * carrying a structured `code` field for branching.\n */\nexport class SpotifyError extends Error {\n  public readonly code: SpotifyErrorCode;\n\n  constructor(code: SpotifyErrorCode, message: string) {\n    super(message);\n    this.name = \"SpotifyError\";\n    this.code = code;\n  }\n}\n"]}
+{"version":3,"file":"ExpoSpotifySDK.types.js","sourceRoot":"","sources":["../src/ExpoSpotifySDK.types.ts"],"names":[],"mappings":"AA2HA;;;GAGG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrB,IAAI,CAAmB;IAEvC,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["/**\n * Result of a successful Spotify authentication.\n *\n * The shape is identical across iOS and Android. On the Android implicit\n * (TOKEN) flow `refreshToken` is `null` and `scopes` reflects what was\n * *requested*, not granted — see the README's \"Android implicit flow is not\n * recommended\" section.\n */\nexport interface SpotifySession {\n  /** OAuth access token. */\n  accessToken: string;\n  /**\n   * OAuth refresh token. `null` on Android when no `tokenSwapURL` is provided\n   * (the Spotify Android SDK does not expose a refresh token for implicit\n   * grants — see the README).\n   */\n  refreshToken: string | null;\n  /** Expiration timestamp as Unix epoch milliseconds. */\n  expirationDate: number;\n  /** Scopes the access token was granted (or requested, on Android implicit). */\n  scopes: SpotifyScope[];\n}\n\n/**\n * Configuration accepted by `refreshSessionAsync`.\n */\nexport interface SpotifyRefreshConfig {\n  /** The refresh token from a previous `authenticateAsync` call. */\n  refreshToken: string;\n  /** URL of your token refresh server endpoint. */\n  tokenRefreshURL: string;\n  /**\n   * Scopes that were granted by the previous session. Used as a fallback\n   * when the refresh response omits the `scope` field (which most\n   * `accounts.spotify.com` refresh responses do — Spotify only returns\n   * `scope` when the granted scope set has changed).\n   *\n   * If omitted, the returned `SpotifySession.scopes` will be `[]` whenever\n   * the refresh response also omits `scope` — silently losing scope\n   * information you held a moment ago. Pass through the previous session's\n   * `scopes` to avoid that.\n   */\n  scopes?: SpotifyScope[];\n}\n\n/**\n * Configuration accepted by `authenticateAsync`.\n */\nexport interface SpotifyConfig {\n  /** OAuth scopes to request. Must contain at least one entry. */\n  scopes: SpotifyScope[];\n  /**\n   * If supplied, requests an authorization code rather than an implicit\n   * token, then POSTs the code to this URL to exchange it for tokens.\n   * **Required on Android** to receive a usable `refreshToken`.\n   */\n  tokenSwapURL?: string;\n  /**\n   * Used by the iOS SDK to refresh access tokens automatically, and by\n   * `refreshSessionAsync` on both platforms.\n   */\n  tokenRefreshURL?: string;\n  /**\n   * If `true`, forces Spotify to show the authorization dialog even when\n   * the user already has an active session. Defaults to `false`.\n   *\n   * Maps to `SPTSessionManager.alwaysShowAuthorizationDialog` on iOS and\n   * `AuthorizationRequest.Builder.setShowDialog(true)` on Android.\n   */\n  showDialog?: boolean;\n}\n\n/**\n * Spotify OAuth scope identifiers that are valid through the iOS, Android\n * and Web auth flows. See https://developer.spotify.com/documentation/web-api/concepts/scopes\n */\nexport type SpotifyScope =\n  | \"ugc-image-upload\"\n  | \"user-read-playback-state\"\n  | \"user-modify-playback-state\"\n  | \"user-read-currently-playing\"\n  | \"app-remote-control\"\n  | \"streaming\"\n  | \"playlist-read-private\"\n  | \"playlist-read-collaborative\"\n  | \"playlist-modify-private\"\n  | \"playlist-modify-public\"\n  | \"user-follow-modify\"\n  | \"user-follow-read\"\n  | \"user-top-read\"\n  | \"user-read-recently-played\"\n  | \"user-library-modify\"\n  | \"user-library-read\"\n  | \"user-read-email\"\n  | \"user-read-private\";\n\n/**\n * JS-side error code constants thrown via `Promise.reject(new Error(...))`\n * by the native modules.\n */\nexport type SpotifyErrorCode =\n  | \"USER_CANCELLED\"\n  | \"AUTH_IN_PROGRESS\"\n  | \"INVALID_CONFIG\"\n  | \"NETWORK_ERROR\"\n  | \"TOKEN_SWAP_FAILED\"\n  | \"TOKEN_SWAP_PARSE_ERROR\"\n  | \"SPOTIFY_NOT_INSTALLED\"\n  | \"AUTH_ERROR\"\n  | \"UNKNOWN\";\n\n/**\n * Payload delivered to `addSessionChangeListener` subscribers.\n *\n * - `didInitiate` — a new session was created by `authenticateAsync`\n * - `didRenew`    — an existing session was refreshed by `refreshSessionAsync`\n * - `didFail`     — an auth or refresh attempt failed\n */\nexport type SpotifySessionChangeEvent =\n  | { type: \"didInitiate\"; session: SpotifySession }\n  | { type: \"didRenew\"; session: SpotifySession }\n  | { type: \"didFail\"; error: { code: SpotifyErrorCode; message: string } };\n\n/**\n * Error subclass thrown by `authenticateAsync` and `refreshSessionAsync`\n * carrying a structured `code` field for branching.\n */\nexport class SpotifyError extends Error {\n  public readonly code: SpotifyErrorCode;\n\n  constructor(code: SpotifyErrorCode, message: string) {\n    super(message);\n    this.name = \"SpotifyError\";\n    this.code = code;\n  }\n}\n"]}

package/build/index.d.ts

@@ -10,6 +10,20 @@ declare function isAvailable(): boolean;
  * rejects with a {@link SpotifyError} carrying a `code`.
  */
 declare function authenticateAsync(config: SpotifyConfig): Promise<SpotifySession>;
+/**
+ * Forcibly cancel any in-flight `authenticateAsync` call. Resolves once the
+ * native coordinator's pending continuation has been cleared. No-op when
+ * nothing is in flight, and a no-op on Android (the Android coordinator
+ * self-cleans via structured concurrency).
+ *
+ * Recovery hatch for the iOS coordinator's stuck-state class of bugs: the
+ * SPTSessionManager delegate callbacks are not guaranteed to fire — e.g. when
+ * Spotify never redirects back to the host app — leaving the coordinator's
+ * `pending` continuation set forever and every subsequent `authenticateAsync`
+ * rejecting with `AUTH_IN_PROGRESS` until the process restarts. Call this
+ * before `authenticateAsync` to defensively clear any leaked state.
+ */
+declare function cancelPendingAuthAsync(): Promise<void>;
 /**
  * Exchanges a refresh token for a new access token via your token refresh
  * server. Resolves with a fresh {@link SpotifySession}; rejects with a
@@ -40,6 +54,6 @@ declare function addSessionChangeListener(listener: (event: SpotifySessionChange
 declare const Authenticate: {
     authenticateAsync: typeof authenticateAsync;
 };
-export { isAvailable, authenticateAsync, refreshSessionAsync, addSessionChangeListener, Authenticate, SpotifyError, };
+export { isAvailable, authenticateAsync, cancelPendingAuthAsync, refreshSessionAsync, addSessionChangeListener, Authenticate, SpotifyError, };
 export type { SpotifyConfig, SpotifyRefreshConfig, SpotifySession, SpotifySessionChangeEvent, SpotifyErrorCode, SpotifyScope, } from "./ExpoSpotifySDK.types";
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAY,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EACL,aAAa,EACb,YAAY,EAEZ,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EAC1B,MAAM,wBAAwB,CAAC;AAWhC;;;GAGG;AACH,iBAAS,WAAW,IAAI,OAAO,CAE9B;AAED;;;GAGG;AACH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAqBzE;AAgCD;;;;GAIG;AACH,iBAAS,mBAAmB,CAC1B,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAczB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,wBAAwB,CAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,GACnD,iBAAiB,CAKnB;AAgCD,QAAA,MAAM,YAAY;;CAEjB,CAAC;AAEF,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,YAAY,GACb,CAAC;AACF,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAY,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EACL,aAAa,EACb,YAAY,EAEZ,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EAC1B,MAAM,wBAAwB,CAAC;AAWhC;;;GAGG;AACH,iBAAS,WAAW,IAAI,OAAO,CAE9B;AAED;;;GAGG;AACH,iBAAS,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAqBzE;AAED;;;;;;;;;;;;GAYG;AACH,iBAAS,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAK/C;AAgCD;;;;GAIG;AACH,iBAAS,mBAAmB,CAC1B,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,cAAc,CAAC,CAczB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,wBAAwB,CAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,GACnD,iBAAiB,CAKnB;AAgCD,QAAA,MAAM,YAAY;;CAEjB,CAAC;AAEF,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,YAAY,GACb,CAAC;AACF,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,yBAAyB,EACzB,gBAAgB,EAChB,YAAY,GACb,MAAM,wBAAwB,CAAC"}

package/build/index.js

@@ -31,6 +31,25 @@ function authenticateAsync(config) {
         .then(normaliseSession)
         .catch(rethrowAsSpotifyError);
 }
+/**
+ * Forcibly cancel any in-flight `authenticateAsync` call. Resolves once the
+ * native coordinator's pending continuation has been cleared. No-op when
+ * nothing is in flight, and a no-op on Android (the Android coordinator
+ * self-cleans via structured concurrency).
+ *
+ * Recovery hatch for the iOS coordinator's stuck-state class of bugs: the
+ * SPTSessionManager delegate callbacks are not guaranteed to fire — e.g. when
+ * Spotify never redirects back to the host app — leaving the coordinator's
+ * `pending` continuation set forever and every subsequent `authenticateAsync`
+ * rejecting with `AUTH_IN_PROGRESS` until the process restarts. Call this
+ * before `authenticateAsync` to defensively clear any leaked state.
+ */
+function cancelPendingAuthAsync() {
+    if (Platform.OS !== "ios") {
+        return Promise.resolve();
+    }
+    return ExpoSpotifySDKModule.cancelPendingAuthAsync();
+}
 function normaliseSession(raw) {
     if (!raw || typeof raw !== "object") {
         throw new SpotifyError("UNKNOWN", "Native module returned a non-object session");
@@ -124,5 +143,5 @@ function rethrowAsSpotifyError(err) {
 const Authenticate = {
     authenticateAsync,
 };
-export { isAvailable, authenticateAsync, refreshSessionAsync, addSessionChangeListener, Authenticate, SpotifyError, };
+export { isAvailable, authenticateAsync, cancelPendingAuthAsync, refreshSessionAsync, addSessionChangeListener, Authenticate, SpotifyError, };
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { EventSubscription, Platform } from \"expo-modules-core\";\n\nimport {\n  SpotifyConfig,\n  SpotifyError,\n  SpotifyErrorCode,\n  SpotifyRefreshConfig,\n  SpotifySession,\n  SpotifySessionChangeEvent,\n} from \"./ExpoSpotifySDK.types\";\nimport ExpoSpotifySDKModule from \"./ExpoSpotifySDKModule\";\n\nconst ANDROID_TOKEN_FLOW_WARNING =\n  \"[expo-spotify-sdk] You are using authenticateAsync on Android without a \" +\n  \"tokenSwapURL. The Spotify Android SDK does NOT return a refresh token or \" +\n  \"the actual granted scopes through this path; see the README's \" +\n  \"'Android implicit (TOKEN) flow is not recommended' section.\";\n\nlet warnedAboutAndroidTokenFlow = false;\n\n/**\n * Returns `true` if the Spotify app is installed on the device.\n * Always returns `false` on web.\n */\nfunction isAvailable(): boolean {\n  return ExpoSpotifySDKModule.isAvailable();\n}\n\n/**\n * Starts a Spotify OAuth flow. Resolves with a {@link SpotifySession};\n * rejects with a {@link SpotifyError} carrying a `code`.\n */\nfunction authenticateAsync(config: SpotifyConfig): Promise<SpotifySession> {\n  if (!config.scopes || config.scopes.length === 0) {\n    return Promise.reject(\n      new SpotifyError(\n        \"INVALID_CONFIG\",\n        \"scopes must contain at least one entry\",\n      ),\n    );\n  }\n  if (\n    Platform.OS === \"android\" &&\n    !config.tokenSwapURL &&\n    !warnedAboutAndroidTokenFlow\n  ) {\n    warnedAboutAndroidTokenFlow = true;\n\n    console.warn(ANDROID_TOKEN_FLOW_WARNING);\n  }\n  return ExpoSpotifySDKModule.authenticateAsync(config)\n    .then(normaliseSession)\n    .catch(rethrowAsSpotifyError);\n}\n\nfunction normaliseSession(raw: unknown): SpotifySession {\n  if (!raw || typeof raw !== \"object\") {\n    throw new SpotifyError(\n      \"UNKNOWN\",\n      \"Native module returned a non-object session\",\n    );\n  }\n  const r = raw as Record<string, unknown>;\n  const accessToken = r.accessToken;\n  if (typeof accessToken !== \"string\" || accessToken.length === 0) {\n    throw new SpotifyError(\"UNKNOWN\", \"Session is missing accessToken\");\n  }\n  const expirationDate = r.expirationDate;\n  if (typeof expirationDate !== \"number\") {\n    throw new SpotifyError(\"UNKNOWN\", \"Session is missing expirationDate\");\n  }\n  const refreshTokenRaw = r.refreshToken;\n  const refreshToken =\n    typeof refreshTokenRaw === \"string\" && refreshTokenRaw.length > 0\n      ? refreshTokenRaw\n      : null;\n  const scopesRaw = r.scopes;\n  const scopes = Array.isArray(scopesRaw)\n    ? (scopesRaw.filter(\n        (s) => typeof s === \"string\",\n      ) as SpotifySession[\"scopes\"])\n    : [];\n  return { accessToken, refreshToken, expirationDate, scopes };\n}\n\n/**\n * Exchanges a refresh token for a new access token via your token refresh\n * server. Resolves with a fresh {@link SpotifySession}; rejects with a\n * {@link SpotifyError}.\n */\nfunction refreshSessionAsync(\n  config: SpotifyRefreshConfig,\n): Promise<SpotifySession> {\n  if (!config.refreshToken) {\n    return Promise.reject(\n      new SpotifyError(\"INVALID_CONFIG\", \"refreshToken is required\"),\n    );\n  }\n  if (!config.tokenRefreshURL) {\n    return Promise.reject(\n      new SpotifyError(\"INVALID_CONFIG\", \"tokenRefreshURL is required\"),\n    );\n  }\n  return ExpoSpotifySDKModule.refreshSessionAsync(config)\n    .then(normaliseSession)\n    .catch(rethrowAsSpotifyError);\n}\n\n/**\n * Subscribes to session lifecycle events emitted by the native module.\n *\n * Events are fired for every `authenticateAsync` and `refreshSessionAsync`\n * call, regardless of whether the call was awaited. Useful for persisting\n * tokens in a central store without coupling the store to the call sites.\n *\n * Returns a {@link Subscription} — call `.remove()` to unsubscribe.\n *\n * @example\n * ```ts\n * const sub = addSessionChangeListener((event) => {\n *   if (event.type === \"didInitiate\" || event.type === \"didRenew\") {\n *     store.setSession(event.session);\n *   }\n * });\n * // later:\n * sub.remove();\n * ```\n */\nfunction addSessionChangeListener(\n  listener: (event: SpotifySessionChangeEvent) => void,\n): EventSubscription {\n  return ExpoSpotifySDKModule.addListener(\n    \"onSessionChange\",\n    listener,\n  ) as EventSubscription;\n}\n\nconst ERROR_PREFIX_RE = /^([A-Z_][A-Z0-9_]*):\\s*(.*)$/s;\n\nconst VALID_CODES: ReadonlySet<SpotifyErrorCode> = new Set<SpotifyErrorCode>([\n  \"USER_CANCELLED\",\n  \"AUTH_IN_PROGRESS\",\n  \"INVALID_CONFIG\",\n  \"NETWORK_ERROR\",\n  \"TOKEN_SWAP_FAILED\",\n  \"TOKEN_SWAP_PARSE_ERROR\",\n  \"SPOTIFY_NOT_INSTALLED\",\n  \"AUTH_ERROR\",\n  \"UNKNOWN\",\n]);\n\nfunction rethrowAsSpotifyError(err: unknown): never {\n  if (err instanceof SpotifyError) throw err;\n  if (err instanceof Error) {\n    const m = err.message.match(ERROR_PREFIX_RE);\n    if (m && VALID_CODES.has(m[1] as SpotifyErrorCode)) {\n      throw new SpotifyError(m[1] as SpotifyErrorCode, m[2]);\n    }\n    const maybeCode = (err as Error & { code?: string }).code;\n    if (maybeCode && VALID_CODES.has(maybeCode as SpotifyErrorCode)) {\n      throw new SpotifyError(maybeCode as SpotifyErrorCode, err.message);\n    }\n    throw new SpotifyError(\"UNKNOWN\", err.message);\n  }\n  throw new SpotifyError(\"UNKNOWN\", String(err));\n}\n\nconst Authenticate = {\n  authenticateAsync,\n};\n\nexport {\n  isAvailable,\n  authenticateAsync,\n  refreshSessionAsync,\n  addSessionChangeListener,\n  Authenticate,\n  SpotifyError,\n};\nexport type {\n  SpotifyConfig,\n  SpotifyRefreshConfig,\n  SpotifySession,\n  SpotifySessionChangeEvent,\n  SpotifyErrorCode,\n  SpotifyScope,\n} from \"./ExpoSpotifySDK.types\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { EventSubscription, Platform } from \"expo-modules-core\";\n\nimport {\n  SpotifyConfig,\n  SpotifyError,\n  SpotifyErrorCode,\n  SpotifyRefreshConfig,\n  SpotifySession,\n  SpotifySessionChangeEvent,\n} from \"./ExpoSpotifySDK.types\";\nimport ExpoSpotifySDKModule from \"./ExpoSpotifySDKModule\";\n\nconst ANDROID_TOKEN_FLOW_WARNING =\n  \"[expo-spotify-sdk] You are using authenticateAsync on Android without a \" +\n  \"tokenSwapURL. The Spotify Android SDK does NOT return a refresh token or \" +\n  \"the actual granted scopes through this path; see the README's \" +\n  \"'Android implicit (TOKEN) flow is not recommended' section.\";\n\nlet warnedAboutAndroidTokenFlow = false;\n\n/**\n * Returns `true` if the Spotify app is installed on the device.\n * Always returns `false` on web.\n */\nfunction isAvailable(): boolean {\n  return ExpoSpotifySDKModule.isAvailable();\n}\n\n/**\n * Starts a Spotify OAuth flow. Resolves with a {@link SpotifySession};\n * rejects with a {@link SpotifyError} carrying a `code`.\n */\nfunction authenticateAsync(config: SpotifyConfig): Promise<SpotifySession> {\n  if (!config.scopes || config.scopes.length === 0) {\n    return Promise.reject(\n      new SpotifyError(\n        \"INVALID_CONFIG\",\n        \"scopes must contain at least one entry\",\n      ),\n    );\n  }\n  if (\n    Platform.OS === \"android\" &&\n    !config.tokenSwapURL &&\n    !warnedAboutAndroidTokenFlow\n  ) {\n    warnedAboutAndroidTokenFlow = true;\n\n    console.warn(ANDROID_TOKEN_FLOW_WARNING);\n  }\n  return ExpoSpotifySDKModule.authenticateAsync(config)\n    .then(normaliseSession)\n    .catch(rethrowAsSpotifyError);\n}\n\n/**\n * Forcibly cancel any in-flight `authenticateAsync` call. Resolves once the\n * native coordinator's pending continuation has been cleared. No-op when\n * nothing is in flight, and a no-op on Android (the Android coordinator\n * self-cleans via structured concurrency).\n *\n * Recovery hatch for the iOS coordinator's stuck-state class of bugs: the\n * SPTSessionManager delegate callbacks are not guaranteed to fire — e.g. when\n * Spotify never redirects back to the host app — leaving the coordinator's\n * `pending` continuation set forever and every subsequent `authenticateAsync`\n * rejecting with `AUTH_IN_PROGRESS` until the process restarts. Call this\n * before `authenticateAsync` to defensively clear any leaked state.\n */\nfunction cancelPendingAuthAsync(): Promise<void> {\n  if (Platform.OS !== \"ios\") {\n    return Promise.resolve();\n  }\n  return ExpoSpotifySDKModule.cancelPendingAuthAsync();\n}\n\nfunction normaliseSession(raw: unknown): SpotifySession {\n  if (!raw || typeof raw !== \"object\") {\n    throw new SpotifyError(\n      \"UNKNOWN\",\n      \"Native module returned a non-object session\",\n    );\n  }\n  const r = raw as Record<string, unknown>;\n  const accessToken = r.accessToken;\n  if (typeof accessToken !== \"string\" || accessToken.length === 0) {\n    throw new SpotifyError(\"UNKNOWN\", \"Session is missing accessToken\");\n  }\n  const expirationDate = r.expirationDate;\n  if (typeof expirationDate !== \"number\") {\n    throw new SpotifyError(\"UNKNOWN\", \"Session is missing expirationDate\");\n  }\n  const refreshTokenRaw = r.refreshToken;\n  const refreshToken =\n    typeof refreshTokenRaw === \"string\" && refreshTokenRaw.length > 0\n      ? refreshTokenRaw\n      : null;\n  const scopesRaw = r.scopes;\n  const scopes = Array.isArray(scopesRaw)\n    ? (scopesRaw.filter(\n        (s) => typeof s === \"string\",\n      ) as SpotifySession[\"scopes\"])\n    : [];\n  return { accessToken, refreshToken, expirationDate, scopes };\n}\n\n/**\n * Exchanges a refresh token for a new access token via your token refresh\n * server. Resolves with a fresh {@link SpotifySession}; rejects with a\n * {@link SpotifyError}.\n */\nfunction refreshSessionAsync(\n  config: SpotifyRefreshConfig,\n): Promise<SpotifySession> {\n  if (!config.refreshToken) {\n    return Promise.reject(\n      new SpotifyError(\"INVALID_CONFIG\", \"refreshToken is required\"),\n    );\n  }\n  if (!config.tokenRefreshURL) {\n    return Promise.reject(\n      new SpotifyError(\"INVALID_CONFIG\", \"tokenRefreshURL is required\"),\n    );\n  }\n  return ExpoSpotifySDKModule.refreshSessionAsync(config)\n    .then(normaliseSession)\n    .catch(rethrowAsSpotifyError);\n}\n\n/**\n * Subscribes to session lifecycle events emitted by the native module.\n *\n * Events are fired for every `authenticateAsync` and `refreshSessionAsync`\n * call, regardless of whether the call was awaited. Useful for persisting\n * tokens in a central store without coupling the store to the call sites.\n *\n * Returns a {@link Subscription} — call `.remove()` to unsubscribe.\n *\n * @example\n * ```ts\n * const sub = addSessionChangeListener((event) => {\n *   if (event.type === \"didInitiate\" || event.type === \"didRenew\") {\n *     store.setSession(event.session);\n *   }\n * });\n * // later:\n * sub.remove();\n * ```\n */\nfunction addSessionChangeListener(\n  listener: (event: SpotifySessionChangeEvent) => void,\n): EventSubscription {\n  return ExpoSpotifySDKModule.addListener(\n    \"onSessionChange\",\n    listener,\n  ) as EventSubscription;\n}\n\nconst ERROR_PREFIX_RE = /^([A-Z_][A-Z0-9_]*):\\s*(.*)$/s;\n\nconst VALID_CODES: ReadonlySet<SpotifyErrorCode> = new Set<SpotifyErrorCode>([\n  \"USER_CANCELLED\",\n  \"AUTH_IN_PROGRESS\",\n  \"INVALID_CONFIG\",\n  \"NETWORK_ERROR\",\n  \"TOKEN_SWAP_FAILED\",\n  \"TOKEN_SWAP_PARSE_ERROR\",\n  \"SPOTIFY_NOT_INSTALLED\",\n  \"AUTH_ERROR\",\n  \"UNKNOWN\",\n]);\n\nfunction rethrowAsSpotifyError(err: unknown): never {\n  if (err instanceof SpotifyError) throw err;\n  if (err instanceof Error) {\n    const m = err.message.match(ERROR_PREFIX_RE);\n    if (m && VALID_CODES.has(m[1] as SpotifyErrorCode)) {\n      throw new SpotifyError(m[1] as SpotifyErrorCode, m[2]);\n    }\n    const maybeCode = (err as Error & { code?: string }).code;\n    if (maybeCode && VALID_CODES.has(maybeCode as SpotifyErrorCode)) {\n      throw new SpotifyError(maybeCode as SpotifyErrorCode, err.message);\n    }\n    throw new SpotifyError(\"UNKNOWN\", err.message);\n  }\n  throw new SpotifyError(\"UNKNOWN\", String(err));\n}\n\nconst Authenticate = {\n  authenticateAsync,\n};\n\nexport {\n  isAvailable,\n  authenticateAsync,\n  cancelPendingAuthAsync,\n  refreshSessionAsync,\n  addSessionChangeListener,\n  Authenticate,\n  SpotifyError,\n};\nexport type {\n  SpotifyConfig,\n  SpotifyRefreshConfig,\n  SpotifySession,\n  SpotifySessionChangeEvent,\n  SpotifyErrorCode,\n  SpotifyScope,\n} from \"./ExpoSpotifySDK.types\";\n"]}

package/ios/ExpoSpotifySDKModule.swift

@@ -1,7 +1,7 @@
 import ExpoModulesCore
 import SpotifyiOS
 
-private let SDK_VERSION = "0.5.0"
+private let SDK_VERSION = "0.8.0" // x-release-please-version
 private let EVENT_SESSION_CHANGE = "onSessionChange"
 
 public class ExpoSpotifySDKModule: Module {
@@ -13,6 +13,10 @@ public class ExpoSpotifySDKModule: Module {
       SpotifyAuthCoordinator.shared?.isSpotifyAppInstalled() ?? false
     }
 
+    AsyncFunction("cancelPendingAuthAsync") { () async -> Void in
+      await SpotifyAuthCoordinator.shared?.cancelPending()
+    }
+
     AsyncFunction("authenticateAsync") { (config: AuthenticateOptions) async throws -> [String: Any?] in
       do {
         guard let coordinator = SpotifyAuthCoordinator.shared else {
@@ -60,7 +64,7 @@ public class ExpoSpotifySDKModule: Module {
         let result = try await client.refresh(
           refreshToken: options.refreshToken,
           tokenRefreshURL: options.tokenRefreshURL,
-          previousScopes: []
+          previousScopes: options.scopes
         )
         let map: [String: Any?] = [
           "accessToken": result.accessToken,
@@ -106,4 +110,5 @@ struct AuthenticateOptions: Record {
 struct RefreshOptions: Record {
   @Field var refreshToken: String = ""
   @Field var tokenRefreshURL: String = ""
+  @Field var scopes: [String] = []
 }

package/ios/SPTScopeSerializer.swift

@@ -38,6 +38,11 @@ enum SPTScopeSerializer {
     for string in scopes {
       if let value = lookup[string] {
         result.insert(value)
+      } else {
+        // Unknown scope strings are silently dropped by the Spotify iOS SDK,
+        // which can quietly change the meaning of a caller's request. Surface
+        // it so it's debuggable from the device console.
+        NSLog("[ExpoSpotifySDK] Unknown scope dropped: %@", string)
       }
     }
     return result

package/ios/SpotifyAuthCoordinator.swift

@@ -112,6 +112,20 @@ actor SpotifyAuthCoordinator {
     pending = nil
     cont?.resume(with: result)
   }
+
+  /// Forcibly cancel any in-flight authenticate() call. The pending
+  /// continuation (if any) is resumed with `userCancelled` and `pending` is
+  /// cleared. Safe to call when nothing is in flight (no-op).
+  ///
+  /// Needed because the SPTSessionManager delegate callbacks are not
+  /// guaranteed to fire — e.g. when Spotify never redirects back to the host
+  /// app — leaving `pending` set forever and every subsequent authenticate()
+  /// rejecting with `authInProgress`.
+  func cancelPending() {
+    guard let cont = pending else { return }
+    pending = nil
+    cont.resume(throwing: SpotifyError.userCancelled)
+  }
 }
 
 /// `SPTSessionManagerDelegate` requires NSObject conformance, which an actor

package/ios/SpotifyTokenRefreshClient.swift

@@ -113,6 +113,9 @@ struct SpotifyTokenRefreshClient {
   private func formURLEncoded(_ pairs: [String: String]) -> String {
     var components = URLComponents()
     components.queryItems = pairs.map { URLQueryItem(name: $0.key, value: $0.value) }
-    return components.percentEncodedQuery ?? ""
+    // `URLComponents.percentEncodedQuery` does NOT escape `+`, but in
+    // `application/x-www-form-urlencoded` bodies `+` means space. Replace it
+    // explicitly so refresh tokens containing `+` survive the round-trip.
+    return (components.percentEncodedQuery ?? "").replacingOccurrences(of: "+", with: "%2B")
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wwdrew/expo-spotify-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Expo module wrapping the native Spotify iOS (v5) and Android (v4) SDKs for OAuth authentication",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/plugin/build/android/withSpotifyAndroidAppBuildGradle.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.withSpotifyAndroidAppBuildGradle = void 0;
 const config_plugins_1 = require("@expo/config-plugins");
 const SENTINEL_KEY = "spotifyClientId";
-const DEFAULT_REDIRECT_PATH_PATTERN = "/.*";
+const DEFAULT_REDIRECT_PATH_PATTERN = ".*";
 const withSpotifyAndroidAppBuildGradle = (config, spotifyConfig) => {
     return (0, config_plugins_1.withAppBuildGradle)(config, (config) => {
         if (config.modResults.contents.includes(SENTINEL_KEY)) {

package/plugin/build/types.d.ts

@@ -15,7 +15,7 @@ export type SpotifyScopes = "ugc-image-upload" | "user-read-playback-state" | "u
  *       clientID: "<spotify-client-id>",
  *       scheme: "myapp",
  *       host: "spotify-auth",
- *       redirectPathPattern: "/.*"
+ *       redirectPathPattern: ".*"
  *     }]
  *   ]
  * }
@@ -32,8 +32,11 @@ export interface SpotifyConfig {
     scheme: string;
     /**
      * Path pattern Spotify will accept on the redirect URI. Required by the
-     * Spotify Android Auth SDK from version 3.0.0 onwards. Defaults to `"/.*"`
-     * which matches any path (preserving pre-3.0.0 SDK behaviour).
+     * Spotify Android Auth SDK from version 3.0.0 onwards. Defaults to `".*"`
+     * which matches any path including the empty string, so it works for both
+     * `scheme://host` and `scheme://host/path` redirect URIs. Use a more
+     * specific pattern (e.g. `"/auth/.*"`) only if you have a specific path
+     * registered in your Spotify app settings.
      *
      * See: https://developer.android.com/guide/topics/manifest/data-element#path
      */