@wwdrew/expo-spotify-sdk 0.8.0 → 1.0.0

package/build/uri/index.js

@@ -0,0 +1,57 @@
+const URI_RE = /^spotify:(track|album|playlist|artist|show|episode):([A-Za-z0-9]+)$/;
+/**
+ * Helpers for constructing, validating and decomposing {@link SpotifyURI}
+ * values.
+ *
+ * @example
+ * ```ts
+ * const uri = SpotifyURI.from("spotify:track:4uLU6hMCjMI75M1A2tKUQC");
+ * const { type, id } = SpotifyURI.parse(uri);
+ * const rebuilt = SpotifyURI.build("track", id);
+ * ```
+ */
+export const SpotifyURI = {
+    /**
+     * Cast `uri` to {@link SpotifyURI} after validation.
+     * Throws a plain `Error` if the URI does not match the `spotify:<type>:<id>`
+     * format — use at app-code call sites where you want early feedback.
+     */
+    from(uri) {
+        if (!SpotifyURI.isValid(uri)) {
+            throw new Error(`Invalid Spotify URI: "${uri}". Expected spotify:<type>:<id> where ` +
+                `<type> is one of: track, album, playlist, artist, show, episode.`);
+        }
+        return uri;
+    },
+    /**
+     * Cast `uri` to {@link SpotifyURI} without validation.
+     * Use only for URIs that originate from the Spotify SDK itself (i.e. already
+     * known-valid values coming back over the bridge).
+     */
+    unsafe(uri) {
+        return uri;
+    },
+    /**
+     * Decompose a {@link SpotifyURI} into its `{ type, id }` parts.
+     */
+    parse(uri) {
+        const m = uri.match(URI_RE);
+        if (!m) {
+            throw new Error(`Cannot parse Spotify URI: "${uri}"`);
+        }
+        return { type: m[1], id: m[2] };
+    },
+    /**
+     * Build a {@link SpotifyURI} from a resource type and ID.
+     */
+    build(type, id) {
+        return `spotify:${type}:${id}`;
+    },
+    /**
+     * Type-guard: returns `true` if `uri` is a valid Spotify URI string.
+     */
+    isValid(uri) {
+        return URI_RE.test(uri);
+    },
+};
+//# sourceMappingURL=index.js.map

