SoundCloud Public API Specification

/**
 * SoundCloudPublicAPISpecification - generated by OmniStream from SoundCloud Public API Specification's OpenAPI spec.
 * One typed method per endpoint. A single Omni key reaches the API.
 */
const DEFAULT_BASE = "https://grid.skinvaults.online/v1/proxy/soundcloud";

export class SoundCloudPublicAPISpecificationError extends Error {
  status: number;
  code?: string;
  constructor(status: number, code: string | undefined, message?: string) {
    super(message || `SoundCloudPublicAPISpecification error ${status}`);
    this.name = "SoundCloudPublicAPISpecificationError";
    this.status = status;
    this.code = code;
  }
}

export interface SoundCloudPublicAPISpecificationOptions {
  baseUrl?: string;
  fetch?: typeof fetch;
  timeoutMs?: number;
}

export class SoundCloudPublicAPISpecification {
  /** @param token Your OmniStream key (one key for every API). */
  constructor(private token: string, private opts: SoundCloudPublicAPISpecificationOptions = {}) {
    if (!token) throw new Error("SoundCloudPublicAPISpecification: token is required");
  }
  rateLimit: { remainingMinute?: number; remainingDay?: number } | null = null;

  private async _request(method: string, path: string, { params, body }: { params?: Record<string, unknown>; body?: unknown } = {}): Promise<any> {
    const f = this.opts.fetch ?? globalThis.fetch;
    const url = new URL((this.opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "") + path);
    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
    const headers: Record<string, string> = { "x-omni-key": this.token };
    if (body !== undefined) headers["content-type"] = "application/json";
    const res = await f(url, { method, headers, body: body !== undefined ? JSON.stringify(body) : undefined });
    this.rateLimit = {
      remainingMinute: Number(res.headers.get("x-ratelimit-remaining-minute")) || undefined,
      remainingDay: Number(res.headers.get("x-ratelimit-remaining-day")) || undefined,
    };
    const data = await res.json().catch(() => ({}));
    if (!res.ok) throw new SoundCloudPublicAPISpecificationError(res.status, data?.error?.code, data?.error?.message);
    return data.data ?? data;
  }

  /** The OAuth2 authorization endpoint. Your app redirects a user to this endpoint, allowing them to delegate access to their account. */
  getconnect(params: { "client_id": string; "redirect_uri": string; "response_type": string; "scope": string; "state"?: string }): Promise<any> {
    return this._request("GET", "/connect", { params });
  }

  /** Likes a playlist. */
  postlikesPlaylistsPlaylistId(params: { "playlist_id": number }): Promise<any> {
    return this._request("POST", "/likes/playlists/{playlist_id}", { params });
  }

  /** Unlikes a playlist. */
  deletelikesPlaylistsPlaylistId(params: { "playlist_id": number }): Promise<any> {
    return this._request("DELETE", "/likes/playlists/{playlist_id}", { params });
  }

  /** Likes a track. */
  postlikesTracksTrackId(params: { "track_id": number }): Promise<any> {
    return this._request("POST", "/likes/tracks/{track_id}", { params });
  }

  /** Unlikes a track. */
  deletelikesTracksTrackId(params: { "track_id": number }): Promise<any> {
    return this._request("DELETE", "/likes/tracks/{track_id}", { params });
  }

  /** Returns the authenticated user’s information. */
  getme(): Promise<any> {
    return this._request("GET", "/me", {});
  }

  /** Returns the authenticated user's activities. */
  getmeActivities(params: { "access"?: unknown[]; "limit"?: number }): Promise<any> {
    return this._request("GET", "/me/activities", { params });
  }

  /** Recent the authenticated user's activities. */
  getmeActivitiesAllOwn(params: { "access"?: unknown[]; "limit"?: number }): Promise<any> {
    return this._request("GET", "/me/activities/all/own", { params });
  }

  /** Returns the authenticated user's recent track related activities. */
  getmeActivitiesTracks(params: { "access"?: unknown[]; "limit"?: number }): Promise<any> {
    return this._request("GET", "/me/activities/tracks", { params });
  }

  /** Returns a list of the authenticated user's connected social accounts. */
  getmeConnections(params: { "limit"?: number; "offset"?: number }): Promise<any> {
    return this._request("GET", "/me/connections", { params });
  }

