@saavn-labs/sdk 0.1.0

package/dist/helpers/utils.js

@@ -0,0 +1,58 @@
+/**
+ * General utilities for @saavn-labs/sdk
+ * @module utils
+ * @internal
+ */
+const DEFAULT_USER_AGENTS = [
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15',
+];
+export function pickUserAgent(custom) {
+    const agents = Array.isArray(custom) && custom.length > 0 ? custom : DEFAULT_USER_AGENTS;
+    return agents[Math.floor(Math.random() * agents.length)];
+}
+/**
+ * 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 function extractPermalinkToken(permaLink) {
+    if (!permaLink || typeof permaLink !== 'string')
+        return undefined;
+    let url;
+    try {
+        url = permaLink.startsWith('http')
+            ? new URL(permaLink)
+            : new URL(permaLink, 'https://www.jiosaavn.com');
+    }
+    catch {
+        return undefined;
+    }
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length < 2)
+        return undefined;
+    const token = segments.at(-1);
+    if (!token)
+        return undefined;
+    const root = segments[0] === 's' ? segments[1] : segments[0];
+    switch (root) {
+        case 'song':
+            return { type: 'song', token };
+        case 'album':
+            return { type: 'album', token };
+        case 'artist':
+            return { type: 'artist', token };
+        case 'label':
+            return { type: 'label', token };
+        case 'playlist':
+        case 'featured':
+            return { type: 'playlist', token };
+        case 'show':
+            return { type: 'show', token };
+        default:
+            return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { ArtistModule as Artist } from './core/modules/artist.module';
+export { AlbumModule as Album } from './core/modules/album.module';
+export { SongModule as Song } from './core/modules/song.module';
+export { PlaylistModule as Playlist } from './core/modules/playlist.module';
+export { ExtrasModule as Extras } from './core/modules/extras.module';
+export { SDKError } from './helpers/errors';
+export type { SDKErrorCode } from './helpers/errors';
+export * from './core/models';
+export { schemas, type Schemas } from './schemas';
+export type { EntityType, ClientConfig, Image, SaavnPermalinkToken, } from './types';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { ArtistModule as Artist } from './core/modules/artist.module';
+export { AlbumModule as Album } from './core/modules/album.module';
+export { SongModule as Song } from './core/modules/song.module';
+export { PlaylistModule as Playlist } from './core/modules/playlist.module';
+export { ExtrasModule as Extras } from './core/modules/extras.module';
+export { SDKError } from './helpers/errors';
+export * from './core/models';
+export { schemas } from './schemas';

package/dist/saavn/common-mapper.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import type { Image } from '../types';
+import type { Album, Artist, Playlist, Song } from '../core/models';
+import type { SaavnArtistBase } from '../saavn/entities/base';
+import type { SaavnAlbumEntity, SaavnArtistEntity, SaavnPlaylistEntity, SaavnSongEntity } from '../saavn/entities';
+import type { SaavnAlbumEdgeCase, SaavnPlaylistEdgeCase } from '../saavn/entities/extras';
+export declare function parseImageUrls(imageUrl?: string): Image[];
+export declare function mapArtistBase(artist: z.infer<typeof SaavnArtistBase>): Artist;
+export declare function mapAlbumEdgeCase(data: z.infer<typeof SaavnAlbumEdgeCase>): Album;
+export declare function mapAlbum(data: z.infer<typeof SaavnAlbumEntity>): Album;
+export declare function mapArtist(data: z.infer<typeof SaavnArtistEntity>): Artist;
+export declare function mapPlaylistEdgeCase(data: z.infer<typeof SaavnPlaylistEdgeCase>): Playlist;
+export declare function mapPlaylist(data: z.infer<typeof SaavnPlaylistEntity>): Playlist;
+export declare function mapSong(song: z.infer<typeof SaavnSongEntity>): Song;
+export declare function mapSearchAllBase(item: any): {
+    id: any;
+    type: "song";
+    title: any;
+    subtitle: any;
+    description: any;
+    url: any;
+    images: Image[];
+    flags: {
+        isExplicit: boolean;
+        isRadioPresent?: undefined;
+    };
+    name?: undefined;
+} | {
+    id: any;
+    type: "album";
+    title: any;
+    subtitle: any;
+    description: any;
+    url: any;
+    images: Image[];
+    flags: {
+        isExplicit: boolean;
+        isRadioPresent?: undefined;
+    };
+    name?: undefined;
+} | {
+    id: any;
+    type: "artist";
+    name: any;
+    url: any;
+    images: Image[];
+    flags: {
+        isRadioPresent: any;
+        isExplicit?: undefined;
+    };
+    title?: undefined;
+    subtitle?: undefined;
+    description?: undefined;
+} | {
+    id: any;
+    type: "playlist";
+    title: any;
+    subtitle: any;
+    description: any;
+    url: any;
+    images: Image[];
+    flags: {
+        isExplicit: boolean;
+        isRadioPresent?: undefined;
+    };
+    name?: undefined;
+} | {
+    id: any;
+    type: "show";
+    title: any;
+    subtitle: any;
+    description: any;
+    url: any;
+    images: Image[];
+    flags?: undefined;
+    name?: undefined;
+} | null;

package/dist/saavn/common-mapper.js

@@ -0,0 +1,348 @@
+import { z } from 'zod';
+export function parseImageUrls(imageUrl) {
+    if (!imageUrl)
+        return [];
+    const resolutions = [
+        '50x50',
+        '150x150',
+        '500x500',
+    ];
+    return resolutions.map((resolution) => ({
+        url: imageUrl.replace(/150x150/, resolution),
+        resolution,
+    }));
+}
+export function mapArtistBase(artist) {
+    return {
+        id: artist.id,
+        type: 'artist',
+        name: artist.name,
+        url: artist.perma_url,
+        images: parseImageUrls(artist.image),
+    };
+}
+function parseBio(bio) {
+    if (typeof bio !== 'string')
+        return undefined;
+    const trimmed = bio.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!Array.isArray(parsed))
+            return undefined;
+        const items = parsed
+            .map((item) => {
+            if (!item || typeof item !== 'object')
+                return null;
+            const text = typeof item.text === 'string' && item.text.trim()
+                ? item.text.trim()
+                : null;
+            if (!text)
+                return null;
+            const title = typeof item.title === 'string' && item.title.trim()
+                ? item.title.trim()
+                : undefined;
+            const sequence = typeof item.sequence === 'number' ? item.sequence : undefined;
+            return { text, title, sequence };
+        })
+            .filter((x) => x !== null);
+        return items.length > 0 ? items : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function mapAlbumEdgeCase(data) {
+    return {
+        id: data.id,
+        type: 'album',
+        title: data.title,
+        subtitle: data.subtitle,
+        description: data.header_desc,
+        url: data.perma_url,
+        images: parseImageUrls(data.image),
+        language: data.language,
+        year: parseInt(data.year, 10),
+        stats: {
+            playCount: parseInt(data.play_count, 10),
+            songCount: data.more_info?.song_count
+                ? parseInt(data.more_info.song_count, 10)
+                : undefined,
+        },
+        flags: {
+            isExplicit: data.explicit_content === '1',
+        },
+        artists: {
+            primary: data.more_info?.artistMap?.primary_artists?.map(mapArtistBase),
+            featured: data.more_info?.artistMap?.featured_artists?.map(mapArtistBase),
+            all: data.more_info?.artistMap?.artists?.map(mapArtistBase),
+        },
+    };
+}
+export function mapAlbum(data) {
+    return {
+        id: data.id,
+        type: 'album',
+        title: data.title,
+        subtitle: data.subtitle,
+        description: data.header_desc,
+        url: data.perma_url,
+        images: parseImageUrls(data.image),
+        language: data.language,
+        year: parseInt(data.year, 10),
+        stats: {
+            playCount: parseInt(data.play_count, 10),
+            songCount: parseInt(data.more_info.song_count, 10),
+        },
+        flags: {
+            isExplicit: data.explicit_content === '1',
+            isDolby: data.more_info.is_dolby_content,
+        },
+        artists: {
+            primary: data.more_info.artistMap.primary_artists?.map(mapArtistBase),
+            featured: data.more_info.artistMap.featured_artists?.map(mapArtistBase),
+            all: data.more_info.artistMap.artists?.map(mapArtistBase),
+        },
+        songs: data.list?.map(mapSong),
+        meta: {
+            copyright: data.more_info?.copyright_text,
+            labelUrl: data.more_info?.label_url,
+        },
+    };
+}
+export function mapArtist(data) {
+    return {
+        id: data.artistId,
+        type: 'artist',
+        name: data.name,
+        subtitle: data.subtitle,
+        url: data.wiki ? data.wiki : '',
+        images: parseImageUrls(data.image),
+        stats: {
+            followerCount: data.follower_count
+                ? parseInt(data.follower_count, 10)
+                : undefined,
+            fanCount: data.fan_count ? parseInt(data.fan_count, 10) : undefined,
+        },
+        flags: {
+            isVerified: data.isVerified,
+            isRadioPresent: data.isRadioPresent,
+        },
+        language: {
+            primary: data.dominantLanguage,
+            available: data.availableLanguages,
+        },
+        profile: {
+            bio: parseBio(data.bio),
+            dob: data.dob || undefined,
+        },
+        links: {
+            saavn: {
+                overview: data.urls?.overview,
+                albums: data.urls?.albums,
+                songs: data.urls?.songs,
+                bio: data.urls?.bio,
+                comments: data.urls?.comments,
+            },
+            social: {
+                wiki: data.wiki || undefined,
+                facebook: data.fb || undefined,
+                twitter: data.twitter || undefined,
+            },
+        },
+        songs: {
+            top: data.topSongs?.map(mapSong),
+        },
+        albums: {
+            top: data.topAlbums?.map(mapAlbumEdgeCase),
+            singles: data.singles?.map(mapAlbumEdgeCase),
+            latest: data.latest_release?.map((album) => mapAlbumEdgeCase(album)),
+        },
+        playlists: {
+            dedicated: data.dedicated_artist_playlist?.map(mapPlaylistEdgeCase),
+            featured: data.featured_artist_playlist?.map(mapPlaylistEdgeCase),
+        },
+    };
+}
+export function mapPlaylistEdgeCase(data) {
+    return {
+        id: data.id,
+        type: 'playlist',
+        title: data.title,
+        subtitle: data.subtitle,
+        url: data.perma_url,
+        images: parseImageUrls(data.image),
+        stats: {
+            followerCount: data.more_info?.follower_count
+                ? parseInt(data.more_info.follower_count, 10)
+                : undefined,
+            fanCount: data.more_info?.fan_count
+                ? parseInt(data.more_info.fan_count, 10)
+                : undefined,
+        },
+        flags: {
+            isExplicit: data.explicit_content === '1',
+            isDolby: data.more_info?.is_dolby_content ?? undefined,
+        },
+        meta: {
+            language: data.more_info?.language,
+        },
+    };
+}
+export function mapPlaylist(data) {
+    return {
+        id: data.id,
+        type: 'playlist',
+        title: data.title,
+        subtitle: data.subtitle,
+        description: data.header_desc,
+        url: data.perma_url,
+        images: parseImageUrls(data.image),
+        stats: {
+            songCount: data.list_count ? parseInt(data.list_count, 10) : undefined,
+            followerCount: data.more_info?.follower_count
+                ? parseInt(data.more_info.follower_count, 10)
+                : undefined,
+            fanCount: data.more_info?.fan_count
+                ? parseInt(data.more_info.fan_count, 10)
+                : undefined,
+        },
+        flags: {
+            isExplicit: data.explicit_content === '1',
+            isDolby: data.more_info?.is_dolby_content,
+            isFollowed: data.more_info?.is_followed === 'true',
+        },
+        songs: data.list?.map(mapSong),
+        artists: data.more_info?.artists?.map(mapArtistBase),
+        owner: {
+            id: data.more_info?.uid,
+            name: [data.more_info?.firstname, data.more_info?.lastname]
+                .filter(Boolean)
+                .join(' ') || undefined,
+        },
+        meta: {
+            playlistType: data.more_info?.playlist_type,
+            language: data.language,
+            lastUpdated: data.more_info?.last_updated
+                ? parseInt(data.more_info.last_updated, 10)
+                : undefined,
+        },
+    };
+}
+export function mapSong(song) {
+    return {
+        id: song.id,
+        type: 'song',
+        title: song.title,
+        subtitle: song.subtitle,
+        url: song.perma_url,
+        images: parseImageUrls(song.image),
+        album: {
+            id: song.more_info?.album_id,
+            title: song.more_info?.album,
+            url: song.more_info?.album_url,
+        },
+        artists: {
+            primary: song.more_info.artistMap.primary_artists?.map(mapArtistBase),
+            featured: song.more_info.artistMap.featured_artists?.map(mapArtistBase),
+            all: song.more_info.artistMap.artists?.map(mapArtistBase),
+        },
+        duration: parseInt(song.more_info.duration, 10),
+        language: song.language,
+        year: parseInt(song.year, 10),
+        stats: {
+            playCount: typeof song.play_count === 'string'
+                ? parseInt(song.play_count, 10)
+                : song.play_count,
+        },
+        flags: {
+            isExplicit: song.explicit_content === '1',
+            hasLyrics: song.more_info?.has_lyrics === 'true',
+            isDolby: song.more_info.is_dolby_content,
+        },
+        lyrics: {
+            id: song.more_info?.lyrics_id,
+            snippet: song.more_info?.lyrics_snippet,
+        },
+        media: {
+            encryptedUrl: song.more_info?.encrypted_media_url,
+            previewUrl: song.more_info?.vlink,
+        },
+        meta: {
+            copyright: song.more_info?.copyright_text,
+            label: {
+                id: song.more_info?.label_id || undefined,
+                name: song.more_info?.label,
+                url: song.more_info?.label_url,
+            },
+            releaseDate: song.more_info?.release_date || undefined,
+        },
+    };
+}
+export function mapSearchAllBase(item) {
+    switch (item.type) {
+        case 'song':
+            return {
+                id: item.id,
+                type: 'song',
+                title: item.title,
+                subtitle: item.subtitle,
+                description: item.description,
+                url: item.perma_url,
+                images: parseImageUrls(item.image),
+                flags: {
+                    isExplicit: item.explicit_content === '1',
+                },
+            };
+        case 'album':
+            return {
+                id: item.id,
+                type: 'album',
+                title: item.title,
+                subtitle: item.subtitle,
+                description: item.description,
+                url: item.perma_url,
+                images: parseImageUrls(item.image),
+                flags: {
+                    isExplicit: item.explicit_content === '1',
+                },
+            };
+        case 'artist':
+            return {
+                id: item.id,
+                type: 'artist',
+                name: item.title,
+                url: item.perma_url,
+                images: parseImageUrls(item.image),
+                flags: {
+                    isRadioPresent: item.isRadioPresent,
+                },
+            };
+        case 'playlist':
+            return {
+                id: item.id,
+                type: 'playlist',
+                title: item.title,
+                subtitle: item.subtitle,
+                description: item.description,
+                url: item.perma_url,
+                images: parseImageUrls(item.image),
+                flags: {
+                    isExplicit: item.explicit_content === '1',
+                },
+            };
+        case 'show':
+            return {
+                id: item.id,
+                type: 'show',
+                title: item.title,
+                subtitle: item.subtitle,
+                description: item.description,
+                url: item.perma_url,
+                images: parseImageUrls(item.image),
+            };
+        default:
+            return null;
+    }
+}

package/dist/saavn/entities/album.entity.d.ts

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+export declare const SaavnAlbumEntity: z.ZodLazy<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodString;
+    type: z.ZodLiteral<"album">;
+    image: z.ZodString;
+    perma_url: z.ZodString;
+    explicit_content: z.ZodString;
+    header_desc: z.ZodString;
+    play_count: z.ZodString;
+    language: z.ZodString;
+    year: z.ZodString;
+    list_count: z.ZodString;
+    list_type: z.ZodLiteral<"song">;
+    list: z.ZodArray<z.ZodLazy<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        subtitle: z.ZodString;
+        type: z.ZodLiteral<"song">;
+        perma_url: z.ZodString;
+        image: z.ZodString;
+        explicit_content: z.ZodString;
+        header_desc: z.ZodString;
+        language: z.ZodString;
+        year: z.ZodString;
+        play_count: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        more_info: z.ZodObject<{
+            music: z.ZodString;
+            album_id: z.ZodString;
+            album: z.ZodString;
+            label: z.ZodString;
+            label_id: z.ZodNullable<z.ZodString>;
+            origin: z.ZodString;
+            is_dolby_content: z.ZodBoolean;
+            encrypted_media_url: z.ZodString;
+            encrypted_drm_media_url: z.ZodString;
+            album_url: z.ZodString;
+            duration: z.ZodString;
+            has_lyrics: z.ZodString;
+            lyrics_snippet: z.ZodString;
+            lyrics_id: z.ZodOptional<z.ZodString>;
+            copyright_text: z.ZodString;
+            release_date: z.ZodNullable<z.ZodString>;
+            label_url: z.ZodOptional<z.ZodString>;
+            vcode: z.ZodOptional<z.ZodString>;
+            vlink: z.ZodOptional<z.ZodString>;
+            artistMap: z.ZodLazy<z.ZodObject<{
+                primary_artists: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                    role: z.ZodString;
+                    image: z.ZodString;
+                    type: z.ZodLiteral<"artist">;
+                    perma_url: z.ZodString;
+                }, z.core.$loose>>;
+                featured_artists: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                    role: z.ZodString;
+                    image: z.ZodString;
+                    type: z.ZodLiteral<"artist">;
+                    perma_url: z.ZodString;
+                }, z.core.$loose>>;
+                artists: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                    role: z.ZodString;
+                    image: z.ZodString;
+                    type: z.ZodLiteral<"artist">;
+                    perma_url: z.ZodString;
+                }, z.core.$loose>>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>;
+    }, z.core.$loose>>>;
+    more_info: z.ZodObject<{
+        song_count: z.ZodString;
+        copyright_text: z.ZodString;
+        is_dolby_content: z.ZodBoolean;
+        label_url: z.ZodString;
+        artistMap: z.ZodObject<{
+            primary_artists: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                role: z.ZodString;
+                image: z.ZodString;
+                type: z.ZodLiteral<"artist">;
+                perma_url: z.ZodString;
+            }, z.core.$loose>>;
+            featured_artists: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                role: z.ZodString;
+                image: z.ZodString;
+                type: z.ZodLiteral<"artist">;
+                perma_url: z.ZodString;
+            }, z.core.$loose>>;
+            artists: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                role: z.ZodString;
+                image: z.ZodString;
+                type: z.ZodLiteral<"artist">;
+                perma_url: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+}, z.core.$loose>>;
+export declare const SaavnTrendingAlbum: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    subtitle: z.ZodString;
+    header_desc: z.ZodString;
+    perma_url: z.ZodString;
+    image: z.ZodString;
+    language: z.ZodString;
+    year: z.ZodString;
+    play_count: z.ZodString;
+    explicit_content: z.ZodString;
+    type: z.ZodLiteral<"album">;
+    more_info: z.ZodObject<{
+        release_date: z.ZodString;
+        song_count: z.ZodString;
+        artistMap: z.ZodObject<{
+            primary_artists: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                role: z.ZodString;
+                image: z.ZodString;
+                type: z.ZodLiteral<"artist">;
+                perma_url: z.ZodString;
+            }, z.core.$loose>>;
+            featured_artists: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                role: z.ZodString;
+                image: z.ZodString;
+                type: z.ZodLiteral<"artist">;
+                perma_url: z.ZodString;
+            }, z.core.$loose>>;
+            artists: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                name: z.ZodString;
+                role: z.ZodString;
+                image: z.ZodString;
+                type: z.ZodLiteral<"artist">;
+                perma_url: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+}, z.core.$loose>;

package/dist/saavn/entities/album.entity.js

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import { SaavnAlbumBase, SaavnArtistMap, SaavnTrendingBase } from './base';
+import { SaavnSongEntity } from './song.entity';
+export const SaavnAlbumEntity = z.lazy(() => SaavnAlbumBase.extend({
+    language: z.string(),
+    year: z.string(),
+    list_count: z.string(),
+    list_type: z.literal('song'),
+    list: z.array(z.lazy(() => SaavnSongEntity)),
+    more_info: z.looseObject({
+        song_count: z.string(),
+        copyright_text: z.string(),
+        is_dolby_content: z.boolean(),
+        label_url: z.string(),
+        artistMap: SaavnArtistMap,
+    }),
+}));
+export const SaavnTrendingAlbum = SaavnTrendingBase.extend({
+    type: z.literal('album'),
+    more_info: z.looseObject({
+        release_date: z.string(),
+        song_count: z.string(),
+        artistMap: SaavnArtistMap,
+    }),
+});