@wwdrew/expo-spotify-sdk 0.8.0 → 2.0.0

package/README.md

@@ -4,28 +4,70 @@
 [![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 | —                   |
-| `cancelPendingAuthAsync()`                    | ✅  | no-op        | no-op               |
-| `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 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)).
+
+## Public API (Auth + App Remote)
+
+```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)
 
 ```sh
-# 1. Install
+# 1. Install (Expo SDK 56+ — matches `main` / npm `2.x`)
 npx expo install @wwdrew/expo-spotify-sdk
 
+# Expo SDK 55 only: npx expo install @wwdrew/expo-spotify-sdk@1
+
 # 2. Add the config plugin to app.config.ts / app.json  (see Configuration below)
 # 3. Regenerate native projects
 npx expo prebuild
@@ -97,7 +139,29 @@ Replace `myapp`, `spotify-auth`, and `your-spotify-client-id` with your own valu
 
 ## Configuration
 
-Add the plugin to your `app.config.ts` (or `app.json`):
+Add the plugin to your `app.config.ts` (or `app.json`).
+
+### Typed plugin (Expo SDK 56+)
+
+Import from `@wwdrew/expo-spotify-sdk/plugin` for autocomplete and type-checked options:
+
+```ts
+import type { ExpoConfig } from "expo/config";
+import withSpotifySdk from "@wwdrew/expo-spotify-sdk/plugin";
+
+export default ({ config }: { config: ExpoConfig }): ExpoConfig => ({
+  ...config,
+  plugins: [
+    withSpotifySdk({
+      clientID: "your-spotify-client-id",
+      scheme: "myapp",
+      host: "spotify-auth",
+    }),
+  ],
+});
+```
+
+### String tuple (all SDK versions)
 
 ```ts
 export default {
@@ -138,201 +202,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;
   }
 }
-```
 
-### Refresh a session
+function NowPlaying() {
+  const session = useSession();
+  const connectionState = useConnectionState();
+  const track = useCurrentTrack();
+  const isPlaying = useIsPlaying();
 
-```ts
-import { refreshSessionAsync } from "@wwdrew/expo-spotify-sdk";
+  useEffect(() => {
+    if (session == null || connectionState !== "disconnected") return;
+    void connectRemote(session.accessToken);
+  }, [session, connectionState]);
 
-const refreshed = await refreshSessionAsync({
-  refreshToken: storedRefreshToken,
-  tokenRefreshURL: "https://your-server.example.com/refresh",
-});
-```
+  if (connectionState !== "connected") {
+    return null;
+  }
 
-## API reference
+  return (
+    <Text>
+      {track?.name ?? "No track"} · {isPlaying ? "Playing" : "Paused"}
+    </Text>
+  );
+}
+```
 
-### `isAvailable(): boolean`
+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.
 
-Returns `true` if the Spotify app is installed on the device. Always returns `false` on web. Does not throw.
+### Check account tier (Web API)
 
----
+App Remote does not expose Premium status. Call Spotify's Web API with the access token from `Auth.authenticate()`:
 
-### `authenticateAsync(config: SpotifyConfig): Promise<SpotifySession>`
+```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";
+```
 
-Starts a Spotify OAuth flow. If the Spotify app is installed it authenticates natively; otherwise it falls back to the Spotify web login page.
+The [example app](./example) displays this as "Account tier: Premium / Free".
 
