soundcloud-api-ts 1.13.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,7 +11,7 @@
 [![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)
-[![OpenAPI Coverage](https://img.shields.io/badge/OpenAPI%20coverage-tracked-blue)](tools/coverage-baseline.json)
+[![Endpoints](https://img.shields.io/badge/endpoints-51%20wrapped-blue)](https://github.com/twin-paws/soundcloud-api-ts/blob/main/src/client/registry.ts)
 
 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.
 
@@ -589,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-JH7TLL2C.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
         })
@@ -1071,6 +1079,11 @@ var SoundCloudClient = class _SoundCloudClient {
      * @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
@@ -1081,6 +1094,9 @@ var SoundCloudClient = class _SoundCloudClient {
      * @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 });
     }
@@ -1725,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",
@@ -1757,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
     })
@@ -1843,11 +1861,16 @@ var getUserWebProfiles = (token, userId) => scFetch({ path: `/users/${userId}/we
 var getTrack = (token, trackId) => scFetch({ path: `/tracks/${trackId}`, method: "GET", token });
 
 // src/tracks/getTracks.ts
-var getTracks = (token, ids) => scFetch({
-  path: `/tracks?ids=${ids.join(",")}`,
-  method: "GET",
-  token
-});
+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 });
@@ -2026,5 +2049,5 @@ var unrepostPlaylist = async (token, playlistId) => {
 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, 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-JH7TLL2C.mjs.map
-//# sourceMappingURL=chunk-JH7TLL2C.mjs.map
+//# sourceMappingURL=chunk-CCHK5S6S.mjs.map
+//# sourceMappingURL=chunk-CCHK5S6S.mjs.map