@shiqianjiang/ceru-plugin-sdk 0.3.15 → 3.0.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 +14 -4
- package/dist/accounts.d.ts +107 -1
- package/dist/accounts.js +14 -0
- package/dist/catalog.d.ts +1 -1
- package/dist/catalog.js +23 -0
- package/dist/crypto-streams.d.ts +10 -0
- package/dist/crypto-streams.js +1 -0
- package/dist/events.d.ts +21 -0
- package/dist/events.js +14 -0
- package/dist/hooks.d.ts +211 -0
- package/dist/hooks.js +14 -0
- package/dist/index.d.ts +55 -22
- package/dist/index.js +46 -3
- package/dist/legacy-http.d.ts +1 -0
- package/dist/legacy-http.js +3 -0
- package/dist/lifecycle.d.ts +21 -0
- package/dist/lifecycle.js +1 -0
- package/dist/links.d.ts +2 -0
- package/dist/links.js +25 -0
- package/dist/manifest.d.ts +190 -131
- package/dist/music-api.d.ts +44 -0
- package/dist/music-api.js +1 -0
- package/dist/music.js +3 -0
- package/dist/navigation.d.ts +17 -0
- package/dist/navigation.js +45 -1
- package/dist/permissions.d.ts +92 -0
- package/dist/permissions.js +23 -0
- package/dist/plugins-api.d.ts +16 -0
- package/dist/plugins-api.js +1 -0
- package/dist/regions.d.ts +76 -0
- package/dist/regions.js +9 -0
- package/dist/server.d.ts +32 -0
- package/dist/server.js +4 -0
- package/dist/services.d.ts +48 -24
- package/dist/services.js +6 -22
- package/dist/streams.d.ts +35 -0
- package/dist/streams.js +51 -0
- package/dist/validate.d.ts +2 -1
- package/dist/validate.js +18 -0
- package/dist/view-bridge.d.ts +6 -0
- package/dist/view-bridge.js +1 -0
- package/dist/view-contracts.d.ts +136 -0
- package/dist/view-contracts.js +1 -0
- package/dist/vue/index.d.ts +17 -0
- package/dist/vue/index.js +74 -0
- package/dist/vue/region.d.ts +7 -0
- package/dist/vue/region.js +5 -0
- package/dist/wasm.d.ts +5 -0
- package/dist/wasm.js +1 -0
- package/package.json +14 -6
- package/dist/host-library.d.ts +0 -29
- package/dist/host-library.js +0 -69
package/README.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# Ceru Plugin SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
v3 只接受 `manifestVersion: 3`,使用 `entry/provides/uses/ui` 分组。Host 注册与数据类型由 SDK 描述;Host 自身的歌单委托实现位于 Core。
|
|
4
4
|
|
|
5
5
|
## 原生 UI 与账号菜单
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
v3 原生视图使用 `entry.views` 和 `provides.actions`。
|
|
8
8
|
|
|
9
|
-
从根入口导入 `defineNativeView`、`NativeView`、`assertNativeView` 和 `AccountSummary`。`kind: 'native'` 的 Surface 以声明的 action 为 render 入口,返回网格/列表与标准内容数据,由 Host
|
|
9
|
+
从根入口导入 `defineNativeView`、`NativeView`、`assertNativeView` 和 `AccountSummary`。`kind: 'native'` 的 Surface 以声明的 action 为 render 入口,返回网格/列表与标准内容数据,由 Host 的原生组件渲染。旧的 `accountItems` 摘要动作不能直接变成 `provides.accounts` 的登录实现。
|
|
10
10
|
|
|
11
11
|
[原生 Surface、导航、播放与账号贡献教程](https://github.com/CeruMusic/CeruMusic-Plugin-Cli/blob/main/docs/NATIVE-SURFACES.md)。脚手架 `connected-library` 的 JS/TS 示例可直接构建和预览。
|
|
12
12
|
|
|
@@ -37,7 +37,7 @@ Manifest 的分享入口和 Guest 展示字段还需要匹配的构建器与校
|
|
|
37
37
|
`npm pack` 会先编译 SDK、复制必要的 ambient 声明,并检查每个 exports 目标存在。
|
|
38
38
|
仓库的 `npm run test:sdk-package` 将真实 tarball 安装到空项目中,验证根入口、子路径和类型约束。
|
|
39
39
|
|
|
40
|
-
面向 Ceru Music
|
|
40
|
+
面向 Ceru Music v3 的 TypeScript 类型与小型作者辅助函数。
|
|
41
41
|
|
|
42
42
|
包含 PluginContext、分组 Provider、歌曲/歌词/歌单标准数据、宿主服务、权限组、Surface、资源引用、结构化错误、UI Slot、图标名和类型化 Lodash。运行能力由 Host 提供,SDK 本身不授予权限。
|
|
43
43
|
|
|
@@ -63,3 +63,13 @@ CLI 并非必需。插件也可以直接写成 `exports.manifest`、`exports.act
|
|
|
63
63
|
运行配置通过 `await ctx.config.get<PluginConfig>()` 读取。配置默认值来自静态 `exports.manifest.config`,个性化发行值来自签名后的 `personalization.config`;Host 递归合并后再交给插件。`definePluginConfig()` 可为外部 TS/JS 配置保留完整字段提示。
|
|
64
64
|
|
|
65
65
|
[完整指南与示例](https://github.com/CeruMusic/CeruMusic-Plugin-Cli#readme)
|
|
66
|
+
|
|
67
|
+
## v3 插件间服务
|
|
68
|
+
|
|
69
|
+
提供方在 `provides.services` 声明 `{id: 'echo', version: '1.2.0', methods: ['reply']}`,启用时注册处理函数:
|
|
70
|
+
|
|
71
|
+
```js
|
|
72
|
+
ctx.services.register('echo', { reply: (input, { callerPluginId }) => ({ input, callerPluginId }) })
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
调用方在 `uses.permissions` 声明 `services.consume`,在 `uses.plugins` 声明 `{pluginId: 'example.provider', service: 'echo', version: '^1.0.0'}`。使用 `const echo = await ctx.plugins.use('example.provider', 'echo')`,再 `await echo.reply({text:'你好'})`。指定 `optional: true` 时须处理 `null`,可用 `ctx.plugins.on('available', handler)` 与 `unavailable` 监听变化。硬依赖不满足时应用保留启用意愿;提供方恢复后自动启动,用户手动停用的插件不会被重新打开。版本按服务自身的 semver 匹配,不是插件包版本。处理函数不能嵌套服务调用。
|
package/dist/accounts.d.ts
CHANGED
|
@@ -1,4 +1,110 @@
|
|
|
1
|
-
|
|
1
|
+
import type { CredentialRef, OperationContext, Page, ResourceRef } from './index.js';
|
|
2
|
+
import type { MusicTrack, MusicPlaylist } from './music.js';
|
|
3
|
+
export interface AccountConnection {
|
|
4
|
+
id: string;
|
|
5
|
+
credential: CredentialRef;
|
|
6
|
+
}
|
|
7
|
+
export interface PluginAccountProfile {
|
|
8
|
+
id: string;
|
|
9
|
+
displayName: string;
|
|
10
|
+
avatar?: string;
|
|
11
|
+
vip?: boolean;
|
|
12
|
+
}
|
|
13
|
+
export interface AccountFormField {
|
|
14
|
+
key: string;
|
|
15
|
+
label: string;
|
|
16
|
+
type: 'text' | 'password' | 'code';
|
|
17
|
+
optional?: boolean;
|
|
18
|
+
}
|
|
19
|
+
export interface AccountForm {
|
|
20
|
+
fields: AccountFormField[];
|
|
21
|
+
}
|
|
22
|
+
export interface AccountLoginResult {
|
|
23
|
+
credential: string;
|
|
24
|
+
binding?: {
|
|
25
|
+
origin: string;
|
|
26
|
+
sendAs: 'bearer' | 'cookie';
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/** Public state supplied only to the custom QR view. No credential or login ticket. */
|
|
30
|
+
export type AccountQrViewState = {
|
|
31
|
+
kind: 'qrcode';
|
|
32
|
+
accountId: string;
|
|
33
|
+
status: 'waiting' | 'scanned';
|
|
34
|
+
expiresAt: number;
|
|
35
|
+
image?: string;
|
|
36
|
+
url?: string;
|
|
37
|
+
origin?: string;
|
|
38
|
+
};
|
|
39
|
+
export type AccountQrCode = ({
|
|
40
|
+
image: string;
|
|
41
|
+
url?: never;
|
|
42
|
+
} | {
|
|
43
|
+
url: string;
|
|
44
|
+
image?: never;
|
|
45
|
+
}) & {
|
|
46
|
+
/** Optional component/web view declared by this plugin. Omit for the Host template. */
|
|
47
|
+
view?: string;
|
|
48
|
+
expiresInMs: number;
|
|
49
|
+
poll(operation: OperationContext): Promise<{
|
|
50
|
+
status: 'waiting' | 'scanned' | 'expired';
|
|
51
|
+
} | ({
|
|
52
|
+
status: 'done';
|
|
53
|
+
} & AccountLoginResult)>;
|
|
54
|
+
};
|
|
55
|
+
export interface AccountOAuthOptions {
|
|
56
|
+
authorizationUrl: string;
|
|
57
|
+
tokenUrl: string;
|
|
58
|
+
clientId: string;
|
|
59
|
+
scopes?: string[];
|
|
60
|
+
resourceOrigin?: string;
|
|
61
|
+
}
|
|
62
|
+
export interface AccountLoginReceipt {
|
|
63
|
+
readonly completionId: string;
|
|
64
|
+
}
|
|
65
|
+
export type AccountListCapability = 'likes' | 'playlists' | 'history' | 'recommend';
|
|
66
|
+
export interface AccountPageRequest {
|
|
67
|
+
cursor?: string;
|
|
68
|
+
limit: number;
|
|
69
|
+
}
|
|
70
|
+
export interface AccountCollection<T> {
|
|
71
|
+
list(account: AccountConnection, request: AccountPageRequest, operation: OperationContext): Promise<Page<T>>;
|
|
72
|
+
}
|
|
73
|
+
export interface AccountBrowserOptions {
|
|
74
|
+
url: string;
|
|
75
|
+
until: {
|
|
76
|
+
cookie: string;
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
export interface AccountLoginRequest {
|
|
80
|
+
method: 'form' | 'qrcode' | 'oauth' | 'browser';
|
|
81
|
+
auth: {
|
|
82
|
+
form(form: AccountForm): Promise<Record<string, string> | null>;
|
|
83
|
+
qrcode(options: AccountQrCode): Promise<AccountLoginResult | null>;
|
|
84
|
+
oauth(options: AccountOAuthOptions): Promise<AccountLoginReceipt | null>;
|
|
85
|
+
browser(options: AccountBrowserOptions): Promise<AccountLoginReceipt | null>;
|
|
86
|
+
};
|
|
87
|
+
}
|
|
88
|
+
export interface AccountImplementation {
|
|
89
|
+
likes?: AccountCollection<MusicTrack> & {
|
|
90
|
+
set?(account: AccountConnection, change: {
|
|
91
|
+
ref: ResourceRef;
|
|
92
|
+
liked: boolean;
|
|
93
|
+
}, operation: OperationContext): Promise<void>;
|
|
94
|
+
};
|
|
95
|
+
playlists?: AccountCollection<MusicPlaylist>;
|
|
96
|
+
history?: AccountCollection<MusicTrack>;
|
|
97
|
+
recommend?: AccountCollection<MusicTrack>;
|
|
98
|
+
login(request: AccountLoginRequest, operation: OperationContext): Promise<AccountLoginResult | AccountLoginReceipt | null>;
|
|
99
|
+
profile(account: AccountConnection, operation: OperationContext): PluginAccountProfile | Promise<PluginAccountProfile>;
|
|
100
|
+
validate?(account: AccountConnection, operation: OperationContext): {
|
|
101
|
+
valid: boolean;
|
|
102
|
+
} | Promise<{
|
|
103
|
+
valid: boolean;
|
|
104
|
+
}>;
|
|
105
|
+
logout?(account: AccountConnection, operation: OperationContext): void | Promise<void>;
|
|
106
|
+
}
|
|
107
|
+
export declare function assertAccountForm(value: unknown): asserts value is AccountForm;
|
|
2
108
|
export type AccountSummary = {
|
|
3
109
|
signedIn: boolean;
|
|
4
110
|
displayName: string;
|
package/dist/accounts.js
CHANGED
|
@@ -1,3 +1,17 @@
|
|
|
1
|
+
export function assertAccountForm(value) {
|
|
2
|
+
const form = value;
|
|
3
|
+
if (!Array.isArray(form?.fields) || !form.fields.length || form.fields.length > 8)
|
|
4
|
+
throw Error('Invalid account form');
|
|
5
|
+
const keys = new Set();
|
|
6
|
+
for (const field of form.fields) {
|
|
7
|
+
if (!field || typeof field.key !== 'string' || !/^[a-zA-Z][a-zA-Z0-9_]{0,39}$/.test(field.key) ||
|
|
8
|
+
['constructor', 'prototype'].includes(field.key) || keys.has(field.key) ||
|
|
9
|
+
typeof field.label !== 'string' || !field.label.trim() || field.label.length > 100 ||
|
|
10
|
+
!['text', 'code', 'password'].includes(field.type) || (field.optional !== undefined && typeof field.optional !== 'boolean'))
|
|
11
|
+
throw Error('Invalid account field');
|
|
12
|
+
keys.add(field.key);
|
|
13
|
+
}
|
|
14
|
+
}
|
|
1
15
|
export function assertAccountSummary(value) {
|
|
2
16
|
const account = value;
|
|
3
17
|
if (!account ||
|
package/dist/catalog.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ export declare const HOST_ICON_NAMES: readonly ["platform.tx", "platform.kg", "p
|
|
|
3
3
|
export type HostIconName = (typeof HOST_ICON_NAMES)[number];
|
|
4
4
|
export declare const HOST_ASSET_NAMES: readonly ["app.logo", "placeholder.cover", "placeholder.avatar"];
|
|
5
5
|
export type HostAssetName = (typeof HOST_ASSET_NAMES)[number];
|
|
6
|
-
export declare const PERMISSION_NAMES: readonly ["account.profile", "downloads.manage", "localMusic.read", "localMusic.write", "settings.read", "settings.write", "window.control", "hotkeys.register", "rooms.read", "rooms.control", "ai.use", "devices.control", "ui.styles.global", "network.request", "network.socket", "network.private", "network.discovery", "credentials.use", "credentials.read", "library.read", "library.write", "library.delete", "player.read", "player.control", "playback.fallback.hold", "files.read", "files.write", "downloads.create", "clipboard.read", "clipboard.write", "notifications.system", "external.open", "background.run", "services.consume", "sharing.publish", "sharing.revoke", "guests.manage", "guests.run"];
|
|
6
|
+
export declare const PERMISSION_NAMES: readonly ["account.profile", "downloads.manage", "localMusic.read", "localMusic.write", "settings.read", "settings.write", "window.control", "hotkeys.register", "rooms.read", "rooms.control", "ai.use", "devices.control", "ui.styles.global", "network.request", "network.socket", "network.private", "network.discovery", "network.serve", "network.serve.lan", "streams.transform", "runtime.trusted", "credentials.use", "credentials.read", "credentials.capture", "library.read", "library.write", "library.delete", "player.read", "route.read", "navigation.intercept", "music.read", "music.control", "player.control", "player.intercept", "account.intercept", "library.intercept", "search.intercept", "search.read", "links.read", "notifications.read", "window.read", "window.intercept", "lyrics.intercept", "downloads.intercept", "sharing.intercept", "links.intercept", "notifications.intercept", "playback.fallback.hold", "files.read", "files.write", "downloads.create", "clipboard.read", "clipboard.write", "notifications.system", "external.open", "background.run", "services.consume", "sharing.publish", "sharing.revoke", "guests.manage", "guests.run"];
|
|
7
7
|
export type PermissionName = (typeof PERMISSION_NAMES)[number];
|
|
8
8
|
/** Runtime modules available to hand-written plugins without bundling. */
|
|
9
9
|
export declare const HOST_MODULE_NAMES: readonly ["ceru", "@ceru/http", "@ceru/ui", "@ceru/socket", "@ceru/library", "@ceru/account", "@ceru/player", "@ceru/tools", "@ceru/crypto", "@ceru/compression", "@ceru/encoding", "@ceru/legacy-http", "lodash"];
|
package/dist/catalog.js
CHANGED
|
@@ -45,13 +45,36 @@ export const PERMISSION_NAMES = [
|
|
|
45
45
|
'network.socket',
|
|
46
46
|
'network.private',
|
|
47
47
|
'network.discovery',
|
|
48
|
+
'network.serve',
|
|
49
|
+
'network.serve.lan',
|
|
50
|
+
'streams.transform',
|
|
51
|
+
'runtime.trusted',
|
|
48
52
|
'credentials.use',
|
|
49
53
|
'credentials.read',
|
|
54
|
+
'credentials.capture',
|
|
50
55
|
'library.read',
|
|
51
56
|
'library.write',
|
|
52
57
|
'library.delete',
|
|
53
58
|
'player.read',
|
|
59
|
+
'route.read',
|
|
60
|
+
'navigation.intercept',
|
|
61
|
+
'music.read',
|
|
62
|
+
'music.control',
|
|
54
63
|
'player.control',
|
|
64
|
+
'player.intercept',
|
|
65
|
+
'account.intercept',
|
|
66
|
+
'library.intercept',
|
|
67
|
+
'search.intercept',
|
|
68
|
+
'search.read',
|
|
69
|
+
'links.read',
|
|
70
|
+
'notifications.read',
|
|
71
|
+
'window.read',
|
|
72
|
+
'window.intercept',
|
|
73
|
+
'lyrics.intercept',
|
|
74
|
+
'downloads.intercept',
|
|
75
|
+
'sharing.intercept',
|
|
76
|
+
'links.intercept',
|
|
77
|
+
'notifications.intercept',
|
|
55
78
|
'playback.fallback.hold',
|
|
56
79
|
'files.read',
|
|
57
80
|
'files.write',
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { StreamAlgorithm } from './streams.js';
|
|
2
|
+
export interface CryptoStreamOptions {
|
|
3
|
+
/** String keys and IVs are hexadecimal unless base64 is specified. */
|
|
4
|
+
encoding?: 'hex' | 'base64';
|
|
5
|
+
signal?: AbortSignal;
|
|
6
|
+
}
|
|
7
|
+
export interface CryptoStreamsAPI {
|
|
8
|
+
createCipher(algorithm: StreamAlgorithm, key: string | Uint8Array, iv: string | Uint8Array, options?: CryptoStreamOptions): TransformStream<Uint8Array, Uint8Array>;
|
|
9
|
+
createDecipher(algorithm: StreamAlgorithm, key: string | Uint8Array, iv: string | Uint8Array, options?: CryptoStreamOptions): TransformStream<Uint8Array, Uint8Array>;
|
|
10
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/events.d.ts
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { HookOperationName, HookResult, OperationInputs, OperationSource } from './hooks.js';
|
|
2
|
+
import type { PermissionName } from './catalog.js';
|
|
3
|
+
export type OperationEventName = HookOperationName | `${HookOperationName}:done`;
|
|
4
|
+
type ReadonlyTree<T> = T extends object ? {
|
|
5
|
+
readonly [K in keyof T]: ReadonlyTree<T[K]>;
|
|
6
|
+
} : T;
|
|
7
|
+
export type OperationEvent<Name extends OperationEventName> = Name extends `${infer Op extends HookOperationName}:done` ? ReadonlyTree<{
|
|
8
|
+
input: OperationInputs[Op];
|
|
9
|
+
source: OperationSource;
|
|
10
|
+
result: HookResult<Op>;
|
|
11
|
+
prevented: boolean;
|
|
12
|
+
handledBy: string[];
|
|
13
|
+
failed: boolean;
|
|
14
|
+
}> : Name extends HookOperationName ? ReadonlyTree<{
|
|
15
|
+
input: OperationInputs[Name];
|
|
16
|
+
source: OperationSource;
|
|
17
|
+
}> & {
|
|
18
|
+
preventDefault(): void;
|
|
19
|
+
} : never;
|
|
20
|
+
export declare function operationEventPermission(name: string): PermissionName | undefined;
|
|
21
|
+
export {};
|
package/dist/events.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export function operationEventPermission(name) {
|
|
2
|
+
const done = name.endsWith(':done');
|
|
3
|
+
const operation = done ? name.slice(0, -5) : name;
|
|
4
|
+
const group = operation.split('.')[0];
|
|
5
|
+
const permissions = {
|
|
6
|
+
player: ['player.intercept', 'player.read'], queue: ['player.intercept', 'player.read'],
|
|
7
|
+
track: ['library.intercept', 'library.read'], playlist: ['library.intercept', 'library.read'],
|
|
8
|
+
account: ['account.intercept', 'account.profile'], search: ['search.intercept', 'search.read'],
|
|
9
|
+
lyrics: ['lyrics.intercept', 'player.read'], download: ['downloads.intercept', 'downloads.manage'],
|
|
10
|
+
share: ['sharing.intercept', 'music.read'], link: ['links.intercept', 'links.read'],
|
|
11
|
+
notification: ['notifications.intercept', 'notifications.read'], window: ['window.intercept', 'window.read'],
|
|
12
|
+
};
|
|
13
|
+
return permissions[group]?.[done ? 1 : 0];
|
|
14
|
+
}
|
package/dist/hooks.d.ts
ADDED
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
import type { OperationContext } from './index.js';
|
|
2
|
+
import type { CrLyric } from './music.js';
|
|
3
|
+
export declare const PLAYBACK_OPERATION_NAMES: readonly ["player.play", "queue.add", "player.pause", "player.resume", "player.previous", "player.next", "player.error", "player.queueEnded", "player.seek", "player.setVolume", "player.setMode", "queue.remove", "queue.clear", "queue.shuffle"];
|
|
4
|
+
export type PlaybackOperationName = (typeof PLAYBACK_OPERATION_NAMES)[number];
|
|
5
|
+
export type SearchOperationName = 'search.query' | 'search.suggest' | 'search.results';
|
|
6
|
+
declare const LIBRARY_OPERATION_NAMES: readonly ["track.like", "playlist.create", "playlist.delete", "playlist.addTracks", "playlist.removeTracks", "playlist.export", "playlist.import"];
|
|
7
|
+
export type LibraryOperationName = (typeof LIBRARY_OPERATION_NAMES)[number];
|
|
8
|
+
export declare function isLibraryOperation(name: unknown): name is LibraryOperationName;
|
|
9
|
+
export type LyricOperationName = 'lyrics.load' | 'lyrics.transform';
|
|
10
|
+
export type DownloadOperationName = 'download.create' | 'download.filename';
|
|
11
|
+
export declare function isDownloadOperation(name: unknown): name is DownloadOperationName;
|
|
12
|
+
export declare function isLyricOperation(name: unknown): name is LyricOperationName;
|
|
13
|
+
export type OperationLyric = Omit<CrLyric, 'track'> & {
|
|
14
|
+
track: OperationTrack['ref'];
|
|
15
|
+
};
|
|
16
|
+
export type SystemOperationName = 'link.open' | 'notification.show';
|
|
17
|
+
export type HookOperationName = PlaybackOperationName | 'player.resolve' | 'account.switch' | 'window.close' | 'share.create' | SystemOperationName | SearchOperationName | LibraryOperationName | LyricOperationName | DownloadOperationName;
|
|
18
|
+
export interface ShareOperationResult {
|
|
19
|
+
id: string;
|
|
20
|
+
url: string;
|
|
21
|
+
template?: string;
|
|
22
|
+
}
|
|
23
|
+
export interface ResolveStatus {
|
|
24
|
+
readonly ok: boolean;
|
|
25
|
+
}
|
|
26
|
+
export type HookResult<Name extends HookOperationName> = Name extends 'share.create' ? ShareOperationResult | null : Name extends LyricOperationName ? OperationLyric | null : Name extends 'player.resolve' ? ResolveStatus : null;
|
|
27
|
+
export declare function isSearchOperation(name: unknown): name is SearchOperationName;
|
|
28
|
+
export type OperationSource = {
|
|
29
|
+
kind: 'ui' | 'system';
|
|
30
|
+
location?: string;
|
|
31
|
+
} | {
|
|
32
|
+
kind: 'plugin';
|
|
33
|
+
pluginId: string;
|
|
34
|
+
runtime: 2 | 3;
|
|
35
|
+
};
|
|
36
|
+
export interface OperationTrack {
|
|
37
|
+
ref: {
|
|
38
|
+
kind: 'track';
|
|
39
|
+
id: string;
|
|
40
|
+
providerId: string;
|
|
41
|
+
};
|
|
42
|
+
title: string;
|
|
43
|
+
metadata: {
|
|
44
|
+
artists: string[];
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
export interface OperationInputs {
|
|
48
|
+
'link.open': {
|
|
49
|
+
url: string;
|
|
50
|
+
readonly from: 'paste' | 'drop' | 'deeplink';
|
|
51
|
+
};
|
|
52
|
+
'notification.show': {
|
|
53
|
+
title: string;
|
|
54
|
+
body: string;
|
|
55
|
+
level: 'info' | 'success' | 'warning' | 'error';
|
|
56
|
+
};
|
|
57
|
+
'share.create': {
|
|
58
|
+
track: OperationTrack;
|
|
59
|
+
};
|
|
60
|
+
'download.create': {
|
|
61
|
+
tracks: OperationTrack[];
|
|
62
|
+
quality: string;
|
|
63
|
+
readonly directory?: string;
|
|
64
|
+
};
|
|
65
|
+
'download.filename': {
|
|
66
|
+
readonly track: OperationTrack;
|
|
67
|
+
name: string;
|
|
68
|
+
};
|
|
69
|
+
'lyrics.load': {
|
|
70
|
+
readonly track: OperationTrack;
|
|
71
|
+
};
|
|
72
|
+
'lyrics.transform': {
|
|
73
|
+
readonly track: OperationTrack;
|
|
74
|
+
lyric: OperationLyric | null;
|
|
75
|
+
};
|
|
76
|
+
'window.close': Record<string, never>;
|
|
77
|
+
'player.resolve': {
|
|
78
|
+
track: OperationTrack;
|
|
79
|
+
quality: string;
|
|
80
|
+
};
|
|
81
|
+
'track.like': {
|
|
82
|
+
track: OperationTrack;
|
|
83
|
+
liked: boolean;
|
|
84
|
+
};
|
|
85
|
+
'playlist.create': {
|
|
86
|
+
name: string;
|
|
87
|
+
readonly location: 'local' | 'cloud';
|
|
88
|
+
};
|
|
89
|
+
'playlist.delete': {
|
|
90
|
+
readonly playlist: {
|
|
91
|
+
readonly id: string;
|
|
92
|
+
readonly name: string;
|
|
93
|
+
readonly location: 'local' | 'cloud' | 'both';
|
|
94
|
+
};
|
|
95
|
+
};
|
|
96
|
+
'playlist.addTracks': OperationInputs['playlist.delete'] & {
|
|
97
|
+
tracks: OperationTrack[];
|
|
98
|
+
};
|
|
99
|
+
'playlist.removeTracks': OperationInputs['playlist.addTracks'];
|
|
100
|
+
'playlist.export': OperationInputs['playlist.delete'] & {
|
|
101
|
+
format: 'cmpl' | 'cpl';
|
|
102
|
+
};
|
|
103
|
+
'playlist.import': {
|
|
104
|
+
value: string;
|
|
105
|
+
importerId?: string;
|
|
106
|
+
};
|
|
107
|
+
'search.results': {
|
|
108
|
+
readonly query: string;
|
|
109
|
+
readonly sourceId: string;
|
|
110
|
+
page: {
|
|
111
|
+
readonly kind: 'track' | 'playlist';
|
|
112
|
+
items: SearchResultItem[];
|
|
113
|
+
};
|
|
114
|
+
};
|
|
115
|
+
'search.query': {
|
|
116
|
+
query: string;
|
|
117
|
+
readonly sourceId: string;
|
|
118
|
+
readonly kinds: readonly string[];
|
|
119
|
+
};
|
|
120
|
+
'search.suggest': {
|
|
121
|
+
readonly query: string;
|
|
122
|
+
items: string[];
|
|
123
|
+
};
|
|
124
|
+
'account.switch': {
|
|
125
|
+
readonly pluginId: string;
|
|
126
|
+
readonly accountId: string;
|
|
127
|
+
readonly fromConnectionId: string | null;
|
|
128
|
+
readonly connectionId: string;
|
|
129
|
+
};
|
|
130
|
+
'player.pause': Record<string, never>;
|
|
131
|
+
'player.resume': Record<string, never>;
|
|
132
|
+
'player.previous': Record<string, never>;
|
|
133
|
+
'player.seek': {
|
|
134
|
+
positionMs: number;
|
|
135
|
+
};
|
|
136
|
+
'player.setMode': {
|
|
137
|
+
mode: 'sequence' | 'random' | 'single';
|
|
138
|
+
};
|
|
139
|
+
'player.setVolume': {
|
|
140
|
+
volume: number;
|
|
141
|
+
};
|
|
142
|
+
'player.next': {
|
|
143
|
+
reason: 'user' | 'ended' | 'error';
|
|
144
|
+
track?: OperationTrack;
|
|
145
|
+
};
|
|
146
|
+
'player.error': {
|
|
147
|
+
readonly track: OperationTrack;
|
|
148
|
+
readonly error: 'resolve' | 'start' | 'media' | 'playback';
|
|
149
|
+
};
|
|
150
|
+
'player.queueEnded': {
|
|
151
|
+
tracks?: OperationTrack[];
|
|
152
|
+
};
|
|
153
|
+
'player.play': {
|
|
154
|
+
track: OperationTrack;
|
|
155
|
+
queueIndex?: number;
|
|
156
|
+
};
|
|
157
|
+
'queue.add': {
|
|
158
|
+
tracks: OperationTrack[];
|
|
159
|
+
position: 'next' | 'end';
|
|
160
|
+
};
|
|
161
|
+
'queue.remove': {
|
|
162
|
+
tracks: OperationTrack[];
|
|
163
|
+
};
|
|
164
|
+
'queue.clear': {
|
|
165
|
+
tracks?: OperationTrack[];
|
|
166
|
+
};
|
|
167
|
+
'queue.shuffle': {
|
|
168
|
+
items: OperationTrack[];
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
export interface SearchResultItem {
|
|
172
|
+
ref: {
|
|
173
|
+
kind: 'track' | 'playlist';
|
|
174
|
+
providerId: string;
|
|
175
|
+
id: string;
|
|
176
|
+
};
|
|
177
|
+
title: string;
|
|
178
|
+
subtitle?: string;
|
|
179
|
+
metadata?: {
|
|
180
|
+
artists: string[];
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
export type HookInput<Name extends HookOperationName> = OperationInputs[Name] | (Name extends 'player.next' ? {
|
|
184
|
+
track: OperationTrack;
|
|
185
|
+
} : never);
|
|
186
|
+
export type HookPriority = 'early' | 'normal' | 'late';
|
|
187
|
+
type ReadonlyTree<T> = T extends object ? {
|
|
188
|
+
readonly [Key in keyof T]: ReadonlyTree<T[Key]>;
|
|
189
|
+
} : T;
|
|
190
|
+
export type OperationState = ReadonlyTree<{
|
|
191
|
+
player: (Omit<import('./services.js').PlayerState, 'track'> & {
|
|
192
|
+
track: OperationTrack | null;
|
|
193
|
+
}) | null;
|
|
194
|
+
route: import('./navigation.js').PluginRoute | null;
|
|
195
|
+
account: import('./services.js').AccountSession | null;
|
|
196
|
+
}>;
|
|
197
|
+
export interface HookContext<Name extends HookOperationName> {
|
|
198
|
+
input: OperationInputs[Name];
|
|
199
|
+
readonly source: OperationSource;
|
|
200
|
+
readonly operation: OperationContext;
|
|
201
|
+
/** Missing read permission is represented by null; the snapshot cannot be mutated. */
|
|
202
|
+
readonly state: OperationState;
|
|
203
|
+
preventDefault(): void;
|
|
204
|
+
respondWith(result: HookResult<Name>): void;
|
|
205
|
+
}
|
|
206
|
+
export interface HooksAPI {
|
|
207
|
+
on<Name extends HookOperationName>(name: Name, handler: (op: HookContext<Name>, next: (input?: HookInput<Name>) => Promise<HookResult<Name>>) => void | HookResult<Name> | HookInput<Name> | Promise<void | HookResult<Name> | HookInput<Name>>, options?: {
|
|
208
|
+
priority?: HookPriority;
|
|
209
|
+
}): () => void;
|
|
210
|
+
}
|
|
211
|
+
export {};
|
package/dist/hooks.js
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
export const PLAYBACK_OPERATION_NAMES = ['player.play', 'queue.add', 'player.pause', 'player.resume', 'player.previous', 'player.next', 'player.error', 'player.queueEnded', 'player.seek', 'player.setVolume', 'player.setMode', 'queue.remove', 'queue.clear', 'queue.shuffle'];
|
|
2
|
+
const LIBRARY_OPERATION_NAMES = ['track.like', 'playlist.create', 'playlist.delete', 'playlist.addTracks', 'playlist.removeTracks', 'playlist.export', 'playlist.import'];
|
|
3
|
+
export function isLibraryOperation(name) {
|
|
4
|
+
return LIBRARY_OPERATION_NAMES.some(operation => operation === name);
|
|
5
|
+
}
|
|
6
|
+
export function isDownloadOperation(name) {
|
|
7
|
+
return name === 'download.create' || name === 'download.filename';
|
|
8
|
+
}
|
|
9
|
+
export function isLyricOperation(name) {
|
|
10
|
+
return name === 'lyrics.load' || name === 'lyrics.transform';
|
|
11
|
+
}
|
|
12
|
+
export function isSearchOperation(name) {
|
|
13
|
+
return name === 'search.query' || name === 'search.suggest' || name === 'search.results';
|
|
14
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
/// <reference path="./host-modules.d.cts" />
|
|
2
|
-
/** This package defines the
|
|
2
|
+
/** This package defines the v3 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';
|
|
5
5
|
export * from './catalog.js';
|
|
6
|
+
export * from './plugins-api.js';
|
|
6
7
|
export * from './http.js';
|
|
7
8
|
export * from './library.js';
|
|
8
9
|
export * from './validate.js';
|
|
@@ -12,7 +13,13 @@ import type { GuestAPI, GuestBootstrapAPI } from './guests.js';
|
|
|
12
13
|
import type { PluginStorageAPI } from './storage.js';
|
|
13
14
|
import type { createHttpClient, HttpClientOptions } from './http.js';
|
|
14
15
|
export * from './music.js';
|
|
16
|
+
export * from './streams.js';
|
|
17
|
+
export * from './server.js';
|
|
18
|
+
export type * from './wasm.js';
|
|
19
|
+
export type * from './crypto-streams.js';
|
|
20
|
+
export * from './music-api.js';
|
|
15
21
|
export * from './lyrics.js';
|
|
22
|
+
export * from './regions.js';
|
|
16
23
|
export * from './quality.js';
|
|
17
24
|
export * from './guests.js';
|
|
18
25
|
export * from './share.js';
|
|
@@ -54,11 +61,6 @@ export interface AssetHandle {
|
|
|
54
61
|
readonly kind: 'asset';
|
|
55
62
|
readonly id: string;
|
|
56
63
|
}
|
|
57
|
-
export interface MediaLease {
|
|
58
|
-
/** @deprecated v0.2 providers return direct playback URLs. */
|
|
59
|
-
readonly kind: 'media';
|
|
60
|
-
readonly id: string;
|
|
61
|
-
}
|
|
62
64
|
export interface CredentialRef {
|
|
63
65
|
readonly kind: 'credential';
|
|
64
66
|
readonly id: string;
|
|
@@ -126,6 +128,8 @@ export type ResolveResult = {
|
|
|
126
128
|
expiresAt?: number;
|
|
127
129
|
/** Headers the Host must attach while fetching this exact media URL. */
|
|
128
130
|
requestHeaders?: Record<string, string>;
|
|
131
|
+
/** Optional processing performed by the Host before playback or download. */
|
|
132
|
+
stream?: import('./streams.js').StreamSpec;
|
|
129
133
|
} | {
|
|
130
134
|
ok: false;
|
|
131
135
|
error: MusicFault;
|
|
@@ -161,6 +165,9 @@ export interface ArtworkHiresRequest {
|
|
|
161
165
|
targetSize?: number;
|
|
162
166
|
}
|
|
163
167
|
export interface TrackProvider {
|
|
168
|
+
suggest?(query: string, operation: OperationContext): Promise<string[]>;
|
|
169
|
+
hotSearch?(operation: OperationContext): Promise<string[]>;
|
|
170
|
+
artwork?(resource: ResourceRef, operation: OperationContext): Promise<string | undefined>;
|
|
164
171
|
search?(request: SearchRequest, operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
165
172
|
resolve?(resource: ResourceRef, quality: string | undefined, operation: OperationContext): Promise<ResolveResult>;
|
|
166
173
|
lyrics?(resource: ResourceRef, operation: OperationContext): Promise<LyricsDocument>;
|
|
@@ -188,20 +195,36 @@ export interface ProviderImplementation {
|
|
|
188
195
|
playlists?: PlaylistProvider;
|
|
189
196
|
charts?: ChartProvider;
|
|
190
197
|
sharing?: SharingProvider;
|
|
191
|
-
/** @deprecated Use tracks.lyrics. Kept for v2 preview compatibility. */
|
|
192
|
-
lyrics?(resource: ResourceRef, operation: OperationContext): Promise<LyricsDocument>;
|
|
193
|
-
/** @deprecated Use tracks.search. */
|
|
194
|
-
search?(request: SearchRequest, operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
195
|
-
/** @deprecated Use tracks.resolve. */
|
|
196
|
-
resolve?(resource: ResourceRef, quality: string | undefined, operation: OperationContext): Promise<ResolveResult>;
|
|
197
|
-
/** @deprecated Use playlists.categories. */
|
|
198
|
-
categories?(operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
199
|
-
/** @deprecated Use playlists.list/get or charts.getTracks. */
|
|
200
|
-
list?(resource: ResourceRef, cursor: string | undefined, operation: OperationContext): Promise<Page<ContentEntity>>;
|
|
201
|
-
/** @deprecated Use sharing.describe. */
|
|
202
|
-
share?(resource: ResourceRef, policy: JsonObject, operation: OperationContext): Promise<JsonObject>;
|
|
203
198
|
}
|
|
199
|
+
export type * from './hooks.js';
|
|
200
|
+
export { publicLink } from './links.js';
|
|
201
|
+
export type * from './lifecycle.js';
|
|
202
|
+
import { type PluginOptions } from './lifecycle.js';
|
|
204
203
|
export interface PluginContext extends HostServices {
|
|
204
|
+
server: import('./server.js').ServerAPI;
|
|
205
|
+
streams: import('./streams.js').StreamsAPI;
|
|
206
|
+
wasm: import('./wasm.js').WasmAPI;
|
|
207
|
+
crypto: import('./crypto-streams.js').CryptoStreamsAPI;
|
|
208
|
+
entries: {
|
|
209
|
+
invalidate(): Promise<void>;
|
|
210
|
+
selection(): Promise<import('./manifest.js').SourceSelection>;
|
|
211
|
+
};
|
|
212
|
+
accounts: {
|
|
213
|
+
current(accountId: string): Promise<{
|
|
214
|
+
connectionId: string;
|
|
215
|
+
expired: boolean;
|
|
216
|
+
} | null>;
|
|
217
|
+
reportExpired(accountId: string, connectionId: string, credential: CredentialRef): Promise<boolean>;
|
|
218
|
+
register(id: string, implementation: import('./accounts.js').AccountImplementation): () => void;
|
|
219
|
+
};
|
|
220
|
+
router: import('./navigation.js').PluginRouter;
|
|
221
|
+
lifecycle: import('./lifecycle.js').LifecycleAPI;
|
|
222
|
+
hooks: import('./hooks.js').HooksAPI;
|
|
223
|
+
music: import('./music-api.js').MusicAPI;
|
|
224
|
+
plugins: import('./plugins-api.js').PluginsAPI;
|
|
225
|
+
services: {
|
|
226
|
+
register(id: string, handlers: Record<string, import('./plugins-api.js').ServiceHandler>): () => void;
|
|
227
|
+
};
|
|
205
228
|
modules: PluginModules;
|
|
206
229
|
readonly plugin: {
|
|
207
230
|
id: string;
|
|
@@ -324,6 +347,18 @@ export interface PluginContext extends HostServices {
|
|
|
324
347
|
queued?: boolean;
|
|
325
348
|
}>;
|
|
326
349
|
};
|
|
350
|
+
pages: {
|
|
351
|
+
open(pageId: string, props?: JsonObject): Promise<void>;
|
|
352
|
+
close(pageId: string): Promise<void>;
|
|
353
|
+
};
|
|
354
|
+
views: {
|
|
355
|
+
setState(viewId: string, state: JsonObject): Promise<void>;
|
|
356
|
+
on(event: 'mounted' | 'unmounted', handler: (info: {
|
|
357
|
+
viewId: string;
|
|
358
|
+
instanceId: string;
|
|
359
|
+
props: JsonObject;
|
|
360
|
+
}) => void): Disposable;
|
|
361
|
+
};
|
|
327
362
|
setState(surfaceId: string, state: JsonObject): Promise<void>;
|
|
328
363
|
notify(message: {
|
|
329
364
|
key: string;
|
|
@@ -378,13 +413,10 @@ export interface GuestContext extends Pick<PluginContext, 'host' | 'utils'>, Gue
|
|
|
378
413
|
export type LogicEntry = (ctx: PluginContext) => MaybePromise<void | Disposable>;
|
|
379
414
|
export type SurfaceEntry = (ctx: SurfaceContext) => MaybePromise<void | Disposable>;
|
|
380
415
|
export type GuestEntry = (ctx: GuestContext) => MaybePromise<void | Disposable>;
|
|
381
|
-
export declare function definePlugin(entry: LogicEntry): LogicEntry;
|
|
416
|
+
export declare function definePlugin(entry: LogicEntry | PluginOptions): LogicEntry;
|
|
382
417
|
export declare function defineSurface(entry: SurfaceEntry): SurfaceEntry;
|
|
383
418
|
export { defineNativeView, assertNativeView } from './native-view.js';
|
|
384
419
|
export type { NativeView, NativeViewSection, NativeViewAction } from './native-view.js';
|
|
385
|
-
/** Host-side playlist delegation; import in the Electron main/renderer host, not in a plugin. */
|
|
386
|
-
export { createHostLibraryBridge } from './host-library.js';
|
|
387
|
-
export type { HostLibraryServices } from './host-library.js';
|
|
388
420
|
export declare function defineGuestAdapter(entry: GuestEntry): GuestEntry;
|
|
389
421
|
export declare function defineManifest(manifest: PluginManifest): PluginManifest;
|
|
390
422
|
export declare function definePluginConfig<const T extends JsonObject>(config: T): T;
|
|
@@ -422,4 +454,5 @@ export interface UISchema {
|
|
|
422
454
|
id?: string;
|
|
423
455
|
root: UINode;
|
|
424
456
|
}
|
|
457
|
+
export * from './events.js';
|
|
425
458
|
export declare function defineUISchema(schema: UISchema): UISchema;
|