harmonyy 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+<div align='center'>
+    <h1>harmony</h1>
+    <h3>a keyless search tool for music streaming services</h3>
+</div>
+
+<br>
+
+```
+npm i harmonyy
+pnpm i harmonyy
+bun add harmonyy
+```
+
+each service lives in its own subpath and is the default export:
+
+```ts
+import Spotify from 'harmonyy/spotify';
+import AppleMusic from 'harmonyy/apple';
+import YoutubeMusic from 'harmonyy/youtube';
+```
+
+every service returns its own response structure, so results are not interchangeable between services. the response types are exported from the same subpath as the class; see `src/<service>/types.ts` for the full shapes.
+
+## /spotify
+
+```ts
+import Spotify from 'harmonyy/spotify';
+
+const spotify = new Spotify();
+
+const results = await spotify.search('daft punk', { limit: 5 });
+const popular = await spotify.getPopular();
+const album = await spotify.getAlbum('spotify:album:2noRn2Aes5aoNVsU6iWThc');
+const artist = await spotify.getArtist('spotify:artist:4tZwfgrHOc3mvqYlEYSvVi');
+```
+
+- `search(query, opts?)`
+- `getPopular(timezone?)`
+- `getAlbum(uri)`
+- `getArtist(uri)`
+
+`search` options: `offset`, `limit`, `numberOfTopResults`, `includeAudiobooks`, `includeArtistHasConcertsField`, `includePreReleases`, `includeLocalConcertsField`, `includeAuthors`. any other keys are passed through to spotify.
+
+`uri` is a full spotify uri (`spotify:album:...`, `spotify:artist:...`).
+
+## /apple
+
+```ts
+import AppleMusic from 'harmonyy/apple';
+
+const apple = new AppleMusic('us'); // optional: storefront, defaults to 'us'
+
+const results = await apple.search('daft punk');
+const artist = await apple.getArtist('5468295');
+const album = await apple.getAlbum('1440833098');
+```
+
+- `search(query)`
+- `getArtist(id)`
+- `getAlbum(id)`
+
+ids are the numeric ids from apple music urls.
+
+## /youtube
+
+```ts
+import YoutubeMusic from 'harmonyy/youtube';
+
+const youtube = new YoutubeMusic();
+
+const results = await youtube.search('daft punk');
+const album = await youtube.getAlbum('MPREb_...');
+const artist = await youtube.getArtist('UC...');
+```
+
+- `search(query)`
+- `getAlbum(browseId)`
+- `getArtist(browseId)`
+
+`browseId` is the youtube music browse id (`MPREb_...` for albums, `UC...` for artists).
+
+## App
+
+every service class implements at minimum the `App` interface (`src/App.ts`):
+
+```ts
+export interface App {
+    $getHeaders(): Promise<Record<string, string>>;
+
+    search(query: string): Promise<any>;
+    getPopular?(): Promise<any>;
+    getAlbum(uri: string): Promise<any>;
+    getArtist(uri: string): Promise<any>;
+    getTrack?(uri: string): Promise<any>;
+}
+```
+
+- `$getHeaders` builds the request headers (fetching tokens or cookies first if needed).
+- `search`, `getAlbum` and `getArtist` are implemented by every service.
+- `getPopular` and `getTrack` are optional and depend on whether the service supports it.
+
+<br><br>
+<h5 align='center'>made with ❤️</h5>

package/dist/App.d.ts

@@ -0,0 +1,8 @@
+export interface App {
+    $getHeaders(): Promise<Record<string, string>>;
+    search(query: string): Promise<any>;
+    getPopular?(): Promise<any>;
+    getAlbum(uri: string): Promise<any>;
+    getArtist(uri: string): Promise<any>;
+    getTrack?(uri: string): Promise<any>;
+}

package/dist/App.js

@@ -0,0 +1 @@
+export {};

package/dist/apple/index.d.ts

@@ -0,0 +1,13 @@
+import type { AlbumResponse, ArtistResponse, SearchResponse } from './types.js';
+import type { App } from '../App.js';
+export * from './types.js';
+export default class AppleMusic implements App {
+    authorization: string;
+    storefront: string;
+    constructor(storefront?: string);
+    getAuthorization(): Promise<void>;
+    $getHeaders(): Promise<Record<string, string>>;
+    search(query: string): Promise<SearchResponse>;
+    getArtist(uri: string): Promise<ArtistResponse>;
+    getAlbum(uri: string): Promise<AlbumResponse>;
+}

package/dist/apple/index.js

