soundcloud-api-ts 1.6.2 → 1.6.4
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/README.md +30 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -25,14 +25,25 @@ A fully-typed TypeScript client for the SoundCloud API. Zero dependencies, nativ
|
|
|
25
25
|
|
|
26
26
|
## Comparison
|
|
27
27
|
|
|
28
|
-
| Feature | soundcloud-api-ts | soundcloud.ts |
|
|
28
|
+
| Feature | soundcloud-api-ts | soundcloud.ts | soundcloud-fetch |
|
|
29
29
|
| --- | --- | --- | --- |
|
|
30
|
-
| TypeScript | ✅ Native | ✅ |
|
|
31
|
-
| Dependencies | 0 |
|
|
32
|
-
| OAuth 2.0 |
|
|
33
|
-
|
|
|
34
|
-
|
|
|
35
|
-
|
|
|
30
|
+
| TypeScript | ✅ Native | ✅ | ✅ |
|
|
31
|
+
| Dependencies | **0** | 1 | 3 (lodash, cookie, undici) |
|
|
32
|
+
| Auth method | **Official OAuth 2.0** | ⚠️ Scrape client ID from browser | ⚠️ Scrape client ID from browser |
|
|
33
|
+
| PKCE support | ✅ | ❌ | ❌ |
|
|
34
|
+
| Auto token refresh | ✅ on 401 | ❌ | ❌ |
|
|
35
|
+
| Auto retry (429/5xx) | ✅ exponential backoff | ❌ | ❌ |
|
|
36
|
+
| CLI tool | ✅ `sc-cli` | ❌ | ❌ |
|
|
37
|
+
| Pagination helpers | ✅ async iterators | ❌ | ✅ |
|
|
38
|
+
| Typed errors | ✅ `SoundCloudError` | ❌ | ❌ |
|
|
39
|
+
| Test coverage | **94%** | — | — |
|
|
40
|
+
| API docs site | ✅ [TypeDoc](https://twin-paws.github.io/soundcloud-api-ts/) | ✅ | ❌ |
|
|
41
|
+
| LLM/AI-friendly | ✅ llms.txt + AGENTS.md | ❌ | ❌ |
|
|
42
|
+
| Maintained | ✅ 2026 | ✅ 2025 | ✅ 2026 |
|
|
43
|
+
|
|
44
|
+
> **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."*
|
|
45
|
+
>
|
|
46
|
+
> `soundcloud-api-ts` uses the **official documented API** (`api.soundcloud.com`) with registered app credentials, OAuth 2.1 as specified by SoundCloud, PKCE for public clients, and automatic token refresh.
|
|
36
47
|
|
|
37
48
|
## Install
|
|
38
49
|
|
|
@@ -392,6 +403,18 @@ const sc = new SoundCloudClient({
|
|
|
392
403
|
- **401 errors** trigger `onTokenRefresh` (if configured) instead of retry
|
|
393
404
|
- Backoff formula: `baseDelay × 2^attempt` with jitter
|
|
394
405
|
|
|
406
|
+
## API Terms Compliance
|
|
407
|
+
|
|
408
|
+
This package is built on SoundCloud's **official documented API** (`api.soundcloud.com`) and follows the [API Terms of Use](https://developers.soundcloud.com/docs/api/terms-of-use):
|
|
409
|
+
|
|
410
|
+
- ✅ Uses registered app credentials (client ID + client secret) via OAuth 2.1
|
|
411
|
+
- ✅ No undocumented or internal API endpoints (`api-v2`)
|
|
412
|
+
- ✅ No client ID scraping or credential circumvention
|
|
413
|
+
- ✅ No content downloading, ripping, or stream capture
|
|
414
|
+
- ✅ No content aggregation into alternative streaming services
|
|
415
|
+
|
|
416
|
+
> **Important:** SoundCloud's API Terms prohibit using User Content (audio, tracks, metadata) to train or develop AI/ML models. The "LLM-friendly" features of this package (`llms.txt`, `AGENTS.md`) are for helping AI coding agents **use the package itself** — not for feeding SoundCloud content to AI systems. Please review the [full terms](https://developers.soundcloud.com/docs/api/terms-of-use) before building your application.
|
|
417
|
+
|
|
395
418
|
## AI / LLM Integration
|
|
396
419
|
|
|
397
420
|
This package is designed to be easily used by AI coding agents:
|
package/package.json
CHANGED