soundcloud-api-ts 1.2.0 → 1.3.0

package/README.md

@@ -293,6 +293,57 @@ import { getSoundCloudWidgetUrl } from "soundcloud-api-ts";
 const widgetUrl = getSoundCloudWidgetUrl(trackId);
 ```
 
+## Error Handling
+
+All API errors throw a `SoundCloudError` with structured properties:
+
+```ts
+import { SoundCloudError } from "soundcloud-api-ts";
+
+try {
+  await sc.tracks.getTrack(999);
+} catch (err) {
+  if (err instanceof SoundCloudError) {
+    console.log(err.status);     // 404
+    console.log(err.statusText); // "Not Found"
+    console.log(err.message);    // "404 - Not Found" (from SC's response)
+    console.log(err.errorCode);  // "invalid_client" (on auth errors)
+    console.log(err.errors);     // ["404 - Not Found"] (individual error messages)
+    console.log(err.docsLink);   // "https://developers.soundcloud.com/docs/api/explorer/open-api"
+    console.log(err.body);       // full parsed response body
+
+    // Convenience getters
+    if (err.isNotFound) { /* handle 404 */ }
+    if (err.isRateLimited) { /* handle 429 */ }
+    if (err.isUnauthorized) { /* handle 401 */ }
+    if (err.isForbidden) { /* handle 403 */ }
+    if (err.isServerError) { /* handle 5xx */ }
+  }
+}
+```
+
+Error messages are parsed directly from SoundCloud's API response format, giving you the most useful message available.
+
+## Rate Limiting & Retries
+
+The client automatically retries on **429 Too Many Requests** and **5xx Server Errors** with exponential backoff:
+
+```ts
+const sc = new SoundCloudClient({
+  clientId: "...",
+  clientSecret: "...",
+  maxRetries: 3,         // default: 3
+  retryBaseDelay: 1000,  // default: 1000ms
+  onDebug: (msg) => console.log(msg), // optional retry logging
+});
+```
+
+- **429 responses** respect the `Retry-After` header when present
+- **5xx responses** (500, 502, 503, 504) are retried with exponential backoff
+- **4xx errors** (except 429) are NOT retried — they throw immediately
+- **401 errors** trigger `onTokenRefresh` (if configured) instead of retry
+- Backoff formula: `baseDelay × 2^attempt` with jitter
+
 ## Requirements
 
 - Node.js 20+ (uses native `fetch`)

package/dist/chunk-34DWTDWF.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// src/errors.ts
+var SoundCloudError = class extends Error {
+  /** HTTP status code */
+  status;
+  /** HTTP status text (e.g. "Unauthorized") */
+  statusText;
+  /** SC error code (e.g. "invalid_client") */
+  errorCode;
+  /** SC docs link */
+  docsLink;
+  /** Individual error messages from the errors array */
+  errors;
+  /** The full parsed response body */
+  body;
+  constructor(status, statusText, body) {
+    const msg = body?.message || body?.error_description || body?.error_code || body?.errors?.[0]?.error_message || body?.error || `${status} ${statusText}`;
+    super(msg);
+    this.name = "SoundCloudError";
+    this.status = status;
+    this.statusText = statusText;
+    this.errorCode = body?.error_code ?? void 0;
+    this.docsLink = body?.link ?? void 0;
+    this.errors = body?.errors?.map((e) => e.error_message).filter((m) => !!m) ?? [];
+    this.body = body;
+  }
+  /** True if status is 401 Unauthorized */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True if status is 403 Forbidden */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** True if status is 404 Not Found */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** True if status is 429 Too Many Requests */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  /** True if status is 5xx server error */
+  get isServerError() {
+    return this.status >= 500 && this.status < 600;
+  }
+};
+
+exports.SoundCloudError = SoundCloudError;
+//# sourceMappingURL=chunk-34DWTDWF.js.map
+//# sourceMappingURL=chunk-34DWTDWF.js.map

package/dist/chunk-34DWTDWF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";;;AAgCO,IAAM,eAAA,GAAN,cAA8B,KAAA,CAAM;AAAA;AAAA,EAEhC,MAAA;AAAA;AAAA,EAEA,UAAA;AAAA;AAAA,EAEA,SAAA;AAAA;AAAA,EAEA,QAAA;AAAA;AAAA,EAEA,MAAA;AAAA;AAAA,EAEA,IAAA;AAAA,EAET,WAAA,CAAY,MAAA,EAAgB,UAAA,EAAoB,IAAA,EAA4B;AAE1E,IAAA,MAAM,MACJ,IAAA,EAAM,OAAA,IACN,IAAA,EAAM,iBAAA,IACN,MAAM,UAAA,IACN,IAAA,EAAM,MAAA,GAAS,CAAC,GAAG,aAAA,IACnB,IAAA,EAAM,SACN,CAAA,EAAG,MAAM,IAAI,UAAU,CAAA,CAAA;AAEzB,IAAA,KAAA,CAAM,GAAG,CAAA;AACT,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAClB,IAAA,IAAA,CAAK,SAAA,GAAY,MAAM,UAAA,IAAc,MAAA;AACrC,IAAA,IAAA,CAAK,QAAA,GAAW,MAAM,IAAA,IAAQ,MAAA;AAC9B,IAAA,IAAA,CAAK,SACH,IAAA,EAAM,MAAA,EACF,GAAA,CAAI,CAAC,MAAM,CAAA,CAAE,aAAa,CAAA,CAC3B,MAAA,CAAO,CAAC,CAAA,KAAmB,CAAC,CAAC,CAAC,KAAK,EAAC;AACzC,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,cAAA,GAA0B;AAC5B,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,WAAA,GAAuB;AACzB,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,UAAA,GAAsB;AACxB,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,aAAA,GAAyB;AAC3B,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,aAAA,GAAyB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAA,IAAU,GAAA,IAAO,IAAA,CAAK,MAAA,GAAS,GAAA;AAAA,EAC7C;AACF","file":"chunk-34DWTDWF.js","sourcesContent":["/**\n * SoundCloud API error response shape.\n * Based on actual SC API responses, e.g.:\n * {\n *   \"code\": 401,\n *   \"message\": \"invalid_client\",\n *   \"link\": \"https://developers.soundcloud.com/docs/api/explorer/open-api\",\n *   \"status\": \"401 - Unauthorized\",\n *   \"errors\": [{\"error_message\": \"invalid_client\"}],\n *   \"error\": null,\n *   \"error_code\": \"invalid_client\"\n * }\n */\nexport interface SoundCloudErrorBody {\n  /** HTTP status code */\n  code?: number;\n  /** Error message from SC (e.g. \"invalid_client\", \"404 - Not Found\") */\n  message?: string;\n  /** SC status string (e.g. \"401 - Unauthorized\") */\n  status?: string;\n  /** Link to SC API docs */\n  link?: string;\n  /** Array of individual errors */\n  errors?: Array<{ error_message?: string }>;\n  /** Error field — typically null in SC responses */\n  error?: string | null;\n  /** Error code (e.g. \"invalid_client\") */\n  error_code?: string;\n  /** OAuth error_description (used in /oauth2/token errors) */\n  error_description?: string;\n}\n\nexport class SoundCloudError extends Error {\n  /** HTTP status code */\n  readonly status: number;\n  /** HTTP status text (e.g. \"Unauthorized\") */\n  readonly statusText: string;\n  /** SC error code (e.g. \"invalid_client\") */\n  readonly errorCode?: string;\n  /** SC docs link */\n  readonly docsLink?: string;\n  /** Individual error messages from the errors array */\n  readonly errors: string[];\n  /** The full parsed response body */\n  readonly body?: SoundCloudErrorBody;\n\n  constructor(status: number, statusText: string, body?: SoundCloudErrorBody) {\n    // Build the most useful message we can from SC's response\n    const msg =\n      body?.message ||\n      body?.error_description ||\n      body?.error_code ||\n      body?.errors?.[0]?.error_message ||\n      body?.error ||\n      `${status} ${statusText}`;\n\n    super(msg);\n    this.name = \"SoundCloudError\";\n    this.status = status;\n    this.statusText = statusText;\n    this.errorCode = body?.error_code ?? undefined;\n    this.docsLink = body?.link ?? undefined;\n    this.errors =\n      body?.errors\n        ?.map((e) => e.error_message)\n        .filter((m): m is string => !!m) ?? [];\n    this.body = body;\n  }\n\n  /** True if status is 401 Unauthorized */\n  get isUnauthorized(): boolean {\n    return this.status === 401;\n  }\n\n  /** True if status is 403 Forbidden */\n  get isForbidden(): boolean {\n    return this.status === 403;\n  }\n\n  /** True if status is 404 Not Found */\n  get isNotFound(): boolean {\n    return this.status === 404;\n  }\n\n  /** True if status is 429 Too Many Requests */\n  get isRateLimited(): boolean {\n    return this.status === 429;\n  }\n\n  /** True if status is 5xx server error */\n  get isServerError(): boolean {\n    return this.status >= 500 && this.status < 600;\n  }\n}\n"]}

package/dist/chunk-GKNBLKPB.mjs

@@ -0,0 +1,50 @@
+// src/errors.ts
+var SoundCloudError = class extends Error {
+  /** HTTP status code */
+  status;
+  /** HTTP status text (e.g. "Unauthorized") */
+  statusText;
+  /** SC error code (e.g. "invalid_client") */
+  errorCode;
+  /** SC docs link */
+  docsLink;
+  /** Individual error messages from the errors array */
+  errors;
+  /** The full parsed response body */
+  body;
+  constructor(status, statusText, body) {
+    const msg = body?.message || body?.error_description || body?.error_code || body?.errors?.[0]?.error_message || body?.error || `${status} ${statusText}`;
+    super(msg);
+    this.name = "SoundCloudError";
+    this.status = status;
+    this.statusText = statusText;
+    this.errorCode = body?.error_code ?? void 0;
+    this.docsLink = body?.link ?? void 0;
+    this.errors = body?.errors?.map((e) => e.error_message).filter((m) => !!m) ?? [];
+    this.body = body;
+  }
+  /** True if status is 401 Unauthorized */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True if status is 403 Forbidden */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** True if status is 404 Not Found */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** True if status is 429 Too Many Requests */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  /** True if status is 5xx server error */
+  get isServerError() {
+    return this.status >= 500 && this.status < 600;
+  }
+};
+
+export { SoundCloudError };
+//# sourceMappingURL=chunk-GKNBLKPB.mjs.map
+//# sourceMappingURL=chunk-GKNBLKPB.mjs.map

package/dist/chunk-GKNBLKPB.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AAgCO,IAAM,eAAA,GAAN,cAA8B,KAAA,CAAM;AAAA;AAAA,EAEhC,MAAA;AAAA;AAAA,EAEA,UAAA;AAAA;AAAA,EAEA,SAAA;AAAA;AAAA,EAEA,QAAA;AAAA;AAAA,EAEA,MAAA;AAAA;AAAA,EAEA,IAAA;AAAA,EAET,WAAA,CAAY,MAAA,EAAgB,UAAA,EAAoB,IAAA,EAA4B;AAE1E,IAAA,MAAM,MACJ,IAAA,EAAM,OAAA,IACN,IAAA,EAAM,iBAAA,IACN,MAAM,UAAA,IACN,IAAA,EAAM,MAAA,GAAS,CAAC,GAAG,aAAA,IACnB,IAAA,EAAM,SACN,CAAA,EAAG,MAAM,IAAI,UAAU,CAAA,CAAA;AAEzB,IAAA,KAAA,CAAM,GAAG,CAAA;AACT,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AACZ,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAClB,IAAA,IAAA,CAAK,SAAA,GAAY,MAAM,UAAA,IAAc,MAAA;AACrC,IAAA,IAAA,CAAK,QAAA,GAAW,MAAM,IAAA,IAAQ,MAAA;AAC9B,IAAA,IAAA,CAAK,SACH,IAAA,EAAM,MAAA,EACF,GAAA,CAAI,CAAC,MAAM,CAAA,CAAE,aAAa,CAAA,CAC3B,MAAA,CAAO,CAAC,CAAA,KAAmB,CAAC,CAAC,CAAC,KAAK,EAAC;AACzC,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AAAA;AAAA,EAGA,IAAI,cAAA,GAA0B;AAC5B,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,WAAA,GAAuB;AACzB,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,UAAA,GAAsB;AACxB,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,aAAA,GAAyB;AAC3B,IAAA,OAAO,KAAK,MAAA,KAAW,GAAA;AAAA,EACzB;AAAA;AAAA,EAGA,IAAI,aAAA,GAAyB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAA,IAAU,GAAA,IAAO,IAAA,CAAK,MAAA,GAAS,GAAA;AAAA,EAC7C;AACF","file":"chunk-GKNBLKPB.mjs","sourcesContent":["/**\n * SoundCloud API error response shape.\n * Based on actual SC API responses, e.g.:\n * {\n *   \"code\": 401,\n *   \"message\": \"invalid_client\",\n *   \"link\": \"https://developers.soundcloud.com/docs/api/explorer/open-api\",\n *   \"status\": \"401 - Unauthorized\",\n *   \"errors\": [{\"error_message\": \"invalid_client\"}],\n *   \"error\": null,\n *   \"error_code\": \"invalid_client\"\n * }\n */\nexport interface SoundCloudErrorBody {\n  /** HTTP status code */\n  code?: number;\n  /** Error message from SC (e.g. \"invalid_client\", \"404 - Not Found\") */\n  message?: string;\n  /** SC status string (e.g. \"401 - Unauthorized\") */\n  status?: string;\n  /** Link to SC API docs */\n  link?: string;\n  /** Array of individual errors */\n  errors?: Array<{ error_message?: string }>;\n  /** Error field — typically null in SC responses */\n  error?: string | null;\n  /** Error code (e.g. \"invalid_client\") */\n  error_code?: string;\n  /** OAuth error_description (used in /oauth2/token errors) */\n  error_description?: string;\n}\n\nexport class SoundCloudError extends Error {\n  /** HTTP status code */\n  readonly status: number;\n  /** HTTP status text (e.g. \"Unauthorized\") */\n  readonly statusText: string;\n  /** SC error code (e.g. \"invalid_client\") */\n  readonly errorCode?: string;\n  /** SC docs link */\n  readonly docsLink?: string;\n  /** Individual error messages from the errors array */\n  readonly errors: string[];\n  /** The full parsed response body */\n  readonly body?: SoundCloudErrorBody;\n\n  constructor(status: number, statusText: string, body?: SoundCloudErrorBody) {\n    // Build the most useful message we can from SC's response\n    const msg =\n      body?.message ||\n      body?.error_description ||\n      body?.error_code ||\n      body?.errors?.[0]?.error_message ||\n      body?.error ||\n      `${status} ${statusText}`;\n\n    super(msg);\n    this.name = \"SoundCloudError\";\n    this.status = status;\n    this.statusText = statusText;\n    this.errorCode = body?.error_code ?? undefined;\n    this.docsLink = body?.link ?? undefined;\n    this.errors =\n      body?.errors\n        ?.map((e) => e.error_message)\n        .filter((m): m is string => !!m) ?? [];\n    this.body = body;\n  }\n\n  /** True if status is 401 Unauthorized */\n  get isUnauthorized(): boolean {\n    return this.status === 401;\n  }\n\n  /** True if status is 403 Forbidden */\n  get isForbidden(): boolean {\n    return this.status === 403;\n  }\n\n  /** True if status is 404 Not Found */\n  get isNotFound(): boolean {\n    return this.status === 404;\n  }\n\n  /** True if status is 429 Too Many Requests */\n  get isRateLimited(): boolean {\n    return this.status === 429;\n  }\n\n  /** True if status is 5xx server error */\n  get isServerError(): boolean {\n    return this.status >= 500 && this.status < 600;\n  }\n}\n"]}

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './types/index.mjs';
-export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.mjs';
+export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudError, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.mjs';
 
 interface RequestOptions {
     path: string;
@@ -8,6 +8,14 @@ interface RequestOptions {
     body?: Record<string, unknown> | FormData | URLSearchParams;
     contentType?: string;
 }
+interface RetryConfig {
+    /** Max retries on 429/5xx (default: 3) */
+    maxRetries: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    retryBaseDelay: number;
+    /** Optional debug logger */
+    onDebug?: (message: string) => void;
+}
 interface AutoRefreshContext {
     getToken: () => string | undefined;
     onTokenRefresh?: () => Promise<{
@@ -15,6 +23,7 @@ interface AutoRefreshContext {
         refresh_token?: string;
     }>;
     setToken: (accessToken: string, refreshToken?: string) => void;
+    retry?: RetryConfig;
 }
 /**
  * Make a request to the SoundCloud API using native fetch.
@@ -25,7 +34,7 @@ declare function scFetch<T>(options: RequestOptions, refreshCtx?: AutoRefreshCon
  * Fetch an absolute URL (e.g. next_href from paginated responses).
  * Adds OAuth token if provided.
  */
-declare function scFetchUrl<T>(url: string, token?: string): Promise<T>;
+declare function scFetchUrl<T>(url: string, token?: string, retryConfig?: RetryConfig): Promise<T>;
 
 interface UpdateTrackParams {
     title?: string;
@@ -99,6 +108,12 @@ interface SoundCloudClientConfig {
     redirectUri?: string;
     /** Called automatically when a request returns 401. Return new tokens to retry. */
     onTokenRefresh?: (client: SoundCloudClient) => Promise<SoundCloudToken>;
+    /** Max retries on 429/5xx (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    retryBaseDelay?: number;
+    /** Optional debug logger for retry attempts, etc. */
+    onDebug?: (message: string) => void;
 }
 /** Optional token override, passed as the last parameter to client methods. */
 interface TokenOption {
@@ -487,4 +502,4 @@ declare const unrepostPlaylist: (token: string, playlistId: string | number) =>
  */
 declare const getSoundCloudWidgetUrl: (trackId: string | number) => string;
 
-export { type CreatePlaylistParams, type RequestOptions, SoundCloudActivitiesResponse, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type UpdatePlaylistParams, type UpdateTrackParams, 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 };
+export { type CreatePlaylistParams, type RequestOptions, type RetryConfig, SoundCloudActivitiesResponse, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type UpdatePlaylistParams, type UpdateTrackParams, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './types/index.js';
-export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.js';
+export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudError, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.js';
 
 interface RequestOptions {
     path: string;
@@ -8,6 +8,14 @@ interface RequestOptions {
     body?: Record<string, unknown> | FormData | URLSearchParams;
     contentType?: string;
 }
+interface RetryConfig {
+    /** Max retries on 429/5xx (default: 3) */
+    maxRetries: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    retryBaseDelay: number;
+    /** Optional debug logger */
+    onDebug?: (message: string) => void;
+}
 interface AutoRefreshContext {
     getToken: () => string | undefined;
     onTokenRefresh?: () => Promise<{
@@ -15,6 +23,7 @@ interface AutoRefreshContext {
         refresh_token?: string;
     }>;
     setToken: (accessToken: string, refreshToken?: string) => void;
+    retry?: RetryConfig;
 }
 /**
  * Make a request to the SoundCloud API using native fetch.
@@ -25,7 +34,7 @@ declare function scFetch<T>(options: RequestOptions, refreshCtx?: AutoRefreshCon
  * Fetch an absolute URL (e.g. next_href from paginated responses).
  * Adds OAuth token if provided.
  */
-declare function scFetchUrl<T>(url: string, token?: string): Promise<T>;
+declare function scFetchUrl<T>(url: string, token?: string, retryConfig?: RetryConfig): Promise<T>;
 
 interface UpdateTrackParams {
     title?: string;
@@ -99,6 +108,12 @@ interface SoundCloudClientConfig {
     redirectUri?: string;
     /** Called automatically when a request returns 401. Return new tokens to retry. */
     onTokenRefresh?: (client: SoundCloudClient) => Promise<SoundCloudToken>;
+    /** Max retries on 429/5xx (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    retryBaseDelay?: number;
+    /** Optional debug logger for retry attempts, etc. */
+    onDebug?: (message: string) => void;
 }
 /** Optional token override, passed as the last parameter to client methods. */
 interface TokenOption {
@@ -487,4 +502,4 @@ declare const unrepostPlaylist: (token: string, playlistId: string | number) =>
  */
 declare const getSoundCloudWidgetUrl: (trackId: string | number) => string;
 
-export { type CreatePlaylistParams, type RequestOptions, SoundCloudActivitiesResponse, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type UpdatePlaylistParams, type UpdateTrackParams, 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 };
+export { type CreatePlaylistParams, type RequestOptions, type RetryConfig, SoundCloudActivitiesResponse, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type UpdatePlaylistParams, type UpdateTrackParams, 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 };

package/dist/index.js

@@ -1,8 +1,36 @@
 'use strict';
 
+var chunk34DWTDWF_js = require('./chunk-34DWTDWF.js');
+
 // src/client/http.ts
 var BASE_URL = "https://api.soundcloud.com";
+var DEFAULT_RETRY = { maxRetries: 3, retryBaseDelay: 1e3 };
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(status) {
+  return status === 429 || status >= 500 && status <= 599;
+}
+function getRetryDelay(response, attempt, config) {
+  if (response.status === 429) {
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter) {
+      const seconds = Number(retryAfter);
+      if (!Number.isNaN(seconds)) return seconds * 1e3;
+    }
+  }
+  const base = config.retryBaseDelay * Math.pow(2, attempt);
+  return base + Math.random() * base * 0.1;
+}
+async function parseErrorBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    return void 0;
+  }
+}
 async function scFetch(options, refreshCtx) {
+  const retryConfig = refreshCtx?.retry ?? DEFAULT_RETRY;
   const execute = async (tokenOverride) => {
     const url = `${BASE_URL}${options.path}`;
     const headers = {
@@ -26,32 +54,44 @@ async function scFetch(options, refreshCtx) {
     } else if (options.contentType) {
       headers["Content-Type"] = options.contentType;
     }
-    const response = await fetch(url, {
-      method: options.method,
-      headers,
-      body: fetchBody,
-      redirect: "manual"
-    });
-    if (response.status === 302) {
-      const location = response.headers.get("location");
-      if (location) {
-        return location;
+    let lastResponse;
+    for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+      const response = await fetch(url, {
+        method: options.method,
+        headers,
+        body: fetchBody,
+        redirect: "manual"
+      });
+      if (response.status === 302) {
+        const location = response.headers.get("location");
+        if (location) return location;
+      }
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return void 0;
+      }
+      if (response.ok) {
+        return response.json();
+      }
+      if (!isRetryable(response.status)) {
+        const body2 = await parseErrorBody(response);
+        throw new chunk34DWTDWF_js.SoundCloudError(response.status, response.statusText, body2);
+      }
+      lastResponse = response;
+      if (attempt < retryConfig.maxRetries) {
+        const delayMs = getRetryDelay(response, attempt, retryConfig);
+        retryConfig.onDebug?.(
+          `Retry ${attempt + 1}/${retryConfig.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
+        );
+        await delay(delayMs);
       }
     }
