@songloft/lynx-plugin-sdk 2.20.0 → 2.21.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/README.md +22 -3
- package/dist/api.d.ts +2 -0
- package/dist/api.js +2 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/socket.d.ts +22 -0
- package/dist/socket.js +88 -0
- package/package.json +7 -7
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';
|
package/dist/socket.d.ts
ADDED
|
@@ -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.
|
|
3
|
+
"version": "2.21.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
|
+
}
|