soundcloud-api-ts-next 1.2.0 → 1.3.1

package/README.md

@@ -1,38 +1,44 @@
 # soundcloud-api-ts-next
 
-Next.js integration for [soundcloud-api-ts](https://github.com/twin-paws/soundcloud-api-ts) — React hooks + secure API route handlers.
+[![npm version](https://img.shields.io/npm/v/soundcloud-api-ts-next)](https://www.npmjs.com/package/soundcloud-api-ts-next)
+[![npm downloads](https://img.shields.io/npm/dm/soundcloud-api-ts-next)](https://www.npmjs.com/package/soundcloud-api-ts-next)
+[![license](https://img.shields.io/npm/l/soundcloud-api-ts-next)](https://github.com/twin-paws/soundcloud-api-ts-next/blob/main/LICENSE)
 
-## Installation
+React hooks and Next.js API route handlers for the SoundCloud API. Client secrets stay on the server.
+
+Built on [soundcloud-api-ts](https://github.com/twin-paws/soundcloud-api-ts).
+
+## Install
 
 ```bash
 npm install soundcloud-api-ts-next
-# or
-pnpm add soundcloud-api-ts-next
 ```
 
-## Setup
-
-### 1. Server Routes
+## Quick Start
 
-Create an API route handler that proxies SoundCloud requests (keeps your credentials server-side).
-
-**App Router** (`app/api/soundcloud/[...route]/route.ts`):
+**1. Create API routes** — secrets stay server-side:
 
 ```ts
+// app/api/soundcloud/[...route]/route.ts
 import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";
 
 const sc = createSoundCloudRoutes({
   clientId: process.env.SOUNDCLOUD_CLIENT_ID!,
   clientSecret: process.env.SOUNDCLOUD_CLIENT_SECRET!,
+  redirectUri: process.env.SOUNDCLOUD_REDIRECT_URI, // for OAuth
 });
 
 const handler = sc.handler();
 export const GET = handler;
+export const POST = handler;
+export const DELETE = handler;
 ```
 
-**Pages Router** (`pages/api/soundcloud/[...route].ts`):
+<details>
+<summary>Pages Router setup</summary>
 
 ```ts
+// pages/api/soundcloud/[...route].ts
 import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";
 
 const sc = createSoundCloudRoutes({
@@ -42,12 +48,12 @@ const sc = createSoundCloudRoutes({
 
 export default sc.pagesHandler();
 ```
+</details>
 
-### 2. Client Provider
-
-Wrap your app with the `SoundCloudProvider`:
+**2. Add the provider:**
 
 ```tsx
+// app/layout.tsx
 import { SoundCloudProvider } from "soundcloud-api-ts-next";
 
 export default function Layout({ children }) {
@@ -59,140 +65,239 @@ export default function Layout({ children }) {
 }
 ```
 
+**3. Use hooks:**
+
+```tsx
+import { useTrackSearch, usePlayer } from "soundcloud-api-ts-next";
+
+function SearchPage() {
+  const { data: tracks, loading } = useTrackSearch("lofi beats");
+
+  if (loading) return <p>Searching...</p>;
+
+  return tracks?.map((track) => (
+    <div key={track.id}>
+      <p>{track.title} — {track.user.username}</p>
+    </div>
+  ));
+}
+```
+
+---
+
 ## Hooks
 
 All hooks return `{ data, loading, error }`.
 
 ### Tracks
 
-| Hook | Arguments | Description |
-|------|-----------|-------------|
-| `useTrack(trackId)` | `string \| number \| undefined` | Fetch a single track |
-| `useTrackSearch(query, options?)` | `string`, `{ limit? }` | Search tracks |
-| `useTrackComments(trackId)` | `string \| number \| undefined` | Get track comments |
-| `useTrackLikes(trackId)` | `string \| number \| undefined` | Get users who liked a track |
-| `useRelatedTracks(trackId)` | `string \| number \| undefined` | Get related tracks |
+| Hook | Description |
+|------|-------------|
+| `useTrack(id)` | Single track |
+| `useTrackSearch(query)` | Search tracks |
+| `useTrackComments(id)` | Track comments |
+| `useTrackLikes(id)` | Users who liked a track |
+| `useRelatedTracks(id)` | Related tracks |
+| `usePlayer(streamUrl)` | Audio player — `{ playing, progress, duration, play, pause, toggle, seek }` |
 
 ### Users
 
-| Hook | Arguments | Description |
-|------|-----------|-------------|
-| `useUser(userId)` | `string \| number \| undefined` | Fetch a single user |
-| `useUserSearch(query)` | `string` | Search users |
-| `useUserTracks(userId)` | `string \| number \| undefined` | Get a user's tracks |
-| `useUserPlaylists(userId)` | `string \| number \| undefined` | Get a user's playlists |
-| `useUserLikes(userId)` | `string \| number \| undefined` | Get a user's liked tracks |
-| `useUserFollowers(userId)` | `string \| number \| undefined` | Get a user's followers |
-| `useUserFollowings(userId)` | `string \| number \| undefined` | Get a user's followings |
+| Hook | Description |
+|------|-------------|
+| `useUser(id)` | Single user |
+| `useUserSearch(query)` | Search users |
+| `useUserTracks(id)` | User's tracks |
+| `useUserPlaylists(id)` | User's playlists |
+| `useUserLikes(id)` | User's liked tracks |
+| `useUserFollowers(id)` | User's followers |
+| `useUserFollowings(id)` | User's followings |
 
 ### Playlists
 
-| Hook | Arguments | Description |
-|------|-----------|-------------|
-| `usePlaylist(playlistId)` | `string \| number \| undefined` | Fetch a single playlist |
-| `usePlaylistTracks(playlistId)` | `string \| number \| undefined` | Get tracks in a playlist |
-| `usePlaylistSearch(query)` | `string` | Search playlists |
+| Hook | Description |
+|------|-------------|
+| `usePlaylist(id)` | Single playlist |
+| `usePlaylistSearch(query)` | Search playlists |
+| `usePlaylistTracks(id)` | Playlist tracks |
 
-### Player
+---
 
-| Hook | Arguments | Description |
-|------|-----------|-------------|
-| `usePlayer(streamUrl)` | `string \| undefined` | Audio player with play/pause/seek |
+## Infinite Scroll
 
-## Server Routes
+Cursor-based pagination with `loadMore()` and `reset()`. All return `InfiniteResult<T>`:
 
-All routes are available via the catch-all handler and as individual methods on the routes object.
+```ts
+{ data: T[], loading, error, hasMore, loadMore, reset }
+```
 
-### Search
+```tsx
+import { useInfiniteTrackSearch } from "soundcloud-api-ts-next";
 
-| Route | Method | Description |
-|-------|--------|-------------|
-| `GET /search/tracks?q=...` | `searchTracks(q, page?)` | Search tracks |
-| `GET /search/users?q=...` | `searchUsers(q)` | Search users |
-| `GET /search/playlists?q=...` | `searchPlaylists(q)` | Search playlists |
+function Feed() {
+  const { data, loading, hasMore, loadMore } = useInfiniteTrackSearch("dubstep");
 
-### Tracks
+  return (
+    <>
+      {data.map((track) => <TrackCard key={track.id} track={track} />)}
+      {hasMore && <button onClick={loadMore} disabled={loading}>Load More</button>}
+    </>
+  );
+}
+```
 
-| Route | Method | Description |
-|-------|--------|-------------|
-| `GET /tracks/:id` | `getTrack(id)` | Get track details |
-| `GET /tracks/:id/stream` | `getTrackStreams(id)` | Get stream URLs |
-| `GET /tracks/:id/comments` | `getTrackComments(id)` | Get track comments |
-| `GET /tracks/:id/likes` | `getTrackLikes(id)` | Get track likes |
-| `GET /tracks/:id/related` | `getRelatedTracks(id)` | Get related tracks |
+| Hook | Description |
+|------|-------------|
+| `useInfiniteTrackSearch(query)` | Paginated track search |
+| `useInfiniteUserSearch(query)` | Paginated user search |
+| `useInfinitePlaylistSearch(query)` | Paginated playlist search |
+| `useInfiniteUserTracks(id)` | User's tracks |
+| `useInfiniteUserPlaylists(id)` | User's playlists |
+| `useInfiniteUserLikes(id)` | User's liked tracks |
+| `useInfiniteUserFollowers(id)` | User's followers |
+| `useInfiniteUserFollowings(id)` | User's followings |
+| `useInfiniteTrackComments(id)` | Track comments |
+| `useInfinitePlaylistTracks(id)` | Playlist tracks |
 
-### Users
+---
 
-| Route | Method | Description |
-|-------|--------|-------------|
-| `GET /users/:id` | `getUser(id)` | Get user details |
-| `GET /users/:id/tracks` | `getUserTracks(id, limit?)` | Get user's tracks |
-| `GET /users/:id/playlists` | `getUserPlaylists(id)` | Get user's playlists |
-| `GET /users/:id/likes/tracks` | `getUserLikesTracks(id)` | Get user's liked tracks |
-| `GET /users/:id/followers` | `getFollowers(id)` | Get user's followers |
-| `GET /users/:id/followings` | `getFollowings(id)` | Get user's followings |
+## Authentication
 
-### Playlists
+Full OAuth 2.1 with PKCE. No secrets on the client.
 
-| Route | Method | Description |
-|-------|--------|-------------|
-| `GET /playlists/:id` | `getPlaylist(id)` | Get playlist details |
-| `GET /playlists/:id/tracks` | `getPlaylistTracks(id)` | Get playlist tracks |
+### Login
 
-## Pagination / Infinite Scroll
+```tsx
+import { useSCAuth } from "soundcloud-api-ts-next";
 
-All paginated endpoints have `useInfinite*` hooks that handle cursor-based pagination automatically:
+function LoginButton() {
+  const { isAuthenticated, user, login, logout } = useSCAuth();
 
-```tsx
-import { useInfiniteTrackSearch } from "soundcloud-api-ts-next";
+  if (isAuthenticated) {
+    return (
+      <div>
+        <p>Welcome, {user?.username}</p>
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
+  }
 
-function TrackList() {
-  const { data, loading, error, hasMore, loadMore } = useInfiniteTrackSearch("lofi");
+  return <button onClick={login}>Login with SoundCloud</button>;
+}
+```
 
-  return (
-    <div>
-      {data.map((track) => (
-        <div key={track.id}>{track.title}</div>
-      ))}
-      {loading && <p>Loading...</p>}
-      {error && <p>Error: {error.message}</p>}
-      {hasMore && <button onClick={loadMore}>Load More</button>}
-    </div>
-  );
+### Callback Page
+
+```tsx
+// app/callback/page.tsx
+"use client";
+import { useEffect } from "react";
+import { useSearchParams, useRouter } from "next/navigation";
+import { useSCAuth } from "soundcloud-api-ts-next";
+
+export default function Callback() {
+  const params = useSearchParams();
+  const router = useRouter();
+  const { handleCallback } = useSCAuth();
+
+  useEffect(() => {
+    const code = params.get("code");
+    const state = params.get("state");
+    if (code && state) {
+      handleCallback(code, state).then(() => router.push("/"));
+    }
+  }, [params]);
+
+  return <p>Authenticating...</p>;
 }
 ```
 
-### Available infinite hooks
+### Authenticated Hooks
+
+Available after login. Automatically pass the user's access token.
 
 | Hook | Description |
-| ---- | ----------- |
-| `useInfiniteTrackSearch(query, options?)` | Paginated track search |
-| `useInfiniteUserSearch(query, options?)` | Paginated user search |
-| `useInfinitePlaylistSearch(query, options?)` | Paginated playlist search |
-| `useInfiniteUserTracks(userId)` | User's tracks |
-| `useInfiniteUserPlaylists(userId)` | User's playlists |
-| `useInfiniteUserLikes(userId)` | User's liked tracks |
-| `useInfiniteUserFollowers(userId)` | User's followers |
-| `useInfiniteUserFollowings(userId)` | User's followings |
-| `useInfiniteTrackComments(trackId)` | Track comments |
-| `useInfinitePlaylistTracks(playlistId)` | Playlist tracks |
-
-All hooks return `InfiniteResult<T>`:
+|------|-------------|
+| `useMe()` | Current user profile |
+| `useMeTracks()` | Your tracks |
+| `useMeLikes()` | Your liked tracks |
+| `useMePlaylists()` | Your playlists |
+| `useMeFollowings()` | Who you follow |
+| `useMeFollowers()` | Your followers |
 
-```ts
-interface InfiniteResult<T> {
-  data: T[];        // accumulated items across all pages
-  loading: boolean;
-  error: Error | null;
-  hasMore: boolean;  // true if more pages exist
-  loadMore: () => void;
-  reset: () => void; // clear and refetch from page 1
+### Actions
+
+Mutation hooks for authenticated users.
+
+| Hook | Methods |
+|------|---------|
+| `useLike()` | `likeTrack(id)`, `unlikeTrack(id)` |
+| `useFollow()` | `follow(userId)`, `unfollow(userId)` |
+| `useRepost()` | `repostTrack(id)`, `unrepostTrack(id)` |
+
+```tsx
+import { useLike, useFollow } from "soundcloud-api-ts-next";
+
+function TrackActions({ trackId, artistId }) {
+  const { likeTrack } = useLike();
+  const { follow } = useFollow();
+
+  return (
+    <>
+      <button onClick={() => likeTrack(trackId)}>❤️ Like</button>
+      <button onClick={() => follow(artistId)}>➕ Follow</button>
+    </>
+  );
 }
 ```
 
+---
+
+## Server Routes
+
+The catch-all handler exposes these routes automatically:
+
+| Route | Method | Description |
+|-------|--------|-------------|
+| `/search/tracks?q=` | GET | Search tracks |
+| `/search/users?q=` | GET | Search users |
+| `/search/playlists?q=` | GET | Search playlists |
+| `/tracks/:id` | GET | Track details |
+| `/tracks/:id/stream` | GET | Stream URLs |
+| `/tracks/:id/comments` | GET | Track comments |
+| `/tracks/:id/likes` | GET | Track likes |
+| `/tracks/:id/related` | GET | Related tracks |
+| `/tracks/:id/like` | POST/DELETE | Like/unlike (auth) |
+| `/tracks/:id/repost` | POST/DELETE | Repost/unrepost (auth) |
+| `/users/:id` | GET | User details |
+| `/users/:id/tracks` | GET | User tracks |
+| `/users/:id/playlists` | GET | User playlists |
+| `/users/:id/likes/tracks` | GET | User likes |
+| `/users/:id/followers` | GET | User followers |
+| `/users/:id/followings` | GET | User followings |
+| `/playlists/:id` | GET | Playlist details |
+| `/playlists/:id/tracks` | GET | Playlist tracks |
+| `/playlists/:id/like` | POST/DELETE | Like/unlike (auth) |
+| `/playlists/:id/repost` | POST/DELETE | Repost/unrepost (auth) |
+| `/me` | GET | Current user (auth) |
+| `/me/tracks` | GET | Your tracks (auth) |
+| `/me/likes` | GET | Your likes (auth) |
+| `/me/playlists` | GET | Your playlists (auth) |
+| `/me/followings` | GET | Your followings (auth) |
+| `/me/followers` | GET | Your followers (auth) |
+| `/me/follow/:userId` | POST/DELETE | Follow/unfollow (auth) |
+| `/auth/login` | GET | OAuth URL (PKCE) |
+| `/auth/callback` | GET | Token exchange |
+| `/auth/refresh` | POST | Refresh token |
+| `/auth/logout` | POST | Sign out |
+| `/next?url=` | GET | Pagination cursor |
+
+Routes marked **(auth)** require `Authorization: Bearer <token>` header.
+
+---
+
 ## Types
 
-All SoundCloud types are re-exported from `soundcloud-api-ts`:
+Re-exported from [soundcloud-api-ts](https://github.com/twin-paws/soundcloud-api-ts):
 
 ```ts
 import type {
@@ -201,9 +306,22 @@ import type {
   SoundCloudPlaylist,
   SoundCloudComment,
   SoundCloudStreams,
+  SoundCloudToken,
 } from "soundcloud-api-ts-next";
 ```
 
+---
+
+## Requirements
+
+- **Next.js** 13+ (App Router or Pages Router)
+- **React** 18+
+- **soundcloud-api-ts** installed automatically as a dependency
+
 ## License
 
 MIT
+
+## Related
+
+- [soundcloud-api-ts](https://github.com/twin-paws/soundcloud-api-ts) — The TypeScript-first SoundCloud API client this package is built on