package/build/uri/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/uri/index.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,GACV,qEAAqE,CAAC;AAExE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;;;;OAIG;IACH,IAAI,CAAC,GAAW;QACd,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,yBAAyB,GAAG,wCAAwC;gBAClE,kEAAkE,CACrE,CAAC;QACJ,CAAC;QACD,OAAO,GAAiB,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,GAAW;QAChB,OAAO,GAAiB,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAe;QACnB,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,GAAG,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAwB,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAyB,EAAE,EAAU;QACzC,OAAO,WAAW,IAAI,IAAI,EAAE,EAAgB,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,GAAW;QACjB,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACO,CAAC","sourcesContent":["/**\n * The six Spotify resource types accepted by App Remote APIs.\n */\nexport type SpotifyResourceType =\n  | \"track\"\n  | \"album\"\n  | \"playlist\"\n  | \"artist\"\n  | \"show\"\n  | \"episode\";\n\n/**\n * Branded string type for Spotify URIs (`spotify:<type>:<id>`).\n *\n * Construct via `SpotifyURI.from(str)` (validates) or\n * `SpotifyURI.unsafe(str)` (skips validation — use only when the source is\n * trusted, e.g. a URI that came back from the Spotify SDK itself).\n */\nexport type SpotifyURI = string & { readonly __brand: \"SpotifyURI\" };\n\nconst URI_RE =\n  /^spotify:(track|album|playlist|artist|show|episode):([A-Za-z0-9]+)$/;\n\n/**\n * Helpers for constructing, validating and decomposing {@link SpotifyURI}\n * values.\n *\n * @example\n * ```ts\n * const uri = SpotifyURI.from(\"spotify:track:4uLU6hMCjMI75M1A2tKUQC\");\n * const { type, id } = SpotifyURI.parse(uri);\n * const rebuilt = SpotifyURI.build(\"track\", id);\n * ```\n */\nexport const SpotifyURI = {\n  /**\n   * Cast `uri` to {@link SpotifyURI} after validation.\n   * Throws a plain `Error` if the URI does not match the `spotify:<type>:<id>`\n   * format — use at app-code call sites where you want early feedback.\n   */\n  from(uri: string): SpotifyURI {\n    if (!SpotifyURI.isValid(uri)) {\n      throw new Error(\n        `Invalid Spotify URI: \"${uri}\". Expected spotify:<type>:<id> where ` +\n          `<type> is one of: track, album, playlist, artist, show, episode.`,\n      );\n    }\n    return uri as SpotifyURI;\n  },\n\n  /**\n   * Cast `uri` to {@link SpotifyURI} without validation.\n   * Use only for URIs that originate from the Spotify SDK itself (i.e. already\n   * known-valid values coming back over the bridge).\n   */\n  unsafe(uri: string): SpotifyURI {\n    return uri as SpotifyURI;\n  },\n\n  /**\n   * Decompose a {@link SpotifyURI} into its `{ type, id }` parts.\n   */\n  parse(uri: SpotifyURI): { type: SpotifyResourceType; id: string } {\n    const m = uri.match(URI_RE);\n    if (!m) {\n      throw new Error(`Cannot parse Spotify URI: \"${uri}\"`);\n    }\n    return { type: m[1] as SpotifyResourceType, id: m[2] };\n  },\n\n  /**\n   * Build a {@link SpotifyURI} from a resource type and ID.\n   */\n  build(type: SpotifyResourceType, id: string): SpotifyURI {\n    return `spotify:${type}:${id}` as SpotifyURI;\n  },\n\n  /**\n   * Type-guard: returns `true` if `uri` is a valid Spotify URI string.\n   */\n  isValid(uri: string): uri is SpotifyURI {\n    return URI_RE.test(uri);\n  },\n} as const;\n"]}

package/build/user/error.d.ts

@@ -0,0 +1,8 @@
+import { SpotifyError } from "../error";
+export type UserErrorCode = "NOT_CONNECTED" | "CONNECTION_LOST" | "INVALID_URI" | "OPERATION_NOT_ALLOWED" | "UNKNOWN";
+export declare class UserError extends SpotifyError {
+    readonly namespace: "User";
+    readonly code: UserErrorCode;
+    constructor(code: UserErrorCode, message: string);
+}
+//# sourceMappingURL=error.d.ts.map

package/build/user/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/user/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,MAAM,aAAa,GACrB,eAAe,GACf,iBAAiB,GACjB,aAAa,GACb,uBAAuB,GACvB,SAAS,CAAC;AAEd,qBAAa,SAAU,SAAQ,YAAY;IACzC,QAAQ,CAAC,SAAS,EAAG,MAAM,CAAU;IACrC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;gBAEjB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAIjD"}

package/build/user/error.js

@@ -0,0 +1,10 @@
+import { SpotifyError } from "../error";
+export class UserError extends SpotifyError {
+    namespace = "User";
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+//# sourceMappingURL=error.js.map

package/build/user/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/user/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AASxC,MAAM,OAAO,SAAU,SAAQ,YAAY;IAChC,SAAS,GAAG,MAAe,CAAC;IAC5B,IAAI,CAAgB;IAE7B,YAAY,IAAmB,EAAE,OAAe;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF","sourcesContent":["import { SpotifyError } from \"../error\";\n\nexport type UserErrorCode =\n  | \"NOT_CONNECTED\"\n  | \"CONNECTION_LOST\"\n  | \"INVALID_URI\"\n  | \"OPERATION_NOT_ALLOWED\"\n  | \"UNKNOWN\";\n\nexport class UserError extends SpotifyError {\n  readonly namespace = \"User\" as const;\n  readonly code: UserErrorCode;\n\n  constructor(code: UserErrorCode, message: string) {\n    super(message);\n    this.code = code;\n  }\n}\n"]}

package/build/user/index.d.ts

