@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 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 本身不授予权限。
@@ -1,17 +1,23 @@
1
1
  export function createHash(name: any): {
2
2
  update(value: any): /*elided*/ any;
3
- digest(encoding: any): string | Buffer<ArrayBuffer>;
3
+ /** @returns {string | Buffer} */
4
+ digest(encoding: any): string | Buffer;
4
5
  };
5
- export function publicEncrypt(options: any, value: any): Buffer<ArrayBuffer>;
6
+ /** @returns {Buffer} */
7
+ export function publicEncrypt(options: any, value: any): Buffer;
6
8
  export function createCipheriv(mode: any, key: any, iv: any): {
7
- update(value: any): Buffer<ArrayBuffer>;
8
- final(): Buffer<ArrayBuffer>;
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
- update(value: any): Buffer<ArrayBuffer>;
12
- final(): Buffer<ArrayBuffer>;
15
+ /** @returns {Buffer} */
16
+ update(value: any): Buffer;
17
+ /** @returns {Buffer} */
18
+ final(): Buffer;
13
19
  };
14
- export function randomBytes(size: any): Buffer<ArrayBuffer>;
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;
@@ -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');
@@ -1,5 +1,5 @@
1
1
  export function inflate(input: any, callback: any): void;
2
- export function unzipSync(input: any): Buffer<ArrayBuffer>;
2
+ export function unzipSync(input: any): Buffer;
3
3
  declare namespace _default {
4
4
  export { unzipSync };
5
5
  export { inflate };
@@ -1,5 +1,6 @@
1
1
  import { unzlibSync, decompressSync } from 'fflate';
2
2
  import { Buffer } from 'buffer';
3
+ /** @returns {Buffer} */
3
4
  export const unzipSync = (input) => Buffer.from(decompressSync(input));
4
5
  export function inflate(input, callback) {
5
6
  try {
@@ -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.ts" />
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<Page<ContentEntity>>;
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: string;
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
- get<T extends JsonValue = JsonValue>(key: string): Promise<T | undefined>;
261
- set(key: string, value: JsonValue): Promise<void>;
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<Page<ContentEntity> & {
38
- name?: string;
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 {
@@ -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 {};
@@ -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 LyricsDocument {
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;
@@ -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
+ }
@@ -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?: {
@@ -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
+ }
@@ -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.2.3",
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