inki-music-api 2.0.0

package/dist/lx-runtime.d.ts

@@ -0,0 +1,39 @@
+import type { RequestOptions, SourceInitData, SourceScriptMeta } from './types';
+import type { HttpClient } from './http-client';
+type Handler = (payload: unknown) => unknown | Promise<unknown>;
+export declare const EVENT_NAMES: {
+    readonly request: "request";
+    readonly inited: "inited";
+    readonly updateAlert: "updateAlert";
+};
+export declare class LxRuntime {
+    readonly lx: {
+        version: string;
+        env: string;
+        currentScriptInfo: SourceScriptMeta;
+        EVENT_NAMES: typeof EVENT_NAMES;
+        request: (url: string, options: RequestOptions | ((err: Error | null, resp?: unknown) => void), callback?: (err: Error | null, resp?: unknown) => void) => void;
+        on: (eventName: string, handler: Handler) => void;
+        send: (eventName: string, data: unknown) => void;
+        utils: {
+            buffer: {
+                from: typeof Buffer.from;
+                toString: (buf: Buffer, encoding?: BufferEncoding) => string;
+                concat: typeof Buffer.concat;
+            };
+            crypto: {
+                md5: (str: string) => string;
+                hmac: (algorithm: string, key: string, data: string) => string;
+            };
+        };
+    };
+    private handlers;
+    private initedData;
+    private initedResolver;
+    private initedPromise;
+    constructor(httpClient: HttpClient);
+    dispatch(eventName: string, payload: unknown): Promise<unknown>;
+    getInitedData(): SourceInitData;
+    waitForInited(timeout: number): Promise<SourceInitData>;
+}
+export {};

