@songloft/lynx-plugin-sdk 2.20.0 → 2.22.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Songloft contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -104,14 +104,16 @@ pnpm create @songloft/songloft-plugin
104
104
  ## 插件业务请求 / Plugin API requests
105
105
 
106
106
  ```ts
107
- import { apiGet, apiPost } from '@songloft/lynx-plugin-sdk'
107
+ import { apiGet, apiPost, apiPut, apiDelete } from '@songloft/lynx-plugin-sdk'
108
108
  const status = await apiGet<{ logged_in: boolean }>('/api/login/status')
109
109
  await apiPost('/api/settings', { audio_quality: 'high' })
110
+ await apiPut('/api/settings', { audio_quality: 'lossless' })
111
+ await apiDelete('/api/groups?id=1')
110
112
  ```
111
113
 
112
- 请求通过 `plugin.apiRequest` 交给当前 frame 的宿主;宿主绑定插件身份,处理服务器子路径与认证。只接受 `/api` 下的 GET/POST JSON 请求,禁止绝对地址、编码路径与路径穿越。成功返回业务数据,HTTP、桥接、超时或响应中的 `error` 会抛出异常。宿主请求上限 60 秒,SDK 等待回复上限 65 秒。旧宿主不支持时明确报错,需要更新 Lynx 客户端;Flutter/Web 回退需要更新服务端提供的 shim。插件不需要获取 Token。
114
+ 请求通过 `plugin.apiRequest` 交给当前 frame 的宿主;宿主绑定插件身份,处理服务器子路径与认证。只接受 `/api` 下的 GET/POST/PUT/DELETE JSON 请求,禁止绝对地址、编码路径与路径穿越。成功返回业务数据,HTTP、桥接、超时或响应中的 `error` 会抛出异常。宿主请求上限 60 秒,SDK 等待回复上限 65 秒。旧宿主不支持时明确报错,需要更新 Lynx 客户端;Flutter/Web 回退需要更新服务端提供的 shim。插件不需要获取 Token。
113
115
 
114
- Requests use `plugin.apiRequest`. The host binds the current frame's plugin identity and supplies the server base path and authentication. Only GET/POST JSON requests under `/api` are accepted; absolute URLs, encoded route paths and traversal are rejected. Successful calls return business data. HTTP, bridge, timeout and response `error` failures throw. Host requests expire after 60 seconds; SDK replies expire after 65 seconds. Older hosts report an unsupported-call error: update the Lynx client, or the server-provided shim for Flutter/Web fallback. Plugins do not need access tokens.
116
+ Requests use `plugin.apiRequest`. The host binds the current frame's plugin identity and supplies the server base path and authentication. Only GET/POST/PUT/DELETE JSON requests under `/api` are accepted; absolute URLs, encoded route paths and traversal are rejected. Successful calls return business data. HTTP, bridge, timeout and response `error` failures throw. Host requests expire after 60 seconds; SDK replies expire after 65 seconds. Older hosts report an unsupported-call error: update the Lynx client, or the server-provided shim for Flutter/Web fallback. Plugins do not need access tokens.
115
117
 
116
118
  ## 发布 / Publishing
117
119
 
