soundcloud-api-ts 1.11.3 → 1.13.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { SoundCloudTrack, SoundCloudPlaylist, SoundCloudToken, SoundCloudPaginatedResponse, SoundCloudMe, SoundCloudActivitiesResponse, SoundCloudUser, SoundCloudWebProfile, SoundCloudStreams, SoundCloudComment } from './types/index.mjs';
-export { SoundCloudActivity, SoundCloudCommentUser, SoundCloudError, SoundCloudQuota, SoundCloudSubscription, SoundCloudSubscriptionProduct } from './types/index.mjs';
+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';
+export { k as SoundCloudActivity, l as SoundCloudCommentUser, m as SoundCloudError, n as SoundCloudQuota, o as SoundCloudSubscription, p as SoundCloudSubscriptionProduct } from './index-DX6Anc1-.mjs';
 
 /**
  * Options for making a request to the SoundCloud API via {@link scFetch}.
@@ -35,6 +35,21 @@ interface SCRequestTelemetry {
     /** Error message if the request ultimately failed */
     error?: string;
 }
+/**
+ * Information passed to the `onRetry` callback on each retry attempt.
+ */
+interface RetryInfo {
+    /** Which retry attempt this is (1-based) */
+    attempt: number;
+    /** Delay in milliseconds before this retry fires */
+    delayMs: number;
+    /** Human-readable reason (e.g. "429 Too Many Requests") */
+    reason: string;
+    /** HTTP status that triggered the retry, if applicable */
+    status?: number;
+    /** The URL that was requested */
+    url: string;
+}
 /**
  * Configuration for automatic retry with exponential backoff on transient errors.
  */
@@ -45,6 +60,8 @@ interface RetryConfig {
     retryBaseDelay: number;
     /** Optional callback for debug logging of retry attempts */
     onDebug?: (message: string) => void;
+    /** Optional callback fired before each retry with structured retry info */
+    onRetry?: (info: RetryInfo) => void;
 }
 /**
  * Context for automatic token refresh when a request returns 401 Unauthorized.
@@ -114,6 +131,103 @@ declare function scFetch<T>(options: RequestOptions, refreshCtx?: AutoRefreshCon
  */
 declare function scFetchUrl<T>(url: string, token?: string, retryConfig?: RetryConfig, onRequest?: (telemetry: SCRequestTelemetry) => void): Promise<T>;
 
+/**
+ * Raw response from the SoundCloud API, including status code and headers.
+ */
+type RawResponse<T = unknown> = {
+    /** Parsed response body */
+    data: T;
+    /** HTTP status code */
+    status: number;
+    /** Response headers as a plain object */
+    headers: Record<string, string>;
+};
+/**
+ * Low-level HTTP client that returns raw responses without throwing on non-2xx status codes.
+ * Useful when you need access to status codes, headers, or want to handle errors manually.
+ *
+ * @example
+ * ```ts
+ * const raw = sc.raw;
+ * const res = await raw.get('/tracks/123456');
+ * console.log(res.status, res.headers, res.data);
+ * ```
+ */
+declare class RawClient {
+    private baseUrl;
+    private getToken;
+    private fetchFn;
+    constructor(baseUrl: string, getToken: () => string | undefined, fetchFn: typeof fetch);
+    /**
+     * Make a raw HTTP request. Path template placeholders like `{id}` are substituted
+     * from matching keys in `query` before the remaining query params are appended to
+     * the URL as search parameters.
+     */
+    request<T = unknown>({ method, path, query, body, token, }: {
+        method: string;
+        path: string;
+        query?: Record<string, string | number | boolean | undefined>;
+        body?: unknown;
+        token?: string;
+    }): Promise<RawResponse<T>>;
+    /** GET shorthand */
+    get<T = unknown>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<RawResponse<T>>;
+    /** POST shorthand */
+    post<T = unknown>(path: string, body?: unknown): Promise<RawResponse<T>>;
+    /** PUT shorthand */
+    put<T = unknown>(path: string, body?: unknown): Promise<RawResponse<T>>;
+    /** DELETE shorthand */
+    delete<T = unknown>(path: string): Promise<RawResponse<T>>;
+}
+
+/**
+ * A cache entry with an expiration timestamp.
+ */
+interface SoundCloudCacheEntry<T> {
+    /** The cached value */
+    value: T;
+    /** Unix timestamp (ms) when this entry expires */
+    expiresAt: number;
+}
+/**
+ * Cache interface for SoundCloud API responses.
+ *
+ * Implement this interface to plug in any caching backend (in-memory, Redis, etc.).
+ * Pass an instance as `cache` in {@link SoundCloudClientConfig} to enable caching.
+ *
+ * @example
+ * ```ts
+ * // Simple in-memory implementation
+ * class SimpleCache implements SoundCloudCache {
+ *   private store = new Map<string, SoundCloudCacheEntry<unknown>>();
+ *
+ *   get<T>(key: string): T | undefined {
+ *     const entry = this.store.get(key) as SoundCloudCacheEntry<T> | undefined;
+ *     if (!entry || Date.now() > entry.expiresAt) return undefined;
+ *     return entry.value;
+ *   }
+ *
+ *   set<T>(key: string, value: T, { ttlMs }: { ttlMs: number }): void {
+ *     this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
+ *   }
+ *
+ *   delete(key: string): void {
+ *     this.store.delete(key);
+ *   }
+ * }
+ * ```
+ */
+interface SoundCloudCache {
+    /** Retrieve a cached value by key, or `undefined` if missing or expired */
+    get<T>(key: string): Promise<T | undefined> | T | undefined;
+    /** Store a value with a TTL in milliseconds */
+    set<T>(key: string, value: T, options: {
+        ttlMs: number;
+    }): Promise<void> | void;
+    /** Remove a cached entry */
+    delete(key: string): Promise<void> | void;
+}
+
 /**
  * Parameters for updating a track's metadata via {@link updateTrack}.
  */
