@shiqianjiang/ceru-plugin-sdk 0.3.1 → 0.3.3
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/CHANGELOG.md +8 -0
- package/README.md +8 -0
- package/dist/accounts.d.ts +8 -0
- package/dist/accounts.js +18 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.js +2 -0
- package/dist/manifest.d.ts +11 -2
- package/dist/native-view.d.ts +30 -0
- package/dist/native-view.js +67 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# SDK 变更记录
|
|
2
2
|
|
|
3
|
+
## 0.3.3
|
|
4
|
+
|
|
5
|
+
- 新增 Host 原生基础 UI Surface:插件返回经过校验的 `NativeView` 数据,宿主用自己的列表、网格和按钮组件渲染;平台业务与登录流程仍留在插件内。
|
|
6
|
+
- 原生列表支持资源打开、播放及逐项菜单动作;Core 校验所有动作引用,CLI 在 Host DOM 中预览并共享 Surface 生命周期。
|
|
7
|
+
- 新增 `accountItems` 和 `AccountSummary`:插件贡献账号菜单摘要与登录页面,Host 展示头像、昵称和可选会员标签。
|
|
8
|
+
- 账号菜单支持声明 `logoutAction`;Surface 支持 `modal` 展示、Web `ctx.close()` 及逻辑 `ctx.ui.closeView()`,便于插件完成扫码后关闭自己的登录界面。
|
|
9
|
+
- 浏览器沙箱公共服务调用序列化 OperationContext 并传递取消信号,修复调用队列/播放器时 AbortSignal 无法跨窗口克隆的问题。
|
|
10
|
+
|
|
3
11
|
## 0.3.1
|
|
4
12
|
|
|
5
13
|
- 播放解析结果新增 `requestHeaders`,供 Host 在获取对应临时媒体地址时附加防盗链、认证或客户端请求头;请求头只保留在 Host 主进程,并按完整 URL 与到期时间隔离。
|
package/README.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Ceru Plugin SDK
|
|
2
2
|
|
|
3
|
+
## 原生 UI 与账号菜单
|
|
4
|
+
|
|
5
|
+
本节接口由 0.3.3 完整提供。
|
|
6
|
+
|
|
7
|
+
从根入口导入 `defineNativeView`、`NativeView`、`assertNativeView` 和 `AccountSummary`。`kind: 'native'` 的 Surface 以声明的 action 为 render 入口,返回网格/列表与标准内容数据,由 Host 的原生组件渲染。`contributes.accountItems` 以公开摘要动作和账号 Surface 接入 Host 账号菜单;账号业务、凭据和 Vue 登录页面保留在插件内。
|
|
8
|
+
|
|
9
|
+
[原生 Surface、导航、播放与账号贡献教程](https://github.com/CeruMusic/CeruMusic-Plugin-Cli/blob/main/docs/NATIVE-SURFACES.md)。脚手架 `connected-library` 的 JS/TS 示例可直接构建和预览。
|
|
10
|
+
|
|
3
11
|
## 0.2.5 类型同步
|
|
4
12
|
|
|
5
13
|
0.2.5 补齐桌面 v2 已使用的 Guest、分享解析、Storage、插件更新和导入界面契约。
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/** Public account presentation. Credentials and platform login flows remain in plugin logic. */
|
|
2
|
+
export type AccountSummary = {
|
|
3
|
+
signedIn: boolean;
|
|
4
|
+
displayName: string;
|
|
5
|
+
avatarUrl?: string;
|
|
6
|
+
badge?: string;
|
|
7
|
+
};
|
|
8
|
+
export declare function assertAccountSummary(value: unknown): asserts value is AccountSummary;
|
package/dist/accounts.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export function assertAccountSummary(value) {
|
|
2
|
+
const account = value;
|
|
3
|
+
if (!account ||
|
|
4
|
+
typeof account !== 'object' ||
|
|
5
|
+
Array.isArray(account) ||
|
|
6
|
+
typeof account.signedIn !== 'boolean' ||
|
|
7
|
+
typeof account.displayName !== 'string' ||
|
|
8
|
+
!account.displayName.length ||
|
|
9
|
+
account.displayName.length > 200 ||
|
|
10
|
+
(account.badge !== undefined &&
|
|
11
|
+
(typeof account.badge !== 'string' || account.badge.length > 80)))
|
|
12
|
+
throw new Error('Invalid account summary');
|
|
13
|
+
if (account.avatarUrl !== undefined &&
|
|
14
|
+
(typeof account.avatarUrl !== 'string' ||
|
|
15
|
+
account.avatarUrl.length > 8192 ||
|
|
16
|
+
!/^https?:\/\//i.test(account.avatarUrl)))
|
|
17
|
+
throw new Error('Invalid account avatar URL');
|
|
18
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -16,6 +16,7 @@ export * from './quality.js';
|
|
|
16
16
|
export * from './guests.js';
|
|
17
17
|
export * from './share.js';
|
|
18
18
|
export * from './storage.js';
|
|
19
|
+
export * from './accounts.js';
|
|
19
20
|
export * from './permissions.js';
|
|
20
21
|
export * from './services.js';
|
|
21
22
|
export * from './modules.js';
|
|
@@ -283,6 +284,7 @@ export interface PluginContext extends HostServices {
|
|
|
283
284
|
message: string;
|
|
284
285
|
}): Promise<void>;
|
|
285
286
|
openView(surfaceId: string): Promise<void>;
|
|
287
|
+
closeView(surfaceId: string): Promise<void>;
|
|
286
288
|
};
|
|
287
289
|
storage: PluginStorageAPI;
|
|
288
290
|
guests: GuestAPI & {
|
|
@@ -317,6 +319,8 @@ export interface SurfaceContext extends Pick<PluginContext, 'host' | 'utils' | '
|
|
|
317
319
|
mode?: 'append' | 'prepend' | 'wrap' | 'replace';
|
|
318
320
|
};
|
|
319
321
|
invoke(action: string, input: JsonValue): Promise<JsonValue>;
|
|
322
|
+
/** Close this mounted Surface after its current action has returned. */
|
|
323
|
+
close(): Promise<void>;
|
|
320
324
|
subscribe(handler: (state: JsonObject) => void): Disposable;
|
|
321
325
|
}
|
|
322
326
|
export interface GuestContext extends Pick<PluginContext, 'host' | 'utils'>, GuestBootstrapAPI {
|
|
@@ -329,6 +333,8 @@ export type SurfaceEntry = (ctx: SurfaceContext) => MaybePromise<void | Disposab
|
|
|
329
333
|
export type GuestEntry = (ctx: GuestContext) => MaybePromise<void | Disposable>;
|
|
330
334
|
export declare function definePlugin(entry: LogicEntry): LogicEntry;
|
|
331
335
|
export declare function defineSurface(entry: SurfaceEntry): SurfaceEntry;
|
|
336
|
+
export { defineNativeView, assertNativeView } from './native-view.js';
|
|
337
|
+
export type { NativeView, NativeViewSection, NativeViewAction } from './native-view.js';
|
|
332
338
|
export declare function defineGuestAdapter(entry: GuestEntry): GuestEntry;
|
|
333
339
|
export declare function defineManifest(manifest: PluginManifest): PluginManifest;
|
|
334
340
|
export declare function definePluginConfig<const T extends JsonObject>(config: T): T;
|
package/dist/index.js
CHANGED
|
@@ -8,6 +8,7 @@ export * from './quality.js';
|
|
|
8
8
|
export * from './guests.js';
|
|
9
9
|
export * from './share.js';
|
|
10
10
|
export * from './storage.js';
|
|
11
|
+
export * from './accounts.js';
|
|
11
12
|
export * from './permissions.js';
|
|
12
13
|
export * from './services.js';
|
|
13
14
|
export * from './modules.js';
|
|
@@ -18,6 +19,7 @@ export function definePlugin(entry) {
|
|
|
18
19
|
export function defineSurface(entry) {
|
|
19
20
|
return entry;
|
|
20
21
|
}
|
|
22
|
+
export { defineNativeView, assertNativeView } from './native-view.js';
|
|
21
23
|
export function defineGuestAdapter(entry) {
|
|
22
24
|
return entry;
|
|
23
25
|
}
|
package/dist/manifest.d.ts
CHANGED
|
@@ -34,12 +34,13 @@ export interface ProviderDeclaration {
|
|
|
34
34
|
}
|
|
35
35
|
export interface SurfaceDeclaration {
|
|
36
36
|
id: string;
|
|
37
|
-
kind: 'schema' | 'web';
|
|
37
|
+
kind: 'schema' | 'web' | 'native';
|
|
38
|
+
/** Native: declared action returning NativeView; Web: module; Schema: JSON resource. */
|
|
38
39
|
entry: string;
|
|
39
40
|
/** Host chrome only. The plugin owns all content inside a web Surface. */
|
|
40
41
|
title?: string;
|
|
41
42
|
presentation?: {
|
|
42
|
-
kind: 'drawer';
|
|
43
|
+
kind: 'drawer' | 'modal';
|
|
43
44
|
placement?: 'left' | 'right' | 'top' | 'bottom';
|
|
44
45
|
size?: number;
|
|
45
46
|
};
|
|
@@ -146,6 +147,14 @@ export interface PluginManifest {
|
|
|
146
147
|
action: string;
|
|
147
148
|
view?: string;
|
|
148
149
|
}[];
|
|
150
|
+
/** Subaccounts in the Host account menu. action returns AccountSummary; view owns login UI. */
|
|
151
|
+
accountItems?: {
|
|
152
|
+
id: string;
|
|
153
|
+
title: string;
|
|
154
|
+
view: string;
|
|
155
|
+
action: string;
|
|
156
|
+
logoutAction?: string;
|
|
157
|
+
}[];
|
|
149
158
|
sidebarItems?: {
|
|
150
159
|
id: string;
|
|
151
160
|
group: string;
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { ContentEntity, JsonValue, MaybePromise, OperationContext } from './index.js';
|
|
2
|
+
export interface NativeViewAction {
|
|
3
|
+
label: string;
|
|
4
|
+
action: string;
|
|
5
|
+
input?: JsonValue;
|
|
6
|
+
primary?: boolean;
|
|
7
|
+
}
|
|
8
|
+
export interface NativeViewSection {
|
|
9
|
+
id: string;
|
|
10
|
+
title?: string;
|
|
11
|
+
layout: 'grid' | 'list';
|
|
12
|
+
items: ContentEntity[];
|
|
13
|
+
/** Receives { ref }; typically opens a native playlist page. */
|
|
14
|
+
onOpen?: string;
|
|
15
|
+
/** Receives { ref, refs }; typically replaces the native playback queue. */
|
|
16
|
+
onPlay?: string;
|
|
17
|
+
/** Receives the action input merged with { ref }; the Host supplies the item's ref. */
|
|
18
|
+
itemActions?: NativeViewAction[];
|
|
19
|
+
}
|
|
20
|
+
/** Rendered using Host components. No plugin DOM, iframe, or framework runs in this surface. */
|
|
21
|
+
export interface NativeView {
|
|
22
|
+
type: 'page';
|
|
23
|
+
title?: string;
|
|
24
|
+
description?: string;
|
|
25
|
+
actions?: NativeViewAction[];
|
|
26
|
+
sections: NativeViewSection[];
|
|
27
|
+
}
|
|
28
|
+
/** A typed render callback that can be passed directly to ctx.actions.register. */
|
|
29
|
+
export declare function defineNativeView<TInput extends JsonValue = JsonValue>(render: (input: TInput, operation: OperationContext) => MaybePromise<NativeView>): (input: TInput, operation: OperationContext) => Promise<NativeView & JsonValue>;
|
|
30
|
+
export declare function assertNativeView(value: unknown, actions?: ReadonlySet<string>): asserts value is NativeView;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import { assertContentPage } from './music.js';
|
|
2
|
+
/** A typed render callback that can be passed directly to ctx.actions.register. */
|
|
3
|
+
export function defineNativeView(render) {
|
|
4
|
+
return async (input, operation) => {
|
|
5
|
+
const value = await render(input, operation);
|
|
6
|
+
assertNativeView(value);
|
|
7
|
+
return value;
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
function assertJson(value, ancestors = new Set()) {
|
|
11
|
+
if (value === null || typeof value === 'string' || typeof value === 'boolean')
|
|
12
|
+
return;
|
|
13
|
+
if (typeof value === 'number' && Number.isFinite(value))
|
|
14
|
+
return;
|
|
15
|
+
if (!value || typeof value !== 'object' || ancestors.has(value))
|
|
16
|
+
throw new Error('Native view must contain JSON data only');
|
|
17
|
+
if (!Array.isArray(value) &&
|
|
18
|
+
Object.getPrototypeOf(value) !== Object.prototype &&
|
|
19
|
+
Object.getPrototypeOf(value) !== null)
|
|
20
|
+
throw new Error('Native view must contain JSON data only');
|
|
21
|
+
ancestors.add(value);
|
|
22
|
+
for (const item of Object.values(value))
|
|
23
|
+
if (item !== undefined)
|
|
24
|
+
assertJson(item, ancestors);
|
|
25
|
+
ancestors.delete(value);
|
|
26
|
+
}
|
|
27
|
+
export function assertNativeView(value, actions) {
|
|
28
|
+
assertJson(value);
|
|
29
|
+
const v = value;
|
|
30
|
+
const text = (s, max = 500) => typeof s === 'string' && s.length <= max;
|
|
31
|
+
const action = (s) => text(s, 128) && !!s && (!actions || actions.has(s));
|
|
32
|
+
if (!v ||
|
|
33
|
+
v.type !== 'page' ||
|
|
34
|
+
!Array.isArray(v.sections) ||
|
|
35
|
+
v.sections.length > 24 ||
|
|
36
|
+
(v.title !== undefined && !text(v.title)) ||
|
|
37
|
+
(v.description !== undefined && !text(v.description, 4000)))
|
|
38
|
+
throw new Error('Invalid native view');
|
|
39
|
+
const validateActions = (items) => {
|
|
40
|
+
if (items !== undefined && (!Array.isArray(items) || items.length > 16))
|
|
41
|
+
throw new Error('Invalid native actions');
|
|
42
|
+
for (const item of items ?? [])
|
|
43
|
+
if (!item ||
|
|
44
|
+
!text(item.label, 100) ||
|
|
45
|
+
!item.label ||
|
|
46
|
+
!action(item.action) ||
|
|
47
|
+
(item.primary !== undefined && typeof item.primary !== 'boolean') ||
|
|
48
|
+
JSON.stringify(item.input ?? {}).length > 16384)
|
|
49
|
+
throw new Error('Invalid native action');
|
|
50
|
+
};
|
|
51
|
+
validateActions(v.actions);
|
|
52
|
+
const ids = new Set();
|
|
53
|
+
for (const section of v.sections) {
|
|
54
|
+
if (!section ||
|
|
55
|
+
!text(section.id, 128) ||
|
|
56
|
+
!section.id ||
|
|
57
|
+
ids.has(section.id) ||
|
|
58
|
+
!['grid', 'list'].includes(section.layout) ||
|
|
59
|
+
(section.title !== undefined && !text(section.title)) ||
|
|
60
|
+
(section.onOpen !== undefined && !action(section.onOpen)) ||
|
|
61
|
+
(section.onPlay !== undefined && !action(section.onPlay)))
|
|
62
|
+
throw new Error('Invalid native section');
|
|
63
|
+
ids.add(section.id);
|
|
64
|
+
validateActions(section.itemActions);
|
|
65
|
+
assertContentPage({ items: section.items });
|
|
66
|
+
}
|
|
67
|
+
}
|