@wwdrew/expo-spotify-sdk 2.1.0 → 2.2.1

package/README.md

@@ -90,6 +90,7 @@ Top-level v0-style functions were removed in **`2.x`**. If you still use them, s
 npx expo install @wwdrew/expo-spotify-sdk
 
 # Expo SDK 55 only: npx expo install @wwdrew/expo-spotify-sdk@1
+# (or @sdk55 — npm dist-tag for the v1 maintenance lane)
 
 # 2. Add the config plugin to app.config.ts / app.json  (see Configuration below)
 # 3. Regenerate native projects
@@ -98,6 +99,20 @@ npx expo prebuild
 
 For bare React Native (no Expo CLI), see [Installation in bare React Native](#installation-in-bare-react-native).
 
+## Native SDK binaries
+
+| Platform | Distribution |
+| --- | --- |
+| **iOS** | `SpotifyiOS` resolved from Spotify's GitHub via SPM at `pod install` ([ADR-0008](./docs/adr/0008-ios-spotify-sdk-via-spm.md)). Uses React Native's `spm_dependency` (RN 0.75+). Supported Expo SDK lanes: [Platform support](#platform-support). |
+| **Android** | App Remote AAR downloaded from Spotify's GitHub at Gradle build. Auth SDK from Maven Central. |
+
+| You are… | Action |
+| --- | --- |
+| **Using the published npm package** | Network on first native build per platform (`pod install` / Gradle). |
+| **Developing this repo from git** | Same — no manual fetch scripts. |
+
+See [Native SDK distribution](./docs/guides/native-sdk-distribution.md).
+
 ## Installation in bare React Native
 
 This library is an [Expo Module](https://docs.expo.dev/modules/overview/) and therefore requires `expo-modules-core` as a peer. If your project does not use the Expo managed workflow you will need to set this up manually.
@@ -340,7 +355,20 @@ export function useAutoConnectAppRemote(options?: { once?: boolean }) {
 }
 ```
 
-For iOS, if `connect()` fails with `CONNECTION_FAILED`, foreground the Spotify app and retry manually — see [Troubleshooting](#troubleshooting).
+For iOS, if `connect()` fails with `CONNECTION_FAILED`, the Spotify app has likely been suspended in the background — `connect()` can only attach to an already-running Spotify. Instead of asking the user to foreground Spotify and retry manually, call `AppRemote.authorizeAndPlay(accessToken, uri?)`, which wakes Spotify (launching it if needed), starts playback, and then connects:
+
+```ts
+try {
+  await AppRemote.connect(session.accessToken);
+} catch (e) {
+  if (e instanceof AppRemoteError && e.code === "CONNECTION_FAILED") {
+    // Spotify was suspended — wake it, start playing, and connect.
+    await AppRemote.authorizeAndPlay(session.accessToken);
+  }
+}
+```
+
+Note that `authorizeAndPlay()` always starts (or resumes) playback and briefly switches to the Spotify app — see [Troubleshooting](#troubleshooting).
 
 ## Spotify Premium and App Remote
 
@@ -379,6 +407,7 @@ Need the deprecated shims temporarily? Pin **`1.x`**: `npm install @wwdrew/expo-
 | [Error codes](./docs/error-codes.md) | Per-namespace codes with when/what-to-do |
 | [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 |
 | [Token swap server](./docs/guides/token-swap-server.md) | Swap/refresh endpoints + example app setup |
 
 ## Troubleshooting
@@ -400,7 +429,7 @@ On iOS this can also be a stuck state when Spotify never redirects back. Call `A
 **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:
 
-1. **Spotify is not in the foreground** — switch to Spotify, then retry `AppRemote.connect()`.
+1. **Spotify is suspended / not in the foreground** — `connect()` only attaches to a running Spotify. Call `AppRemote.authorizeAndPlay(accessToken, uri?)` to wake it (it launches Spotify, starts playback, and connects), or have the user switch to Spotify and retry `AppRemote.connect()`.
 2. **Connect ran before auth finished** — call `AppRemote.connect()` only after `Auth.authenticate()` resolves.
 3. **Stale access token** — refresh or re-authenticate, then reconnect.
 4. **Retry loop on startup** — avoid calling `connect()` on every render while `connectionState === "disconnected"`; gate on a one-shot flag or user action.
@@ -414,6 +443,7 @@ App Remote player state is limited for non-Premium users. Check `GET /v1/me` →
 ## Related docs
 
 - [CONTEXT.md](./CONTEXT.md) — terminology (Auth SDK vs App Remote vs Web API)
+- [docs/guides/native-sdk-distribution.md](./docs/guides/native-sdk-distribution.md) — how native binaries are fetched and packaged
 - [docs/api-reference.md](./docs/api-reference.md) — method reference
 - [docs/error-codes.md](./docs/error-codes.md) — error code tables
 - [docs/QA_CHECKLIST.md](./docs/QA_CHECKLIST.md) — manual QA before a `2.x` release on `main` (or `1.x` on `v1`)

package/android/build.gradle

@@ -1,4 +1,5 @@
 apply plugin: 'com.android.library'
+apply from: 'spotify-native-sdk.gradle'
 
 group = 'expo.modules.spotifysdk'
 version = '0.5.0'
@@ -49,11 +50,9 @@ repositories {
 dependencies {
   implementation "com.spotify.android:auth:4.0.1"
 
-  // Spotify App Remote SDK — NOT on Maven Central.
-  // Download spotify-app-remote-release-0.8.0.aar from
-  // https://github.com/spotify/android-sdk/releases and place it in android/libs/.
-  // See android/libs/SETUP.md for full instructions.
-  implementation files('libs/spotify-app-remote-release-0.8.0.aar')
+  // Spotify App Remote SDK — NOT on Maven Central; downloaded at build time
+  // (see android/spotify-native-sdk.gradle and ios/spotify-native-sdk-versions.json).
+  implementation files(spotifyAppRemoteAarFile)
   // App Remote is consumed as a local AAR, so transitive deps like Gson must
   // be declared explicitly to avoid NoClassDefFoundError at runtime.
   implementation "com.google.code.gson:gson:2.11.0"

package/android/libs/SETUP.md

@@ -1,29 +1,14 @@
-# Android App Remote SDK setup
+# Android App Remote SDK
 
-The Spotify App Remote SDK for Android is not published to Maven Central and must be
-downloaded manually.
+The Spotify App Remote SDK for Android is **not** on Maven Central. This module
+downloads `spotify-app-remote-release-<version>.aar` from Spotify's GitHub
+releases at Gradle build time (`android/spotify-native-sdk.gradle`).
 
-## Steps
+Version pin: `ios/spotify-native-sdk-versions.json` (`android` section).
 
-1. Go to <https://github.com/spotify/android-sdk/releases>
-2. Download the latest release archive (e.g. `spotify-android-sdk-x.x.x.zip`)
-3. Extract `spotify-app-remote-release-x.x.x.aar` from the archive
-4. Rename it to `spotify-app-remote-release-0.8.0.aar` (or update the version in
-   `android/build.gradle` to match the downloaded version)
-5. Place the `.aar` file in this directory (`android/libs/`)
+The downloaded `.aar` is gitignored under `android/libs/`.
 
-The `flatDir` repository in `android/build.gradle` will pick it up automatically.
+## Bumping the App Remote version
 
-## Why not Maven?
-
-The Spotify Auth SDK (`com.spotify.android:auth`) is on Maven Central, but the App Remote
-SDK is distributed exclusively via GitHub releases. This directory follows the same pattern
-as the iOS side, where `SpotifyiOS.xcframework` is committed directly to `ios/SpotifySDK/`.
-
-## Proguard
-
-`consumer-rules.pro` already keeps the App Remote classes:
-
-```
--keep class com.spotify.android.appremote.** { *; }
-```
+Update `appRemoteVersion`, `appRemoteReleaseTag`, and `appRemoteSha256` in
+`ios/spotify-native-sdk-versions.json`, then ship a new release of this package.

package/android/spotify-native-sdk.gradle

@@ -0,0 +1,116 @@
+// Downloads Spotify App Remote AAR at Gradle build time (pinned in ios/spotify-native-sdk-versions.json).
+def spotifyNativeVersionsFile = file("${projectDir}/../ios/spotify-native-sdk-versions.json")
+if (!spotifyNativeVersionsFile.exists()) {
+  throw new GradleException(
+    "Missing ${spotifyNativeVersionsFile}. Native SDK versions must be pinned in ios/spotify-native-sdk-versions.json."
+  )
+}
+
+def spotifyNative = new groovy.json.JsonSlurper().parse(spotifyNativeVersionsFile)
+def androidSdk = spotifyNative.android
+if (androidSdk == null) {
+  throw new GradleException("ios/spotify-native-sdk-versions.json is missing an \"android\" section.")
+}
+
+def appRemoteVersion = androidSdk.appRemoteVersion as String
+def appRemoteReleaseTag = androidSdk.appRemoteReleaseTag as String
+def appRemoteSha256 = androidSdk.appRemoteSha256 as String
+
+if (!appRemoteVersion || !appRemoteReleaseTag || !appRemoteSha256) {
+  throw new GradleException(
+    "ios/spotify-native-sdk-versions.json android section is missing required fields: " +
+      "appRemoteVersion, appRemoteReleaseTag, appRemoteSha256"
+  )
+}
+
+def libsDir = file("${projectDir}/libs")
+def aarFile = file("${libsDir}/spotify-app-remote-release-${appRemoteVersion}.aar")
+def versionMarker = file("${libsDir}/.version")
+def downloadUrl =
+  "https://github.com/spotify/android-sdk/releases/download/${appRemoteReleaseTag}/spotify-app-remote-release-${appRemoteVersion}.aar"
+
+def sha256File = { File f ->
+  def digest = java.security.MessageDigest.getInstance("SHA-256")
+  f.withInputStream { stream ->
+    def buffer = new byte[8192]
+    int read
+    while ((read = stream.read(buffer)) > 0) {
+      digest.update(buffer, 0, read)
+    }
+  }
+  digest.digest().collect { String.format("%02x", it) }.join("")
+}
+
+def appRemoteAarUpToDate = {
+  if (!aarFile.exists()) {
+    return false
+  }
+  if (!versionMarker.exists() || versionMarker.text.trim() != appRemoteVersion) {
+    return false
+  }
+  sha256File(aarFile) == appRemoteSha256
+}
+
+tasks.register("downloadSpotifyAppRemoteAar") {
+  group = "spotify"
+  description = "Download Spotify App Remote AAR from GitHub releases"
+
+  outputs.file(aarFile)
+  outputs.file(versionMarker)
+
+  onlyIf {
+    !appRemoteAarUpToDate()
+  }
+
+  doLast {
+    libsDir.mkdirs()
+    logger.lifecycle("ExpoSpotifySDK: downloading Spotify App Remote ${appRemoteVersion}")
+
+    def tmp = File.createTempFile("spotify-app-remote", ".aar")
+    try {
+      ant.get(
+        src: downloadUrl,
+        dest: tmp,
+        verbose: true
+      )
+      def actual = sha256File(tmp)
+      if (actual != appRemoteSha256) {
+        throw new GradleException(
+          "Spotify App Remote AAR checksum mismatch\n" +
+            "  expected ${appRemoteSha256}\n" +
+            "  actual   ${actual}"
+        )
+      }
+
+      libsDir.listFiles()?.each { f ->
+        if (f.name.endsWith(".aar") && f.name != aarFile.name) {
+          f.delete()
+        }
+      }
+
+      if (aarFile.exists()) {
+        aarFile.delete()
+      }
+
+      if (!tmp.renameTo(aarFile)) {
+        tmp.withInputStream { input ->
+          aarFile.withOutputStream { output ->
+            output << input
+          }
+        }
+      }
+
+      versionMarker.text = appRemoteVersion
+    } finally {
+      tmp.delete()
+    }
+
+    logger.lifecycle("ExpoSpotifySDK: Spotify App Remote AAR ready at ${aarFile}")
+  }
+}
+
+ext.spotifyAppRemoteAarFile = aarFile
+
+tasks.named("preBuild").configure {
+  dependsOn("downloadSpotifyAppRemoteAar")
+}

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.1.0" // x-release-please-version
+private const val SDK_VERSION = "2.2.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"
@@ -202,6 +202,17 @@ class ExpoSpotifySDKModule : Module() {
       )
     }
 
+    AsyncFunction("appRemoteAuthorizeAndPlay") Coroutine { accessToken: String, uri: String ->
+      val manifest = readManifestConfig()
+      appRemoteCoordinator.authorizeAndPlay(
+        context = context,
+        clientId = manifest.clientId,
+        redirectUri = manifest.redirectUri,
+        accessToken = accessToken,
+        uri = uri,
+      )
+    }
+
     AsyncFunction("appRemoteDisconnect") Coroutine { ->
       appRemoteCoordinator.disconnect()
     }

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

@@ -131,6 +131,38 @@ class SpotifyAppRemoteCoordinator {
     }
   }
 
+  /**
+   * Wakes the Spotify app and starts playback, then ensures an active App
+   * Remote connection — the cross-platform counterpart of iOS
+   * `authorizeAndPlayURI`.
+   *
+   * On Android there is no dedicated "authorize and play" entry point:
+   * [SpotifyAppRemote.connect] already launches/wakes the Spotify service when
+   * it is installed, so this simply connects (if not already connected) and
+   * then issues a play (or resume, for an empty [uri]) command. The resulting
+   * playback keeps Spotify alive, mirroring the iOS behaviour.
+   *
+   * @param uri Spotify URI to play, or empty to resume the last/contextual track.
+   */
+  suspend fun authorizeAndPlay(
+    context: Context,
+    clientId: String,
+    redirectUri: String,
+    accessToken: String,
+    uri: String,
+  ) {
+    if (appRemote?.isConnected != true) {
+      connect(context, clientId, redirectUri, accessToken)
+    }
+    if (uri.isEmpty()) {
+      requireConnected("AppRemote.authorizeAndPlay").playerApi.resume()
+        .awaitVoid("AppRemote.authorizeAndPlay")
+    } else {
+      requireConnected("AppRemote.authorizeAndPlay").playerApi.play(uri)
+        .awaitVoid("AppRemote.authorizeAndPlay")
+    }
+  }
+
   /**
    * Disconnects from the Spotify app. Safe to call when already disconnected.
    */

package/build/app-remote/index.d.ts

@@ -48,6 +48,15 @@ export declare const AppRemote: {
      * Calling `connect()` while already connected is a no-op.
      */
     readonly connect: (accessToken: string) => Promise<void>;
+    /**
+     * Wakes Spotify (launching if suspended), starts or resumes playback, and
+     * connects. Use when {@link connect} may fail because Spotify is not running.
+     * Always foregrounds Spotify and starts audio — see package api-reference.
+     *
+     * @param accessToken Access token from `Auth.authenticate()`.
+     * @param uri Spotify URI to play, or empty (default) to resume last/contextual track.
+     */
+    readonly authorizeAndPlay: (accessToken: string, uri?: string) => Promise<void>;
     /**
      * Disconnects from the Spotify app. Safe to call when already disconnected.
      * Resolves once the disconnection is complete.

package/build/app-remote/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app-remote/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlE,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMzC,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1E,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS;IACpB;;;;;;;;;;;OAWG;oCACkB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;IAM3C;;;OAGG;+BACW,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;OAIG;gCACY,OAAO;IAItB;;;OAGG;uCACmB,OAAO,CAAC,eAAe,CAAC;IAI9C;;;;;;;;;OASG;2BACS,CAAC,SAAS,uBAAuB,GAAG,iBAAiB,SACxD,CAAC,YACE,CAAC,SAAS,uBAAuB,GACvC,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,GAC3C,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,KACxC,iBAAiB;CAUZ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/app-remote/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlE,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAMzC,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1E,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS;IACpB;;;;;;;;;;;OAWG;oCACkB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;IAM3C;;;;;;;OAOG;6CAC2B,MAAM,QAAO,MAAM,KAAQ,OAAO,CAAC,IAAI,CAAC;IAOtE;;;OAGG;+BACW,OAAO,CAAC,IAAI,CAAC;IAI3B;;;;OAIG;gCACY,OAAO;IAItB;;;OAGG;uCACmB,OAAO,CAAC,eAAe,CAAC;IAI9C;;;;;;;;;OASG;2BACS,CAAC,SAAS,uBAAuB,GAAG,iBAAiB,SACxD,CAAC,YACE,CAAC,SAAS,uBAAuB,GACvC,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,GAC3C,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,KACxC,iBAAiB;CAUZ,CAAC"}

package/build/app-remote/index.js

@@ -55,6 +55,17 @@ export const AppRemote = {
     connect(accessToken) {
         return ExpoSpotifySDKModule.appRemoteConnect(accessToken).catch(rethrowAsAppRemoteError);
     },
+    /**
+     * Wakes Spotify (launching if suspended), starts or resumes playback, and
+     * connects. Use when {@link connect} may fail because Spotify is not running.
+     * Always foregrounds Spotify and starts audio — see package api-reference.
+     *
+     * @param accessToken Access token from `Auth.authenticate()`.
+     * @param uri Spotify URI to play, or empty (default) to resume last/contextual track.
+     */
+    authorizeAndPlay(accessToken, uri = "") {
+        return ExpoSpotifySDKModule.appRemoteAuthorizeAndPlay(accessToken, uri).catch(rethrowAsAppRemoteError);
+    },
     /**
      * Disconnects from the Spotify app. Safe to call when already disconnected.
      * Resolves once the disconnection is complete.

package/build/app-remote/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app-remote/index.ts"],"names":[],"mappings":"AAEA,OAAO,oBAAoB,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAA2B,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAoBzC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;IACvD,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,SAAS;IACtB,UAAU,EAAE,IAAI,GAAG,CAAqB;QACtC,mBAAmB;QACnB,iBAAiB;QACjB,eAAe;QACf,SAAS;KACV,CAAC;CACH,CAAC,CAAC;AAEH,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,WAAmB;QACzB,OAAO,oBAAoB,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,KAAK,CAC7D,uBAAuB,CACxB,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,oBAAoB,CAAC,mBAAmB,EAAE,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,WAAW;QACT,OAAO,oBAAoB,CAAC,oBAAoB,EAAE,CAAC;IACrD,CAAC;IAED;;;OAGG;IACH,kBAAkB;QAChB,OAAO,oBAAoB,CAAC,2BAA2B,EAAE,CAAC;IAC5D,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW,CACT,KAAQ,EACR,QAEyC;QAEzC,MAAM,WAAW,GACf,KAAK,KAAK,uBAAuB;YAC/B,CAAC,CAAC,yBAAyB;YAC3B,CAAC,CAAC,mBAAmB,CAAC;QAC1B,OAAO,oBAAoB,CAAC,WAAW,CACrC,WAAW,EACX,QAAoC,CAChB,CAAC;IACzB,CAAC;CACO,CAAC","sourcesContent":["import type { EventSubscription } from \"expo-modules-core\";\n\nimport ExpoSpotifySDKModule from \"../ExpoSpotifySDKModule\";\nimport { AppRemoteError, type AppRemoteErrorCode } from \"./error\";\nimport { createNativeErrorRethrow } from \"../internal/native-errors\";\n\nexport type { AppRemoteErrorCode } from \"./error\";\nexport { AppRemoteError } from \"./error\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Current state of the IPC connection to the Spotify app. */\nexport type ConnectionState = \"disconnected\" | \"connecting\" | \"connected\";\n\n/** Payload of the `connectionStateChange` event. */\nexport interface ConnectionStateChangeEvent {\n  state: ConnectionState;\n}\n\n/** Payload of the `connectionError` event. */\nexport interface ConnectionErrorEvent {\n  code: AppRemoteErrorCode;\n  message: string;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst rethrowAsAppRemoteError = createNativeErrorRethrow({\n  ErrorClass: AppRemoteError,\n  unknownCode: \"UNKNOWN\",\n  validCodes: new Set<AppRemoteErrorCode>([\n    \"CONNECTION_FAILED\",\n    \"CONNECTION_LOST\",\n    \"NOT_CONNECTED\",\n    \"UNKNOWN\",\n  ]),\n});\n\n// ---------------------------------------------------------------------------\n// AppRemote namespace\n// ---------------------------------------------------------------------------\n\n/**\n * Spotify App Remote namespace. Manages the IPC connection to the running\n * Spotify app. All `Player`, `User`, `Content`, and `Images` calls require an\n * active connection established via `AppRemote.connect()`.\n *\n * @example\n * ```ts\n * import { AppRemote } from \"@wwdrew/expo-spotify-sdk\";\n *\n * // Connect using the access token from Auth.authenticate()\n * await AppRemote.connect(session.accessToken);\n *\n * const sub = AppRemote.addListener(\"connectionStateChange\", ({ state }) => {\n *   console.log(\"connection state:\", state);\n * });\n *\n * // later:\n * await AppRemote.disconnect();\n * sub.remove();\n * ```\n */\nexport const AppRemote = {\n  /**\n   * Opens a connection to the running Spotify app using the provided access\n   * token. Resolves when the connection is established; rejects with an\n   * {@link AppRemoteError} if the connection fails.\n   *\n   * **Android note:** The access token is accepted for API parity with iOS but\n   * the Android App Remote SDK does not accept it directly — it uses the\n   * session cached in the Spotify app from your earlier `Auth.authenticate()`\n   * call. Ensure `Auth.authenticate()` has succeeded before calling `connect()`.\n   *\n   * Calling `connect()` while already connected is a no-op.\n   */\n  connect(accessToken: string): Promise<void> {\n    return ExpoSpotifySDKModule.appRemoteConnect(accessToken).catch(\n      rethrowAsAppRemoteError,\n    );\n  },\n\n  /**\n   * Disconnects from the Spotify app. Safe to call when already disconnected.\n   * Resolves once the disconnection is complete.\n   */\n  disconnect(): Promise<void> {\n    return ExpoSpotifySDKModule.appRemoteDisconnect();\n  },\n\n  /**\n   * Returns `true` if currently connected to the Spotify app.\n   * This is a synchronous snapshot — subscribe to `\"connectionStateChange\"`\n   * for reactive updates.\n   */\n  isConnected(): boolean {\n    return ExpoSpotifySDKModule.appRemoteIsConnected();\n  },\n\n  /**\n   * Returns the current {@link ConnectionState} synchronously.\n   * Subscribe to `\"connectionStateChange\"` for reactive updates.\n   */\n  getConnectionState(): Promise<ConnectionState> {\n    return ExpoSpotifySDKModule.appRemoteGetConnectionState();\n  },\n\n  /**\n   * Subscribes to connection lifecycle events.\n   *\n   * | Event | Payload | When |\n   * |---|---|---|\n   * | `\"connectionStateChange\"` | `{ state: ConnectionState }` | State transitions |\n   * | `\"connectionError\"` | `{ code, message }` | Connection failures and drops |\n   *\n   * Returns a `Subscription` — call `.remove()` to unsubscribe.\n   */\n  addListener<E extends \"connectionStateChange\" | \"connectionError\">(\n    event: E,\n    listener: E extends \"connectionStateChange\"\n      ? (event: ConnectionStateChangeEvent) => void\n      : (event: ConnectionErrorEvent) => void,\n  ): EventSubscription {\n    const nativeEvent =\n      event === \"connectionStateChange\"\n        ? \"onConnectionStateChange\"\n        : \"onConnectionError\";\n    return ExpoSpotifySDKModule.addListener(\n      nativeEvent,\n      listener as (event: unknown) => void,\n    ) as EventSubscription;\n  },\n} as const;\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/app-remote/index.ts"],"names":[],"mappings":"AAEA,OAAO,oBAAoB,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAA2B,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAoBzC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;IACvD,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,SAAS;IACtB,UAAU,EAAE,IAAI,GAAG,CAAqB;QACtC,mBAAmB;QACnB,iBAAiB;QACjB,eAAe;QACf,SAAS;KACV,CAAC;CACH,CAAC,CAAC;AAEH,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,WAAmB;QACzB,OAAO,oBAAoB,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,KAAK,CAC7D,uBAAuB,CACxB,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,gBAAgB,CAAC,WAAmB,EAAE,MAAc,EAAE;QACpD,OAAO,oBAAoB,CAAC,yBAAyB,CACnD,WAAW,EACX,GAAG,CACJ,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,oBAAoB,CAAC,mBAAmB,EAAE,CAAC;IACpD,CAAC;IAED;;;;OAIG;IACH,WAAW;QACT,OAAO,oBAAoB,CAAC,oBAAoB,EAAE,CAAC;IACrD,CAAC;IAED;;;OAGG;IACH,kBAAkB;QAChB,OAAO,oBAAoB,CAAC,2BAA2B,EAAE,CAAC;IAC5D,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW,CACT,KAAQ,EACR,QAEyC;QAEzC,MAAM,WAAW,GACf,KAAK,KAAK,uBAAuB;YAC/B,CAAC,CAAC,yBAAyB;YAC3B,CAAC,CAAC,mBAAmB,CAAC;QAC1B,OAAO,oBAAoB,CAAC,WAAW,CACrC,WAAW,EACX,QAAoC,CAChB,CAAC;IACzB,CAAC;CACO,CAAC","sourcesContent":["import type { EventSubscription } from \"expo-modules-core\";\n\nimport ExpoSpotifySDKModule from \"../ExpoSpotifySDKModule\";\nimport { AppRemoteError, type AppRemoteErrorCode } from \"./error\";\nimport { createNativeErrorRethrow } from \"../internal/native-errors\";\n\nexport type { AppRemoteErrorCode } from \"./error\";\nexport { AppRemoteError } from \"./error\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Current state of the IPC connection to the Spotify app. */\nexport type ConnectionState = \"disconnected\" | \"connecting\" | \"connected\";\n\n/** Payload of the `connectionStateChange` event. */\nexport interface ConnectionStateChangeEvent {\n  state: ConnectionState;\n}\n\n/** Payload of the `connectionError` event. */\nexport interface ConnectionErrorEvent {\n  code: AppRemoteErrorCode;\n  message: string;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst rethrowAsAppRemoteError = createNativeErrorRethrow({\n  ErrorClass: AppRemoteError,\n  unknownCode: \"UNKNOWN\",\n  validCodes: new Set<AppRemoteErrorCode>([\n    \"CONNECTION_FAILED\",\n    \"CONNECTION_LOST\",\n    \"NOT_CONNECTED\",\n    \"UNKNOWN\",\n  ]),\n});\n\n// ---------------------------------------------------------------------------\n// AppRemote namespace\n// ---------------------------------------------------------------------------\n\n/**\n * Spotify App Remote namespace. Manages the IPC connection to the running\n * Spotify app. All `Player`, `User`, `Content`, and `Images` calls require an\n * active connection established via `AppRemote.connect()`.\n *\n * @example\n * ```ts\n * import { AppRemote } from \"@wwdrew/expo-spotify-sdk\";\n *\n * // Connect using the access token from Auth.authenticate()\n * await AppRemote.connect(session.accessToken);\n *\n * const sub = AppRemote.addListener(\"connectionStateChange\", ({ state }) => {\n *   console.log(\"connection state:\", state);\n * });\n *\n * // later:\n * await AppRemote.disconnect();\n * sub.remove();\n * ```\n */\nexport const AppRemote = {\n  /**\n   * Opens a connection to the running Spotify app using the provided access\n   * token. Resolves when the connection is established; rejects with an\n   * {@link AppRemoteError} if the connection fails.\n   *\n   * **Android note:** The access token is accepted for API parity with iOS but\n   * the Android App Remote SDK does not accept it directly — it uses the\n   * session cached in the Spotify app from your earlier `Auth.authenticate()`\n   * call. Ensure `Auth.authenticate()` has succeeded before calling `connect()`.\n   *\n   * Calling `connect()` while already connected is a no-op.\n   */\n  connect(accessToken: string): Promise<void> {\n    return ExpoSpotifySDKModule.appRemoteConnect(accessToken).catch(\n      rethrowAsAppRemoteError,\n    );\n  },\n\n  /**\n   * Wakes Spotify (launching if suspended), starts or resumes playback, and\n   * connects. Use when {@link connect} may fail because Spotify is not running.\n   * Always foregrounds Spotify and starts audio — see package api-reference.\n   *\n   * @param accessToken Access token from `Auth.authenticate()`.\n   * @param uri Spotify URI to play, or empty (default) to resume last/contextual track.\n   */\n  authorizeAndPlay(accessToken: string, uri: string = \"\"): Promise<void> {\n    return ExpoSpotifySDKModule.appRemoteAuthorizeAndPlay(\n      accessToken,\n      uri,\n    ).catch(rethrowAsAppRemoteError);\n  },\n\n  /**\n   * Disconnects from the Spotify app. Safe to call when already disconnected.\n   * Resolves once the disconnection is complete.\n   */\n  disconnect(): Promise<void> {\n    return ExpoSpotifySDKModule.appRemoteDisconnect();\n  },\n\n  /**\n   * Returns `true` if currently connected to the Spotify app.\n   * This is a synchronous snapshot — subscribe to `\"connectionStateChange\"`\n   * for reactive updates.\n   */\n  isConnected(): boolean {\n    return ExpoSpotifySDKModule.appRemoteIsConnected();\n  },\n\n  /**\n   * Returns the current {@link ConnectionState} synchronously.\n   * Subscribe to `\"connectionStateChange\"` for reactive updates.\n   */\n  getConnectionState(): Promise<ConnectionState> {\n    return ExpoSpotifySDKModule.appRemoteGetConnectionState();\n  },\n\n  /**\n   * Subscribes to connection lifecycle events.\n   *\n   * | Event | Payload | When |\n   * |---|---|---|\n   * | `\"connectionStateChange\"` | `{ state: ConnectionState }` | State transitions |\n   * | `\"connectionError\"` | `{ code, message }` | Connection failures and drops |\n   *\n   * Returns a `Subscription` — call `.remove()` to unsubscribe.\n   */\n  addListener<E extends \"connectionStateChange\" | \"connectionError\">(\n    event: E,\n    listener: E extends \"connectionStateChange\"\n      ? (event: ConnectionStateChangeEvent) => void\n      : (event: ConnectionErrorEvent) => void,\n  ): EventSubscription {\n    const nativeEvent =\n      event === \"connectionStateChange\"\n        ? \"onConnectionStateChange\"\n        : \"onConnectionError\";\n    return ExpoSpotifySDKModule.addListener(\n      nativeEvent,\n      listener as (event: unknown) => void,\n    ) as EventSubscription;\n  },\n} as const;\n"]}

package/ios/ExpoSpotifyAppDelegate.swift

@@ -1,7 +1,7 @@
 import ExpoModulesCore
 import SpotifyiOS
 
-/// Delivers Spotify auth redirect URLs received via the legacy
+/// Delivers Spotify redirect URLs received via the legacy
 /// `application(_:open:url:)` AppDelegate path.
 public class ExpoSpotifyAppDelegate: ExpoAppDelegateSubscriber {
   public func application(
@@ -9,6 +9,13 @@ public class ExpoSpotifyAppDelegate: ExpoAppDelegateSubscriber {
     open url: URL,
     options: [UIApplication.OpenURLOptionsKey: Any] = [:]
   ) -> Bool {
+    // Both the auth flow (SPTSessionManager) and App Remote's
+    // `authorizeAndPlay()` redirect through the same URL scheme. Offer the URL
+    // to the App Remote coordinator first — it only claims the redirect when an
+    // `authorizeAndPlay()` flow is actually pending — then fall back to auth.
+    if SpotifyAppRemoteCoordinator.shared?.handleAuthorizeRedirect(url) == true {
+      return true
+    }
     return SpotifyAuthCoordinator.shared?.handleOpenURL(url, options: options) ?? false
   }
 }

package/ios/ExpoSpotifySDK.podspec

@@ -1,6 +1,18 @@
 require 'json'
 
+absolute_react_native_path = ''
+if !ENV['REACT_NATIVE_PATH'].nil?
+  absolute_react_native_path = File.expand_path(ENV['REACT_NATIVE_PATH'], Pod::Config.instance.project_root)
+else
+  absolute_react_native_path = File.dirname(`node --print "require.resolve('react-native/package.json')"`)
+end
+
+unless defined?(spm_dependency)
+  require File.join(absolute_react_native_path, "scripts/react_native_pods")
+end
+
 package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+spotify_native = JSON.parse(File.read(File.join(__dir__, 'spotify-native-sdk-versions.json')))
 
 Pod::Spec.new do |s|
   s.name           = 'ExpoSpotifySDK'
@@ -23,6 +35,18 @@ Pod::Spec.new do |s|
   }
 
   s.source_files = "**/*.{h,m,swift}"
-  s.exclude_files = "SpotifySDK/SpotifyiOS.xcframework/**/*.h"
-  s.vendored_frameworks = "SpotifySDK/SpotifyiOS.xcframework"
+
+  ios_sdk = spotify_native['ios']
+  if ios_sdk.nil? ||
+      ios_sdk['spmRepositoryUrl'].to_s.empty? ||
+      ios_sdk['spmVersion'].to_s.empty? ||
+      ios_sdk['spmProduct'].to_s.empty?
+    raise "ios/spotify-native-sdk-versions.json is missing required iOS fields: spmRepositoryUrl, spmVersion, spmProduct"
+  end
+
+  spm_dependency(s,
+    url: ios_sdk['spmRepositoryUrl'],
+    requirement: { kind: 'exactVersion', version: ios_sdk['spmVersion'] },
+    products: [ios_sdk['spmProduct']]
+  )
 end

package/ios/ExpoSpotifySDKModule.swift

@@ -1,7 +1,7 @@
 import ExpoModulesCore
 import SpotifyiOS
 
-private let SDK_VERSION = "2.1.0" // x-release-please-version
+private let SDK_VERSION = "2.2.1" // x-release-please-version
 private let EVENT_SESSION_CHANGE = "onSessionChange"
 private let EVENT_CONNECTION_STATE_CHANGE = "onConnectionStateChange"
 private let EVENT_CONNECTION_ERROR = "onConnectionError"
@@ -138,6 +138,21 @@ public class ExpoSpotifySDKModule: Module {
       }
     }
 
+    AsyncFunction("appRemoteAuthorizeAndPlay") { (accessToken: String, uri: String) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw AppRemoteException(AppRemoteError.connectionFailed(
+          "Missing `ExpoSpotifySDK` configuration in Info.plist."
+        ))
+      }
+      do {
+        try await coordinator.authorizeAndPlay(uri: uri, accessToken: accessToken)
+      } catch let error as AppRemoteError {
+        throw AppRemoteException(error)
+      } catch let error as NativePlayerError {
+        throw PlayerException(error)
+      }
+    }
+
     AsyncFunction("appRemoteDisconnect") { () async -> Void in
       await SpotifyAppRemoteCoordinator.shared?.disconnect()
     }