refactor(sdk): musicSdk 全量迁移至 TypeScript

musicSdk/types.ts

@@ -0,0 +1,146 @@
+// SDK 共享类型定义
+// 所有平台模块与根模块的类型锚点。类型只描述实际返回的数据形状，不改变运行时行为。
+
+/** 音乐平台标识 */
+export type Source = 'kw' | 'kg' | 'tx' | 'wy' | 'mg' | 'bd' | 'xm'
+
+/** 音质标识（wav 仅部分接口声明使用） */
+export type Quality = '128k' | '320k' | 'flac' | 'flac24bit' | 'wav'
+
+/** 单音质资源描述（搜索结果 types 数组项） */
+export interface SongType {
+  type: Quality
+  size: string
+}
+
+/** 单音质详情（搜索结果 _types 映射项） */
+export interface QualityInfo {
+  size: string
+}
+
+/** 歌曲信息（搜索结果项 / 取流入参） */
+export interface SongInfo {
+  songmid?: string
+  hash?: string
+  copyrightId?: string
+  songStringId?: string
+  albumId?: string
+  name?: string | null
+  singer?: string
+  source?: Source
+  interval?: string | number
+  albumName?: string
+  img?: string | null
+  lrc?: string | null
+  otherSource?: string | null
+  types?: SongType[]
+  _types?: Partial<Record<Quality, QualityInfo>>
+  typeUrl?: Partial<Record<Quality, string>>
+  [key: string]: unknown
+}
+
+/** httpFetch 响应（与 src/common/request.js 契约一致） */
+export interface HttpResponse {
+  statusCode: number
+  statusMessage?: string
+  headers: Record<string, string | string[]>
+  body: any
+  raw?: Buffer
+}
+
+/** httpFetch 返回的可取消请求对象 */
+export interface HttpRequestObject {
+  promise: Promise<HttpResponse>
+  cancelHttp(): void
+}
+
+/** httpFetch 选项（src/common/request.js 子集） */
+export interface HttpOptions {
+  method?: string
+  headers?: Record<string, string>
+  body?: string | object
+  form?: Record<string, unknown>
+  timeout?: number
+  lookup?: unknown
+  family?: number
+}
+
+/** 带取消句柄的异步结果（getMusicUrl/getLyric 等的统一返回形态） */
+export interface RequestObj<T> {
+  promise: Promise<T>
+  cancelHttp(): void
+}
+
+/** 取流结果 */
+export interface MusicUrlResult {
+  type: string
+  url: string
+}
+
+/** 歌词结果 */
+export interface LyricInfo {
+  lyric: string
+  tlyric: string
+  rlyric?: string
+  lxlyric?: string
+}
+
+/** 搜索结果 */
+export interface SearchResult {
+  list: SongInfo[]
+  allPage: number
+  total: number
+  limit: number
+  source: Source
+}
+
+/** 搜索模块（平台 musicSearch 子模块） */
+export interface MusicSearchModule {
+  search(str: string, page?: number, limit?: number, retryNum?: number): Promise<SearchResult>
+  [key: string]: unknown
+}
+
+/** 歌词模块 */
+export interface LyricModule {
+  getLyric(songInfo: SongInfo, ...rest: unknown[]): Promise<LyricInfo> | RequestObj<LyricInfo>
+  [key: string]: unknown
+}
+
+/** 封面模块 */
+export interface PicModule {
+  getPic(songInfo: SongInfo, ...rest: unknown[]): Promise<string> | RequestObj<string>
+  [key: string]: unknown
+}
+
+/** 热搜模块 */
+export interface HotSearchModule {
+  getList(): Promise<any>
+  [key: string]: unknown
+}
+
+/** 评论模块 */
+export interface CommentModule {
+  getComment(songInfo: any, page?: number, limit?: number): Promise<any>
+  getHotComment(songInfo: any, page?: number, limit?: number): Promise<any>
+  [key: string]: unknown
+}
+
+/** 平台模块（各平台默认导出需满足的最小形状）
+ * 注：SDK 内部实现大量返回 httpFetch 原生的 HttpRequestObject，
+ *     实际 promise 会在 .then() 中被改写为对应结果类型；此处只约束调用侧可见形态。
+ */
+export interface PlatformModule {
+  init?(): Promise<unknown> | void
+  musicSearch?: MusicSearchModule
+  leaderboard?: any
+  songList?: any
+  hotSearch?: HotSearchModule
+  comment?: CommentModule
+  tipSearch?: any
+  getMusicUrl?(songInfo: SongInfo, type: Quality): HttpRequestObject
+  getLyric?(songInfo: SongInfo, ...rest: unknown[]): HttpRequestObject
+  getPic?(songInfo: SongInfo, ...rest: unknown[]): HttpRequestObject | Promise<any>
+  getMusicInfo?(songInfo: SongInfo): HttpRequestObject | Promise<any>
+  getMusicDetailPageUrl?(songInfo: SongInfo): string
+  [key: string]: any
+}