soundcloud-api-ts 1.11.1 → 1.12.0

package/dist/index.d.mts

@@ -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.
      *
@@ -1311,6 +1437,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.
@@ -2463,4 +2625,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, 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 };

package/dist/index.d.ts

@@ -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.
      *
@@ -1311,6 +1437,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.
@@ -2463,4 +2625,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, 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 };