soundcloud-api-ts 1.10.2 → 1.11.0

package/AGENTS.md

@@ -125,9 +125,10 @@ 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`).
 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.
+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.
+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.
 
 ## Project Structure (for contributors)
 

package/README.md

@@ -423,6 +423,35 @@ const sc = new SoundCloudClient({
 - **401 errors** trigger `onTokenRefresh` (if configured) instead of retry
 - Backoff formula: `baseDelay × 2^attempt` with jitter
 
+## Request Telemetry
+
+Hook into every API request for logging, metrics, or observability:
+
+```ts
+import { SoundCloudClient, type SCRequestTelemetry } from 'soundcloud-api-ts';
+
+const sc = new SoundCloudClient({
+  clientId: '...',
+  clientSecret: '...',
+  onRequest: (t: SCRequestTelemetry) => {
+    console.log(`[SC] ${t.method} ${t.path} status=${t.status} ${t.durationMs}ms retries=${t.retryCount}`);
+  },
+});
+```
+
+The `SCRequestTelemetry` object includes:
+
+| Field | Type | Description |
+|---|---|---|
+| `method` | `"GET" \| "POST" \| "PUT" \| "DELETE"` | HTTP method |
+| `path` | `string` | API path or full URL (for pagination) |
+| `durationMs` | `number` | Total wall-clock time including retries |
+| `status` | `number` | Final HTTP status code |
+| `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.
+
 ## API Terms Compliance
 
 This package is built on SoundCloud's **official documented API** (`api.soundcloud.com`) and follows the [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use):

package/dist/{chunk-ACK4KMGD.mjs → chunk-5FCXAR2S.mjs}

@@ -28,8 +28,23 @@ async function parseErrorBody(response) {
     return void 0;
   }
 }