@@ -321,6 +435,16 @@ interface SoundCloudClientConfig {
     onDebug?: (message: string) => void;
     /** Called after every API request with structured telemetry (timing, status, retries) */
     onRequest?: (telemetry: SCRequestTelemetry) => void;
+    /** Custom fetch implementation (defaults to `globalThis.fetch`) */
+    fetch?: typeof globalThis.fetch;
+    /** Deduplicate concurrent identical requests (default: true) */
+    dedupe?: boolean;
+    /** Optional cache backend for API responses */
+    cache?: SoundCloudCache;
+    /** Default TTL in milliseconds for cached responses (default: 60000) */
+    cacheTtlMs?: number;
+    /** Called before each retry attempt with structured retry info */
+    onRetry?: (info: RetryInfo) => void;
 }
 /**
  * Optional token override that can be passed as the last parameter to client methods.
@@ -386,6 +510,8 @@ declare class SoundCloudClient {
     likes: SoundCloudClient.Likes;
     /** Repost/unrepost actions (/reposts) */
     reposts: SoundCloudClient.Reposts;
+    /** Low-level raw HTTP client — returns status/headers without throwing on non-2xx */
+    raw: RawClient;
     /**
      * Creates a new SoundCloudClient instance.
      *
@@ -729,6 +855,24 @@ declare namespace SoundCloudClient {
          * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_tracks
          */
         getTracks(limit?: number, options?: TokenOption): Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>;
+        /**
+         * List the authenticated user's connected external social accounts.
+         *
+         * @param options - Optional token override
+         * @returns Array of connection objects for linked social services (Twitter, Facebook, etc.)
+         * @throws {SoundCloudError} When the API returns an error
+         *
+         * @remarks This endpoint may require elevated API access or app approval.
+         *
+         * @example
+         * ```ts
+         * const connections = await sc.me.getConnections();
+         * connections.forEach(c => console.log(c.service, c.display_name));
+         * ```
+         *
+         * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
+         */
+        getConnections(options?: TokenOption): Promise<SoundCloudConnection[]>;
     }
     /**
      * User profile namespace — fetch public user data.
@@ -875,6 +1019,23 @@ declare namespace SoundCloudClient {
          * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks__track_id_
          */
         getTrack(trackId: string | number, options?: TokenOption): Promise<SoundCloudTrack>;
