soundcloud-api-ts 1.13.4 → 1.14.0

package/AGENTS.md

@@ -125,20 +125,20 @@ try {
 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`). `Retry-After` header is honored (capped 60s).
 4. **Auto token refresh** — pass `onTokenRefresh` in the config to automatically refresh expired tokens on 401.
-5. **Request telemetry** — pass `onRequest` in the config to receive `SCRequestTelemetry` after every request (method, path, duration, status, retries, error). Fires on all paths including pagination and retries.
+5. **Request telemetry** — pass `onRequest` in the config to receive `SCRequestTelemetry` after every client-namespace request (method, path, duration, status, retries, error), including pagination and retries. NOT emitted for `sc.raw.*` or `auth.signOut`.
 6. **sc.raw** — `sc.raw.get('/tracks/{id}', { id: 123456 })` calls any endpoint without a typed wrapper. Returns `RawResponse<T>` with `{ data, status, headers }`. Does NOT throw on non-2xx — check `res.status` yourself. Good for endpoints not yet wrapped.
-7. **Fetch injection** — pass `fetch` and `AbortController` in the constructor for Bun/Deno/Cloudflare Workers portability. No Node-only APIs used at runtime.
-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.
+7. **Fetch injection** — pass `fetch` in the constructor for Bun/Deno/Cloudflare Workers portability. No Node-only APIs used at runtime. There is no `AbortController` option — bake cancellation/timeouts into the `fetch` you inject.
+8. **Deduplication** — concurrent identical GETs through the client namespaces share a single in-flight promise (`dedupe: true` by default; wired up in v1.14.0 — earlier versions accepted but ignored the option). `sc.raw.*` and pagination `next_href` fetches are not deduped.
+9. **Cache** — pass a `SoundCloudCache` implementation in the constructor to cache namespace GET responses (also wired up in v1.14.0). 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).
+11. **`sc.tracks.getTracks(ids[])`** — batch fetch multiple tracks by ID array in a single request. Max 200 IDs — throws immediately above that, before any network call. 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.
+16. **No env vars** — the package reads no environment variables. Pass `clientId`, `clientSecret`, and `redirectUri` directly to the constructor.
+17. **IDs can be numbers or strings** — all ID parameters accept `string | number`.
+18. **Search pagination** — search uses zero-based `pageNumber` (10 results per page), not cursor-based pagination.
 
 ## Project Structure (for contributors)
 

package/README.md

@@ -7,7 +7,7 @@
 [![bundle size](https://img.shields.io/bundlephobia/minzip/soundcloud-api-ts)](https://bundlephobia.com/package/soundcloud-api-ts)
 [![install size](https://packagephobia.com/badge?p=soundcloud-api-ts)](https://packagephobia.com/result?p=soundcloud-api-ts)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
-[![Node](https://img.shields.io/badge/Node.js-≥22-339933.svg)](https://nodejs.org/)
+[![Node](https://img.shields.io/badge/Node.js-≥20-339933.svg)](https://nodejs.org/)
 [![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)
@@ -25,11 +25,11 @@ It is built on SoundCloud's **official documented API** with registered app cred
 - **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.
+- **Runtime portable** — inject your own `fetch` 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.
+- **Interactive CLI** — `sc-cli track <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
@@ -131,9 +131,11 @@ sc.setToken(token.access_token);
 
 // Now all calls use the stored token automatically
 const results = await sc.search.tracks("electronic");
-const me = await sc.me.getMe();
 const track = await sc.tracks.getTrack(123456);
 const streams = await sc.tracks.getStreams(123456);
+
+// /me endpoints need a user token (authorization code flow), not a client token:
+// const me = await sc.me.getMe();
 ```
 
 ## OAuth 2.1 Flow
@@ -240,7 +242,7 @@ sc.users.getWebProfiles(userId, options?)
 
 // Tracks
 sc.tracks.getTrack(trackId, options?)
-sc.tracks.getTracks(ids[], options?)  // batch fetch by IDs
+sc.tracks.getTracks(ids[], options?)  // batch fetch by IDs (max 200, throws above)
 sc.tracks.getStreams(trackId, options?)
 sc.tracks.getComments(trackId, limit?, options?)
 sc.tracks.createComment(trackId, body, timestamp?, options?)
@@ -277,12 +279,12 @@ sc.search.playlists(query, pageNumber?, options?)
 
 // Resolve
 sc.resolve.resolveUrl(url, options?)
-```
 
 // Raw escape hatch — call any endpoint
 sc.raw.get('/tracks/{id}', { id: 123456 })
 sc.raw.post('/tracks/{id}/comments', { body: { body: 'great track' } })
 sc.raw.request({ method: 'GET', path: '/me', query: {} })
+```
 
 Where `options` is `{ token?: string }` — only needed to override the stored token.
 
@@ -461,6 +463,10 @@ const sc = new SoundCloudClient({
 });
 ```
 
+Dedupe and cache apply to GETs made through the client namespaces (`sc.tracks.*`, `sc.users.*`, …). `sc.raw.*` and pagination `next_href` continuation fetches are not deduped or cached.
+
+> **Note:** the `dedupe`, `cache`, and `cacheTtlMs` options were accepted but not actually wired up in v1.12.0–v1.13.4 — they take effect from v1.14.0.
+
 ### Pluggable Cache
 
 Bring your own cache backend — in-memory, Redis, Cloudflare KV, whatever. The base package defines the interface only (no implementation, no deps):
@@ -490,12 +496,11 @@ Pass a custom `fetch` implementation to work in any runtime — Cloudflare Worke
 ```ts
 const sc = new SoundCloudClient({
   clientId, clientSecret,
-  fetch: myCustomFetch,          // optional: custom fetch
-  AbortController: myAbortCtrl, // optional: custom AbortController
+  fetch: myCustomFetch, // optional: custom fetch (defaults to globalThis.fetch)
 });
 ```
 
-No Node-only APIs are used at runtime. The client works anywhere `fetch` is available.
+No Node-only APIs are used at runtime. The client works anywhere `fetch` is available. There is no `AbortController` option — if you need cancellation or timeouts, wrap them into the `fetch` you inject.
 
 ---
 
@@ -551,7 +556,7 @@ The `SCRequestTelemetry` object includes:
 | `retryCount` | `number` | Number of retries (0 = first attempt succeeded) |
 | `error` | `string?` | Error message if the request failed |
 
-Telemetry fires on every code path: direct calls, pagination, retries, and 401 token refresh. It's fully optional — zero overhead when `onRequest` is not set.
+Telemetry fires for all client-namespace requests: direct calls, pagination, retries, and 401 token refresh. It is **not** emitted for `sc.raw.*` or `auth.signOut`. Fully optional — zero overhead when `onRequest` is not set.
 
 ## API Terms Compliance
 

package/dist/{chunk-B3OPPWJN.mjs → chunk-4FNI5QIN.mjs}

@@ -3,6 +3,7 @@ import { SoundCloudError } from './chunk-QYYEWUIJ.mjs';
 // src/client/http.ts
 var BASE_URL = "https://api.soundcloud.com";
 var AUTH_BASE_URL = "https://secure.soundcloud.com";
+var DEFAULT_CACHE_TTL_MS = 6e4;
 var DEFAULT_RETRY = { maxRetries: 3, retryBaseDelay: 1e3 };
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -29,6 +30,26 @@ async function parseErrorBody(response) {
   }
 }
 async function scFetch(options, refreshCtx, onRequest) {
+  const deduper = refreshCtx?.deduper;
+  const cache = refreshCtx?.cache;
+  if (options.method !== "GET" || !deduper && !cache) {
+    return scFetchCore(options, refreshCtx, onRequest);
+  }
+  const key = `GET ${options.path} ${options.token ?? ""}`;
+  const run = async () => {
+    if (cache) {
+      const hit = await cache.get(key);
+      if (hit !== void 0) return hit;
+    }
+    const result = await scFetchCore(options, refreshCtx, onRequest);
+    if (cache && result !== void 0) {
+      await cache.set(key, result, { ttlMs: refreshCtx?.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS });
+    }
+    return result;
+  };
+  return deduper ? deduper.add(key, run) : run();
+}
+async function scFetchCore(options, refreshCtx, onRequest) {
   const retryConfig = refreshCtx?.retry ?? DEFAULT_RETRY;
   const telemetryCallback = onRequest ?? refreshCtx?.onRequest;
   const startTime = Date.now();
@@ -71,8 +92,9 @@ async function scFetch(options, refreshCtx, onRequest) {
       headers["Content-Type"] = options.contentType;
     }
     let lastResponse;
+    const fetchFn = refreshCtx?.fetchImpl ?? fetch;
     for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
-      const response = await fetch(url, {
+      const response = await fetchFn(url, {
         method: options.method,
         headers,
         body: fetchBody,
@@ -151,7 +173,7 @@ async function scFetch(options, refreshCtx, onRequest) {
     throw err;
   }
 }
-async function scFetchUrl(url, token, retryConfig, onRequest) {
+async function scFetchUrl(url, token, retryConfig, onRequest, fetchImpl) {
   const config = retryConfig ?? DEFAULT_RETRY;
   const headers = { Accept: "application/json" };
   if (token) headers["Authorization"] = `OAuth ${token}`;
@@ -170,8 +192,9 @@ async function scFetchUrl(url, token, retryConfig, onRequest) {
     });
   };
   let lastResponse;
+  const fetchFn = fetchImpl ?? fetch;
   for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
-    const response = await fetch(url, { method: "GET", headers, redirect: "manual" });
+    const response = await fetchFn(url, { method: "GET", headers, redirect: "manual" });
     finalStatus = response.status;
     if (response.status === 302) {
       const location = response.headers.get("location");
@@ -235,6 +258,14 @@ async function scFetchUrl(url, token, retryConfig, onRequest) {
   throw err;
 }
 
+// src/utils/base64.ts
+var toBase64 = (value) => {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(value).toString("base64");
+  }
+  return btoa(value);
+};
+
 // src/client/paginate.ts
 async function* paginate(firstPage, fetchNext) {
   let page = await firstPage();
@@ -353,6 +384,28 @@ var RawClient = class {
   }
 };
 
+// src/client/dedupe.ts
+var InFlightDeduper = class {
+  inFlight = /* @__PURE__ */ new Map();
+  /**
+   * Return an existing in-flight promise for `key`, or start a new one via `factory`.
+   * The entry is removed from the map once the promise settles (resolve or reject).
+   */
+  add(key, factory) {
+    const existing = this.inFlight.get(key);
+    if (existing) return existing;
+    const promise = factory().finally(() => {
+      this.inFlight.delete(key);
+    });
+    this.inFlight.set(key, promise);
+    return promise;
+  }
+  /** Number of currently in-flight requests */
+  get size() {
+    return this.inFlight.size;
+  }
+};
+
 // src/client/SoundCloudClient.ts
 function resolveToken(tokenGetter, explicit) {
   const t = explicit ?? tokenGetter();
@@ -397,6 +450,14 @@ var SoundCloudClient = class _SoundCloudClient {
       onDebug: config.onDebug,
       onRetry: config.onRetry
     };
+    const sharedCtx = {
+      retry: retryConfig,
+      onRequest: config.onRequest,
+      fetchImpl: config.fetch,
+      deduper: config.dedupe ?? true ? new InFlightDeduper() : void 0,
+      cache: config.cache,
+      cacheTtlMs: config.cacheTtlMs
+    };
     const refreshCtx = config.onTokenRefresh ? {
       getToken,
       onTokenRefresh: async () => {
@@ -404,16 +465,14 @@ var SoundCloudClient = class _SoundCloudClient {
         return result;
       },
       setToken: (a, r) => this.setToken(a, r),
-      retry: retryConfig,
-      onRequest: config.onRequest
+      ...sharedCtx
     } : {
       getToken,
       setToken: (
         /* v8 ignore next */
         (a, r) => this.setToken(a, r)
       ),
-      retry: retryConfig,
-      onRequest: config.onRequest
+      ...sharedCtx
     };
     this.auth = new _SoundCloudClient.Auth(this.config);
     this.me = new _SoundCloudClient.Me(getToken, refreshCtx);
@@ -465,7 +524,7 @@ var SoundCloudClient = class _SoundCloudClient {
   paginate(firstPage) {
     const token = this._accessToken;
     const onReq = this.config.onRequest;
-    return paginate(firstPage, (url) => scFetchUrl(url, token, void 0, onReq));
+    return paginate(firstPage, (url) => scFetchUrl(url, token, void 0, onReq, this.config.fetch));
   }
   /**
    * Async generator that yields individual items across all pages.
@@ -483,7 +542,7 @@ var SoundCloudClient = class _SoundCloudClient {
   paginateItems(firstPage) {
     const token = this._accessToken;
     const onReq = this.config.onRequest;
-    return paginateItems(firstPage, (url) => scFetchUrl(url, token, void 0, onReq));
+    return paginateItems(firstPage, (url) => scFetchUrl(url, token, void 0, onReq, this.config.fetch));
   }
   /**
    * Collects all pages into a single flat array.
@@ -502,7 +561,7 @@ var SoundCloudClient = class _SoundCloudClient {
   fetchAll(firstPage, options) {
     const token = this._accessToken;
     const onReq = this.config.onRequest;
-    return fetchAll(firstPage, (url) => scFetchUrl(url, token, void 0, onReq), options);
+    return fetchAll(firstPage, (url) => scFetchUrl(url, token, void 0, onReq, this.config.fetch), options);
   }
 };
 ((SoundCloudClient2) => {
@@ -511,7 +570,25 @@ var SoundCloudClient = class _SoundCloudClient {
       this.config = config;
     }
     fetch(opts) {
-      return scFetch(opts, void 0, this.config.onRequest);
+      const ctx = {
+        getToken: (
+          /* v8 ignore next */
+          () => void 0
+        ),
+        setToken: (
+          /* v8 ignore next */
+          () => {
+          }
+        ),
+        retry: {
+          maxRetries: this.config.maxRetries ?? 3,
+          retryBaseDelay: this.config.retryBaseDelay ?? 1e3,
+          onDebug: this.config.onDebug,
+          onRetry: this.config.onRetry
+        },
+        fetchImpl: this.config.fetch
+      };
+      return scFetch(opts, ctx, this.config.onRequest);
     }
     /**
      * Build the authorization URL to redirect users to SoundCloud's OAuth login page.
@@ -559,7 +636,7 @@ var SoundCloudClient = class _SoundCloudClient {
      * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
      */
     async getClientToken() {
-      const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString("base64");
+      const credentials = toBase64(`${this.config.clientId}:${this.config.clientSecret}`);
       return this.fetch({
         path: "/oauth/token",
         method: "POST",
@@ -586,6 +663,7 @@ var SoundCloudClient = class _SoundCloudClient {
      * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
      */
     async getUserToken(code, codeVerifier) {
+      if (!this.config.redirectUri) throw new Error("redirectUri is required for getUserToken");
       const params = {
         grant_type: "authorization_code",
         client_id: this.config.clientId,
@@ -616,6 +694,7 @@ var SoundCloudClient = class _SoundCloudClient {
      * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
      */
     async refreshUserToken(refreshToken) {
+      if (!this.config.redirectUri) throw new Error("redirectUri is required for refreshUserToken");
       return this.fetch({
         path: "/oauth/token",
         method: "POST",
@@ -644,7 +723,8 @@ var SoundCloudClient = class _SoundCloudClient {
      * ```
      */
     async signOut(accessToken) {
-      const res = await fetch("https://secure.soundcloud.com/sign-out", {
+      const fetchFn = this.config.fetch ?? fetch;
+      const res = await fetchFn("https://secure.soundcloud.com/sign-out", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ access_token: accessToken })
@@ -1643,28 +1723,6 @@ var SoundCloudClient = class _SoundCloudClient {
   SoundCloudClient2.Reposts = Reposts;
 })(SoundCloudClient || (SoundCloudClient = {}));
 
-// src/client/dedupe.ts
-var InFlightDeduper = class {
-  inFlight = /* @__PURE__ */ new Map();
-  /**
-   * Return an existing in-flight promise for `key`, or start a new one via `factory`.
-   * The entry is removed from the map once the promise settles (resolve or reject).
-   */
-  add(key, factory) {
-    const existing = this.inFlight.get(key);
-    if (existing) return existing;
-    const promise = factory().finally(() => {
-      this.inFlight.delete(key);
-    });
-    this.inFlight.set(key, promise);
-    return promise;
-  }
-  /** Number of currently in-flight requests */
-  get size() {
-    return this.inFlight.size;
-  }
-};
-
 // src/client/registry.ts
 var IMPLEMENTED_OPERATIONS = [
   // Auth
@@ -1729,7 +1787,7 @@ var IMPLEMENTED_OPERATIONS = [
 
 // src/auth/getClientToken.ts
 var getClientToken = (clientId, clientSecret) => {
-  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
+  const credentials = toBase64(`${clientId}:${clientSecret}`);
   return scFetch({
     path: "/oauth/token",
     method: "POST",
@@ -2033,5 +2091,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-B3OPPWJN.mjs.map
-//# sourceMappingURL=chunk-B3OPPWJN.mjs.map
+//# sourceMappingURL=chunk-4FNI5QIN.mjs.map
+//# sourceMappingURL=chunk-4FNI5QIN.mjs.map