@@ -0,0 +1,44 @@
+export type { UserErrorCode } from "./error";
+export { UserError } from "./error";
+import { EventSubscription } from "expo-modules-core";
+import type { SpotifyURI as SpotifyURIType } from "../uri";
+/** Capabilities of the current user in Spotify's App Remote context. */
+export interface Capabilities {
+    /** `true` for Premium users with on-demand playback capability. */
+    canPlayOnDemand: boolean;
+}
+/** Library save state for a specific album/track URI. */
+export interface LibraryState {
+    uri: string;
+    isAdded: boolean;
+    canAdd: boolean;
+}
+/**
+ * Spotify User namespace. Capabilities and library-state operations.
+ * Requires `AppRemote.connect()` to be resolved before any call.
+ */
+export declare const User: {
+    /** Returns the current user's capabilities. */
+    readonly getCapabilities: () => Promise<Capabilities>;
+    /** Returns the current library state for a track or album URI. */
+    readonly getLibraryState: (uri: SpotifyURIType) => Promise<LibraryState>;
+    /** Adds a track or album URI to the user's library. */
+    readonly addToLibrary: (uri: SpotifyURIType) => Promise<void>;
+    /** Removes a track or album URI from the user's library. */
+    readonly removeFromLibrary: (uri: SpotifyURIType) => Promise<void>;
+    /**
+     * Subscribes to user-scoped events.
+     * Supported event: `"capabilitiesChange"`.
+     */
+    readonly addListener: (event: "capabilitiesChange", listener: (event: Capabilities) => void) => EventSubscription;
+    /**
+     * Subscribes to library state changes for a specific URI.
+     *
+     * There is no native push stream for per-URI library state updates on all
+     * platforms, so this listener is updated whenever library mutations are
+     * performed via this SDK and can be manually seeded by calling
+     * `User.getLibraryState(uri)` before subscribing.
+     */
+    readonly addLibraryStateListener: (uri: SpotifyURIType, listener: (state: LibraryState) => void) => EventSubscription;
+};
+//# sourceMappingURL=index.d.ts.map

package/build/user/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/user/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAMpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,QAAQ,CAAC;AAG3D,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB;AA2CD;;;GAGG;AACH,eAAO,MAAM,IAAI;IACf,+CAA+C;oCAC5B,OAAO,CAAC,YAAY,CAAC;IAIxC,kEAAkE;oCAC7C,cAAc,KAAG,OAAO,CAAC,YAAY,CAAC;IAI3D,uDAAuD;iCAC/B,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,4DAA4D;sCAC/B,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC;IAO3D;;;OAGG;kCAEM,oBAAoB,YACjB,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KACtC,iBAAiB;IAOpB;;;;;;;OAOG;4CAEI,cAAc,YACT,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,KACtC,iBAAiB;CAiBZ,CAAC"}

package/build/user/index.js

