@wwdrew/expo-spotify-sdk 2.2.2 → 2.3.0

package/README.md

@@ -308,6 +308,35 @@ function NowPlaying() {
 
 Omit `tokenSwapURL` / `tokenRefreshURL` to use the implicit TOKEN flow (iOS only for refresh; not recommended on Android — see below). For local development without a swap server, auth can still succeed on iOS; production apps should use the code + swap flow.
 
+### Refreshing the session and handling token expiry
+
+Use `Auth.refresh()` to exchange a stored `refreshToken` for a fresh access token via your `tokenRefreshURL`.
+
+> **Spotify policy (from July 20, 2026):** refresh tokens expire **six months** after they are issued. Once expired, Spotify returns an `invalid_grant` error and the token can no longer be used — the user must sign in again. (Only user tokens are affected; Client Credentials flows are not.)
+
+Handle a failed refresh by **discarding the stored token and re-running `Auth.authenticate()`** — do **not** retry the refresh. When your swap server forwards Spotify's response verbatim (see [Token swap server](./docs/guides/token-swap-server.md)), an expired or revoked refresh token surfaces as `AuthError` with the dedicated code `REFRESH_TOKEN_EXPIRED`:
+
+```ts
+async function restoreSession(refreshToken: string) {
+  try {
+    return await Auth.refresh({
+      refreshToken,
+      tokenRefreshURL: "https://your-server.example.com/refresh",
+    });
+  } catch (e) {
+    if (e instanceof AuthError && e.code === "REFRESH_TOKEN_EXPIRED") {
+      // Token expired or revoked: discard it and send the user through
+      // sign-in again. Never retry the refresh.
+      await clearStoredSession();
+      return login(); // your Auth.authenticate() wrapper
+    }
+    throw e; // NETWORK_ERROR / TOKEN_SWAP_FAILED etc. — transient; handle/retry as appropriate
+  }
+}
+```
+
+Test this reauthorization path before July 20, 2026 to avoid disruption for existing users.
+
 ### Check account tier (Web API)
 
 App Remote does not expose Premium status. Call Spotify's Web API with the access token from `Auth.authenticate()`:
@@ -406,6 +435,7 @@ Need the deprecated shims temporarily? Pin **`1.x`**: `npm install @wwdrew/expo-
 | --- | --- |
 | [API reference](./docs/api-reference.md) | All namespaces, methods, hooks |
 | [Error codes](./docs/error-codes.md) | Per-namespace codes with when/what-to-do |
+| [Auth error mapping](./docs/auth-error-mapping.md) | iOS/Android auth → JS mapping matrix and parity checklist |
 | [App Remote error mapping](./docs/app-remote-error-mapping.md) | iOS/Android native → JS mapping matrix |
 | [Platform differences](./docs/guides/platform-differences.md) | iOS vs Android parity |
 | [Native SDK distribution](./docs/guides/native-sdk-distribution.md) | How iOS/Android binaries are fetched, packaged, and bumped |
@@ -427,6 +457,13 @@ Ensure your app's URL scheme is registered in Xcode under **Info → URL Types**
 
 On iOS this can also be a stuck state when Spotify never redirects back. Call `Auth.cancelPending()` before retrying.
 
+**iOS: errors report `UNKNOWN` with the correct message (Expo SDK ≤ 56)**
+On iOS before Expo SDK 57, `expo-modules-core` dropped the structured error `code` when an async function rejected — the message survived but the code did not — so a real code like `USER_CANCELLED` reached JS as `UNKNOWN: Authentication was cancelled by the user`. This is a runtime/bridge limitation, **not** a misclassification: the native module emits the correct code, and the `Auth.addListener("sessionChange", …)` `didFail` event reports it correctly regardless of runtime.
+
+Fixed in **Expo SDK 57** ([expo/expo#47259](https://github.com/expo/expo/pull/47259)). On SDK 57+ `Auth.authenticate()` rejects with the accurate `AuthError.code` and no action is needed.
+
+_Optional — for accurate `code`s on Expo SDK 56 and earlier:_ apply the change from that PR to your installed `expo-modules-core` with [`patch-package`](https://github.com/ds300/patch-package). It routes thrown `Exception`s through the code-preserving conversion in `JavaScriptPromise.reject` instead of stringifying them. If you'd rather not patch, read the code from the `sessionChange` `didFail` event, which already carries the correct `code`.
+
 **App Remote: `CONNECTION_FAILED` / `Connection refused` (iOS code 61)**
 The Spotify app is installed but its App Remote transport is not accepting connections. Common causes:
 

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 = "2.2.2" // x-release-please-version
+private const val SDK_VERSION = "2.3.0" // x-release-please-version
 private const val EVENT_SESSION_CHANGE = "onSessionChange"
 private const val EVENT_CONNECTION_STATE_CHANGE = "onConnectionStateChange"
 private const val EVENT_CONNECTION_ERROR = "onConnectionError"
@@ -165,6 +165,13 @@ class ExpoSpotifySDKModule : Module() {
       } catch (e: expo.modules.kotlin.exception.CodedException) {
         emitSessionError(e.code ?: "UNKNOWN", e.localizedMessage ?: e.code ?: "Unknown error")
         throw e
+      } catch (e: Exception) {
+        val wrapped = UnknownSpotifyException(
+          "Unexpected authentication error: ${e.message ?: e::class.java.simpleName}",
+          e,
+        )
+        emitSessionError(wrapped.code ?: "UNKNOWN", wrapped.localizedMessage ?: "Unknown error")
+        throw wrapped
       }
     }
 
@@ -187,6 +194,13 @@ class ExpoSpotifySDKModule : Module() {
       } catch (e: expo.modules.kotlin.exception.CodedException) {
         emitSessionError(e.code ?: "UNKNOWN", e.localizedMessage ?: e.code ?: "Unknown error")
         throw e
+      } catch (e: Exception) {
+        val wrapped = UnknownSpotifyException(
+          "Unexpected token refresh error: ${e.message ?: e::class.java.simpleName}",
+          e,
+        )
+        emitSessionError(wrapped.code ?: "UNKNOWN", wrapped.localizedMessage ?: "Unknown error")
+        throw wrapped
       }
     }
 

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

@@ -24,6 +24,13 @@ class TokenSwapFailedException(status: Int, body: String?) :
 class TokenSwapParseException(message: String, cause: Throwable? = null) :
   CodedException("TOKEN_SWAP_PARSE_ERROR", message, cause)
 
+class RefreshTokenExpiredException :
+  CodedException(
+    "REFRESH_TOKEN_EXPIRED",
+    "The refresh token is no longer valid (expired or revoked). The user must sign in again.",
+    null,
+  )
+
 class SpotifyNotInstalledException(message: String = "The Spotify app is not installed on this device") :
   CodedException("SPOTIFY_NOT_INSTALLED", message, null)
 

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

@@ -4,6 +4,7 @@ import kotlinx.coroutines.suspendCancellableCoroutine
 import okhttp3.Call
 import okhttp3.Callback
 import okhttp3.FormBody
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
 import okhttp3.OkHttpClient
 import okhttp3.Request
 import okhttp3.Response
@@ -43,11 +44,13 @@ class SpotifyTokenSwapClient(
     tokenSwapURL: String,
     requestedScopes: List<String>,
   ): SpotifySessionPayload {
+    val url = tokenSwapURL.toHttpUrlOrNull()
+      ?: throw InvalidConfigException("Invalid token swap URL: $tokenSwapURL")
     val body = FormBody.Builder()
       .add("code", code)
       .build()
     val request = Request.Builder()
-      .url(tokenSwapURL)
+      .url(url)
       .header("User-Agent", userAgent)
       .post(body)
       .build()
@@ -60,15 +63,17 @@ class SpotifyTokenSwapClient(
     tokenRefreshURL: String,
     previousScopes: List<String>,
   ): SpotifySessionPayload {
+    val url = tokenRefreshURL.toHttpUrlOrNull()
+      ?: throw InvalidConfigException("Invalid token refresh URL: $tokenRefreshURL")
     val body = FormBody.Builder()
       .add("refresh_token", refreshToken)
       .build()
     val request = Request.Builder()
-      .url(tokenRefreshURL)
+      .url(url)
       .header("User-Agent", userAgent)
       .post(body)
       .build()
-    val json = executeJson(request)
+    val json = executeJson(request, invalidGrantIsExpiredToken = true)
     return parseSessionPayload(
       json,
       fallbackScopes = previousScopes,
@@ -76,7 +81,10 @@ class SpotifyTokenSwapClient(
     )
   }
 
-  private suspend fun executeJson(request: Request): JSONObject {
+  private suspend fun executeJson(
+    request: Request,
+    invalidGrantIsExpiredToken: Boolean = false,
+  ): JSONObject {
     val response = try {
       client.executeAsync(request)
     } catch (e: IOException) {
@@ -85,6 +93,15 @@ class SpotifyTokenSwapClient(
     response.use { res ->
       val raw = res.body?.string()
       if (!res.isSuccessful) {
+        // On refresh, Spotify returns `invalid_grant` (HTTP 400) when the
+        // refresh token has expired or been revoked — surface a dedicated code
+        // so callers can route to sign-in. On the swap path the same body means
+        // a bad authorization code, so this remap is scoped to refresh only.
+        // Match the structured OAuth `error` field (RFC 6749) on a 400 rather
+        // than a raw-body substring, so unrelated payloads can't misfire.
+        if (invalidGrantIsExpiredToken && res.code == 400 && isInvalidGrant(raw)) {
+          throw RefreshTokenExpiredException()
+        }
         throw TokenSwapFailedException(res.code, raw)
       }
       if (raw.isNullOrBlank()) {
@@ -98,6 +115,22 @@ class SpotifyTokenSwapClient(
     }
   }
 
+  /**
+   * True when an OAuth error response body declares `"error": "invalid_grant"`
+   * (RFC 6749 §5.2). Parses the JSON and checks the structured field rather than
+   * scanning the raw text, so the token value or other fields can't trigger a
+   * false positive. A non-JSON or differently-shaped body is treated as not an
+   * `invalid_grant`.
+   */
+  private fun isInvalidGrant(raw: String?): Boolean {
+    if (raw.isNullOrBlank()) return false
+    return try {
+      JSONObject(raw).optString("error").equals("invalid_grant", ignoreCase = true)
+    } catch (_: JSONException) {
+      false
+    }
+  }
+
   private fun parseSessionPayload(
     json: JSONObject,
     fallbackScopes: List<String>,

package/build/auth/error.d.ts

@@ -1,5 +1,5 @@
 import { SpotifyError } from "../error";
-export type AuthErrorCode = "USER_CANCELLED" | "AUTH_IN_PROGRESS" | "INVALID_CONFIG" | "NETWORK_ERROR" | "TOKEN_SWAP_FAILED" | "TOKEN_SWAP_PARSE_ERROR" | "SPOTIFY_NOT_INSTALLED" | "AUTH_ERROR" | "UNKNOWN";
+export type AuthErrorCode = "USER_CANCELLED" | "AUTH_IN_PROGRESS" | "INVALID_CONFIG" | "NETWORK_ERROR" | "TOKEN_SWAP_FAILED" | "TOKEN_SWAP_PARSE_ERROR" | "REFRESH_TOKEN_EXPIRED" | "SPOTIFY_NOT_INSTALLED" | "AUTH_ERROR" | "UNKNOWN";
 export declare class AuthError extends SpotifyError {
     readonly namespace: "Auth";
     readonly code: AuthErrorCode;

package/build/auth/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/auth/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,wBAAwB,GACxB,uBAAuB,GACvB,YAAY,GACZ,SAAS,CAAC;AAEd,qBAAa,SAAU,SAAQ,YAAY;IACzC,QAAQ,CAAC,SAAS,EAAG,MAAM,CAAU;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAIjD"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/auth/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,kBAAkB,GAClB,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,wBAAwB,GACxB,uBAAuB,GACvB,uBAAuB,GACvB,YAAY,GACZ,SAAS,CAAC;AAEd,qBAAa,SAAU,SAAQ,YAAY;IACzC,QAAQ,CAAC,SAAS,EAAG,MAAM,CAAU;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAIjD"}

package/build/auth/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/auth/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAaxC,MAAM,OAAO,SAAU,SAAQ,YAAY;IAChC,SAAS,GAAG,MAAe,CAAC;IAC5B,IAAI,CAAgB;IAE7B,YAAY,IAAmB,EAAE,OAAe;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["import { SpotifyError } from \"../error\";\n\nexport type AuthErrorCode =\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\nexport class AuthError extends SpotifyError {\n  readonly namespace = \"Auth\" as const;\n  readonly code: AuthErrorCode;\n\n  constructor(code: AuthErrorCode, message: string) {\n    super(message);\n    this.code = code;\n  }\n}\n"]}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/auth/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAcxC,MAAM,OAAO,SAAU,SAAQ,YAAY;IAChC,SAAS,GAAG,MAAe,CAAC;IAC5B,IAAI,CAAgB;IAE7B,YAAY,IAAmB,EAAE,OAAe;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["import { SpotifyError } from \"../error\";\n\nexport type AuthErrorCode =\n  | \"USER_CANCELLED\"\n  | \"AUTH_IN_PROGRESS\"\n  | \"INVALID_CONFIG\"\n  | \"NETWORK_ERROR\"\n  | \"TOKEN_SWAP_FAILED\"\n  | \"TOKEN_SWAP_PARSE_ERROR\"\n  | \"REFRESH_TOKEN_EXPIRED\"\n  | \"SPOTIFY_NOT_INSTALLED\"\n  | \"AUTH_ERROR\"\n  | \"UNKNOWN\";\n\nexport class AuthError extends SpotifyError {\n  readonly namespace = \"Auth\" as const;\n  readonly code: AuthErrorCode;\n\n  constructor(code: AuthErrorCode, message: string) {\n    super(message);\n    this.code = code;\n  }\n}\n"]}

package/build/auth/index.js

@@ -14,7 +14,6 @@ let warnedAboutAndroidTokenFlow = false;
 const rethrowAsAuthError = createNativeErrorRethrow({
     ErrorClass: AuthError,
     unknownCode: "UNKNOWN",
-    legacyCodePrefix: true,
     validCodes: new Set([
         "USER_CANCELLED",
         "AUTH_IN_PROGRESS",
@@ -22,6 +21,7 @@ const rethrowAsAuthError = createNativeErrorRethrow({
         "NETWORK_ERROR",
         "TOKEN_SWAP_FAILED",
         "TOKEN_SWAP_PARSE_ERROR",
+        "REFRESH_TOKEN_EXPIRED",
         "SPOTIFY_NOT_INSTALLED",
         "AUTH_ERROR",
         "UNKNOWN",

package/build/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,oBAAoB,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAsB,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAkFpC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,0BAA0B,GAC9B,0EAA0E;IAC1E,2EAA2E;IAC3E,gEAAgE;IAChE,6DAA6D,CAAC;AAEhE,IAAI,2BAA2B,GAAG,KAAK,CAAC;AAExC,MAAM,kBAAkB,GAAG,wBAAwB,CAAC;IAClD,UAAU,EAAE,SAAS;IACrB,WAAW,EAAE,SAAS;IACtB,gBAAgB,EAAE,IAAI;IACtB,UAAU,EAAE,IAAI,GAAG,CAAgB;QACjC,gBAAgB;QAChB,kBAAkB;QAClB,gBAAgB;QAChB,eAAe;QACf,mBAAmB;QACnB,wBAAwB;QACxB,uBAAuB;QACvB,YAAY;QACZ,SAAS;KACV,CAAC;CACH,CAAC,CAAC;AAEH,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACpC,MAAM,IAAI,SAAS,CACjB,SAAS,EACT,6CAA6C,CAC9C,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IAClC,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,SAAS,CAAC,SAAS,EAAE,gCAAgC,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,cAAc,GAAG,CAAC,CAAC,cAAc,CAAC;IACxC,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,IAAI,SAAS,CAAC,SAAS,EAAE,mCAAmC,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,eAAe,GAAG,CAAC,CAAC,YAAY,CAAC;IACvC,MAAM,YAAY,GAChB,OAAO,eAAe,KAAK,QAAQ,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC;QAC/D,CAAC,CAAC,eAAe;QACjB,CAAC,CAAC,IAAI,CAAC;IACX,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;QACrC,CAAC,CAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAoB;QACpE,CAAC,CAAC,EAAE,CAAC;IACP,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;AAC/D,CAAC;AAED,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB;;OAEG;IACH,WAAW;QACT,OAAO,oBAAoB,CAAC,WAAW,EAAE,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,YAAY,CAAC,MAA0B;QACrC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACjD,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,SAAS,CACX,gBAAgB,EAChB,wCAAwC,CACzC,CACF,CAAC;QACJ,CAAC;QACD,IACE,QAAQ,CAAC,EAAE,KAAK,SAAS;YACzB,CAAC,MAAM,CAAC,YAAY;YACpB,CAAC,2BAA2B,EAC5B,CAAC;YACD,2BAA2B,GAAG,IAAI,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,oBAAoB,CAAC,iBAAiB,CAAC,MAAM,CAAC;aAClD,IAAI,CAAC,gBAAgB,CAAC;aACtB,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,MAAqB;QAC3B,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,SAAS,CAAC,gBAAgB,EAAE,0BAA0B,CAAC,CAC5D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YAC5B,OAAO,OAAO,CAAC,MAAM,CACnB,IAAI,SAAS,CAAC,gBAAgB,EAAE,6BAA6B,CAAC,CAC/D,CAAC;QACJ,CAAC;QACD,OAAO,oBAAoB,CAAC,mBAAmB,CAAC,MAAM,CAAC;aACpD,IAAI,CAAC,gBAAgB,CAAC;aACtB,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,aAAa;QACX,IAAI,QAAQ,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,OAAO,oBAAoB,CAAC,sBAAsB,EAAE,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CACT,KAAsB,EACtB,QAA6C;QAE7C,OAAO,oBAAoB,CAAC,WAAW,CACrC,iBAAiB,EACjB,QAAQ,CACY,CAAC;IACzB,CAAC;CACO,CAAC","sourcesContent":["import type { EventSubscription } from \"expo-modules-core\";\nimport { Platform } from \"expo-modules-core\";\n\nimport ExpoSpotifySDKModule from \"../ExpoSpotifySDKModule\";\nimport { AuthError, type AuthErrorCode } from \"./error\";\nimport { createNativeErrorRethrow } from \"../internal/native-errors\";\n\nexport type { AuthErrorCode } from \"./error\";\nexport { AuthError } from \"./error\";\n\n// ---------------------------------------------------------------------------\n// Auth-specific types\n// ---------------------------------------------------------------------------\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).\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\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\nexport interface AuthenticateConfig {\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   * `Auth.refresh()` on both platforms.\n   */\n  tokenRefreshURL?: string;\n  /**\n   * If `true`, forces Spotify to show the authorization dialog even when the\n   * user already has an active session. Defaults to `false`.\n   */\n  showDialog?: boolean;\n}\n\nexport interface RefreshConfig {\n  /** The refresh token from a previous `Auth.authenticate()` 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 when\n   * the refresh response omits the `scope` field.\n   */\n  scopes?: SpotifyScope[];\n}\n\n/**\n * Payload delivered to `Auth.addListener(\"sessionChange\", ...)` subscribers.\n */\nexport type SessionChangeEvent =\n  | { type: \"didInitiate\"; session: SpotifySession }\n  | { type: \"didRenew\"; session: SpotifySession }\n  | { type: \"didFail\"; error: { code: AuthErrorCode; message: string } };\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst ANDROID_TOKEN_FLOW_WARNING =\n  \"[expo-spotify-sdk] You are using Auth.authenticate 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\nconst rethrowAsAuthError = createNativeErrorRethrow({\n  ErrorClass: AuthError,\n  unknownCode: \"UNKNOWN\",\n  legacyCodePrefix: true,\n  validCodes: new Set<AuthErrorCode>([\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\nfunction normaliseSession(raw: unknown): SpotifySession {\n  if (!raw || typeof raw !== \"object\") {\n    throw new AuthError(\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 AuthError(\"UNKNOWN\", \"Session is missing accessToken\");\n  }\n  const expirationDate = r.expirationDate;\n  if (typeof expirationDate !== \"number\") {\n    throw new AuthError(\"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((s) => typeof s === \"string\") as SpotifyScope[])\n    : [];\n  return { accessToken, refreshToken, expirationDate, scopes };\n}\n\n// ---------------------------------------------------------------------------\n// Auth namespace\n// ---------------------------------------------------------------------------\n\n/**\n * Spotify Auth namespace. Handles OAuth authentication and session lifecycle.\n *\n * @example\n * ```ts\n * import { Auth } from \"@wwdrew/expo-spotify-sdk\";\n *\n * const session = await Auth.authenticate({ scopes: [\"streaming\"] });\n * ```\n */\nexport const Auth = {\n  /**\n   * Returns `true` if the Spotify app is installed on the device.\n   */\n  isAvailable(): boolean {\n    return ExpoSpotifySDKModule.isAvailable();\n  },\n\n  /**\n   * Starts a Spotify OAuth flow. Resolves with a {@link SpotifySession};\n   * rejects with an {@link AuthError} carrying a `code`.\n   */\n  authenticate(config: AuthenticateConfig): Promise<SpotifySession> {\n    if (!config.scopes || config.scopes.length === 0) {\n      return Promise.reject(\n        new AuthError(\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      console.warn(ANDROID_TOKEN_FLOW_WARNING);\n    }\n    return ExpoSpotifySDKModule.authenticateAsync(config)\n      .then(normaliseSession)\n      .catch(rethrowAsAuthError);\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 an\n   * {@link AuthError}.\n   */\n  refresh(config: RefreshConfig): Promise<SpotifySession> {\n    if (!config.refreshToken) {\n      return Promise.reject(\n        new AuthError(\"INVALID_CONFIG\", \"refreshToken is required\"),\n      );\n    }\n    if (!config.tokenRefreshURL) {\n      return Promise.reject(\n        new AuthError(\"INVALID_CONFIG\", \"tokenRefreshURL is required\"),\n      );\n    }\n    return ExpoSpotifySDKModule.refreshSessionAsync(config)\n      .then(normaliseSession)\n      .catch(rethrowAsAuthError);\n  },\n\n  /**\n   * Forcibly cancel any in-flight `Auth.authenticate()` call. No-op on\n   * Android (the Android coordinator self-cleans via structured concurrency).\n   *\n   * Use before `Auth.authenticate()` to defensively clear any leaked iOS\n   * coordinator state (the `SPTSessionManager` delegate callbacks are not\n   * guaranteed to fire).\n   */\n  cancelPending(): Promise<void> {\n    if (Platform.OS !== \"ios\") {\n      return Promise.resolve();\n    }\n    return ExpoSpotifySDKModule.cancelPendingAuthAsync();\n  },\n\n  /**\n   * Subscribes to session lifecycle events.\n   *\n   * Events fire for every `Auth.authenticate()` and `Auth.refresh()` call,\n   * regardless of whether the call was awaited. Useful for persisting tokens\n   * in a central store without coupling the store to the call sites.\n   *\n   * Returns a `Subscription` — call `.remove()` to unsubscribe.\n   *\n   * @example\n   * ```ts\n   * const sub = Auth.addListener(\"sessionChange\", (event) => {\n   *   if (event.type === \"didInitiate\" || event.type === \"didRenew\") {\n   *     store.setSession(event.session);\n   *   }\n   * });\n   * // later:\n   * sub.remove();\n   * ```\n   */\n  addListener(\n    event: \"sessionChange\",\n    listener: (event: SessionChangeEvent) => void,\n  ): EventSubscription {\n    return ExpoSpotifySDKModule.addListener(\n      \"onSessionChange\",\n      listener,\n    ) as EventSubscription;\n  },\n} as const;\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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","sourcesContent":["import type { EventSubscription } from \"expo-modules-core\";\nimport { Platform } from \"expo-modules-core\";\n\nimport ExpoSpotifySDKModule from \"../ExpoSpotifySDKModule\";\nimport { AuthError, type AuthErrorCode } from \"./error\";\nimport { createNativeErrorRethrow } from \"../internal/native-errors\";\n\nexport type { AuthErrorCode } from \"./error\";\nexport { AuthError } from \"./error\";\n\n// ---------------------------------------------------------------------------\n// Auth-specific types\n// ---------------------------------------------------------------------------\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).\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\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\nexport interface AuthenticateConfig {\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   * `Auth.refresh()` on both platforms.\n   */\n  tokenRefreshURL?: string;\n  /**\n   * If `true`, forces Spotify to show the authorization dialog even when the\n   * user already has an active session. Defaults to `false`.\n   */\n  showDialog?: boolean;\n}\n\nexport interface RefreshConfig {\n  /** The refresh token from a previous `Auth.authenticate()` 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 when\n   * the refresh response omits the `scope` field.\n   */\n  scopes?: SpotifyScope[];\n}\n\n/**\n * Payload delivered to `Auth.addListener(\"sessionChange\", ...)` subscribers.\n */\nexport type SessionChangeEvent =\n  | { type: \"didInitiate\"; session: SpotifySession }\n  | { type: \"didRenew\"; session: SpotifySession }\n  | { type: \"didFail\"; error: { code: AuthErrorCode; message: string } };\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst ANDROID_TOKEN_FLOW_WARNING =\n  \"[expo-spotify-sdk] You are using Auth.authenticate 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\nconst rethrowAsAuthError = createNativeErrorRethrow({\n  ErrorClass: AuthError,\n  unknownCode: \"UNKNOWN\",\n  validCodes: new Set<AuthErrorCode>([\n    \"USER_CANCELLED\",\n    \"AUTH_IN_PROGRESS\",\n    \"INVALID_CONFIG\",\n    \"NETWORK_ERROR\",\n    \"TOKEN_SWAP_FAILED\",\n    \"TOKEN_SWAP_PARSE_ERROR\",\n    \"REFRESH_TOKEN_EXPIRED\",\n    \"SPOTIFY_NOT_INSTALLED\",\n    \"AUTH_ERROR\",\n    \"UNKNOWN\",\n  ]),\n});\n\nfunction normaliseSession(raw: unknown): SpotifySession {\n  if (!raw || typeof raw !== \"object\") {\n    throw new AuthError(\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 AuthError(\"UNKNOWN\", \"Session is missing accessToken\");\n  }\n  const expirationDate = r.expirationDate;\n  if (typeof expirationDate !== \"number\") {\n    throw new AuthError(\"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((s) => typeof s === \"string\") as SpotifyScope[])\n    : [];\n  return { accessToken, refreshToken, expirationDate, scopes };\n}\n\n// ---------------------------------------------------------------------------\n// Auth namespace\n// ---------------------------------------------------------------------------\n\n/**\n * Spotify Auth namespace. Handles OAuth authentication and session lifecycle.\n *\n * @example\n * ```ts\n * import { Auth } from \"@wwdrew/expo-spotify-sdk\";\n *\n * const session = await Auth.authenticate({ scopes: [\"streaming\"] });\n * ```\n */\nexport const Auth = {\n  /**\n   * Returns `true` if the Spotify app is installed on the device.\n   */\n  isAvailable(): boolean {\n    return ExpoSpotifySDKModule.isAvailable();\n  },\n\n  /**\n   * Starts a Spotify OAuth flow. Resolves with a {@link SpotifySession};\n   * rejects with an {@link AuthError} carrying a `code`.\n   */\n  authenticate(config: AuthenticateConfig): Promise<SpotifySession> {\n    if (!config.scopes || config.scopes.length === 0) {\n      return Promise.reject(\n        new AuthError(\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      console.warn(ANDROID_TOKEN_FLOW_WARNING);\n    }\n    return ExpoSpotifySDKModule.authenticateAsync(config)\n      .then(normaliseSession)\n      .catch(rethrowAsAuthError);\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 an\n   * {@link AuthError}.\n   */\n  refresh(config: RefreshConfig): Promise<SpotifySession> {\n    if (!config.refreshToken) {\n      return Promise.reject(\n        new AuthError(\"INVALID_CONFIG\", \"refreshToken is required\"),\n      );\n    }\n    if (!config.tokenRefreshURL) {\n      return Promise.reject(\n        new AuthError(\"INVALID_CONFIG\", \"tokenRefreshURL is required\"),\n      );\n    }\n    return ExpoSpotifySDKModule.refreshSessionAsync(config)\n      .then(normaliseSession)\n      .catch(rethrowAsAuthError);\n  },\n\n  /**\n   * Forcibly cancel any in-flight `Auth.authenticate()` call. No-op on\n   * Android (the Android coordinator self-cleans via structured concurrency).\n   *\n   * Use before `Auth.authenticate()` to defensively clear any leaked iOS\n   * coordinator state (the `SPTSessionManager` delegate callbacks are not\n   * guaranteed to fire).\n   */\n  cancelPending(): Promise<void> {\n    if (Platform.OS !== \"ios\") {\n      return Promise.resolve();\n    }\n    return ExpoSpotifySDKModule.cancelPendingAuthAsync();\n  },\n\n  /**\n   * Subscribes to session lifecycle events.\n   *\n   * Events fire for every `Auth.authenticate()` and `Auth.refresh()` call,\n   * regardless of whether the call was awaited. Useful for persisting tokens\n   * in a central store without coupling the store to the call sites.\n   *\n   * Returns a `Subscription` — call `.remove()` to unsubscribe.\n   *\n   * @example\n   * ```ts\n   * const sub = Auth.addListener(\"sessionChange\", (event) => {\n   *   if (event.type === \"didInitiate\" || event.type === \"didRenew\") {\n   *     store.setSession(event.session);\n   *   }\n   * });\n   * // later:\n   * sub.remove();\n   * ```\n   */\n  addListener(\n    event: \"sessionChange\",\n    listener: (event: SessionChangeEvent) => void,\n  ): EventSubscription {\n    return ExpoSpotifySDKModule.addListener(\n      \"onSessionChange\",\n      listener,\n    ) as EventSubscription;\n  },\n} as const;\n"]}

package/build/internal/native-errors.d.ts

@@ -4,8 +4,6 @@ export interface NativeErrorRethrowOptions<C extends string, E extends SpotifyEr
 }> {
     ErrorClass: new (code: C, message: string) => E;
     validCodes: ReadonlySet<C>;
-    /** Parse legacy `"CODE: message"` prefixes embedded in native error reasons. */
-    legacyCodePrefix?: boolean;
     unknownCode: C;
 }
 export declare function createNativeErrorRethrow<C extends string, E extends SpotifyError & {

package/build/internal/native-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-errors.d.ts","sourceRoot":"","sources":["../../src/internal/native-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAU7C,MAAM,WAAW,yBAAyB,CACxC,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,YAAY,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE;IAEpC,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC,CAAC;IAChD,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAC3B,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,WAAW,EAAE,CAAC,CAAC;CAChB;AAED,wBAAgB,wBAAwB,CACtC,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,YAAY,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,EACpC,OAAO,EAAE,yBAAyB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,CAqBnE"}
+{"version":3,"file":"native-errors.d.ts","sourceRoot":"","sources":["../../src/internal/native-errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAS7C,MAAM,WAAW,yBAAyB,CACxC,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,YAAY,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE;IAEpC,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC,CAAC;IAChD,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAC3B,WAAW,EAAE,CAAC,CAAC;CAChB;AAED,wBAAgB,wBAAwB,CACtC,CAAC,SAAS,MAAM,EAChB,CAAC,SAAS,YAAY,GAAG;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,EACpC,OAAO,EAAE,yBAAyB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,CAmBnE"}

package/build/internal/native-errors.js

@@ -1,26 +1,23 @@
 const CAUSE_SEPARATOR = "→ Caused by: ";
-const LEGACY_CODE_PREFIX_RE = /^([A-Z_][A-Z0-9_]*):\s*(.*)$/s;
 function unwrapReason(message) {
     const idx = message.lastIndexOf(CAUSE_SEPARATOR);
     return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);
 }
 export function createNativeErrorRethrow(options) {
-    const { ErrorClass, validCodes, legacyCodePrefix, unknownCode } = options;
+    const { ErrorClass, validCodes, unknownCode } = options;
     return function rethrowNativeError(err) {
         if (err instanceof ErrorClass)
             throw err;
         if (err instanceof Error) {
             const reason = unwrapReason(err.message);
+            // `err.code` is the structured code from the native `Exception`. On iOS
+            // before Expo SDK 57 the async-rejection bridge dropped it (the message
+            // survived), surfacing as `unknownCode` with the correct message; fixed
+            // in Expo SDK 57 (expo/expo#47259), which preserves the code.
             const maybeCode = err.code;
             if (maybeCode && validCodes.has(maybeCode)) {
                 throw new ErrorClass(maybeCode, reason);
             }
-            if (legacyCodePrefix) {
-                const match = reason.match(LEGACY_CODE_PREFIX_RE);
-                if (match && validCodes.has(match[1])) {
-                    throw new ErrorClass(match[1], match[2]);
-                }
-            }
             throw new ErrorClass(unknownCode, reason);
         }
         throw new ErrorClass(unknownCode, String(err));

package/build/internal/native-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"native-errors.js","sourceRoot":"","sources":["../../src/internal/native-errors.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,eAAe,CAAC;AACxC,MAAM,qBAAqB,GAAG,+BAA+B,CAAC;AAE9D,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IACjD,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAC5E,CAAC;AAaD,MAAM,UAAU,wBAAwB,CAGtC,OAAwC;IACxC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAE1E,OAAO,SAAS,kBAAkB,CAAC,GAAY;QAC7C,IAAI,GAAG,YAAY,UAAU;YAAE,MAAM,GAAG,CAAC;QACzC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,SAAS,GAAI,GAAiC,CAAC,IAAI,CAAC;YAC1D,IAAI,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,SAAc,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,UAAU,CAAC,SAAc,EAAE,MAAM,CAAC,CAAC;YAC/C,CAAC;YACD,IAAI,gBAAgB,EAAE,CAAC;gBACrB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBAClD,IAAI,KAAK,IAAI,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAM,CAAC,EAAE,CAAC;oBAC3C,MAAM,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAM,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import type { SpotifyError } from \"../error\";\n\nconst CAUSE_SEPARATOR = \"→ Caused by: \";\nconst LEGACY_CODE_PREFIX_RE = /^([A-Z_][A-Z0-9_]*):\\s*(.*)$/s;\n\nfunction unwrapReason(message: string): string {\n  const idx = message.lastIndexOf(CAUSE_SEPARATOR);\n  return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);\n}\n\nexport interface NativeErrorRethrowOptions<\n  C extends string,\n  E extends SpotifyError & { code: C },\n> {\n  ErrorClass: new (code: C, message: string) => E;\n  validCodes: ReadonlySet<C>;\n  /** Parse legacy `\"CODE: message\"` prefixes embedded in native error reasons. */\n  legacyCodePrefix?: boolean;\n  unknownCode: C;\n}\n\nexport function createNativeErrorRethrow<\n  C extends string,\n  E extends SpotifyError & { code: C },\n>(options: NativeErrorRethrowOptions<C, E>): (err: unknown) => never {\n  const { ErrorClass, validCodes, legacyCodePrefix, unknownCode } = options;\n\n  return function rethrowNativeError(err: unknown): never {\n    if (err instanceof ErrorClass) throw err;\n    if (err instanceof Error) {\n      const reason = unwrapReason(err.message);\n      const maybeCode = (err as Error & { code?: string }).code;\n      if (maybeCode && validCodes.has(maybeCode as C)) {\n        throw new ErrorClass(maybeCode as C, reason);\n      }\n      if (legacyCodePrefix) {\n        const match = reason.match(LEGACY_CODE_PREFIX_RE);\n        if (match && validCodes.has(match[1] as C)) {\n          throw new ErrorClass(match[1] as C, match[2]!);\n        }\n      }\n      throw new ErrorClass(unknownCode, reason);\n    }\n    throw new ErrorClass(unknownCode, String(err));\n  };\n}\n"]}
+{"version":3,"file":"native-errors.js","sourceRoot":"","sources":["../../src/internal/native-errors.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,eAAe,CAAC;AAExC,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;IACjD,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;AAC5E,CAAC;AAWD,MAAM,UAAU,wBAAwB,CAGtC,OAAwC;IACxC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAExD,OAAO,SAAS,kBAAkB,CAAC,GAAY;QAC7C,IAAI,GAAG,YAAY,UAAU;YAAE,MAAM,GAAG,CAAC;QACzC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,wEAAwE;YACxE,wEAAwE;YACxE,wEAAwE;YACxE,8DAA8D;YAC9D,MAAM,SAAS,GAAI,GAAiC,CAAC,IAAI,CAAC;YAC1D,IAAI,SAAS,IAAI,UAAU,CAAC,GAAG,CAAC,SAAc,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,UAAU,CAAC,SAAc,EAAE,MAAM,CAAC,CAAC;YAC/C,CAAC;YACD,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import type { SpotifyError } from \"../error\";\n\nconst CAUSE_SEPARATOR = \"→ Caused by: \";\n\nfunction unwrapReason(message: string): string {\n  const idx = message.lastIndexOf(CAUSE_SEPARATOR);\n  return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);\n}\n\nexport interface NativeErrorRethrowOptions<\n  C extends string,\n  E extends SpotifyError & { code: C },\n> {\n  ErrorClass: new (code: C, message: string) => E;\n  validCodes: ReadonlySet<C>;\n  unknownCode: C;\n}\n\nexport function createNativeErrorRethrow<\n  C extends string,\n  E extends SpotifyError & { code: C },\n>(options: NativeErrorRethrowOptions<C, E>): (err: unknown) => never {\n  const { ErrorClass, validCodes, unknownCode } = options;\n\n  return function rethrowNativeError(err: unknown): never {\n    if (err instanceof ErrorClass) throw err;\n    if (err instanceof Error) {\n      const reason = unwrapReason(err.message);\n      // `err.code` is the structured code from the native `Exception`. On iOS\n      // before Expo SDK 57 the async-rejection bridge dropped it (the message\n      // survived), surfacing as `unknownCode` with the correct message; fixed\n      // in Expo SDK 57 (expo/expo#47259), which preserves the code.\n      const maybeCode = (err as Error & { code?: string }).code;\n      if (maybeCode && validCodes.has(maybeCode as C)) {\n        throw new ErrorClass(maybeCode as C, reason);\n      }\n      throw new ErrorClass(unknownCode, reason);\n    }\n    throw new ErrorClass(unknownCode, String(err));\n  };\n}\n"]}

package/ios/ExpoSpotifySDKModule.swift

@@ -1,7 +1,7 @@
 import ExpoModulesCore
 import SpotifyiOS
 
-private let SDK_VERSION = "2.2.2" // x-release-please-version
+private let SDK_VERSION = "2.3.0" // x-release-please-version
 private let EVENT_SESSION_CHANGE = "onSessionChange"
 private let EVENT_CONNECTION_STATE_CHANGE = "onConnectionStateChange"
 private let EVENT_CONNECTION_ERROR = "onConnectionError"
@@ -72,12 +72,18 @@ public class ExpoSpotifySDKModule: Module {
         let map = self.sessionToMap(session)
         self.sendEvent(EVENT_SESSION_CHANGE, ["type": "didInitiate", "session": map])
         return map
-      } catch let error as SpotifyError {
-        self.sendEvent(EVENT_SESSION_CHANGE, [
-          "type": "didFail",
-          "error": ["code": error.code, "message": error.message],
-        ])
-        throw SpotifyAuthException(error)
+      } catch {
+        // Already-typed `SpotifyError`s pass through; anything else is a raw
+        // failure the SDK surfaced without routing through the delegate (e.g. a
+        // user-cancelled web auth). `classify` is the same entry point the
+        // delegate uses, so both paths map identical errors to identical codes.
+        let mapped = error as? SpotifyError
+          ?? SpotifyAuthErrorMapping.classify(
+            error,
+            context: .init(tokenSwapConfigured: config.tokenSwapURL.flatMap(URL.init) != nil)
+          )
+        self.emitDidFail(mapped)
+        throw SpotifyAuthException(mapped)
       }
     }
 
@@ -109,16 +115,10 @@ public class ExpoSpotifySDKModule: Module {
         self.sendEvent(EVENT_SESSION_CHANGE, ["type": "didRenew", "session": map])
         return map
       } catch let error as SpotifyError {
-        self.sendEvent(EVENT_SESSION_CHANGE, [
-          "type": "didFail",
-          "error": ["code": error.code, "message": error.message],
-        ])
+        self.emitDidFail(error)
         throw SpotifyAuthException(error)
       } catch let error as SpotifyRefreshError {
-        self.sendEvent(EVENT_SESSION_CHANGE, [
-          "type": "didFail",
-          "error": ["code": error.code, "message": error.message],
-        ])
+        self.emitDidFail(code: error.code, message: error.message)
         throw SpotifyRefreshException(error)
       }
     }
