soundcloud-api-ts 1.12.0 → 1.13.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +11 -1
- package/README.md +38 -25
- package/dist/{chunk-JLRQJWU5.mjs → chunk-CCHK5S6S.mjs} +86 -11
- package/dist/chunk-CCHK5S6S.mjs.map +1 -0
- package/dist/{chunk-D7AF372V.js → chunk-RS2J5LTS.js} +87 -10
- package/dist/chunk-RS2J5LTS.js.map +1 -0
- package/dist/cli.js +6 -6
- package/dist/cli.mjs +1 -1
- package/dist/index-DX6Anc1-.d.mts +582 -0
- package/dist/index-DX6Anc1-.d.ts +582 -0
- package/dist/index.d.mts +158 -3
- package/dist/index.d.ts +158 -3
- package/dist/index.js +74 -66
- package/dist/index.mjs +1 -1
- package/dist/types/index.d.mts +1 -555
- package/dist/types/index.d.ts +1 -555
- package/llms.txt +33 -1
- package/package.json +2 -2
- package/dist/chunk-D7AF372V.js.map +0 -1
- package/dist/chunk-JLRQJWU5.mjs.map +0 -1
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './
|
|
2
|
-
export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudError, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './
|
|
1
|
+
import { S as SoundCloudTrack, a as SoundCloudPlaylist, b as SoundCloudToken, c as SoundCloudPaginatedResponse, d as SoundCloudMe, e as SoundCloudActivitiesResponse, f as SoundCloudUser, g as SoundCloudConnection, h as SoundCloudWebProfile, i as SoundCloudStreams, j as SoundCloudComment } from './index-DX6Anc1-.mjs';
|
|
2
|
+
export { k as SoundCloudActivity, l as SoundCloudCommentUser, m as SoundCloudError, n as SoundCloudQuota, o as SoundCloudSubscription, p as SoundCloudSubscriptionProduct } from './index-DX6Anc1-.mjs';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Options for making a request to the SoundCloud API via {@link scFetch}.
|
|
@@ -855,6 +855,24 @@ declare namespace SoundCloudClient {
|
|
|
855
855
|
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_tracks
|
|
856
856
|
*/
|
|
857
857
|
getTracks(limit?: number, options?: TokenOption): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>;
|
|
858
|
+
/**
|
|
859
|
+
* List the authenticated user's connected external social accounts.
|
|
860
|
+
*
|
|
861
|
+
* @param options - Optional token override
|
|
862
|
+
* @returns Array of connection objects for linked social services (Twitter, Facebook, etc.)
|
|
863
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
864
|
+
*
|
|
865
|
+
* @remarks This endpoint may require elevated API access or app approval.
|
|
866
|
+
*
|
|
867
|
+
* @example
|
|
868
|
+
* ```ts
|
|
869
|
+
* const connections = await sc.me.getConnections();
|
|
870
|
+
* connections.forEach(c => console.log(c.service, c.display_name));
|
|
871
|
+
* ```
|
|
872
|
+
*
|
|
873
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
|
|
874
|
+
*/
|
|
875
|
+
getConnections(options?: TokenOption): Promise<SoundCloudConnection[]>;
|
|
858
876
|
}
|
|
859
877
|
/**
|
|
860
878
|
* User profile namespace — fetch public user data.
|
|
@@ -1001,6 +1019,28 @@ declare namespace SoundCloudClient {
|
|
|
1001
1019
|
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id_
|
|
1002
1020
|
*/
|
|
1003
1021
|
getTrack(trackId: string | number, options?: TokenOption): Promise<SoundCloudTrack>;
|
|
1022
|
+
/**
|
|
1023
|
+
* Fetch multiple tracks by their IDs in a single request.
|
|
1024
|
+
*
|
|
1025
|
+
* @param ids - Array of track IDs (numeric or string URNs)
|
|
1026
|
+
* @param options - Optional token override
|
|
1027
|
+
* @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
|
|
1028
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
1029
|
+
* @throws {Error} When more than 200 IDs are provided
|
|
1030
|
+
*
|
|
1031
|
+
* @remarks
|
|
1032
|
+
* SoundCloud's API likely caps at ~200 IDs per request. Passing more than 200 IDs
|
|
1033
|
+
* will throw immediately without making a network request.
|
|
1034
|
+
*
|
|
1035
|
+
* @example
|
|
1036
|
+
* ```ts
|
|
1037
|
+
* const tracks = await sc.tracks.getTracks([123456, 234567, 345678]);
|
|
1038
|
+
* tracks.forEach(t => console.log(t.title));
|
|
1039
|
+
* ```
|
|
1040
|
+
*
|
|
1041
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
|
|
1042
|
+
*/
|
|
1043
|
+
getTracks(ids: (string | number)[], options?: TokenOption): Promise<SoundCloudTrack[]>;
|
|
1004
1044
|
/**
|
|
1005
1045
|
* Get stream URLs for a track.
|
|
1006
1046
|
*
|
|
@@ -1723,6 +1763,75 @@ declare function generateCodeVerifier(): string;
|
|
|
1723
1763
|
*/
|
|
1724
1764
|
declare function generateCodeChallenge(verifier: string): Promise<string>;
|
|
1725
1765
|
|
|
1766
|
+
/**
|
|
1767
|
+
* Contract for a pluggable token provider that manages OAuth token lifecycle.
|
|
1768
|
+
*
|
|
1769
|
+
* Implement this interface to integrate soundcloud-api-ts with your
|
|
1770
|
+
* framework's session management, e.g. NextAuth, Clerk, Redis, or a simple
|
|
1771
|
+
* in-memory store.
|
|
1772
|
+
*
|
|
1773
|
+
* @example
|
|
1774
|
+
* ```ts
|
|
1775
|
+
* class InMemoryTokenProvider implements TokenProvider {
|
|
1776
|
+
* private _accessToken?: string;
|
|
1777
|
+
* private _refreshToken?: string;
|
|
1778
|
+
*
|
|
1779
|
+
* getAccessToken() { return this._accessToken; }
|
|
1780
|
+
* setTokens(access: string, refresh?: string) {
|
|
1781
|
+
* this._accessToken = access;
|
|
1782
|
+
* this._refreshToken = refresh;
|
|
1783
|
+
* }
|
|
1784
|
+
* async refreshIfNeeded(client: SoundCloudClient) {
|
|
1785
|
+
* if (!this._refreshToken) throw new Error('No refresh token');
|
|
1786
|
+
* const token = await client.auth.refreshUserToken(this._refreshToken);
|
|
1787
|
+
* this.setTokens(token.access_token, token.refresh_token);
|
|
1788
|
+
* return token.access_token;
|
|
1789
|
+
* }
|
|
1790
|
+
* }
|
|
1791
|
+
* ```
|
|
1792
|
+
*
|
|
1793
|
+
* @see docs/auth-guide.md
|
|
1794
|
+
*/
|
|
1795
|
+
interface TokenProvider {
|
|
1796
|
+
/** Returns the current access token, or undefined if none is stored. */
|
|
1797
|
+
getAccessToken(): string | undefined | Promise<string | undefined>;
|
|
1798
|
+
/** Persist new tokens (called after a successful token grant or refresh). */
|
|
1799
|
+
setTokens(accessToken: string, refreshToken?: string): void | Promise<void>;
|
|
1800
|
+
/**
|
|
1801
|
+
* Ensure a valid access token is available, refreshing if necessary.
|
|
1802
|
+
* Called automatically when a request returns 401 Unauthorized.
|
|
1803
|
+
*/
|
|
1804
|
+
refreshIfNeeded(client: SoundCloudClient): Promise<string> | string;
|
|
1805
|
+
}
|
|
1806
|
+
/**
|
|
1807
|
+
* Minimal synchronous key–value store for OAuth tokens.
|
|
1808
|
+
*
|
|
1809
|
+
* Useful for implementing a simple in-memory or cookie-backed token store
|
|
1810
|
+
* without the full async lifecycle of {@link TokenProvider}.
|
|
1811
|
+
*
|
|
1812
|
+
* @example
|
|
1813
|
+
* ```ts
|
|
1814
|
+
* class CookieTokenStore implements TokenStore {
|
|
1815
|
+
* getAccessToken() { return getCookie('sc_access_token') ?? undefined; }
|
|
1816
|
+
* getRefreshToken() { return getCookie('sc_refresh_token') ?? undefined; }
|
|
1817
|
+
* setTokens(a, r) { setCookie('sc_access_token', a); if (r) setCookie('sc_refresh_token', r); }
|
|
1818
|
+
* clearTokens() { deleteCookie('sc_access_token'); deleteCookie('sc_refresh_token'); }
|
|
1819
|
+
* }
|
|
1820
|
+
* ```
|
|
1821
|
+
*
|
|
1822
|
+
* @see docs/auth-guide.md
|
|
1823
|
+
*/
|
|
1824
|
+
interface TokenStore {
|
|
1825
|
+
/** Returns the stored access token, or undefined if none. */
|
|
1826
|
+
getAccessToken(): string | undefined;
|
|
1827
|
+
/** Returns the stored refresh token, or undefined if none. */
|
|
1828
|
+
getRefreshToken(): string | undefined;
|
|
1829
|
+
/** Persist new tokens. */
|
|
1830
|
+
setTokens(accessToken: string, refreshToken?: string): void;
|
|
1831
|
+
/** Remove all stored tokens (call on sign-out). */
|
|
1832
|
+
clearTokens(): void;
|
|
1833
|
+
}
|
|
1834
|
+
|
|
1726
1835
|
/**
|
|
1727
1836
|
* Fetch the authenticated user's profile.
|
|
1728
1837
|
*
|
|
@@ -1929,6 +2038,31 @@ declare const getUserWebProfiles: (token: string, userId: string | number) => Pr
|
|
|
1929
2038
|
*/
|
|
1930
2039
|
declare const getTrack: (token: string, trackId: string | number) => Promise<SoundCloudTrack>;
|
|
1931
2040
|
|
|
2041
|
+
/**
|
|
2042
|
+
* Fetch multiple tracks by their IDs in a single request.
|
|
2043
|
+
*
|
|
2044
|
+
* @param token - OAuth access token
|
|
2045
|
+
* @param ids - Array of track IDs (numeric or string URNs)
|
|
2046
|
+
* @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
|
|
2047
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
2048
|
+
* @throws {Error} When more than 200 IDs are provided
|
|
2049
|
+
*
|
|
2050
|
+
* @remarks
|
|
2051
|
+
* SoundCloud's API likely caps at ~200 IDs per request. Passing more than 200 IDs
|
|
2052
|
+
* will throw immediately without making a network request.
|
|
2053
|
+
*
|
|
2054
|
+
* @example
|
|
2055
|
+
* ```ts
|
|
2056
|
+
* import { getTracks } from 'soundcloud-api-ts';
|
|
2057
|
+
*
|
|
2058
|
+
* const tracks = await getTracks(token, [123456, 234567, 345678]);
|
|
2059
|
+
* tracks.forEach(t => console.log(t.title));
|
|
2060
|
+
* ```
|
|
2061
|
+
*
|
|
2062
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
|
|
2063
|
+
*/
|
|
2064
|
+
declare const getTracks: (token: string, ids: (string | number)[]) => Promise<SoundCloudTrack[]>;
|
|
2065
|
+
|
|
1932
2066
|
/**
|
|
1933
2067
|
* Fetch comments on a track.
|
|
1934
2068
|
*
|
|
@@ -2505,6 +2639,27 @@ declare const getMePlaylists: (token: string, limit?: number) => Promise<SoundCl
|
|
|
2505
2639
|
*/
|
|
2506
2640
|
declare const getMeTracks: (token: string, limit?: number) => Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>;
|
|
2507
2641
|
|
|
2642
|
+
/**
|
|
2643
|
+
* List the authenticated user's connected external social accounts.
|
|
2644
|
+
*
|
|
2645
|
+
* @param token - OAuth access token (user token required)
|
|
2646
|
+
* @returns Array of connection objects for linked social services
|
|
2647
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
2648
|
+
*
|
|
2649
|
+
* @remarks This endpoint may require elevated API access or app approval.
|
|
2650
|
+
*
|
|
2651
|
+
* @example
|
|
2652
|
+
* ```ts
|
|
2653
|
+
* import { getMeConnections } from 'soundcloud-api-ts';
|
|
2654
|
+
*
|
|
2655
|
+
* const connections = await getMeConnections(token);
|
|
2656
|
+
* connections.forEach(c => console.log(c.service, c.display_name));
|
|
2657
|
+
* ```
|
|
2658
|
+
*
|
|
2659
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
|
|
2660
|
+
*/
|
|
2661
|
+
declare const getMeConnections: (token: string) => Promise<SoundCloudConnection[]>;
|
|
2662
|
+
|
|
2508
2663
|
/**
|
|
2509
2664
|
* Like a playlist as the authenticated user.
|
|
2510
2665
|
*
|
|
@@ -2625,4 +2780,4 @@ declare const unrepostPlaylist: (token: string, playlistId: string | number) =>
|
|
|
2625
2780
|
*/
|
|
2626
2781
|
declare const getSoundCloudWidgetUrl: (trackId: string | number) => string;
|
|
2627
2782
|
|
|
2628
|
-
export { type CreatePlaylistParams, IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, type RawResponse, type RequestOptions, type RetryConfig, type RetryInfo, type SCRequestTelemetry, SoundCloudActivitiesResponse, type SoundCloudCache, type SoundCloudCacheEntry, 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 };
|
|
2783
|
+
export { type CreatePlaylistParams, IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, type RawResponse, type RequestOptions, type RetryConfig, type RetryInfo, type SCRequestTelemetry, SoundCloudActivitiesResponse, type SoundCloudCache, type SoundCloudCacheEntry, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudConnection, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type TokenProvider, type TokenStore, type UpdatePlaylistParams, type UpdateTrackParams, createPlaylist, createTrackComment, deletePlaylist, deleteTrack, fetchAll, followUser, generateCodeChallenge, generateCodeVerifier, getAuthorizationUrl, getClientToken, getFollowers, getFollowings, getMe, getMeActivities, getMeActivitiesOwn, getMeActivitiesTracks, getMeConnections, getMeFollowers, getMeFollowings, getMeFollowingsTracks, getMeLikesPlaylists, getMeLikesTracks, getMePlaylists, getMeTracks, getPlaylist, getPlaylistReposts, getPlaylistTracks, getRelatedTracks, getSoundCloudWidgetUrl, getTrack, getTrackComments, getTrackLikes, getTrackReposts, getTrackStreams, getTracks, 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
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './
|
|
2
|
-
export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudError, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './
|
|
1
|
+
import { S as SoundCloudTrack, a as SoundCloudPlaylist, b as SoundCloudToken, c as SoundCloudPaginatedResponse, d as SoundCloudMe, e as SoundCloudActivitiesResponse, f as SoundCloudUser, g as SoundCloudConnection, h as SoundCloudWebProfile, i as SoundCloudStreams, j as SoundCloudComment } from './index-DX6Anc1-.js';
|
|
2
|
+
export { k as SoundCloudActivity, l as SoundCloudCommentUser, m as SoundCloudError, n as SoundCloudQuota, o as SoundCloudSubscription, p as SoundCloudSubscriptionProduct } from './index-DX6Anc1-.js';
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
5
|
* Options for making a request to the SoundCloud API via {@link scFetch}.
|
|
@@ -855,6 +855,24 @@ declare namespace SoundCloudClient {
|
|
|
855
855
|
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_tracks
|
|
856
856
|
*/
|
|
857
857
|
getTracks(limit?: number, options?: TokenOption): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>;
|
|
858
|
+
/**
|
|
859
|
+
* List the authenticated user's connected external social accounts.
|
|
860
|
+
*
|
|
861
|
+
* @param options - Optional token override
|
|
862
|
+
* @returns Array of connection objects for linked social services (Twitter, Facebook, etc.)
|
|
863
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
864
|
+
*
|
|
865
|
+
* @remarks This endpoint may require elevated API access or app approval.
|
|
866
|
+
*
|
|
867
|
+
* @example
|
|
868
|
+
* ```ts
|
|
869
|
+
* const connections = await sc.me.getConnections();
|
|
870
|
+
* connections.forEach(c => console.log(c.service, c.display_name));
|
|
871
|
+
* ```
|
|
872
|
+
*
|
|
873
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
|
|
874
|
+
*/
|
|
875
|
+
getConnections(options?: TokenOption): Promise<SoundCloudConnection[]>;
|
|
858
876
|
}
|
|
859
877
|
/**
|
|
860
878
|
* User profile namespace — fetch public user data.
|
|
@@ -1001,6 +1019,28 @@ declare namespace SoundCloudClient {
|
|
|
1001
1019
|
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id_
|
|
1002
1020
|
*/
|
|
1003
1021
|
getTrack(trackId: string | number, options?: TokenOption): Promise<SoundCloudTrack>;
|
|
1022
|
+
/**
|
|
1023
|
+
* Fetch multiple tracks by their IDs in a single request.
|
|
1024
|
+
*
|
|
1025
|
+
* @param ids - Array of track IDs (numeric or string URNs)
|
|
1026
|
+
* @param options - Optional token override
|
|
1027
|
+
* @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
|
|
1028
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
1029
|
+
* @throws {Error} When more than 200 IDs are provided
|
|
1030
|
+
*
|
|
1031
|
+
* @remarks
|
|
1032
|
+
* SoundCloud's API likely caps at ~200 IDs per request. Passing more than 200 IDs
|
|
1033
|
+
* will throw immediately without making a network request.
|
|
1034
|
+
*
|
|
1035
|
+
* @example
|
|
1036
|
+
* ```ts
|
|
1037
|
+
* const tracks = await sc.tracks.getTracks([123456, 234567, 345678]);
|
|
1038
|
+
* tracks.forEach(t => console.log(t.title));
|
|
1039
|
+
* ```
|
|
1040
|
+
*
|
|
1041
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
|
|
1042
|
+
*/
|
|
1043
|
+
getTracks(ids: (string | number)[], options?: TokenOption): Promise<SoundCloudTrack[]>;
|
|
1004
1044
|
/**
|
|
1005
1045
|
* Get stream URLs for a track.
|
|
1006
1046
|
*
|
|
@@ -1723,6 +1763,75 @@ declare function generateCodeVerifier(): string;
|
|
|
1723
1763
|
*/
|
|
1724
1764
|
declare function generateCodeChallenge(verifier: string): Promise<string>;
|
|
1725
1765
|
|
|
1766
|
+
/**
|
|
1767
|
+
* Contract for a pluggable token provider that manages OAuth token lifecycle.
|
|
1768
|
+
*
|
|
1769
|
+
* Implement this interface to integrate soundcloud-api-ts with your
|
|
1770
|
+
* framework's session management, e.g. NextAuth, Clerk, Redis, or a simple
|
|
1771
|
+
* in-memory store.
|
|
1772
|
+
*
|
|
1773
|
+
* @example
|
|
1774
|
+
* ```ts
|
|
1775
|
+
* class InMemoryTokenProvider implements TokenProvider {
|
|
1776
|
+
* private _accessToken?: string;
|
|
1777
|
+
* private _refreshToken?: string;
|
|
1778
|
+
*
|
|
1779
|
+
* getAccessToken() { return this._accessToken; }
|
|
1780
|
+
* setTokens(access: string, refresh?: string) {
|
|
1781
|
+
* this._accessToken = access;
|
|
1782
|
+
* this._refreshToken = refresh;
|
|
1783
|
+
* }
|
|
1784
|
+
* async refreshIfNeeded(client: SoundCloudClient) {
|
|
1785
|
+
* if (!this._refreshToken) throw new Error('No refresh token');
|
|
1786
|
+
* const token = await client.auth.refreshUserToken(this._refreshToken);
|
|
1787
|
+
* this.setTokens(token.access_token, token.refresh_token);
|
|
1788
|
+
* return token.access_token;
|
|
1789
|
+
* }
|
|
1790
|
+
* }
|
|
1791
|
+
* ```
|
|
1792
|
+
*
|
|
1793
|
+
* @see docs/auth-guide.md
|
|
1794
|
+
*/
|
|
1795
|
+
interface TokenProvider {
|
|
1796
|
+
/** Returns the current access token, or undefined if none is stored. */
|
|
1797
|
+
getAccessToken(): string | undefined | Promise<string | undefined>;
|
|
1798
|
+
/** Persist new tokens (called after a successful token grant or refresh). */
|
|
1799
|
+
setTokens(accessToken: string, refreshToken?: string): void | Promise<void>;
|
|
1800
|
+
/**
|
|
1801
|
+
* Ensure a valid access token is available, refreshing if necessary.
|
|
1802
|
+
* Called automatically when a request returns 401 Unauthorized.
|
|
1803
|
+
*/
|
|
1804
|
+
refreshIfNeeded(client: SoundCloudClient): Promise<string> | string;
|
|
1805
|
+
}
|
|
1806
|
+
/**
|
|
1807
|
+
* Minimal synchronous key–value store for OAuth tokens.
|
|
1808
|
+
*
|
|
1809
|
+
* Useful for implementing a simple in-memory or cookie-backed token store
|
|
1810
|
+
* without the full async lifecycle of {@link TokenProvider}.
|
|
1811
|
+
*
|
|
1812
|
+
* @example
|
|
1813
|
+
* ```ts
|
|
1814
|
+
* class CookieTokenStore implements TokenStore {
|
|
1815
|
+
* getAccessToken() { return getCookie('sc_access_token') ?? undefined; }
|
|
1816
|
+
* getRefreshToken() { return getCookie('sc_refresh_token') ?? undefined; }
|
|
1817
|
+
* setTokens(a, r) { setCookie('sc_access_token', a); if (r) setCookie('sc_refresh_token', r); }
|
|
1818
|
+
* clearTokens() { deleteCookie('sc_access_token'); deleteCookie('sc_refresh_token'); }
|
|
1819
|
+
* }
|
|
1820
|
+
* ```
|
|
1821
|
+
*
|
|
1822
|
+
* @see docs/auth-guide.md
|
|
1823
|
+
*/
|
|
1824
|
+
interface TokenStore {
|
|
1825
|
+
/** Returns the stored access token, or undefined if none. */
|
|
1826
|
+
getAccessToken(): string | undefined;
|
|
1827
|
+
/** Returns the stored refresh token, or undefined if none. */
|
|
1828
|
+
getRefreshToken(): string | undefined;
|
|
1829
|
+
/** Persist new tokens. */
|
|
1830
|
+
setTokens(accessToken: string, refreshToken?: string): void;
|
|
1831
|
+
/** Remove all stored tokens (call on sign-out). */
|
|
1832
|
+
clearTokens(): void;
|
|
1833
|
+
}
|
|
1834
|
+
|
|
1726
1835
|
/**
|
|
1727
1836
|
* Fetch the authenticated user's profile.
|
|
1728
1837
|
*
|
|
@@ -1929,6 +2038,31 @@ declare const getUserWebProfiles: (token: string, userId: string | number) => Pr
|
|
|
1929
2038
|
*/
|
|
1930
2039
|
declare const getTrack: (token: string, trackId: string | number) => Promise<SoundCloudTrack>;
|
|
1931
2040
|
|
|
2041
|
+
/**
|
|
2042
|
+
* Fetch multiple tracks by their IDs in a single request.
|
|
2043
|
+
*
|
|
2044
|
+
* @param token - OAuth access token
|
|
2045
|
+
* @param ids - Array of track IDs (numeric or string URNs)
|
|
2046
|
+
* @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
|
|
2047
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
2048
|
+
* @throws {Error} When more than 200 IDs are provided
|
|
2049
|
+
*
|
|
2050
|
+
* @remarks
|
|
2051
|
+
* SoundCloud's API likely caps at ~200 IDs per request. Passing more than 200 IDs
|
|
2052
|
+
* will throw immediately without making a network request.
|
|
2053
|
+
*
|
|
2054
|
+
* @example
|
|
2055
|
+
* ```ts
|
|
2056
|
+
* import { getTracks } from 'soundcloud-api-ts';
|
|
2057
|
+
*
|
|
2058
|
+
* const tracks = await getTracks(token, [123456, 234567, 345678]);
|
|
2059
|
+
* tracks.forEach(t => console.log(t.title));
|
|
2060
|
+
* ```
|
|
2061
|
+
*
|
|
2062
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
|
|
2063
|
+
*/
|
|
2064
|
+
declare const getTracks: (token: string, ids: (string | number)[]) => Promise<SoundCloudTrack[]>;
|
|
2065
|
+
|
|
1932
2066
|
/**
|
|
1933
2067
|
* Fetch comments on a track.
|
|
1934
2068
|
*
|
|
@@ -2505,6 +2639,27 @@ declare const getMePlaylists: (token: string, limit?: number) => Promise<SoundCl
|
|
|
2505
2639
|
*/
|
|
2506
2640
|
declare const getMeTracks: (token: string, limit?: number) => Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>;
|
|
2507
2641
|
|
|
2642
|
+
/**
|
|
2643
|
+
* List the authenticated user's connected external social accounts.
|
|
2644
|
+
*
|
|
2645
|
+
* @param token - OAuth access token (user token required)
|
|
2646
|
+
* @returns Array of connection objects for linked social services
|
|
2647
|
+
* @throws {SoundCloudError} When the API returns an error
|
|
2648
|
+
*
|
|
2649
|
+
* @remarks This endpoint may require elevated API access or app approval.
|
|
2650
|
+
*
|
|
2651
|
+
* @example
|
|
2652
|
+
* ```ts
|
|
2653
|
+
* import { getMeConnections } from 'soundcloud-api-ts';
|
|
2654
|
+
*
|
|
2655
|
+
* const connections = await getMeConnections(token);
|
|
2656
|
+
* connections.forEach(c => console.log(c.service, c.display_name));
|
|
2657
|
+
* ```
|
|
2658
|
+
*
|
|
2659
|
+
* @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
|
|
2660
|
+
*/
|
|
2661
|
+
declare const getMeConnections: (token: string) => Promise<SoundCloudConnection[]>;
|
|
2662
|
+
|
|
2508
2663
|
/**
|
|
2509
2664
|
* Like a playlist as the authenticated user.
|
|
2510
2665
|
*
|
|
@@ -2625,4 +2780,4 @@ declare const unrepostPlaylist: (token: string, playlistId: string | number) =>
|
|
|
2625
2780
|
*/
|
|
2626
2781
|
declare const getSoundCloudWidgetUrl: (trackId: string | number) => string;
|
|
2627
2782
|
|
|
2628
|
-
export { type CreatePlaylistParams, IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, type RawResponse, type RequestOptions, type RetryConfig, type RetryInfo, type SCRequestTelemetry, SoundCloudActivitiesResponse, type SoundCloudCache, type SoundCloudCacheEntry, 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 };
|
|
2783
|
+
export { type CreatePlaylistParams, IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, type RawResponse, type RequestOptions, type RetryConfig, type RetryInfo, type SCRequestTelemetry, SoundCloudActivitiesResponse, type SoundCloudCache, type SoundCloudCacheEntry, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudConnection, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type TokenProvider, type TokenStore, type UpdatePlaylistParams, type UpdateTrackParams, createPlaylist, createTrackComment, deletePlaylist, deleteTrack, fetchAll, followUser, generateCodeChallenge, generateCodeVerifier, getAuthorizationUrl, getClientToken, getFollowers, getFollowings, getMe, getMeActivities, getMeActivitiesOwn, getMeActivitiesTracks, getMeConnections, getMeFollowers, getMeFollowings, getMeFollowingsTracks, getMeLikesPlaylists, getMeLikesTracks, getMePlaylists, getMeTracks, getPlaylist, getPlaylistReposts, getPlaylistTracks, getRelatedTracks, getSoundCloudWidgetUrl, getTrack, getTrackComments, getTrackLikes, getTrackReposts, getTrackStreams, getTracks, 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 };
|