  /** Returns the authenticated user's connected social account. */
  getmeConnectionsConnectionId(params: { "connection_id": number }): Promise<any> {
    return this._request("GET", "/me/connections/{connection_id}", { params });
  }

  /** Returns a list of users who are following the authenticated user. */
  getmeFollowers(params: { "limit"?: number }): Promise<any> {
    return this._request("GET", "/me/followers", { params });
  }

  /** Returns a list of users who are followed by the authenticated user. */
  getmeFollowings(params: { "limit"?: number; "offset"?: number }): Promise<any> {
    return this._request("GET", "/me/followings", { params });
  }

  /** Returns a list of recent tracks from users followed by the authenticated user. */
  getmeFollowingsTracks(params: { "access"?: unknown[]; "limit"?: number; "offset"?: number }): Promise<any> {
    return this._request("GET", "/me/followings/tracks", { params });
  }

  /** Follows a user. */
  putmeFollowingsUserId(params: { "user_id": number }): Promise<any> {
    return this._request("PUT", "/me/followings/{user_id}", { params });
  }

  /** Deletes a user who is followed by the authenticated user. */
  deletemeFollowingsUserId(params: { "user_id": number }): Promise<any> {
    return this._request("DELETE", "/me/followings/{user_id}", { params });
  }

  /** Returns a list of favorited or liked tracks of the authenticated user. */
  getmeLikesTracks(params: { "limit"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/me/likes/tracks", { params });
  }

  /** Returns user’s playlists (sets). */
  getmePlaylists(params: { "limit"?: number }): Promise<any> {
    return this._request("GET", "/me/playlists", { params });
  }

  /** Returns a list of user's tracks. */
  getmeTracks(params: { "limit"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/me/tracks", { params });
  }

  /** This endpoint accepts POST requests and is used to provision access tokens once a user has authorized your application. */
  postoauth2Token(): Promise<any> {
    return this._request("POST", "/oauth2/token", {  });
  }

  /** Performs a playlist search based on a query */
  getplaylists(params: { "q": string; "access"?: unknown[]; "limit"?: number; "offset"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/playlists", { params });
  }

  /** Creates a playlist. */
  postplaylists(body: unknown): Promise<any> {
    return this._request("POST", "/playlists", { body });
  }

  /** Returns a playlist. */
  getplaylistsPlaylistId(params: { "playlist_id": number; "secret_token"?: string; "access"?: unknown[] }): Promise<any> {
    return this._request("GET", "/playlists/{playlist_id}", { params });
  }

  /** Updates a playlist. */
  putplaylistsPlaylistId(body: unknown, params: { "playlist_id": number }): Promise<any> {
    return this._request("PUT", "/playlists/{playlist_id}", { body, params });
  }

  /** Deletes a playlist. */
  deleteplaylistsPlaylistId(params: { "playlist_id": number }): Promise<any> {
    return this._request("DELETE", "/playlists/{playlist_id}", { params });
  }

  /** Returns a collection of playlist's reposters. */
  getplaylistsPlaylistIdReposters(params: { "playlist_id": number; "limit"?: number }): Promise<any> {
    return this._request("GET", "/playlists/{playlist_id}/reposters", { params });
  }

  /** Returns tracks under a playlist. */
  getplaylistsPlaylistIdTracks(params: { "playlist_id": number; "secret_token"?: string; "access"?: unknown[]; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/playlists/{playlist_id}/tracks", { params });
  }

  /** Reposts a playlist as the authenticated user */
  postrepostsPlaylistsPlaylistId(params: { "playlist_id": number }): Promise<any> {
    return this._request("POST", "/reposts/playlists/{playlist_id}", { params });
  }

  /** Removes a repost on a playlist as the authenticated user */
  deleterepostsPlaylistsPlaylistId(params: { "playlist_id": number }): Promise<any> {
    return this._request("DELETE", "/reposts/playlists/{playlist_id}", { params });
  }

  /** Reposts a track as the authenticated user */
  postrepostsTracksTrackId(params: { "track_id": number }): Promise<any> {
    return this._request("POST", "/reposts/tracks/{track_id}", { params });
  }

  /** Removes a repost on a track as the authenticated user */
  deleterepostsTracksTrackId(params: { "track_id": number }): Promise<any> {
    return this._request("DELETE", "/reposts/tracks/{track_id}", { params });
  }

  /** Resolves soundcloud.com URLs to Resource URLs to use with the API. */
  getresolve(params: { "url": string }): Promise<any> {
    return this._request("GET", "/resolve", { params });
  }

  /** Performs a track search based on a query */
  gettracks(params: { "q": string; "ids"?: string; "genres"?: string; "tags"?: string; "bpm"?: string; "duration"?: string; "created_at"?: string; "access"?: unknown[]; "limit"?: number; "offset"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/tracks", { params });
  }

  /** Uploads a new track. */
  posttracks(): Promise<any> {
    return this._request("POST", "/tracks", {  });
  }

  /** Returns a track. */
  gettracksTrackId(params: { "track_id": number; "secret_token"?: string }): Promise<any> {
    return this._request("GET", "/tracks/{track_id}", { params });
  }

  /** Updates a track's information. */
  puttracksTrackId(body: unknown, params: { "track_id": number }): Promise<any> {
    return this._request("PUT", "/tracks/{track_id}", { body, params });
  }

  /** Deletes a track. */
  deletetracksTrackId(params: { "track_id": number }): Promise<any> {
    return this._request("DELETE", "/tracks/{track_id}", { params });
  }

  /** Returns the comments posted on the track(track_id). */
  gettracksTrackIdComments(params: { "track_id": number; "limit"?: number; "offset"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/tracks/{track_id}/comments", { params });
  }

  /** Returns the newly created comment on success */
  posttracksTrackIdComments(params: { "track_id": number }): Promise<any> {
    return this._request("POST", "/tracks/{track_id}/comments", { params });
  }

  /** Returns a list of users who have favorited or liked the track. */
  gettracksTrackIdFavoriters(params: { "track_id": number; "limit"?: number; "offset"?: number }): Promise<any> {
    return this._request("GET", "/tracks/{track_id}/favoriters", { params });
  }

  /** Returns all related tracks of track on SoundCloud. */
  gettracksTrackIdRelated(params: { "track_id": number; "access"?: unknown[]; "limit"?: number; "offset"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/tracks/{track_id}/related", { params });
  }

  /** Returns a collection of track's reposters. */
  gettracksTrackIdReposters(params: { "track_id": number; "limit"?: number }): Promise<any> {
    return this._request("GET", "/tracks/{track_id}/reposters", { params });
  }

  /** Returns a track's streamable URLs */
  gettracksTrackIdStreams(params: { "track_id": number; "secret_token"?: string }): Promise<any> {
    return this._request("GET", "/tracks/{track_id}/streams", { params });
  }

  /** Performs a user search based on a query */
  getusers(params: { "q": string; "ids"?: string; "limit"?: number; "offset"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/users", { params });
  }

  /** Returns a user. */
  getusersUserId(params: { "user_id": number }): Promise<any> {
    return this._request("GET", "/users/{user_id}", { params });
  }

  /** Returns a list of user's comments. */
  getusersUserIdComments(params: { "user_id": number; "limit"?: number; "offset"?: number }): Promise<any> {
    return this._request("GET", "/users/{user_id}/comments", { params });
  }

  /** Returns a list of user’s followers. */
  getusersUserIdFollowers(params: { "user_id": number; "limit"?: number }): Promise<any> {
    return this._request("GET", "/users/{user_id}/followers", { params });
  }

  /** Returns a list of user’s followings. */
  getusersUserIdFollowings(params: { "user_id": number; "limit"?: number }): Promise<any> {
    return this._request("GET", "/users/{user_id}/followings", { params });
  }

  /** Returns a list of user's liked tracks. */
  getusersUserIdLikesTracks(params: { "user_id": number; "access"?: unknown[]; "limit"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/users/{user_id}/likes/tracks", { params });
  }

  /** Returns a list of user's playlists. */
  getusersUserIdPlaylists(params: { "user_id": number; "access"?: unknown[]; "limit"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/users/{user_id}/playlists", { params });
  }

  /** Returns a list of user's tracks. */
  getusersUserIdTracks(params: { "user_id": number; "access"?: unknown[]; "limit"?: number; "linked_partitioning"?: boolean }): Promise<any> {
    return this._request("GET", "/users/{user_id}/tracks", { params });
  }

  /** Returns list of user's links added to their profile (website, facebook, instagram). */
  getusersUserIdWebProfiles(params: { "user_id": number; "limit"?: number }): Promise<any> {
    return this._request("GET", "/users/{user_id}/web-profiles", { params });
  }
}

export default SoundCloudPublicAPISpecification;