@shiqianjiang/ceru-plugin-sdk 0.3.12 → 0.3.14

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 CHANGED
@@ -1,5 +1,12 @@
1
1
  # SDK 变更记录
2
2
 
3
+ ## 0.3.13
4
+
5
+ - `ctx.library.playlists` 新增 `removeTracks({ target, items, permissionKey, operation })`,返回 `{ removed, notFound }`,不会创建或移动歌单。
6
+ - 新增 `clearPlaylist({ target, permissionKey, operation })`,清空歌单但保留歌单本体。
7
+ - 两个删除接口均要求 `library.delete`;`createHostLibraryBridge` 新增 `remove` / `clear` 宿主回调,并在持久化成功后调用 `changed(target)`。
8
+ - 新增 `assertRemovableTracks`(从包根导出与 `@shiqianjiang/ceru-plugin-sdk/validate` 子路径),在破坏性调用前校验纯曲目列表。
9
+
3
10
  ## 0.3.7
4
11
 
5
12
  - 公共 `scope: 'provider'` 歌曲不再要求 `pluginId`;Host 在调用用户选定的实现时才补入目标插件 ID。私有资源仍必须声明所有者。
@@ -1,8 +1,9 @@
1
- import type { LibraryAPI, LibraryPlaylist, PlaylistImportRequest, PlaylistLocation, PlaylistReference } from './library.js';
1
+ import type { LibraryAPI, LibraryPlaylist, PlaylistImportRequest, PlaylistLocation, PlaylistReference, PlaylistRemoveResult } from './library.js';
2
2
  import type { ContentEntity, OperationContext, Page } from './index.js';
3
+ type LibraryCapability = 'library.read' | 'library.write' | 'library.delete';
3
4
  /** Bind these functions to existing app services. No database, account or UI is created here. */
4
5
  export interface HostLibraryServices {
5
- authorize(permissionKey: string, capability: 'library.read' | 'library.write', operation: OperationContext, target?: PlaylistReference): Promise<void>;
6
+ authorize(permissionKey: string, capability: LibraryCapability, operation: OperationContext, target?: PlaylistReference): Promise<void>;
6
7
  chooseTarget(suggestedName: string | undefined, operation: OperationContext): Promise<PlaylistReference | null>;
7
8
  list(location: PlaylistLocation | undefined, cursor: string | undefined, operation: OperationContext): Promise<Page<LibraryPlaylist>>;
8
9
  getTracks(target: PlaylistReference, cursor: string | undefined, operation: OperationContext): Promise<Page<ContentEntity>>;
@@ -13,8 +14,16 @@ export interface HostLibraryServices {
13
14
  added: number;
14
15
  skipped: number;
15
16
  }>;
17
+ /**
18
+ * Delete the given tracks from an existing playlist and report how many rows
19
+ * were actually there. Cloud targets may need a paginated lookup first.
20
+ */
21
+ remove(target: PlaylistReference, items: ContentEntity[], operation: OperationContext): Promise<PlaylistRemoveResult>;
22
+ /** Keep the playlist, drop its tracks. */
23
+ clear(target: PlaylistReference, operation: OperationContext): Promise<void>;
16
24
  /** Notify the existing store/event bus only after persistence succeeds. */
17
25
  changed(target: PlaylistReference): void;
18
26
  }
19
27
  /** Core-side validation/delegation. Pass only a Host-authenticated OperationContext. */
20
28
  export declare function createHostLibraryBridge(services: HostLibraryServices): LibraryAPI;
29
+ export {};
@@ -1,3 +1,4 @@
1
+ import { assertRemovableTracks } from './validate.js';
1
2
  import { assertContentPage } from './music.js';
2
3
  function checkTarget(target) {
3
4
  if (!target ||
@@ -41,6 +42,28 @@ export function createHostLibraryBridge(services) {
41
42
  services.changed(target);
42
43
  return { cancelled: false, target, added: result.added, skipped: result.skipped };
43
44
  },
45
+ async removeTracks(input) {
46
+ checkTarget(input.target);
47
+ assertRemovableTracks(input.items);
48
+ input.operation.signal.throwIfAborted();
49
+ await services.authorize(input.permissionKey, 'library.delete', input.operation, input.target);
50
+ input.operation.signal.throwIfAborted();
51
+ const result = await services.remove(input.target, input.items, input.operation);
52
+ const removed = Number(result?.removed) || 0;
53
+ const notFound = Number(result?.notFound) || 0;
54
+ if (removed + notFound !== input.items.length)
55
+ throw new Error('Playlist removal result does not match the request');
56
+ services.changed(input.target);
57
+ return { removed, notFound };
58
+ },
59
+ async clearPlaylist(input) {
60
+ checkTarget(input.target);
61
+ input.operation.signal.throwIfAborted();
62
+ await services.authorize(input.permissionKey, 'library.delete', input.operation, input.target);
63
+ input.operation.signal.throwIfAborted();
64
+ await services.clear(input.target, input.operation);
65
+ services.changed(input.target);
66
+ },
44
67
  },
45
68
  };
