soundcloud-api-ts-next 1.7.2 → 1.7.3

package/AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md — soundcloud-api-ts-next
+
+Instructions for AI coding agents working with this package.
+
+## Overview
+
+React hooks and Next.js API route handlers for the SoundCloud API. Client secrets stay on the server. Built on `soundcloud-api-ts`.
+
+## Setup
+
+```bash
+npm install soundcloud-api-ts-next
+```
+
+Requires: React 18+/19+, Next.js 13+/14+/15+
+
+### 1. Create API Routes (App Router)
+
+```ts
+// app/api/soundcloud/[...soundcloud]/route.ts
+import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server";
+
+const routes = createSoundCloudRoutes({
+  clientId: process.env.SOUNDCLOUD_CLIENT_ID!,
+  clientSecret: process.env.SOUNDCLOUD_CLIENT_SECRET!,
+  redirectUri: process.env.SOUNDCLOUD_REDIRECT_URI,
+});
+
+export const { GET, POST, DELETE } = routes.handler();
+```
+
+### 2. Wrap App with Provider
+
+```tsx
+import { SoundCloudProvider } from "soundcloud-api-ts-next";
+
+export default function Layout({ children }) {
+  return <SoundCloudProvider apiPrefix="/api/soundcloud">{children}</SoundCloudProvider>;
+}
+```
+
+### 3. Use Hooks
+
+```tsx
+import { useTrack, useTrackSearch, usePlayer } from "soundcloud-api-ts-next";
+
+const { data: track } = useTrack(123456);
+const { data: results } = useTrackSearch("lofi");
+const player = usePlayer(trackId);
+```
+
+## Key Concepts
+
+1. **All SoundCloud API calls go through your Next.js API routes** — client secrets never reach the browser
+2. **Hooks return `{ data, loading, error }`** — standard pattern for all data hooks
+3. **Infinite hooks return `{ data, loading, error, hasMore, loadMore, reset }`** — for scroll pagination
+4. **Action hooks return mutation functions** — `useLike().likeTrack(id)`, `useFollow().follow(id)`
+5. **Auth is managed via `useSCAuth()`** — handles OAuth redirect flow with PKCE
+
+## Project Structure
+
+```
+src/
+  index.ts           — Client-side exports (hooks, provider, types)
+  server.ts          — Server-side exports (createSoundCloudRoutes)
+  client/            — React hooks and provider implementation
+  server/            — API route handler implementation
+  types.ts           — Shared type definitions
+```
+
+## Build
+
+```bash
+pnpm build       # tsup → dist/ (ESM + CJS + .d.ts)
+pnpm typecheck   # tsc --noEmit
+pnpm docs        # TypeDoc → API docs site
+```
+
+## Publishing
+
+Uses **Trusted Publishing** via GitHub Releases (same as soundcloud-api-ts).
+
+## Gotchas
+
+1. **Two entry points** — `soundcloud-api-ts-next` (client hooks) and `soundcloud-api-ts-next/server` (route handlers). Don't import server code in client components.
+2. **Provider required** — all hooks need `<SoundCloudProvider>` in the component tree.
+3. **API prefix must match** — the `apiPrefix` in the provider must match your route file path.
+4. **Auth hooks need redirectUri** — set `redirectUri` in `createSoundCloudRoutes` config for OAuth flow.
+
+## Related Packages
+
+- [soundcloud-api-ts](https://github.com/twin-paws/soundcloud-api-ts) — The underlying API client (dependency)
+
+## Full Documentation
+
+https://twin-paws.github.io/soundcloud-api-ts-next/

package/llms-full.txt

@@ -0,0 +1,325 @@
+# soundcloud-api-ts-next
+
+> React hooks and Next.js API route handlers for the SoundCloud API. Client secrets stay on the server.
+
+## What this package does
+- Provides 25+ React hooks for accessing SoundCloud data (tracks, users, playlists, search)
+- Provides 10 infinite scroll hooks with cursor-based pagination
+- Provides secure Next.js API route handlers that keep OAuth credentials server-side
+- Provides full OAuth 2.1 authentication with PKCE
+- Provides mutation hooks for authenticated actions (like, follow, repost)
+- Built on soundcloud-api-ts
+
+## When to use this package
+- Building a Next.js app that needs SoundCloud data
+- Building a music discovery or streaming app with React
+- Need to search SoundCloud tracks, users, or playlists from a React app
+- Need SoundCloud OAuth login in a Next.js app
+- Need a SoundCloud audio player in React
+- Want typed SoundCloud API access without exposing client secrets to the browser
+
+## When NOT to use this package
+- Not using React or Next.js (use soundcloud-api-ts directly instead)
+- Building a backend-only service (use soundcloud-api-ts directly)
+- Need to download or scrape SoundCloud content (this is an API client, not a scraper)
+
+## Installation
+npm install soundcloud-api-ts-next
+
+## Quick Setup
+1. Create API routes: import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server"
+2. Wrap app with <SoundCloudProvider apiPrefix="/api/soundcloud">
+3. Use hooks: useTrack, useTrackSearch, useUser, usePlaylist, usePlayer, etc.
+
+## Key Exports (from "soundcloud-api-ts-next")
+
+### Hooks - General
+
+```ts
+function useResolve(url: string | undefined): HookResult<any>
+```
+Resolve a SoundCloud URL (e.g. `https://soundcloud.com/artist/track`) to a track, user, or playlist object.
+
+### Hooks - Tracks
+
+```ts
+function useTrack(trackId: string | number | undefined): HookResult<SoundCloudTrack>
+```
+Fetch a single track by ID.
+
+```ts
+function useTrackSearch(query: string, options?: { limit?: number }): HookResult<SoundCloudTrack[]>
+```
+Search tracks by query string. Optional limit parameter.
+
+```ts
+function useTrackComments(trackId: string | number | undefined): HookResult<SoundCloudComment[]>
+```
+Fetch comments on a track.
+
+```ts
+function useTrackLikes(trackId: string | number | undefined): HookResult<SoundCloudUser[]>
+```
+Fetch users who liked a track.
+
+```ts
+function useRelatedTracks(trackId: string | number | undefined): HookResult<SoundCloudTrack[]>
+```
+Fetch tracks related to the given track.
+
+```ts
+function usePlayer(trackId: string | number | undefined): PlayerState
+```
+Audio player hook. Returns:
+```ts
+interface PlayerState {
+  playing: boolean;
+  progress: number;   // current position in seconds
+  duration: number;    // total duration in seconds
+  play: () => void;
+  pause: () => void;
+  toggle: () => void;
+  seek: (time: number) => void;
+}
+```
+
+### Hooks - Users
+
+```ts
+function useUser(userId: string | number | undefined): HookResult<SoundCloudUser>
+```
+Fetch a single user by ID.
+
+```ts
+function useUserSearch(query: string): HookResult<SoundCloudUser[]>
+```
+Search users by query string.
+
+```ts
+function useUserTracks(userId: string | number | undefined): HookResult<SoundCloudTrack[]>
+```
+Fetch a user's tracks.
+
+```ts
+function useUserPlaylists(userId: string | number | undefined): HookResult<SoundCloudPlaylist[]>
+```
+Fetch a user's playlists.
+
+```ts
+function useUserLikes(userId: string | number | undefined): HookResult<SoundCloudTrack[]>
+```
+Fetch a user's liked tracks.
+
+```ts
+function useUserFollowers(userId: string | number | undefined): HookResult<SoundCloudUser[]>
+```
+Fetch a user's followers.
+
+```ts
+function useUserFollowings(userId: string | number | undefined): HookResult<SoundCloudUser[]>
+```
+Fetch a user's followings.
+
+### Hooks - Playlists
+
+```ts
+function usePlaylist(playlistId: string | number | undefined): HookResult<SoundCloudPlaylist>
+```
+Fetch a single playlist by ID.
+
+```ts
+function usePlaylistSearch(query: string): HookResult<SoundCloudPlaylist[]>
+```
+Search playlists by query string.
+
+```ts
+function usePlaylistTracks(playlistId: string | number | undefined): HookResult<SoundCloudTrack[]>
+```
+Fetch tracks in a playlist.
+
+### Hooks - Infinite Scroll
+
+All infinite hooks return:
+```ts
+interface InfiniteResult<T> {
+  data: T[];
+  loading: boolean;
+  error: Error | null;
+  hasMore: boolean;
+  loadMore: () => void;
+  reset: () => void;
+}
+```
+
+```ts
+function useInfiniteTrackSearch(query: string, options?: { limit?: number }): InfiniteResult<SoundCloudTrack>
+function useInfiniteUserSearch(query: string, options?: { limit?: number }): InfiniteResult<SoundCloudUser>
+function useInfinitePlaylistSearch(query: string, options?: { limit?: number }): InfiniteResult<SoundCloudPlaylist>
+function useInfiniteUserTracks(userId: string | number | null): InfiniteResult<SoundCloudTrack>
+function useInfiniteUserPlaylists(userId: string | number | null): InfiniteResult<SoundCloudPlaylist>
+function useInfiniteUserLikes(userId: string | number | null): InfiniteResult<SoundCloudTrack>
+function useInfiniteUserFollowers(userId: string | number | null): InfiniteResult<SoundCloudUser>
+function useInfiniteUserFollowings(userId: string | number | null): InfiniteResult<SoundCloudUser>
+function useInfiniteTrackComments(trackId: string | number | null): InfiniteResult<SoundCloudComment>
+function useInfinitePlaylistTracks(playlistId: string | number | null): InfiniteResult<SoundCloudTrack>
+```
+
+### Hooks - Authentication
+
+```ts
+function useSCAuth(): {
+  user: SoundCloudUser | null;
+  isAuthenticated: boolean;
+  loading: boolean;
+  login: () => void;
+  logout: () => void;
+  handleCallback: (code: string, state: string) => Promise<SoundCloudToken>;
+}
+```
+Full OAuth 2.1 with PKCE. Redirects to SoundCloud for login, exchanges code for tokens.
+
+```ts
+function useMe(): HookResult<SoundCloudUser>
+```
+Current authenticated user profile.
+
+```ts
+function useMeTracks(): HookResult<SoundCloudTrack[]>
+```
+Current user's tracks.
+
+```ts
+function useMeLikes(): HookResult<SoundCloudTrack[]>
+```
+Current user's liked tracks.
+
+```ts
+function useMePlaylists(): HookResult<SoundCloudPlaylist[]>
+```
+Current user's playlists.
+
+```ts
+function useMeFollowings(): HookResult<SoundCloudUser[]>
+```
+Users the current user follows.
+
+```ts
+function useMeFollowers(): HookResult<SoundCloudUser[]>
+```
+Current user's followers.
+
+### Hooks - Actions (authenticated)
+
+```ts
+function useLike(): {
+  likeTrack: (trackId: string | number) => Promise<void>;
+  unlikeTrack: (trackId: string | number) => Promise<void>;
+  loading: boolean;
+  error: Error | null;
+}
+```
+Like or unlike a track. Requires authentication.
+
+```ts
+function useFollow(): {
+  follow: (userId: string | number) => Promise<void>;
+  unfollow: (userId: string | number) => Promise<void>;
+  loading: boolean;
+  error: Error | null;
+}
+```
+Follow or unfollow a user. Requires authentication.
+
+```ts
+function useRepost(): {
+  repostTrack: (trackId: string | number) => Promise<void>;
+  unrepostTrack: (trackId: string | number) => Promise<void>;
+  loading: boolean;
+  error: Error | null;
+}
+```
+Repost or unrepost a track. Requires authentication.
+
+### Provider
+
+```tsx
+<SoundCloudProvider apiPrefix="/api/soundcloud">
+  {children}
+</SoundCloudProvider>
+```
+Wraps app, configures API route prefix, manages auth state.
+
+## Key Exports (from "soundcloud-api-ts-next/server")
+
+```ts
+function createSoundCloudRoutes(config: {
+  clientId: string;
+  clientSecret: string;
+  redirectUri?: string;
+  getToken?: () => Promise<string>;  // custom token provider (e.g. Redis, database)
+}): SoundCloudRoutes
+```
+
+Returns an object with:
+- `.handler()` — App Router catch-all handler (assign to GET, POST, DELETE)
+- `.pagesHandler()` — Pages Router catch-all handler
+- `.resolveUrl(url)` — resolve a SoundCloud URL to an API resource
+- `.searchTracks(q)`, `.getTrack(id)`, `.getUser(id)`, etc. — individual server-side methods
+
+When `getToken` is provided, it replaces the built-in client credentials flow for all public routes. Auth routes (`/me/*`, actions) still use the `Authorization: Bearer` header from the request.
+
+## Common Types
+
+```ts
+interface HookResult<T> {
+  data: T | null;
+  loading: boolean;
+  error: Error | null;
+}
+
+interface InfiniteResult<T> {
+  data: T[];
+  loading: boolean;
+  error: Error | null;
+  hasMore: boolean;
+  loadMore: () => void;
+  reset: () => void;
+}
+
+interface PlayerState {
+  playing: boolean;
+  progress: number;
+  duration: number;
+  play: () => void;
+  pause: () => void;
+  toggle: () => void;
+  seek: (time: number) => void;
+}
+
+interface SoundCloudRoutesConfig {
+  clientId: string;
+  clientSecret: string;
+  redirectUri?: string;
+  getToken?: () => Promise<string>;
+}
+
+interface SoundCloudToken {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  token_type: string;
+  scope: string;
+}
+```
+
+## TypeScript types (re-exported from soundcloud-api-ts)
+SoundCloudTrack, SoundCloudUser, SoundCloudPlaylist, SoundCloudComment, SoundCloudStreams, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudWebProfile, SoundCloudActivity, SoundCloudActivitiesResponse
+
+## Related packages
+- soundcloud-api-ts — TypeScript-first SoundCloud API client (dependency)
+
+## Links
+- npm: https://www.npmjs.com/package/soundcloud-api-ts-next
+- GitHub: https://github.com/twin-paws/soundcloud-api-ts-next
+- API Docs: https://twin-paws.github.io/soundcloud-api-ts-next/
+- API client: https://github.com/twin-paws/soundcloud-api-ts

package/llms.txt

@@ -0,0 +1,104 @@
+# soundcloud-api-ts-next
+
+> React hooks and Next.js API route handlers for the SoundCloud API. Client secrets stay on the server.
+
+## What this package does
+- Provides 25+ React hooks for accessing SoundCloud data (tracks, users, playlists, search)
+- Provides 10 infinite scroll hooks with cursor-based pagination
+- Provides secure Next.js API route handlers that keep OAuth credentials server-side
+- Provides full OAuth 2.1 authentication with PKCE
+- Provides mutation hooks for authenticated actions (like, follow, repost)
+- Built on soundcloud-api-ts
+
+## When to use this package
+- Building a Next.js app that needs SoundCloud data
+- Building a music discovery or streaming app with React
+- Need to search SoundCloud tracks, users, or playlists from a React app
+- Need SoundCloud OAuth login in a Next.js app
+- Need a SoundCloud audio player in React
+- Want typed SoundCloud API access without exposing client secrets to the browser
+
+## When NOT to use this package
+- Not using React or Next.js (use soundcloud-api-ts directly instead)
+- Building a backend-only service (use soundcloud-api-ts directly)
+- Need to download or scrape SoundCloud content (this is an API client, not a scraper)
+
+## Installation
+npm install soundcloud-api-ts-next
+
+## Quick Setup
+1. Create API routes: import { createSoundCloudRoutes } from "soundcloud-api-ts-next/server"
+2. Wrap app with <SoundCloudProvider apiPrefix="/api/soundcloud">
+3. Use hooks: useTrack, useTrackSearch, useUser, usePlaylist, usePlayer, etc.
+
+## Key Exports (from "soundcloud-api-ts-next")
+### Hooks - General
+- useResolve(url) — resolve a SoundCloud URL to a track, user, or playlist
+
+### Hooks - Tracks
+- useTrack(trackId) — fetch single track
+- useTrackSearch(query) — search tracks
+- useTrackComments(trackId) — track comments
+- useTrackLikes(trackId) — users who liked track
+- useRelatedTracks(trackId) — related tracks
+- usePlayer(streamUrl) — audio player with play/pause/seek
+
+### Hooks - Users
+- useUser(userId) — fetch single user
+- useUserSearch(query) — search users
+- useUserTracks(userId) — user's tracks
+- useUserPlaylists(userId) — user's playlists
+- useUserLikes(userId) — user's liked tracks
+- useUserFollowers(userId) — user's followers
+- useUserFollowings(userId) — user's followings
+
+### Hooks - Playlists
+- usePlaylist(playlistId) — fetch single playlist
+- usePlaylistSearch(query) — search playlists
+- usePlaylistTracks(playlistId) — playlist tracks
+
+### Hooks - Infinite Scroll
+All return { data: T[], loading, error, hasMore, loadMore, reset }
+- useInfiniteTrackSearch, useInfiniteUserSearch, useInfinitePlaylistSearch
+- useInfiniteUserTracks, useInfiniteUserPlaylists, useInfiniteUserLikes
+- useInfiniteUserFollowers, useInfiniteUserFollowings
+- useInfiniteTrackComments, useInfinitePlaylistTracks
+
+### Hooks - Authentication
+- useSCAuth() — { isAuthenticated, user, login, logout, handleCallback }
+- useMe() — current user profile
+- useMeTracks() — your tracks
+- useMeLikes() — your liked tracks
+- useMePlaylists() — your playlists
+- useMeFollowings() — who you follow
+- useMeFollowers() — your followers
+
+### Hooks - Actions (authenticated)
+- useLike() — { likeTrack(id), unlikeTrack(id) }
+- useFollow() — { follow(userId), unfollow(userId) }
+- useRepost() — { repostTrack(id), unrepostTrack(id) }
+
+### Provider
+- SoundCloudProvider — wraps app, configures API route prefix
+
+## Key Exports (from "soundcloud-api-ts-next/server")
+- createSoundCloudRoutes({ clientId, clientSecret, redirectUri?, getToken? }) — creates route handlers
+  - getToken: optional async function returning a token string (for custom token stores like Redis)
+  - .handler() — App Router catch-all (assign to GET, POST, DELETE)
+  - .pagesHandler() — Pages Router catch-all
+  - .resolveUrl(url) — resolve a SoundCloud URL server-side
+  - .searchTracks(q), .getTrack(id), .getUser(id), etc. — individual methods
+
+## All hooks return
+{ data: T | null, loading: boolean, error: Error | null }
+
+## TypeScript types (re-exported from soundcloud-api-ts)
+SoundCloudTrack, SoundCloudUser, SoundCloudPlaylist, SoundCloudComment, SoundCloudStreams, SoundCloudToken
+
+## Related packages
+- soundcloud-api-ts — TypeScript-first SoundCloud API client (dependency)
+
+## Links
+- npm: https://www.npmjs.com/package/soundcloud-api-ts-next
+- GitHub: https://github.com/twin-paws/soundcloud-api-ts-next
+- API client: https://github.com/twin-paws/soundcloud-api-ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soundcloud-api-ts-next",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "TypeScript SoundCloud API React hooks and Next.js API route handlers — App Router, Pages Router, OAuth PKCE, secrets stay server-side",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,10 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "llms.txt",
+    "llms-full.txt",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsup",