@saavn-labs/sdk 0.1.1 → 0.1.2
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 +27 -21
- package/dist/helpers/experimental/stream-urls/index.js +11 -2
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -7,6 +7,28 @@ A low-level, type-safe TypeScript SDK over **JioSaavn’s native API**, built fo
|
|
|
7
7
|
[](./LICENSE)
|
|
8
8
|
|
|
9
9
|
**This is not a product API. This is the foundation everything else is built on.**
|
|
10
|
+
|
|
11
|
+
## Table of contents
|
|
12
|
+
|
|
13
|
+
- [Why This Exists](#why-this-exists)
|
|
14
|
+
- [What This SDK Guarantees](#what-this-sdk-guarantees)
|
|
15
|
+
- [Design Principles](#design-principles)
|
|
16
|
+
- [Operations](#operations)
|
|
17
|
+
- [Installation](#installation)
|
|
18
|
+
- [Examples](#examples)
|
|
19
|
+
- [Get Songs by ID](#1-get-songs-by-id)
|
|
20
|
+
- [Get Song by Permalink](#2-get-song-by-permalink)
|
|
21
|
+
- [Search Songs](#3-search-songs)
|
|
22
|
+
- [Get Trending Albums](#4-get-trending-albums)
|
|
23
|
+
- [Cross-Entity Search](#5-cross-entity-search)
|
|
24
|
+
- [Full Module Documentation](#full-module-documentation)
|
|
25
|
+
- [Error Handling](#error-handling)
|
|
26
|
+
- [Runtime Support](#runtime-support)
|
|
27
|
+
- [What This SDK Does NOT Do](#what-this-sdk-does-not-do)
|
|
28
|
+
- [Development & Examples](#development--examples)
|
|
29
|
+
- [Contributing](#contributing)
|
|
30
|
+
- [Legal Notice](#legal-notice)
|
|
31
|
+
- [License](#license)
|
|
10
32
|
|
|
11
33
|
This SDK mirrors Saavn’s native operations at the boundary, while exposing stable, domain-level outputs to consumers.
|
|
12
34
|
|
|
@@ -70,30 +92,14 @@ This package is the **single source of truth** for interacting with JioSaavn’s
|
|
|
70
92
|
|
|
71
93
|
---
|
|
72
94
|
|
|
73
|
-
##
|
|
95
|
+
## Operations
|
|
74
96
|
|
|
75
|
-
|
|
76
|
-
@saavn-labs/sdk
|
|
77
|
-
├── saavn # ODD: Native Saavn operations, params, and raw response schemas
|
|
78
|
-
├── core # DDD: Stable SDK entities, primitives, and modules
|
|
79
|
-
├── mappers # Bridges from Saavn responses to domain entities
|
|
80
|
-
├── transport # Request lifecycle, fetch utilities, and user-agent rotation
|
|
81
|
-
└── types # Public TypeScript types and endpoint contracts
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
- **`saavn/` (Operations-Driven Design)** mirrors JioSaavn’s native calls (`call`, `params`, `response`) and stays close to upstream payloads.
|
|
85
|
-
- **`core/` (Domain-Driven Design)** is the long-lived surface for consumers; shapes change only in majors.
|
|
86
|
-
- **`mappers/`** connect raw Saavn responses to domain entities when normalization is needed.
|
|
87
|
-
- **`transport/`** provides the thin HTTP layer (`fetchFromSaavn`) with context selection, UA rotation, and timeouts.
|
|
88
|
-
|
|
89
|
-
### Operations currently modeled (0.x)
|
|
90
|
-
|
|
91
|
-
- `get-details` (song, album, artist, playlist, top albums of the year, top searches)
|
|
97
|
+
- `get-details` (album, artist, playlist, song, top albums of the year, top searches)
|
|
92
98
|
- `get-reco` (album, playlist, song)
|
|
93
99
|
- `get-trending` (all, albums, playlists, songs)
|
|
94
|
-
- `search-results`
|
|
95
|
-
- `web-api`
|
|
96
|
-
- `web-radio`
|
|
100
|
+
- `search-results` (all, albums, artists, playlists, songs)
|
|
101
|
+
- `web-api` (album, artist, playlist, songs)
|
|
102
|
+
- `web-radio` (ceate stations, get station songs)
|
|
97
103
|
|
|
98
104
|
Each operation ships Zod schemas for both parameters and raw responses, validated against recorded Postman fixtures in `tests/postman/collections`.
|
|
99
105
|
|
|
@@ -1,6 +1,13 @@
|
|
|
1
1
|
import { SDKError, experimentalError } from '../../../helpers/errors.js';
|
|
2
|
-
import { generateStreamUrlsNode } from './stream-urls.node.js';
|
|
3
2
|
import { generateStreamUrlsEdge } from './stream-urls.edge.js';
|
|
3
|
+
async function loadNodeImpl() {
|
|
4
|
+
if (typeof process === 'undefined' ||
|
|
5
|
+
!process.versions?.node) {
|
|
6
|
+
throw new SDKError('UNSUPPORTED_RUNTIME', 'Node runtime required for node stream URL generation');
|
|
7
|
+
}
|
|
8
|
+
const mod = await import('./stream-urls.node.js');
|
|
9
|
+
return mod.generateStreamUrlsNode;
|
|
10
|
+
}
|
|
4
11
|
/**
|
|
5
12
|
* ⚠️ EXPERIMENTAL
|
|
6
13
|
*
|
|
@@ -23,8 +30,10 @@ export async function fetchStreamUrls(encryptedUrl, runtime, acknowledge) {
|
|
|
23
30
|
throw experimentalError('Stream URL generation is experimental and requires explicit acknowledgment.');
|
|
24
31
|
}
|
|
25
32
|
switch (runtime) {
|
|
26
|
-
case 'node':
|
|
33
|
+
case 'node': {
|
|
34
|
+
const generateStreamUrlsNode = await loadNodeImpl();
|
|
27
35
|
return generateStreamUrlsNode(encryptedUrl);
|
|
36
|
+
}
|
|
28
37
|
case 'edge':
|
|
29
38
|
return generateStreamUrlsEdge(encryptedUrl);
|
|
30
39
|
default:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@saavn-labs/sdk",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "A low-level, type-safe TypeScript SDK over JioSaavn’s native API, built for developers who want full control, predictable contracts, and long-term stability.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -70,6 +70,7 @@
|
|
|
70
70
|
},
|
|
71
71
|
"devDependencies": {
|
|
72
72
|
"@types/bun": "latest",
|
|
73
|
+
"@types/node": "^25.0.9",
|
|
73
74
|
"prettier": "^3.7.4",
|
|
74
75
|
"tsc-alias": "^1.8.16",
|
|
75
76
|
"typescript": "^5.9.3",
|