soundcloud-api-ts 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,8 +1,36 @@
 'use strict';
 
+var chunkDZRZLIAH_js = require('./chunk-DZRZLIAH.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 chunkDZRZLIAH_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 chunkDZRZLIAH_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 chunkDZRZLIAH_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 chunkDZRZLIAH_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 chunkDZRZLIAH_js.SoundCloudError(lastResponse.status, lastResponse.statusText, body);
 }
 
 // src/client/paginate.ts
@@ -114,26 +171,50 @@ exports.SoundCloudClient = class _SoundCloudClient {
   config;
   _accessToken;
   _refreshToken;
+  /** Authentication methods (OAuth token grants, sign out) */
   auth;
+  /** Authenticated user endpoints (/me) */
   me;
+  /** User profile endpoints (/users) */
   users;
+  /** Track endpoints (/tracks) */
   tracks;
+  /** Playlist endpoints (/playlists) */
   playlists;
+  /** Search endpoints */
   search;
+  /** URL resolution endpoint (/resolve) */
   resolve;
+  /** Like/unlike actions (/likes) */
   likes;
+  /** Repost/unrepost actions (/reposts) */
   reposts;
+  /**
+   * Creates a new SoundCloudClient instance.
+   *
+   * @param config - Client configuration including OAuth credentials and optional settings
+   */
   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);
@@ -144,29 +225,38 @@ exports.SoundCloudClient = class _SoundCloudClient {
     this.likes = new _SoundCloudClient.Likes(getToken, refreshCtx);
     this.reposts = new _SoundCloudClient.Reposts(getToken, refreshCtx);
   }
-  /** Store an access token (and optionally refresh token) on this client instance. */
+  /**
+   * Store an access token (and optionally refresh token) on this client instance.
+   *
+   * @param accessToken - The OAuth access token to store
+   * @param refreshToken - Optional refresh token for automatic token renewal
+   */
   setToken(accessToken, refreshToken) {
     this._accessToken = accessToken;
     if (refreshToken !== void 0) this._refreshToken = refreshToken;
   }
-  /** Clear stored tokens. */
+  /** Clear all stored tokens from this client instance. */
   clearToken() {
     this._accessToken = void 0;
     this._refreshToken = void 0;
   }
-  /** Get the currently stored access token, if any. */
+  /** Get the currently stored access token, or `undefined` if none is set. */
   get accessToken() {
     return this._accessToken;
   }
-  /** Get the currently stored refresh token, if any. */
+  /** Get the currently stored refresh token, or `undefined` if none is set. */
   get refreshToken() {
     return this._refreshToken;
   }
   /**
    * Async generator that follows `next_href` automatically, yielding each page's `collection`.
    *
+   * @param firstPage - Function that fetches the first page
+   * @returns An async generator yielding arrays of items (one per page)
+   *
+   * @example
    * ```ts
-   * for await (const page of sc.paginate(() => sc.search.tracks("lofi"))) {
+   * for await (const page of sc.paginate(() => sc.search.tracks('lofi'))) {
    *   console.log(page); // SoundCloudTrack[]
    * }
    * ```
@@ -178,9 +268,13 @@ exports.SoundCloudClient = class _SoundCloudClient {
   /**
    * Async generator that yields individual items across all pages.
    *
+   * @param firstPage - Function that fetches the first page
+   * @returns An async generator yielding individual items
+   *
+   * @example
    * ```ts
-   * for await (const track of sc.paginateItems(() => sc.search.tracks("lofi"))) {
-   *   console.log(track); // single SoundCloudTrack
+   * for await (const track of sc.paginateItems(() => sc.search.tracks('lofi'))) {
+   *   console.log(track.title); // single SoundCloudTrack
    * }
    * ```
    */
@@ -191,8 +285,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
   /**
    * Collects all pages into a single flat array.
    *
+   * @param firstPage - Function that fetches the first page
+   * @param options - Optional configuration
+   * @param options.maxItems - Maximum number of items to collect
+   * @returns A promise resolving to a flat array of all items
+   *
+   * @example
    * ```ts
-   * const allTracks = await sc.fetchAll(() => sc.search.tracks("lofi"), { maxItems: 100 });
+   * const allTracks = await sc.fetchAll(() => sc.search.tracks('lofi'), { maxItems: 100 });
+   * console.log(allTracks.length);
    * ```
    */
   fetchAll(firstPage, options) {
@@ -205,7 +306,23 @@ exports.SoundCloudClient = class _SoundCloudClient {
     constructor(config) {
       this.config = config;
     }
-    /** Build the authorization URL to redirect users to SoundCloud's login. */
+    /**
+     * Build the authorization URL to redirect users to SoundCloud's OAuth login page.
+     *
+     * @param options - Optional parameters for the authorization request
+     * @param options.state - Opaque state value for CSRF protection
+     * @param options.codeChallenge - PKCE S256 code challenge for enhanced security
+     * @returns The full authorization URL to redirect the user to
+     * @throws {Error} If `redirectUri` was not provided in the client config
+     *
+     * @example
+     * ```ts
+     * const url = sc.auth.getAuthorizationUrl({ state: 'random-state' });
+     * // Redirect user to `url`
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2
+     */
     getAuthorizationUrl(options) {
       if (!this.config.redirectUri) throw new Error("redirectUri is required for getAuthorizationUrl");
       const params = new URLSearchParams({
@@ -220,7 +337,20 @@ exports.SoundCloudClient = class _SoundCloudClient {
       }
       return `https://api.soundcloud.com/connect?${params}`;
     }
-    /** POST /oauth2/token — client_credentials grant */
+    /**
+     * Exchange client credentials for an access token (machine-to-machine auth).
+     *
+     * @returns The OAuth token response
+     * @throws {SoundCloudError} When authentication fails
+     *
+     * @example
+     * ```ts
+     * const token = await sc.auth.getClientToken();
+     * sc.setToken(token.access_token);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
+     */
     async getClientToken() {
       return scFetch({
         path: "/oauth2/token",
@@ -232,7 +362,22 @@ exports.SoundCloudClient = class _SoundCloudClient {
         })
       });
     }
-    /** POST /oauth2/token — authorization_code grant */
+    /**
+     * Exchange an authorization code for user tokens (authorization_code grant).
+     *
+     * @param code - The authorization code received from the OAuth callback
+     * @param codeVerifier - PKCE code verifier if a code challenge was used
+     * @returns The OAuth token response including access and refresh tokens
+     * @throws {SoundCloudError} When the code is invalid or expired
+     *
+     * @example
+     * ```ts
+     * const token = await sc.auth.getUserToken(code, codeVerifier);
+     * sc.setToken(token.access_token, token.refresh_token);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
+     */
     async getUserToken(code, codeVerifier) {
       const params = {
         grant_type: "authorization_code",
@@ -248,7 +393,21 @@ exports.SoundCloudClient = class _SoundCloudClient {
         body: new URLSearchParams(params)
       });
     }
-    /** POST /oauth2/token — refresh_token grant */
+    /**
+     * Refresh an expired access token using a refresh token.
+     *
+     * @param refreshToken - The refresh token from a previous token response
+     * @returns A new OAuth token response with fresh access and refresh tokens
+     * @throws {SoundCloudError} When the refresh token is invalid or expired
+     *
+     * @example
+     * ```ts
+     * const newToken = await sc.auth.refreshUserToken(sc.refreshToken!);
+     * sc.setToken(newToken.access_token, newToken.refresh_token);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/oauth2/post_oauth2_token
+     */
     async refreshUserToken(refreshToken) {
       return scFetch({
         path: "/oauth2/token",
@@ -263,10 +422,19 @@ exports.SoundCloudClient = class _SoundCloudClient {
       });
     }
     /**
-     * POST /sign-out — invalidates session.
+     * Invalidate the session associated with an access token.
      *
      * **Note:** This hits `https://secure.soundcloud.com`, NOT the regular
      * `api.soundcloud.com` host used by all other endpoints.
+     *
+     * @param accessToken - The access token to invalidate
+     * @throws {Error} When the sign-out request fails
+     *
+     * @example
+     * ```ts
+     * await sc.auth.signOut(sc.accessToken!);
+     * sc.clearToken();
+     * ```
      */
     async signOut(accessToken) {
       const res = await fetch("https://secure.soundcloud.com/sign-out", {
@@ -286,67 +454,209 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** GET /me */
+    /**
+     * Get the authenticated user's profile.
+     *
+     * @param options - Optional token override
+     * @returns The authenticated user's full profile
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const me = await sc.me.getMe();
+     * console.log(me.username, me.followers_count);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me
+     */
     async getMe(options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: "/me", method: "GET", token: t });
     }
-    /** GET /me/activities */
+    /**
+     * Get the authenticated user's activity feed.
+     *
+     * @param limit - Maximum number of activities per page
+     * @param options - Optional token override
+     * @returns Paginated activities response with `future_href` for polling
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const activities = await sc.me.getActivities(25);
+     * activities.collection.forEach(a => console.log(a.type, a.created_at));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_activities
+     */
     async getActivities(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/activities?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/activities/all/own */
+    /**
+     * Get the authenticated user's own activities (uploads, reposts).
+     *
+     * @param limit - Maximum number of activities per page
+     * @param options - Optional token override
+     * @returns Paginated activities response
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_activities_all_own
+     */
     async getActivitiesOwn(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/activities/all/own?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/activities/tracks */
+    /**
+     * Get track-related activities in the authenticated user's feed.
+     *
+     * @param limit - Maximum number of activities per page
+     * @param options - Optional token override
+     * @returns Paginated activities response filtered to track activities
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_activities_tracks
+     */
     async getActivitiesTracks(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/activities/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/likes/tracks */
+    /**
+     * Get tracks liked by the authenticated user.
+     *
+     * @param limit - Maximum number of tracks per page
+     * @param options - Optional token override
+     * @returns Paginated list of liked tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const likes = await sc.me.getLikesTracks(50);
+     * likes.collection.forEach(t => console.log(t.title));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_likes_tracks
+     */
     async getLikesTracks(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/likes/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/likes/playlists */
+    /**
+     * Get playlists liked by the authenticated user.
+     *
+     * @param limit - Maximum number of playlists per page
+     * @param options - Optional token override
+     * @returns Paginated list of liked playlists
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_likes_playlists
+     */
     async getLikesPlaylists(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/likes/playlists?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/followings */
+    /**
+     * Get users the authenticated user is following.
+     *
+     * @param limit - Maximum number of users per page
+     * @param options - Optional token override
+     * @returns Paginated list of followed users
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_followings
+     */
     async getFollowings(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/followings?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/followings/tracks */
+    /**
+     * Get recent tracks from users the authenticated user is following.
+     *
+     * @param limit - Maximum number of tracks per page
+     * @param options - Optional token override
+     * @returns Paginated list of tracks from followed users
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_followings_tracks
+     */
     async getFollowingsTracks(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/followings/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** PUT /me/followings/:user_urn — follow a user */
+    /**
+     * Follow a user.
+     *
+     * @param userUrn - The user's ID or URN to follow
+     * @param options - Optional token override
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * await sc.me.follow(123456);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/put_me_followings__user_id_
+     */
     async follow(userUrn, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/followings/${userUrn}`, method: "PUT", token: t });
     }
-    /** DELETE /me/followings/:user_urn — unfollow a user */
+    /**
+     * Unfollow a user.
+     *
+     * @param userUrn - The user's ID or URN to unfollow
+     * @param options - Optional token override
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * await sc.me.unfollow(123456);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/delete_me_followings__user_id_
+     */
     async unfollow(userUrn, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/followings/${userUrn}`, method: "DELETE", token: t });
     }
-    /** GET /me/followers */
+    /**
+     * Get the authenticated user's followers.
+     *
+     * @param limit - Maximum number of users per page
+     * @param options - Optional token override
+     * @returns Paginated list of follower users
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_followers
+     */
     async getFollowers(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/followers?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/playlists */
+    /**
+     * Get the authenticated user's playlists.
+     *
+     * @param limit - Maximum number of playlists per page
+     * @param options - Optional token override
+     * @returns Paginated list of playlists
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_playlists
+     */
     async getPlaylists(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/playlists?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /me/tracks */
+    /**
+     * Get the authenticated user's tracks.
+     *
+     * @param limit - Maximum number of tracks per page
+     * @param options - Optional token override
+     * @returns Paginated list of tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_tracks
+     */
     async getTracks(limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
@@ -361,42 +671,133 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** GET /users/:id */
+    /**
+     * Get a user's profile by ID.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param options - Optional token override
+     * @returns The user's public profile
+     * @throws {SoundCloudError} When the user is not found or the API returns an error
+     *
+     * @example
+     * ```ts
+     * const user = await sc.users.getUser(123456);
+     * console.log(user.username, user.followers_count);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id_
+     */
     async getUser(userId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}`, method: "GET", token: t });
     }
-    /** GET /users/:id/followers */
+    /**
+     * Get a user's followers.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param limit - Maximum number of followers per page
+     * @param options - Optional token override
+     * @returns Paginated list of follower users
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__followers
+     */
     async getFollowers(userId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/followers?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /users/:id/followings */
+    /**
+     * Get users that a user is following.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param limit - Maximum number of users per page
+     * @param options - Optional token override
+     * @returns Paginated list of followed users
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__followings
+     */
     async getFollowings(userId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/followings?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /users/:id/tracks */
+    /**
+     * Get a user's public tracks.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param limit - Maximum number of tracks per page
+     * @param options - Optional token override
+     * @returns Paginated list of tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__tracks
+     */
     async getTracks(userId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /users/:id/playlists */
+    /**
+     * Get a user's public playlists.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param limit - Maximum number of playlists per page
+     * @param options - Optional token override
+     * @returns Paginated list of playlists (without full track data)
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__playlists
+     */
     async getPlaylists(userId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/playlists?${limit ? `limit=${limit}&` : ""}linked_partitioning=true&show_tracks=false`, method: "GET", token: t });
     }
-    /** GET /users/:id/likes/tracks */
+    /**
+     * Get tracks liked by a user.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param limit - Maximum number of tracks per page
+     * @param cursor - Pagination cursor from a previous response's `next_href`
+     * @param options - Optional token override
+     * @returns Paginated list of liked tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__likes_tracks
+     */
     async getLikesTracks(userId, limit, cursor, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/likes/tracks?${limit ? `limit=${limit}&` : ""}${cursor ? `cursor=${cursor}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /users/:id/likes/playlists */
+    /**
+     * Get playlists liked by a user.
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param limit - Maximum number of playlists per page
+     * @param options - Optional token override
+     * @returns Paginated list of liked playlists
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__likes_playlists
+     */
     async getLikesPlaylists(userId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/likes/playlists?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /users/:id/web-profiles */
+    /**
+     * Get a user's external web profile links (Twitter, Instagram, etc.).
+     *
+     * @param userId - The user's numeric ID or URN
+     * @param options - Optional token override
+     * @returns Array of web profile objects
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const profiles = await sc.users.getWebProfiles(123456);
+     * profiles.forEach(p => console.log(p.service, p.url));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users__user_id__web_profiles
+     */
     async getWebProfiles(userId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users/${userId}/web-profiles`, method: "GET", token: t });
@@ -411,22 +812,79 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** GET /tracks/:id */
+    /**
+     * Get a track by ID.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @returns The track object with full metadata
+     * @throws {SoundCloudError} When the track is not found or the API returns an error
+     *
+     * @example
+     * ```ts
+     * const track = await sc.tracks.getTrack(123456);
+     * console.log(track.title, track.duration);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id_
+     */
     async getTrack(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}`, method: "GET", token: t });
     }
-    /** GET /tracks/:id/streams */
+    /**
+     * Get stream URLs for a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @returns Object containing available stream URLs (HLS, MP3, preview)
+     * @throws {SoundCloudError} When the track is not found or not streamable
+     *
+     * @example
+     * ```ts
+     * const streams = await sc.tracks.getStreams(123456);
+     * console.log(streams.hls_mp3_128_url);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__streams
+     */
     async getStreams(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}/streams`, method: "GET", token: t });
     }
-    /** GET /tracks/:id/comments */
+    /**
+     * Get comments on a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param limit - Maximum number of comments per page
+     * @param options - Optional token override
+     * @returns Paginated list of comments
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__comments
+     */
     async getComments(trackId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}/comments?threaded=1&filter_replies=0${limit ? `&limit=${limit}` : ""}&linked_partitioning=true`, method: "GET", token: t });
     }
-    /** POST /tracks/:id/comments */
+    /**
+     * Post a comment on a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param body - The comment text
+     * @param timestamp - Position in the track in milliseconds where the comment is placed
+     * @param options - Optional token override
+     * @returns The created comment object
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const comment = await sc.tracks.createComment(123456, 'Great track!', 30000);
+     * console.log(comment.id);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/post_tracks__track_id__comments
+     */
     async createComment(trackId, body, timestamp, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({
@@ -436,27 +894,92 @@ exports.SoundCloudClient = class _SoundCloudClient {
         body: { comment: { body, ...timestamp !== void 0 ? { timestamp } : {} } }
       });
     }
-    /** GET /tracks/:id/favoriters */
+    /**
+     * Get users who have liked (favorited) a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param limit - Maximum number of users per page
+     * @param options - Optional token override
+     * @returns Paginated list of users who liked the track
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__favoriters
+     */
     async getLikes(trackId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}/favoriters?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /tracks/:id/reposters */
+    /**
+     * Get users who have reposted a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param limit - Maximum number of users per page
+     * @param options - Optional token override
+     * @returns Paginated list of users who reposted the track
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__reposters
+     */
     async getReposts(trackId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}/reposters?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** GET /tracks/:id/related */
+    /**
+     * Get tracks related to a given track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param limit - Maximum number of related tracks to return
+     * @param options - Optional token override
+     * @returns Array of related tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const related = await sc.tracks.getRelated(123456, 5);
+     * related.forEach(t => console.log(t.title));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id__related
+     */
     async getRelated(trackId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}/related${limit ? `?limit=${limit}` : ""}`, method: "GET", token: t });
     }
-    /** PUT /tracks/:id — update track metadata */
+    /**
+     * Update a track's metadata.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param params - Fields to update (title, description, genre, etc.)
+     * @param options - Optional token override
+     * @returns The updated track object
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const updated = await sc.tracks.update(123456, { title: 'New Title', genre: 'Electronic' });
+     * console.log(updated.title);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/put_tracks__track_id_
+     */
     async update(trackId, params, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}`, method: "PUT", token: t, body: { track: params } });
     }
-    /** DELETE /tracks/:id */
+    /**
+     * Delete a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * await sc.tracks.delete(123456);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/delete_tracks__track_id_
+     */
     async delete(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}`, method: "DELETE", token: t });
@@ -471,32 +994,114 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** GET /playlists/:id */
+    /**
+     * Get a playlist by ID.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param options - Optional token override
+     * @returns The playlist object with track data
+     * @throws {SoundCloudError} When the playlist is not found or the API returns an error
+     *
+     * @example
+     * ```ts
+     * const playlist = await sc.playlists.getPlaylist(123456);
+     * console.log(playlist.title, playlist.track_count);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/get_playlists__playlist_id_
+     */
     async getPlaylist(playlistId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/playlists/${playlistId}`, method: "GET", token: t });
     }
-    /** GET /playlists/:id/tracks */
+    /**
+     * Get tracks in a playlist.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param limit - Maximum number of tracks per page
+     * @param offset - Number of tracks to skip (for offset-based pagination)
+     * @param options - Optional token override
+     * @returns Paginated list of tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/get_playlists__playlist_id__tracks
+     */
     async getTracks(playlistId, limit, offset, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/playlists/${playlistId}/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true${offset ? `&offset=${offset}` : ""}`, method: "GET", token: t });
     }
-    /** GET /playlists/:id/reposters */
+    /**
+     * Get users who have reposted a playlist.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param limit - Maximum number of users per page
+     * @param options - Optional token override
+     * @returns Paginated list of users who reposted the playlist
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/get_playlists__playlist_id__reposters
+     */
     async getReposts(playlistId, limit, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/playlists/${playlistId}/reposters?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
-    /** POST /playlists — create a playlist */
+    /**
+     * Create a new playlist.
+     *
+     * @param params - Playlist creation parameters (title is required)
+     * @param options - Optional token override
+     * @returns The created playlist object
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const playlist = await sc.playlists.create({
+     *   title: 'My Favorites',
+     *   sharing: 'public',
+     *   tracks: [{ urn: 'soundcloud:tracks:123' }],
+     * });
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/post_playlists
+     */
     async create(params, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: "/playlists", method: "POST", token: t, body: { playlist: params } });
     }
-    /** PUT /playlists/:id — update a playlist */
+    /**
+     * Update a playlist's metadata or track list.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param params - Fields to update
+     * @param options - Optional token override
+     * @returns The updated playlist object
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const updated = await sc.playlists.update(123456, { title: 'Updated Title' });
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/put_playlists__playlist_id_
+     */
     async update(playlistId, params, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/playlists/${playlistId}`, method: "PUT", token: t, body: { playlist: params } });
     }
-    /** DELETE /playlists/:id */
+    /**
+     * Delete a playlist.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param options - Optional token override
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * await sc.playlists.delete(123456);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/delete_playlists__playlist_id_
+     */
     async delete(playlistId, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/playlists/${playlistId}`, method: "DELETE", token: t });
@@ -511,17 +1116,65 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** GET /tracks?q= */
+    /**
+     * Search for tracks by query string.
+     *
+     * @param query - Search query text
+     * @param pageNumber - Zero-based page number (10 results per page)
+     * @param options - Optional token override
+     * @returns Paginated list of matching tracks
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const results = await sc.search.tracks('lofi hip hop');
+     * results.collection.forEach(t => console.log(t.title));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
+     */
     async tracks(query, pageNumber, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks?q=${encodeURIComponent(query)}&linked_partitioning=true&limit=10${pageNumber && pageNumber > 0 ? `&offset=${10 * pageNumber}` : ""}`, method: "GET", token: t });
     }
-    /** GET /users?q= */
+    /**
+     * Search for users by query string.
+     *
+     * @param query - Search query text
+     * @param pageNumber - Zero-based page number (10 results per page)
+     * @param options - Optional token override
+     * @returns Paginated list of matching users
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const results = await sc.search.users('deadmau5');
+     * results.collection.forEach(u => console.log(u.username));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/users/get_users
+     */
     async users(query, pageNumber, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/users?q=${encodeURIComponent(query)}&linked_partitioning=true&limit=10${pageNumber && pageNumber > 0 ? `&offset=${10 * pageNumber}` : ""}`, method: "GET", token: t });
     }
