@shiqianjiang/ceru-plugin-sdk 0.3.2 → 0.3.5
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 +12 -1
- package/README.md +4 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +1 -0
- package/dist/manifest.d.ts +9 -1
- package/dist/navigation.d.ts +14 -0
- package/dist/navigation.js +24 -0
- package/dist/services.d.ts +2 -5
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,10 +1,21 @@
|
|
|
1
1
|
# SDK 变更记录
|
|
2
2
|
|
|
3
|
-
## 0.3.
|
|
3
|
+
## 0.3.5
|
|
4
|
+
|
|
5
|
+
- Web Surface 自动上报挂载内容高度;Host 可按视口调整短弹框高度,长内容保留滚动,关闭后停止尺寸观察。
|
|
6
|
+
|
|
7
|
+
- 新增 `contributes.playlistSections`:插件的 native Surface 嵌入 Host 现有本地/云歌单页。
|
|
8
|
+
- `ui.navigation.open({ page: 'playlist', sectionId })` 跳转定位调用插件的已声明区块,SDK、Issuer 与 CLI 校验原生视图引用及导航归属。
|
|
9
|
+
- 独立工作台增加 Host 歌单页预览,多区块共用 Core Surface 生命周期;connected-library JS/TS 模板展示页内集成和导航。
|
|
10
|
+
- CLI 保留 0.3.4 的实际包版本查询。
|
|
11
|
+
|
|
12
|
+
## 0.3.3
|
|
4
13
|
|
|
5
14
|
- 新增 Host 原生基础 UI Surface:插件返回经过校验的 `NativeView` 数据,宿主用自己的列表、网格和按钮组件渲染;平台业务与登录流程仍留在插件内。
|
|
6
15
|
- 原生列表支持资源打开、播放及逐项菜单动作;Core 校验所有动作引用,CLI 在 Host DOM 中预览并共享 Surface 生命周期。
|
|
7
16
|
- 新增 `accountItems` 和 `AccountSummary`:插件贡献账号菜单摘要与登录页面,Host 展示头像、昵称和可选会员标签。
|
|
17
|
+
- 账号菜单支持声明 `logoutAction`;Surface 支持 `modal` 展示、Web `ctx.close()` 及逻辑 `ctx.ui.closeView()`,便于插件完成扫码后关闭自己的登录界面。
|
|
18
|
+
- 浏览器沙箱公共服务调用序列化 OperationContext 并传递取消信号,修复调用队列/播放器时 AbortSignal 无法跨窗口克隆的问题。
|
|
8
19
|
|
|
9
20
|
## 0.3.1
|
|
10
21
|
|
package/README.md
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
# Ceru Plugin SDK
|
|
2
2
|
|
|
3
|
+
0.3.5 新增 `contributes.playlistSections`、`HostNavigationRequest` 和 `assertNavigationRequest`。插件通过 `ui.navigation.open({ page: 'playlist', sectionId })` 前往 Host 现有歌单页的原生区块,校验以调用插件的 manifest 为准。
|
|
4
|
+
|
|
3
5
|
## 原生 UI 与账号菜单
|
|
4
6
|
|
|
7
|
+
本节接口由 0.3.3 完整提供。
|
|
8
|
+
|
|
5
9
|
从根入口导入 `defineNativeView`、`NativeView`、`assertNativeView` 和 `AccountSummary`。`kind: 'native'` 的 Surface 以声明的 action 为 render 入口,返回网格/列表与标准内容数据,由 Host 的原生组件渲染。`contributes.accountItems` 以公开摘要动作和账号 Surface 接入 Host 账号菜单;账号业务、凭据和 Vue 登录页面保留在插件内。
|
|
6
10
|
|
|
7
11
|
[原生 Surface、导航、播放与账号贡献教程](https://github.com/CeruMusic/CeruMusic-Plugin-Cli/blob/main/docs/NATIVE-SURFACES.md)。脚手架 `connected-library` 的 JS/TS 示例可直接构建和预览。
|
package/dist/index.d.ts
CHANGED
|
@@ -17,6 +17,7 @@ export * from './guests.js';
|
|
|
17
17
|
export * from './share.js';
|
|
18
18
|
export * from './storage.js';
|
|
19
19
|
export * from './accounts.js';
|
|
20
|
+
export * from './navigation.js';
|
|
20
21
|
export * from './permissions.js';
|
|
21
22
|
export * from './services.js';
|
|
22
23
|
export * from './modules.js';
|
|
@@ -284,6 +285,7 @@ export interface PluginContext extends HostServices {
|
|
|
284
285
|
message: string;
|
|
285
286
|
}): Promise<void>;
|
|
286
287
|
openView(surfaceId: string): Promise<void>;
|
|
288
|
+
closeView(surfaceId: string): Promise<void>;
|
|
287
289
|
};
|
|
288
290
|
storage: PluginStorageAPI;
|
|
289
291
|
guests: GuestAPI & {
|
|
@@ -318,6 +320,8 @@ export interface SurfaceContext extends Pick<PluginContext, 'host' | 'utils' | '
|
|
|
318
320
|
mode?: 'append' | 'prepend' | 'wrap' | 'replace';
|
|
319
321
|
};
|
|
320
322
|
invoke(action: string, input: JsonValue): Promise<JsonValue>;
|
|
323
|
+
/** Close this mounted Surface after its current action has returned. */
|
|
324
|
+
close(): Promise<void>;
|
|
321
325
|
subscribe(handler: (state: JsonObject) => void): Disposable;
|
|
322
326
|
}
|
|
323
327
|
export interface GuestContext extends Pick<PluginContext, 'host' | 'utils'>, GuestBootstrapAPI {
|
package/dist/index.js
CHANGED
|
@@ -9,6 +9,7 @@ export * from './guests.js';
|
|
|
9
9
|
export * from './share.js';
|
|
10
10
|
export * from './storage.js';
|
|
11
11
|
export * from './accounts.js';
|
|
12
|
+
export * from './navigation.js';
|
|
12
13
|
export * from './permissions.js';
|
|
13
14
|
export * from './services.js';
|
|
14
15
|
export * from './modules.js';
|
package/dist/manifest.d.ts
CHANGED
|
@@ -40,7 +40,7 @@ export interface SurfaceDeclaration {
|
|
|
40
40
|
/** Host chrome only. The plugin owns all content inside a web Surface. */
|
|
41
41
|
title?: string;
|
|
42
42
|
presentation?: {
|
|
43
|
-
kind: 'drawer';
|
|
43
|
+
kind: 'drawer' | 'modal';
|
|
44
44
|
placement?: 'left' | 'right' | 'top' | 'bottom';
|
|
45
45
|
size?: number;
|
|
46
46
|
};
|
|
@@ -122,6 +122,13 @@ export interface PluginManifest {
|
|
|
122
122
|
providers?: ProviderDeclaration[];
|
|
123
123
|
/** Home tabs exist only while at least one enabled plugin contributes them. */
|
|
124
124
|
homeSections?: HomeSectionContribution[];
|
|
125
|
+
/** Native sections inside the Host's existing local/cloud playlist page. */
|
|
126
|
+
playlistSections?: {
|
|
127
|
+
id: string;
|
|
128
|
+
title: string;
|
|
129
|
+
view: string;
|
|
130
|
+
order?: number;
|
|
131
|
+
}[];
|
|
125
132
|
/** Controlled UI composition. The Host owns the target DOM and lifecycle. */
|
|
126
133
|
uiExtensions?: UIExtensionContribution[];
|
|
127
134
|
/** Surface/slot styles are scoped. Application styles require ui.styles.global. */
|
|
@@ -153,6 +160,7 @@ export interface PluginManifest {
|
|
|
153
160
|
title: string;
|
|
154
161
|
view: string;
|
|
155
162
|
action: string;
|
|
163
|
+
logoutAction?: string;
|
|
156
164
|
}[];
|
|
157
165
|
sidebarItems?: {
|
|
158
166
|
id: string;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { ResourceRef } from './index.js';
|
|
2
|
+
import type { PluginManifest } from './manifest.js';
|
|
3
|
+
export type HostNavigationRequest = {
|
|
4
|
+
query?: string;
|
|
5
|
+
ref?: ResourceRef;
|
|
6
|
+
} & ({
|
|
7
|
+
page: 'playlist';
|
|
8
|
+
sectionId?: string;
|
|
9
|
+
} | {
|
|
10
|
+
page: 'search' | 'charts' | 'downloads' | 'account' | 'settings';
|
|
11
|
+
sectionId?: never;
|
|
12
|
+
});
|
|
13
|
+
/** Validate using the calling plugin's manifest, never a caller-supplied owner ID. */
|
|
14
|
+
export declare function assertNavigationRequest(value: unknown, manifest?: PluginManifest): asserts value is HostNavigationRequest;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { assertResourceRef } from './music.js';
|
|
2
|
+
/** Validate using the calling plugin's manifest, never a caller-supplied owner ID. */
|
|
3
|
+
export function assertNavigationRequest(value, manifest) {
|
|
4
|
+
const request = value;
|
|
5
|
+
if (!request ||
|
|
6
|
+
typeof request !== 'object' ||
|
|
7
|
+
Array.isArray(request) ||
|
|
8
|
+
!['search', 'playlist', 'charts', 'downloads', 'account', 'settings'].includes(request.page) ||
|
|
9
|
+
(request.query !== undefined &&
|
|
10
|
+
(typeof request.query !== 'string' || request.query.length > 8192)))
|
|
11
|
+
throw new Error('Invalid Host navigation request');
|
|
12
|
+
if (request.ref !== undefined)
|
|
13
|
+
assertResourceRef(request.ref);
|
|
14
|
+
if (request.sectionId !== undefined) {
|
|
15
|
+
if (request.page !== 'playlist' ||
|
|
16
|
+
typeof request.sectionId !== 'string' ||
|
|
17
|
+
!request.sectionId.length ||
|
|
18
|
+
request.sectionId.length > 128)
|
|
19
|
+
throw new Error('sectionId is only valid for playlist navigation');
|
|
20
|
+
if (manifest &&
|
|
21
|
+
!manifest.contributes?.playlistSections?.some((section) => section.id === request.sectionId))
|
|
22
|
+
throw new Error('Unknown playlist section: ' + request.sectionId);
|
|
23
|
+
}
|
|
24
|
+
}
|
package/dist/services.d.ts
CHANGED
|
@@ -3,6 +3,7 @@ import type { ContentEntity, MusicFault, OperationContext, Page, ResourceRef, As
|
|
|
3
3
|
import type { LibraryPlaylist, PlaylistReference } from './library.js';
|
|
4
4
|
import type { LyricsDocument } from './music.js';
|
|
5
5
|
import type { PermissionGroup } from './permissions.js';
|
|
6
|
+
import type { HostNavigationRequest } from './navigation.js';
|
|
6
7
|
/** Supplied by Host actions/events. Never construct trusted intents from plugin JSON. */
|
|
7
8
|
export interface ServiceCall {
|
|
8
9
|
operation: OperationContext;
|
|
@@ -284,11 +285,7 @@ export interface HostUI {
|
|
|
284
285
|
}): Promise<LibraryPlaylist | null>;
|
|
285
286
|
};
|
|
286
287
|
navigation: {
|
|
287
|
-
open(request:
|
|
288
|
-
page: 'search' | 'playlist' | 'charts' | 'downloads' | 'account' | 'settings';
|
|
289
|
-
query?: string;
|
|
290
|
-
ref?: ResourceRef;
|
|
291
|
-
}): Promise<void>;
|
|
288
|
+
open(request: HostNavigationRequest): Promise<void>;
|
|
292
289
|
};
|
|
293
290
|
notifications: {
|
|
294
291
|
show(request: {
|