soundcloud-api-ts 1.12.0 → 1.13.1

package/AGENTS.md

@@ -131,6 +131,11 @@ try {
 8. **Deduplication** — concurrent identical GETs share a single in-flight promise (`dedupe: true` by default). Prevents redundant fetches in SSR or concurrent component trees.
 9. **Cache** — pass a `SoundCloudCache` implementation in the constructor to cache GET responses. Base package defines the interface only; bring your own backend. `cacheTtlMs` defaults to 60000ms.
 10. **Retry hook** — pass `onRetry` to receive `RetryInfo` on each retry: `{ attempt, delayMs, reason, status?, url }`.
+11. **`sc.tracks.getTracks(ids[])`** — batch fetch multiple tracks by ID array in a single request. Returns `SoundCloudTrack[]` (may be shorter than input if some tracks are unavailable).
+12. **`sc.me.getConnections()`** — list linked social accounts. Requires user token. May require elevated API access.
+13. **TokenProvider / TokenStore interfaces** — in `src/auth/token-provider.ts`. Implement to integrate with NextAuth, Clerk, Redis, or any session framework. See `docs/auth-guide.md`.
+14. **Auth guide** — `docs/auth-guide.md` covers: client creds vs user tokens, full PKCE flow, auto-refresh, NextAuth/Clerk bridge patterns, 401 troubleshooting table (invalid_client / insufficient_scope / invalid_token / unauthorized_client).
+15. **OpenAPI tooling** — `pnpm openapi:sync` fetches the spec (if available), `pnpm openapi:coverage` reports implemented vs total. `src/client/registry.ts` is the source of truth — update it when adding new endpoints.
 6. **No env vars** — the package reads no environment variables. Pass `clientId`, `clientSecret`, and `redirectUri` directly to the constructor.
 7. **IDs can be numbers or strings** — all ID parameters accept `string | number`.
 8. **Search pagination** — search uses zero-based `pageNumber` (10 results per page), not cursor-based pagination.
@@ -141,9 +146,14 @@ try {
 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/http.ts               — scFetch, scFetchUrl (HTTP layer with retry + RetryInfo hook)
   client/paginate.ts           — paginate, paginateItems, fetchAll helpers
+  client/raw.ts                — RawClient (sc.raw escape hatch)
+  client/dedupe.ts             — InFlightDeduper (GET coalescing)
+  client/cache.ts              — SoundCloudCache interface
+  client/registry.ts           — IMPLEMENTED_OPERATIONS (OpenAPI coverage tracking)
   auth/                        — Standalone auth functions + PKCE
+  auth/token-provider.ts       — TokenProvider + TokenStore interfaces
   users/                       — Standalone user functions (getMe, getUser, etc.)
   tracks/                      — Standalone track functions
   playlists/                   — Standalone playlist functions

package/README.md

@@ -11,28 +11,26 @@
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)]()
 [![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)
+[![Endpoints](https://img.shields.io/badge/endpoints-51%20wrapped-blue)](https://github.com/twin-paws/soundcloud-api-ts/blob/main/src/client/registry.ts)
 
-soundcloud-api-ts is a TypeScript-first SoundCloud API client for accessing tracks, users, playlists, and search endpoints using modern async/await APIs.
-
-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.
+The TypeScript SoundCloud API client built on the official API. Zero runtime dependencies, native `fetch`, OAuth 2.1 + PKCE, production-grade retry and deduplication, pluggable cache, raw escape hatch, and an interactive CLI.
 
 ## 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:
+Most TypeScript SoundCloud clients fall into one of two categories: unmaintained wrappers that predate OAuth 2.1, or scrapers that harvest undocumented `api-v2` client IDs from browser dev tools and break whenever SoundCloud ships a frontend update. soundcloud-api-ts is neither.
 
-- **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
-- **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`
-- **Clean API** — `sc.tracks.getTrack(id)` not `getTrack(token, id)`
-- **Automatic retry** — exponential backoff on 429 and 5xx
-- **Dual ESM/CJS output** — works everywhere
-- **LLM-friendly** — includes `llms.txt` and `AGENTS.md` for AI coding agents
+It is built on SoundCloud's **official documented API** with registered app credentials, OAuth 2.1 + PKCE, and a production-grade HTTP layer — all with zero runtime dependencies.
+
+- **Official API only** — `api.soundcloud.com` + `secure.soundcloud.com` OAuth. No `api-v2` scraping, no harvested client IDs, no terms violations.
+- **TypeScript-first** — full types ship in the package. No `@types/*` installs, no casting to `any`.
+- **Zero dependencies** — native `fetch`, nothing in `node_modules` at runtime. 4.5 KB min+gz.
+- **Production HTTP layer** — exponential backoff on 429/5xx, `Retry-After` header respected, in-flight GET deduplication, pluggable cache interface, `onRetry` hook.
+- **Runtime portable** — inject your own `fetch` and `AbortController` for Cloudflare Workers, Bun, Deno, and Edge runtimes.
+- **Raw escape hatch** — `sc.raw.get('/any/endpoint/{id}', { id })` calls anything in the spec, not just wrapped endpoints. Never blocked by a missing wrapper.
+- **Full auth support** — client credentials flow for server-to-server, authorization code + PKCE for user-context operations, auto token refresh on 401.
+- **Pagination built-in** — async iterators and `fetchAll` helpers across all paginated endpoints.
+- **Interactive CLI** — `sc-cli tracks <id>`, `sc-cli search <query>`, `sc-cli me` from your terminal.
+- **LLM-friendly** — ships `llms.txt`, `llms-full.txt`, and `AGENTS.md` for AI coding agents.
 
 ## Comparison
 
@@ -40,22 +38,23 @@ Unlike legacy JavaScript SoundCloud SDKs and community wrappers that require sep
 | --- | --- | --- | --- |
 | TypeScript | ✅ Native | ✅ | ✅ |
 | Dependencies | **0** | 1 | 3 (lodash, cookie, undici) |
-| Bundle size (min+gz) | **4.5 KB** | ❌ unbundlable (native binary) | 191 KB |
-| Auth method | **Official OAuth 2.1** | ⚠️ Scrape client ID from browser | ⚠️ Scrape client ID from browser |
+| Bundle size (min+gz) | **4.5 KB** | ❌ unbundlable | 191 KB |
+| Auth method | **Official OAuth 2.1** | ⚠️ Scrapes client ID | ⚠️ Scrapes client ID |
 | PKCE support | ✅ | ❌ | ❌ |
-| Auto token refresh | ✅ on 401 | ❌ | ❌ |
-| Auto retry (429/5xx) | ✅ exponential backoff | ❌ | ❌ |
+| Auto token refresh | ✅ | ❌ | ❌ |
+| Auto retry (429/5xx) | ✅ + Retry-After | ❌ | ❌ |
+| In-flight deduplication | ✅ | ❌ | ❌ |
+| Pluggable cache interface | ✅ | ❌ | ❌ |
+| Fetch injection (Workers/Bun/Deno) | ✅ | ❌ | ❌ |
+| Raw escape hatch | ✅ `sc.raw` | ❌ | ❌ |
 | CLI tool | ✅ `sc-cli` | ❌ | ❌ |
 | Pagination helpers | ✅ async iterators | ❌ | ✅ |
 | Typed errors | ✅ `SoundCloudError` | ❌ | ❌ |
 | Test coverage | **100%** | — | — |
 | API docs site | ✅ [TypeDoc](https://twin-paws.github.io/soundcloud-api-ts/) | ✅ | ❌ |
 | LLM/AI-friendly | ✅ llms.txt + AGENTS.md | ❌ | ❌ |
-| Maintained | ✅ 2026 | ✅ 2025 | ✅ 2026 |
 
-> **Why does auth method matter?** `soundcloud.ts` and `soundcloud-fetch` use SoundCloud's undocumented internal `api-v2` and require you to scrape your client ID from browser dev tools. This can break anytime SoundCloud changes their frontend, and may violate the [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use) which state *"you must register your app"* and *"any attempt to circumvent this and obtain a new client ID and Security Code is strictly prohibited."*
->
-> `soundcloud-api-ts` uses the **official documented API** (`api.soundcloud.com`) with registered app credentials, OAuth 2.1 via `secure.soundcloud.com` as specified by SoundCloud, PKCE for public clients, and automatic token refresh.
+> **Why does auth method matter?** `soundcloud.ts` and `soundcloud-fetch` scrape SoundCloud's undocumented `api-v2` and require harvesting a client ID from browser dev tools. This breaks whenever SoundCloud ships a frontend update, and the [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use) explicitly prohibit it: *"any attempt to circumvent this and obtain a new client ID and Security Code is strictly prohibited."*
 
 **Coming from `soundcloud.ts`?** See the [Migration Guide](docs/MIGRATING.md) — most changes are find-and-replace.
 
@@ -182,6 +181,17 @@ await sc.auth.signOut(token.access_token);
 sc.clearToken();
 ```
 
+### Auth at a glance
+
+| Endpoint category | Client Credentials | User Token |
+|---|---|---|
+| tracks, users, search, playlists, resolve | ✅ | ✅ |
+| /me endpoints | ❌ | ✅ |
+| likes, reposts | ❌ | ✅ |
+| create/update/delete | ❌ | ✅ |
+
+See [Auth Guide](docs/auth-guide.md) for full details, token provider patterns, and troubleshooting.
+
 ## Client Class
 
 The `SoundCloudClient` class organizes all endpoints into namespaces. Token is resolved automatically when `setToken()` has been called. Override per-call via `{ token: "..." }` options object.
@@ -216,6 +226,7 @@ sc.me.unfollow(userUrn, options?)
 sc.me.getFollowers(limit?, options?)
 sc.me.getPlaylists(limit?, options?)
 sc.me.getTracks(limit?, options?)
+sc.me.getConnections(options?)  // connected social accounts; may require app approval
 
 // Users
 sc.users.getUser(userId, options?)
@@ -229,6 +240,7 @@ sc.users.getWebProfiles(userId, options?)
 
 // Tracks
 sc.tracks.getTrack(trackId, options?)
+sc.tracks.getTracks(ids[], options?)  // batch fetch by IDs
 sc.tracks.getStreams(trackId, options?)
 sc.tracks.getComments(trackId, limit?, options?)
 sc.tracks.createComment(trackId, body, timestamp?, options?)
@@ -577,6 +589,7 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 ## Related Packages
 
 - **[soundcloud-api-ts-next](https://github.com/twin-paws/soundcloud-api-ts-next)** — React hooks + Next.js API route handlers built on this package. Use it when building Next.js apps that need SoundCloud data with secrets kept server-side.
+- **[soundcloud-widget-react](https://github.com/twin-paws/soundcloud-widget-react)** — React component for the SoundCloud HTML5 Widget API. Embed SoundCloud players and control playback programmatically. Complements this package for full SoundCloud integration.
 
 ## Contributing
 

package/dist/{chunk-JLRQJWU5.mjs → chunk-CCHK5S6S.mjs}

@@ -353,6 +353,14 @@ var RawClient = class {
   }
 };
 
+// src/utils/base64.ts
+var toBase64 = (value) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value).toString("base64");
+  }
+  return btoa(value);
+};
+
 // src/client/SoundCloudClient.ts
 function resolveToken(tokenGetter, explicit) {
   const t = explicit ?? tokenGetter();
@@ -559,9 +567,7 @@ var SoundCloudClient = class _SoundCloudClient {
      * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
      */
     async getClientToken() {
-      const basicAuth = Buffer.from(
-        `${this.config.clientId}:${this.config.clientSecret}`
-      ).toString("base64");
+      const basicAuth = toBase64(`${this.config.clientId}:${this.config.clientSecret}`);
       return this.fetch({
         path: "/oauth/token",
         method: "POST",
@@ -620,13 +626,15 @@ var SoundCloudClient = class _SoundCloudClient {
      * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
      */
     async refreshUserToken(refreshToken) {
+      const basicAuth = toBase64(`${this.config.clientId}:${this.config.clientSecret}`);
       return this.fetch({
         path: "/oauth/token",
         method: "POST",
+        headers: {
+          Authorization: `Basic ${basicAuth}`
+        },
         body: new URLSearchParams({
           grant_type: "refresh_token",
-          client_id: this.config.clientId,
-          client_secret: this.config.clientSecret,
           redirect_uri: this.config.redirectUri,
           refresh_token: refreshToken
         })
@@ -872,6 +880,27 @@ var SoundCloudClient = class _SoundCloudClient {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
+    /**
+     * List the authenticated user's connected external social accounts.
+     *
+     * @param options - Optional token override
+     * @returns Array of connection objects for linked social services (Twitter, Facebook, etc.)
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @remarks This endpoint may require elevated API access or app approval.
+     *
+     * @example
+     * ```ts
+     * const connections = await sc.me.getConnections();
+     * connections.forEach(c => console.log(c.service, c.display_name));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
+     */
+    async getConnections(options) {
+      const t = resolveToken(this.getToken, options?.token);
+      return this.fetch({ path: "/me/connections", method: "GET", token: t });
+    }
   }
   SoundCloudClient2.Me = Me;
   class Users {
@@ -1043,6 +1072,34 @@ var SoundCloudClient = class _SoundCloudClient {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}`, method: "GET", token: t });
     }
+    /**
+     * Fetch multiple tracks by their IDs in a single request.
+     *
+     * @param ids - Array of track IDs (numeric or string URNs)
+     * @param options - Optional token override
+     * @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
+     * @throws {SoundCloudError} When the API returns an error
+     * @throws {Error} When more than 200 IDs are provided
+     *
+     * @remarks
+     * SoundCloud's API likely caps at ~200 IDs per request. Passing more than 200 IDs
+     * will throw immediately without making a network request.
+     *
+     * @example
+     * ```ts
+     * const tracks = await sc.tracks.getTracks([123456, 234567, 345678]);
+     * tracks.forEach(t => console.log(t.title));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
+     */
+    async getTracks(ids, options) {
+      if (ids.length > 200) {
+        throw new Error("getTracks: SoundCloud API supports a maximum of 200 IDs per request");
+      }
+      const t = resolveToken(this.getToken, options?.token);
+      return this.fetch({ path: `/tracks?ids=${ids.join(",")}`, method: "GET", token: t });
+    }
     /**
      * Get stream URLs for a track.
      *
@@ -1639,6 +1696,7 @@ var IMPLEMENTED_OPERATIONS = [
   "get_me_followers",
   "get_me_playlists",
   "get_me_tracks",
+  "get_me_connections",
   // Users
   "get_users_user_id",
   "get_users_user_id_followers",
@@ -1683,7 +1741,7 @@ var IMPLEMENTED_OPERATIONS = [
 
 // src/auth/getClientToken.ts
 var getClientToken = (clientId, clientSecret) => {
-  const basicAuth = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+  const basicAuth = toBase64(`${clientId}:${clientSecret}`);
   return scFetch({
     path: "/oauth/token",
     method: "POST",
@@ -1715,13 +1773,15 @@ var getUserToken = (clientId, clientSecret, redirectUri, code, codeVerifier) =>
 
 // src/auth/refreshUserToken.ts
 var refreshUserToken = (clientId, clientSecret, redirectUri, refreshToken) => {
+  const basicAuth = toBase64(`${clientId}:${clientSecret}`);
   return scFetch({
     path: "/oauth/token",
     method: "POST",
+    headers: {
+      Authorization: `Basic ${basicAuth}`
+    },
     body: new URLSearchParams({
       grant_type: "refresh_token",
-      client_id: clientId,
-      client_secret: clientSecret,
       redirect_uri: redirectUri,
       refresh_token: refreshToken
     })
@@ -1800,6 +1860,18 @@ var getUserWebProfiles = (token, userId) => scFetch({ path: `/users/${userId}/we
 // src/tracks/getTrack.ts
 var getTrack = (token, trackId) => scFetch({ path: `/tracks/${trackId}`, method: "GET", token });
 
+// src/tracks/getTracks.ts
+var getTracks = (token, ids) => {
+  if (ids.length > 200) {
+    throw new Error("getTracks: SoundCloud API supports a maximum of 200 IDs per request");
+  }
+  return scFetch({
+    path: `/tracks?ids=${ids.join(",")}`,
+    method: "GET",
+    token
+  });
+};
+
 // src/tracks/getComments.ts
 var getTrackComments = (token, trackId, limit) => scFetch({ path: `/tracks/${trackId}/comments?threaded=1&filter_replies=0${limit ? `&limit=${limit}` : ""}&linked_partitioning=true`, method: "GET", token });
 
@@ -1918,6 +1990,9 @@ var getMePlaylists = (token, limit) => scFetch({ path: `/me/playlists?${limit ?
 // src/me/tracks.ts
 var getMeTracks = (token, limit) => scFetch({ path: `/me/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token });
 
+// src/me/connections.ts
+var getMeConnections = (token) => scFetch({ path: "/me/connections", method: "GET", token });
+
 // src/likes/index.ts
 var likePlaylist = async (token, playlistId) => {
   try {
@@ -1973,6 +2048,6 @@ var unrepostPlaylist = async (token, playlistId) => {
 // src/utils/widget.ts
 var getSoundCloudWidgetUrl = (trackId) => `https%3A//api.soundcloud.com/tracks/${trackId}&show_teaser=false&color=%2300a99d&inverse=false&show_user=false&sharing=false&buying=false&liking=false&show_artwork=false&show_name=false`;
 
-export { IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, SoundCloudClient, createPlaylist, createTrackComment, deletePlaylist, deleteTrack, fetchAll, followUser, generateCodeChallenge, generateCodeVerifier, getAuthorizationUrl, getClientToken, getFollowers, getFollowings, getMe, getMeActivities, getMeActivitiesOwn, getMeActivitiesTracks, getMeFollowers, getMeFollowings, getMeFollowingsTracks, getMeLikesPlaylists, getMeLikesTracks, getMePlaylists, getMeTracks, getPlaylist, getPlaylistReposts, getPlaylistTracks, getRelatedTracks, getSoundCloudWidgetUrl, getTrack, getTrackComments, getTrackLikes, getTrackReposts, getTrackStreams, getUser, getUserLikesPlaylists, getUserLikesTracks, getUserPlaylists, getUserToken, getUserTracks, getUserWebProfiles, likePlaylist, likeTrack, paginate, paginateItems, refreshUserToken, repostPlaylist, repostTrack, resolveUrl, scFetch, scFetchUrl, searchPlaylists, searchTracks, searchUsers, signOut, unfollowUser, unlikePlaylist, unlikeTrack, unrepostPlaylist, unrepostTrack, updatePlaylist, updateTrack };
-//# sourceMappingURL=chunk-JLRQJWU5.mjs.map
-//# sourceMappingURL=chunk-JLRQJWU5.mjs.map
+export { IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, SoundCloudClient, createPlaylist, createTrackComment, deletePlaylist, deleteTrack, fetchAll, followUser, generateCodeChallenge, generateCodeVerifier, getAuthorizationUrl, getClientToken, getFollowers, getFollowings, getMe, getMeActivities, getMeActivitiesOwn, getMeActivitiesTracks, getMeConnections, getMeFollowers, getMeFollowings, getMeFollowingsTracks, getMeLikesPlaylists, getMeLikesTracks, getMePlaylists, getMeTracks, getPlaylist, getPlaylistReposts, getPlaylistTracks, getRelatedTracks, getSoundCloudWidgetUrl, getTrack, getTrackComments, getTrackLikes, getTrackReposts, getTrackStreams, getTracks, getUser, getUserLikesPlaylists, getUserLikesTracks, getUserPlaylists, getUserToken, getUserTracks, getUserWebProfiles, likePlaylist, likeTrack, paginate, paginateItems, refreshUserToken, repostPlaylist, repostTrack, resolveUrl, scFetch, scFetchUrl, searchPlaylists, searchTracks, searchUsers, signOut, unfollowUser, unlikePlaylist, unlikeTrack, unrepostPlaylist, unrepostTrack, updatePlaylist, updateTrack };
+//# sourceMappingURL=chunk-CCHK5S6S.mjs.map
+//# sourceMappingURL=chunk-CCHK5S6S.mjs.map