+        /**
+         * Fetch multiple tracks by their IDs in a single request.
+         *
+         * @param ids - Array of track IDs (numeric or string URNs)
+         * @param options - Optional token override
+         * @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
+         * @throws {SoundCloudError} When the API returns an error
+         *
+         * @example
+         * ```ts
+         * const tracks = await sc.tracks.getTracks([123456, 234567, 345678]);
+         * tracks.forEach(t => console.log(t.title));
+         * ```
+         *
+         * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
+         */
+        getTracks(ids: (string | number)[], options?: TokenOption): Promise<SoundCloudTrack[]>;
         /**
          * Get stream URLs for a track.
          *
@@ -1311,6 +1472,42 @@ declare namespace SoundCloudClient {
     }
 }
 
+/**
+ * Deduplicates concurrent in-flight requests with the same key.
+ *
+ * When multiple callers request the same resource simultaneously,
+ * only one underlying promise is created — all callers share the result.
+ * The key is cleaned up automatically once the promise settles.
+ *
+ * @example
+ * ```ts
+ * const deduper = new InFlightDeduper();
+ *
+ * // Both calls share a single fetch:
+ * const [a, b] = await Promise.all([
+ *   deduper.add('track:123', () => fetchTrack(123)),
+ *   deduper.add('track:123', () => fetchTrack(123)),
+ * ]);
+ * // a === b (same resolved value)
+ * ```
+ */
+declare class InFlightDeduper {
+    private inFlight;
+    /**
+     * Return an existing in-flight promise for `key`, or start a new one via `factory`.
+     * The entry is removed from the map once the promise settles (resolve or reject).
+     */
+    add<T>(key: string, factory: () => Promise<T>): Promise<T>;
+    /** Number of currently in-flight requests */
+    get size(): number;
+}
+
+/**
+ * List of operation IDs currently implemented by soundcloud-api-ts.
+ * Used for OpenAPI coverage reporting.
+ */
+declare const IMPLEMENTED_OPERATIONS: string[];
+
 /**
  * Async generator that automatically follows `next_href` pagination,
  * yielding each page's `collection` array.
@@ -1561,6 +1758,75 @@ declare function generateCodeVerifier(): string;
  */
 declare function generateCodeChallenge(verifier: string): Promise<string>;
 
+/**
+ * Contract for a pluggable token provider that manages OAuth token lifecycle.
+ *
+ * Implement this interface to integrate soundcloud-api-ts with your
+ * framework's session management, e.g. NextAuth, Clerk, Redis, or a simple
+ * in-memory store.
+ *
+ * @example
+ * ```ts
+ * class InMemoryTokenProvider implements TokenProvider {
+ *   private _accessToken?: string;
+ *   private _refreshToken?: string;
+ *
+ *   getAccessToken() { return this._accessToken; }
+ *   setTokens(access: string, refresh?: string) {
+ *     this._accessToken = access;
+ *     this._refreshToken = refresh;
+ *   }
+ *   async refreshIfNeeded(client: SoundCloudClient) {
+ *     if (!this._refreshToken) throw new Error('No refresh token');
+ *     const token = await client.auth.refreshUserToken(this._refreshToken);
+ *     this.setTokens(token.access_token, token.refresh_token);
+ *     return token.access_token;
+ *   }
+ * }
+ * ```
+ *
+ * @see docs/auth-guide.md
+ */
+interface TokenProvider {
+    /** Returns the current access token, or undefined if none is stored. */
+    getAccessToken(): string | undefined | Promise<string | undefined>;
+    /** Persist new tokens (called after a successful token grant or refresh). */
+    setTokens(accessToken: string, refreshToken?: string): void | Promise<void>;
+    /**
+     * Ensure a valid access token is available, refreshing if necessary.
+     * Called automatically when a request returns 401 Unauthorized.
+     */
+    refreshIfNeeded(client: SoundCloudClient): Promise<string> | string;
+}
+/**
+ * Minimal synchronous key–value store for OAuth tokens.
+ *
+ * Useful for implementing a simple in-memory or cookie-backed token store
+ * without the full async lifecycle of {@link TokenProvider}.
+ *
+ * @example
+ * ```ts
+ * class CookieTokenStore implements TokenStore {
+ *   getAccessToken()  { return getCookie('sc_access_token') ?? undefined; }
+ *   getRefreshToken() { return getCookie('sc_refresh_token') ?? undefined; }
+ *   setTokens(a, r)   { setCookie('sc_access_token', a); if (r) setCookie('sc_refresh_token', r); }
+ *   clearTokens()     { deleteCookie('sc_access_token'); deleteCookie('sc_refresh_token'); }
+ * }
+ * ```
+ *
+ * @see docs/auth-guide.md
+ */
+interface TokenStore {
+    /** Returns the stored access token, or undefined if none. */
+    getAccessToken(): string | undefined;
+    /** Returns the stored refresh token, or undefined if none. */
+    getRefreshToken(): string | undefined;
+    /** Persist new tokens. */
+    setTokens(accessToken: string, refreshToken?: string): void;
+    /** Remove all stored tokens (call on sign-out). */
+    clearTokens(): void;
+}
+
 /**
  * Fetch the authenticated user's profile.
  *
@@ -1767,6 +2033,26 @@ declare const getUserWebProfiles: (token: string, userId: string | number) => Pr
  */
 declare const getTrack: (token: string, trackId: string | number) => Promise<SoundCloudTrack>;
 
