@shiqianjiang/ceru-plugin-sdk 0.2.3 → 0.3.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/CHANGELOG.md +21 -0
- package/README.md +27 -0
- package/dist/compat/crypto.d.ts +13 -7
- package/dist/compat/crypto.js +6 -0
- package/dist/compat/zlib.d.ts +1 -1
- package/dist/compat/zlib.js +1 -0
- package/dist/guests.d.ts +44 -0
- package/dist/guests.js +1 -0
- package/dist/index.d.ts +33 -16
- package/dist/index.js +5 -0
- package/dist/library.d.ts +5 -3
- package/dist/lyrics.d.ts +26 -0
- package/dist/lyrics.js +1 -0
- package/dist/manifest.d.ts +39 -0
- package/dist/music.d.ts +7 -1
- package/dist/music.js +3 -0
- package/dist/quality.d.ts +3 -0
- package/dist/quality.js +18 -0
- package/dist/services.d.ts +3 -0
- package/dist/share.d.ts +54 -0
- package/dist/share.js +1 -0
- package/dist/storage.d.ts +18 -0
- package/dist/storage.js +1 -0
- package/package.json +29 -1
- /package/dist/{host-modules.d.ts → host-modules.d.cts} +0 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# SDK 变更记录
|
|
2
|
+
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
- 正式声明 Web Surface 的 title、presentation 和 lifecycle;界面与业务由插件实现,宿主仅提供容器。
|
|
6
|
+
- CLI 和 Core 共用 SurfaceSession,统一打开、关闭、取消请求和过期会话校验。
|
|
7
|
+
- 开发工作台按页面分发状态,支持关闭页面和私有存储持久化;页面不接收清单中的默认凭据。
|
|
8
|
+
- Core 正式导出 /guests、/surface、/surface-document,恢复已使用的 Guest 和分享能力,消除本机 node_modules 补丁。
|
|
9
|
+
- 五个工具链包与脚手架模板统一到 0.3.0。以下 0.2.5 的类型改动一并发布。
|
|
10
|
+
|
|
11
|
+
## 0.2.5
|
|
12
|
+
|
|
13
|
+
- 从根入口及 `/guests`、`/share`、`/storage` 导出 Guest、分享解析与存储类型。
|
|
14
|
+
- 同步 PluginContext 的 Guest 管理、插件更新、歌单导入参数与 Storage 空值/共享键签名。
|
|
15
|
+
- 补齐 GuestBootstrapAPI、Manifest 分享入口、命令说明、Guest 展示信息与菜单说明。
|
|
16
|
+
- 打包前自动构建并检查公开导出文件,避免源码中存在但 npm tarball 缺失。
|
|
17
|
+
- 新增真实打包、隔离安装、严格类型检查及运行时子路径导入测试。
|
|
18
|
+
- 将 CommonJS 宿主模块声明明确标为 .d.cts,兼容 NodeNext 与 Bundler 模式。
|
|
19
|
+
- 避免公开 Buffer 返回类型依赖开发环境中的 Node Buffer 泛型声明。
|
|
20
|
+
|
|
21
|
+
运行能力由 Host 决定;本次类型补充不会为旧宿主添加业务实现。
|
package/README.md
CHANGED
|
@@ -1,5 +1,32 @@
|
|
|
1
1
|
# Ceru Plugin SDK
|
|
2
2
|
|
|
3
|
+
## 0.2.5 类型同步
|
|
4
|
+
|
|
5
|
+
0.2.5 补齐桌面 v2 已使用的 Guest、分享解析、Storage、插件更新和导入界面契约。
|
|
6
|
+
Guest / 分享 / 存储类型可从包根入口导入,也可分别从 `/guests`、`/share`、`/storage` 导入:
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import type {
|
|
10
|
+
GuestInfo,
|
|
11
|
+
GuestBootstrapAPI,
|
|
12
|
+
ShareResolverEntry,
|
|
13
|
+
PluginStorageAPI,
|
|
14
|
+
} from '@shiqianjiang/ceru-plugin-sdk'
|
|
15
|
+
import type { GuestInfo as Guest } from '@shiqianjiang/ceru-plugin-sdk/guests'
|
|
16
|
+
import type { ShareResolverEntry as Resolver } from '@shiqianjiang/ceru-plugin-sdk/share'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
`PluginContext.storage` 支持桌面结构化键、`readableBy` 与 `null` 空值;
|
|
20
|
+
`guests` 补齐 `import/select/remove` 和完整信息;`GuestContext` 包含 bootstrap 契约;
|
|
21
|
+
`ui.pluginUpdate.request` 和导入窗口的可选 `importerId/title` 也已声明。
|
|
22
|
+
|
|
23
|
+
这些类型描述宿主契约,不会让旧 Host 或 CLI 工作台自动获得对应能力。
|
|
24
|
+
Manifest 的分享入口和 Guest 展示字段还需要匹配的构建器与校验器。
|
|
25
|
+
`prepareInstall/requestInstall` 保留旧声明,桌面优先使用 `guests.import`。
|
|
26
|
+
|
|
27
|
+
`npm pack` 会先编译 SDK、复制必要的 ambient 声明,并检查每个 exports 目标存在。
|
|
28
|
+
仓库的 `npm run test:sdk-package` 将真实 tarball 安装到空项目中,验证根入口、子路径和类型约束。
|
|
29
|
+
|
|
3
30
|
面向 Ceru Music v2 的 TypeScript 类型与小型作者辅助函数。
|
|
4
31
|
|
|
5
32
|
包含 PluginContext、分组 Provider、歌曲/歌词/歌单标准数据、宿主服务、权限组、Surface、资源引用、结构化错误、UI Slot、图标名和类型化 Lodash。运行能力由 Host 提供,SDK 本身不授予权限。
|
package/dist/compat/crypto.d.ts
CHANGED
|
@@ -1,17 +1,23 @@
|
|
|
1
1
|
export function createHash(name: any): {
|
|
2
2
|
update(value: any): /*elided*/ any;
|
|
3
|
-
|
|
3
|
+
/** @returns {string | Buffer} */
|
|
4
|
+
digest(encoding: any): string | Buffer;
|
|
4
5
|
};
|
|
5
|
-
|
|
6
|
+
/** @returns {Buffer} */
|
|
7
|
+
export function publicEncrypt(options: any, value: any): Buffer;
|
|
6
8
|
export function createCipheriv(mode: any, key: any, iv: any): {
|
|
7
|
-
|
|
8
|
-
|
|
9
|
+
/** @returns {Buffer} */
|
|
10
|
+
update(value: any): Buffer;
|
|
11
|
+
/** @returns {Buffer} */
|
|
12
|
+
final(): Buffer;
|
|
9
13
|
};
|
|
10
14
|
export function createDecipheriv(mode: any, key: any, iv: any): {
|
|
11
|
-
|
|
12
|
-
|
|
15
|
+
/** @returns {Buffer} */
|
|
16
|
+
update(value: any): Buffer;
|
|
17
|
+
/** @returns {Buffer} */
|
|
18
|
+
final(): Buffer;
|
|
13
19
|
};
|
|
14
|
-
export function randomBytes(size: any): Buffer
|
|
20
|
+
export function randomBytes(size: any): Buffer;
|
|
15
21
|
export function randomUUID(): `${string}-${string}-${string}-${string}-${string}`;
|
|
16
22
|
export namespace constants {
|
|
17
23
|
let RSA_NO_PADDING: number;
|
package/dist/compat/crypto.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import CryptoJS from 'crypto-js';
|
|
2
2
|
import { Buffer } from 'buffer';
|
|
3
3
|
const words = (value) => CryptoJS.enc.Hex.parse(Buffer.from(value).toString('hex'));
|
|
4
|
+
/** @returns {Buffer} */
|
|
4
5
|
const bytes = (value) => Buffer.from(value.toString(CryptoJS.enc.Hex), 'hex');
|
|
5
6
|
export function createHash(name) {
|
|
6
7
|
const factory = {
|
|
@@ -16,6 +17,7 @@ export function createHash(name) {
|
|
|
16
17
|
hash.update(words(value));
|
|
17
18
|
return this;
|
|
18
19
|
},
|
|
20
|
+
/** @returns {string | Buffer} */
|
|
19
21
|
digest(encoding) {
|
|
20
22
|
const result = bytes(hash.finalize());
|
|
21
23
|
return encoding ? result.toString(encoding) : result;
|
|
@@ -27,10 +29,12 @@ function cipher(mode, key, iv, decrypt) {
|
|
|
27
29
|
throw new Error('Unsupported cipher: ' + mode);
|
|
28
30
|
const chunks = [];
|
|
29
31
|
return {
|
|
32
|
+
/** @returns {Buffer} */
|
|
30
33
|
update(value) {
|
|
31
34
|
chunks.push(Buffer.from(value));
|
|
32
35
|
return Buffer.alloc(0);
|
|
33
36
|
},
|
|
37
|
+
/** @returns {Buffer} */
|
|
34
38
|
final() {
|
|
35
39
|
const data = words(Buffer.concat(chunks));
|
|
36
40
|
const options = {
|
|
@@ -46,10 +50,12 @@ function cipher(mode, key, iv, decrypt) {
|
|
|
46
50
|
}
|
|
47
51
|
export const createCipheriv = (mode, key, iv) => cipher(mode, key, iv, false);
|
|
48
52
|
export const createDecipheriv = (mode, key, iv) => cipher(mode, key, iv, true);
|
|
53
|
+
/** @returns {Buffer} */
|
|
49
54
|
export const randomBytes = (size) => Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(size)));
|
|
50
55
|
export const randomUUID = () => globalThis.crypto.randomUUID();
|
|
51
56
|
export const constants = { RSA_NO_PADDING: 3 };
|
|
52
57
|
// SPKI public-key parsing for the existing NetEase no-padding RSA request format.
|
|
58
|
+
/** @returns {Buffer} */
|
|
53
59
|
export function publicEncrypt(options, value) {
|
|
54
60
|
if (options.padding !== constants.RSA_NO_PADDING)
|
|
55
61
|
throw new Error('Unsupported RSA padding');
|
package/dist/compat/zlib.d.ts
CHANGED
package/dist/compat/zlib.js
CHANGED
package/dist/guests.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { Disposable, JsonValue } from './manifest.js';
|
|
2
|
+
import type { OperationContext } from './index.js';
|
|
3
|
+
export interface GuestProvider {
|
|
4
|
+
id: string;
|
|
5
|
+
name: string;
|
|
6
|
+
/** Lowest to highest, as declared by the imported script. */
|
|
7
|
+
qualities: string[];
|
|
8
|
+
protocols: string[];
|
|
9
|
+
}
|
|
10
|
+
export interface GuestInfo {
|
|
11
|
+
id: string;
|
|
12
|
+
adapterId: string;
|
|
13
|
+
name: string;
|
|
14
|
+
version: string;
|
|
15
|
+
author?: string;
|
|
16
|
+
state: 'ready' | 'stopped' | 'error';
|
|
17
|
+
selected: boolean;
|
|
18
|
+
providers: GuestProvider[];
|
|
19
|
+
error?: string;
|
|
20
|
+
}
|
|
21
|
+
/** Requires a Host with Guest management support; the SDK does not install Guest runtimes. */
|
|
22
|
+
export interface GuestAPI {
|
|
23
|
+
list(): Promise<GuestInfo[]>;
|
|
24
|
+
/** The Host owns file selection and approval. Cancellation returns null. */
|
|
25
|
+
import(adapterId: string): Promise<GuestInfo | null>;
|
|
26
|
+
select(guestId: string | null): Promise<void>;
|
|
27
|
+
remove(guestId: string): Promise<void>;
|
|
28
|
+
invoke(guestId: string, method: string, input: JsonValue, operation: OperationContext): Promise<JsonValue>;
|
|
29
|
+
}
|
|
30
|
+
export interface GuestBootstrapAPI {
|
|
31
|
+
readonly scriptInfo: Readonly<{
|
|
32
|
+
name: string;
|
|
33
|
+
version: string;
|
|
34
|
+
author?: string;
|
|
35
|
+
description?: string;
|
|
36
|
+
homepage?: string;
|
|
37
|
+
rawScript: string;
|
|
38
|
+
}>;
|
|
39
|
+
ready(metadata: {
|
|
40
|
+
providers: GuestProvider[];
|
|
41
|
+
}): void;
|
|
42
|
+
handle(handler: (method: string, input: JsonValue, operation: OperationContext) => Promise<JsonValue>): Disposable;
|
|
43
|
+
invokeHost(method: string, input: JsonValue): Promise<JsonValue>;
|
|
44
|
+
}
|
package/dist/guests.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/// <reference path="./host-modules.d.
|
|
1
|
+
/// <reference path="./host-modules.d.cts" />
|
|
2
2
|
/** This package defines the v2 wire/authoring contract. It does not grant Host permissions. */
|
|
3
3
|
import type { LoDashStatic } from 'lodash';
|
|
4
4
|
import type { HostIconName, HostAssetName, LODASH_METHODS } from './catalog.js';
|
|
@@ -7,8 +7,15 @@ export * from './http.js';
|
|
|
7
7
|
export * from './library.js';
|
|
8
8
|
export * from './sockets.js';
|
|
9
9
|
import type { SocketAPI } from './sockets.js';
|
|
10
|
+
import type { GuestAPI, GuestBootstrapAPI } from './guests.js';
|
|
11
|
+
import type { PluginStorageAPI } from './storage.js';
|
|
10
12
|
import type { createHttpClient, HttpClientOptions } from './http.js';
|
|
11
13
|
export * from './music.js';
|
|
14
|
+
export * from './lyrics.js';
|
|
15
|
+
export * from './quality.js';
|
|
16
|
+
export * from './guests.js';
|
|
17
|
+
export * from './share.js';
|
|
18
|
+
export * from './storage.js';
|
|
12
19
|
export * from './permissions.js';
|
|
13
20
|
export * from './services.js';
|
|
14
21
|
export * from './modules.js';
|
|
@@ -79,6 +86,7 @@ export interface SearchRequest {
|
|
|
79
86
|
kinds: string[];
|
|
80
87
|
filters: JsonObject;
|
|
81
88
|
cursor?: string;
|
|
89
|
+
/** Requested size; providers may clamp to their upstream API's supported range. */
|
|
82
90
|
limit: number;
|
|
83
91
|
}
|
|
84
92
|
export interface MusicFault {
|
|
@@ -116,7 +124,7 @@ export interface PlaylistProvider {
|
|
|
116
124
|
search?(request: SearchRequest, operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
117
125
|
categories?(operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
118
126
|
list?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
119
|
-
get?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<
|
|
127
|
+
get?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<import('./library.js').PlaylistTrackPage>;
|
|
120
128
|
}
|
|
121
129
|
export interface ChartProvider {
|
|
122
130
|
list?(operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
@@ -189,6 +197,9 @@ export interface PluginContext extends HostServices {
|
|
|
189
197
|
playlistImporters: {
|
|
190
198
|
register(id: string, implementation: PlaylistImporterImplementation): Disposable;
|
|
191
199
|
};
|
|
200
|
+
lyricConverters: {
|
|
201
|
+
register(id: string, implementation: import('./lyrics.js').LyricConverter): Disposable;
|
|
202
|
+
};
|
|
192
203
|
providers: {
|
|
193
204
|
register(id: string, implementation: ProviderImplementation): Disposable;
|
|
194
205
|
};
|
|
@@ -243,11 +254,26 @@ export interface PluginContext extends HostServices {
|
|
|
243
254
|
}): Promise<void>;
|
|
244
255
|
/** Opens the application's existing import dialog. This does not create a plugin Surface. */
|
|
245
256
|
playlistImport: {
|
|
257
|
+
/** Only this plugin's importers are offered. Omit importerId to let the user choose. */
|
|
246
258
|
open(request: {
|
|
247
|
-
importerId
|
|
259
|
+
importerId?: string;
|
|
248
260
|
initialValue?: string;
|
|
261
|
+
title?: string;
|
|
249
262
|
}): Promise<void>;
|
|
250
263
|
};
|
|
264
|
+
/** Requests an update through the Host UI. A queued result does not mean it was installed. */
|
|
265
|
+
pluginUpdate: {
|
|
266
|
+
request(request: {
|
|
267
|
+
version: string;
|
|
268
|
+
url: string;
|
|
269
|
+
notes?: string;
|
|
270
|
+
}): Promise<{
|
|
271
|
+
accepted: boolean;
|
|
272
|
+
updated: boolean;
|
|
273
|
+
version?: string;
|
|
274
|
+
queued?: boolean;
|
|
275
|
+
}>;
|
|
276
|
+
};
|
|
251
277
|
setState(surfaceId: string, state: JsonObject): Promise<void>;
|
|
252
278
|
notify(message: {
|
|
253
279
|
key: string;
|
|
@@ -256,17 +282,9 @@ export interface PluginContext extends HostServices {
|
|
|
256
282
|
}): Promise<void>;
|
|
257
283
|
openView(surfaceId: string): Promise<void>;
|
|
258
284
|
};
|
|
259
|
-
storage:
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
delete(key: string): Promise<void>;
|
|
263
|
-
};
|
|
264
|
-
guests: {
|
|
265
|
-
list(): Promise<{
|
|
266
|
-
id: string;
|
|
267
|
-
name: string;
|
|
268
|
-
state: string;
|
|
269
|
-
}[]>;
|
|
285
|
+
storage: PluginStorageAPI;
|
|
286
|
+
guests: GuestAPI & {
|
|
287
|
+
/** Legacy install-draft contract; availability depends on the Host. Prefer import on desktop. */
|
|
270
288
|
prepareInstall(request: {
|
|
271
289
|
adapterId: string;
|
|
272
290
|
artifactHandle: string;
|
|
@@ -277,7 +295,6 @@ export interface PluginContext extends HostServices {
|
|
|
277
295
|
requestInstall(draftId: string, operation: OperationContext): Promise<{
|
|
278
296
|
guestId: string;
|
|
279
297
|
} | null>;
|
|
280
|
-
invoke(guestId: string, method: string, input: JsonValue, operation: OperationContext): Promise<JsonValue>;
|
|
281
298
|
};
|
|
282
299
|
log: {
|
|
283
300
|
debug(message: string, data?: JsonValue): void;
|
|
@@ -300,7 +317,7 @@ export interface SurfaceContext extends Pick<PluginContext, 'host' | 'utils' | '
|
|
|
300
317
|
invoke(action: string, input: JsonValue): Promise<JsonValue>;
|
|
301
318
|
subscribe(handler: (state: JsonObject) => void): Disposable;
|
|
302
319
|
}
|
|
303
|
-
export interface GuestContext extends Pick<PluginContext, 'host' | 'utils'
|
|
320
|
+
export interface GuestContext extends Pick<PluginContext, 'host' | 'utils'>, GuestBootstrapAPI {
|
|
304
321
|
readonly guestId: string;
|
|
305
322
|
expose(name: string, value: unknown): void;
|
|
306
323
|
invokeHost(method: string, input: JsonValue): Promise<JsonValue>;
|
package/dist/index.js
CHANGED
|
@@ -3,6 +3,11 @@ export * from './http.js';
|
|
|
3
3
|
export * from './library.js';
|
|
4
4
|
export * from './sockets.js';
|
|
5
5
|
export * from './music.js';
|
|
6
|
+
export * from './lyrics.js';
|
|
7
|
+
export * from './quality.js';
|
|
8
|
+
export * from './guests.js';
|
|
9
|
+
export * from './share.js';
|
|
10
|
+
export * from './storage.js';
|
|
6
11
|
export * from './permissions.js';
|
|
7
12
|
export * from './services.js';
|
|
8
13
|
export * from './modules.js';
|
package/dist/library.d.ts
CHANGED
|
@@ -34,9 +34,11 @@ export interface PlaylistImporterImplementation {
|
|
|
34
34
|
value: string;
|
|
35
35
|
cursor?: string;
|
|
36
36
|
limit: number;
|
|
37
|
-
}, operation: OperationContext): Promise<
|
|
38
|
-
|
|
39
|
-
|
|
37
|
+
}, operation: OperationContext): Promise<PlaylistTrackPage>;
|
|
38
|
+
}
|
|
39
|
+
export interface PlaylistTrackPage extends Page<ContentEntity> {
|
|
40
|
+
name?: string;
|
|
41
|
+
playlist?: import('./music.js').PlaylistMetadata;
|
|
40
42
|
}
|
|
41
43
|
/** Existing application library services. No plugin-owned playlist database. */
|
|
42
44
|
export interface LibraryAPI {
|
package/dist/lyrics.d.ts
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import type { CrLyric } from './music.js';
|
|
2
|
+
import type { ResourceRef, OperationContext } from './index.js';
|
|
3
|
+
export type LyricInputFormat = 'auto' | 'lrc' | 'enhanced-lrc' | 'yrc' | 'qrc' | 'krc' | 'ttml' | 'plain';
|
|
4
|
+
export type LyricExportFormat = 'lrc' | 'enhanced-lrc' | 'yrc';
|
|
5
|
+
export interface LyricParseRequest {
|
|
6
|
+
track: ResourceRef;
|
|
7
|
+
format: LyricInputFormat;
|
|
8
|
+
text: string;
|
|
9
|
+
translation?: string;
|
|
10
|
+
romanization?: string;
|
|
11
|
+
}
|
|
12
|
+
export interface LyricExportRequest {
|
|
13
|
+
document: CrLyric;
|
|
14
|
+
format: LyricExportFormat;
|
|
15
|
+
}
|
|
16
|
+
export interface LyricExportResult {
|
|
17
|
+
format: LyricExportFormat;
|
|
18
|
+
text: string;
|
|
19
|
+
mime: 'text/plain';
|
|
20
|
+
extension: 'lrc' | 'yrc';
|
|
21
|
+
}
|
|
22
|
+
/** Parsing/decryption/serialization belongs to plugins, not the player or download manager. */
|
|
23
|
+
export interface LyricConverter {
|
|
24
|
+
parse(request: LyricParseRequest, operation: OperationContext): Promise<CrLyric>;
|
|
25
|
+
export(request: LyricExportRequest, operation: OperationContext): Promise<LyricExportResult>;
|
|
26
|
+
}
|
package/dist/lyrics.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/manifest.d.ts
CHANGED
|
@@ -27,6 +27,7 @@ export interface ProviderDeclaration {
|
|
|
27
27
|
id: string;
|
|
28
28
|
name: string;
|
|
29
29
|
protocols: string[];
|
|
30
|
+
/** Ordered from lowest to highest; names have no intrinsic rank. */
|
|
30
31
|
qualities?: string[];
|
|
31
32
|
icon?: IconRef;
|
|
32
33
|
connectionMode?: 'none' | 'single' | 'multiple';
|
|
@@ -35,6 +36,18 @@ export interface SurfaceDeclaration {
|
|
|
35
36
|
id: string;
|
|
36
37
|
kind: 'schema' | 'web';
|
|
37
38
|
entry: string;
|
|
39
|
+
/** Host chrome only. The plugin owns all content inside a web Surface. */
|
|
40
|
+
title?: string;
|
|
41
|
+
presentation?: {
|
|
42
|
+
kind: 'drawer';
|
|
43
|
+
placement?: 'left' | 'right' | 'top' | 'bottom';
|
|
44
|
+
size?: number;
|
|
45
|
+
};
|
|
46
|
+
/** Declared logic actions. Open runs after mounting; close runs once per session. */
|
|
47
|
+
lifecycle?: {
|
|
48
|
+
openAction?: string;
|
|
49
|
+
closeAction?: string;
|
|
50
|
+
};
|
|
38
51
|
}
|
|
39
52
|
export type HomeSectionKind = 'playlists' | 'charts' | 'custom';
|
|
40
53
|
export type UISlotName = 'home.header' | 'home.content.before' | 'home.content.after' | 'search.source-selector.after' | 'playlist.header.actions' | 'playlist.item.actions' | 'player.actions' | 'settings.sections';
|
|
@@ -90,9 +103,21 @@ export interface PluginManifest {
|
|
|
90
103
|
entry: string;
|
|
91
104
|
activation?: string[];
|
|
92
105
|
};
|
|
106
|
+
/** Separate server-side playback resolver. Requires a compatible builder and share Host. */
|
|
107
|
+
share?: {
|
|
108
|
+
entry: string;
|
|
109
|
+
configKeys?: string[];
|
|
110
|
+
guestAdapterId?: string;
|
|
111
|
+
guestGlobals?: string[];
|
|
112
|
+
};
|
|
93
113
|
surfaces?: SurfaceDeclaration[];
|
|
94
114
|
};
|
|
95
115
|
contributes?: {
|
|
116
|
+
lyricConverters?: {
|
|
117
|
+
id: string;
|
|
118
|
+
title: string;
|
|
119
|
+
formats: import('./lyrics.js').LyricInputFormat[];
|
|
120
|
+
}[];
|
|
96
121
|
providers?: ProviderDeclaration[];
|
|
97
122
|
/** Home tabs exist only while at least one enabled plugin contributes them. */
|
|
98
123
|
homeSections?: HomeSectionContribution[];
|
|
@@ -105,12 +130,19 @@ export interface PluginManifest {
|
|
|
105
130
|
playlistImporters?: {
|
|
106
131
|
id: string;
|
|
107
132
|
title: string;
|
|
133
|
+
providerId?: string;
|
|
134
|
+
examples?: {
|
|
135
|
+
label: string;
|
|
136
|
+
value: string;
|
|
137
|
+
}[];
|
|
138
|
+
instructions?: string[];
|
|
108
139
|
description?: string;
|
|
109
140
|
placeholder?: string;
|
|
110
141
|
}[];
|
|
111
142
|
commands?: {
|
|
112
143
|
id: string;
|
|
113
144
|
title: string;
|
|
145
|
+
description?: string;
|
|
114
146
|
action: string;
|
|
115
147
|
view?: string;
|
|
116
148
|
}[];
|
|
@@ -127,7 +159,14 @@ export interface PluginManifest {
|
|
|
127
159
|
}[];
|
|
128
160
|
guestAdapters?: {
|
|
129
161
|
id: string;
|
|
162
|
+
title?: string;
|
|
163
|
+
extensions?: string[];
|
|
130
164
|
format: string;
|
|
165
|
+
badge?: {
|
|
166
|
+
label: string;
|
|
167
|
+
backgroundColor: string;
|
|
168
|
+
textColor: string;
|
|
169
|
+
};
|
|
131
170
|
compatibilityProfile: string;
|
|
132
171
|
bootstrap: string;
|
|
133
172
|
runtime: string;
|
package/dist/music.d.ts
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
import type { ContentEntity, ResourceRef, ResolveResult } from './index.js';
|
|
2
2
|
/** Milliseconds throughout. Platform-specific formats/decryption stay inside the plugin. */
|
|
3
3
|
export interface LyricWord {
|
|
4
|
+
romanization?: string;
|
|
4
5
|
startTimeMs: number;
|
|
5
6
|
endTimeMs: number;
|
|
6
7
|
text: string;
|
|
7
8
|
}
|
|
8
9
|
export interface LyricLine {
|
|
10
|
+
isBackground?: boolean;
|
|
11
|
+
isDuet?: boolean;
|
|
9
12
|
startTimeMs: number;
|
|
10
13
|
endTimeMs?: number;
|
|
11
14
|
text: string;
|
|
@@ -13,7 +16,8 @@ export interface LyricLine {
|
|
|
13
16
|
romanization?: string;
|
|
14
17
|
words?: LyricWord[];
|
|
15
18
|
}
|
|
16
|
-
export interface
|
|
19
|
+
export interface CrLyric {
|
|
20
|
+
format: 'crlyric';
|
|
17
21
|
version: 1;
|
|
18
22
|
track: ResourceRef;
|
|
19
23
|
offsetMs: number;
|
|
@@ -21,6 +25,8 @@ export interface LyricsDocument {
|
|
|
21
25
|
/** Untimed lyrics only. Empty lines + no plainText means no available lyrics. */
|
|
22
26
|
plainText?: string;
|
|
23
27
|
}
|
|
28
|
+
/** @deprecated Use CrLyric. */
|
|
29
|
+
export type LyricsDocument = CrLyric;
|
|
24
30
|
export interface TrackMetadata {
|
|
25
31
|
artists: string[];
|
|
26
32
|
album?: {
|
package/dist/music.js
CHANGED
|
@@ -68,12 +68,15 @@ export function assertResolveResult(value) {
|
|
|
68
68
|
}
|
|
69
69
|
export function assertLyricsDocument(value) {
|
|
70
70
|
if (!record(value) ||
|
|
71
|
+
value.format !== 'crlyric' ||
|
|
71
72
|
value.version !== 1 ||
|
|
72
73
|
!Number.isFinite(value.offsetMs) ||
|
|
73
74
|
!Array.isArray(value.lines) ||
|
|
74
75
|
value.lines.length > 20000)
|
|
75
76
|
throw new Error('Invalid lyrics document');
|
|
76
77
|
assertResourceRef(value.track);
|
|
78
|
+
if (value.track.kind !== 'track')
|
|
79
|
+
throw new Error('Lyrics must reference a track');
|
|
77
80
|
let previous = -1;
|
|
78
81
|
for (const line of value.lines) {
|
|
79
82
|
if (!record(line) ||
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
/** Manifest order is authoritative: first is lowest, last is highest. */
|
|
2
|
+
export declare function compareQualities(order: readonly string[], a: string, b: string): -1 | 0 | 1 | undefined;
|
|
3
|
+
export declare function selectQuality(order: readonly string[], available?: readonly string[], requested?: string): string | undefined;
|
package/dist/quality.js
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Manifest order is authoritative: first is lowest, last is highest. */
|
|
2
|
+
export function compareQualities(order, a, b) {
|
|
3
|
+
const left = order.indexOf(a), right = order.indexOf(b);
|
|
4
|
+
if (left < 0 || right < 0)
|
|
5
|
+
return undefined;
|
|
6
|
+
return left === right ? 0 : left < right ? -1 : 1;
|
|
7
|
+
}
|
|
8
|
+
export function selectQuality(order, available = order, requested) {
|
|
9
|
+
const choices = order.filter((quality) => available.includes(quality));
|
|
10
|
+
if (!choices.length)
|
|
11
|
+
return undefined;
|
|
12
|
+
if (!requested || !order.includes(requested))
|
|
13
|
+
return choices.at(-1);
|
|
14
|
+
if (choices.includes(requested))
|
|
15
|
+
return requested;
|
|
16
|
+
const index = order.indexOf(requested);
|
|
17
|
+
return choices.filter((quality) => order.indexOf(quality) <= index).at(-1) ?? choices[0];
|
|
18
|
+
}
|
package/dist/services.d.ts
CHANGED
|
@@ -12,6 +12,8 @@ export interface ServiceAvailability {
|
|
|
12
12
|
service: string;
|
|
13
13
|
version: string;
|
|
14
14
|
available: boolean;
|
|
15
|
+
/** When present, only these methods are connected by the Host. */
|
|
16
|
+
methods?: string[];
|
|
15
17
|
reason?: 'host-not-connected' | 'unsupported' | 'not-logged-in' | 'disabled';
|
|
16
18
|
permissionGroups: PermissionGroup[];
|
|
17
19
|
}
|
|
@@ -312,6 +314,7 @@ export interface MenuContribution {
|
|
|
312
314
|
id: string;
|
|
313
315
|
slot: 'playlist.import' | 'playlist.actions' | 'track.actions' | 'player.actions' | 'search.tools';
|
|
314
316
|
title: string;
|
|
317
|
+
description?: string;
|
|
315
318
|
commandId: string;
|
|
316
319
|
icon?: IconRef;
|
|
317
320
|
when?: {
|
package/dist/share.d.ts
ADDED
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import type { JsonObject, MaybePromise } from './manifest.js';
|
|
2
|
+
export interface ShareMusicInfo {
|
|
3
|
+
songmid?: string | number;
|
|
4
|
+
hash?: string;
|
|
5
|
+
id?: string | number;
|
|
6
|
+
[key: string]: unknown;
|
|
7
|
+
}
|
|
8
|
+
/** Context supplied by the separate share-resolver Host, not the desktop PluginContext. */
|
|
9
|
+
export interface ShareResolverContext<Config = JsonObject> {
|
|
10
|
+
config: Readonly<Config>;
|
|
11
|
+
plugin: {
|
|
12
|
+
name: string;
|
|
13
|
+
version: string;
|
|
14
|
+
author?: string;
|
|
15
|
+
};
|
|
16
|
+
sources: Record<string, {
|
|
17
|
+
name: string;
|
|
18
|
+
qualitys: string[];
|
|
19
|
+
}>;
|
|
20
|
+
request<T = unknown>(url: string, options?: {
|
|
21
|
+
method?: string;
|
|
22
|
+
headers?: Record<string, string>;
|
|
23
|
+
body?: string;
|
|
24
|
+
timeout?: number;
|
|
25
|
+
}): Promise<{
|
|
26
|
+
body: T;
|
|
27
|
+
statusCode: number;
|
|
28
|
+
headers: Record<string, string>;
|
|
29
|
+
}>;
|
|
30
|
+
/** Only available when the manifest declares a selected Guest adapter. */
|
|
31
|
+
guest?: {
|
|
32
|
+
name: string;
|
|
33
|
+
version: string;
|
|
34
|
+
author?: string;
|
|
35
|
+
rawScript: string;
|
|
36
|
+
};
|
|
37
|
+
runGuest?(bindings: Record<string, unknown>): void;
|
|
38
|
+
utils: {
|
|
39
|
+
buffer: {
|
|
40
|
+
from(data: unknown, encoding?: 'base64' | 'hex' | 'utf8'): Uint8Array;
|
|
41
|
+
bufToString(data: Uint8Array, encoding?: 'base64' | 'hex' | 'utf8'): string;
|
|
42
|
+
};
|
|
43
|
+
crypto: {
|
|
44
|
+
md5(value: string): string;
|
|
45
|
+
randomBytes(size: number): Uint8Array;
|
|
46
|
+
aesEncrypt(data: unknown, mode: string, key: unknown, iv?: unknown): Uint8Array;
|
|
47
|
+
rsaEncrypt(data: string, key: string): string;
|
|
48
|
+
};
|
|
49
|
+
};
|
|
50
|
+
}
|
|
51
|
+
export interface ShareResolver {
|
|
52
|
+
musicUrl(source: string, musicInfo: ShareMusicInfo, quality: string): Promise<string>;
|
|
53
|
+
}
|
|
54
|
+
export type ShareResolverEntry<Config = JsonObject> = (context: ShareResolverContext<Config>) => MaybePromise<ShareResolver>;
|
package/dist/share.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import type { JsonValue } from './manifest.js';
|
|
2
|
+
export type PluginStorageReadKey = string | {
|
|
3
|
+
key: string;
|
|
4
|
+
pluginId?: string;
|
|
5
|
+
};
|
|
6
|
+
export type PluginStorageWriteKey = string | {
|
|
7
|
+
key: string;
|
|
8
|
+
pluginId?: string;
|
|
9
|
+
/** Omitted preserves the existing policy; new keys are private. Empty array revokes sharing. */
|
|
10
|
+
readableBy?: '*' | string[];
|
|
11
|
+
};
|
|
12
|
+
/** JSON storage. Structured keys and shared reads require a supporting desktop Host. */
|
|
13
|
+
export interface PluginStorageAPI {
|
|
14
|
+
/** Missing local keys return null. Unauthorized shared reads reject. */
|
|
15
|
+
get<T extends JsonValue = JsonValue>(key: PluginStorageReadKey): Promise<T | null>;
|
|
16
|
+
set(key: PluginStorageWriteKey, value: JsonValue): Promise<void>;
|
|
17
|
+
delete(key: PluginStorageReadKey): Promise<void>;
|
|
18
|
+
}
|
package/dist/storage.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,11 +1,38 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@shiqianjiang/ceru-plugin-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Typed authoring contracts for Ceru Music v2 single-file plugins",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
7
7
|
"types": "./dist/index.d.ts",
|
|
8
|
+
"scripts": {
|
|
9
|
+
"build": "tsc -b && node scripts/prepare-package.mjs",
|
|
10
|
+
"prepack": "npm run build"
|
|
11
|
+
},
|
|
8
12
|
"exports": {
|
|
13
|
+
"./quality": {
|
|
14
|
+
"types": "./dist/quality.d.ts",
|
|
15
|
+
"default": "./dist/quality.js"
|
|
16
|
+
},
|
|
17
|
+
"./lyrics": {
|
|
18
|
+
"types": "./dist/lyrics.d.ts",
|
|
19
|
+
"default": "./dist/lyrics.js"
|
|
20
|
+
},
|
|
21
|
+
"./guests": {
|
|
22
|
+
"types": "./dist/guests.d.ts",
|
|
23
|
+
"import": "./dist/guests.js",
|
|
24
|
+
"default": "./dist/guests.js"
|
|
25
|
+
},
|
|
26
|
+
"./share": {
|
|
27
|
+
"types": "./dist/share.d.ts",
|
|
28
|
+
"import": "./dist/share.js",
|
|
29
|
+
"default": "./dist/share.js"
|
|
30
|
+
},
|
|
31
|
+
"./storage": {
|
|
32
|
+
"types": "./dist/storage.d.ts",
|
|
33
|
+
"import": "./dist/storage.js",
|
|
34
|
+
"default": "./dist/storage.js"
|
|
35
|
+
},
|
|
9
36
|
".": {
|
|
10
37
|
"types": "./dist/index.d.ts",
|
|
11
38
|
"import": "./dist/index.js",
|
|
@@ -90,6 +117,7 @@
|
|
|
90
117
|
"files": [
|
|
91
118
|
"dist",
|
|
92
119
|
"README.md",
|
|
120
|
+
"CHANGELOG.md",
|
|
93
121
|
"LICENSE"
|
|
94
122
|
],
|
|
95
123
|
"license": "MIT",
|
|
File without changes
|