@@ -0,0 +1,97 @@
+export { UserError } from "./error";
+import ExpoSpotifySDKModule from "../ExpoSpotifySDKModule";
+import { UserError } from "./error";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+const VALID_USER_CODES = new Set([
+    "NOT_CONNECTED",
+    "CONNECTION_LOST",
+    "INVALID_URI",
+    "OPERATION_NOT_ALLOWED",
+    "UNKNOWN",
+]);
+const CAUSE_SEPARATOR = "→ Caused by: ";
+function unwrapReason(message) {
+    const idx = message.lastIndexOf(CAUSE_SEPARATOR);
+    return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);
+}
+function rethrowAsUserError(err) {
+    if (err instanceof UserError)
+        throw err;
+    if (err instanceof Error) {
+        const reason = unwrapReason(err.message);
+        const maybeCode = err.code;
+        if (maybeCode && VALID_USER_CODES.has(maybeCode)) {
+            throw new UserError(maybeCode, reason);
+        }
+        throw new UserError("UNKNOWN", reason);
+    }
+    throw new UserError("UNKNOWN", String(err));
+}
+const libraryListeners = new Map();
+function notifyLibraryState(state) {
+    const set = libraryListeners.get(state.uri);
+    if (!set)
+        return;
+    set.forEach((listener) => listener(state));
+}
+/**
+ * Spotify User namespace. Capabilities and library-state operations.
+ * Requires `AppRemote.connect()` to be resolved before any call.
+ */
+export const User = {
+    /** Returns the current user's capabilities. */
+    getCapabilities() {
+        return ExpoSpotifySDKModule.userGetCapabilities().catch(rethrowAsUserError);
+    },
+    /** Returns the current library state for a track or album URI. */
+    getLibraryState(uri) {
+        return ExpoSpotifySDKModule.userGetLibraryState(uri).catch(rethrowAsUserError);
+    },
+    /** Adds a track or album URI to the user's library. */
+    async addToLibrary(uri) {
+        const state = (await ExpoSpotifySDKModule.userAddToLibrary(uri).catch(rethrowAsUserError));
+        notifyLibraryState(state);
+    },
+    /** Removes a track or album URI from the user's library. */
+    async removeFromLibrary(uri) {
+        const state = (await ExpoSpotifySDKModule.userRemoveFromLibrary(uri).catch(rethrowAsUserError));
+        notifyLibraryState(state);
+    },
+    /**
+     * Subscribes to user-scoped events.
+     * Supported event: `"capabilitiesChange"`.
+     */
+    addListener(event, listener) {
+        return ExpoSpotifySDKModule.addListener("onCapabilitiesChange", listener);
+    },
+    /**
+     * Subscribes to library state changes for a specific URI.
+     *
+     * There is no native push stream for per-URI library state updates on all
+     * platforms, so this listener is updated whenever library mutations are
+     * performed via this SDK and can be manually seeded by calling
+     * `User.getLibraryState(uri)` before subscribing.
+     */
+    addLibraryStateListener(uri, listener) {
+        const key = String(uri);
+        let set = libraryListeners.get(key);
+        if (!set) {
+            set = new Set();
+            libraryListeners.set(key, set);
+        }
+        set.add(listener);
+        return {
+            remove() {
+                const current = libraryListeners.get(key);
+                if (!current)
+                    return;
+                current.delete(listener);
+                if (current.size === 0)
+                    libraryListeners.delete(key);
+            },
+        };
+    },
+};
+//# sourceMappingURL=index.js.map