+/**
+ * Fetch multiple tracks by their IDs in a single request.
+ *
+ * @param token - OAuth access token
+ * @param ids - Array of track IDs (numeric or string URNs)
+ * @returns Array of track objects (may be shorter than `ids` if some tracks are unavailable)
+ * @throws {SoundCloudError} When the API returns an error
+ *
+ * @example
+ * ```ts
+ * import { getTracks } from 'soundcloud-api-ts';
+ *
+ * const tracks = await getTracks(token, [123456, 234567, 345678]);
+ * tracks.forEach(t => console.log(t.title));
+ * ```
+ *
+ * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/tracks/get_tracks
+ */
+declare const getTracks: (token: string, ids: (string | number)[]) => Promise<SoundCloudTrack[]>;
+
 /**
  * Fetch comments on a track.
  *
@@ -2343,6 +2629,27 @@ declare const getMePlaylists: (token: string, limit?: number) => Promise<SoundCl
  */
 declare const getMeTracks: (token: string, limit?: number) => Promise<SoundCloudPaginatedResponse<SoundCloudTrack>>;
 
+/**
+ * List the authenticated user's connected external social accounts.
+ *
+ * @param token - OAuth access token (user token required)
+ * @returns Array of connection objects for linked social services
+ * @throws {SoundCloudError} When the API returns an error
+ *
+ * @remarks This endpoint may require elevated API access or app approval.
+ *
+ * @example
+ * ```ts
+ * import { getMeConnections } from 'soundcloud-api-ts';
+ *
+ * const connections = await getMeConnections(token);
+ * connections.forEach(c => console.log(c.service, c.display_name));
+ * ```
+ *
+ * @see https://developers.soundcloud.com/docs/api/explorer/open-api#/me/get_me_connections
+ */
+declare const getMeConnections: (token: string) => Promise<SoundCloudConnection[]>;
+
 /**
  * Like a playlist as the authenticated user.
  *
@@ -2463,4 +2770,4 @@ declare const unrepostPlaylist: (token: string, playlistId: string | number) =>
  */
 declare const getSoundCloudWidgetUrl: (trackId: string | number) => string;
 
-export { type CreatePlaylistParams, type RequestOptions, type RetryConfig, type SCRequestTelemetry, SoundCloudActivitiesResponse, SoundCloudClient, type SoundCloudClientConfig, SoundCloudComment, SoundCloudMe, SoundCloudPaginatedResponse, SoundCloudPlaylist, SoundCloudStreams, SoundCloudToken, SoundCloudTrack, SoundCloudUser, SoundCloudWebProfile, type TokenOption, type UpdatePlaylistParams, type UpdateTrackParams, createPlaylist, createTrackComment, deletePlaylist, deleteTrack, fetchAll, followUser, generateCodeChallenge, generateCodeVerifier, getAuthorizationUrl, getClientToken, getFollowers, getFollowings, getMe, getMeActivities, getMeActivitiesOwn, getMeActivitiesTracks, getMeFollowers, getMeFollowings, getMeFollowingsTracks, getMeLikesPlaylists, getMeLikesTracks, getMePlaylists, getMeTracks, getPlaylist, getPlaylistReposts, getPlaylistTracks, getRelatedTracks, getSoundCloudWidgetUrl, getTrack, getTrackComments, getTrackLikes, getTrackReposts, getTrackStreams, getUser, getUserLikesPlaylists, getUserLikesTracks, getUserPlaylists, getUserToken, getUserTracks, getUserWebProfiles, likePlaylist, likeTrack, paginate, paginateItems, refreshUserToken, repostPlaylist, repostTrack, resolveUrl, scFetch, scFetchUrl, searchPlaylists, searchTracks, searchUsers, signOut, unfollowUser, unlikePlaylist, unlikeTrack, unrepostPlaylist, unrepostTrack, updatePlaylist, updateTrack };
+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 };