soundcloud-api-ts 1.2.0 → 1.4.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-ALTJSKVN.mjs

@@ -0,0 +1,57 @@
+// src/errors.ts
+var SoundCloudError = class extends Error {
+  /** HTTP status code of the failed response (e.g. 401, 404, 429) */
+  status;
+  /** HTTP status text of the failed response (e.g. "Unauthorized", "Not Found") */
+  statusText;
+  /** Machine-readable error code from SoundCloud (e.g. "invalid_client"), if present */
+  errorCode;
+  /** Link to SoundCloud API documentation, if included in the error response */
+  docsLink;
+  /** Individual error messages extracted from the response body's `errors` array */
+  errors;
+  /** The full parsed error response body, if available */
+  body;
+  /**
+   * Creates a new SoundCloudError.
+   *
+   * @param status - HTTP status code
+   * @param statusText - HTTP status text
+   * @param body - Parsed JSON error response body from SoundCloud, if available
+   */
+  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 (invalid or expired token) */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True if status is 403 Forbidden (insufficient permissions) */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** True if status is 404 Not Found (resource does not exist) */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** True if status is 429 Too Many Requests (rate limit exceeded) */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  /** True if status is 5xx (SoundCloud server error) */
+  get isServerError() {
+    return this.status >= 500 && this.status < 600;
+  }
+};
+
+export { SoundCloudError };
+//# sourceMappingURL=chunk-ALTJSKVN.mjs.map
+//# sourceMappingURL=chunk-ALTJSKVN.mjs.map

package/dist/chunk-ALTJSKVN.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";AA6DO,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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,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-ALTJSKVN.mjs","sourcesContent":["/**\n * Shape of error response bodies returned by the SoundCloud API.\n *\n * The API returns varying combinations of these fields depending on the endpoint\n * and error type. All fields are optional.\n *\n * @example\n * ```json\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 * ```\n *\n * @see https://developers.soundcloud.com/docs/api/explorer/open-api\n */\nexport interface SoundCloudErrorBody {\n  /** HTTP status code echoed in the response body */\n  code?: number;\n  /** Error message from SoundCloud (e.g. \"invalid_client\", \"404 - Not Found\") */\n  message?: string;\n  /** Human-readable status string (e.g. \"401 - Unauthorized\") */\n  status?: string;\n  /** Link to SoundCloud API documentation */\n  link?: string;\n  /** Array of individual error detail objects */\n  errors?: Array<{ error_message?: string }>;\n  /** Generic error field — typically null in SoundCloud responses */\n  error?: string | null;\n  /** Machine-readable error code (e.g. \"invalid_client\") */\n  error_code?: string;\n  /** OAuth error description, present in `/oauth2/token` error responses */\n  error_description?: string;\n}\n\n/**\n * Error class thrown when a SoundCloud API request fails.\n *\n * Provides structured access to HTTP status, error codes, and convenience\n * getters for common error categories.\n *\n * @example\n * ```ts\n * import { SoundCloudError } from 'tsd-soundcloud';\n *\n * try {\n *   await sc.tracks.getTrack(999999999);\n * } catch (err) {\n *   if (err instanceof SoundCloudError) {\n *     if (err.isNotFound) console.log('Track not found');\n *     if (err.isRateLimited) console.log('Rate limited, retry later');\n *     console.log(err.status, err.message);\n *   }\n * }\n * ```\n */\nexport class SoundCloudError extends Error {\n  /** HTTP status code of the failed response (e.g. 401, 404, 429) */\n  readonly status: number;\n  /** HTTP status text of the failed response (e.g. \"Unauthorized\", \"Not Found\") */\n  readonly statusText: string;\n  /** Machine-readable error code from SoundCloud (e.g. \"invalid_client\"), if present */\n  readonly errorCode?: string;\n  /** Link to SoundCloud API documentation, if included in the error response */\n  readonly docsLink?: string;\n  /** Individual error messages extracted from the response body's `errors` array */\n  readonly errors: string[];\n  /** The full parsed error response body, if available */\n  readonly body?: SoundCloudErrorBody;\n\n  /**\n   * Creates a new SoundCloudError.\n   *\n   * @param status - HTTP status code\n   * @param statusText - HTTP status text\n   * @param body - Parsed JSON error response body from SoundCloud, if available\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 (invalid or expired token) */\n  get isUnauthorized(): boolean {\n    return this.status === 401;\n  }\n\n  /** True if status is 403 Forbidden (insufficient permissions) */\n  get isForbidden(): boolean {\n    return this.status === 403;\n  }\n\n  /** True if status is 404 Not Found (resource does not exist) */\n  get isNotFound(): boolean {\n    return this.status === 404;\n  }\n\n  /** True if status is 429 Too Many Requests (rate limit exceeded) */\n  get isRateLimited(): boolean {\n    return this.status === 429;\n  }\n\n  /** True if status is 5xx (SoundCloud server error) */\n  get isServerError(): boolean {\n    return this.status >= 500 && this.status < 600;\n  }\n}\n"]}

