@wwdrew/expo-spotify-sdk 0.6.0 → 0.7.0

package/README.md

@@ -194,6 +194,7 @@ Starts a Spotify OAuth flow. If the Spotify app is installed it authenticates na
 | `scopes`          | `SpotifyScope[]` | ✅       | OAuth scopes to request. Must contain at least one entry.                                                                  |
 | `tokenSwapURL`    | `string`         | —        | URL of your token swap server endpoint. Triggers CODE flow (recommended). Required on Android to receive a `refreshToken`. |
 | `tokenRefreshURL` | `string`         | —        | URL of your token refresh server endpoint. Used by iOS SDK natively and by `refreshSessionAsync` on both platforms.        |
+| `showDialog`      | `boolean`        | —        | Force Spotify to show the authorization dialog even when the user already has an active session. Defaults to `false`. Useful during development; avoid in production.        |
 
 **Returns (`SpotifySession`):**
 

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

@@ -94,6 +94,7 @@ class ExpoSpotifySDKModule : Module() {
           redirectUri = manifest.redirectUri,
           responseType = responseType,
           scopes = config.scopes.toTypedArray(),
+          showDialog = config.showDialog,
         )
 
         val response = coordinator.authenticate(authLauncher, input)

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

@@ -33,6 +33,7 @@ class SpotifyAuthorizationContract :
       input.redirectUri,
     )
       .setScopes(input.scopes)
+      .setShowDialog(input.showDialog)
       .build()
     return AuthorizationClient.createLoginActivityIntent(activity, request)
   }

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

@@ -12,6 +12,7 @@ class SpotifyAuthenticateOptions : Record {
   @Field val scopes: List<String> = emptyList()
   @Field val tokenSwapURL: String? = null
   @Field val tokenRefreshURL: String? = null
+  @Field val showDialog: Boolean = false
 }
 
 /**
@@ -60,6 +61,7 @@ data class SpotifyAuthInput(
   val redirectUri: String,
   val responseType: AuthorizationResponse.Type,
   val scopes: Array<String>,
+  val showDialog: Boolean,
 ) : Serializable {
   override fun equals(other: Any?): Boolean {
     if (this === other) return true
@@ -67,7 +69,8 @@ data class SpotifyAuthInput(
     return clientId == other.clientId &&
       redirectUri == other.redirectUri &&
       responseType == other.responseType &&
-      scopes.contentEquals(other.scopes)
+      scopes.contentEquals(other.scopes) &&
+      showDialog == other.showDialog
   }
 
   override fun hashCode(): Int {
@@ -75,6 +78,7 @@ data class SpotifyAuthInput(
     result = 31 * result + redirectUri.hashCode()
     result = 31 * result + responseType.hashCode()
     result = 31 * result + scopes.contentHashCode()
+    result = 31 * result + showDialog.hashCode()
     return result
   }
 }

package/build/ExpoSpotifySDK.types.d.ts

@@ -46,6 +46,14 @@ export interface SpotifyConfig {
      * `refreshSessionAsync` on both platforms.
      */
     tokenRefreshURL?: string;