package/build/user/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/user/index.ts"],"names":[],"mappings":"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","sourcesContent":["export type { UserErrorCode } from \"./error\";\nexport { UserError } from \"./error\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nimport { EventSubscription } from \"expo-modules-core\";\n\nimport ExpoSpotifySDKModule from \"../ExpoSpotifySDKModule\";\nimport type { SpotifyURI as SpotifyURIType } from \"../uri\";\nimport { UserError, UserErrorCode } from \"./error\";\n\n/** Capabilities of the current user in Spotify's App Remote context. */\nexport interface Capabilities {\n  /** `true` for Premium users with on-demand playback capability. */\n  canPlayOnDemand: boolean;\n}\n\n/** Library save state for a specific album/track URI. */\nexport interface LibraryState {\n  uri: string;\n  isAdded: boolean;\n  canAdd: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst VALID_USER_CODES = new Set<UserErrorCode>([\n  \"NOT_CONNECTED\",\n  \"CONNECTION_LOST\",\n  \"INVALID_URI\",\n  \"OPERATION_NOT_ALLOWED\",\n  \"UNKNOWN\",\n]);\n\nconst CAUSE_SEPARATOR = \"→ Caused by: \";\n\nfunction unwrapReason(message: string): string {\n  const idx = message.lastIndexOf(CAUSE_SEPARATOR);\n  return idx === -1 ? message : message.slice(idx + CAUSE_SEPARATOR.length);\n}\n\nfunction rethrowAsUserError(err: unknown): never {\n  if (err instanceof UserError) throw err;\n  if (err instanceof Error) {\n    const reason = unwrapReason(err.message);\n    const maybeCode = (err as Error & { code?: string }).code;\n    if (maybeCode && VALID_USER_CODES.has(maybeCode as UserErrorCode)) {\n      throw new UserError(maybeCode as UserErrorCode, reason);\n    }\n    throw new UserError(\"UNKNOWN\", reason);\n  }\n  throw new UserError(\"UNKNOWN\", String(err));\n}\n\ntype LibraryListener = (state: LibraryState) => void;\nconst libraryListeners = new Map<string, Set<LibraryListener>>();\n\nfunction notifyLibraryState(state: LibraryState) {\n  const set = libraryListeners.get(state.uri);\n  if (!set) return;\n  set.forEach((listener) => listener(state));\n}\n\n/**\n * Spotify User namespace. Capabilities and library-state operations.\n * Requires `AppRemote.connect()` to be resolved before any call.\n */\nexport const User = {\n  /** Returns the current user's capabilities. */\n  getCapabilities(): Promise<Capabilities> {\n    return ExpoSpotifySDKModule.userGetCapabilities().catch(rethrowAsUserError);\n  },\n\n  /** Returns the current library state for a track or album URI. */\n  getLibraryState(uri: SpotifyURIType): Promise<LibraryState> {\n    return ExpoSpotifySDKModule.userGetLibraryState(uri).catch(rethrowAsUserError);\n  },\n\n  /** Adds a track or album URI to the user's library. */\n  async addToLibrary(uri: SpotifyURIType): Promise<void> {\n    const state = (await ExpoSpotifySDKModule.userAddToLibrary(uri).catch(\n      rethrowAsUserError,\n    )) as LibraryState;\n    notifyLibraryState(state);\n  },\n\n  /** Removes a track or album URI from the user's library. */\n  async removeFromLibrary(uri: SpotifyURIType): Promise<void> {\n    const state = (await ExpoSpotifySDKModule.userRemoveFromLibrary(uri).catch(\n      rethrowAsUserError,\n    )) as LibraryState;\n    notifyLibraryState(state);\n  },\n\n  /**\n   * Subscribes to user-scoped events.\n   * Supported event: `\"capabilitiesChange\"`.\n   */\n  addListener(\n    event: \"capabilitiesChange\",\n    listener: (event: Capabilities) => void,\n  ): EventSubscription {\n    return ExpoSpotifySDKModule.addListener(\n      \"onCapabilitiesChange\",\n      listener as (event: unknown) => void,\n    ) as EventSubscription;\n  },\n\n  /**\n   * Subscribes to library state changes for a specific URI.\n   *\n   * There is no native push stream for per-URI library state updates on all\n   * platforms, so this listener is updated whenever library mutations are\n   * performed via this SDK and can be manually seeded by calling\n   * `User.getLibraryState(uri)` before subscribing.\n   */\n  addLibraryStateListener(\n    uri: SpotifyURIType,\n    listener: (state: LibraryState) => void,\n  ): EventSubscription {\n    const key = String(uri);\n    let set = libraryListeners.get(key);\n    if (!set) {\n      set = new Set();\n      libraryListeners.set(key, set);\n    }\n    set.add(listener);\n    return {\n      remove() {\n        const current = libraryListeners.get(key);\n        if (!current) return;\n        current.delete(listener);\n        if (current.size === 0) libraryListeners.delete(key);\n      },\n    } as EventSubscription;\n  },\n} as const;\n"]}

package/ios/ExpoSpotifySDKModule.swift

@@ -1,13 +1,47 @@
 import ExpoModulesCore
 import SpotifyiOS
 
-private let SDK_VERSION = "0.8.0" // x-release-please-version
+private let SDK_VERSION = "1.0.0" // x-release-please-version
 private let EVENT_SESSION_CHANGE = "onSessionChange"
