@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.
Files changed (52) hide show
  1. package/README.md +14 -4
  2. package/dist/accounts.d.ts +107 -1
  3. package/dist/accounts.js +14 -0
  4. package/dist/catalog.d.ts +1 -1
  5. package/dist/catalog.js +23 -0
  6. package/dist/crypto-streams.d.ts +10 -0
  7. package/dist/crypto-streams.js +1 -0
  8. package/dist/events.d.ts +21 -0
  9. package/dist/events.js +14 -0
  10. package/dist/hooks.d.ts +211 -0
  11. package/dist/hooks.js +14 -0
  12. package/dist/index.d.ts +55 -22
  13. package/dist/index.js +46 -3
  14. package/dist/legacy-http.d.ts +1 -0
  15. package/dist/legacy-http.js +3 -0
  16. package/dist/lifecycle.d.ts +21 -0
  17. package/dist/lifecycle.js +1 -0
  18. package/dist/links.d.ts +2 -0
  19. package/dist/links.js +25 -0
  20. package/dist/manifest.d.ts +190 -131
  21. package/dist/music-api.d.ts +44 -0
  22. package/dist/music-api.js +1 -0
  23. package/dist/music.js +3 -0
  24. package/dist/navigation.d.ts +17 -0
  25. package/dist/navigation.js +45 -1
  26. package/dist/permissions.d.ts +92 -0
  27. package/dist/permissions.js +23 -0
  28. package/dist/plugins-api.d.ts +16 -0
  29. package/dist/plugins-api.js +1 -0
  30. package/dist/regions.d.ts +76 -0
  31. package/dist/regions.js +9 -0
  32. package/dist/server.d.ts +32 -0
  33. package/dist/server.js +4 -0
  34. package/dist/services.d.ts +48 -24
  35. package/dist/services.js +6 -22
  36. package/dist/streams.d.ts +35 -0
  37. package/dist/streams.js +51 -0
  38. package/dist/validate.d.ts +2 -1
  39. package/dist/validate.js +18 -0
  40. package/dist/view-bridge.d.ts +6 -0
  41. package/dist/view-bridge.js +1 -0
  42. package/dist/view-contracts.d.ts +136 -0
  43. package/dist/view-contracts.js +1 -0
  44. package/dist/vue/index.d.ts +17 -0
  45. package/dist/vue/index.js +74 -0
  46. package/dist/vue/region.d.ts +7 -0
  47. package/dist/vue/region.js +5 -0
  48. package/dist/wasm.d.ts +5 -0
  49. package/dist/wasm.js +1 -0
  50. package/package.json +14 -6
  51. package/dist/host-library.d.ts +0 -29
  52. package/dist/host-library.js +0 -69
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # Ceru Plugin SDK
2
2
 
3
- 0.3.5 新增 `contributes.playlistSections`、`HostNavigationRequest` 和 `assertNavigationRequest`。插件通过 `ui.navigation.open({ page: 'playlist', sectionId })` 前往 Host 现有歌单页的原生区块,校验以调用插件的 manifest 为准。
3
+ v3 只接受 `manifestVersion: 3`,使用 `entry/provides/uses/ui` 分组。Host 注册与数据类型由 SDK 描述;Host 自身的歌单委托实现位于 Core。
4
4
 
5
5
  ## 原生 UI 与账号菜单
6
6
 
7
- 本节接口由 0.3.3 完整提供。
7
+ v3 原生视图使用 `entry.views` 和 `provides.actions`。
8
8
 
9
- 从根入口导入 `defineNativeView`、`NativeView`、`assertNativeView` 和 `AccountSummary`。`kind: 'native'` 的 Surface 以声明的 action 为 render 入口,返回网格/列表与标准内容数据,由 Host 的原生组件渲染。`contributes.accountItems` 以公开摘要动作和账号 Surface 接入 Host 账号菜单;账号业务、凭据和 Vue 登录页面保留在插件内。
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 v2 的 TypeScript 类型与小型作者辅助函数。
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 匹配,不是插件包版本。处理函数不能嵌套服务调用。
@@ -1,4 +1,110 @@
1
- /** Public account presentation. Credentials and platform login flows remain in plugin logic. */
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 {};
@@ -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
+ }
@@ -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 v2 wire/authoring contract. It does not grant Host permissions. */
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;