-    /** GET /playlists?q= */
+    /**
+     * Search for playlists by query string.
+     *
+     * @param query - Search query text
+     * @param pageNumber - Zero-based page number (10 results per page)
+     * @param options - Optional token override
+     * @returns Paginated list of matching playlists
+     * @throws {SoundCloudError} When the API returns an error
+     *
+     * @example
+     * ```ts
+     * const results = await sc.search.playlists('chill vibes');
+     * results.collection.forEach(p => console.log(p.title));
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/playlists/get_playlists
+     */
     async playlists(query, pageNumber, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/playlists?q=${encodeURIComponent(query)}&linked_partitioning=true&limit=10${pageNumber && pageNumber > 0 ? `&offset=${10 * pageNumber}` : ""}`, method: "GET", token: t });
@@ -536,7 +1189,22 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** GET /resolve?url= */
+    /**
+     * Resolve a SoundCloud URL to its API resource URL.
+     *
+     * @param url - A SoundCloud URL (e.g. "https://soundcloud.com/artist/track-name")
+     * @param options - Optional token override
+     * @returns The resolved API resource URL (via 302 redirect)
+     * @throws {SoundCloudError} When the URL cannot be resolved
+     *
+     * @example
+     * ```ts
+     * const apiUrl = await sc.resolve.resolveUrl('https://soundcloud.com/deadmau5/strobe');
+     * console.log(apiUrl); // "https://api.soundcloud.com/tracks/..."
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/resolve/get_resolve
+     */
     async resolveUrl(url, options) {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/resolve?url=${encodeURIComponent(url)}`, method: "GET", token: t });
@@ -551,7 +1219,20 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** POST /likes/tracks/:id */
+    /**
+     * Like a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the like was successful, `false` on failure
+     *
+     * @example
+     * ```ts
+     * const success = await sc.likes.likeTrack(123456);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/likes/post_likes_tracks__track_id_
+     */
     async likeTrack(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -561,7 +1242,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
         return false;
       }
     }
-    /** DELETE /likes/tracks/:id */
+    /**
+     * Unlike a track.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the unlike was successful, `false` on failure
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/likes/delete_likes_tracks__track_id_
+     */
     async unlikeTrack(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -571,7 +1260,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
         return false;
       }
     }