+private let EVENT_CONNECTION_STATE_CHANGE = "onConnectionStateChange"
+private let EVENT_CONNECTION_ERROR = "onConnectionError"
+private let EVENT_PLAYER_STATE_CHANGE = "onPlayerStateChange"
+private let EVENT_CAPABILITIES_CHANGE = "onCapabilitiesChange"
 
 public class ExpoSpotifySDKModule: Module {
   public func definition() -> ModuleDefinition {
     Name("ExpoSpotifySDK")
-    Events(EVENT_SESSION_CHANGE)
+
+    Events(
+      EVENT_SESSION_CHANGE,
+      EVENT_CONNECTION_STATE_CHANGE,
+      EVENT_CONNECTION_ERROR,
+      EVENT_PLAYER_STATE_CHANGE,
+      EVENT_CAPABILITIES_CHANGE
+    )
+
+    // Wire up App Remote coordinator event callbacks once the module is alive.
+    OnCreate {
+      Task {
+        guard let coordinator = SpotifyAppRemoteCoordinator.shared else { return }
+        await coordinator.setEventHandlers(
+          onConnectionStateChange: { [weak self] state in
+            self?.sendEvent(EVENT_CONNECTION_STATE_CHANGE, ["state": state])
+          },
+          onConnectionError: { [weak self] code, message in
+            self?.sendEvent(EVENT_CONNECTION_ERROR, ["code": code, "message": message])
+          },
+          onPlayerStateChange: { [weak self] stateMap in
+            self?.sendEvent(EVENT_PLAYER_STATE_CHANGE, stateMap)
+          },
+          onCapabilitiesChange: { [weak self] capabilities in
+            self?.sendEvent(EVENT_CAPABILITIES_CHANGE, capabilities)
+          }
+        )
+      }
+    }
+
+    // MARK: — Auth
 
     Function("isAvailable") { () -> Bool in
       SpotifyAuthCoordinator.shared?.isSpotifyAppInstalled() ?? false
@@ -43,7 +77,7 @@ public class ExpoSpotifySDKModule: Module {
           "type": "didFail",
           "error": ["code": error.code, "message": error.message],
         ])
-        throw GenericException("\(error.code): \(error.message)")
+        throw SpotifyAuthException(error)
       }
     }
 
@@ -79,17 +113,203 @@ public class ExpoSpotifySDKModule: Module {
           "type": "didFail",
           "error": ["code": error.code, "message": error.message],
         ])