@@ -325,6 +325,17 @@ public class ExpoSpotifySDKModule: Module {
 
   // MARK: — Helpers
 
+  private func emitDidFail(_ error: SpotifyError) {
+    emitDidFail(code: error.code, message: error.message)
+  }
+
+  private func emitDidFail(code: String, message: String) {
+    sendEvent(EVENT_SESSION_CHANGE, [
+      "type": "didFail",
+      "error": ["code": code, "message": message],
+    ])
+  }
+
   private func sessionToMap(_ session: SPTSession) -> [String: Any?] {
     return [
       "accessToken": session.accessToken,

package/ios/SpotifyAuthCoordinator.swift

@@ -3,69 +3,6 @@ import Foundation
 import SpotifyiOS
 import UIKit
 
-/// Public, structured errors thrown by the coordinator. Each case carries the
-/// JS-facing error code in `code`, mirroring the Android `CodedException`
-/// taxonomy.
-enum SpotifyError: Error {
-  case invalidConfiguration(String)
-  case authInProgress
-  case userCancelled
-  case spotifyNotInstalled
-  case underlying(message: String, cause: Error)
-
-  var code: String {
-    switch self {
-    case .invalidConfiguration: return "INVALID_CONFIG"
-    case .authInProgress:       return "AUTH_IN_PROGRESS"
-    case .userCancelled:        return "USER_CANCELLED"
-    case .spotifyNotInstalled:  return "SPOTIFY_NOT_INSTALLED"
-    case .underlying:           return "UNKNOWN"
-    }
-  }
-
-  var message: String {
-    switch self {
-    case .invalidConfiguration(let m):     return m
-    case .authInProgress:                  return "Another authentication request is already in progress"
-    case .userCancelled:                   return "Authentication was cancelled by the user"
-    case .spotifyNotInstalled:             return "The Spotify app is not installed on this device"
-    case .underlying(let message, _):      return message
-    }
-  }
-
-  /// The original error that caused this failure, if any. Surfaced as the
-  /// JS-facing exception's `cause` so debugging / Sentry breadcrumbs keep the
-  /// full chain rather than collapsing into "undefined reason".
-  var underlyingCause: Error? {
-    switch self {
-    case .underlying(_, let cause): return cause
-    default:                        return nil
-    }
-  }
-}
-
-/// `Exception` subclass that projects a `SpotifyError`'s `code` and `message`
-/// through `expo-modules-core`'s exception bridge so JS receives the structured
-/// code and a meaningful reason — not the default "undefined reason" placeholder.
-///
-/// Without this wrapper an `AsyncFunction` rejection collapses to
-/// `FunctionCallException` → `cause.reason = "undefined reason"` because the
-/// previously-used `GenericException<String>` does not override `reason`.
-final class SpotifyAuthException: Exception, @unchecked Sendable {
-  private let spotifyCode: String
-  private let spotifyMessage: String
-
-  init(_ error: SpotifyError, file: String = #fileID, line: UInt = #line, function: String = #function) {
-    self.spotifyCode = error.code
-    self.spotifyMessage = error.message
-    super.init(file: file, line: line, function: function)
-    self.cause = error.underlyingCause
-  }
-
-  override var code: String { spotifyCode }
-  override var reason: String { spotifyMessage }
-}
-
 /// `actor` ensures `pending` is mutated only on the actor's serial executor;
 /// no manual locks needed.
 actor SpotifyAuthCoordinator {
@@ -123,6 +60,10 @@ actor SpotifyAuthCoordinator {
     // mutating it here takes effect for the upcoming initiateSession call.
     sptConfiguration.tokenSwapURL = tokenSwapURL
     sptConfiguration.tokenRefreshURL = tokenRefreshURL
+    bridge.updateAuthContext(
+      tokenSwapURL: tokenSwapURL,
+      tokenRefreshURL: tokenRefreshURL
+    )
     // alwaysShowAuthorizationDialog is a property on SPTSessionManager, not an
     // SPTAuthorizationOptions flag (the options enum has no such case).
     sessionManager.alwaysShowAuthorizationDialog = showDialog
@@ -146,6 +87,7 @@ actor SpotifyAuthCoordinator {
   func deliver(_ result: Result<SPTSession, Error>) {
     let cont = pending
     pending = nil
+    bridge.clearAuthContext()
     cont?.resume(with: result)
   }
 
@@ -168,7 +110,21 @@ actor SpotifyAuthCoordinator {
 /// can't satisfy directly. The bridge is a tiny NSObject that hops the call
 /// onto the actor's executor.
 final class SpotifySessionDelegateBridge: NSObject, SPTSessionManagerDelegate {
+  private struct AuthContext {
+    let tokenSwapURL: URL?
+    let tokenRefreshURL: URL?
+  }
+
   weak var coordinator: SpotifyAuthCoordinator?
+  private var authContext: AuthContext?
+
+  func updateAuthContext(tokenSwapURL: URL?, tokenRefreshURL: URL?) {
+    authContext = AuthContext(tokenSwapURL: tokenSwapURL, tokenRefreshURL: tokenRefreshURL)
+  }
+
+  func clearAuthContext() {
+    authContext = nil
+  }
 
   func sessionManager(manager _: SPTSessionManager, didInitiate session: SPTSession) {
     NSLog(
@@ -182,8 +138,11 @@ final class SpotifySessionDelegateBridge: NSObject, SPTSessionManagerDelegate {
   }
 
   func sessionManager(manager _: SPTSessionManager, didFailWith error: Error) {
-    let mapped: Error = mapSDKError(error)
     NSLog("[ExpoSpotifySDK] didFailWithError %@", String(describing: error))
+    let mapped = SpotifyAuthErrorMapping.classify(
+      error,
+      context: .init(tokenSwapConfigured: authContext?.tokenSwapURL != nil)
+    )
     Task { await coordinator?.deliver(.failure(mapped)) }
   }
 
@@ -195,41 +154,4 @@ final class SpotifySessionDelegateBridge: NSObject, SPTSessionManagerDelegate {
     )
     Task { await coordinator?.deliver(.success(session)) }
   }
-
-  /// Translate a few well-known SDK error shapes into our taxonomy.
-  private func mapSDKError(_ error: Error) -> Error {
-    let nsError = error as NSError
-    let description = nsError.localizedDescription.lowercased()
-    if description.contains("cancel") {
-      return SpotifyError.userCancelled
-    }
-    // Keep the original NSError as `cause` so the structured underlying-chain
-    // is preserved (Sentry, debug breadcrumbs); the rendered string goes to
-    // `message` so JS callers get a single human-readable line.
-    return SpotifyError.underlying(message: describeError(nsError), cause: nsError)
-  }
-
-  /// Build a diagnostic string from an NSError that includes the domain,
-  /// code, localized description, and the full chain of underlying errors.
-  /// Used because `SPTError` (and many `URLSession` errors it wraps) often
-  /// have an empty `localizedDescription`, surfacing as "undefined reason"
-  /// in JS without this expansion.
-  private func describeError(_ error: NSError) -> String {
-    var parts: [String] = []
-    parts.append("\(error.domain) code \(error.code)")
-    let desc = error.localizedDescription
-    if !desc.isEmpty {
-      parts.append("\"\(desc)\"")
-    }
-    var ui = error.userInfo
-    ui.removeValue(forKey: NSUnderlyingErrorKey)
-    ui.removeValue(forKey: NSLocalizedDescriptionKey)
-    if !ui.isEmpty {
-      parts.append("userInfo=\(ui)")
-    }
-    if let underlying = error.userInfo[NSUnderlyingErrorKey] as? NSError {
-      parts.append("→ underlying: \(describeError(underlying))")
-    }
-    return parts.joined(separator: " ")
-  }
 }

package/ios/SpotifyAuthErrorMapping.swift

@@ -0,0 +1,259 @@
+import AuthenticationServices
+import Foundation
+
+/// Maps a raw authentication `NSError` into the structured `SpotifyError`
+/// taxonomy.
+///
+/// This is the **single** canonical entry point for auth-error classification.
+/// Both the `SPTSessionManager` delegate failure callback and the module-level
+/// top-level `catch` route through `classify(_:context:)`, so a given raw error
+/// yields the same `SpotifyError` regardless of which path delivers it. (The
+/// Spotify iOS SDK does not always route cancellations through the delegate, so
+/// the same error can arrive via either path.)
+///
+/// Keep aligned with [docs/auth-error-mapping.md](../docs/auth-error-mapping.md).
+enum SpotifyAuthErrorMapping {
+  /// Signals the classifier needs that aren't derivable from the error itself.
+  /// `tokenSwapConfigured` lets ambiguous SDK failures be treated as
+  /// token-swap-class errors when the caller supplied a token swap URL.
+  struct Context {
+    var tokenSwapConfigured: Bool = false
+  }
+
+  /// Walk the error once, then apply rules in priority order: typed/structural
+  /// signals first (cancellation domain/code, URL transport errors, parsed HTTP
+  /// status), then best-effort message-text heuristics, then `UNKNOWN`.
+  static func classify(_ error: Error, context: Context = Context()) -> SpotifyError {
+    let chain = nsErrorChain(error)
+    let root = chain[0]
+    // `detail` keeps raw `userInfo` for the in-process classification heuristics
+    // only; `redactedDetail` (keys-only `userInfo`) is the sole variant that
+    // leaves this process via NSLog or JS-visible error messages.
+    let detail = describeError(root)
+    let redactedDetail = describeError(root, redactUserInfo: true)
+    let result = classify(
+      chain: chain,
+      root: root,
+      detail: detail,
+      redactedDetail: redactedDetail,
+      context: context
+    )
+
+    NSLog(
+      "[ExpoSpotifySDK] classifyAuthError classified=%@ domain=%@ code=%d detail=%@",
+      result.code,
+      root.domain,
+      root.code,
+      redactedDetail
+    )
+    return result
+  }
+
+  private static func classify(
+    chain: [NSError],
+    root: NSError,
+    detail: String,
+    redactedDetail: String,
+    context: Context
+  ) -> SpotifyError {
+    // 1. User cancellation — a typed domain/code anywhere in the chain, or
+    //    best-effort cancel text within a known auth/browser domain.
+    if chain.contains(where: { isKnownCancellationCode($0) || messageLooksCancelled($0) }) {
+      return .userCancelled
+    }
+
+    // 2. Transport failure anywhere in the chain (cancellation already handled).
+    if chain.contains(where: { $0.domain == NSURLErrorDomain && $0.code != NSURLErrorCancelled }) {
+      return .networkError(
+        message: "Network error during Spotify authentication: \(redactedDetail)",
+        cause: root
+      )
+    }
+
+    let lower = detail.lowercased()
+
+    // 3. OAuth-style rejection text — evaluated before the token-swap gate so
+    //    these are never misclassified as token-swap errors.
+    if lower.contains("access_denied") || lower.contains("invalid_scope") ||
+       lower.contains("invalid_client") || lower.contains("authorization") ||
+       lower.contains("oauth") || lower.contains("spotify account") {
+      return .authError(message: "Spotify authorization failed: \(redactedDetail)", cause: root)
+    }
+
+    if let status = extractHTTPStatusCode(from: detail), status == 401 || status == 403 {
+      return .authError(
+        message: "Spotify authorization failed (HTTP \(status)): \(redactedDetail)",
+        cause: root
+      )
+    }
+
+    // 4. Token-swap-class failure — when a swap URL was configured, or the text
+    //    explicitly references the token endpoint.
+    if context.tokenSwapConfigured || lower.contains("token swap") ||
+       lower.contains("token endpoint") || lower.contains("token exchange") {
+      if let status = extractHTTPStatusCode(from: detail) {
+        return .tokenSwapFailed(
+          status: status,
+          message: "Token swap server returned HTTP \(status): \(redactedDetail)",
+          cause: root
+        )
+      }
+      if lower.contains("parse") || lower.contains("json") ||
+         lower.contains("decode") || lower.contains("malformed") {
+        return .tokenSwapParseError(
+          message: "Token swap response was invalid: \(redactedDetail)",
+          cause: root
+        )
+      }
+      return .tokenSwapFailed(status: nil, message: "Token swap failed: \(redactedDetail)", cause: root)
+    }
+
+    // 5. Fallback. Keep the original NSError as `cause` so the structured
+    //    underlying-chain is preserved (Sentry, debug breadcrumbs).
+    return .underlying(message: redactedDetail, cause: root)
+  }
+
+  // MARK: — Chain traversal
+
+  /// The error plus its `NSUnderlyingErrorKey` ancestry, root first. The chain
+  /// is effectively a singly-linked list; the `seen` set only guards against a
+  /// pathological cycle. Every rule above consumes this single walk instead of
+  /// re-implementing the traversal.
+  private static func nsErrorChain(_ error: Error) -> [NSError] {
+    var chain: [NSError] = []
+    var seen = Set<ObjectIdentifier>()
+    var current: NSError? = error as NSError
+    while let node = current, seen.insert(ObjectIdentifier(node)).inserted {
+      chain.append(node)
+      current = node.userInfo[NSUnderlyingErrorKey] as? NSError
+    }
+    return chain
+  }
+
+  // MARK: — Typed cancellation signals (locale-independent)
+
+  /// Recognise a single error's well-known cancellation domain/code. These are
+  /// stable identifiers and integer codes, so they hold across every locale.
+  private static func isKnownCancellationCode(_ error: NSError) -> Bool {
+    if error.domain == NSURLErrorDomain && error.code == NSURLErrorCancelled {
+      return true
+    }
+
+    if #available(iOS 12.0, *),
+       error.domain == ASWebAuthenticationSessionErrorDomain,
+       error.code == ASWebAuthenticationSessionError.canceledLogin.rawValue {
+      return true
+    }
+
+    if error.domain == "SFAuthenticationErrorDomain" && error.code == 1 {
+      return true
+    }
+
+    // The Spotify iOS auth/login SDK reports user cancellation under its own
+    // login domain with code 1. This domain contains "spotify" but not "auth",
+    // so the fuzzy text matching below would not catch it either.
+    if error.domain == "com.spotify.sdk.login" && error.code == 1 {
+      return true
+    }
+
+    return false
+  }
+
+  // MARK: — Best-effort text heuristics (locale-dependent fallback)
+
+  /// Last-resort cancellation detection for errors that lack a recognised
+  /// domain/code. Matches localized message text, so it is English-biased by
+  /// nature — kept deliberately narrow (auth/browser domains only) so unrelated
+  /// transport/backend failures are never mapped to `USER_CANCELLED`.
+  private static func messageLooksCancelled(_ error: NSError) -> Bool {
+    guard isLikelyAuthCancellationDomain(error.domain) else {
+      return false
+    }
+
+    let cancelKeywords = ["cancel", "canceled", "cancelled"]
+    let negativeKeywords = [
+      "timed out", "timeout", "network", "offline", "unreachable",
+      "server", "unauthorized", "forbidden", "invalid"
+    ]
+    let combined = [
+      error.localizedDescription,
+      error.localizedFailureReason ?? "",
+      error.userInfo[NSLocalizedDescriptionKey] as? String ?? "",
+      error.userInfo[NSLocalizedFailureReasonErrorKey] as? String ?? ""
+    ].joined(separator: " ").lowercased()
+
+    if negativeKeywords.contains(where: { combined.contains($0) }) {
+      return false
+    }
+    return cancelKeywords.contains(where: { combined.contains($0) })
+  }
+
+  private static func isLikelyAuthCancellationDomain(_ domain: String) -> Bool {
+    if domain == ASWebAuthenticationSessionErrorDomain || domain == "SFAuthenticationErrorDomain" {
+      return true
+    }
+    // SPT wrappers commonly bubble auth-web errors under their own namespace.
+    let lower = domain.lowercased()
+    return lower.contains("spotify") && lower.contains("auth")
+  }
+
+  // MARK: — Diagnostics
+
+  /// Build a diagnostic string from an NSError that includes the domain, code,
+  /// localized description, and the full chain of underlying errors. Needed
+  /// because `SPTError` (and many `URLSession` errors it wraps) often have an
+  /// empty `localizedDescription`, surfacing as "undefined reason" in JS
+  /// without this expansion.
+  ///
+  /// When `redactUserInfo` is `true`, arbitrary `userInfo` *values* are dropped
+  /// in favour of a sorted key list. `userInfo` can carry secrets (tokens,
+  /// auth codes, raw request/response bodies), so any string that is logged or
+  /// returned to JS must use the redacted form; the unredacted form is for the
+  /// in-process classification heuristics only.
+  private static func describeError(_ error: NSError, redactUserInfo: Bool = false) -> String {
+    var parts: [String] = ["\(error.domain) code \(error.code)"]
+    let desc = error.localizedDescription
+    if !desc.isEmpty {
+      parts.append("\"\(desc)\"")
+    }
+    var ui = error.userInfo
+    ui.removeValue(forKey: NSUnderlyingErrorKey)
+    ui.removeValue(forKey: NSLocalizedDescriptionKey)
+    if !ui.isEmpty {
+      if redactUserInfo {
+        let keys = ui.keys.sorted().joined(separator: ", ")
+        parts.append("userInfoKeys=[\(keys)]")
+      } else {
+        parts.append("userInfo=\(ui)")
+      }
+    }
+    if let underlying = error.userInfo[NSUnderlyingErrorKey] as? NSError {
+      parts.append("→ underlying: \(describeError(underlying, redactUserInfo: redactUserInfo))")
+    }
+    return parts.joined(separator: " ")
+  }
+
+  private static func extractHTTPStatusCode(from message: String) -> Int? {
+    let patterns = [
+      #"http\s+([1-5][0-9]{2})"#,
+      #"status(?:\s+code)?[:=\s]+([1-5][0-9]{2})"#
+    ]
+
+    for pattern in patterns {
+      guard let regex = try? NSRegularExpression(pattern: pattern, options: [.caseInsensitive]) else {
+        continue
+      }
+      let range = NSRange(message.startIndex..<message.endIndex, in: message)
+      guard let match = regex.firstMatch(in: message, options: [], range: range),
+            match.numberOfRanges > 1,
+            let codeRange = Range(match.range(at: 1), in: message)
+      else {
+        continue
+      }
+      if let code = Int(message[codeRange]) {
+        return code
+      }
+    }
+    return nil
+  }
+}

package/ios/SpotifyError.swift

@@ -0,0 +1,82 @@
+import ExpoModulesCore
+import Foundation
+
+/// Public, structured errors thrown by the auth coordinator. Each case carries
+/// the JS-facing error code in `code`, mirroring the Android `CodedException`
+/// taxonomy. Raw `NSError`s are turned into these by
+/// `SpotifyAuthErrorMapping.classify(_:context:)`.
+enum SpotifyError: Error {
+  case invalidConfiguration(String)
+  case authInProgress
+  case userCancelled
+  case spotifyNotInstalled
+  case networkError(message: String, cause: Error)
+  case tokenSwapFailed(status: Int?, message: String, cause: Error)
+  case tokenSwapParseError(message: String, cause: Error)
+  case authError(message: String, cause: Error)
+  case underlying(message: String, cause: Error)
+
+  var code: String {
+    switch self {
+    case .invalidConfiguration: return "INVALID_CONFIG"
+    case .authInProgress:       return "AUTH_IN_PROGRESS"
+    case .userCancelled:        return "USER_CANCELLED"
+    case .spotifyNotInstalled:  return "SPOTIFY_NOT_INSTALLED"
+    case .networkError:         return "NETWORK_ERROR"
+    case .tokenSwapFailed:      return "TOKEN_SWAP_FAILED"
+    case .tokenSwapParseError:  return "TOKEN_SWAP_PARSE_ERROR"
+    case .authError:            return "AUTH_ERROR"
+    case .underlying:           return "UNKNOWN"
+    }
+  }
+
+  var message: String {
+    switch self {
+    case .invalidConfiguration(let m):     return m
+    case .authInProgress:                  return "Another authentication request is already in progress"
+    case .userCancelled:                   return "Authentication was cancelled by the user"
+    case .spotifyNotInstalled:             return "The Spotify app is not installed on this device"
+    case .networkError(let message, _):    return message
+    case .tokenSwapFailed(_, let message, _): return message
+    case .tokenSwapParseError(let message, _): return message
+    case .authError(let message, _):       return message
+    case .underlying(let message, _):      return message
+    }
+  }
+
+  /// The original error that caused this failure, if any. Surfaced as the
+  /// JS-facing exception's `cause` so debugging / Sentry breadcrumbs keep the
+  /// full chain rather than collapsing into "undefined reason".
+  var underlyingCause: Error? {
+    switch self {
+    case .networkError(_, let cause): return cause
+    case .tokenSwapFailed(_, _, let cause): return cause
+    case .tokenSwapParseError(_, let cause): return cause
+    case .authError(_, let cause): return cause
+    case .underlying(_, let cause): return cause
+    default:                        return nil
+    }
+  }
+}
+
+/// `Exception` subclass that projects a `SpotifyError`'s `code` and `message`
+/// through `expo-modules-core`'s exception bridge so JS receives the structured
+/// code and a meaningful reason — not the default "undefined reason" placeholder.
+///
+/// Without this wrapper an `AsyncFunction` rejection collapses to
+/// `FunctionCallException` → `cause.reason = "undefined reason"` because the
+/// previously-used `GenericException<String>` does not override `reason`.
+final class SpotifyAuthException: Exception, @unchecked Sendable {
+  private let spotifyCode: String
+  private let spotifyMessage: String
+
+  init(_ error: SpotifyError, file: String = #fileID, line: UInt = #line, function: String = #function) {
+    self.spotifyCode = error.code
+    self.spotifyMessage = error.message
+    super.init(file: file, line: line, function: function)
+    self.cause = error.underlyingCause
+  }
+
+  override var code: String { spotifyCode }
+  override var reason: String { spotifyMessage }
+}

package/ios/SpotifyTokenRefreshClient.swift

@@ -5,14 +5,16 @@ enum SpotifyRefreshError: Error {
   case invalidURL(String)
   case network(Error)
   case http(status: Int, body: String?)
+  case refreshTokenExpired
   case parse(String)
 
   var code: String {
     switch self {
-    case .invalidURL:  return "INVALID_CONFIG"
-    case .network:     return "NETWORK_ERROR"
-    case .http:        return "TOKEN_SWAP_FAILED"
-    case .parse:       return "TOKEN_SWAP_PARSE_ERROR"
+    case .invalidURL:          return "INVALID_CONFIG"
+    case .network:             return "NETWORK_ERROR"
+    case .http:                return "TOKEN_SWAP_FAILED"
+    case .refreshTokenExpired: return "REFRESH_TOKEN_EXPIRED"
+    case .parse:               return "TOKEN_SWAP_PARSE_ERROR"
     }
   }
 
@@ -25,6 +27,8 @@ enum SpotifyRefreshError: Error {
     case .http(let status, let body):
       let trimmed = body.map { String($0.prefix(512)) } ?? ""
       return "Token refresh server returned HTTP \(status)\(trimmed.isEmpty ? "" : ": \(trimmed)")"
+    case .refreshTokenExpired:
+      return "The refresh token is no longer valid (expired or revoked). The user must sign in again."
     case .parse(let m):
       return m
     }
@@ -106,6 +110,13 @@ struct SpotifyTokenRefreshClient {
     }
     guard (200..<300).contains(http.statusCode) else {
       let body = String(data: data, encoding: .utf8)
+      // Spotify returns `invalid_grant` (HTTP 400) when the refresh token has
+      // expired or been revoked — the user must re-authenticate. Surface this
+      // as a dedicated code rather than a generic token-swap failure so callers
+      // can branch to sign-in without inspecting the message string.
+      if let body, body.range(of: "invalid_grant", options: .caseInsensitive) != nil {
+        throw SpotifyRefreshError.refreshTokenExpired
+      }
       throw SpotifyRefreshError.http(status: http.statusCode, body: body)
     }
 

package/package.json

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