@@ -0,0 +1,97 @@
+export * from './types.js';
+export default class AppleMusic {
+    authorization;
+    storefront = 'us';
+    constructor(storefront = 'us') {
+        this.storefront = storefront;
+    }
+    async getAuthorization() {
+        const mainPageReq = await fetch(`https://music.apple.com/${this.storefront}/new`);
+        const mainPage = await mainPageReq.text();
+        const indexFileName = mainPage.match(/\<script type="module" crossorigin src="(.*?)"\>/)[1];
+        const indexFileReq = await fetch(`https://music.apple.com${indexFileName}`);
+        const indexFile = await indexFileReq.text();
+        this.authorization = indexFile.match(/="(eyJ.*?)"/)[1];
+    }
+    async $getHeaders() {
+        if (!this.authorization)
+            await this.getAuthorization();
+        return {
+            'Accept': '*/*',
+            'Accept-Encoding': 'gzip, deflate, br, zstd',
+            'Accept-Language': 'en-US,en;q=0.9',
+            'Authorization': `Bearer ${this.authorization}`,
+            'Cache-Control': 'no-cache',
+            'Cookie': 'geo=US',
+            'Origin': 'https://music.apple.com',
+            'Referer': 'https://music.apple.com/',
+            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36'
+        };
+    }
+    async search(query) {
+        const url = new URL(`https://amp-api-edge.music.apple.com/v1/catalog/${this.storefront}/search`);
+        url.searchParams.append('art[music-videos:url]', 'c');
+        url.searchParams.append('art[url]', 'f');
+        url.searchParams.append('extend', 'artistUrl');
+        url.searchParams.append('fields[albums]', 'artistName,artistUrl,artwork,contentRating,editorialArtwork,editorialNotes,name,playParams,releaseDate,url,trackCount');
+        url.searchParams.append('fields[artists]', 'url,name,artwork');
+        url.searchParams.append('format[resources]', 'map');
+        url.searchParams.append('include[albums]', 'artists');
+        url.searchParams.append('include[music-videos]', 'artists');
+        url.searchParams.append('include[songs]', 'artists');
+        url.searchParams.append('include[stations]', 'radio-show');
+        url.searchParams.append('l', 'en-US');
+        url.searchParams.append('limit', '21');
+        url.searchParams.append('omit[resource]', 'autos');
+        url.searchParams.append('platform', 'web');
+        url.searchParams.append('relate[albums]', 'artists');
+        url.searchParams.append('relate[songs]', 'albums');
+        url.searchParams.append('term', query);
+        url.searchParams.append('types', 'activities,albums,apple-curators,artists,curators,editorial-items,music-movies,music-videos,playlists,record-labels,songs,stations,tv-episodes,uploaded-videos');
+        url.searchParams.append('with', 'lyricHighlights,lyrics,naturalLanguage,serverBubbles,subtitles');
+        const searchReq = await fetch(url.toString(), { headers: await this.$getHeaders() });
+        const searchRes = await searchReq.json();
+        return searchRes;
+    }
+    async getArtist(uri) {
+        const url = new URL(`https://amp-api.music.apple.com/v1/catalog/${this.storefront}/artists/${uri}`);
+        url.searchParams.set('art[url]', 'c,f');
+        url.searchParams.set('extend', 'artistBio,bornOrFormed,editorialArtwork,editorialVideo,extendedAssetUrls,hero,isGroup,origin,plainEditorialNotes,seoDescription,seoTitle');
+        url.searchParams.set('extend[playlists]', 'trackCount');
+        url.searchParams.set('format[resources]', 'map');
+        url.searchParams.set('include', 'record-labels,artists,persons,bands');
+        url.searchParams.set('include[concerts]', 'venues');
+        url.searchParams.set('include[music-videos]', 'artists');
+        url.searchParams.set('include[songs]', 'artists,albums');
+        url.searchParams.set('l', 'en-US');
+        url.searchParams.set('limit[all-upcoming-concerts]', '8');
+        url.searchParams.set('limit[artists:top-songs]', '24');
+        url.searchParams.set('meta[albums:tracks]', 'popularity');
+        url.searchParams.set('omit[resource]', 'autos');
+        url.searchParams.set('platform', 'web');
+        url.searchParams.set('views', 'all-upcoming-concerts,appears-on-albums,compilation-albums,featured-albums,featured-on-albums,featured-release,full-albums,latest-release,live-albums,more-to-hear,more-to-see,music-videos,playlists,radio-shows,similar-artists,singles,top-songs');
+        const artistReq = await fetch(url.toString(), { headers: await this.$getHeaders() });
+        const artistRes = await artistReq.json();
+        return artistRes;
+    }
+    async getAlbum(uri) {
+        const url = new URL(`https://amp-api.music.apple.com/v1/catalog/${this.storefront}/albums/${uri}`);
+        url.searchParams.set('art[url]', 'f');
+        url.searchParams.set('extend', 'editorialArtwork,editorialVideo,extendedAssetUrls,offers,seoDescription,seoTitle');
+        url.searchParams.set('fields[artists]', 'name,url');
+        url.searchParams.set('fields[curators]', 'name');
+        url.searchParams.set('fields[record-labels]', 'name,url');
+        url.searchParams.set('format[resources]', 'map');
+        url.searchParams.set('include', 'record-labels,artists');
+        url.searchParams.set('include[music-videos]', 'artists');
+        url.searchParams.set('include[playlists]', 'curator');
+        url.searchParams.set('include[songs]', 'artists,composers,albums');
+        url.searchParams.set('l', 'en-US');
+        url.searchParams.set('meta[albums:tracks]', 'popularity');
+        url.searchParams.set('platform', 'web');
+        url.searchParams.set('views', 'appears-on,audio-extras,more-by-artist,other-versions,related-videos,video-extras,you-might-also-like');
+        const req = await fetch(url.toString(), { headers: await this.$getHeaders() });
+        const data = await req.json();
+        return data;
+    }
+}