-        throw GenericException("\(error.code): \(error.message)")
+        throw SpotifyAuthException(error)
       } catch let error as SpotifyRefreshError {
         self.sendEvent(EVENT_SESSION_CHANGE, [
           "type": "didFail",
           "error": ["code": error.code, "message": error.message],
         ])
-        throw GenericException("\(error.code): \(error.message)")
+        throw SpotifyRefreshException(error)
+      }
+    }
+
+    // MARK: — App Remote
+
+    AsyncFunction("appRemoteConnect") { (accessToken: String) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw AppRemoteException(AppRemoteError.connectionFailed(
+          "Missing `ExpoSpotifySDK` configuration in Info.plist."
+        ))
+      }
+      do {
+        try await coordinator.connect(accessToken: accessToken)
+      } catch let error as AppRemoteError {
+        throw AppRemoteException(error)
+      }
+    }
+
+    AsyncFunction("appRemoteDisconnect") { () async -> Void in
+      await SpotifyAppRemoteCoordinator.shared?.disconnect()
+    }
+
+    Function("appRemoteIsConnected") { () -> Bool in
+      SpotifyAppRemoteCoordinator.shared?.isConnected() ?? false
+    }
+
+    AsyncFunction("appRemoteGetConnectionState") { () async -> String in
+      await SpotifyAppRemoteCoordinator.shared?.getConnectionState() ?? "disconnected"
+    }
+
+    // MARK: — Player
+
+    AsyncFunction("playerPlay") { (uri: String) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.play: missing configuration"))
+      }
+      do { try await coordinator.playerPlay(uri: uri) } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerPause") { () async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.pause: missing configuration"))
+      }
+      do { try await coordinator.playerPause() } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerResume") { () async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.resume: missing configuration"))
+      }
+      do { try await coordinator.playerResume() } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerSkipNext") { () async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.skipNext: missing configuration"))
+      }
+      do { try await coordinator.playerSkipNext() } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerSkipPrevious") { () async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.skipPrevious: missing configuration"))
+      }
+      do { try await coordinator.playerSkipPrevious() } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerSeekTo") { (positionMs: Int) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.seekTo: missing configuration"))
+      }
+      do { try await coordinator.playerSeekTo(positionMs: positionMs) } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerSetShuffle") { (enabled: Bool) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.setShuffle: missing configuration"))
+      }
+      do { try await coordinator.playerSetShuffle(enabled: enabled) } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerSetRepeatMode") { (mode: Int) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.setRepeatMode: missing configuration"))
+      }
+      do { try await coordinator.playerSetRepeatMode(mode: mode) } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerSetPodcastPlaybackSpeed") { (value: Double) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.setPodcastPlaybackSpeed: missing configuration"))
+      }
+      do {
+        try await coordinator.playerSetPodcastPlaybackSpeed(value: Float(value))
+      } catch let e as NativePlayerError {
+        throw PlayerException(e)
+      }
+    }
+
+    AsyncFunction("playerQueue") { (uri: String) async throws -> Void in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.queue: missing configuration"))
+      }
+      do { try await coordinator.playerQueue(uri: uri) } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerGetPlayerState") { () async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.getPlayerState: missing configuration"))
+      }
+      do { return try await coordinator.playerGetPlayerState() } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    AsyncFunction("playerGetCrossfadeState") { () async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw PlayerException(NativePlayerError.notConnected("Player.getCrossfadeState: missing configuration"))
+      }
+      do { return try await coordinator.playerGetCrossfadeState() } catch let e as NativePlayerError { throw PlayerException(e) }
+    }
+
+    // MARK: — User
+
+    AsyncFunction("userGetCapabilities") { () async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw UserException(NativeUserError.notConnected("User.getCapabilities: missing configuration"))
+      }
+      do { return try await coordinator.userGetCapabilities() } catch let e as NativeUserError { throw UserException(e) }
+    }
+
+    AsyncFunction("userGetLibraryState") { (uri: String) async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw UserException(NativeUserError.notConnected("User.getLibraryState: missing configuration"))
+      }
+      do { return try await coordinator.userGetLibraryState(uri: uri) } catch let e as NativeUserError { throw UserException(e) }
+    }
+
+    AsyncFunction("userAddToLibrary") { (uri: String) async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw UserException(NativeUserError.notConnected("User.addToLibrary: missing configuration"))
+      }
+      do { return try await coordinator.userAddToLibrary(uri: uri) } catch let e as NativeUserError { throw UserException(e) }
+    }
+
+    AsyncFunction("userRemoveFromLibrary") { (uri: String) async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw UserException(NativeUserError.notConnected("User.removeFromLibrary: missing configuration"))
+      }
+      do { return try await coordinator.userRemoveFromLibrary(uri: uri) } catch let e as NativeUserError { throw UserException(e) }
+    }
+
+    // MARK: — Content
+
+    AsyncFunction("contentGetRecommendedContentItems") { (type: String) async throws -> [[String: Any]] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw ContentException(NativeContentError.notConnected("Content.getRecommendedContentItems: missing configuration"))
+      }
+      do {
+        return try await coordinator.contentGetRecommendedContentItems(type: type)
+      } catch let e as NativeContentError {
+        throw ContentException(e)
+      }
+    }
+
+    AsyncFunction("contentGetChildren") { (item: [String: Any]) async throws -> [[String: Any]] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw ContentException(NativeContentError.notConnected("Content.getChildren: missing configuration"))
+      }
+      do {
+        return try await coordinator.contentGetChildren(itemMap: item)
+      } catch let e as NativeContentError {
+        throw ContentException(e)
+      }
+    }
+
+    // MARK: — Images
+
+    AsyncFunction("imagesLoad") { (imageIdentifier: String, size: String) async throws -> [String: Any] in
+      guard let coordinator = SpotifyAppRemoteCoordinator.shared else {
+        throw ImagesException(NativeImagesError.notConnected("Images.load: missing configuration"))
+      }
+      do {
+        return try await coordinator.imagesLoad(imageIdentifier: imageIdentifier, size: size)
+      } catch let e as NativeImagesError {
+        throw ImagesException(e)
       }
     }
   }
 
+  // MARK: — Helpers
+
   private func sessionToMap(_ session: SPTSession) -> [String: Any?] {
     return [
       "accessToken": session.accessToken,
@@ -100,6 +320,8 @@ public class ExpoSpotifySDKModule: Module {
   }
 }
 
+// MARK: — Record types
+
 struct AuthenticateOptions: Record {
   @Field var scopes: [String] = []
   @Field var tokenSwapURL: String? = nil