46
69
  }
package/dist/index.d.ts CHANGED
@@ -5,6 +5,7 @@ import type { HostIconName, HostAssetName, LODASH_METHODS } from './catalog.js';
5
5
  export * from './catalog.js';
6
6
  export * from './http.js';
7
7
  export * from './library.js';
8
+ export * from './validate.js';
8
9
  export * from './sockets.js';
9
10
  import type { SocketAPI } from './sockets.js';
10
11
  import type { GuestAPI, GuestBootstrapAPI } from './guests.js';
@@ -129,10 +130,45 @@ export type ResolveResult = {
129
130
  ok: false;
130
131
  error: MusicFault;
131
132
  };
133
+ /**
134
+ * 高清封面协议(可选)。
135
+ *
136
+ * 存在的意义:系统媒体控件(Windows SMTC / Linux MPRIS / macOS NowPlaying)
137
+ * 按整卡尺寸(约 1000px)显示封面,而平台音源在搜索/歌单阶段给出的
138
+ * `artworkUrl` 往往是缩略图(如 QQ 500、酷狗 240、酷我 500、网易云默认)。
139
+ * 把这层「按歌曲拿到尽可能高清封面」的能力开放给插件——插件最清楚自家
140
+ * CDN 的尺寸参数规则,可据此直接改写 URL 或另行请求,而宿主无需了解各平台差异。
141
+ *
142
+ * 可选性:插件**不实现**本方法即为不支持,宿主必须静默回落到原有 `artwork`
143
+ * 封面。实现时若无法给出更清晰的图,返回 `undefined` 或原样返回入参即可,
144
+ * 宿主会自行判定是否采纳(不会因为返回低清/相同地址而报错)。
145
+ */
146
+ export interface ArtworkHiresRequest {
147
+ /**
148
+ * 完整歌曲信息(宿主透传,字段随平台而异,常见 `img`/`albumId`/`songmid`/
149
+ * `hash` 等)。插件可直接用它已有的 `img` 做尺寸转换,也可据此发起新请求。
150
+ */
151
+ song: JsonObject;
152
+ /**
153
+ * 宿主当前已持有的封面地址(多为平台缩略图,也可能是 blob:/data: URL)。
154
+ * 插件可据此改写尺寸参数;若它不可用则由 `song` 重新生成更合适的地址。
155
+ */
156
+ artworkUrl?: string;
157
+ /**
158
+ * 期望的长边像素提示。**不限定画质**——插件可按平台能力自由上调/下调或忽略,
159
+ * 最终以插件返回的地址为准。
160
+ */
161
+ targetSize?: number;
162
+ }
132
163
  export interface TrackProvider {
133
164
  search?(request: SearchRequest, operation: OperationContext): Promise<Page<ContentEntity>>;
134
165
  resolve?(resource: ResourceRef, quality: string | undefined, operation: OperationContext): Promise<ResolveResult>;
135
166
  lyrics?(resource: ResourceRef, operation: OperationContext): Promise<LyricsDocument>;
167
+ /**
168
+ * 高清封面协议(可选)。返回一张尽可能高清的封面 URL;
169
+ * 无法提供时返回 `undefined`(宿主回落原封面)。
170
+ */
171
+ artworkHires?(resource: ResourceRef, request: ArtworkHiresRequest, operation: OperationContext): Promise<string | undefined>;
136
172
  }