-async function scFetch(options, refreshCtx) {
+async function scFetch(options, refreshCtx, onRequest) {
   const retryConfig = refreshCtx?.retry ?? DEFAULT_RETRY;
+  const telemetryCallback = onRequest ?? refreshCtx?.onRequest;
+  const startTime = Date.now();
+  let retryCount = 0;
+  let finalStatus = 0;
+  const emitTelemetry = (error) => {
+    if (!telemetryCallback) return;
+    telemetryCallback({
+      method: options.method,
+      path: options.path,
+      durationMs: Date.now() - startTime,
+      status: finalStatus,
+      retryCount,
+      ...error ? { error } : {}
+    });
+  };
   const execute = async (tokenOverride) => {
     const isAuthPath = options.path.startsWith("/oauth");
     const url = `${isAuthPath ? AUTH_BASE_URL : BASE_URL}${options.path}`;
@@ -63,22 +78,32 @@ async function scFetch(options, refreshCtx) {
         body: fetchBody,
         redirect: "manual"
       });
+      finalStatus = response.status;
       if (response.status === 302) {
         const location = response.headers.get("location");
-        if (location) return location;
+        if (location) {
+          emitTelemetry();
+          return location;
+        }
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
+        emitTelemetry();
         return void 0;
       }
       if (response.ok) {
-        return response.json();
+        const result = response.json();
+        emitTelemetry();
+        return result;
       }
       if (!isRetryable(response.status)) {
         const body2 = await parseErrorBody(response);
-        throw new SoundCloudError(response.status, response.statusText, body2);
+        const err2 = new SoundCloudError(response.status, response.statusText, body2);
+        emitTelemetry(err2.message);
+        throw err2;
       }
       lastResponse = response;
       if (attempt < retryConfig.maxRetries) {
+        retryCount = attempt + 1;
         const delayMs = getRetryDelay(response, attempt, retryConfig);
         retryConfig.onDebug?.(
           `Retry ${attempt + 1}/${retryConfig.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
@@ -87,7 +112,9 @@ async function scFetch(options, refreshCtx) {
       }
     }
     const body = await parseErrorBody(lastResponse);
-    throw new SoundCloudError(lastResponse.status, lastResponse.statusText, body);
+    const err = new SoundCloudError(lastResponse.status, lastResponse.statusText, body);
+    emitTelemetry(err.message);
+    throw err;
   };
   try {
     return await execute();
@@ -100,29 +127,53 @@ async function scFetch(options, refreshCtx) {
     throw err;
   }
 }
-async function scFetchUrl(url, token, retryConfig) {
+async function scFetchUrl(url, token, retryConfig, onRequest) {
   const config = retryConfig ?? DEFAULT_RETRY;
   const headers = { Accept: "application/json" };
   if (token) headers["Authorization"] = `OAuth ${token}`;
+  const startTime = Date.now();
+  let retryCount = 0;
+  let finalStatus = 0;
+  const emitTelemetry = (error) => {
+    if (!onRequest) return;
+    onRequest({
+      method: "GET",
+      path: url,
+      durationMs: Date.now() - startTime,
+      status: finalStatus,
+      retryCount,
+      ...error ? { error } : {}
+    });
+  };
   let lastResponse;
   for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
     const response = await fetch(url, { method: "GET", headers, redirect: "manual" });
+    finalStatus = response.status;
     if (response.status === 302) {
       const location = response.headers.get("location");
-      if (location) return location;
+      if (location) {
+        emitTelemetry();
+        return location;
+      }
     }
     if (response.status === 204 || response.headers.get("content-length") === "0") {
+      emitTelemetry();
       return void 0;
     }
     if (response.ok) {
-      return response.json();
+      const result = response.json();
+      emitTelemetry();
+      return result;
     }
     if (!isRetryable(response.status)) {
       const body2 = await parseErrorBody(response);
-      throw new SoundCloudError(response.status, response.statusText, body2);
+      const err2 = new SoundCloudError(response.status, response.statusText, body2);
+      emitTelemetry(err2.message);
+      throw err2;
     }
     lastResponse = response;
     if (attempt < config.maxRetries) {
+      retryCount = attempt + 1;
       const delayMs = getRetryDelay(response, attempt, config);
       config.onDebug?.(
         `Retry ${attempt + 1}/${config.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
@@ -131,7 +182,9 @@ async function scFetchUrl(url, token, retryConfig) {
     }
   }
   const body = await parseErrorBody(lastResponse);
-  throw new SoundCloudError(lastResponse.status, lastResponse.statusText, body);
+  const err = new SoundCloudError(lastResponse.status, lastResponse.statusText, body);
+  emitTelemetry(err.message);
+  throw err;
 }
 
 // src/client/paginate.ts
@@ -210,14 +263,16 @@ var SoundCloudClient = class _SoundCloudClient {
         return result;
       },
       setToken: (a, r) => this.setToken(a, r),
-      retry: retryConfig
+      retry: retryConfig,
+      onRequest: config.onRequest
     } : {
       getToken,
       setToken: (
         /* v8 ignore next */
         (a, r) => this.setToken(a, r)
       ),
-      retry: retryConfig
+      retry: retryConfig,
+      onRequest: config.onRequest
     };
     this.auth = new _SoundCloudClient.Auth(this.config);
     this.me = new _SoundCloudClient.Me(getToken, refreshCtx);
@@ -267,7 +322,8 @@ var SoundCloudClient = class _SoundCloudClient {
    */
   paginate(firstPage) {
     const token = this._accessToken;
-    return paginate(firstPage, (url) => scFetchUrl(url, token));
+    const onReq = this.config.onRequest;
+    return paginate(firstPage, (url) => scFetchUrl(url, token, void 0, onReq));
   }
   /**
    * Async generator that yields individual items across all pages.
@@ -284,7 +340,8 @@ var SoundCloudClient = class _SoundCloudClient {
    */
   paginateItems(firstPage) {
     const token = this._accessToken;
-    return paginateItems(firstPage, (url) => scFetchUrl(url, token));
+    const onReq = this.config.onRequest;
+    return paginateItems(firstPage, (url) => scFetchUrl(url, token, void 0, onReq));
   }
   /**
    * Collects all pages into a single flat array.
@@ -302,7 +359,8 @@ var SoundCloudClient = class _SoundCloudClient {
    */
   fetchAll(firstPage, options) {
     const token = this._accessToken;
-    return fetchAll(firstPage, (url) => scFetchUrl(url, token), options);
+    const onReq = this.config.onRequest;
+    return fetchAll(firstPage, (url) => scFetchUrl(url, token, void 0, onReq), options);
   }
 };
 ((SoundCloudClient2) => {
@@ -1684,5 +1742,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 { 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-ACK4KMGD.mjs.map
-//# sourceMappingURL=chunk-ACK4KMGD.mjs.map
+//# sourceMappingURL=chunk-5FCXAR2S.mjs.map
+//# sourceMappingURL=chunk-5FCXAR2S.mjs.map