@saavn-labs/sdk 0.1.0

package/dist/core/modules/playlist.module.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Fetch a playlist by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.playlistId - Saavn playlist ID
+ * @returns Normalized playlist object
+ */
+declare function getById({ playlistId }: {
+    playlistId: string;
+}): Promise<import("../models").Playlist>;
+/**
+ * Fetch a playlist by permalink.
+ *
+ * @param params - Parameters object
+ * @param params.permalink - Playlist permalink string
+ * @returns Normalized playlist object
+ */
+declare function getByPermalink({ permalink }: {
+    permalink: string;
+}): Promise<import("../models").Playlist>;
+/**
+ * Fetch playlist recommendations by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.playlistId - Saavn playlist ID
+ * @returns List of recommended playlists
+ */
+declare function getRecommendations({ playlistId }: {
+    playlistId: string;
+}): Promise<{
+    id: string;
+    type: "playlist";
+    title: string;
+    subtitle: string;
+    url: string;
+    images: import("../..").Image[];
+    flags: {
+        isExplicit: boolean;
+    };
+    owner: {
+        name: string;
+    };
+}[]>;
+/**
+ * Get trending playlists by language.
+ *
+ * @param params - Parameters object
+ * @param params.language - Language code
+ * @returns List of trending playlists
+ */
+declare function getTrending({ language }: {
+    language: string;
+}): Promise<import("../models").Playlist[]>;
+/**
+ * Search for playlists by query.
+ *
+ * @param params - Parameters object
+ * @param params.query - Search query string
+ * @param params.limit - Number of results to return (default: 10)
+ * @param params.offset - Offset for pagination (default: 1)
+ * @returns List of matching playlists
+ */
+declare function search({ query, limit, offset, }: {
+    query: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    total: number;
+    start: number;
+    results: import("../models").Playlist[];
+}>;
+export declare const PlaylistModule: {
+    getById: typeof getById;
+    getByPermalink: typeof getByPermalink;
+    getRecommendations: typeof getRecommendations;
+    getTrending: typeof getTrending;
+    search: typeof search;
+};
+export {};

package/dist/core/modules/playlist.module.js

@@ -0,0 +1,74 @@
+import { SaavnGetDetails, SaavnGetReco, SaavnGetTrending, SaavnSearchResults, SaavnWebAPI, } from '../../saavn/operations';
+import { runOperation } from '../../saavn/run-operation';
+import { extractPermalinkToken } from '../../helpers/utils';
+import { SDKError } from '../../helpers/errors';
+/**
+ * Fetch a playlist by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.playlistId - Saavn playlist ID
+ * @returns Normalized playlist object
+ */
+function getById({ playlistId }) {
+    return runOperation(SaavnGetDetails.playlist, { listid: playlistId });
+}
+/**
+ * Fetch a playlist by permalink.
+ *
+ * @param params - Parameters object
+ * @param params.permalink - Playlist permalink string
+ * @returns Normalized playlist object
+ */
+function getByPermalink({ permalink }) {
+    const { token, type } = extractPermalinkToken(permalink) ?? {};
+    if (!token || type !== 'playlist') {
+        throw new SDKError('INVALID_PARAMS', 'Invalid permalink provided');
+    }
+    return runOperation(SaavnWebAPI.playlist, { token, type: 'playlist' });
+}
+/**
+ * Fetch playlist recommendations by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.playlistId - Saavn playlist ID
+ * @returns List of recommended playlists
+ */
+function getRecommendations({ playlistId }) {
+    return runOperation(SaavnGetReco.playlists, { listid: playlistId });
+}
+/**
+ * Get trending playlists by language.
+ *
+ * @param params - Parameters object
+ * @param params.language - Language code
+ * @returns List of trending playlists
+ */
+function getTrending({ language }) {
+    return runOperation(SaavnGetTrending.playlists, {
+        entity_language: language,
+        entity_type: 'playlist',
+    });
+}
+/**
+ * Search for playlists by query.
+ *
+ * @param params - Parameters object
+ * @param params.query - Search query string
+ * @param params.limit - Number of results to return (default: 10)
+ * @param params.offset - Offset for pagination (default: 1)
+ * @returns List of matching playlists
+ */
+function search({ query, limit = 20, offset = 1, }) {
+    return runOperation(SaavnSearchResults.playlists, {
+        q: query,
+        p: String(offset),
+        n: String(limit),
+    });
+}
+export const PlaylistModule = {
+    getById,
+    getByPermalink,
+    getRecommendations,
+    getTrending,
+    search,
+};

package/dist/core/modules/song.module.d.ts

@@ -0,0 +1,91 @@
+import { fetchStreamUrls } from '../../helpers/experimental/stream-urls';
+/**
+ * Fetch a song or songs by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.songIds - Saavn song ID or array of IDs
+ * @returns Normalized song object or list
+ */
+declare function getById({ songIds }: {
+    songIds: string[] | string;
+}): Promise<{
+    songs: import("../models").Song[];
+}>;
+/**
+ * Fetch a song by permalink.
+ *
+ * @param params - Parameters object
+ * @param params.permalink - Song permalink string
+ * @returns Normalized song object
+ */
+declare function getByPermalink({ permalink }: {
+    permalink: string;
+}): Promise<{
+    songs: import("../models").Song[];
+}>;
+/**
+ * Fetch songs by station ID.
+ *
+ * @param params - Parameters object
+ * @param params.stationId - Station ID
+ * @param params.limit - Number of songs to fetch (default: 10)
+ * @param params.next - Whether to get next songs (optional)
+ * @returns List of songs from station
+ */
+declare function getByStationId({ stationId, limit, next, }: {
+    stationId: string;
+    limit?: number;
+    next?: boolean;
+}): Promise<{
+    stationId: string | undefined;
+    songs: import("../models").Song[];
+}>;
+/**
+ * Fetch song recommendations by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.songId - Saavn song ID
+ * @returns List of recommended songs
+ */
+declare function getRecommendations({ songId }: {
+    songId: string;
+}): Promise<import("../models").Song[]>;
+/**
+ * Get trending songs by language.
+ * @param params - Parameters object
+ * @param params.language - Language code
+ * @returns List of trending songs
+ */
+declare function getTrending({ language }: {
+    language: string;
+}): Promise<import("../models").Song[]>;
+/**
+ * Search for songs by query.
+ *
+ * @param params - Parameters object
+ * @param params.query - Search query string
+ * @param params.limit - Number of results to return (default: 10)
+ * @param params.offset - Offset for pagination (default: 1)
+ * @returns List of matching songs
+ */
+declare function search({ query, limit, offset, }: {
+    query: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    total: number;
+    start: number;
+    results: import("../models").Song[];
+}>;
+export declare const SongModule: {
+    getById: typeof getById;
+    getByPermalink: typeof getByPermalink;
+    getByStationId: typeof getByStationId;
+    getRecommendations: typeof getRecommendations;
+    getTrending: typeof getTrending;
+    search: typeof search;
+    experimental: {
+        fetchStreamUrls: typeof fetchStreamUrls;
+    };
+};
+export {};

package/dist/core/modules/song.module.js

@@ -0,0 +1,97 @@
+import { SaavnGetDetails, SaavnGetReco, SaavnGetTrending, SaavnSearchResults, SaavnWebAPI, SaavnWebRadio, } from '../../saavn/operations';
+import { runOperation } from '../../saavn/run-operation';
+import { extractPermalinkToken } from '../../helpers/utils';
+import { fetchStreamUrls } from '../../helpers/experimental/stream-urls';
+import { SDKError } from '../../helpers/errors';
+/**
+ * Fetch a song or songs by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.songIds - Saavn song ID or array of IDs
+ * @returns Normalized song object or list
+ */
+function getById({ songIds }) {
+    return runOperation(SaavnGetDetails.songs, {
+        pids: songIds instanceof Array ? songIds.join(',') : songIds,
+    });
+}
+/**
+ * Fetch a song by permalink.
+ *
+ * @param params - Parameters object
+ * @param params.permalink - Song permalink string
+ * @returns Normalized song object
+ */
+function getByPermalink({ permalink }) {
+    const { token, type } = extractPermalinkToken(permalink) ?? {};
+    if (!token || type !== 'song') {
+        throw new SDKError('INVALID_PARAMS', 'Invalid permalink provided');
+    }
+    return runOperation(SaavnWebAPI.songs, { token, type: 'song' });
+}
+/**
+ * Fetch songs by station ID.
+ *
+ * @param params - Parameters object
+ * @param params.stationId - Station ID
+ * @param params.limit - Number of songs to fetch (default: 10)
+ * @param params.next - Whether to get next songs (optional)
+ * @returns List of songs from station
+ */
+function getByStationId({ stationId, limit = 20, next, }) {
+    return runOperation(SaavnWebRadio.songs, {
+        ctx: 'android',
+        stationid: stationId,
+        k: String(limit),
+        next: next ? '1' : '0',
+    });
+}
+/**
+ * Fetch song recommendations by Saavn ID.
+ *
+ * @param params - Parameters object
+ * @param params.songId - Saavn song ID
+ * @returns List of recommended songs
+ */
+function getRecommendations({ songId }) {
+    return runOperation(SaavnGetReco.songs, { pid: songId });
+}
+/**
+ * Get trending songs by language.
+ * @param params - Parameters object
+ * @param params.language - Language code
+ * @returns List of trending songs
+ */
+function getTrending({ language }) {
+    return runOperation(SaavnGetTrending.songs, {
+        entity_language: language,
+        entity_type: 'song',
+    });
+}
+/**
+ * Search for songs by query.
+ *
+ * @param params - Parameters object
+ * @param params.query - Search query string
+ * @param params.limit - Number of results to return (default: 10)
+ * @param params.offset - Offset for pagination (default: 1)
+ * @returns List of matching songs
+ */
+function search({ query, limit = 20, offset = 1, }) {
+    return runOperation(SaavnSearchResults.songs, {
+        q: query,
+        p: String(offset),
+        n: String(limit),
+    });
+}
+export const SongModule = {
+    getById,
+    getByPermalink,
+    getByStationId,
+    getRecommendations,
+    getTrending,
+    search,
+    experimental: {
+        fetchStreamUrls,
+    },
+};

package/dist/helpers/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Error utilities for @saavn-labs/sdk
+ * @module errors
+ * @internal
+ */
+import { ZodError } from 'zod';
+export type SDKErrorCode = 'INVALID_PARAMS' | 'INVALID_RESPONSE' | 'API_ERROR' | 'NETWORK_ERROR' | 'UNSUPPORTED_RUNTIME' | 'EXPERIMENTAL_FEATURE' | 'INTERNAL_ERROR';
+export declare class SDKError extends Error {
+    readonly code: SDKErrorCode;
+    readonly details?: unknown;
+    cause?: unknown;
+    constructor(code: SDKErrorCode, message: string, options?: {
+        details?: unknown;
+        cause?: unknown;
+    });
+}
+export declare function fromZodError(error: ZodError, kind: 'params' | 'response', context?: string): SDKError;
+export declare function networkError(context?: string, status?: number): SDKError;
+export declare function experimentalError(message?: string): SDKError;
+export declare function internalError(message?: string, cause?: unknown): SDKError;
+/**
+ * Detect unusable API responses before schema validation.
+ * Returns a user-friendly message or null if response looks valid.
+ */
+export declare function detectSaavnApiError(data: unknown): string | null;

package/dist/helpers/errors.js

@@ -0,0 +1,84 @@
+/**
+ * Error utilities for @saavn-labs/sdk
+ * @module errors
+ * @internal
+ */
+import { ZodError } from 'zod';
+export class SDKError extends Error {
+    code;
+    details;
+    cause;
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'SDKError';
+        this.code = code;
+        this.details = options?.details;
+        this.cause = options?.cause;
+    }
+}
+export function fromZodError(error, kind, context) {
+    return new SDKError(kind === 'params' ? 'INVALID_PARAMS' : 'INVALID_RESPONSE', `Invalid ${kind}${context ? ` for ${context}` : ''}.`, {
+        details: error.issues.map((issue) => ({
+            path: issue.path.join('.'),
+            message: issue.message,
+        })),
+        cause: error,
+    });
+}
+export function networkError(context, status) {
+    return new SDKError('NETWORK_ERROR', `Request failed${context ? ` for ${context}` : ''}.`, {
+        details: status ? { status } : undefined,
+    });
+}
+export function experimentalError(message) {
+    return new SDKError('EXPERIMENTAL_FEATURE', message ??
+        'This feature is experimental and requires explicit user acknowledgment.');
+}
+export function internalError(message = 'An internal error occurred.', cause) {
+    return new SDKError('INTERNAL_ERROR', message, { cause });
+}
+/**
+ * Detect unusable API responses before schema validation.
+ * Returns a user-friendly message or null if response looks valid.
+ */
+export function detectSaavnApiError(data) {
+    if (data == null) {
+        return 'Empty response from Saavn API.';
+    }
+    if (data === '' || data === false) {
+        return 'Invalid response from Saavn API.';
+    }
+    if (Array.isArray(data) && data.length === 0) {
+        return 'No data returned from Saavn API.';
+    }
+    if (typeof data !== 'object') {
+        return null;
+    }
+    const obj = data;
+    if (typeof obj.error === 'string') {
+        return obj.error;
+    }
+    if (typeof obj.error === 'object' && obj.error !== null) {
+        const err = obj.error;
+        if (typeof err.msg === 'string') {
+            return err.msg;
+        }
+        if (typeof err.code === 'string') {
+            switch (err.code) {
+                case 'INPUT_MISSING':
+                    return 'One or more required parameters are missing.';
+                default:
+                    return `Saavn API error (${err.code}).`;
+            }
+        }
+        return 'Saavn API returned an error.';
+    }
+    if (Object.prototype.hasOwnProperty.call(obj, 'stationid') &&
+        obj.stationid === '') {
+        return 'Invalid or expired station ID.';
+    }
+    if (typeof obj.status === 'string' && obj.status !== 'success') {
+        return `Saavn API returned status: ${obj.status}.`;
+    }
+    return null;
+}

package/dist/helpers/experimental/stream-urls/index.d.ts

@@ -0,0 +1,20 @@
+export type Runtime = 'node' | 'edge';
+/**
+ * ⚠️ EXPERIMENTAL
+ *
+ * Generates direct download links for a song.
+ *
+ * This API behaves differently depending on runtime:
+ * - `node`: uses local DES-ECB decryption via Node crypto
+ * - `edge`: uses Saavn's undocumented internal API
+ *
+ * Runtime must be specified explicitly.
+ *
+ * @param encryptedUrl - Encrypted media URL
+ * @param options - { runtime: 'node' | 'edge', acknowledge: boolean } to acknowledge experimental nature
+ * @returns Stream URL
+ */
+export declare function fetchStreamUrls(encryptedUrl: string, runtime: Runtime, acknowledge: boolean): Promise<Array<{
+    bitrate: string;
+    url: string;
+}>>;

package/dist/helpers/experimental/stream-urls/index.js

@@ -0,0 +1,33 @@
+import { SDKError, experimentalError } from '../../../helpers/errors';
+import { generateStreamUrlsNode } from './stream-urls.node';
+import { generateStreamUrlsEdge } from './stream-urls.edge';
+/**
+ * ⚠️ EXPERIMENTAL
+ *
+ * Generates direct download links for a song.
+ *
+ * This API behaves differently depending on runtime:
+ * - `node`: uses local DES-ECB decryption via Node crypto
+ * - `edge`: uses Saavn's undocumented internal API
+ *
+ * Runtime must be specified explicitly.
+ *
+ * @param encryptedUrl - Encrypted media URL
+ * @param options - { runtime: 'node' | 'edge', acknowledge: boolean } to acknowledge experimental nature
+ * @returns Stream URL
+ */
+export async function fetchStreamUrls(encryptedUrl, runtime, acknowledge) {
+    if (!encryptedUrl)
+        return [];
+    if (acknowledge !== true) {
+        throw experimentalError('Stream URL generation is experimental and requires explicit acknowledgment.');
+    }
+    switch (runtime) {
+        case 'node':
+            return generateStreamUrlsNode(encryptedUrl);
+        case 'edge':
+            return generateStreamUrlsEdge(encryptedUrl);
+        default:
+            throw new SDKError('UNSUPPORTED_RUNTIME', `Unsupported runtime: ${String(runtime)}`);
+    }
+}

package/dist/helpers/experimental/stream-urls/stream-urls.edge.d.ts

@@ -0,0 +1,4 @@
+export declare function generateStreamUrlsEdge(encryptedUrl: string): Promise<{
+    bitrate: "12kbps" | "48kbps" | "96kbps" | "160kbps" | "320kbps";
+    url: string;
+}[]>;

package/dist/helpers/experimental/stream-urls/stream-urls.edge.js

@@ -0,0 +1,38 @@
+import { fetchFromSaavn } from '../../../helpers/fetch';
+const AUDIO_QUALITIES = [
+    { id: '_12', bitrate: '12kbps' },
+    { id: '_48', bitrate: '48kbps' },
+    { id: '_96', bitrate: '96kbps' },
+    { id: '_160', bitrate: '160kbps' },
+    { id: '_320', bitrate: '320kbps' },
+];
+function normalizeAacUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        url.hostname = url.hostname.replace(/^web\./, 'aac.');
+        return url.toString();
+    }
+    catch {
+        return rawUrl;
+    }
+}
+export async function generateStreamUrlsEdge(encryptedUrl) {
+    const res = await fetchFromSaavn({
+        call: 'song.generateAuthToken',
+        params: {
+            url: encryptedUrl,
+            bitrate: '96',
+        },
+    });
+    if (!res.ok)
+        return [];
+    const data = res.data;
+    if (typeof data.auth_url === 'string') {
+        const baseUrl = normalizeAacUrl(data.auth_url.split('?')[0]);
+        return AUDIO_QUALITIES.map((q) => ({
+            bitrate: q.bitrate,
+            url: baseUrl.replace('_96', q.id),
+        }));
+    }
+    return [];
+}

