soundcloud-api-ts 1.1.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Twin Paws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,9 +2,33 @@
 
 [![npm version](https://img.shields.io/npm/v/soundcloud-api-ts)](https://www.npmjs.com/package/soundcloud-api-ts)
 [![npm downloads](https://img.shields.io/npm/dm/soundcloud-api-ts)](https://www.npmjs.com/package/soundcloud-api-ts)
-[![license](https://img.shields.io/npm/l/soundcloud-api-ts)](https://github.com/twin-paws/soundcloud-api-client/blob/main/LICENSE)
-
-A TypeScript client for the SoundCloud API. Zero dependencies, uses native `fetch` (Node 18+).
+[![CI](https://github.com/twin-paws/soundcloud-api-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/twin-paws/soundcloud-api-ts/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/soundcloud-api-ts)](https://github.com/twin-paws/soundcloud-api-ts/blob/main/LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/soundcloud-api-ts)](https://bundlephobia.com/package/soundcloud-api-ts)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+[![coverage](https://img.shields.io/badge/coverage-67%25-yellow.svg)]()
+
+A TypeScript client for the SoundCloud API. Zero dependencies, uses native `fetch`.
+
+## Why soundcloud-api-ts?
+
+- **Zero dependencies** — uses native `fetch`, nothing to install
+- **Full TypeScript types** for all API responses
+- **Token management built-in** — `setToken()`, auto-refresh on 401
+- **PKCE support** for public clients and SPAs
+- **Clean API** — `sc.tracks.getTrack(id)` not `getTrack(token, id)`
+- **Dual ESM/CJS output** — works everywhere
+
+## Comparison
+
+| Feature | soundcloud-api-ts | soundcloud.ts | node-soundcloud |
+| --- | --- | --- | --- |
+| TypeScript | ✅ Native | ✅ | ❌ |
+| Dependencies | 0 | varies | varies |
+| OAuth 2.0 | ✅ Full | Partial | Partial |
+| Auto token refresh | ✅ | ❌ | ❌ |
+| PKCE | ✅ | ❌ | ❌ |
+| Maintained | ✅ 2026 | — | — |
 
 ## Install
 
@@ -234,6 +258,32 @@ interface SoundCloudPaginatedResponse<T> {
 }
 ```
 
+### Automatic Pagination
+
+The client provides three helpers that automatically follow `next_href` across pages:
+
+```ts
+// Stream pages — yields T[] for each page
+for await (const page of sc.paginate(() => sc.users.getTracks(userId))) {
+  console.log(`Got ${page.length} tracks`);
+}
+
+// Stream individual items — yields one T at a time
+for await (const track of sc.paginateItems(() => sc.search.tracks("lofi"))) {
+  console.log(track.title);
+}
+
+// Collect all into a flat array (with optional limit)
+const allTracks = await sc.fetchAll(() => sc.users.getTracks(userId));
+const first100 = await sc.fetchAll(() => sc.search.tracks("lofi"), { maxItems: 100 });
+```
+
+The standalone functions are also exported for advanced use:
+
+```ts
+import { paginate, paginateItems, fetchAll, scFetchUrl } from "soundcloud-api-ts";
+```
+
 ## Utilities
 
 ```ts
@@ -243,11 +293,66 @@ 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 18+ (uses native `fetch`)
+- Node.js 20+ (uses native `fetch`)
 - SoundCloud API credentials
 
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
 ## License
 
-MIT
+[MIT](LICENSE) © Twin Paws

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, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudPaginatedResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './types/index.mjs';
-export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.mjs';
+import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } 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,12 +23,18 @@ interface AutoRefreshContext {
         refresh_token?: string;
     }>;
     setToken: (accessToken: string, refreshToken?: string) => void;
+    retry?: RetryConfig;
 }
 /**
  * Make a request to the SoundCloud API using native fetch.
  * Returns parsed JSON, or for 302 redirects returns the Location header.
  */
 declare function scFetch<T>(options: RequestOptions, refreshCtx?: AutoRefreshContext): Promise<T>;
+/**
+ * Fetch an absolute URL (e.g. next_href from paginated responses).
+ * Adds OAuth token if provided.
+ */
+declare function scFetchUrl<T>(url: string, token?: string, retryConfig?: RetryConfig): Promise<T>;
 
 interface UpdateTrackParams {
     title?: string;
@@ -94,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 {
@@ -123,6 +143,36 @@ declare class SoundCloudClient {
     get accessToken(): string | undefined;
     /** Get the currently stored refresh token, if any. */
     get refreshToken(): string | undefined;
+    /**
+     * Async generator that follows `next_href` automatically, yielding each page's `collection`.
+     *
+     * ```ts
+     * for await (const page of sc.paginate(() => sc.search.tracks("lofi"))) {
+     *   console.log(page); // SoundCloudTrack[]
+     * }
+     * ```
+     */
+    paginate<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T[], void, undefined>;
+    /**
+     * Async generator that yields individual items across all pages.
+     *
+     * ```ts
+     * for await (const track of sc.paginateItems(() => sc.search.tracks("lofi"))) {
+     *   console.log(track); // single SoundCloudTrack
+     * }
+     * ```
+     */
+    paginateItems<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T, void, undefined>;
+    /**
+     * Collects all pages into a single flat array.
+     *
+     * ```ts
+     * const allTracks = await sc.fetchAll(() => sc.search.tracks("lofi"), { maxItems: 100 });
+     * ```
+     */
+    fetchAll<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, options?: {
+        maxItems?: number;
+    }): Promise<T[]>;
 }
 declare namespace SoundCloudClient {
     class Auth {
@@ -293,6 +343,21 @@ declare namespace SoundCloudClient {
     }
 }
 
+/**
+ * Async generator that follows `next_href` automatically, yielding each page's `collection`.
+ */
+declare function paginate<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, fetchNext: (url: string) => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T[], void, undefined>;
+/**
+ * Async generator that yields individual items across all pages.
+ */
+declare function paginateItems<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, fetchNext: (url: string) => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T, void, undefined>;
+/**
+ * Collects all pages into a single flat array with an optional max items limit.
+ */
+declare function fetchAll<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, fetchNext: (url: string) => Promise<SoundCloudPaginatedResponse<T>>, options?: {
+    maxItems?: number;
+}): Promise<T[]>;
+
 declare const getClientToken: (clientId: string, clientSecret: string) => Promise<SoundCloudToken>;
 
 declare const getUserToken: (clientId: string, clientSecret: string, redirectUri: string, code: string, codeVerifier?: string) => Promise<SoundCloudToken>;
@@ -437,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, 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, refreshUserToken, repostPlaylist, repostTrack, resolveUrl, scFetch, 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, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudPaginatedResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './types/index.js';
-export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.js';
+import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } 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,12 +23,18 @@ interface AutoRefreshContext {
         refresh_token?: string;
     }>;
     setToken: (accessToken: string, refreshToken?: string) => void;
+    retry?: RetryConfig;
 }
 /**
  * Make a request to the SoundCloud API using native fetch.
  * Returns parsed JSON, or for 302 redirects returns the Location header.
  */
 declare function scFetch<T>(options: RequestOptions, refreshCtx?: AutoRefreshContext): Promise<T>;
+/**
+ * Fetch an absolute URL (e.g. next_href from paginated responses).
+ * Adds OAuth token if provided.
+ */
+declare function scFetchUrl<T>(url: string, token?: string, retryConfig?: RetryConfig): Promise<T>;
 
 interface UpdateTrackParams {
     title?: string;
@@ -94,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 {
@@ -123,6 +143,36 @@ declare class SoundCloudClient {
     get accessToken(): string | undefined;
     /** Get the currently stored refresh token, if any. */
     get refreshToken(): string | undefined;
+    /**
+     * Async generator that follows `next_href` automatically, yielding each page's `collection`.
+     *
+     * ```ts
+     * for await (const page of sc.paginate(() => sc.search.tracks("lofi"))) {
+     *   console.log(page); // SoundCloudTrack[]
+     * }
+     * ```
+     */
+    paginate<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T[], void, undefined>;
+    /**
+     * Async generator that yields individual items across all pages.
+     *
+     * ```ts
+     * for await (const track of sc.paginateItems(() => sc.search.tracks("lofi"))) {
+     *   console.log(track); // single SoundCloudTrack
+     * }
+     * ```
+     */
+    paginateItems<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T, void, undefined>;
+    /**
+     * Collects all pages into a single flat array.
+     *
+     * ```ts
+     * const allTracks = await sc.fetchAll(() => sc.search.tracks("lofi"), { maxItems: 100 });
+     * ```
+     */
+    fetchAll<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, options?: {
+        maxItems?: number;
+    }): Promise<T[]>;
 }
 declare namespace SoundCloudClient {
     class Auth {
@@ -293,6 +343,21 @@ declare namespace SoundCloudClient {
     }
 }
 
+/**
+ * Async generator that follows `next_href` automatically, yielding each page's `collection`.
+ */
+declare function paginate<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, fetchNext: (url: string) => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T[], void, undefined>;
+/**
+ * Async generator that yields individual items across all pages.
+ */
+declare function paginateItems<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, fetchNext: (url: string) => Promise<SoundCloudPaginatedResponse<T>>): AsyncGenerator<T, void, undefined>;
+/**
+ * Collects all pages into a single flat array with an optional max items limit.
+ */
+declare function fetchAll<T>(firstPage: () => Promise<SoundCloudPaginatedResponse<T>>, fetchNext: (url: string) => Promise<SoundCloudPaginatedResponse<T>>, options?: {
+    maxItems?: number;
+}): Promise<T[]>;
+
 declare const getClientToken: (clientId: string, clientSecret: string) => Promise<SoundCloudToken>;
 
 declare const getUserToken: (clientId: string, clientSecret: string, redirectUri: string, code: string, codeVerifier?: string) => Promise<SoundCloudToken>;
@@ -437,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, 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, refreshUserToken, repostPlaylist, repostTrack, resolveUrl, scFetch, 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 };