@wwdrew/expo-spotify-sdk 2.0.0 → 2.2.0

package/README.md

@@ -8,32 +8,55 @@ An Expo module that wraps the native [Spotify iOS SDK](https://github.com/spotif
 
 **Why this exists:** Spotify ships native SDKs for iOS and Android that enable authentication via the installed Spotify app (no browser redirect, better UX) but there is no maintained Expo module for them. This library fills that gap.
 
+## Table of contents
+
+- [Platform support](#platform-support)
+- [Versioning and Expo SDK lanes](#versioning-and-expo-sdk-lanes)
+- [Public API (Auth + App Remote)](#public-api-auth--app-remote)
+- [Quick start (Expo)](#quick-start-expo)
+- [Installation in bare React Native](#installation-in-bare-react-native)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Spotify Premium and App Remote](#spotify-premium-and-app-remote)
+- [Migration from v0.x](#migration-from-v0x)
+- [Documentation](#documentation)
+- [Troubleshooting](#troubleshooting)
+- [Related docs](#related-docs)
+- [Acknowledgements](#acknowledgements)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Platform support
 
 **iOS and Android only.** This module will not support Expo Web or any browser target — there is no web implementation and none is planned.
 
-| Feature | iOS | Android |
-| --- | --- | --- |
-| `Auth.*` | ✅ | ✅ |
-| `AppRemote.*` | ✅ | ✅ |
-| `Player.*` | ✅ | ✅ |
-| `User.*` | ✅ | ✅ |
-| `Content.*` | ✅ | ✅ |
-| `Images.*` | ✅ | ✅ |
+| Feature       | iOS | Android |
+| ------------- | --- | ------- |
+| `Auth.*`      | ✅  | ✅      |
+| `AppRemote.*` | ✅  | ✅      |
+| `Player.*`    | ✅  | ✅      |
+| `User.*`      | ✅  | ✅      |
+| `Content.*`   | ✅  | ✅      |
+| `Images.*`    | ✅  | ✅      |
 
 ## Versioning and Expo SDK lanes
 
 Install the major that matches your Expo SDK:
 
-| npm version | Expo SDK | iOS minimum | Branch |
-| --- | --- | --- | --- |
-| **`1.x`** | 55 | 15.1 | `v1` (long-lived maintenance) |
-| **`2.x`** | 56+ | 16.4 | `main` |
+| npm version | Expo SDK | iOS minimum | Branch                        |
+| ----------- | -------- | ----------- | ----------------------------- |
+| **`1.x`**   | 55       | 15.1        | `v1` (long-lived maintenance) |
+| **`2.x`**   | 56+      | 16.4        | `main`                        |
 
 Both lanes ship the same public API (Auth + App Remote namespaces and hooks). The major version signals **runtime lane**, not a different feature set. See [ADR-0005](./docs/adr/0005-sdk-lane-versioning.md).
 
 The current `main` branch targets **Expo SDK 56** and releases as **`2.x`**. For Expo SDK 55, install **`1.x`** from the `v1` branch ([ADR-0005](./docs/adr/0005-sdk-lane-versioning.md)).
 
+Auth payload note by lane:
+
+- **`2.x` (`main`)**: Android token swap/refresh requests are normalized to match iOS (`code` for swap, `refresh_token` for refresh).
+- **`1.x` (`v1`)**: Android keeps the legacy payload shape that includes additional form fields for compatibility with existing backends.
+
 ## Public API (Auth + App Remote)
 
 ```ts
@@ -56,7 +79,7 @@ import {
 } from "@wwdrew/expo-spotify-sdk";
 ```
 
-Top-level v0-style functions (`authenticateAsync`, `isAvailable`, etc.) are still exported for backward compatibility but are deprecated — see [Migration from v0.x](#migration-from-v0x).
+Top-level v0-style functions were removed in **`2.x`**. If you still use them, stay on **`1.x`** or migrate — see [Migration from v0.x](#migration-from-v0x).
 
 **Not wrapped:** [Spotify Web API](https://developer.spotify.com/documentation/web-api) (`api.spotify.com`). Use the access token from `Auth.authenticate()` and call REST yourself. See [CONTEXT.md](./CONTEXT.md) for terminology.
 
@@ -67,6 +90,7 @@ Top-level v0-style functions (`authenticateAsync`, `isAvailable`, etc.) are stil
 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
@@ -75,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.
@@ -289,7 +327,11 @@ Avoid reconnect loops by gating on connection state and attempting at most once
 
 ```ts
 import { useEffect, useRef } from "react";
-import { AppRemote, useConnectionState, useSession } from "@wwdrew/expo-spotify-sdk";
+import {
+  AppRemote,
+  useConnectionState,
+  useSession,
+} from "@wwdrew/expo-spotify-sdk";
 
 /**
  * Connect when a session exists and App Remote is disconnected.
@@ -313,24 +355,37 @@ 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
 
-| Concern | Auth (`Auth.*`) | App Remote (`AppRemote.*`, `Player.*`, …) |
-| --- | --- | --- |
-| Spotify app installed | Recommended (native UX) | **Required** |
-| Spotify app running | No | **Required** — connect talks to the running Spotify process over IPC |
-| Spotify Premium | No | **Required** for reliable on-demand playback and rich player state (track name, transport, browse) |
-| Free account | Auth works | `Player.play()` may fail with `PREMIUM_REQUIRED`; `User.getCapabilities().canPlayOnDemand` is `false` |
+| Concern               | Auth (`Auth.*`)         | App Remote (`AppRemote.*`, `Player.*`, …)                                                             |
+| --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| Spotify app installed | Recommended (native UX) | **Required**                                                                                          |
+| Spotify app running   | No                      | **Required** — connect talks to the running Spotify process over IPC                                  |
+| Spotify Premium       | No                      | **Required** for reliable on-demand playback and rich player state (track name, transport, browse)    |
+| Free account          | Auth works              | `Player.play()` may fail with `PREMIUM_REQUIRED`; `User.getCapabilities().canPlayOnDemand` is `false` |
 
 **This library does not play audio.** It remote-controls the official Spotify app. On Android especially, Free accounts often see empty or incomplete now-playing metadata even when connected.
 
 ## Migration from v0.x
 
-v0.x top-level functions remain exported but are deprecated (scheduled for removal in a future major).
+**Removed in `2.x`.** The flat top-level functions (`authenticateAsync`, `isAvailable`, `refreshSessionAsync`, `cancelPendingAuthAsync`, `addSessionChangeListener`) and legacy type aliases (`SpotifyConfig`, `SpotifyErrorCode`) are no longer exported on the **`2.x`** lane.
 
-| v0.x | v1 |
+| v0.x | v2 |
 | --- | --- |
 | `isAvailable()` | `Auth.isAvailable()` |
 | `authenticateAsync(config)` | `Auth.authenticate(config)` |
@@ -340,329 +395,20 @@ v0.x top-level functions remain exported but are deprecated (scheduled for remov
 | `SpotifyError` (auth throws) | `AuthError` (or `instanceof SpotifyError` as catch-all) |
 | `SpotifyErrorCode` | `AuthErrorCode` |
 
-`SpotifySession`, `SpotifyScope`, and config shapes are unchanged. For auth-specific `e.code` narrowing, use `instanceof AuthError` instead of `instanceof SpotifyError`.
-
-## API reference
-
-### `Auth`
-
-#### `Auth.isAvailable(): boolean`
-
-Returns `true` if the Spotify app is installed. Does not throw (not available on unsupported platforms).
-
-#### `Auth.authenticate(config): Promise<SpotifySession>`
-
-Starts OAuth via the installed Spotify app (or web fallback). Throws [`AuthError`](#autherror) on failure.
-
-| Field | Type | Required | Description |
-| --- | --- | --- | --- |
-| `scopes` | `SpotifyScope[]` | ✅ | At least one scope. Include `app-remote-control` for App Remote. |
-| `tokenSwapURL` | `string` | — | Code flow + server swap (recommended). Required on Android for a `refreshToken`. |
-| `tokenRefreshURL` | `string` | — | Refresh endpoint for iOS SDK and `Auth.refresh()`. |
-| `showDialog` | `boolean` | — | Force the consent screen. Default `false`. |
-
-| Return field | Type | Description |
-| --- | --- | --- |
-| `accessToken` | `string` | Bearer token for Web API and `AppRemote.connect()`. |
-| `refreshToken` | `string \| null` | `null` on Android without `tokenSwapURL`. |
-| `expirationDate` | `number` | Expiry as Unix epoch **milliseconds**. |
-| `scopes` | `SpotifyScope[]` | Granted scopes (requested-only on Android TOKEN flow). |
+Need the deprecated shims temporarily? Pin **`1.x`**: `npm install @wwdrew/expo-spotify-sdk@1`.
 
-#### `Auth.cancelPending(): Promise<void>`
-
-Cancels an in-flight `Auth.authenticate()`. On iOS, call before retrying if you see `AUTH_IN_PROGRESS` after a dropped redirect. No-op on Android.
-
-```ts
-await Auth.cancelPending();
-const session = await Auth.authenticate({ scopes: ["streaming"] });
-```
-
-A cancelled call rejects with `AuthError` `code: "USER_CANCELLED"`.
-
-#### `Auth.refresh(config): Promise<SpotifySession>`
-
-Exchanges a refresh token via your refresh server. Pass through `scopes` from the previous session when the refresh response omits `scope`.
-
-```ts
-const refreshed = await Auth.refresh({
-  refreshToken: previous.refreshToken!,
-  tokenRefreshURL: "https://your-server.example.com/refresh",
-  scopes: previous.scopes,
-});
-```
-
-#### `Auth.addListener("sessionChange", listener): Subscription`
-
-Central place to persist tokens. Fires for every `authenticate` / `refresh` — including calls you did not `await`.
-
-| `type` | Payload | When |
-| --- | --- | --- |
-| `"didInitiate"` | `{ session }` | `Auth.authenticate()` succeeded |
-| `"didRenew"` | `{ session }` | `Auth.refresh()` succeeded |
-| `"didFail"` | `{ error: { code, message } }` | Either call failed |
-
-#### `AuthError`
-
-```ts
-import { Auth, AuthError } from "@wwdrew/expo-spotify-sdk";
-
-try {
-  await Auth.authenticate({ scopes: ["streaming"] });
-} catch (e) {
-  if (e instanceof AuthError) {
-    switch (e.code) {
-      case "USER_CANCELLED":
-      case "AUTH_IN_PROGRESS":
-        return;
-      case "INVALID_CONFIG":
-      case "NETWORK_ERROR":
-      case "TOKEN_SWAP_FAILED":
-      case "TOKEN_SWAP_PARSE_ERROR":
-      case "SPOTIFY_NOT_INSTALLED":
-      case "AUTH_ERROR":
-      case "UNKNOWN":
-        reportError(e);
-    }
-  }
-}
-```
-
-`e.message` is the native reason string. On iOS `UNKNOWN` auth failures, the message includes the full `NSError` chain (e.g. `NSURLErrorDomain` to your `tokenSwapURL`). `e.cause` retains the original error for logging.
-
-### `AppRemote`
+`SpotifySession`, `SpotifyScope`, and config shapes are unchanged. For auth-specific `e.code` narrowing, use `instanceof AuthError` instead of `instanceof SpotifyError`.
 
-Connects to the **running** Spotify app. All `Player`, `User`, `Content`, and `Images` calls require an active connection.
+## Documentation
 
-| Method | Description |
+| Guide | Contents |
 | --- | --- |
-| `connect(accessToken)` | Open IPC to Spotify. Resolves when connected. |
-| `disconnect()` | Tear down connection. |
-| `isConnected()` | Synchronous snapshot. |
-| `getConnectionState()` | `"disconnected"` \| `"connecting"` \| `"connected"`. |
-| `addListener("connectionStateChange", cb)` | State transitions. |
-| `addListener("connectionError", cb)` | Failures and drops (`AppRemoteError` codes). |
-
-**Platform notes:**
-
-- **iOS:** pass the access token from `Auth.authenticate()`. If connect fails with `CONNECTION_FAILED` / `Connection refused` (`NSPOSIXErrorDomain` 61), bring Spotify to the foreground and retry — backgrounded Spotify often has no transport listener yet.
-- **Android:** `accessToken` is accepted for API parity; the SDK uses the session cached in the Spotify app from your prior `Auth.authenticate()` call.
-
-Calling `connect()` while already connected is a no-op.
-
-### `Player`
-
-- `Player.play(uri)`
-- `Player.pause()`
-- `Player.resume()`
-- `Player.skipNext()`
-- `Player.skipPrevious()`
-- `Player.seekTo(positionMs)`
-- `Player.setShuffle(enabled)`
-- `Player.setRepeatMode(mode)`
-- `Player.setPodcastPlaybackSpeed(speed)`
-- `Player.queue(uri)`
-- `Player.getPlayerState()`
-- `Player.getCrossfadeState()`
-- `Player.addListener("playerStateChange", cb)`
-
-### `User`
-
-- `User.getCapabilities()`
-- `User.getLibraryState(uri)`
-- `User.addToLibrary(uri)`
-- `User.removeFromLibrary(uri)`
-- `User.addListener("capabilitiesChange", cb)`
-- `User.addLibraryStateListener(uri, cb)`
-
-### `Content`
-
-- `Content.getRecommendedContentItems(type)`
-- `Content.getChildren(item)`
-
-### `Images`
-
-- `Images.load(item, size)`
-
-### Hooks
-
-Built on `useSyncExternalStore` over the native event streams. Subscribe in any component; no manual `addListener` cleanup required.
-
-- `useSession()` — latest `SpotifySession` from auth events (or `null`)
-- `useConnectionState()` — `disconnected` \| `connecting` \| `connected`
-- `usePlayerState()` — full player snapshot
-- `useCurrentTrack()` / `useIsPlaying()` / `usePlaybackPosition()` — derived from player state
-- `useCapabilities()` — `canPlayOnDemand` and related flags
-- `useLibraryState(uri)` — save state for one URI
-
-## Error codes by namespace
-
-Every rejection is an instance of a namespace-specific subclass (`AuthError`, `AppRemoteError`, …) extending the abstract `SpotifyError` base. Catch with `instanceof` for typed `code` narrowing.
-
-### `AuthErrorCode`
-
-| Code | When | What to do |
-| --- | --- | --- |
-| `USER_CANCELLED` | User closed auth or `Auth.cancelPending()` ran | Benign — no action |
-| `AUTH_IN_PROGRESS` | Concurrent `Auth.authenticate()` or iOS stuck pending auth | `await Auth.cancelPending()` then retry |
-| `INVALID_CONFIG` | Missing `clientID`, empty `scopes`, or bad plugin setup | Fix config plugin / `app.config`; run `expo prebuild` |
-| `NETWORK_ERROR` | Device cannot reach `tokenSwapURL` / `tokenRefreshURL` | Check dev server URL, HTTPS, device network |
-| `TOKEN_SWAP_FAILED` | Swap server returned non-2xx | Fix server; read status + body in `e.message` |
-| `TOKEN_SWAP_PARSE_ERROR` | Swap response was not valid token JSON | Fix server response shape |
-| `SPOTIFY_NOT_INSTALLED` | Spotify app not found (rare — web fallback may still run) | Prompt install or use web auth |
-| `AUTH_ERROR` | Spotify rejected the authorization | Check Dashboard redirect URI, scopes, test users |
-| `UNKNOWN` | Unexpected native failure | Read `e.message` / `e.cause`; file an issue with logs |
-
-### `AppRemoteErrorCode`
-
-| Code | When | What to do |
-| --- | --- | --- |
-| `CONNECTION_FAILED` | `connect()` failed (app missing, refused, handshake error) | Open Spotify foreground; re-auth if token stale; retry once |
-| `CONNECTION_LOST` | Connection dropped mid-session | `AppRemote.connect()` again with fresh token |
-| `NOT_CONNECTED` | `AppRemote.*` called before connect completed | `await AppRemote.connect()` first |
-| `UNKNOWN` | Unexpected IPC failure | Read `e.message`; retry connect |
-
-### `PlayerErrorCode`
-
-| Code | When | What to do |
-| --- | --- | --- |
-| `NOT_CONNECTED` | `Player.*` before `AppRemote.connect()` | Connect App Remote first |
-| `CONNECTION_LOST` | Dropped during a player call | Reconnect, then retry |
-| `PREMIUM_REQUIRED` | `canPlayOnDemand === false` (Free tier) | Upgrade account or use shuffle/context play only |
-| `INVALID_URI` | URI failed validation | Use `SpotifyURI.from()` |
-| `INVALID_PARAMETER` | Bad argument (e.g. negative seek) | Fix caller |
-| `OPERATION_NOT_ALLOWED` | Player restriction (can't skip, etc.) | Check `PlayerState` restrictions |
-| `UNKNOWN` | Other native player error | Read `e.message` |
-
-### `UserErrorCode`
-
-| Code | When | What to do |
-| --- | --- | --- |
-| `NOT_CONNECTED` | `User.*` before connect | Connect App Remote first |
-| `CONNECTION_LOST` | Dropped during user API call | Reconnect |
-| `INVALID_URI` | Bad library URI | Use `SpotifyURI.from()` |
-| `OPERATION_NOT_ALLOWED` | Save/remove blocked (tier, region) | Check `LibraryState.canAdd` / capabilities |
-| `UNKNOWN` | Other native user error | Read `e.message` |
-
-### `ContentErrorCode`
-
-| Code | When | What to do |
-| --- | --- | --- |
-| `NOT_CONNECTED` | `Content.*` before connect | Connect App Remote first |
-| `CONNECTION_LOST` | Dropped during browse | Reconnect |
-| `CONTENT_API_UNAVAILABLE` | Spotify app too old for Content API | Update Spotify app |
-| `UNKNOWN` | Other content error | Read `e.message` |
-
-### `ImagesErrorCode`
-
-| Code | When | What to do |
-| --- | --- | --- |
-| `NOT_CONNECTED` | `Images.load()` before connect | Connect App Remote first |
-| `INVALID_URI` | Item has no loadable image | Skip artwork or use placeholder |
-| `IMAGE_LOAD_FAILED` | Spotify or disk write failed | Retry; check free space |
-| `UNKNOWN` | Other image error | Read `e.message` |
-
-## Platform differences (parity)
-
-| Topic | iOS | Android |
-| --- | --- | --- |
-| `AppRemote.connect(accessToken)` | Token passed to `SPTAppRemote` | Token accepted for API parity; SDK uses session cached in Spotify app from prior auth |
-| `Auth.cancelPending()` | Clears stuck `SPTSessionManager` state | No-op |
-| Refresh token without swap | Possible (iOS TOKEN flow) | Not available — use `tokenSwapURL` |
-| `session.scopes` without swap | Granted scopes returned | Requested scopes only (not granted list) |
-| Premium / player metadata | Full App Remote when Premium | Free accounts often lack track titles / on-demand play |
-| Content / Images | Requires recent Spotify app | Same |
-
-## Android implicit (TOKEN) flow is not recommended
-
-When `Auth.authenticate()` is called on Android **without** a `tokenSwapURL`, the Spotify Android SDK uses the implicit (TOKEN) flow. This flow has two hard limitations that **will not be fixed** — Spotify has deprecated it:
-
-1. **No `refreshToken`.** The Android SDK does not expose a refresh token for implicit grants. `session.refreshToken` will always be `null`.
-2. **`scopes` reflects what was requested, not what was granted.** The Android SDK does not return the actual granted scope list for TOKEN responses.
-
-The library emits a one-time `console.warn` at runtime when this path is taken.
-
-**The fix:** provide a `tokenSwapURL` to use the Authorization Code flow, which returns a full `refreshToken` and the actual granted `scopes` on both platforms.
-
-See [Spotify's migration guide](https://developer.spotify.com/documentation/android/tutorials/migration-token-code) for context, and the [token swap server section](#token-swap-server) below for a reference implementation.
-
-## Token swap server
-
-The `tokenSwapURL` / `tokenRefreshURL` endpoints must be a server you control — **never** put your Spotify `CLIENT_SECRET` in the app bundle.
-
-### Swap endpoint (`POST {tokenSwapURL}`)
-
-The native module sends a `application/x-www-form-urlencoded` body:
-
-```
-code=<authorization-code>&redirect_uri=<redirect-uri>&client_id=<client-id>
-```
-
-Your server POSTs these to `https://accounts.spotify.com/api/token` with `grant_type=authorization_code` and your `CLIENT_SECRET` in the `Authorization` header, then returns Spotify's response verbatim as `application/json`:
-
-```json
-{
-  "access_token": "BQA...",
-  "token_type": "Bearer",
-  "expires_in": 3600,
-  "refresh_token": "AQA...",
-  "scope": "user-read-email streaming"
-}
-```
-
-### Refresh endpoint (`POST {tokenRefreshURL}`)
-
-The native module sends:
-
-```
-refresh_token=<token>&client_id=<client-id>
-```
-
-Your server POSTs to `https://accounts.spotify.com/api/token` with `grant_type=refresh_token`. Return Spotify's response verbatim. If Spotify rotates the refresh token the response will contain a new `refresh_token`; if not, the field is absent — the library handles both cases correctly.
-
-### Error responses
-
-Return a non-2xx HTTP status with a JSON body for structured error propagation. The library will reject with `TOKEN_SWAP_FAILED` and include the status code and (truncated) response body in `e.message`.
-
-### Reference implementation
-
-The example app uses [Expo Router API routes](https://docs.expo.dev/router/reference/api-routes/) for the swap and refresh endpoints — no separate server process needed.
-
-**Before running the example, you need a Spotify app:**
-
-> **Note (February 2026 onwards):** Spotify now requires the app owner to have an active **Spotify Premium** subscription to use Development Mode apps. Development Mode apps are also limited to **5 test users** — each user must be explicitly added in your Dashboard under **User Management**. See [Spotify's February 2026 migration guide](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide) for details.
-
-1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) and create an app (or use an existing one).
-2. In the app settings, under **APIs used**, enable **Web API** (required for the `/v1/me` profile call).
-3. Under **Redirect URIs**, add `expo-spotify-sdk-example://authenticate` exactly and save.
-4. Under **User Management**, add the Spotify accounts that will test the app (up to 5 in Development Mode).
-
-**Then populate the credentials:**
-
-```sh
-cd example
-cp .env.local.example .env.local
-```
-
-Edit `.env.local` — all three values are required:
-
-```sh
-# From your Spotify app's dashboard page
-SPOTIFY_CLIENT_ID=your_client_id_here
-SPOTIFY_CLIENT_SECRET=your_client_secret_here
-
-# Must match the redirect URI you registered in the Spotify Dashboard
-SPOTIFY_REDIRECT_URI=expo-spotify-sdk-example://authenticate
-```
-
-`SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` are shown on your app's dashboard page. `SPOTIFY_CLIENT_SECRET` is revealed by clicking **View client secret**.
-
-**Then run the app:**
-
-```sh
-npx expo start
-```
-
-The `/swap` and `/refresh` API routes are served by the Expo dev server alongside the app. `Constants.expoConfig.hostUri` auto-detects the correct server URL for any device or simulator — no manual IP configuration needed.
+| [API reference](./docs/api-reference.md) | All namespaces, methods, hooks |
+| [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
 
@@ -678,18 +424,18 @@ Ensure your app's URL scheme is registered in Xcode under **Info → URL Types**
 **`AUTH_IN_PROGRESS`**
 `Auth.authenticate()` was called while a previous call was still pending. Usually a concurrent call — wait for the first to settle.
 
-On iOS this can also be a stuck state when Spotify never redirects back. Call [`Auth.cancelPending()`](#authcancelpending-promisevoid) before retrying.
+On iOS this can also be a stuck state when Spotify never redirects back. Call `Auth.cancelPending()` before retrying.
 
 **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.
 
 **Token swap: `NETWORK_ERROR` / `Could not connect to the server` to `http://127.0.0.1:…/swap`**
-The swap URL must be reachable from the device running your app. During local dev, the Expo dev server must be running and serving API routes. Omit `tokenSwapURL` to test auth without a swap server (iOS TOKEN flow only; see [Android implicit flow](#android-implicit-token-flow-is-not-recommended)).
+The swap URL must be reachable from the device running your app. During local dev, the Expo dev server must be running and serving API routes. Omit `tokenSwapURL` to test auth without a swap server (iOS TOKEN flow only; see [Platform differences](./docs/guides/platform-differences.md)).
 
 **Now playing shows no track title (Android, Free account)**
 App Remote player state is limited for non-Premium users. Check `GET /v1/me` → `product` and `User.getCapabilities().canPlayOnDemand`.
@@ -697,7 +443,9 @@ 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/V1_PLAN.md](./docs/V1_PLAN.md) — implementation plan and release criteria
+- [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`)
 - [docs/RELEASE.md](./docs/RELEASE.md) — Release Please on `main` (`2.x`); maintenance releases from `v1` (`1.x`)
 - [ATTRIBUTION.md](./ATTRIBUTION.md) — third-party SDKs and scope boundaries

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.