+    /**
+     * If `true`, forces Spotify to show the authorization dialog even when
+     * the user already has an active session. Defaults to `false`.
+     *
+     * Maps to `SPTSessionManager.alwaysShowAuthorizationDialog` on iOS and
+     * `AuthorizationRequest.Builder.setShowDialog(true)` on Android.
+     */
+    showDialog?: boolean;
 }
 /**
  * Spotify OAuth scope identifiers that are valid through the iOS, Android

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

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

package/build/ExpoSpotifySDK.types.js.map

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

package/ios/ExpoSpotifySDKModule.swift

@@ -28,7 +28,8 @@ public class ExpoSpotifySDKModule: Module {
         let session = try await coordinator.authenticate(
           scopes: scopes,
           tokenSwapURL: config.tokenSwapURL.flatMap(URL.init),
-          tokenRefreshURL: config.tokenRefreshURL.flatMap(URL.init)
+          tokenRefreshURL: config.tokenRefreshURL.flatMap(URL.init),
+          showDialog: config.showDialog
         )
         let map = self.sessionToMap(session)
         self.sendEvent(EVENT_SESSION_CHANGE, ["type": "didInitiate", "session": map])
@@ -99,6 +100,7 @@ struct AuthenticateOptions: Record {
   @Field var scopes: [String] = []
   @Field var tokenSwapURL: String? = nil
   @Field var tokenRefreshURL: String? = nil
+  @Field var showDialog: Bool = false
 }
 
 struct RefreshOptions: Record {

package/ios/SpotifyAuthCoordinator.swift

@@ -78,7 +78,8 @@ actor SpotifyAuthCoordinator {
   func authenticate(
     scopes: SPTScope,
     tokenSwapURL: URL?,
-    tokenRefreshURL: URL?
+    tokenRefreshURL: URL?,
+    showDialog: Bool = false
   ) async throws -> SPTSession {
     guard pending == nil else { throw SpotifyError.authInProgress }
 
@@ -86,6 +87,17 @@ actor SpotifyAuthCoordinator {
     // mutating it here takes effect for the upcoming initiateSession call.
     sptConfiguration.tokenSwapURL = tokenSwapURL
     sptConfiguration.tokenRefreshURL = tokenRefreshURL
+    // alwaysShowAuthorizationDialog is a property on SPTSessionManager, not an
+    // SPTAuthorizationOptions flag (the options enum has no such case).
+    sessionManager.alwaysShowAuthorizationDialog = showDialog
+
+    NSLog(
+      "[ExpoSpotifySDK] initiateSession redirectURL=%@ tokenSwapURL=%@ tokenRefreshURL=%@ showDialog=%d",
+      sptConfiguration.redirectURL.absoluteString,
+      tokenSwapURL?.absoluteString ?? "nil",
+      tokenRefreshURL?.absoluteString ?? "nil",
+      showDialog ? 1 : 0
+    )
 
     return try await withCheckedThrowingContinuation { (cont: CheckedContinuation<SPTSession, Error>) in
       self.pending = cont
@@ -109,15 +121,28 @@ final class SpotifySessionDelegateBridge: NSObject, SPTSessionManagerDelegate {
   weak var coordinator: SpotifyAuthCoordinator?
 
   func sessionManager(manager _: SPTSessionManager, didInitiate session: SPTSession) {
+    NSLog(
+      "[ExpoSpotifySDK] didInitiate accessToken.length=%d refreshToken.length=%d expirationDate=%@ scope=%lu",
+      session.accessToken.count,
+      session.refreshToken.count,
+      session.expirationDate as NSDate,
+      session.scope.rawValue
+    )
     Task { await coordinator?.deliver(.success(session)) }
   }
 
   func sessionManager(manager _: SPTSessionManager, didFailWith error: Error) {
     let mapped: Error = mapSDKError(error)
+    NSLog("[ExpoSpotifySDK] didFailWithError %@", String(describing: error))
     Task { await coordinator?.deliver(.failure(mapped)) }
   }
 
   func sessionManager(manager _: SPTSessionManager, didRenew session: SPTSession) {
+    NSLog(
+      "[ExpoSpotifySDK] didRenew accessToken.length=%d refreshToken.length=%d",
+      session.accessToken.count,
+      session.refreshToken.count
+    )
     Task { await coordinator?.deliver(.success(session)) }
   }
 
@@ -128,6 +153,34 @@ final class SpotifySessionDelegateBridge: NSObject, SPTSessionManagerDelegate {
     if description.contains("cancel") {
       return SpotifyError.userCancelled
     }
-    return SpotifyError.underlying(error)
+    return SpotifyError.underlying(NSError(
+      domain: nsError.domain,
+      code: nsError.code,
+      userInfo: [NSLocalizedDescriptionKey: describeError(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/package.json

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