@@ -123,3 +125,20 @@ This package participates in the unified toolchain release (starting with v2.20.
123
125
  发布中途失败后,可以从 main 执行 `gh workflow run release.yml -f tag=v2.20.0` 恢复同一个 tag。源码仍固定到该 tag,发布工具取自工作流提交;已存在版本跳过,仅明确的 npm E404 才尝试发布,认证和网络失败会中止。首次发布 Lynx SDK 需 npm 账号完成浏览器验证,随后可在 npm 包设置中配置此仓库 `release.yml` 的 Trusted Publisher。
124
126
 
125
127
  After a partial failure, run `gh workflow run release.yml -f tag=v2.20.0` from main to resume the same tag. Package sources remain pinned to the tag; publishing tools come from the workflow revision. Existing versions are skipped; only explicit npm E404 results permit publishing, while authentication/network errors stop the run. Initial SDK publishing requires browser verification through an npm account; configure this repository's `release.yml` as a Trusted Publisher in the package settings afterward.
128
+
129
+ ## 文本连接 / Text sockets
130
+
131
+ ```ts
132
+ import { PluginSocket } from '@songloft/lynx-plugin-sdk'
133
+ const socket = new PluginSocket('/status/ws?device_id=example')
134
+ socket.onopen = () => socket.send('refresh')
135
+ socket.onmessage = ({ data }) => console.log(data)
136
+ socket.onerror = () => console.log('connection failed')
137
+ socket.onclose = () => console.log('closed')
138
+ // Dispose on hide/unmount; create a fresh connection when resumed.
139
+ socket.close()
140
+ ```
141
+
142
+ 路径仅限当前插件的相对路径;宿主提供服务器地址、子路径与认证,按 frame 限八条连接并在释放时关闭。`readyState` 为 0/1/2/3;文本上行最多 65536 字符。需要配套新版 Android/iOS/HarmonyOS/Web 宿主或服务端回退 shim;源码存在不代表 npm 已发布。
143
+
144
+ Only relative paths within the current plugin are accepted. The host supplies server/base path/authentication, caps each frame at eight sockets and closes them on release. `readyState` is 0/1/2/3; outgoing text is limited to 65536 characters. Matching updated native/Web hosts or the server fallback shim are required. Source changes do not imply an npm publication.
package/dist/api.d.ts CHANGED
@@ -2,3 +2,5 @@
2
2
  export declare function validateApiPath(path: string): void;
3
3
  export declare const apiGet: <T = unknown>(path: string) => Promise<T>;
4
4
  export declare const apiPost: <T = unknown>(path: string, body: unknown) => Promise<T>;
5
+ export declare const apiPut: <T = unknown>(path: string, body: unknown) => Promise<T>;
6
+ export declare const apiDelete: <T = unknown>(path: string) => Promise<T>;
package/dist/api.js CHANGED
@@ -21,3 +21,5 @@ async function request(method, path, body) {
21
21
  }
22
22
  export const apiGet = (path) => request('GET', path);
23
23
  export const apiPost = (path, body) => request('POST', path, body);
24
+ export const apiPut = (path, body) => request('PUT', path, body);
25
+ export const apiDelete = (path) => request('DELETE', path);
package/dist/index.d.ts CHANGED
@@ -12,6 +12,7 @@
12
12
  * onPlayerState((state) => { ... })
13
13
  */
14
14
  export { invokeHost, type HostCallResult } from './bridge.js';
15
- export { apiGet, apiPost } from './api.js';
15
+ export { apiGet, apiPost, apiPut, apiDelete } from './api.js';
16
16
  export { onPlayerState, onThemeChange, onPush, type PlayerState, } from './events.js';
17
17
  export { getGlobalProps, getFrameId, getTheme } from './globals.js';
18
+ export { PluginSocket } from './socket.js';
package/dist/index.js CHANGED
@@ -12,6 +12,7 @@
12
12
  * onPlayerState((state) => { ... })
13
13
  */
14
14
  export { invokeHost } from './bridge.js';
15
- export { apiGet, apiPost } from './api.js';
15
+ export { apiGet, apiPost, apiPut, apiDelete } from './api.js';
16
16
  export { onPlayerState, onThemeChange, onPush, } from './events.js';
17
17
  export { getGlobalProps, getFrameId, getTheme } from './globals.js';
18
+ export { PluginSocket } from './socket.js';
@@ -0,0 +1,22 @@
1
+ /** A text WebSocket scoped to the current plugin. Authentication stays in the host. */
2
+ export declare class PluginSocket {
3
+ readonly CONNECTING = 0;
4
+ readonly OPEN = 1;
5
+ readonly CLOSING = 2;
6
+ readonly CLOSED = 3;
7
+ readyState: number;
8
+ onopen: (() => void) | null;
9
+ onmessage: ((event: {
10
+ data: string;
11
+ }) => void) | null;
12
+ onerror: ((event?: unknown) => void) | null;
13
+ onclose: (() => void) | null;
14
+ private readonly id;
15
+ private unsubscribe;
16
+ constructor(path: string);
17
+ private call;
18
+ private fail;
19
+ private finish;
20
+ send(data: string): void;
21
+ close(code?: number, reason?: string): void;
22
+ }
package/dist/socket.js ADDED
@@ -0,0 +1,88 @@
1
+ import { invokeHost } from './bridge.js';
2
+ import { onPush } from './events.js';
3
+ let sequence = 0;
4
+ /** A text WebSocket scoped to the current plugin. Authentication stays in the host. */
5
+ export class PluginSocket {
6
+ constructor(path) {
7
+ this.CONNECTING = 0;
8
+ this.OPEN = 1;
9
+ this.CLOSING = 2;
10
+ this.CLOSED = 3;
11
+ this.readyState = 0;
12
+ this.onopen = null;
13
+ this.onmessage = null;
14
+ this.onerror = null;
15
+ this.onclose = null;
16
+ this.id = `socket-${++sequence}`;
17
+ if (!path.startsWith('/') ||
18
+ path.startsWith('//') ||
19
+ /[\\#\s]/.test(path) ||
20
+ /%/.test(path.split('?')[0]) ||
21
+ path
22
+ .split('?')[0]
23
+ .split('/')
24
+ .some((p) => p === '..' || p === '.'))
25
+ throw new Error('invalid plugin socket path');
26
+ this.unsubscribe = onPush((event, raw) => {
27
+ if (event !== 'pluginSocket')
28
+ return;
29
+ let frame;
30
+ try {
31
+ frame = JSON.parse(String(raw));
32
+ }
33
+ catch {
34
+ return;
35
+ }
36
+ if (!frame ||
37
+ typeof frame !== 'object' ||
38
+ frame.id !== this.id ||
39
+ this.readyState === this.CLOSED)
40
+ return;
41
+ if (frame.type === 'open' && this.readyState === this.CONNECTING) {
42
+ this.readyState = this.OPEN;
43
+ this.onopen?.();
44
+ }
45
+ else if (frame.type === 'message' && this.readyState === this.OPEN)
46
+ this.onmessage?.({ data: frame.data || '' });
47
+ else if (frame.type === 'error')
48
+ this.fail();
49
+ else if (frame.type === 'close')
50
+ this.finish();
51
+ });
52
+ void this.call('socketOpen', { path }).catch(() => this.fail());
53
+ }
54
+ async call(method, params = {}) {
55
+ const result = await invokeHost('plugin', method, {
56
+ ...params,
57
+ id: this.id,
58
+ });
59
+ if (!result.ok)
60
+ throw new Error(result.error || 'plugin socket failed');
61
+ }
62
+ fail() {
63
+ if (this.readyState >= this.CLOSING)
64
+ return;
65
+ this.onerror?.();
66
+ this.finish();
67
+ }
68
+ finish() {
69
+ if (this.readyState === this.CLOSED)
70
+ return;
71
+ this.readyState = this.CLOSED;
72
+ this.unsubscribe();
73
+ this.onclose?.();
74
+ }
75
+ send(data) {
76
+ if (this.readyState !== this.OPEN)
77
+ throw new Error('socket is not open');
78
+ void this.call('socketSend', { data }).catch(() => this.fail());
79
+ }
80
+ close(code = 1000, reason = 'client') {
81
+ if (this.readyState >= this.CLOSING)
82
+ return;
83
+ this.readyState = this.CLOSING;
84
+ void this.call('socketClose', { code, reason })
85
+ .finally(() => this.finish())
86
+ .catch(() => { });
87
+ }
88
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@songloft/lynx-plugin-sdk",
3
- "version": "2.20.0",
3
+ "version": "2.22.0",
4
4
  "description": "SDK for Songloft plugins rendered via Lynx native (renderEngine: lynx)",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -11,11 +11,6 @@
11
11
  "import": "./dist/index.js"
12
12
  }
13
13
  },
14
- "scripts": {
15
- "build": "tsc",
16
- "dev": "tsc --watch",
17
- "test": "node --test tests/*.test.mjs"
18
- },
19
14
  "files": [
20
15
  "dist",
21
16
  "README.md"
@@ -31,5 +26,10 @@
31
26
  "type": "git",
32
27
  "url": "git+https://github.com/songloft-org/plugin-toolchain.git",
33
28
  "directory": "packages/lynx-plugin-sdk"
29
+ },
30
+ "scripts": {
31
+ "build": "tsc",
32
+ "dev": "tsc --watch",
33
+ "test": "node --test tests/*.test.mjs"
34
34
  }
35
- }
35
+ }