137
173
  export interface PlaylistProvider {
138
174
  search?(request: SearchRequest, operation: OperationContext): Promise<Page<ContentEntity>>;
@@ -346,6 +382,9 @@ export declare function definePlugin(entry: LogicEntry): LogicEntry;
346
382
  export declare function defineSurface(entry: SurfaceEntry): SurfaceEntry;
347
383
  export { defineNativeView, assertNativeView } from './native-view.js';
348
384
  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';
349
388
  export declare function defineGuestAdapter(entry: GuestEntry): GuestEntry;
350
389
  export declare function defineManifest(manifest: PluginManifest): PluginManifest;
351
390
  export declare function definePluginConfig<const T extends JsonObject>(config: T): T;
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
1
  export * from './catalog.js';
2
2
  export * from './http.js';
3
3
  export * from './library.js';
4
+ export * from './validate.js';
4
5
  export * from './sockets.js';
5
6
  export * from './music.js';
6
7
  export * from './lyrics.js';
@@ -21,6 +22,8 @@ export function defineSurface(entry) {
21
22
  return entry;
22
23
  }
23
24
  export { defineNativeView, assertNativeView } from './native-view.js';
25
+ /** Host-side playlist delegation; import in the Electron main/renderer host, not in a plugin. */
26
+ export { createHostLibraryBridge } from './host-library.js';
24
27
  export function defineGuestAdapter(entry) {
25
28
  return entry;
26
29
  }
package/dist/library.d.ts CHANGED
@@ -28,6 +28,19 @@ export interface PlaylistImportResult {
28
28
  added: number;
29
29
  skipped: number;
30
30
  }
31
+ export interface PlaylistRemoveRequest {
32
+ target: PlaylistReference;
33
+ /** Only `kind: 'track'` entities are accepted. */
34
+ items: ContentEntity[];
35
+ permissionKey: string;
36
+ operation: OperationContext;
37
+ }
38
+ export interface PlaylistRemoveResult {
39
+ /** Tracks that were actually in the playlist and are now gone. */
40
+ removed: number;
41
+ /** Tracks that matched nothing, so the caller can tell a no-op from a failure. */
42
+ notFound: number;
43
+ }
31
44
  export interface PlaylistImporterImplementation {
32
45
  /** Resolve a pasted link/ID and return one page. Host owns paging and the import UI. */
33
46
  getTracks(request: {
@@ -57,5 +70,16 @@ export interface LibraryAPI {
57
70
  }): Promise<Page<ContentEntity>>;
58
71
  /** Host handles destination selection, auth, deduplication, persistence and cloud sync. */
59
72
  import(request: PlaylistImportRequest): Promise<PlaylistImportResult>;
73
+ /**
74
+ * Delete tracks from an existing playlist. Requires `library.delete`; never
75
+ * creates or relocates a playlist. `removed + notFound` equals `items.length`.
76
+ */
77
+ removeTracks(request: PlaylistRemoveRequest): Promise<PlaylistRemoveResult>;
78
+ /** Empty a playlist while keeping the playlist itself. Requires `library.delete`. */
79
+ clearPlaylist(request: {
80
+ target: PlaylistReference;
81
+ permissionKey: string;
82
+ operation: OperationContext;
83
+ }): Promise<void>;
60
84
  };
61
85
  }
@@ -0,0 +1,7 @@
1
+ import type { ContentEntity } from './index.js';
2
+ /**
3
+ * Reject anything that is not a plain track list before a destructive call.
4
+ * Hosts pass untrusted renderer input here, so this must not depend on the
5
+ * caller having already validated shapes.
6
+ */
7
+ export declare function assertRemovableTracks(value: unknown): asserts value is ContentEntity[];
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Reject anything that is not a plain track list before a destructive call.
3
+ * Hosts pass untrusted renderer input here, so this must not depend on the
4
+ * caller having already validated shapes.
5
+ */
6
+ export function assertRemovableTracks(value) {
7
+ if (!Array.isArray(value) || value.length === 0)
8
+ throw new Error('Invalid playlist removal items');
9
+ if (value.length > 1000)
10
+ throw new Error('Invalid playlist removal items');
11
+ for (const item of value) {
12
+ if (!item || typeof item !== 'object')
13
+ throw new Error('Invalid playlist removal item');
14
+ const ref = item.ref;
15
+ if (!ref || typeof ref !== 'object' || ref.kind !== 'track')
16
+ throw new Error('Only tracks can be removed');
17
+ if (typeof ref.id !== 'string' || !ref.id)
18
+ throw new Error('Invalid playlist removal item');
19
+ }
20
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shiqianjiang/ceru-plugin-sdk",
3
- "version": "0.3.12",
3
+ "version": "0.3.14",
4
4
  "description": "Typed authoring contracts for Ceru Music v2 single-file plugins",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -58,6 +58,11 @@
58
58
  "import": "./dist/permissions.js",
59
59
  "default": "./dist/permissions.js"
60
60
  },
61
+ "./validate": {
62
+ "types": "./dist/validate.d.ts",
63
+ "import": "./dist/validate.js",
64
+ "default": "./dist/validate.js"
65
+ },
61
66
  "./services": {
62
67
  "types": "./dist/services.d.ts",
63
68
  "import": "./dist/services.js",