@wwdrew/expo-spotify-sdk 2.2.3 → 2.3.1

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()`:
@@ -428,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.3" // x-release-please-version
+private const val SDK_VERSION = "2.3.1" // 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"

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

@@ -73,7 +73,7 @@ class SpotifyTokenSwapClient(
       .header("User-Agent", userAgent)
       .post(body)
       .build()
-    val json = executeJson(request)
+    val json = executeJson(request, invalidGrantIsExpiredToken = true)
     return parseSessionPayload(
       json,
       fallbackScopes = previousScopes,
@@ -81,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) {
@@ -90,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()) {
@@ -103,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":"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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  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.3" // x-release-please-version
+private let SDK_VERSION = "2.3.1" // 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/NSError+SafeLocalizedDescription.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+extension NSError {
+  /// `NSError.localizedDescription` force-bridges `userInfo[NSLocalizedDescriptionKey]`
+  /// to `String`. When that value is a non-`String` object (Spotify's SDK can deliver an
+  /// empty `__NSDictionary0`), the bridge sends `-length` to a dictionary and aborts.
+  var safeLocalizedDescription: String {
+    guard let value = userInfo[NSLocalizedDescriptionKey] else {
+      return localizedDescription
+    }
+    return (value as? String) ?? ""
+  }
+
+  /// Same force-bridge hazard as `localizedDescription`, but for
+  /// `NSLocalizedFailureReasonErrorKey`.
+  var safeLocalizedFailureReason: String? {
+    guard let value = userInfo[NSLocalizedFailureReasonErrorKey] else {
+      return localizedFailureReason
+    }
+    return value as? String
+  }
+}
+
+extension Error {
+  /// Summary for logging that avoids `String(describing:)` / `localizedDescription`
+  /// force-bridges on poisoned `userInfo` values.
+  var safeLogSummary: String {
+    let nsError = self as NSError
+    let description = nsError.safeLocalizedDescription
+    if description.isEmpty {
+      return "\(nsError.domain) code \(nsError.code)"
+    }
+    return "\(nsError.domain) code \(nsError.code): \(description)"
+  }
+}
+
+func safeLogSummary(for error: (any Error)?) -> String {
+  guard let error else { return "nil" }
+  return error.safeLogSummary
+}

package/ios/SpotifyAppRemoteConnection.swift

@@ -210,12 +210,12 @@ final class SpotifyAppRemoteDelegateBridge: NSObject, SPTAppRemoteDelegate {
   }
 
   func appRemote(_ appRemote: SPTAppRemote, didFailConnectionAttemptWithError error: (any Error)?) {
-    NSLog("[ExpoSpotifySDK] AppRemote: connection failed — %@", String(describing: error))
+    NSLog("[ExpoSpotifySDK] AppRemote: connection failed — %@", safeLogSummary(for: error))
     Task { await coordinator?.didFailToConnect(error: error) }
   }
 
   func appRemote(_ appRemote: SPTAppRemote, didDisconnectWithError error: (any Error)?) {
-    NSLog("[ExpoSpotifySDK] AppRemote: disconnected — %@", String(describing: error))
+    NSLog("[ExpoSpotifySDK] AppRemote: disconnected — %@", safeLogSummary(for: error))
     Task { await coordinator?.didDisconnect(error: error) }
   }
 }

package/ios/SpotifyAppRemoteCoordinator.swift

@@ -421,7 +421,7 @@ actor SpotifyAppRemoteCoordinator {
 
   func describeNSError(_ error: NSError) -> String {
     var parts: [String] = ["\(error.domain) code \(error.code)"]
-    let desc = error.localizedDescription
+    let desc = error.safeLocalizedDescription
     if !desc.isEmpty { parts.append("\"\(desc)\"") }
     if let underlying = error.userInfo[NSUnderlyingErrorKey] as? NSError {
       parts.append("→ \(describeNSError(underlying))")

package/ios/SpotifyAppRemoteErrorMapping.swift

@@ -30,71 +30,75 @@ enum SpotifyAppRemoteErrorMapping {
   }
 
   static func mapPlayerError(_ error: NSError, callsite: String) -> NativePlayerError {
+    let desc = error.safeLocalizedDescription
     guard isSPTError(error) else {
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
     if isConnectionTerminated(error) {
       return .connectionLost(connectionLostMessage(callsite: callsite))
     }
     if isInvalidArguments(error) {
-      let desc = error.localizedDescription.lowercased()
-      if desc.contains("uri") {
-        return .invalidURI("\(callsite): \(error.localizedDescription)")
+      let lower = desc.lowercased()
+      if lower.contains("uri") {
+        return .invalidURI("\(callsite): \(desc)")
       }
-      return .invalidParameter(error.localizedDescription)
+      return .invalidParameter(desc)
     }
     if isRequestFailed(error) {
-      let desc = error.localizedDescription.lowercased()
-      if desc.contains("premium") {
+      let lower = desc.lowercased()
+      if lower.contains("premium") {
         return .premiumRequired("\(callsite): Spotify Premium is required for on-demand playback")
       }
-      if containsRestriction(error.localizedDescription) {
-        return .operationNotAllowed("\(callsite): \(error.localizedDescription)")
+      if containsRestriction(desc) {
+        return .operationNotAllowed("\(callsite): \(desc)")
       }
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
-    return .unknown(error.localizedDescription)
+    return .unknown(desc)
   }
 
   static func mapUserError(_ error: NSError, callsite: String) -> NativeUserError {
+    let desc = error.safeLocalizedDescription
     guard isSPTError(error) else {
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
     if isConnectionTerminated(error) {
       return .connectionLost(connectionLostMessage(callsite: callsite))
     }
     if isInvalidArguments(error) {
-      return .invalidURI("\(callsite): \(error.localizedDescription)")
+      return .invalidURI("\(callsite): \(desc)")
     }
     if isRequestFailed(error) {
-      if containsRestriction(error.localizedDescription) {
-        return .operationNotAllowed("\(callsite): \(error.localizedDescription)")
+      if containsRestriction(desc) {
+        return .operationNotAllowed("\(callsite): \(desc)")
       }
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
-    return .unknown(error.localizedDescription)
+    return .unknown(desc)
   }
 
   static func mapContentError(_ error: NSError, callsite: String) -> NativeContentError {
+    let desc = error.safeLocalizedDescription
     guard isSPTError(error) else {
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
     if isConnectionTerminated(error) {
       return .connectionLost(connectionLostMessage(callsite: callsite))
     }
     if isRequestFailed(error) {
-      let desc = error.localizedDescription.lowercased()
-      if desc.contains("not supported") || desc.contains("unsupported") {
+      let lower = desc.lowercased()
+      if lower.contains("not supported") || lower.contains("unsupported") {
         return .contentAPIUnavailable("\(callsite): content API is unavailable on this Spotify app version")
       }
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
-    return .unknown(error.localizedDescription)
+    return .unknown(desc)
   }
 
   static func mapImagesError(_ error: NSError, callsite: String) -> NativeImagesError {
+    let desc = error.safeLocalizedDescription
     guard isSPTError(error) else {
-      return .unknown(error.localizedDescription)
+      return .unknown(desc)
     }
     if isConnectionTerminated(error) {
       return .notConnected(connectionLostMessage(callsite: callsite))
@@ -105,6 +109,6 @@ enum SpotifyAppRemoteErrorMapping {
     if isRequestFailed(error) {
       return .imageLoadFailed("\(callsite): Spotify rejected image request")
     }
-    return .unknown(error.localizedDescription)
+    return .unknown(desc)
   }
 }