-    /** POST /likes/playlists/:id */
+    /**
+     * Like a playlist.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the like was successful, `false` on failure
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/likes/post_likes_playlists__playlist_id_
+     */
     async likePlaylist(playlistId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -581,7 +1278,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
         return false;
       }
     }
-    /** DELETE /likes/playlists/:id */
+    /**
+     * Unlike a playlist.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the unlike was successful, `false` on failure
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/likes/delete_likes_playlists__playlist_id_
+     */
     async unlikePlaylist(playlistId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -601,7 +1306,20 @@ exports.SoundCloudClient = class _SoundCloudClient {
     fetch(opts) {
       return scFetch(opts, this.refreshCtx);
     }
-    /** POST /reposts/tracks/:id */
+    /**
+     * Repost a track to your profile.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the repost was successful, `false` on failure
+     *
+     * @example
+     * ```ts
+     * const success = await sc.reposts.repostTrack(123456);
+     * ```
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/reposts/post_reposts_tracks__track_id_
+     */
     async repostTrack(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -611,7 +1329,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
         return false;
       }
     }
-    /** DELETE /reposts/tracks/:id */
+    /**
+     * Remove a track repost from your profile.
+     *
+     * @param trackId - The track's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the unrepost was successful, `false` on failure
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/reposts/delete_reposts_tracks__track_id_
+     */
     async unrepostTrack(trackId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -621,7 +1347,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
         return false;
       }
     }
-    /** POST /reposts/playlists/:id */
+    /**
+     * Repost a playlist to your profile.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the repost was successful, `false` on failure
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/reposts/post_reposts_playlists__playlist_id_
+     */
     async repostPlaylist(playlistId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -631,7 +1365,15 @@ exports.SoundCloudClient = class _SoundCloudClient {
         return false;
       }
     }
-    /** DELETE /reposts/playlists/:id */
+    /**
+     * Remove a playlist repost from your profile.
+     *
+     * @param playlistId - The playlist's numeric ID or URN
+     * @param options - Optional token override
+     * @returns `true` if the unrepost was successful, `false` on failure
+     *
+     * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/reposts/delete_reposts_playlists__playlist_id_
+     */
     async unrepostPlaylist(playlistId, options) {
       const t = resolveToken(this.getToken, options?.token);
       try {
@@ -935,6 +1677,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 chunkDZRZLIAH_js.SoundCloudError; }
+});
 exports.createPlaylist = createPlaylist;
 exports.createTrackComment = createTrackComment;
 exports.deletePlaylist = deletePlaylist;