@wwdrew/expo-spotify-sdk 0.7.1 → 1.0.0

package/README.md

@@ -4,20 +4,61 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/wwdrew/expo-spotify-sdk/ci.yml?label=CI)](https://github.com/wwdrew/expo-spotify-sdk/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/github/license/wwdrew/expo-spotify-sdk)](LICENSE)
 
-An Expo module that wraps the native [Spotify iOS SDK](https://github.com/spotify/ios-sdk) (v5.0.1) and [Spotify Android SDK](https://github.com/spotify/android-sdk) (v4.0.1) to provide OAuth authentication in Expo and React Native apps.
+An Expo module that wraps the native [Spotify iOS SDK](https://github.com/spotify/ios-sdk) (v5.0.1) and [Spotify Android SDK](https://github.com/spotify/android-sdk) (v4.0.1) to provide Spotify Auth + App Remote control in Expo and React Native apps.
 
 **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.
 
 ## Platform support
 
-| Feature                                       | iOS | Android      | Web                 |
-| --------------------------------------------- | --- | ------------ | ------------------- |
-| `isAvailable()`                               | ✅  | ✅           | ✅ (always `false`) |
-| `authenticateAsync` — CODE flow (recommended) | ✅  | ✅           | —                   |
-| `authenticateAsync` — TOKEN flow (implicit)   | ✅  | ⚠️ see below | —                   |
-| `refreshSessionAsync`                         | ✅  | ✅           | —                   |
-| Auth via installed Spotify app                | ✅  | ✅           | —                   |
-| Auth via Spotify web fallback                 | ✅  | ✅           | —                   |
+**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.*` | ✅ | ✅ |
+
+## 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` |
+
+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 55** and releases as **`1.0.0`**. SDK 56 migration is [Phase 7](./docs/V1_PLAN.md#phase-7--migrate-main-to-expo-sdk-56-v200) (`2.0.0` on `main`).
+
+## v1 namespaced API
+
+```ts
+import {
+  Auth,
+  AppRemote,
+  Player,
+  User,
+  Content,
+  Images,
+  SpotifyURI,
+  useSession,
+  useConnectionState,
+  usePlayerState,
+  useCurrentTrack,
+  useIsPlaying,
+  usePlaybackPosition,
+  useCapabilities,
+  useLibraryState,
+} 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).
+
+**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.
 
 ## Quick start (Expo)
 
@@ -137,164 +178,379 @@ The redirect URI registered in your [Spotify Developer Dashboard](https://develo
 
 ## Usage
 
+Typical integration: authenticate, connect App Remote, then read/control playback via hooks.
+
 ```ts
+import { useEffect } from "react";
 import {
-  isAvailable,
-  authenticateAsync,
-  refreshSessionAsync,
-  addSessionChangeListener,
-  SpotifyError,
+  Auth,
+  AppRemote,
+  AuthError,
+  AppRemoteError,
+  useSession,
+  useConnectionState,
+  useCurrentTrack,
+  useIsPlaying,
 } from "@wwdrew/expo-spotify-sdk";
 
-// Check whether the Spotify app is installed
-const spotifyInstalled = isAvailable();
+async function login() {
+  if (!Auth.isAvailable()) {
+    throw new Error("Install the Spotify app to continue");
+  }
 
-// Authenticate
-try {
-  const session = await authenticateAsync({
-    scopes: ["user-read-email", "streaming"],
+  // On iOS, clear a leaked in-flight auth before retrying.
+  await Auth.cancelPending();
+
+  return Auth.authenticate({
+    scopes: ["app-remote-control", "user-read-playback-state", "streaming"],
     tokenSwapURL: "https://your-server.example.com/swap",
     tokenRefreshURL: "https://your-server.example.com/refresh",
   });
+}
 
-  console.log(session.accessToken); // use with Spotify Web API
-  console.log(session.refreshToken); // store securely for later refresh
-  console.log(session.expirationDate); // Unix epoch milliseconds
-  console.log(session.scopes); // granted scopes
-} catch (e) {
-  if (e instanceof SpotifyError) {
-    if (e.code === "USER_CANCELLED") return; // user backed out — benign
-    console.error(`[${e.code}] ${e.message}`);
+async function connectRemote(accessToken: string) {
+  try {
+    await AppRemote.connect(accessToken);
+  } catch (e) {
+    if (e instanceof AppRemoteError && e.code === "CONNECTION_FAILED") {
+      // Spotify's IPC transport is not ready — open Spotify and retry.
+      // See "App Remote connection failed" in Troubleshooting.
+    }
+    throw e;
   }
 }
+
+function NowPlaying() {
+  const session = useSession();
+  const connectionState = useConnectionState();
+  const track = useCurrentTrack();
+  const isPlaying = useIsPlaying();
+
+  useEffect(() => {
+    if (session == null || connectionState !== "disconnected") return;
+    void connectRemote(session.accessToken);
+  }, [session, connectionState]);
+
+  if (connectionState !== "connected") {
+    return null;
+  }
+
+  return (
+    <Text>
+      {track?.name ?? "No track"} · {isPlaying ? "Playing" : "Paused"}
+    </Text>
+  );
+}
 ```
 
-### Refresh a session
+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.
 
-```ts
-import { refreshSessionAsync } from "@wwdrew/expo-spotify-sdk";
+### Check account tier (Web API)
 
-const refreshed = await refreshSessionAsync({
-  refreshToken: storedRefreshToken,
-  tokenRefreshURL: "https://your-server.example.com/refresh",
+App Remote does not expose Premium status. Call Spotify's Web API with the access token from `Auth.authenticate()`:
+
+```ts
+const res = await fetch("https://api.spotify.com/v1/me", {
+  headers: { Authorization: `Bearer ${session.accessToken}` },
 });
+const profile = await res.json();
+const isPremium = profile.product === "premium";
 ```
 
-## API reference
+The [example app](./example) displays this as "Account tier: Premium / Free".
 
-### `isAvailable(): boolean`
+### Auto-connect App Remote
 
-Returns `true` if the Spotify app is installed on the device. Always returns `false` on web. Does not throw.
+Avoid reconnect loops by gating on connection state and attempting at most once per session restore:
 
----
+```ts
+import { useEffect, useRef } from "react";
+import { AppRemote, useConnectionState, useSession } from "@wwdrew/expo-spotify-sdk";
+
+/**
+ * Connect when a session exists and App Remote is disconnected.
+ * Set `once` to true to avoid retry spam after failures (recommended on cold start).
+ */
+export function useAutoConnectAppRemote(options?: { once?: boolean }) {
+  const session = useSession();
+  const connectionState = useConnectionState();
+  const attemptedRef = useRef(false);
+
+  useEffect(() => {
+    const token = session?.accessToken;
+    if (!token || connectionState !== "disconnected") return;
+    if (options?.once && attemptedRef.current) return;
+
+    attemptedRef.current = true;
+    void AppRemote.connect(token).catch(() => {
+      // Surface via AppRemote.addListener("connectionError") or your UI.
+    });
+  }, [session?.accessToken, connectionState, options?.once]);
+}
+```
 
-### `authenticateAsync(config: SpotifyConfig): Promise<SpotifySession>`
+For iOS, if `connect()` fails with `CONNECTION_FAILED`, foreground the Spotify app and retry manually — see [Troubleshooting](#troubleshooting).
 
-Starts a Spotify OAuth flow. If the Spotify app is installed it authenticates natively; otherwise it falls back to the Spotify web login page.
+## Spotify Premium and App Remote
 
-**Throws [`SpotifyError`](#spotifyerror)** on failure.
+| 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` |
 
-**Parameters (`SpotifyConfig`):**
+**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.
 
-| Field             | Type             | Required | Description                                                                                                                |
-| ----------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `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.        |
+## Migration from v0.x
 
-**Returns (`SpotifySession`):**
+v0.x top-level functions remain exported but are deprecated (removed in v2.0.0).
 
-| Field            | Type             | Description                                                                                                                                         |
-| ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `accessToken`    | `string`         | OAuth access token. Use as `Authorization: Bearer <token>` with the Spotify Web API.                                                                |
-| `refreshToken`   | `string \| null` | Refresh token. `null` on Android when no `tokenSwapURL` is provided — see [Android implicit flow](#android-implicit-token-flow-is-not-recommended). |
-| `expirationDate` | `number`         | Token expiry as Unix epoch **milliseconds**.                                                                                                        |
-| `scopes`         | `SpotifyScope[]` | Granted scopes. On Android TOKEN flow, reflects requested scopes (Spotify does not expose granted scopes in the implicit flow).                     |
+| v0.x | v1 |
+| --- | --- |
+| `isAvailable()` | `Auth.isAvailable()` |
+| `authenticateAsync(config)` | `Auth.authenticate(config)` |
+| `refreshSessionAsync(config)` | `Auth.refresh(config)` |
+| `cancelPendingAuthAsync()` | `Auth.cancelPending()` |
+| `addSessionChangeListener(cb)` | `Auth.addListener("sessionChange", cb)` |
+| `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`.
 
-### `refreshSessionAsync(options): Promise<SpotifySession>`
+## API reference
 
-Exchanges a refresh token for a new access token via your token refresh server.
+### `Auth`
 
-**Parameters:**
+#### `Auth.isAvailable(): boolean`
 
-| Field             | Type     | Description                                                 |
-| ----------------- | -------- | ----------------------------------------------------------- |
-| `refreshToken`    | `string` | The refresh token from a previous `authenticateAsync` call. |
-| `tokenRefreshURL` | `string` | URL of your token refresh server endpoint.                  |
+Returns `true` if the Spotify app is installed. Does not throw (not available on unsupported platforms).
 
-**Returns** a fresh `SpotifySession` with an updated `accessToken` and `expirationDate`. If the server rotates the refresh token the new one is returned in `refreshToken`; otherwise the original token is returned so you can continue refreshing.
+#### `Auth.authenticate(config): Promise<SpotifySession>`
 
----
+Starts OAuth via the installed Spotify app (or web fallback). Throws [`AuthError`](#autherror) on failure.
 
-### `addSessionChangeListener(listener): Subscription`
+| 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`. |
 
-Subscribes to session lifecycle events emitted by the native module. Events fire for every `authenticateAsync` and `refreshSessionAsync` call — including ones you didn't directly `await` — making this the right place to persist tokens in a central store.
+| 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). |
 
-Returns a `Subscription` object; call `.remove()` to unsubscribe.
+#### `Auth.cancelPending(): Promise<void>`
 
-```ts
-import { addSessionChangeListener } from "@wwdrew/expo-spotify-sdk";
-
-const sub = addSessionChangeListener((event) => {
-  switch (event.type) {
-    case "didInitiate":
-    case "didRenew":
-      store.setSession(event.session); // { accessToken, refreshToken, expirationDate, scopes }
-      break;
-    case "didFail":
-      console.error(`[${event.error.code}] ${event.error.message}`);
-      break;
-  }
-});
+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.
 
-// When the subscribing component unmounts:
-sub.remove();
+```ts
+await Auth.cancelPending();
+const session = await Auth.authenticate({ scopes: ["streaming"] });
 ```
 
-**Event types (`SpotifySessionChangeEvent`):**
+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,
+});
+```
 
-| `type` | Payload | Fired when |
-|---|---|---|
-| `"didInitiate"` | `{ session: SpotifySession }` | `authenticateAsync` succeeded |
-| `"didRenew"` | `{ session: SpotifySession }` | `refreshSessionAsync` succeeded |
-| `"didFail"` | `{ error: { code, message } }` | Either function rejected |
+#### `Auth.addListener("sessionChange", listener): Subscription`
 
----
+Central place to persist tokens. Fires for every `authenticate` / `refresh` — including calls you did not `await`.
 
-### `SpotifyError`
+| `type` | Payload | When |
+| --- | --- | --- |
+| `"didInitiate"` | `{ session }` | `Auth.authenticate()` succeeded |
+| `"didRenew"` | `{ session }` | `Auth.refresh()` succeeded |
+| `"didFail"` | `{ error: { code, message } }` | Either call failed |
 
-All rejections from `authenticateAsync` and `refreshSessionAsync` are instances of `SpotifyError`:
+#### `AuthError`
 
 ```ts
-import { SpotifyError } from "@wwdrew/expo-spotify-sdk";
+import { Auth, AuthError } from "@wwdrew/expo-spotify-sdk";
 
 try {
-  await authenticateAsync({ scopes: ["streaming"] });
+  await Auth.authenticate({ scopes: ["streaming"] });
 } catch (e) {
-  if (e instanceof SpotifyError) {
+  if (e instanceof AuthError) {
     switch (e.code) {
-      case "USER_CANCELLED": // user closed the auth screen — benign
-      case "AUTH_IN_PROGRESS": // concurrent call — benign
+      case "USER_CANCELLED":
+      case "AUTH_IN_PROGRESS":
         return;
-      case "INVALID_CONFIG": // missing clientID / scopes / tokenSwapURL
-      case "NETWORK_ERROR": // connectivity failure during token swap
-      case "TOKEN_SWAP_FAILED": // swap server returned non-2xx (e.message has status + body)
-      case "TOKEN_SWAP_PARSE_ERROR": // swap server returned invalid JSON
-      case "SPOTIFY_NOT_INSTALLED": // Spotify app not found (rare — most flows fall back to web)
-      case "AUTH_ERROR": // Spotify returned an error (e.message has detail)
-      case "UNKNOWN": // unexpected failure
+      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`
+
+Connects to the **running** Spotify app. All `Player`, `User`, `Content`, and `Images` calls require an active connection.
+
+| Method | Description |
+| --- | --- |
+| `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 `authenticateAsync` 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:
+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.
@@ -389,14 +645,38 @@ The `/swap` and `/refresh` API routes are served by the Expo dev server alongsid
 **`INVALID_CONFIG: Missing meta-data 'spotifyClientId'`**
 Run `expo prebuild` after adding the plugin to your config. The plugin injects the required `AndroidManifest.xml` entries.
 
-**`isAvailable()` returns `false` on Android 11+ release builds**
+**`Auth.isAvailable()` returns `false` on Android 11+ release builds**
 Android 11+ requires a `<queries>` element to inspect other apps' package names. The module ships this in its `AndroidManifest.xml`; make sure you are not merging a custom manifest that removes it.
 
 **iOS: authentication never returns**
 Ensure your app's URL scheme is registered in Xcode under **Info → URL Types** and that it matches the `scheme` in the plugin config. The `expo prebuild` step does this automatically; if you have a bare workflow, check `CFBundleURLSchemes` in `Info.plist`.
 
 **`AUTH_IN_PROGRESS`**
-`authenticateAsync` was called while a previous call was still pending. Wait for the first call to resolve or reject before calling again.
+`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.
+
+**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()`.
+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)).
+
+**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`.
+
+## 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/QA_CHECKLIST.md](./docs/QA_CHECKLIST.md) — manual QA sign-off before `v1.0.0`
+- [docs/RELEASE.md](./docs/RELEASE.md) — tag `v1.0.0` and cut the `v1` branch
+- [ATTRIBUTION.md](./ATTRIBUTION.md) — third-party SDKs and scope boundaries
 
 ## Acknowledgements
 

package/android/build.gradle

@@ -48,6 +48,16 @@ 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')
+  // 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"
+
   implementation "com.squareup.okhttp3:okhttp:4.12.0"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"

package/android/consumer-rules.pro

@@ -3,6 +3,11 @@
 -keepclassmembers class com.spotify.sdk.android.auth.** { *; }
 -dontwarn com.spotify.sdk.android.auth.**
 
+# Keep Spotify App Remote SDK classes
+-keep class com.spotify.android.appremote.** { *; }
+-keepclassmembers class com.spotify.android.appremote.** { *; }
+-dontwarn com.spotify.android.appremote.**
+
 # Keep our module's data classes
 -keep class expo.modules.spotifysdk.** { *; }
 -keepclassmembers class expo.modules.spotifysdk.** { *; }

package/android/libs/SETUP.md

@@ -0,0 +1,29 @@
+# Android App Remote SDK setup
+
+The Spotify App Remote SDK for Android is not published to Maven Central and must be
+downloaded manually.
+
+## Steps
+
+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 `flatDir` repository in `android/build.gradle` will pick it up automatically.
+
+## 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.** { *; }
+```