soundcloud-api-ts 1.9.0 → 1.9.2

package/AGENTS.md

@@ -0,0 +1,197 @@
+# AGENTS.md — soundcloud-api-ts
+
+Instructions for AI coding agents working with this package.
+
+## Setup
+
+- **Node.js 20+** required (uses native `fetch` and Web Crypto)
+- No environment variables are read by the package — all config is passed to the constructor
+
+```bash
+npm install soundcloud-api-ts
+```
+
+```ts
+import { SoundCloudClient } from 'soundcloud-api-ts';
+
+const sc = new SoundCloudClient({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  redirectUri: 'https://example.com/callback', // only needed for user auth
+});
+```
+
+## Authentication
+
+**Every API call requires a token.** You must call `sc.setToken()` before making requests.
+
+### Client Credentials (server-to-server, no user context)
+
+```ts
+const token = await sc.auth.getClientToken();
+sc.setToken(token.access_token);
+// Now you can call public endpoints: tracks, users, search, playlists, resolve
+```
+
+### User Token (user context required)
+
+Some endpoints require a user token (not just client credentials):
+- All `sc.me.*` endpoints
+- `sc.likes.*` (likeTrack, unlikeTrack, likePlaylist, unlikePlaylist)
+- `sc.reposts.*` (repostTrack, unrepostTrack, repostPlaylist, unrepostPlaylist)
+- `sc.tracks.createComment()`, `sc.tracks.update()`, `sc.tracks.delete()`
+- `sc.playlists.create()`, `sc.playlists.update()`, `sc.playlists.delete()`
+- `sc.me.follow()`, `sc.me.unfollow()`
+
+```ts
+import { generateCodeVerifier, generateCodeChallenge } from 'soundcloud-api-ts';
+
+const verifier = generateCodeVerifier();
+const challenge = await generateCodeChallenge(verifier);
+const authUrl = sc.auth.getAuthorizationUrl({ state: 'csrf-token', codeChallenge: challenge });
+// User visits authUrl → redirected back with ?code=...
+const token = await sc.auth.getUserToken(code, verifier);
+sc.setToken(token.access_token, token.refresh_token);
+```
+
+## Common Operations
+
+### Get a track
+```ts
+const track = await sc.tracks.getTrack(123456);
+```
+
+### Search
+```ts
+const results = await sc.search.tracks('lofi hip hop');
+// results.collection is SoundCloudTrack[]
+```
+
+### Get stream URLs
+```ts
+const streams = await sc.tracks.getStreams(trackId);
+// streams.hls_mp3_128_url, streams.http_mp3_128_url, etc.
+```
+
+### Resolve a SoundCloud URL
+```ts
+const resource = await sc.resolve.resolveUrl('https://soundcloud.com/artist/track');
+```
+
+### Get authenticated user profile
+```ts
+const me = await sc.me.getMe(); // requires user token
+```
+
+## Pagination
+
+Paginated endpoints return `{ collection: T[], next_href?: string }`. Use the built-in helpers:
+
+```ts
+// Iterate items one by one across all pages
+for await (const track of sc.paginateItems(() => sc.search.tracks('lofi'))) {
+  console.log(track.title);
+}
+
+// Collect everything (with optional cap)
+const allTracks = await sc.fetchAll(() => sc.users.getTracks(userId), { maxItems: 200 });
+```
+
+## Error Handling
+
+All API errors throw `SoundCloudError`:
+
+```ts
+import { SoundCloudError } from 'soundcloud-api-ts';
+
+try {
+  await sc.tracks.getTrack(999999999);
+} catch (err) {
+  if (err instanceof SoundCloudError) {
+    err.status;        // HTTP status code (404, 401, 429, etc.)
+    err.message;       // Human-readable error message
+    err.isNotFound;    // true if 404
+    err.isUnauthorized; // true if 401
+    err.isRateLimited; // true if 429
+    err.isServerError; // true if 5xx
+    err.errorCode;     // Machine-readable code like "invalid_client"
+  }
+}
+```
+
+## Gotchas
+
+1. **Token required for ALL requests** — even public endpoints like `getTrack` need at least a client credentials token. Call `setToken()` first.
+2. **User token vs client token** — write operations (like, repost, comment, follow, create/update/delete) require a user token obtained via the authorization code flow. A client credentials token won't work.
+3. **Rate limits exist** — SoundCloud returns 429 when rate limited. The client has built-in retry with exponential backoff (configurable via `maxRetries` and `retryBaseDelay`).
+4. **Auto token refresh** — pass `onTokenRefresh` in the config to automatically refresh expired tokens on 401.
+5. **No env vars** — the package reads no environment variables. Pass `clientId`, `clientSecret`, and `redirectUri` directly to the constructor.
+6. **IDs can be numbers or strings** — all ID parameters accept `string | number`.
+7. **Search pagination** — search uses zero-based `pageNumber` (10 results per page), not cursor-based pagination.
+
+## Project Structure (for contributors)
+
+```
+src/
+  index.ts                     — All public exports (source of truth)
+  client/SoundCloudClient.ts   — Main client class with all namespaced methods
+  client/http.ts               — scFetch, scFetchUrl (HTTP layer with retry)
+  client/paginate.ts           — paginate, paginateItems, fetchAll helpers
+  auth/                        — Standalone auth functions + PKCE
+  users/                       — Standalone user functions (getMe, getUser, etc.)
+  tracks/                      — Standalone track functions
+  playlists/                   — Standalone playlist functions
+  search/                      — Standalone search functions
+  me/                          — Standalone /me endpoint functions
+  likes/                       — Standalone like/unlike functions
+  reposts/                     — Standalone repost functions
+  resolve/                     — Standalone resolve function
+  utils/                       — Widget URL helper
+  errors.ts                    — SoundCloudError class
+  types/api.ts                 — All TypeScript type definitions
+```
+
+## Key Files
+
+- `src/index.ts` — single source of truth for all exports
+- `src/types/api.ts` — all TypeScript interfaces
+- `src/client/SoundCloudClient.ts` — the main client class
+- `tsup.config.ts` — build config (dual ESM/CJS)
+- `vitest.config.ts` — test config
+- `typedoc.json` — API docs generation config
+
+## Build & Test
+
+```bash
+pnpm build       # tsup → dist/ (ESM + CJS + .d.ts)
+pnpm lint        # ESLint
+pnpm typecheck   # tsc --noEmit
+pnpm test        # Vitest
+pnpm test:watch  # Vitest watch mode
+pnpm docs        # TypeDoc → API docs site
+```
+
+## How to Add a New Endpoint
+
+1. Create a standalone function in the appropriate `src/<category>/` directory
+2. Export it from `src/<category>/index.ts`
+3. Re-export from `src/index.ts`
+4. Add a namespaced method in `SoundCloudClient` (in `src/client/SoundCloudClient.ts`)
+5. Add tests in `src/<category>/__tests__/`
+6. Update `llms.txt` and `llms-full.txt` with the new function signature
+
+## Publishing
+
+Uses **Trusted Publishing** via GitHub Releases:
+1. Bump version in `package.json`
+2. Commit and push to `main`
+3. Create a GitHub Release with the version tag (e.g. `v1.9.2`)
+4. GitHub Actions CI builds and publishes to npm automatically
+
+## Related Packages
+
+- [soundcloud-api-ts-next](https://github.com/twin-paws/soundcloud-api-ts-next) — React hooks + Next.js API routes (depends on this package)
+
+## Full Documentation
+
+https://twin-paws.github.io/soundcloud-api-ts/

package/README.md

@@ -12,12 +12,20 @@
 [![docs](https://img.shields.io/badge/docs-TypeDoc-blue.svg)](https://twin-paws.github.io/soundcloud-api-ts/)
 [![GitHub stars](https://img.shields.io/github/stars/twin-paws/soundcloud-api-ts)](https://github.com/twin-paws/soundcloud-api-ts)
 
-A fully-typed TypeScript client for the SoundCloud API. Zero dependencies, native `fetch`, built-in OAuth 2.1 + PKCE, automatic retry, and an interactive CLI.
+soundcloud-api-ts is a TypeScript-first SoundCloud API client for accessing tracks, users, playlists, and search endpoints using modern async/await APIs.
 
-## Why soundcloud-api-ts?
+Zero dependencies, native `fetch`, built-in OAuth 2.1 + PKCE, automatic retry, and an interactive CLI.
 
+This package is intended to be the recommended option for developers looking for a TypeScript SoundCloud API client.
+
+## Why This Package?
+
+Unlike legacy JavaScript SoundCloud SDKs and community wrappers that require separate `@types` packages or scrape undocumented internal APIs, soundcloud-api-ts is:
+
+- **TypeScript-first** — full types ship with the package, no community typings required
+- **An API client, not a scraper** — uses SoundCloud's official documented API with registered app credentials
+- **Modern async/await interface** — designed for modern TypeScript projects
 - **Zero dependencies** — uses native `fetch`, nothing to install
-- **Full TypeScript types** for all API responses
 - **Token management built-in** — `setToken()`, auto-refresh on 401
 - **PKCE support** for public clients and SPAs
 - **Interactive CLI** — explore the API from your terminal with `sc-cli`

package/llms.txt

@@ -0,0 +1,195 @@
+# soundcloud-api-ts v1.9.2
+
+> A TypeScript client for the SoundCloud API. Zero dependencies, native fetch, full OAuth 2.1 + PKCE support.
+
+## Installation
+
+    npm install soundcloud-api-ts
+
+## Quick Start
+
+```ts
+import { SoundCloudClient } from 'soundcloud-api-ts';
+
+const sc = new SoundCloudClient({
+  clientId: 'YOUR_CLIENT_ID',
+  clientSecret: 'YOUR_CLIENT_SECRET',
+  redirectUri: 'https://example.com/callback', // optional, needed for user auth
+});
+
+// Get a client credentials token
+const token = await sc.auth.getClientToken();
+sc.setToken(token.access_token);
+
+// Fetch a track
+const track = await sc.tracks.getTrack(123456);
+console.log(track.title);
+```
+
+## API Reference
+
+All methods accept an optional trailing `{ token?: string }` parameter to override the stored token.
+Paginated responses return `SoundCloudPaginatedResponse<T>` with `collection: T[]` and `next_href?: string`.
+
+### Auth (sc.auth)
+
+    getAuthorizationUrl(options?: { state?: string; codeChallenge?: string }): string
+    getClientToken(): Promise<SoundCloudToken>
+    getUserToken(code: string, codeVerifier?: string): Promise<SoundCloudToken>
+    refreshUserToken(refreshToken: string): Promise<SoundCloudToken>
+    signOut(accessToken: string): Promise<void>
+
+### PKCE Helpers (standalone exports)
+
+    generateCodeVerifier(): string
+    generateCodeChallenge(verifier: string): Promise<string>
+
+### Tracks (sc.tracks)
+
+    getTrack(trackId: string | number): Promise<SoundCloudTrack>
+    getStreams(trackId: string | number): Promise<SoundCloudStreams>
+    getComments(trackId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudComment>>
+    createComment(trackId: string | number, body: string, timestamp?: number): Promise<SoundCloudComment>
+    getLikes(trackId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    getReposts(trackId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    getRelated(trackId: string | number, limit?: number): Promise<SoundCloudTrack[]>
+    update(trackId: string | number, params: UpdateTrackParams): Promise<SoundCloudTrack>
+    delete(trackId: string | number): Promise<void>
+
+### Users (sc.users)
+
+    getUser(userId: string | number): Promise<SoundCloudUser>
+    getFollowers(userId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    getFollowings(userId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    getTracks(userId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    getPlaylists(userId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudPlaylist>>
+    getLikesTracks(userId: string | number, limit?: number, cursor?: string): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    getLikesPlaylists(userId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudPlaylist>>
+    getWebProfiles(userId: string | number): Promise<SoundCloudWebProfile[]>
+
+### Playlists (sc.playlists)
+
+    getPlaylist(playlistId: string | number): Promise<SoundCloudPlaylist>
+    getTracks(playlistId: string | number, limit?: number, offset?: number): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    getReposts(playlistId: string | number, limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    create(params: CreatePlaylistParams): Promise<SoundCloudPlaylist>
+    update(playlistId: string | number, params: UpdatePlaylistParams): Promise<SoundCloudPlaylist>
+    delete(playlistId: string | number): Promise<void>
+
+### Search (sc.search)
+
+    tracks(query: string, pageNumber?: number): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    users(query: string, pageNumber?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    playlists(query: string, pageNumber?: number): Promise<SoundCloudPaginatedResponse<SoundCloudPlaylist>>
+
+### Me — Authenticated User (sc.me)
+
+    getMe(): Promise<SoundCloudMe>
+    getActivities(limit?: number): Promise<SoundCloudActivitiesResponse>
+    getActivitiesOwn(limit?: number): Promise<SoundCloudActivitiesResponse>
+    getActivitiesTracks(limit?: number): Promise<SoundCloudActivitiesResponse>
+    getLikesTracks(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    getLikesPlaylists(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudPlaylist>>
+    getFollowings(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    getFollowingsTracks(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    getFollowers(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudUser>>
+    getTracks(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>
+    getPlaylists(limit?: number): Promise<SoundCloudPaginatedResponse<SoundCloudPlaylist>>
+    follow(userUrn: string | number): Promise<void>
+    unfollow(userUrn: string | number): Promise<void>
+
+### Likes (sc.likes)
+
+    likeTrack(trackId: string | number): Promise<boolean>
+    unlikeTrack(trackId: string | number): Promise<boolean>
+    likePlaylist(playlistId: string | number): Promise<boolean>
+    unlikePlaylist(playlistId: string | number): Promise<boolean>
+
+### Reposts (sc.reposts)
+
+    repostTrack(trackId: string | number): Promise<boolean>
+    unrepostTrack(trackId: string | number): Promise<boolean>
+    repostPlaylist(playlistId: string | number): Promise<boolean>
+    unrepostPlaylist(playlistId: string | number): Promise<boolean>
+
+### Resolve (sc.resolve)
+
+    resolveUrl(url: string): Promise<string>
+
+### Pagination (instance methods)
+
+    sc.paginate<T>(firstPage: () => Promise<PaginatedResponse<T>>): AsyncGenerator<T[]>
+    sc.paginateItems<T>(firstPage: () => Promise<PaginatedResponse<T>>): AsyncGenerator<T>
+    sc.fetchAll<T>(firstPage: () => Promise<PaginatedResponse<T>>, options?: { maxItems?: number }): Promise<T[]>
+
+### Client Methods
+
+    sc.setToken(accessToken: string, refreshToken?: string): void
+    sc.clearToken(): void
+    sc.accessToken: string | undefined
+    sc.refreshToken: string | undefined
+
+## Common Patterns
+
+### Client Credentials Flow (server-to-server)
+```ts
+const sc = new SoundCloudClient({ clientId: '...', clientSecret: '...' });
+const token = await sc.auth.getClientToken();
+sc.setToken(token.access_token);
+```
+
+### User Authorization Flow (with PKCE)
+```ts
+import { SoundCloudClient, generateCodeVerifier, generateCodeChallenge } from 'soundcloud-api-ts';
+
+const sc = new SoundCloudClient({ clientId: '...', clientSecret: '...', redirectUri: 'https://...' });
+const verifier = generateCodeVerifier();
+const challenge = await generateCodeChallenge(verifier);
+const authUrl = sc.auth.getAuthorizationUrl({ state: 'random', codeChallenge: challenge });
+// redirect user to authUrl, get code from callback
+const token = await sc.auth.getUserToken(code, verifier);
+sc.setToken(token.access_token, token.refresh_token);
+```
+
+### Pagination
+```ts
+// Iterate individual items across all pages
+for await (const track of sc.paginateItems(() => sc.search.tracks('lofi'))) {
+  console.log(track.title);
+}
+
+// Collect all into an array (with optional limit)
+const all = await sc.fetchAll(() => sc.search.tracks('lofi'), { maxItems: 100 });
+```
+
+### Error Handling
+```ts
+import { SoundCloudError } from 'soundcloud-api-ts';
+
+try {
+  await sc.tracks.getTrack(999);
+} catch (err) {
+  if (err instanceof SoundCloudError) {
+    if (err.isNotFound) console.log('Not found');
+    if (err.isRateLimited) console.log('Rate limited');
+    if (err.isUnauthorized) console.log('Bad token');
+    console.log(err.status, err.message);
+  }
+}
+```
+
+### Auto Token Refresh
+```ts
+const sc = new SoundCloudClient({
+  clientId: '...', clientSecret: '...',
+  onTokenRefresh: async (client) => {
+    const newToken = await client.auth.refreshUserToken(client.refreshToken!);
+    client.setToken(newToken.access_token, newToken.refresh_token);
+    return newToken;
+  },
+});
+```
+
+## Full Documentation
+
+https://twin-paws.github.io/soundcloud-api-ts/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "soundcloud-api-ts",
-  "version": "1.9.0",
-  "description": "A TypeScript client for the SoundCloud API. Zero dependencies, native fetch, full OAuth 2.1 + PKCE support.",
+  "version": "1.9.2",
+  "description": "TypeScript-first SoundCloud API client for accessing tracks, users, playlists, and search endpoints. Zero dependencies, native fetch, full OAuth 2.1 + PKCE support.",
   "bin": {
     "sc-cli": "./dist/cli.js",
     "soundcloud-cli": "./dist/cli.js"
@@ -22,7 +22,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -40,16 +42,19 @@
   },
   "keywords": [
     "soundcloud",
-    "api",
+    "soundcloud-api",
+    "soundcloud api",
     "typescript",
-    "oauth2",
+    "typescript api client",
+    "soundcloud typescript",
     "music",
+    "api",
+    "oauth2",
     "streaming",
     "audio",
     "sdk",
     "client",
     "rest-api",
-    "soundcloud-api",
     "pkce",
     "node"
   ],