@shiqianjiang/ceru-plugin-sdk 0.3.12 → 0.3.13

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';
@@ -346,6 +347,9 @@ export declare function definePlugin(entry: LogicEntry): LogicEntry;
346
347
  export declare function defineSurface(entry: SurfaceEntry): SurfaceEntry;
347
348
  export { defineNativeView, assertNativeView } from './native-view.js';
348
349
  export type { NativeView, NativeViewSection, NativeViewAction } from './native-view.js';
350
+ /** Host-side playlist delegation; import in the Electron main/renderer host, not in a plugin. */
351
+ export { createHostLibraryBridge } from './host-library.js';
352
+ export type { HostLibraryServices } from './host-library.js';
349
353
  export declare function defineGuestAdapter(entry: GuestEntry): GuestEntry;
350
354
  export declare function defineManifest(manifest: PluginManifest): PluginManifest;
351
355
  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.13",
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",