@song-spotlight/api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nexpid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @song-spotlight/api
+
+[Song Spotlight](https://github.com/nexpid-labs/SongSpotlight) API types and song validation module
+
+## How to use
+
+TODO!!!
+
+## Development
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To build:
+
+```bash
+bun run build
+```
+
+To publish:
+
+```bash
+bun run publish
+```
+
+This project was created using `bun init` in bun v1.2.20. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/dist/core-CLy9m0H1.js

@@ -0,0 +1,480 @@
+//#region package.json
+var version = "0.1.0";
+
+//#endregion
+//#region src/handlers/common.ts
+function clean(link) {
+	const url = new URL(link);
+	url.protocol = "https";
+	url.username = url.password = url.port = url.search = url.hash = "";
+	return url.toString().replace(/\/?$/, "/");
+}
+async function request(options) {
+	if (options.body) {
+		const body = JSON.stringify(options.body);
+		options.body = body;
+		options.headers ??= {};
+		options.headers["content-type"] ??= "application/json";
+		options.headers["content-length"] ??= String(body.length);
+	}
+	const url = new URL(options.url);
+	for (const [key, value] of Object.entries(options.query ?? {})) url.searchParams.set(key, value);
+	const res = await fetch(url, {
+		method: options.method,
+		cache: "force-cache",
+		redirect: "follow",
+		headers: {
+			"accept": "*/*",
+			"user-agent": `song-spotlight/v${version}`,
+			"cache-control": "public, max-age=3600",
+			...options.headers
+		},
+		body: options.body
+	});
+	const text = await res.text();
+	let json;
+	try {
+		json = JSON.parse(text);
+	} catch {
+		json = null;
+	}
+	return {
+		ok: res.ok,
+		redirected: res.redirected,
+		url: res.url,
+		status: res.status,
+		headers: res.headers,
+		text,
+		json
+	};
+}
+function parseNextData(html) {
+	const data = html.match(/id="__NEXT_DATA__" type="application\/json">(.*?)<\/script>/)?.[1];
+	if (!data) return void 0;
+	try {
+		return JSON.parse(data);
+	} catch {
+		return void 0;
+	}
+}
+const PLAYLIST_LIMIT = 15;
+
+//#endregion
+//#region src/handlers/finders.ts
+const $ = {
+	services: [],
+	parsers: []
+};
+function sid(song) {
+	return [
+		song.service,
+		song.type,
+		song.id
+	].join(":");
+}
+const parseCache = /* @__PURE__ */ new Map();
+const linkCache = /* @__PURE__ */ new Map();
+async function parseLink(link) {
+	const cleaned = clean(link);
+	if (parseCache.has(cleaned)) return parseCache.get(cleaned);
+	const { hostname, pathname } = new URL(cleaned);
+	const path = pathname.slice(1).split(/\/+/);
+	let song = null;
+	for (const parser of $.parsers) if (parser.hosts.includes(hostname)) {
+		song = await parser.parse(cleaned, hostname, path);
+		if (song) break;
+	}
+	parseCache.set(cleaned, song);
+	if (song) linkCache.set(sid(song), cleaned);
+	return song;
+}
+const renderCache = /* @__PURE__ */ new Map();
+async function renderSong(song) {
+	const id = sid(song);
+	if (renderCache.has(id)) return renderCache.get(id);
+	let info = null;
+	const service = $.services.find((x) => x.name === song.service);
+	if (service?.types.includes(song.type)) info = await service.render(song.type, song.id);
+	renderCache.set(id, info);
+	return info;
+}
+async function toLink(song) {
+	const id = sid(song);
+	if (linkCache.has(id)) return linkCache.get(id);
+	let link = null;
+	const service = $.services.find((x) => x.name === song.service);
+	if (service?.types.includes(song.type)) link = await service.from(song.type, song.id);
+	const cleaned = link ? clean(link) : link;
+	linkCache.set(id, cleaned);
+	if (cleaned) parseCache.set(cleaned, {
+		service: song.service,
+		type: song.type,
+		id: song.id
+	});
+	return link;
+}
+
+//#endregion
+//#region src/handlers/defs/parsers/songdotlink.ts
+const songdotlink = {
+	hosts: [
+		"song.link",
+		"album.link",
+		"artist.link",
+		"pods.link",
+		"playlist.link",
+		"mylink.page",
+		"odesli.co"
+	],
+	async parse(link, _host, path) {
+		const [first, second, third] = path;
+		if (!first || third) return null;
+		if (second && Number.isNaN(+second)) return null;
+		else if (!second && (!first.match(/^[A-z0-9-_]+$/) || first.match(/^[-_]/) || first.match(/[-_]$/))) return null;
+		const html = (await request({ url: link })).text;
+		const sections = parseNextData(html)?.props?.pageProps?.pageData?.sections;
+		if (!sections) return null;
+		const links = sections.flatMap((x) => x.links ?? []).filter((x) => x.url && x.platform);
+		const valid = links.find((x) => x.platform === "spotify") ?? links.find((x) => x.platform === "soundcloud") ?? links.find((x) => x.platform === "appleMusic");
+		if (!valid) return null;
+		return await parseLink(valid.url);
+	}
+};
+
+//#endregion
+//#region src/handlers/defs/cache.ts
+const handlerCache = /* @__PURE__ */ new Map();
+function makeCache(name, retrieve) {
+	return { retrieve(...args) {
+		if (handlerCache.has(name)) return handlerCache.get(name);
+		const res = retrieve(...args);
+		if (res instanceof Promise) return res.then((ret) => {
+			handlerCache.set(name, ret);
+			return ret;
+		});
+		else {
+			handlerCache.set(name, res);
+			return res;
+		}
+	} };
+}
+
+//#endregion
+//#region src/handlers/defs/services/applemusic.ts
+const geo = "fr", defaultName = "songspotlight";
+const applemusicToken = makeCache("applemusicToken", async (html) => {
+	html ??= (await request({ url: `https://music.apple.com/${geo}/new` })).text;
+	const asset = html.match(/src="(\/assets\/index-\w+\.js)"/i)?.[1];
+	if (!asset) return;
+	const js = (await request({ url: `https://music.apple.com${asset}` })).text;
+	const code = js.match(/\w+="(ey.*?)"/i)?.[1];
+	return code;
+});
+const applemusic = {
+	name: "applemusic",
+	hosts: ["music.apple.com", "geo.music.apple.com"],
+	types: [
+		"artist",
+		"album",
+		"playlist",
+		"song"
+	],
+	async parse(_link, _host, path) {
+		const [country, type, name, id, fourth] = path;
+		if (!country || !type || !this.types.includes(type) || !name || !id || fourth) return null;
+		const res = await request({ url: `https://music.apple.com/${geo}/${type}/${defaultName}/${id}` });
+		if (res.status !== 200) return null;
+		await applemusicToken.retrieve(res.text);
+		return {
+			service: this.name,
+			type,
+			id
+		};
+	},
+	async render(type, id) {
+		const token = await applemusicToken.retrieve();
+		if (!token) return null;
+		const res = await request({
+			url: `https://amp-api.music.apple.com/v1/catalog/${geo}/${type}s/${id}?include=songs`,
+			headers: {
+				authorization: `Bearer ${token}`,
+				origin: "https://music.apple.com"
+			}
+		});
+		if (res.status !== 200) return null;
+		const { attributes, relationships } = res.json.data[0];
+		const base = {
+			label: attributes.name,
+			sublabel: attributes.artistName ?? "Top Songs",
+			explicit: attributes.contentRating === "explicit"
+		};
+		const thumbnailUrl = attributes.artwork?.url?.replace("{w}", "128")?.replace("{h}", "128");
+		if (type === "song") {
+			const duration = attributes.durationInMillis, previewUrl = attributes.previews?.[0]?.url;
+			return {
+				...base,
+				form: "single",
+				thumbnailUrl,
+				single: {
+					audio: previewUrl && duration ? {
+						previewUrl,
+						duration
+					} : void 0,
+					link: attributes.url
+				}
+			};
+		}
+		const songs = (relationships.songs ?? relationships.tracks)?.data;
+		if (!songs) return null;
+		return {
+			...base,
+			form: "list",
+			thumbnailUrl,
+			list: songs.slice(0, PLAYLIST_LIMIT).map(({ attributes: song }) => {
+				const duration = song.durationInMillis, previewUrl = song.previews?.[0]?.url;
+				return {
+					label: song.name,
+					sublabel: song.artistName,
+					explicit: song.contentRating === "explicit",
+					audio: previewUrl && duration ? {
+						previewUrl,
+						duration
+					} : void 0,
+					link: song.url
+				};
+			})
+		};
+	},
+	from(type, id) {
+		return `https://music.apple.com/us/${type}/${defaultName}/${id}`;
+	}
+};
+
+//#endregion
+//#region src/handlers/defs/services/soundcloud.ts
+const client_id = "nIjtjiYnjkOhMyh5xrbqEW12DxeJVnic";
+async function parseWidget(type, id, tracks) {
+	return (await request({
+		url: `https://api-widget.soundcloud.com/${type}s/${id}${tracks ? "/tracks?limit=20" : ""}`,
+		query: {
+			client_id,
+			app_version: "1752674865",
+			format: "json",
+			representation: "full"
+		}
+	})).json;
+}
+async function parsePreview(transcodings) {
+	const preview = transcodings.sort((a, b) => {
+		const isA = a.format.protocol === "progressive";
+		const isB = b.format.protocol === "progressive";
+		return isA && !isB ? -1 : isB && !isA ? 1 : 0;
+	})?.[0];
+	if (preview?.url && preview?.duration) {
+		const link = (await request({
+			url: preview.url,
+			query: { client_id }
+		})).json;
+		if (!link?.url) return;
+		return {
+			duration: preview.duration,
+			previewUrl: link.url
+		};
+	}
+}
+const soundcloud = {
+	name: "soundcloud",
+	hosts: [
+		"soundcloud.com",
+		"m.soundcloud.com",
+		"on.soundcloud.com"
+	],
+	types: [
+		"user",
+		"track",
+		"playlist"
+	],
+	async parse(link, host, path) {
+		if (host === "on.soundcloud.com") {
+			if (!path[0] || path[1]) return null;
+			const { url, status } = await request({ url: link.slice(0, -1) });
+			return status === 200 ? await parseLink(url) : null;
+		} else {
+			const [user, second, track, fourth] = path;
+			let valid = false;
+			if (user && !second) valid = true;
+			else if (user && second && second !== "sets" && !track) valid = true;
+			else if (user && second === "sets" && track && !fourth) valid = true;
+			if (!valid) return null;
+			const data = (await request({
+				url: "https://soundcloud.com/oembed",
+				query: {
+					format: "json",
+					url: link.slice(0, -1)
+				}
+			})).json;
+			if (!data?.html) return null;
+			const rawUrl = data.html.match(/w\.soundcloud\.com.*?url=(.*?)[&"]/)?.[1];
+			if (!rawUrl) return null;
+			const splits = decodeURIComponent(rawUrl).split(/\/+/);
+			const kind = splits[2], id = splits[3];
+			if (!kind || !id) return null;
+			return {
+				service: this.name,
+				type: kind.slice(0, -1),
+				id
+			};
+		}
+	},
+	async render(type, id) {
+		const data = await parseWidget(type, id, false);
+		if (!data.id) return null;
+		const base = {
+			label: data.title ?? data.username,
+			sublabel: data.user?.username ?? "Top tracks",
+			explicit: Boolean(data.publisher_metadata?.explicit)
+		};
+		const thumbnailUrl = data.artwork_url ?? data.avatar_url;
+		if (type === "track") {
+			const audio = await parsePreview(data.media?.transcodings ?? []);
+			return {
+				...base,
+				form: "single",
+				thumbnailUrl,
+				single: {
+					audio,
+					link: data.permalink_url
+				}
+			};
+		}
+		let tracks = [];
+		if (type === "user") {
+			const got = await parseWidget(type, id, true);
+			if (!got.collection) return null;
+			tracks = got.collection;
+		} else {
+			if (!data.tracks) return null;
+			tracks = data.tracks;
+		}
+		const list = [];
+		for (const track of tracks) {
+			if (!track.title || list.length >= PLAYLIST_LIMIT) continue;
+			const audio = await parsePreview(track.media?.transcodings ?? []);
+			list.push({
+				label: track.title,
+				sublabel: track.user?.username ?? "IDKK",
+				explicit: Boolean(track.publisher_metadata.explicit),
+				audio,
+				link: track.permalink_url
+			});
+		}
+		return {
+			...base,
+			form: "list",
+			thumbnailUrl,
+			list
+		};
+	},
+	async from(type, id) {
+		const data = await parseWidget(type, id, false);
+		if (!data.id) return null;
+		return data.permalink_url;
+	}
+};
+
+//#endregion
+//#region src/handlers/defs/services/spotify.ts
+async function parseEmbed(type, id) {
+	return parseNextData((await request({ url: `https://open.spotify.com/embed/${type}/${id}` })).text);
+}
+function from(type, id) {
+	return `https://open.spotify.com/${type}/${id}`;
+}
+function fromUri(uri) {
+	const [sanityCheck, type, id] = uri.split(":");
+	if (sanityCheck === "spotify" && type && id) return from(type, id);
+	else return null;
+}
+const spotify = {
+	name: "spotify",
+	hosts: ["open.spotify.com"],
+	types: [
+		"track",
+		"album",
+		"playlist",
+		"artist"
+	],
+	async parse(_link, _host, path) {
+		const [type, id, third] = path;
+		if (!type || !this.types.includes(type) || !id || third) return null;
+		const title = (await parseEmbed(type, id))?.props?.pageProps?.title;
+		if (title) return null;
+		return {
+			service: this.name,
+			type,
+			id
+		};
+	},
+	async render(type, id) {
+		const data = (await parseEmbed(type, id))?.props?.pageProps?.state?.data?.entity;
+		if (!data) return null;
+		const base = {
+			label: data.title,
+			sublabel: data.subtitle ?? data.artists?.map((x) => x.name).join(", "),
+			explicit: Boolean(data.isExplicit)
+		};
+		const thumbnailUrl = data.visualIdentity.image.sort((a, b) => a.maxWidth - b.maxWidth)[0]?.url;
+		if (type === "track") {
+			const link = fromUri(data.uri);
+			return {
+				...base,
+				form: "single",
+				thumbnailUrl,
+				single: {
+					audio: data.audioPreview && data.duration ? {
+						duration: data.duration,
+						previewUrl: data.audioPreview.url
+					} : void 0,
+					link
+				}
+			};
+		} else {
+			const list = [];
+			for (const track of data.trackList ?? []) {
+				if (list.length >= PLAYLIST_LIMIT) continue;
+				const link = fromUri(track.uri);
+				list.push({
+					label: track.title,
+					sublabel: track.subtitle ?? track.artists?.map((x) => x.name).join(", "),
+					explicit: Boolean(track.isExplicit),
+					audio: track.audioPreview && track.duration ? {
+						duration: track.duration,
+						previewUrl: track.audioPreview.url
+					} : void 0,
+					link
+				});
+			}
+			return {
+				...base,
+				form: "list",
+				thumbnailUrl,
+				list
+			};
+		}
+	},
+	from
+};
+
+//#endregion
+//#region src/handlers/core.ts
+const services = [
+	spotify,
+	soundcloud,
+	applemusic
+];
+$.services = services;
+const parsers = [songdotlink, ...services];
+$.parsers = parsers;
+
+//#endregion
+export { $, parseLink, parsers, renderSong, services, toLink };

package/dist/handlers.d.ts

@@ -0,0 +1,55 @@
+import { Song } from "./types-Cp4kDlRH.js";
+import { MaybePromise } from "bun";
+
+//#region src/handlers/types.d.ts
+interface RenderInfoBase {
+  label: string;
+  sublabel: string;
+  explicit: boolean;
+}
+interface RenderInfoEntry {
+  audio?: {
+    duration: number;
+    previewUrl: string;
+  } | undefined;
+  link: string;
+}
+type RenderInfoEntryBased = RenderInfoEntry & RenderInfoBase;
+interface RenderSongSingle extends RenderInfoBase {
+  form: "single";
+  thumbnailUrl?: string;
+  single: RenderInfoEntry;
+}
+interface RenderSongList extends RenderInfoBase {
+  form: "list";
+  thumbnailUrl?: string;
+  list: RenderInfoEntryBased[];
+}
+type RenderSongInfo = RenderSongSingle | RenderSongList;
+//#endregion
+//#region src/handlers/helpers.d.ts
+interface SongParser {
+  hosts: string[];
+  parse(link: string, host: string, path: string[]): MaybePromise<Song | null>;
+}
+interface SongService extends SongParser {
+  name: string;
+  types: string[];
+  render(type: string, id: string): MaybePromise<RenderSongInfo | null>;
+  from(type: string, id: string): MaybePromise<string | null>;
+}
+//#endregion
+//#region src/handlers/core.d.ts
+declare const services: SongService[];
+declare const parsers: SongParser[];
+//#endregion
+//#region src/handlers/finders.d.ts
+declare const $: {
+  services: SongService[];
+  parsers: SongParser[];
+};
+declare function parseLink(link: string): Promise<Song | null>;
+declare function renderSong(song: Song): Promise<RenderSongInfo | null>;
+declare function toLink(song: Song): Promise<string | null>;
+//#endregion
+export { $, RenderInfoBase, RenderInfoEntry, RenderInfoEntryBased, RenderSongInfo, SongParser, SongService, parseLink, parsers, renderSong, services, toLink };

package/dist/handlers.js

@@ -0,0 +1,3 @@
+import { $, parseLink, parsers, renderSong, services, toLink } from "./core-CLy9m0H1.js";
+
+export { $, parseLink, parsers, renderSong, services, toLink };

package/dist/structs.d.ts

@@ -0,0 +1,13 @@
+import { Song, UserData } from "./types-Cp4kDlRH.js";
+import z, { ZodLiteral, ZodObject, ZodString, ZodUnion, core } from "zod";
+
+//#region src/structs/zod.d.ts
+type SongDef = ZodObject<{
+  service: ZodLiteral<string>;
+  type: ZodUnion<ZodLiteral<string>[]>;
+  id: ZodString;
+}, core.$strip>;
+declare const SongSchema: z.ZodDiscriminatedUnion<[SongDef], "service">;
+declare const UserDataSchema: z.ZodArray<z.ZodDiscriminatedUnion<[SongDef], "service">>;
+//#endregion
+export { Song, SongSchema, UserData, UserDataSchema };

package/dist/structs.js

@@ -0,0 +1,13 @@
+import { services } from "./core-CLy9m0H1.js";
+import z from "zod";
+
+//#region src/structs/zod.ts
+const SongSchema = z.discriminatedUnion("service", services.map((service) => z.object({
+	service: z.literal(service.name),
+	type: z.union(service.types.map((type) => z.literal(type))),
+	id: z.string()
+})));
+const UserDataSchema = z.array(SongSchema).max(6);
+
+//#endregion
+export { SongSchema, UserDataSchema };

package/dist/types-Cp4kDlRH.d.ts

@@ -0,0 +1,9 @@
+//#region src/structs/types.d.ts
+interface Song {
+  service: string;
+  type: string;
+  id: string;
+}
+type UserData = Song[];
+//#endregion
+export { Song, UserData };

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@song-spotlight/api",
+	"version": "0.1.0",
+	"description": "Song Spotlight API types and song validation module",
+	"type": "module",
+	"scripts": {
+		"build": "rm -rf dist && rolldown -c rolldown.config.mts",
+		"prepublishOnly": "bun run build"
+	},
+	"exports": {
+		"./handlers": {
+			"default": "./dist/handlers.js",
+			"types": "./dist/handlers.d.ts"
+		},
+		"./structs": {
+			"default": "./dist/structs.js",
+			"types": "./dist/structs.d.ts"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist"
+	],
+	"license": "MIT",
+	"homepage": "https://github.com/nexpid-labs/SongSpotlight/tree/main/packages/api",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nexpid-labs/SongSpotlight.git",
+		"directory": "packages/api"
+	},
+	"bugs": {
+		"url": "https://github.com/nexpid-labs/SongSpotlight/issues"
+	},
+	"dependencies": {
+		"zod": "^4.1.5"
+	},
+	"devDependencies": {
+		"@types/bun": "latest",
+		"rolldown": "^1.0.0-beta.34",
+		"rolldown-plugin-dts": "^0.15.10"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}