@songloft/client-sdk 2.13.0 → 2.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -94,6 +94,23 @@ if (isClient()) {
94
94
 
95
95
  完整类型见包内 `.d.ts`(`ClientSong` / `ClientPlayerState` / `HostInfo` / `PlayMode` 等)。
96
96
 
97
+ ### `getCookies(origin: string): Promise<Record<string, string>>`
98
+
99
+ 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie(含 HttpOnly)。
100
+
101
+ ```ts
102
+ import { getCookies } from '@songloft/client-sdk';
103
+
104
+ const cookies = await getCookies('https://pcyear.5ddd.com');
105
+ // { 'os-access-code': '...', 'music-token': '...' }
106
+ ```
107
+
108
+ | 参数 | 说明 |
109
+ |------|------|
110
+ | `origin` | 目标站点 origin,含协议+主机+端口,如 `https://example.com` |
111
+
112
+ > **⚠️ 仅原生客户端可用**(Android / iOS / macOS / Windows / Linux)。Web 端因浏览器同源策略限制无法读取跨源 Cookie,调用会 reject 并提示平台不支持。使用前建议通过 `host.getInfo()` 检查 `platform !== 'web'`。
113
+
97
114
  ## License
98
115
 
99
116
  Apache-2.0
package/dist/index.cjs CHANGED
@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/index.ts
21
21
  var index_exports = {};
22
22
  __export(index_exports, {
23
+ getCookies: () => getCookies,
23
24
  host: () => host,
24
25
  isClient: () => isClient,
25
26
  player: () => player
@@ -66,8 +67,16 @@ var host = {
66
67
  isAvailable: () => isClient(),
67
68
  getInfo: () => requireHost().getInfo()
68
69
  };
70
+ function getCookies(origin) {
71
+ const g = getGlobal();
72
+ if (!g || typeof g.getCookies !== "function") {
73
+ return Promise.reject(new Error("getCookies is not available on this platform (requires native client)"));
74
+ }
75
+ return g.getCookies(origin);
76
+ }
69
77
  // Annotate the CommonJS export names for ESM import in node:
70
78
  0 && (module.exports = {
79
+ getCookies,
71
80
  host,
72
81
  isClient,
73
82
  player
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// native 客户端走 flutter_inappwebview.callHandler,Web 端插件页(Tab 内嵌页与\n// 首页/全屏页均在宿主 iframe 内)走 postMessage。本包是**类型层 + 便捷封装**,\n// 所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiKA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// 传输由 common.js 按宿主环境自动选择,插件无需关心:\n// - native 客户端 + WebF 渲染引擎 → webf.methodChannel\n// - native 客户端 + 系统 WebView → flutter_inappwebview.callHandler\n// - Web 端插件页(Tab 内嵌页与首页/全屏页均在宿主 iframe 内)→ postMessage\n// 本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n /**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。\n *\n * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"(含协议 + 主机 + 端口)\n * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}\n */\n getCookies?(origin: string): Promise<Record<string, string>>;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n\n/**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 仅原生客户端可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"\n * @returns name → value 映射\n */\nexport function getCookies(origin: string): Promise<Record<string, string>> {\n const g = getGlobal();\n if (!g || typeof g.getCookies !== 'function') {\n return Promise.reject(new Error('getCookies is not available on this platform (requires native client)'));\n }\n return g.getCookies(origin);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6KA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;AASO,SAAS,WAAW,QAAiD;AAC1E,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,OAAO,EAAE,eAAe,YAAY;AAC5C,WAAO,QAAQ,OAAO,IAAI,MAAM,uEAAuE,CAAC;AAAA,EAC1G;AACA,SAAO,EAAE,WAAW,MAAM;AAC5B;","names":[]}
package/dist/index.d.cts CHANGED
@@ -107,6 +107,16 @@ interface SongloftPluginHost {
107
107
  interface SongloftPluginGlobal {
108
108
  host?: SongloftPluginHost;
109
109
  player?: SongloftPluginPlayer;
110
+ /**
111
+ * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。
112
+ * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。
113
+ *
114
+ * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。
115
+ *
116
+ * @param origin 目标站点 origin,例如 "https://example.com"(含协议 + 主机 + 端口)
117
+ * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}
118
+ */
119
+ getCookies?(origin: string): Promise<Record<string, string>>;
110
120
  getTheme?(): 'light' | 'dark';
111
121
  onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;
112
122
  apiGet?(path: string): Promise<unknown>;
@@ -129,5 +139,13 @@ declare function isClient(): boolean;
129
139
  declare const player: SongloftPluginPlayer;
130
140
  /** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */
131
141
  declare const host: SongloftPluginHost;
142
+ /**
143
+ * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。
144
+ * 仅原生客户端可用,Web 端调用会 reject。
145
+ *
146
+ * @param origin 目标站点 origin,例如 "https://example.com"
147
+ * @returns name → value 映射
148
+ */
149
+ declare function getCookies(origin: string): Promise<Record<string, string>>;
132
150
 
133
- export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, host, isClient, player };
151
+ export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, getCookies, host, isClient, player };
package/dist/index.d.ts CHANGED
@@ -107,6 +107,16 @@ interface SongloftPluginHost {
107
107
  interface SongloftPluginGlobal {
108
108
  host?: SongloftPluginHost;
109
109
  player?: SongloftPluginPlayer;
110
+ /**
111
+ * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。
112
+ * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。
113
+ *
114
+ * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。
115
+ *
116
+ * @param origin 目标站点 origin,例如 "https://example.com"(含协议 + 主机 + 端口)
117
+ * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}
118
+ */
119
+ getCookies?(origin: string): Promise<Record<string, string>>;
110
120
  getTheme?(): 'light' | 'dark';
111
121
  onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;
112
122
  apiGet?(path: string): Promise<unknown>;
@@ -129,5 +139,13 @@ declare function isClient(): boolean;
129
139
  declare const player: SongloftPluginPlayer;
130
140
  /** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */
131
141
  declare const host: SongloftPluginHost;
142
+ /**
143
+ * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。
144
+ * 仅原生客户端可用,Web 端调用会 reject。
145
+ *
146
+ * @param origin 目标站点 origin,例如 "https://example.com"
147
+ * @returns name → value 映射
148
+ */
149
+ declare function getCookies(origin: string): Promise<Record<string, string>>;
132
150
 
133
- export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, host, isClient, player };
151
+ export { type ClientPlayerState, type ClientSong, type HostInfo, type PlayMode, type SetQueueOptions, type SongloftPluginGlobal, type SongloftPluginHost, type SongloftPluginPlayer, getCookies, host, isClient, player };
package/dist/index.js CHANGED
@@ -40,7 +40,15 @@ var host = {
40
40
  isAvailable: () => isClient(),
41
41
  getInfo: () => requireHost().getInfo()
42
42
  };
43
+ function getCookies(origin) {
44
+ const g = getGlobal();
45
+ if (!g || typeof g.getCookies !== "function") {
46
+ return Promise.reject(new Error("getCookies is not available on this platform (requires native client)"));
47
+ }
48
+ return g.getCookies(origin);
49
+ }
43
50
  export {
51
+ getCookies,
44
52
  host,
45
53
  isClient,
46
54
  player
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// native 客户端走 flutter_inappwebview.callHandler,Web 端插件页(Tab 内嵌页与\n// 首页/全屏页均在宿主 iframe 内)走 postMessage。本包是**类型层 + 便捷封装**,\n// 所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n"],"mappings":";AAiKA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;","names":[]}
1
+ {"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @songloft/client-sdk — 客户端 SDK\n//\n// 让「在 Songloft Flutter 客户端 webview 中打开的插件页面」调用宿主客户端能力\n// (改写正在播放队列、控制播放、订阅播放状态等)。\n//\n// 架构:运行时能力由宿主注入到 `window.SongloftPlugin`(common.js + Flutter 宿主)。\n// 传输由 common.js 按宿主环境自动选择,插件无需关心:\n// - native 客户端 + WebF 渲染引擎 → webf.methodChannel\n// - native 客户端 + 系统 WebView → flutter_inappwebview.callHandler\n// - Web 端插件页(Tab 内嵌页与首页/全屏页均在宿主 iframe 内)→ postMessage\n// 本包是**类型层 + 便捷封装**,所有调用都委托给注入的全局对象,因此:\n// - native 客户端 webview 插件页、Web 端 iframe 内嵌插件页内有效;\n// - 仅当用户通过「在浏览器中打开」将插件页在独立新标签打开(无宿主父窗口)、\n// 或宿主版本过旧时,`isClient()` / `host.isAvailable()` 返回 false,调用会抛出明确错误,请先 feature-detect。\n//\n// 用法:\n// import { player, host, isClient } from '@songloft/client-sdk';\n// if (isClient()) {\n// await player.setQueue([101, 102], { startIndex: 0 });\n// player.onStateChange((s) => console.log(s.current_index));\n// }\n//\n// 免构建的 vanilla 插件可直接用注入的全局对象:\n// window.SongloftPlugin.player.setQueue([101, 102]);\n\n// ===== 数据模型 =====\n\n/** 播放模式(与宿主一致)。 */\nexport type PlayMode = 'order' | 'loop' | 'single' | 'random' | 'singlePlay';\n\n/**\n * 队列中的歌曲对象(宿主返回值,字段为 snake_case,与后端 JSON 一致)。\n * 只列出常用字段;宿主可能返回更多字段。\n */\nexport interface ClientSong {\n id: number;\n type: 'local' | 'remote' | 'radio';\n title: string;\n artist?: string;\n album?: string;\n duration?: number;\n url?: string;\n cover_url?: string;\n lyric_url?: string;\n is_live?: boolean;\n [key: string]: unknown;\n}\n\n/** 播放器状态快照(`player.getState()` / `onStateChange` 回调)。 */\nexport interface ClientPlayerState {\n /** 正在播放队列 */\n queue: ClientSong[];\n /** 当前歌曲在队列中的下标;无歌曲时为 -1 */\n current_index: number;\n /** 当前歌曲;无歌曲时为 null */\n current_song: ClientSong | null;\n is_playing: boolean;\n /** 当前播放进度(秒) */\n current_time: number;\n /** 当前歌曲总时长(秒) */\n duration: number;\n /** 音量 0-100 */\n volume: number;\n play_mode: PlayMode;\n /** 队列来源的服务端歌单 id(如有) */\n source_playlist_id?: number | null;\n}\n\n/** 宿主信息与能力协商结果(`host.getInfo()`)。 */\nexport interface HostInfo {\n /** 客户端应用版本,如 \"2.12.0\" */\n version: string;\n /** 运行平台:android / ios / macos / windows / linux / web */\n platform: string;\n /** 宿主支持的能力命名空间,如 [\"player\"],用于向前兼容的能力协商 */\n capabilities: string[];\n}\n\n/** `setQueue` 的可选参数。 */\nexport interface SetQueueOptions {\n /** 从队列的哪一首开始播放,默认 0 */\n startIndex?: number;\n /** 标记队列来源的服务端歌单 id(可选,仅用于 UI 展示归属) */\n sourcePlaylistId?: number;\n}\n\n// ===== 注入的全局对象类型(window.SongloftPlugin) =====\n\n/** 宿主客户端能力:播放器命名空间。 */\nexport interface SongloftPluginPlayer {\n /** 获取当前播放器状态快照 */\n getState(): Promise<ClientPlayerState>;\n /** 用歌曲 id 列表替换整个正在播放队列并开始播放 */\n setQueue(ids: number[], options?: SetQueueOptions): Promise<void>;\n /** 追加歌曲到队列末尾(去重,不改变当前播放) */\n addToQueue(ids: number[]): Promise<void>;\n /** 在队列指定位置插入一首歌(不触发播放) */\n insertToQueue(index: number, id: number): Promise<void>;\n /** 移除队列中指定下标的歌曲 */\n removeFromQueue(index: number): Promise<void>;\n /** 重排队列 */\n reorderQueue(oldIndex: number, newIndex: number): Promise<void>;\n /** 清空队列 */\n clearQueue(): Promise<void>;\n /** 播放:传 id 则播放该歌曲(不在队列则追加),不传则恢复播放 */\n play(id?: number): Promise<void>;\n /** 暂停 */\n pause(): Promise<void>;\n /** 播放/暂停切换 */\n togglePlay(): Promise<void>;\n /** 下一首 */\n next(): Promise<void>;\n /** 上一首 */\n prev(): Promise<void>;\n /** 跳转到指定进度(秒) */\n seek(seconds: number): Promise<void>;\n /** 设置音量 0-100 */\n setVolume(volume: number): Promise<void>;\n /** 设置播放模式 */\n setPlayMode(mode: PlayMode): Promise<void>;\n /** 直接播放服务端歌单(按歌单 id) */\n playPlaylistById(playlistId: number): Promise<void>;\n /**\n * 订阅播放状态变更。返回取消订阅函数。\n * 注意:状态推送经过节流,`current_time` 可能不是每秒更新。\n */\n onStateChange(handler: (state: ClientPlayerState) => void): () => void;\n}\n\n/** 宿主客户端能力:host 命名空间。 */\nexport interface SongloftPluginHost {\n /** 同步 feature-detect:当前是否运行在支持原生桥接的 Songloft 客户端 webview 内 */\n isAvailable(): boolean;\n /** 获取宿主信息与能力列表 */\n getInfo(): Promise<HostInfo>;\n}\n\n/**\n * 注入到页面的 `window.SongloftPlugin` 全局对象。\n * 由主程序 common.js 注入到所有插件 HTML 页面。此处仅声明本 SDK 依赖的成员,\n * 现有的 apiGet/apiPost/getTheme 等成员见插件开发指南。\n */\nexport interface SongloftPluginGlobal {\n host?: SongloftPluginHost;\n player?: SongloftPluginPlayer;\n /**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 原生层读取,不受浏览器同源策略 / HttpOnly 限制。\n *\n * 仅原生客户端(Android/iOS/macOS/Windows/Linux)可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"(含协议 + 主机 + 端口)\n * @returns name → value 映射;该 origin 无 Cookie 时返回空对象 {}\n */\n getCookies?(origin: string): Promise<Record<string, string>>;\n // 现有成员(主题 / API 工具)——保留为可选,避免与旧宿主冲突。\n getTheme?(): 'light' | 'dark';\n onThemeChange?(cb: (theme: 'light' | 'dark') => void): void;\n apiGet?(path: string): Promise<unknown>;\n apiPost?(path: string, body: unknown): Promise<unknown>;\n apiPut?(path: string, body: unknown): Promise<unknown>;\n apiDelete?(path: string): Promise<unknown>;\n [key: string]: unknown;\n}\n\ndeclare global {\n interface Window {\n SongloftPlugin?: SongloftPluginGlobal;\n }\n}\n\n// ===== 便捷封装(委托注入的全局对象) =====\n\nconst NOT_AVAILABLE_MSG =\n '[@songloft/client-sdk] 宿主客户端桥接不可用:请确保插件页在 Songloft 客户端(非 Web)的 webview 中打开,且客户端版本支持客户端 SDK。可用 isClient() 预先检测。';\n\nfunction getGlobal(): SongloftPluginGlobal | undefined {\n return typeof window !== 'undefined' ? window.SongloftPlugin : undefined;\n}\n\n/**\n * 是否运行在支持原生桥接的 Songloft 客户端 webview 内。\n * 调用任何 player/host 方法前建议先检测。\n */\nexport function isClient(): boolean {\n const g = getGlobal();\n return !!(g && g.host && typeof g.host.isAvailable === 'function' && g.host.isAvailable());\n}\n\nfunction requirePlayer(): SongloftPluginPlayer {\n const g = getGlobal();\n if (!g || !g.player) throw new Error(NOT_AVAILABLE_MSG);\n return g.player;\n}\n\nfunction requireHost(): SongloftPluginHost {\n const g = getGlobal();\n if (!g || !g.host) throw new Error(NOT_AVAILABLE_MSG);\n return g.host;\n}\n\n/** 播放器控制。所有方法委托注入的 `window.SongloftPlugin.player`。 */\nexport const player: SongloftPluginPlayer = {\n getState: () => requirePlayer().getState(),\n setQueue: (ids, options) => requirePlayer().setQueue(ids, options),\n addToQueue: (ids) => requirePlayer().addToQueue(ids),\n insertToQueue: (index, id) => requirePlayer().insertToQueue(index, id),\n removeFromQueue: (index) => requirePlayer().removeFromQueue(index),\n reorderQueue: (oldIndex, newIndex) => requirePlayer().reorderQueue(oldIndex, newIndex),\n clearQueue: () => requirePlayer().clearQueue(),\n play: (id) => requirePlayer().play(id),\n pause: () => requirePlayer().pause(),\n togglePlay: () => requirePlayer().togglePlay(),\n next: () => requirePlayer().next(),\n prev: () => requirePlayer().prev(),\n seek: (seconds) => requirePlayer().seek(seconds),\n setVolume: (volume) => requirePlayer().setVolume(volume),\n setPlayMode: (mode) => requirePlayer().setPlayMode(mode),\n playPlaylistById: (playlistId) => requirePlayer().playPlaylistById(playlistId),\n onStateChange: (handler) => requirePlayer().onStateChange(handler),\n};\n\n/** 宿主信息与能力协商。委托注入的 `window.SongloftPlugin.host`。 */\nexport const host: SongloftPluginHost = {\n isAvailable: () => isClient(),\n getInfo: () => requireHost().getInfo(),\n};\n\n/**\n * 读取宿主 WebView Cookie Store 中指定 origin 的 Cookie。\n * 仅原生客户端可用,Web 端调用会 reject。\n *\n * @param origin 目标站点 origin,例如 \"https://example.com\"\n * @returns name → value 映射\n */\nexport function getCookies(origin: string): Promise<Record<string, string>> {\n const g = getGlobal();\n if (!g || typeof g.getCookies !== 'function') {\n return Promise.reject(new Error('getCookies is not available on this platform (requires native client)'));\n }\n return g.getCookies(origin);\n}\n"],"mappings":";AA6KA,IAAM,oBACJ;AAEF,SAAS,YAA8C;AACrD,SAAO,OAAO,WAAW,cAAc,OAAO,iBAAiB;AACjE;AAMO,SAAS,WAAoB;AAClC,QAAM,IAAI,UAAU;AACpB,SAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,OAAO,EAAE,KAAK,gBAAgB,cAAc,EAAE,KAAK,YAAY;AAC1F;AAEA,SAAS,gBAAsC;AAC7C,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,OAAQ,OAAM,IAAI,MAAM,iBAAiB;AACtD,SAAO,EAAE;AACX;AAEA,SAAS,cAAkC;AACzC,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,CAAC,EAAE,KAAM,OAAM,IAAI,MAAM,iBAAiB;AACpD,SAAO,EAAE;AACX;AAGO,IAAM,SAA+B;AAAA,EAC1C,UAAU,MAAM,cAAc,EAAE,SAAS;AAAA,EACzC,UAAU,CAAC,KAAK,YAAY,cAAc,EAAE,SAAS,KAAK,OAAO;AAAA,EACjE,YAAY,CAAC,QAAQ,cAAc,EAAE,WAAW,GAAG;AAAA,EACnD,eAAe,CAAC,OAAO,OAAO,cAAc,EAAE,cAAc,OAAO,EAAE;AAAA,EACrE,iBAAiB,CAAC,UAAU,cAAc,EAAE,gBAAgB,KAAK;AAAA,EACjE,cAAc,CAAC,UAAU,aAAa,cAAc,EAAE,aAAa,UAAU,QAAQ;AAAA,EACrF,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,CAAC,OAAO,cAAc,EAAE,KAAK,EAAE;AAAA,EACrC,OAAO,MAAM,cAAc,EAAE,MAAM;AAAA,EACnC,YAAY,MAAM,cAAc,EAAE,WAAW;AAAA,EAC7C,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,MAAM,cAAc,EAAE,KAAK;AAAA,EACjC,MAAM,CAAC,YAAY,cAAc,EAAE,KAAK,OAAO;AAAA,EAC/C,WAAW,CAAC,WAAW,cAAc,EAAE,UAAU,MAAM;AAAA,EACvD,aAAa,CAAC,SAAS,cAAc,EAAE,YAAY,IAAI;AAAA,EACvD,kBAAkB,CAAC,eAAe,cAAc,EAAE,iBAAiB,UAAU;AAAA,EAC7E,eAAe,CAAC,YAAY,cAAc,EAAE,cAAc,OAAO;AACnE;AAGO,IAAM,OAA2B;AAAA,EACtC,aAAa,MAAM,SAAS;AAAA,EAC5B,SAAS,MAAM,YAAY,EAAE,QAAQ;AACvC;AASO,SAAS,WAAW,QAAiD;AAC1E,QAAM,IAAI,UAAU;AACpB,MAAI,CAAC,KAAK,OAAO,EAAE,eAAe,YAAY;AAC5C,WAAO,QAAQ,OAAO,IAAI,MAAM,uEAAuE,CAAC;AAAA,EAC1G;AACA,SAAO,EAAE,WAAW,MAAM;AAC5B;","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@songloft/client-sdk",
3
- "version": "2.13.0",
3
+ "version": "2.13.2",
4
4
  "description": "Client SDK for Songloft webview plugin pages — call Flutter host APIs (player queue, etc.)",
5
5
  "type": "module",
6
6
  "exports": {