package/dist/lx-runtime.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LxRuntime = exports.EVENT_NAMES = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+exports.EVENT_NAMES = {
+    request: 'request',
+    inited: 'inited',
+    updateAlert: 'updateAlert',
+};
+class LxRuntime {
+    constructor(httpClient) {
+        this.handlers = {};
+        this.initedData = null;
+        this.initedResolver = null;
+        this.initedPromise = new Promise((resolve) => {
+            this.initedResolver = resolve;
+        });
+        this.lx = {
+            version: '1.1.0',
+            env: 'desktop',
+            currentScriptInfo: {},
+            EVENT_NAMES: exports.EVENT_NAMES,
+            request: (url, options, callback) => {
+                if (typeof options === 'function') {
+                    httpClient.request(url, options);
+                    return;
+                }
+                httpClient.request(url, options, callback);
+            },
+            on: (eventName, handler) => {
+                this.handlers[eventName] = handler;
+            },
+            send: (eventName, data) => {
+                if (eventName === exports.EVENT_NAMES.inited) {
+                    this.initedData = data;
+                    if (this.initedResolver)
+                        this.initedResolver(this.initedData);
+                }
+            },
+            utils: {
+                buffer: {
+                    from: Buffer.from,
+                    toString: (buf, encoding) => buf.toString(encoding),
+                    concat: Buffer.concat,
+                },
+                crypto: {
+                    md5: (str) => {
+                        return crypto_1.default.createHash('md5').update(str).digest('hex');
+                    },
+                    hmac: (algorithm, key, data) => {
+                        return crypto_1.default.createHmac(algorithm, key).update(data).digest('hex');
+                    },
+                },
+            },
+        };
+    }
+    async dispatch(eventName, payload) {
+        const handler = this.handlers[eventName];
+        if (!handler)
+            throw new Error(`[inki-music-api] 没有找到事件处理器: ${eventName}`);
+        return handler(payload);
+    }
+    getInitedData() {
+        return this.initedData;
+    }
+    waitForInited(timeout) {
+        if (this.initedData)
+            return Promise.resolve(this.initedData);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error('[inki-music-api] 源脚本未调用 send(EVENT_NAMES.inited, ...)，初始化失败')), timeout);
+            this.initedPromise
+                .then((data) => {
+                clearTimeout(timer);
+                resolve(data);
+            })
+                .catch((err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+}
+exports.LxRuntime = LxRuntime;

package/dist/memory-cache.d.ts

@@ -0,0 +1,10 @@
+export declare class MemoryCache {
+    private store;
+    private maxEntries;
+    constructor(maxEntries: number);
+    setMaxEntries(maxEntries: number): void;
+    get<T>(key: string): T | null;
+    set(key: string, value: unknown, ttlMs: number): void;
+    clear(): void;
+    private prune;
+}

package/dist/memory-cache.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryCache = void 0;
+class MemoryCache {
+    constructor(maxEntries) {
+        this.store = new Map();
+        this.maxEntries = maxEntries;
+    }
+    setMaxEntries(maxEntries) {
+        this.maxEntries = maxEntries;
+        this.prune();
+    }
+    get(key) {
+        const item = this.store.get(key);
+        if (!item)
+            return null;
+        if (Date.now() > item.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return item.value;
+    }
+    set(key, value, ttlMs) {
+        this.store.set(key, { value, expiresAt: Date.now() + ttlMs });
+        this.prune();
+    }
+    clear() {
+        this.store.clear();
+    }
+    prune() {
+        if (this.store.size <= this.maxEntries)
+            return;
+        const overflow = this.store.size - this.maxEntries;
+        const keys = this.store.keys();
+        for (let i = 0; i < overflow; i += 1) {
+            const next = keys.next();
+            if (next.done)
+                return;
+            this.store.delete(next.value);
+        }
+    }
+}
+exports.MemoryCache = MemoryCache;

package/dist/music-api.d.ts

@@ -0,0 +1,84 @@
+import { SourceInstance } from './source-loader';
+import type { CommentResult, MusicApiConfig, MusicInfo, RemoteSourceOptions, SearchOptions, SearchResult, SourceCapabilities, SongListDetailResult, SongListResult, SongListTagResult, SourceInfo, SourceKey, SupportedPlatform } from './types';
+export declare class MusicApi {
+    private config;
+    private httpClient;
+    private sourceLoader;
+    private lxProjectApi;
+    private sourceInstance;
+    private cache;
+    constructor(config?: MusicApiConfig);
+    /** 更新运行时配置（超时、证书、重定向等） */
+    updateConfig(config: Partial<MusicApiConfig>): void;
+    /** 初始化：必须先加载 source，不再提供内置默认源 */
+    init(): Promise<SourceInstance>;
+    /** 从本地文件加载源脚本 */
+    loadSourceFromFile(scriptPath: string): Promise<SourceInstance>;
+    /** 从脚本文本加载源 */
+    loadSourceFromCode(code: string): Promise<SourceInstance>;
+    /** 从远程地址加载源（http/https） */
+    loadSourceFromRemote(url: string, options?: RemoteSourceOptions): Promise<SourceInstance>;
+    loadSourceFormRemote(url: string, options?: RemoteSourceOptions): Promise<SourceInstance>;
+    loadSourceFormRmote(url: string, options?: RemoteSourceOptions): Promise<SourceInstance>;
+    /** 手动设置已加载源实例 */
+    setSource(sourceInstance: SourceInstance): void;
+    /** 获取内置支持平台列表 */
+    getSupportedPlatforms(): SupportedPlatform[];
+    getCapabilities(): SourceCapabilities;
+    /** 获取当前源声明的可用源列表 */
+    getSupportedSourceList(): Promise<Array<{
+        key: SourceKey;
+        info: SourceInfo;
+    }>>;
+    private getSource;
+    /** 单平台搜索歌曲 */
+    search(source: string, keywords: string, options?: SearchOptions): Promise<SearchResult>;
+    /** 获取播放链接（仅此能力依赖 source 脚本） */
+    getMusicUrl(source: string, musicInfo: MusicInfo, quality?: string): Promise<unknown>;
+    /** 获取歌词 */
+    getLyric(source: string, musicInfo: MusicInfo): Promise<import("./types").MusicLyric>;
+    /** 获取封面 */
+    getPic(source: string, musicInfo: MusicInfo): Promise<string>;
+    /** 获取热门歌曲 */
+    getHot(source: string, options?: SearchOptions): Promise<import("./types").RankResult>;
+    /** 获取榜单歌曲 */
+    getRank(source: string, rankType: string, options?: SearchOptions): Promise<import("./types").RankResult>;
+    /** 获取歌单标签（含热门标签） */
+    getSongListTags(source: string): Promise<SongListTagResult>;
+    /** 获取歌单列表 */
+    getSongList(source: string, options?: SearchOptions & {
+        sortId?: string;
+        tagId?: string;
+    }): Promise<SongListResult>;
+    /** 获取歌单详情（含歌单内歌曲） */
+    getSongListDetail(source: string, listId: string, options?: SearchOptions): Promise<SongListDetailResult>;
+    /** 获取歌曲评论 */
+    getComment(source: string, musicInfo: MusicInfo, options?: SearchOptions): Promise<CommentResult>;
+    /** 获取热门评论 */
+    getHotComment(source: string, musicInfo: MusicInfo, options?: SearchOptions): Promise<CommentResult>;
+    /** 获取歌曲详情页地址 */
+    getMusicDetailPageUrl(source: string, musicInfo: MusicInfo): string | null;
+    /** 跨平台搜索同名歌曲（排除指定源） */
+    searchMusic(params: {
+        name: string;
+        singer?: string;
+        source?: SourceKey;
+        limit?: number;
+    }): Promise<SearchResult[]>;
+    /** 尝试从多平台匹配最接近的歌曲 */
+    findMusic(params: {
+        name: string;
+        singer?: string;
+        albumName?: string;
+        interval?: string;
+        source?: SourceKey;
+    }): Promise<MusicInfo[]>;
+    /** 透传调用源脚本的自定义 action */
+    dispatch(source: string, action: string, info?: Record<string, unknown>): Promise<unknown>;
+    getLoadedSource(): SourceInstance;
+    clearCache(): void;
+    private normalizeRetryConfig;
+    private normalizeCacheConfig;
+    private execute;
+    private executeCached;
+}

package/dist/music-api.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MusicApi = void 0;
+const api_error_1 = require("./api-error");
+const http_client_1 = require("./http-client");
+const memory_cache_1 = require("./memory-cache");
+const source_loader_1 = require("./source-loader");
+const lx_project_api_1 = require("./lx-project-api");
+const types_1 = require("./types");
+const DEFAULT_CONFIG = {
+    initTimeout: 15000,
+    requestTimeout: 15000,
+    followMaxRedirects: 5,
+    rejectUnauthorized: false,
+    retry: {
+        retries: 2,
+        retryDelayMs: 200,
+        retryStatusCodes: [429, 500, 502, 503, 504],
+        retryErrorCodes: ['ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'EAI_AGAIN'],
+    },
+    cache: {
+        enabled: true,
+        ttlMs: 30 * 1000,
+        maxEntries: 1000,
+    },
+};
+class MusicApi {
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.httpClient = new http_client_1.HttpClient({
+            timeout: this.config.requestTimeout,
+            followMaxRedirects: this.config.followMaxRedirects,
+            rejectUnauthorized: this.config.rejectUnauthorized,
+            retry: this.normalizeRetryConfig(this.config.retry),
+        });
+        this.sourceLoader = new source_loader_1.SourceLoader(this.httpClient, { initTimeout: this.config.initTimeout });
+        this.lxProjectApi = new lx_project_api_1.LxProjectApi(this.httpClient);
+        this.sourceInstance = null;
+        this.cache = new memory_cache_1.MemoryCache(this.normalizeCacheConfig(this.config.cache).maxEntries);
+    }
+    /** 更新运行时配置（超时、证书、重定向等） */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        const retry = this.normalizeRetryConfig(this.config.retry);
+        const cache = this.normalizeCacheConfig(this.config.cache);
+        this.httpClient.updateConfig({
+            timeout: this.config.requestTimeout,
+            followMaxRedirects: this.config.followMaxRedirects,
+            rejectUnauthorized: this.config.rejectUnauthorized,
+            retry,
+        });
+        this.sourceLoader.updateOptions({ initTimeout: this.config.initTimeout });
+        this.cache.setMaxEntries(cache.maxEntries);
+    }
+    /** 初始化：必须先加载 source，不再提供内置默认源 */
+    async init() {
+        if (this.sourceInstance)
+            return this.sourceInstance;
+        throw new api_error_1.ApiError('E_SOURCE_INIT', '[inki-music-api] source 未初始化，请先 loadSourceFromFile/loadSourceFromCode/loadSourceFromRemote');
+    }
+    /** 从本地文件加载源脚本 */
+    async loadSourceFromFile(scriptPath) {
+        this.sourceInstance = await this.sourceLoader.loadFromFile(scriptPath);
+        return this.sourceInstance;
+    }
+    /** 从脚本文本加载源 */
+    async loadSourceFromCode(code) {
+        this.sourceInstance = await this.sourceLoader.loadFromCode(code);
+        return this.sourceInstance;
+    }
+    /** 从远程地址加载源（http/https） */
+    async loadSourceFromRemote(url, options = {}) {
+        return this.execute('loadSourceFromRemote', async () => {
+            const { headers, timeout, rejectUnauthorized } = options;
+            const response = await this.httpClient.requestPromise(url, {
+                method: 'GET',
+                headers,
+                timeout,
+                rejectUnauthorized,
+            });
+            const body = response.body;
+            if (typeof body !== 'string') {
+                throw new api_error_1.ApiError('E_REMOTE_SOURCE_INVALID', '[inki-music-api] 远程源内容不是字符串脚本');
+            }
+            return this.loadSourceFromCode(body);
+        });
+    }
+    async loadSourceFormRemote(url, options = {}) {
+        return this.loadSourceFromRemote(url, options);
+    }
+    async loadSourceFormRmote(url, options = {}) {
+        return this.loadSourceFromRemote(url, options);
+    }
+    /** 手动设置已加载源实例 */
+    setSource(sourceInstance) {
+        this.sourceInstance = sourceInstance;
+    }
+    /** 获取内置支持平台列表 */
+    getSupportedPlatforms() {
+        return [...types_1.SUPPORTED_PLATFORMS];
+    }
+    getCapabilities() {
+        return {
+            search: true,
+            musicUrl: true,
+            lyric: true,
+            pic: true,
+            hot: true,
+            rank: true,
+            songListTags: true,
+            songList: true,
+            songListDetail: true,
+            comment: true,
+            hotComment: true,
+            searchMusic: true,
+            findMusic: true,
+            dispatch: true,
+        };
+    }
+    /** 获取当前源声明的可用源列表 */
+    async getSupportedSourceList() {
+        return this.execute('getSupportedSourceList', async () => {
+            const source = await this.getSource();
+            return Object.entries(source.sources).map(([key, info]) => ({ key, info }));
+        });
+    }
+    async getSource() {
+        if (this.sourceInstance)
+            return this.sourceInstance;
+        return this.init();
+    }
+    /** 单平台搜索歌曲 */
+    async search(source, keywords, options = {}) {
+        return this.executeCached(`search:${source}:${keywords}:${options.page || 1}:${options.limit || 20}`, async () => {
+            const { page = 1, limit = 20 } = options;
+            return this.lxProjectApi.search(source, keywords, page, limit);
+        });
+    }
+    /** 获取播放链接（仅此能力依赖 source 脚本） */
+    async getMusicUrl(source, musicInfo, quality = '128k') {
+        return this.execute('getMusicUrl', async () => {
+            const sourceInstance = await this.getSource();
+            return sourceInstance.getMusicUrl(source, musicInfo, quality);
+        }, source);
+    }
+    /** 获取歌词 */
+    async getLyric(source, musicInfo) {
+        return this.executeCached(`lyric:${source}:${musicInfo.songmid}`, async () => this.lxProjectApi.lyric(source, musicInfo), source);
+    }
+    /** 获取封面 */
+    async getPic(source, musicInfo) {
+        return this.executeCached(`pic:${source}:${musicInfo.songmid}`, async () => this.lxProjectApi.pic(source, musicInfo), source);
+    }
+    /** 获取热门歌曲 */
+    async getHot(source, options = {}) {
+        return this.executeCached(`hot:${source}:${options.page || 1}:${options.limit || 20}`, async () => {
+            const { page = 1, limit = 20 } = options;
+            return this.lxProjectApi.hot(source, page, limit);
+        }, source);
+    }
+    /** 获取榜单歌曲 */
+    async getRank(source, rankType, options = {}) {
+        return this.executeCached(`rank:${source}:${rankType}:${options.page || 1}:${options.limit || 20}`, async () => {
+            const { page = 1, limit = 20 } = options;
+            return this.lxProjectApi.rank(source, rankType, page, limit);
+        }, source);
+    }
+    /** 获取歌单标签（含热门标签） */
+    async getSongListTags(source) {
+        return this.executeCached(`song-list-tags:${source}`, async () => this.lxProjectApi.songListTags(source), source);
+    }
+    /** 获取歌单列表 */
+    async getSongList(source, options = {}) {
+        return this.executeCached(`song-list:${source}:${options.sortId || 'hot'}:${options.tagId || ''}:${options.page || 1}:${options.limit || 30}`, async () => {
+            const { page = 1, limit = 30, sortId = 'hot', tagId = '' } = options;
+            return this.lxProjectApi.songList(source, sortId, tagId, page, limit);
+        }, source);
+    }
+    /** 获取歌单详情（含歌单内歌曲） */
+    async getSongListDetail(source, listId, options = {}) {
+        return this.executeCached(`song-list-detail:${source}:${listId}:${options.page || 1}:${options.limit || 100}`, async () => {
+            const { page = 1, limit = 100 } = options;
+            return this.lxProjectApi.songListDetail(source, listId, page, limit);
+        }, source);
+    }
+    /** 获取歌曲评论 */
+    async getComment(source, musicInfo, options = {}) {
+        return this.executeCached(`comment:${source}:${musicInfo.songmid}:${options.page || 1}:${options.limit || 20}`, async () => {
+            const { page = 1, limit = 20 } = options;
+            return this.lxProjectApi.comment(source, musicInfo, page, limit, false);
+        }, source);
+    }
+    /** 获取热门评论 */
+    async getHotComment(source, musicInfo, options = {}) {
+        return this.executeCached(`hot-comment:${source}:${musicInfo.songmid}:${options.page || 1}:${options.limit || 20}`, async () => {
+            const { page = 1, limit = 20 } = options;
+            return this.lxProjectApi.comment(source, musicInfo, page, limit, true);
+        }, source);
+    }
+    /** 获取歌曲详情页地址 */
+    getMusicDetailPageUrl(source, musicInfo) {
+        return this.lxProjectApi.getMusicDetailPageUrl(source, musicInfo);
+    }
+    /** 跨平台搜索同名歌曲（排除指定源） */
+    async searchMusic(params) {
+        return this.execute('searchMusic', async () => {
+            const { name, singer = '', source, limit = 25 } = params;
+            const keyword = `${name} ${singer}`.trim();
+            const tasks = this.getSupportedPlatforms()
+                .filter((platform) => platform !== source)
+                .map((platform) => this.search(platform, keyword, { page: 1, limit }).catch(() => null));
+            const result = await Promise.all(tasks);
+            return result.filter((item) => item != null);
+        });
+    }
+    /** 尝试从多平台匹配最接近的歌曲 */
+    async findMusic(params) {
+        return this.execute('findMusic', async () => {
+            const { name, singer = '', albumName = '', interval = '', source } = params;
+            const lists = await this.searchMusic({ name, singer, source, limit: 25 });
+            const normalize = (text) => text.toLowerCase().replace(/\s|'|\.|,|，|&|"|、|\(|\)|（|）|`|~|-|<|>|\||\/|\]|\[|!|！/g, '');
+            const targetName = normalize(name);
+            const targetSinger = normalize(singer);
+            const targetAlbum = normalize(albumName);
+            const targetInterval = interval;
+            const candidates = [];
+            for (const list of lists) {
+                for (const item of list.list) {
+                    let score = 0;
+                    if (normalize(item.name) === targetName)
+                        score += 4;
+                    if (targetSinger && normalize(item.singer) === targetSinger)
+                        score += 3;
+                    if (targetAlbum && normalize(item.albumName) === targetAlbum)
+                        score += 2;
+                    if (targetInterval && item.interval === targetInterval)
+                        score += 2;
+                    if (score > 0)
+                        candidates.push({ score, item });
+                }
+            }
+            return candidates.sort((a, b) => b.score - a.score).map((item) => item.item);
+        });
+    }
+    /** 透传调用源脚本的自定义 action */
+    async dispatch(source, action, info = {}) {
+        return this.execute('dispatch', async () => {
+            const sourceInstance = await this.getSource();
+            return sourceInstance.dispatchAction(source, action, info);
+        }, source);
+    }
+    getLoadedSource() {
+        return this.sourceInstance;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    normalizeRetryConfig(config) {
+        return {
+            retries: config?.retries ?? DEFAULT_CONFIG.retry.retries,
+            retryDelayMs: config?.retryDelayMs ?? DEFAULT_CONFIG.retry.retryDelayMs,
+            retryStatusCodes: config?.retryStatusCodes ?? DEFAULT_CONFIG.retry.retryStatusCodes,
+            retryErrorCodes: config?.retryErrorCodes ?? DEFAULT_CONFIG.retry.retryErrorCodes,
+        };
+    }
+    normalizeCacheConfig(config) {
+        return {
+            enabled: config?.enabled ?? DEFAULT_CONFIG.cache.enabled,
+            ttlMs: config?.ttlMs ?? DEFAULT_CONFIG.cache.ttlMs,
+            maxEntries: config?.maxEntries ?? DEFAULT_CONFIG.cache.maxEntries,
+        };
+    }
+    async execute(operation, runner, source) {
+        try {
+            return await runner();
+        }
+        catch (error) {
+            throw (0, api_error_1.toApiError)(error, 'E_UPSTREAM', `[inki-music-api] ${operation} failed`, source);
+        }
+    }
+    async executeCached(key, runner, source) {
+        const cache = this.normalizeCacheConfig(this.config.cache);
+        if (cache.enabled) {
+            const existed = this.cache.get(key);
+            if (existed != null)
+                return existed;
+        }
+        const result = await this.execute(key, runner, source);
+        if (cache.enabled)
+            this.cache.set(key, result, cache.ttlMs);
+        return result;
+    }
+}
+exports.MusicApi = MusicApi;

package/dist/source-loader.d.ts

@@ -0,0 +1,28 @@
+import { LxRuntime } from './lx-runtime';
+import type { HttpClient } from './http-client';
+import type { SourceInfo, SourceInitData, SourceScriptMeta } from './types';
+export declare class SourceInstance {
+    readonly meta: SourceScriptMeta;
+    readonly sources: Record<string, SourceInfo>;
+    private runtime;
+    constructor(runtime: LxRuntime, initedData: SourceInitData, meta: SourceScriptMeta);
+    private dispatch;
+    getMusicUrl(source: string, musicInfo: unknown, quality?: string): Promise<unknown>;
+    getLyric(source: string, musicInfo: unknown): Promise<unknown>;
+    getPic(source: string, musicInfo: unknown): Promise<unknown>;
+    search(source: string, keywords: string, page?: number, limit?: number): Promise<unknown>;
+    getHot(source: string, page?: number, limit?: number): Promise<unknown>;
+    getRank(source: string, rankType: string, page?: number, limit?: number): Promise<unknown>;
+    dispatchAction(source: string, action: string, info: Record<string, unknown>): Promise<unknown>;
+}
+export interface LoaderOptions {
+    initTimeout: number;
+}
+export declare class SourceLoader {
+    private httpClient;
+    private options;
+    constructor(httpClient: HttpClient, options: LoaderOptions);
+    updateOptions(options: Partial<LoaderOptions>): void;
+    loadFromFile(scriptPath: string): Promise<SourceInstance>;
+    loadFromCode(code: string): Promise<SourceInstance>;
+}