-    if (response.status === 204 || response.headers.get("content-length") === "0") {
-      return void 0;
-    }
-    if (!response.ok) {
-      throw new Error(
-        `SoundCloud API error: ${response.status} ${response.statusText}`
-      );
-    }
-    return response.json();
+    const body = await parseErrorBody(lastResponse);
+    throw new chunk34DWTDWF_js.SoundCloudError(lastResponse.status, lastResponse.statusText, body);
   };
   try {
     return await execute();
   } catch (err) {
-    if (refreshCtx?.onTokenRefresh && err instanceof Error && err.message.includes("401")) {
+    if (refreshCtx?.onTokenRefresh && err instanceof chunk34DWTDWF_js.SoundCloudError && err.status === 401) {
       const newToken = await refreshCtx.onTokenRefresh();
       refreshCtx.setToken(newToken.access_token, newToken.refresh_token);
       return execute(newToken.access_token);
@@ -59,21 +99,38 @@ async function scFetch(options, refreshCtx) {
     throw err;
   }
 }
-async function scFetchUrl(url, token) {
+async function scFetchUrl(url, token, retryConfig) {
+  const config = retryConfig ?? DEFAULT_RETRY;
   const headers = { Accept: "application/json" };
   if (token) headers["Authorization"] = `OAuth ${token}`;
-  const response = await fetch(url, { method: "GET", headers, redirect: "manual" });
-  if (response.status === 302) {
-    const location = response.headers.get("location");
-    if (location) return location;
-  }
-  if (response.status === 204 || response.headers.get("content-length") === "0") {
-    return void 0;
-  }
-  if (!response.ok) {
-    throw new Error(`SoundCloud API error: ${response.status} ${response.statusText}`);
+  let lastResponse;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    const response = await fetch(url, { method: "GET", headers, redirect: "manual" });
+    if (response.status === 302) {
+      const location = response.headers.get("location");
+      if (location) return location;
+    }
+    if (response.status === 204 || response.headers.get("content-length") === "0") {
+      return void 0;
+    }
+    if (response.ok) {
+      return response.json();
+    }
+    if (!isRetryable(response.status)) {
+      const body2 = await parseErrorBody(response);
+      throw new chunk34DWTDWF_js.SoundCloudError(response.status, response.statusText, body2);
+    }
+    lastResponse = response;
+    if (attempt < config.maxRetries) {
+      const delayMs = getRetryDelay(response, attempt, config);
+      config.onDebug?.(
+        `Retry ${attempt + 1}/${config.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
+      );
+      await delay(delayMs);
+    }
   }
-  return response.json();
+  const body = await parseErrorBody(lastResponse);
+  throw new chunk34DWTDWF_js.SoundCloudError(lastResponse.status, lastResponse.statusText, body);
 }
 
 // src/client/paginate.ts
@@ -126,14 +183,24 @@ exports.SoundCloudClient = class _SoundCloudClient {
   constructor(config) {
     this.config = config;
     const getToken = () => this._accessToken;
+    const retryConfig = {
+      maxRetries: config.maxRetries ?? 3,
+      retryBaseDelay: config.retryBaseDelay ?? 1e3,
+      onDebug: config.onDebug
+    };
     const refreshCtx = config.onTokenRefresh ? {
       getToken,
       onTokenRefresh: async () => {
         const result = await config.onTokenRefresh(this);
         return result;
       },
-      setToken: (a, r) => this.setToken(a, r)
-    } : void 0;
+      setToken: (a, r) => this.setToken(a, r),
+      retry: retryConfig
+    } : {
+      getToken,
+      setToken: (a, r) => this.setToken(a, r),
+      retry: retryConfig
+    };
     this.auth = new _SoundCloudClient.Auth(this.config);
     this.me = new _SoundCloudClient.Me(getToken, refreshCtx);
     this.users = new _SoundCloudClient.Users(getToken, refreshCtx);
@@ -935,6 +1002,10 @@ 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`;
 
+Object.defineProperty(exports, "SoundCloudError", {
+  enumerable: true,
+  get: function () { return chunk34DWTDWF_js.SoundCloudError; }
+});
 exports.createPlaylist = createPlaylist;
 exports.createTrackComment = createTrackComment;
 exports.deletePlaylist = deletePlaylist;