package/dist/helpers/experimental/stream-urls/stream-urls.node.d.ts

@@ -0,0 +1,4 @@
+export declare function generateStreamUrlsNode(encryptedUrl: string): {
+    bitrate: "12kbps" | "48kbps" | "96kbps" | "160kbps" | "320kbps";
+    url: string;
+}[];

package/dist/helpers/experimental/stream-urls/stream-urls.node.js

@@ -0,0 +1,27 @@
+import crypto from 'node:crypto';
+const AUDIO_QUALITIES = [
+    { id: '_12', bitrate: '12kbps' },
+    { id: '_48', bitrate: '48kbps' },
+    { id: '_96', bitrate: '96kbps' },
+    { id: '_160', bitrate: '160kbps' },
+    { id: '_320', bitrate: '320kbps' },
+];
+export function generateStreamUrlsNode(encryptedUrl) {
+    if (!encryptedUrl)
+        return [];
+    try {
+        const key = Buffer.from('38346591', 'utf8');
+        const decipher = crypto.createDecipheriv('des-ecb', key, null);
+        decipher.setAutoPadding(true);
+        const decrypted = decipher.update(encryptedUrl, 'base64', 'utf8') + decipher.final('utf8');
+        if (!decrypted)
+            return [];
+        return AUDIO_QUALITIES.map((q) => ({
+            bitrate: q.bitrate,
+            url: decrypted.replace('_96', q.id),
+        }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/helpers/fetch.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fetch utility for @saavn-labs/sdk
+ * @module fetch
+ * @internal
+ */
+/**
+ * API context/environment to use for requests
+ * - 'web6dot0': Web context
+ * - 'android': Android context
+ */
+export type ClientContext = 'web6dot0' | 'android';
+/**
+ * Parameters for making an API request to JioSaavn
+ */
+export interface FetchParams {
+    /** API call to op (e.g., 'song.getDetails') */
+    call: string;
+    /** Query parameters for the API call */
+    params?: Record<string, string | number | boolean>;
+    /** API context to use (default: 'web6dot0') */
+    context?: ClientContext;
+    /** Base URL for the JioSaavn API (e.g. your own proxy) */
+    baseUrl?: string;
+    /** Custom HTTP headers to include in request */
+    headers?: Record<string, string>;
+    /** Custom User-Agent strings to rotate from (optional) */
+    userAgents?: string[];
+    /** Custom fetch implementation (e.g., for environments without global fetch) */
+    fetch?: typeof fetch;
+    /** Optional timeout in milliseconds */
+    timeoutMs?: number;
+}
+export interface FetchResponse {
+    data: unknown;
+    ok: boolean;
+    status: number;
+}
+export declare const fetchFromSaavn: ({ call, params, context, baseUrl, headers, userAgents, timeoutMs, fetch: fetchImpl, }: FetchParams) => Promise<FetchResponse>;

package/dist/helpers/fetch.js

@@ -0,0 +1,38 @@
+/**
+ * Fetch utility for @saavn-labs/sdk
+ * @module fetch
+ * @internal
+ */
+import { pickUserAgent } from './utils';
+const BASE_URL = 'https://www.jiosaavn.com';
+export const fetchFromSaavn = async ({ call, params = {}, context = 'web6dot0', baseUrl = BASE_URL, headers = {}, userAgents, timeoutMs, fetch: fetchImpl = globalThis.fetch, }) => {
+    const url = new URL(`${baseUrl}/api.php`);
+    url.searchParams.append('__call', call);
+    url.searchParams.append('_format', 'json');
+    url.searchParams.append('_marker', '0');
+    url.searchParams.append('api_version', '4');
+    url.searchParams.append('ctx', context);
+    for (const [k, v] of Object.entries(params)) {
+        url.searchParams.append(k, String(v));
+    }
+    const controller = timeoutMs ? new AbortController() : undefined;
+    const timer = timeoutMs
+        ? setTimeout(() => controller?.abort(), timeoutMs)
+        : undefined;
+    try {
+        const res = await fetchImpl(url.toString(), {
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': pickUserAgent(userAgents),
+                ...headers,
+            },
+            signal: controller?.signal,
+        });
+        const data = await res.json();
+        return { data, ok: res.ok, status: res.status };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+};

package/dist/helpers/utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * General utilities for @saavn-labs/sdk
+ * @module utils
+ * @internal
+ */
+import type { SaavnPermalinkToken } from '../types';
+export declare function pickUserAgent(custom?: readonly string[]): string;
+/**
+ * Extract entity type and token from a JioSaavn share URL
+ * @param permaLink - JioSaavn share URL or token
+ * @returns Extracted token object or undefined if invalid
+ */
+export declare function extractPermalinkToken(permaLink: string): SaavnPermalinkToken | undefined;