package/dist/chunk-DZRZLIAH.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// src/errors.ts
+var SoundCloudError = class extends Error {
+  /** HTTP status code of the failed response (e.g. 401, 404, 429) */
+  status;
+  /** HTTP status text of the failed response (e.g. "Unauthorized", "Not Found") */
+  statusText;
+  /** Machine-readable error code from SoundCloud (e.g. "invalid_client"), if present */
+  errorCode;
+  /** Link to SoundCloud API documentation, if included in the error response */
+  docsLink;
+  /** Individual error messages extracted from the response body's `errors` array */
+  errors;
+  /** The full parsed error response body, if available */
+  body;
+  /**
+   * Creates a new SoundCloudError.
+   *
+   * @param status - HTTP status code
+   * @param statusText - HTTP status text
+   * @param body - Parsed JSON error response body from SoundCloud, if available
+   */
+  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 (invalid or expired token) */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True if status is 403 Forbidden (insufficient permissions) */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** True if status is 404 Not Found (resource does not exist) */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** True if status is 429 Too Many Requests (rate limit exceeded) */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+  /** True if status is 5xx (SoundCloud server error) */
+  get isServerError() {
+    return this.status >= 500 && this.status < 600;
+  }
+};
+
+exports.SoundCloudError = SoundCloudError;
+//# sourceMappingURL=chunk-DZRZLIAH.js.map
+//# sourceMappingURL=chunk-DZRZLIAH.js.map

package/dist/chunk-DZRZLIAH.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":";;;AA6DO,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;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAST,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-DZRZLIAH.js","sourcesContent":["/**\n * Shape of error response bodies returned by the SoundCloud API.\n *\n * The API returns varying combinations of these fields depending on the endpoint\n * and error type. All fields are optional.\n *\n * @example\n * ```json\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 * ```\n *\n * @see https://developers.soundcloud.com/docs/api/explorer/open-api\n */\nexport interface SoundCloudErrorBody {\n  /** HTTP status code echoed in the response body */\n  code?: number;\n  /** Error message from SoundCloud (e.g. \"invalid_client\", \"404 - Not Found\") */\n  message?: string;\n  /** Human-readable status string (e.g. \"401 - Unauthorized\") */\n  status?: string;\n  /** Link to SoundCloud API documentation */\n  link?: string;\n  /** Array of individual error detail objects */\n  errors?: Array<{ error_message?: string }>;\n  /** Generic error field — typically null in SoundCloud responses */\n  error?: string | null;\n  /** Machine-readable error code (e.g. \"invalid_client\") */\n  error_code?: string;\n  /** OAuth error description, present in `/oauth2/token` error responses */\n  error_description?: string;\n}\n\n/**\n * Error class thrown when a SoundCloud API request fails.\n *\n * Provides structured access to HTTP status, error codes, and convenience\n * getters for common error categories.\n *\n * @example\n * ```ts\n * import { SoundCloudError } from 'tsd-soundcloud';\n *\n * try {\n *   await sc.tracks.getTrack(999999999);\n * } catch (err) {\n *   if (err instanceof SoundCloudError) {\n *     if (err.isNotFound) console.log('Track not found');\n *     if (err.isRateLimited) console.log('Rate limited, retry later');\n *     console.log(err.status, err.message);\n *   }\n * }\n * ```\n */\nexport class SoundCloudError extends Error {\n  /** HTTP status code of the failed response (e.g. 401, 404, 429) */\n  readonly status: number;\n  /** HTTP status text of the failed response (e.g. \"Unauthorized\", \"Not Found\") */\n  readonly statusText: string;\n  /** Machine-readable error code from SoundCloud (e.g. \"invalid_client\"), if present */\n  readonly errorCode?: string;\n  /** Link to SoundCloud API documentation, if included in the error response */\n  readonly docsLink?: string;\n  /** Individual error messages extracted from the response body's `errors` array */\n  readonly errors: string[];\n  /** The full parsed error response body, if available */\n  readonly body?: SoundCloudErrorBody;\n\n  /**\n   * Creates a new SoundCloudError.\n   *\n   * @param status - HTTP status code\n   * @param statusText - HTTP status text\n   * @param body - Parsed JSON error response body from SoundCloud, if available\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 (invalid or expired token) */\n  get isUnauthorized(): boolean {\n    return this.status === 401;\n  }\n\n  /** True if status is 403 Forbidden (insufficient permissions) */\n  get isForbidden(): boolean {\n    return this.status === 403;\n  }\n\n  /** True if status is 404 Not Found (resource does not exist) */\n  get isNotFound(): boolean {\n    return this.status === 404;\n  }\n\n  /** True if status is 429 Too Many Requests (rate limit exceeded) */\n  get isRateLimited(): boolean {\n    return this.status === 429;\n  }\n\n  /** True if status is 5xx (SoundCloud server error) */\n  get isServerError(): boolean {\n    return this.status >= 500 && this.status < 600;\n  }\n}\n"]}