-**Throws [`SpotifyError`](#spotifyerror)** on failure.
+### Auto-connect App Remote
 
-**Parameters (`SpotifyConfig`):**
+Avoid reconnect loops by gating on connection state and attempting at most once per session restore:
 
-| 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.        |
+```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]);
+}
+```
 
-**Returns (`SpotifySession`):**
+For iOS, if `connect()` fails with `CONNECTION_FAILED`, foreground the Spotify app and retry manually — see [Troubleshooting](#troubleshooting).
 
-| 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).                     |
+## 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` |
 
-### `cancelPendingAuthAsync(): Promise<void>`
+**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.
 
-Forcibly cancels any in-flight `authenticateAsync` call. Resolves once the native coordinator's pending state is cleared. No-op when nothing is in flight.
+## Migration from v0.x
 
-**Why this exists:** the iOS `SPTSessionManager` delegate callbacks (`didInitiate` / `didFailWith`) are not guaranteed to fire — for example when Spotify never redirects back to the host app, or the host process is backgrounded mid-flow. When that happens the coordinator's pending continuation leaks and every subsequent `authenticateAsync` rejects immediately with `AUTH_IN_PROGRESS` until the process restarts.
+v0.x top-level functions remain exported but are deprecated (scheduled for removal in a future major).
 
-**When to call it:** defensively, before each `authenticateAsync`, so retries always start from a clean slate. The cost is one cheap async hop when nothing is leaked.
+| 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` |
 
-```ts
-import {
-  authenticateAsync,
-  cancelPendingAuthAsync,
-} from "@wwdrew/expo-spotify-sdk";
+`SpotifySession`, `SpotifyScope`, and config shapes are unchanged. For auth-specific `e.code` narrowing, use `instanceof AuthError` instead of `instanceof SpotifyError`.
 
-async function login() {
-  await cancelPendingAuthAsync();
-  return authenticateAsync({ scopes: ["user-read-email", "streaming"] });
-}
-```
+## API reference
 
-If a pending call is cancelled this way, its original `authenticateAsync` promise rejects with `SpotifyError` `code: "USER_CANCELLED"`.
+### `Auth`
 
-**Platform notes:** no-op on Android (the Kotlin coordinator self-cleans via structured concurrency) and on web. Safe to call unconditionally.
+#### `Auth.isAvailable(): boolean`
 
----
+Returns `true` if the Spotify app is installed. Does not throw (not available on unsupported platforms).
 
-### `refreshSessionAsync(options): Promise<SpotifySession>`
+#### `Auth.authenticate(config): Promise<SpotifySession>`
 
-Exchanges a refresh token for a new access token via your token refresh server.
+Starts OAuth via the installed Spotify app (or web fallback). Throws [`AuthError`](#autherror) on failure.
 
-**Parameters:**
+| 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`. |
 
-| Field             | Type             | Required | Description                                                                                                                                                                              |
-| ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `refreshToken`    | `string`         | ✅       | The refresh token from a previous `authenticateAsync` call.                                                                                                                              |
-| `tokenRefreshURL` | `string`         | ✅       | URL of your token refresh server endpoint.                                                                                                                                               |
-| `scopes`          | `SpotifyScope[]` | —        | Previously-granted scopes. Used as a fallback when the refresh response omits the `scope` field. **Pass through the previous session's `scopes`** to avoid silently losing scope info.   |
+| 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 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.cancelPending(): Promise<void>`
 
-**Why pass `scopes`:** Spotify's refresh endpoint only returns `scope` when the granted scope set has changed since the last issuance — most refresh responses omit it. Without `scopes` plumbed through, the returned session's `scopes` will be `[]` on every refresh that doesn't include the field, even though the access token itself still carries the same scopes.
+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
-const refreshed = await refreshSessionAsync({
-  refreshToken: previous.refreshToken,
-  tokenRefreshURL: "https://your-server.example.com/refresh",
-  scopes: previous.scopes,
-});
+await Auth.cancelPending();
+const session = await Auth.authenticate({ scopes: ["streaming"] });
 ```
 
----
-
-### `addSessionChangeListener(listener): Subscription`
+A cancelled call rejects with `AuthError` `code: "USER_CANCELLED"`.
 
-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.
+#### `Auth.refresh(config): Promise<SpotifySession>`
 
-Returns a `Subscription` object; call `.remove()` to unsubscribe.
+Exchanges a refresh token via your refresh server. Pass through `scopes` from the previous session when the refresh response omits `scope`.
 
 ```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;
-  }
+const refreshed = await Auth.refresh({
+  refreshToken: previous.refreshToken!,
+  tokenRefreshURL: "https://your-server.example.com/refresh",
+  scopes: previous.scopes,
 });
-
-// When the subscribing component unmounts:
-sub.remove();
 ```
 
-**Event types (`SpotifySessionChangeEvent`):**
-
-| `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, or iOS stuck state — see cancelPendingAuthAsync
+      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.
@@ -427,16 +669,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. Usually this means a concurrent call — wait for the first one to resolve.
+`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
 
-On iOS this can also be a stuck state: the SPTSessionManager delegate callbacks aren't guaranteed to fire (e.g. Spotify never redirected back to the app), so the previous call's continuation leaks and every retry rejects immediately. Call [`cancelPendingAuthAsync()`](#cancelpendingauthasync-promisevoid) before retrying — or, defensively, before every `authenticateAsync`.
+- [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 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
 
 ## Acknowledgements