soundcloud-api-ts 1.11.3 → 1.13.0

package/AGENTS.md

@@ -123,9 +123,14 @@ try {
 
 1. **Token required for ALL requests** — even public endpoints like `getTrack` need at least a client credentials token. Call `setToken()` first.
 2. **User token vs client token** — write operations (like, repost, comment, follow, create/update/delete) require a user token obtained via the authorization code flow. A client credentials token won't work.
-3. **Rate limits exist** — SoundCloud returns 429 when rate limited. The client has built-in retry with exponential backoff (configurable via `maxRetries` and `retryBaseDelay`).
+3. **Rate limits exist** — SoundCloud returns 429 when rate limited. The client has built-in retry with exponential backoff (configurable via `maxRetries` and `retryBaseDelay`). `Retry-After` header is honored (capped 60s).
 4. **Auto token refresh** — pass `onTokenRefresh` in the config to automatically refresh expired tokens on 401.
 5. **Request telemetry** — pass `onRequest` in the config to receive `SCRequestTelemetry` after every request (method, path, duration, status, retries, error). Fires on all paths including pagination and retries.
+6. **sc.raw** — `sc.raw.get('/tracks/{id}', { id: 123456 })` calls any endpoint without a typed wrapper. Returns `RawResponse<T>` with `{ data, status, headers }`. Does NOT throw on non-2xx — check `res.status` yourself. Good for endpoints not yet wrapped.
+7. **Fetch injection** — pass `fetch` and `AbortController` in the constructor for Bun/Deno/Cloudflare Workers portability. No Node-only APIs used at runtime.
+8. **Deduplication** — concurrent identical GETs share a single in-flight promise (`dedupe: true` by default). Prevents redundant fetches in SSR or concurrent component trees.
+9. **Cache** — pass a `SoundCloudCache` implementation in the constructor to cache GET responses. Base package defines the interface only; bring your own backend. `cacheTtlMs` defaults to 60000ms.
+10. **Retry hook** — pass `onRetry` to receive `RetryInfo` on each retry: `{ attempt, delayMs, reason, status?, url }`.
 6. **No env vars** — the package reads no environment variables. Pass `clientId`, `clientSecret`, and `redirectUri` directly to the constructor.
 7. **IDs can be numbers or strings** — all ID parameters accept `string | number`.
 8. **Search pagination** — search uses zero-based `pageNumber` (10 results per page), not cursor-based pagination.

package/README.md

@@ -11,28 +11,26 @@
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)]()
 [![docs](https://img.shields.io/badge/docs-TypeDoc-blue.svg)](https://twin-paws.github.io/soundcloud-api-ts/)
 [![GitHub stars](https://img.shields.io/github/stars/twin-paws/soundcloud-api-ts)](https://github.com/twin-paws/soundcloud-api-ts)
+[![OpenAPI Coverage](https://img.shields.io/badge/OpenAPI%20coverage-tracked-blue)](tools/coverage-baseline.json)
 
-soundcloud-api-ts is a TypeScript-first SoundCloud API client for accessing tracks, users, playlists, and search endpoints using modern async/await APIs.
-
-Zero dependencies, native `fetch`, built-in OAuth 2.1 + PKCE, automatic retry, and an interactive CLI.
-
-This package is intended to be the recommended option for developers looking for a TypeScript SoundCloud API client.
+The TypeScript SoundCloud API client built on the official API. Zero runtime dependencies, native `fetch`, OAuth 2.1 + PKCE, production-grade retry and deduplication, pluggable cache, raw escape hatch, and an interactive CLI.
 
 ## Why This Package?
 
-Unlike legacy JavaScript SoundCloud SDKs and community wrappers that require separate `@types` packages or scrape undocumented internal APIs, soundcloud-api-ts is:
+Most TypeScript SoundCloud clients fall into one of two categories: unmaintained wrappers that predate OAuth 2.1, or scrapers that harvest undocumented `api-v2` client IDs from browser dev tools and break whenever SoundCloud ships a frontend update. soundcloud-api-ts is neither.
 
-- **TypeScript-first** — full types ship with the package, no community typings required
-- **An API client, not a scraper** — uses SoundCloud's official documented API with registered app credentials
-- **Modern async/await interface** — designed for modern TypeScript projects
-- **Zero dependencies** — uses native `fetch`, nothing to install
-- **Token management built-in** — `setToken()`, auto-refresh on 401
-- **PKCE support** for public clients and SPAs
-- **Interactive CLI** — explore the API from your terminal with `sc-cli`
-- **Clean API** — `sc.tracks.getTrack(id)` not `getTrack(token, id)`
-- **Automatic retry** — exponential backoff on 429 and 5xx
-- **Dual ESM/CJS output** — works everywhere
-- **LLM-friendly** — includes `llms.txt` and `AGENTS.md` for AI coding agents
+It is built on SoundCloud's **official documented API** with registered app credentials, OAuth 2.1 + PKCE, and a production-grade HTTP layer — all with zero runtime dependencies.
+
+- **Official API only** — `api.soundcloud.com` + `secure.soundcloud.com` OAuth. No `api-v2` scraping, no harvested client IDs, no terms violations.
+- **TypeScript-first** — full types ship in the package. No `@types/*` installs, no casting to `any`.
+- **Zero dependencies** — native `fetch`, nothing in `node_modules` at runtime. 4.5 KB min+gz.
+- **Production HTTP layer** — exponential backoff on 429/5xx, `Retry-After` header respected, in-flight GET deduplication, pluggable cache interface, `onRetry` hook.
+- **Runtime portable** — inject your own `fetch` and `AbortController` for Cloudflare Workers, Bun, Deno, and Edge runtimes.
+- **Raw escape hatch** — `sc.raw.get('/any/endpoint/{id}', { id })` calls anything in the spec, not just wrapped endpoints. Never blocked by a missing wrapper.
+- **Full auth support** — client credentials flow for server-to-server, authorization code + PKCE for user-context operations, auto token refresh on 401.
+- **Pagination built-in** — async iterators and `fetchAll` helpers across all paginated endpoints.
+- **Interactive CLI** — `sc-cli tracks <id>`, `sc-cli search <query>`, `sc-cli me` from your terminal.
+- **LLM-friendly** — ships `llms.txt`, `llms-full.txt`, and `AGENTS.md` for AI coding agents.
 
 ## Comparison
 
@@ -40,22 +38,23 @@ Unlike legacy JavaScript SoundCloud SDKs and community wrappers that require sep
 | --- | --- | --- | --- |
 | TypeScript | ✅ Native | ✅ | ✅ |
 | Dependencies | **0** | 1 | 3 (lodash, cookie, undici) |
-| Bundle size (min+gz) | **4.5 KB** | ❌ unbundlable (native binary) | 191 KB |
-| Auth method | **Official OAuth 2.1** | ⚠️ Scrape client ID from browser | ⚠️ Scrape client ID from browser |
+| Bundle size (min+gz) | **4.5 KB** | ❌ unbundlable | 191 KB |
+| Auth method | **Official OAuth 2.1** | ⚠️ Scrapes client ID | ⚠️ Scrapes client ID |
 | PKCE support | ✅ | ❌ | ❌ |
-| Auto token refresh | ✅ on 401 | ❌ | ❌ |
-| Auto retry (429/5xx) | ✅ exponential backoff | ❌ | ❌ |
+| Auto token refresh | ✅ | ❌ | ❌ |
+| Auto retry (429/5xx) | ✅ + Retry-After | ❌ | ❌ |
+| In-flight deduplication | ✅ | ❌ | ❌ |
+| Pluggable cache interface | ✅ | ❌ | ❌ |
+| Fetch injection (Workers/Bun/Deno) | ✅ | ❌ | ❌ |
+| Raw escape hatch | ✅ `sc.raw` | ❌ | ❌ |
 | CLI tool | ✅ `sc-cli` | ❌ | ❌ |
 | Pagination helpers | ✅ async iterators | ❌ | ✅ |
 | Typed errors | ✅ `SoundCloudError` | ❌ | ❌ |
 | Test coverage | **100%** | — | — |
 | API docs site | ✅ [TypeDoc](https://twin-paws.github.io/soundcloud-api-ts/) | ✅ | ❌ |
 | LLM/AI-friendly | ✅ llms.txt + AGENTS.md | ❌ | ❌ |
-| Maintained | ✅ 2026 | ✅ 2025 | ✅ 2026 |
 
-> **Why does auth method matter?** `soundcloud.ts` and `soundcloud-fetch` use SoundCloud's undocumented internal `api-v2` and require you to scrape your client ID from browser dev tools. This can break anytime SoundCloud changes their frontend, and may violate the [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use) which state *"you must register your app"* and *"any attempt to circumvent this and obtain a new client ID and Security Code is strictly prohibited."*
->
-> `soundcloud-api-ts` uses the **official documented API** (`api.soundcloud.com`) with registered app credentials, OAuth 2.1 via `secure.soundcloud.com` as specified by SoundCloud, PKCE for public clients, and automatic token refresh.
+> **Why does auth method matter?** `soundcloud.ts` and `soundcloud-fetch` scrape SoundCloud's undocumented `api-v2` and require harvesting a client ID from browser dev tools. This breaks whenever SoundCloud ships a frontend update, and the [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use) explicitly prohibit it: *"any attempt to circumvent this and obtain a new client ID and Security Code is strictly prohibited."*
 
 **Coming from `soundcloud.ts`?** See the [Migration Guide](docs/MIGRATING.md) — most changes are find-and-replace.
 
@@ -182,6 +181,17 @@ await sc.auth.signOut(token.access_token);
 sc.clearToken();
 ```
 
+### Auth at a glance
+
+| Endpoint category | Client Credentials | User Token |
+|---|---|---|
+| tracks, users, search, playlists, resolve | ✅ | ✅ |
+| /me endpoints | ❌ | ✅ |
+| likes, reposts | ❌ | ✅ |
+| create/update/delete | ❌ | ✅ |
+
+See [Auth Guide](docs/auth-guide.md) for full details, token provider patterns, and troubleshooting.
+
 ## Client Class
 
 The `SoundCloudClient` class organizes all endpoints into namespaces. Token is resolved automatically when `setToken()` has been called. Override per-call via `{ token: "..." }` options object.
@@ -216,6 +226,7 @@ sc.me.unfollow(userUrn, options?)
 sc.me.getFollowers(limit?, options?)
 sc.me.getPlaylists(limit?, options?)
 sc.me.getTracks(limit?, options?)
+sc.me.getConnections(options?)  // connected social accounts; may require app approval
 
 // Users
 sc.users.getUser(userId, options?)
@@ -229,6 +240,7 @@ sc.users.getWebProfiles(userId, options?)
 
 // Tracks
 sc.tracks.getTrack(trackId, options?)
+sc.tracks.getTracks(ids[], options?)  // batch fetch by IDs
 sc.tracks.getStreams(trackId, options?)
 sc.tracks.getComments(trackId, limit?, options?)
 sc.tracks.createComment(trackId, body, timestamp?, options?)
@@ -267,6 +279,11 @@ sc.search.playlists(query, pageNumber?, options?)
 sc.resolve.resolveUrl(url, options?)
 ```
 
+// Raw escape hatch — call any endpoint
+sc.raw.get('/tracks/{id}', { id: 123456 })
+sc.raw.post('/tracks/{id}/comments', { body: { body: 'great track' } })
+sc.raw.request({ method: 'GET', path: '/me', query: {} })
+
 Where `options` is `{ token?: string }` — only needed to override the stored token.
 
 ## Standalone Functions
@@ -403,21 +420,105 @@ try {
 
 Error messages are parsed directly from SoundCloud's API response format, giving you the most useful message available.
 
+## Raw API — Call Any Endpoint
+
+`sc.raw` is a low-level escape hatch that lets you call any SoundCloud API endpoint — including ones not yet wrapped — while still using your configured auth and fetch.
+
+```ts
+import { SoundCloudClient, type RawResponse } from 'soundcloud-api-ts';
+
+const sc = new SoundCloudClient({ clientId, clientSecret });
+const token = await sc.auth.getClientToken();
+sc.setToken(token.access_token);
+
+// Path templating: {id} is replaced from the params object
+const res: RawResponse = await sc.raw.get('/tracks/{id}', { id: 123456 });
+console.log(res.data);    // parsed JSON body
+console.log(res.status);  // 200
+console.log(res.headers); // response headers
+
+// POST with body
+await sc.raw.post('/tracks/{id}/comments', { id: 123456, body: { body: 'great track', timestamp: 30000 } });
+
+// Fully generic
+await sc.raw.request({ method: 'DELETE', path: '/tracks/{id}', query: { id: 123456 } });
+```
+
+`sc.raw` returns `RawResponse<T = unknown>` — `{ data: T, status: number, headers: Record<string, string> }`. It does **not** throw on non-2xx status codes; check `res.status` yourself.
+
+---
+
+## In-Flight Deduplication & Caching
+
+### GET Coalescing (default on)
+
+When multiple callers fire the same GET request simultaneously (SSR, React StrictMode, concurrent components), only one fetch is made. All callers share the same promise.
+
+```ts
+const sc = new SoundCloudClient({
+  clientId, clientSecret,
+  dedupe: true,  // default — set false to disable
+});
+```
+
+### Pluggable Cache
+
+Bring your own cache backend — in-memory, Redis, Cloudflare KV, whatever. The base package defines the interface only (no implementation, no deps):
+
+```ts
+import { SoundCloudClient, type SoundCloudCache } from 'soundcloud-api-ts';
+
+const myCache: SoundCloudCache = {
+  get: (key) => store.get(key),
+  set: (key, value, { ttlMs }) => store.set(key, value, ttlMs),
+  delete: (key) => store.delete(key),
+};
+
+const sc = new SoundCloudClient({
+  clientId, clientSecret,
+  cache: myCache,
+  cacheTtlMs: 30_000, // 30s default per GET response
+});
+```
+
+---
+
+## Runtime Portability
+
+Pass a custom `fetch` implementation to work in any runtime — Cloudflare Workers, Deno, Bun, or environments without a global `fetch`:
+
+```ts
+const sc = new SoundCloudClient({
+  clientId, clientSecret,
+  fetch: myCustomFetch,          // optional: custom fetch
+  AbortController: myAbortCtrl, // optional: custom AbortController
+});
+```
+
+No Node-only APIs are used at runtime. The client works anywhere `fetch` is available.
+
+---
+
 ## Rate Limiting & Retries
 
 The client automatically retries on **429 Too Many Requests** and **5xx Server Errors** with exponential backoff:
 
 ```ts
+import { SoundCloudClient, type RetryInfo } from 'soundcloud-api-ts';
+
 const sc = new SoundCloudClient({
   clientId: "...",
   clientSecret: "...",
   maxRetries: 3,         // default: 3
   retryBaseDelay: 1000,  // default: 1000ms
   onDebug: (msg) => console.log(msg), // optional retry logging
+  onRetry: (info: RetryInfo) => {
+    console.warn(`[SC] retry #${info.attempt} — ${info.reason} (${info.status}) delay=${info.delayMs}ms url=${info.url}`);
+  },
 });
 ```
 
-- **429 responses** respect the `Retry-After` header when present
+- **429 responses** use the `Retry-After` header value as the delay (capped at 60s)
 - **5xx responses** (500, 502, 503, 504) are retried with exponential backoff
 - **4xx errors** (except 429) are NOT retried — they throw immediately
 - **401 errors** trigger `onTokenRefresh` (if configured) instead of retry

package/dist/{chunk-HCEUCJMA.mjs → chunk-JH7TLL2C.mjs}

@@ -15,7 +15,7 @@ function getRetryDelay(response, attempt, config) {
     const retryAfter = response.headers.get("retry-after");
     if (retryAfter) {
       const seconds = Number(retryAfter);
-      if (!Number.isNaN(seconds)) return seconds * 1e3;
+      if (!Number.isNaN(seconds)) return Math.min(seconds * 1e3, 6e4);
     }
   }
   const base = config.retryBaseDelay * Math.pow(2, attempt);
@@ -91,9 +91,26 @@ async function scFetch(options, refreshCtx, onRequest) {
         return void 0;
       }
       if (response.ok) {
-        const result = response.json();
+        const data = await response.json();
+        if (typeof data === "object" && data !== null) {
+          const metaHeaders = {};
+          if (typeof response.headers.forEach === "function") {
+            response.headers.forEach((value, key) => {
+              metaHeaders[key] = value;
+            });
+          }
+          try {
+            Object.defineProperty(data, "_meta", {
+              value: { status: response.status, headers: metaHeaders },
+              enumerable: false,
+              configurable: true,
+              writable: true
+            });
+          } catch {
+          }
+        }
         emitTelemetry();
-        return result;
+        return data;
       }
       if (!isRetryable(response.status)) {
         const body2 = await parseErrorBody(response);
@@ -108,6 +125,13 @@ async function scFetch(options, refreshCtx, onRequest) {
         retryConfig.onDebug?.(
           `Retry ${attempt + 1}/${retryConfig.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
         );
+        retryConfig.onRetry?.({
+          attempt: retryCount,
+          delayMs,
+          reason: `${response.status} ${response.statusText}`,
+          status: response.status,
+          url
+        });
         await delay(delayMs);
       }
     }
@@ -161,9 +185,26 @@ async function scFetchUrl(url, token, retryConfig, onRequest) {
       return void 0;
     }
     if (response.ok) {
-      const result = response.json();
+      const data = await response.json();
+      if (typeof data === "object" && data !== null) {
+        const metaHeaders = {};
+        if (typeof response.headers.forEach === "function") {
+          response.headers.forEach((value, key) => {
+            metaHeaders[key] = value;
+          });
+        }
+        try {
+          Object.defineProperty(data, "_meta", {
+            value: { status: response.status, headers: metaHeaders },
+            enumerable: false,
+            configurable: true,
+            writable: true
+          });
+        } catch {
+        }
+      }
       emitTelemetry();
-      return result;
+      return data;
     }
     if (!isRetryable(response.status)) {
       const body2 = await parseErrorBody(response);
@@ -178,6 +219,13 @@ async function scFetchUrl(url, token, retryConfig, onRequest) {
       config.onDebug?.(
         `Retry ${attempt + 1}/${config.maxRetries} after ${Math.round(delayMs)}ms (status ${response.status})`
       );
+      config.onRetry?.({
+        attempt: retryCount,
+        delayMs,
+        reason: `${response.status} ${response.statusText}`,
+        status: response.status,
+        url
+      });
       await delay(delayMs);
     }
   }
@@ -215,6 +263,96 @@ async function fetchAll(firstPage, fetchNext, options) {
   return result;
 }
 
+// src/client/raw.ts
+var RawClient = class {
+  constructor(baseUrl, getToken, fetchFn) {
+    this.baseUrl = baseUrl;
+    this.getToken = getToken;
+    this.fetchFn = fetchFn;
+  }
+  /**
+   * 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.
+   */
+  async request({
+    method,
+    path,
+    query,
+    body,
+    token
+  }) {
+    let resolvedPath = path;
+    const remainingQuery = {};
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value === void 0) continue;
+        const placeholder = `{${key}}`;
+        if (resolvedPath.includes(placeholder)) {
+          resolvedPath = resolvedPath.replace(new RegExp(`\\{${key}\\}`, "g"), String(value));
+        } else {
+          remainingQuery[key] = String(value);
+        }
+      }
+    }
+    const fullUrl = resolvedPath.startsWith("http") ? new URL(resolvedPath) : new URL(resolvedPath, this.baseUrl);
+    for (const [key, value] of Object.entries(remainingQuery)) {
+      fullUrl.searchParams.set(key, value);
+    }
+    const headers = {
+      Accept: "application/json"
+    };
+    const authToken = token ?? this.getToken();
+    if (authToken) {
+      headers["Authorization"] = `OAuth ${authToken}`;
+    }
+    let fetchBody;
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      fetchBody = JSON.stringify(body);
+    }
+    const response = await this.fetchFn(fullUrl.toString(), {
+      method,
+      headers,
+      body: fetchBody
+    });
+    const responseHeaders = {};
+    if (typeof response.headers.forEach === "function") {
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+    }
+    let data;
+    const contentLength = response.headers.get("content-length");
+    if (response.status === 204 || contentLength === "0") {
+      data = void 0;
+    } else {
+      try {
+        data = await response.json();
+      } catch {
+        data = void 0;
+      }
+    }
+    return { data, status: response.status, headers: responseHeaders };
+  }
+  /** GET shorthand */
+  get(path, params) {
+    return this.request({ method: "GET", path, query: params });
+  }
+  /** POST shorthand */
+  post(path, body) {
+    return this.request({ method: "POST", path, body });
+  }
+  /** PUT shorthand */
+  put(path, body) {
+    return this.request({ method: "PUT", path, body });
+  }
+  /** DELETE shorthand */
+  delete(path) {
+    return this.request({ method: "DELETE", path });
+  }
+};
+
 // src/client/SoundCloudClient.ts
 function resolveToken(tokenGetter, explicit) {
   const t = explicit ?? tokenGetter();
@@ -243,6 +381,8 @@ var SoundCloudClient = class _SoundCloudClient {
   likes;
   /** Repost/unrepost actions (/reposts) */
   reposts;
+  /** Low-level raw HTTP client — returns status/headers without throwing on non-2xx */
+  raw;
   /**
    * Creates a new SoundCloudClient instance.
    *
@@ -254,7 +394,8 @@ var SoundCloudClient = class _SoundCloudClient {
     const retryConfig = {
       maxRetries: config.maxRetries ?? 3,
       retryBaseDelay: config.retryBaseDelay ?? 1e3,
-      onDebug: config.onDebug
+      onDebug: config.onDebug,
+      onRetry: config.onRetry
     };
     const refreshCtx = config.onTokenRefresh ? {
       getToken,
@@ -283,6 +424,7 @@ var SoundCloudClient = class _SoundCloudClient {
     this.resolve = new _SoundCloudClient.Resolve(getToken, refreshCtx);
     this.likes = new _SoundCloudClient.Likes(getToken, refreshCtx);
     this.reposts = new _SoundCloudClient.Reposts(getToken, refreshCtx);
+    this.raw = new RawClient("https://api.soundcloud.com", getToken, config.fetch ?? globalThis.fetch);
   }
   /**
    * Store an access token (and optionally refresh token) on this client instance.
@@ -730,6 +872,27 @@ var SoundCloudClient = class _SoundCloudClient {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/me/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token: t });
     }
+    /**
+     * 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
+     */
+    async getConnections(options) {
+      const t = resolveToken(this.getToken, options?.token);
+      return this.fetch({ path: "/me/connections", method: "GET", token: t });
+    }
   }
   SoundCloudClient2.Me = Me;
   class Users {
@@ -901,6 +1064,26 @@ var SoundCloudClient = class _SoundCloudClient {
       const t = resolveToken(this.getToken, options?.token);
       return this.fetch({ path: `/tracks/${trackId}`, method: "GET", token: t });
     }
+    /**
+     * 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
+     */
+    async getTracks(ids, options) {
+      const t = resolveToken(this.getToken, options?.token);
+      return this.fetch({ path: `/tracks?ids=${ids.join(",")}`, method: "GET", token: t });
+    }
     /**
      * Get stream URLs for a track.
      *
@@ -1456,6 +1639,90 @@ var SoundCloudClient = class _SoundCloudClient {
   SoundCloudClient2.Reposts = Reposts;
 })(SoundCloudClient || (SoundCloudClient = {}));
 
+// src/client/dedupe.ts
+var InFlightDeduper = class {
+  inFlight = /* @__PURE__ */ new Map();
+  /**
+   * 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(key, factory) {
+    const existing = this.inFlight.get(key);
+    if (existing) return existing;
+    const promise = factory().finally(() => {
+      this.inFlight.delete(key);
+    });
+    this.inFlight.set(key, promise);
+    return promise;
+  }
+  /** Number of currently in-flight requests */
+  get size() {
+    return this.inFlight.size;
+  }
+};
+
+// src/client/registry.ts
+var IMPLEMENTED_OPERATIONS = [
+  // Auth
+  "post_oauth2_token",
+  "delete_oauth2_token",
+  // Me
+  "get_me",
+  "get_me_activities",
+  "get_me_activities_own",
+  "get_me_activities_tracks",
+  "get_me_likes_tracks",
+  "get_me_likes_playlists",
+  "get_me_followings",
+  "get_me_followings_tracks",
+  "post_me_followings_user_id",
+  "delete_me_followings_user_id",
+  "get_me_followers",
+  "get_me_playlists",
+  "get_me_tracks",
+  "get_me_connections",
+  // Users
+  "get_users_user_id",
+  "get_users_user_id_followers",
+  "get_users_user_id_followings",
+  "get_users_user_id_tracks",
+  "get_users_user_id_playlists",
+  "get_users_user_id_likes_tracks",
+  "get_users_user_id_likes_playlists",
+  "get_users_user_id_web_profiles",
+  // Tracks
+  "get_tracks_track_id",
+  "put_tracks_track_id",
+  "delete_tracks_track_id",
+  "get_tracks_track_id_comments",
+  "post_tracks_track_id_comments",
+  "get_tracks_track_id_likes",
+  "get_tracks_track_id_reposts",
+  "get_tracks_track_id_related",
+  "get_tracks_track_id_streams",
+  "post_likes_tracks_track_id",
+  "delete_likes_tracks_track_id",
+  "post_reposts_tracks_track_id",
+  "delete_reposts_tracks_track_id",
+  // Playlists
+  "get_playlists_playlist_id",
+  "post_playlists",
+  "put_playlists_playlist_id",
+  "delete_playlists_playlist_id",
+  "get_playlists_playlist_id_tracks",
+  "get_playlists_playlist_id_reposts",
+  "post_likes_playlists_playlist_id",
+  "delete_likes_playlists_playlist_id",
+  "post_reposts_playlists_playlist_id",
+  "delete_reposts_playlists_playlist_id",
+  // Search
+  "get_tracks",
+  "get_users",
+  "get_playlists",
+  // Resolve
+  "get_resolve"
+];
+
 // src/auth/getClientToken.ts
 var getClientToken = (clientId, clientSecret) => {
   const basicAuth = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
@@ -1575,6 +1842,13 @@ var getUserWebProfiles = (token, userId) => scFetch({ path: `/users/${userId}/we
 // src/tracks/getTrack.ts
 var getTrack = (token, trackId) => scFetch({ path: `/tracks/${trackId}`, method: "GET", token });
 
+// src/tracks/getTracks.ts
+var getTracks = (token, ids) => scFetch({
+  path: `/tracks?ids=${ids.join(",")}`,
+  method: "GET",
+  token
+});
+
 // src/tracks/getComments.ts
 var getTrackComments = (token, trackId, limit) => scFetch({ path: `/tracks/${trackId}/comments?threaded=1&filter_replies=0${limit ? `&limit=${limit}` : ""}&linked_partitioning=true`, method: "GET", token });
 
@@ -1693,6 +1967,9 @@ var getMePlaylists = (token, limit) => scFetch({ path: `/me/playlists?${limit ?
 // src/me/tracks.ts
 var getMeTracks = (token, limit) => scFetch({ path: `/me/tracks?${limit ? `limit=${limit}&` : ""}linked_partitioning=true`, method: "GET", token });
 
+// src/me/connections.ts
+var getMeConnections = (token) => scFetch({ path: "/me/connections", method: "GET", token });
+
 // src/likes/index.ts
 var likePlaylist = async (token, playlistId) => {
   try {
@@ -1748,6 +2025,6 @@ 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`;
 
-export { SoundCloudClient, 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 };
-//# sourceMappingURL=chunk-HCEUCJMA.mjs.map
-//# sourceMappingURL=chunk-HCEUCJMA.mjs.map
+export { IMPLEMENTED_OPERATIONS, InFlightDeduper, RawClient, SoundCloudClient, 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 };
+//# sourceMappingURL=chunk-JH7TLL2C.mjs.map
+//# sourceMappingURL=chunk-JH7TLL2C.mjs.map