@shiqianjiang/ceru-plugin-sdk 0.3.5 → 0.3.7
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 +12 -0
- package/README.md +2 -0
- package/dist/index.d.ts +11 -1
- package/dist/lyrics.d.ts +2 -2
- package/dist/music.d.ts +19 -0
- package/dist/music.js +75 -16
- package/dist/services.d.ts +1 -0
- package/dist/services.js +13 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# SDK 变更记录
|
|
2
2
|
|
|
3
|
+
## 0.3.7
|
|
4
|
+
|
|
5
|
+
- 公共 `scope: 'provider'` 歌曲不再要求 `pluginId`;Host 在调用用户选定的实现时才补入目标插件 ID。私有资源仍必须声明所有者。
|
|
6
|
+
- `CrLyric` 新增 TTML 同构的 `translations` / `romanizations` 子行及逐字时间轴,保留单数纯文本字段以兼容旧 Host。
|
|
7
|
+
- `LyricWord` 新增可选 `translation`,歌词断言现在严格校验主歌词和附属歌词的所有词级字段与时间顺序。
|
|
8
|
+
- `LyricExportFormat` 新增 `ttml`,逐字翻译/音译可无损导出后再次解析。
|
|
9
|
+
|
|
10
|
+
## 0.3.6
|
|
11
|
+
|
|
12
|
+
- `ResourceRef.scope: 'provider'` 标记公共平台歌曲 ID;支持 Host 按用户的播放/歌词路由选择实现。私有资源默认仍归原插件,`retargetTrackRef` 跨插件时只保留公共标识,剥离私有数据。
|
|
13
|
+
- `TrackMetadata.qualitySizes` 按音质 ID 返回真实字节数,供原生下载界面显示;校验拒绝负值、非整数及未声明音质。
|
|
14
|
+
|
|
3
15
|
## 0.3.5
|
|
4
16
|
|
|
5
17
|
- Web Surface 自动上报挂载内容高度;Host 可按视口调整短弹框高度,长内容保留滚动,关闭后停止尺寸观察。
|
package/README.md
CHANGED
|
@@ -56,6 +56,8 @@ const icon = hostIcon('platform.tx')
|
|
|
56
56
|
|
|
57
57
|
动作需要在 Manifest 中声明。平台图标复用 Host 资源,不内嵌图片。
|
|
58
58
|
|
|
59
|
+
日志支持单条消息或消息加结构化详情:`ctx.log.info('请求完成')`、`ctx.log.info('请求完成', { status: 200 })`。详情对象由 Host 统一脱敏并序列化为同一条日志,插件不需要手动 `JSON.stringify`;过长字段会保留首尾并标记截断。`undefined` 不会被追加为额外日志参数。
|
|
60
|
+
|
|
59
61
|
CLI 并非必需。插件也可以直接写成 `exports.manifest`、`exports.activate`、`exports.surfaces` 的单个 JavaScript 文件,通过 `require('@ceru/http')` 等内置模块使用相同能力。第三方 npm 包必须在发行前打入文件。
|
|
60
62
|
|
|
61
63
|
运行配置通过 `await ctx.config.get<PluginConfig>()` 读取。配置默认值来自静态 `exports.manifest.config`,个性化发行值来自签名后的 `personalization.config`;Host 递归合并后再交给插件。`definePluginConfig()` 可为外部 TS/JS 配置保留完整字段提示。
|
package/dist/index.d.ts
CHANGED
|
@@ -31,11 +31,21 @@ export type HostLodash = Pick<LoDashStatic, (typeof LODASH_METHODS)[number]>;
|
|
|
31
31
|
export * from './manifest.js';
|
|
32
32
|
import type { JsonValue, JsonObject, MaybePromise, Disposable, PluginManifest } from './manifest.js';
|
|
33
33
|
export interface ResourceRef {
|
|
34
|
-
|
|
34
|
+
/**
|
|
35
|
+
* Owning plugin for private resources. Public provider-scoped tracks may omit
|
|
36
|
+
* this field so a playlist/search result does not pin playback to its source
|
|
37
|
+
* plugin; the Host fills it in only when invoking a selected implementation.
|
|
38
|
+
*/
|
|
39
|
+
pluginId?: string;
|
|
35
40
|
providerId: string;
|
|
36
41
|
connectionId?: string;
|
|
37
42
|
kind: string;
|
|
38
43
|
id: string;
|
|
44
|
+
/** Public canonical track ID within providerId. Allows the Host's selected resolver.
|
|
45
|
+
* Omit for plugin/account-private IDs. Cannot be combined with connectionId.
|
|
46
|
+
* Cross-plugin calls receive only this public identity, never data.
|
|
47
|
+
*/
|
|
48
|
+
scope?: 'provider';
|
|
39
49
|
/** Opaque plugin-owned JSON persisted by the Host and returned only to this plugin. */
|
|
40
50
|
data?: JsonObject;
|
|
41
51
|
}
|
package/dist/lyrics.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { CrLyric } from './music.js';
|
|
2
2
|
import type { ResourceRef, OperationContext } from './index.js';
|
|
3
3
|
export type LyricInputFormat = 'auto' | 'lrc' | 'enhanced-lrc' | 'yrc' | 'qrc' | 'krc' | 'ttml' | 'plain';
|
|
4
|
-
export type LyricExportFormat = 'lrc' | 'enhanced-lrc' | 'yrc';
|
|
4
|
+
export type LyricExportFormat = 'lrc' | 'enhanced-lrc' | 'yrc' | 'ttml';
|
|
5
5
|
export interface LyricParseRequest {
|
|
6
6
|
track: ResourceRef;
|
|
7
7
|
format: LyricInputFormat;
|
|
@@ -17,7 +17,7 @@ export interface LyricExportResult {
|
|
|
17
17
|
format: LyricExportFormat;
|
|
18
18
|
text: string;
|
|
19
19
|
mime: 'text/plain';
|
|
20
|
-
extension: 'lrc' | 'yrc';
|
|
20
|
+
extension: 'lrc' | 'yrc' | 'ttml';
|
|
21
21
|
}
|
|
22
22
|
/** Parsing/decryption/serialization belongs to plugins, not the player or download manager. */
|
|
23
23
|
export interface LyricConverter {
|
package/dist/music.d.ts
CHANGED
|
@@ -1,11 +1,19 @@
|
|
|
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
|
+
/** Optional translation aligned with this timed source word. */
|
|
5
|
+
translation?: string;
|
|
4
6
|
romanization?: string;
|
|
5
7
|
startTimeMs: number;
|
|
6
8
|
endTimeMs: number;
|
|
7
9
|
text: string;
|
|
8
10
|
}
|
|
11
|
+
/** A translation or romanization, optionally preserving its own timed words. */
|
|
12
|
+
export interface LyricSubLine {
|
|
13
|
+
language?: string;
|
|
14
|
+
text: string;
|
|
15
|
+
words?: LyricWord[];
|
|
16
|
+
}
|
|
9
17
|
export interface LyricLine {
|
|
10
18
|
isBackground?: boolean;
|
|
11
19
|
isDuet?: boolean;
|
|
@@ -14,6 +22,9 @@ export interface LyricLine {
|
|
|
14
22
|
text: string;
|
|
15
23
|
translation?: string;
|
|
16
24
|
romanization?: string;
|
|
25
|
+
/** Structured TTML-style alternatives. Singular fields remain backward compatible. */
|
|
26
|
+
translations?: LyricSubLine[];
|
|
27
|
+
romanizations?: LyricSubLine[];
|
|
17
28
|
words?: LyricWord[];
|
|
18
29
|
}
|
|
19
30
|
export interface CrLyric {
|
|
@@ -28,12 +39,18 @@ export interface CrLyric {
|
|
|
28
39
|
/** @deprecated Use CrLyric. */
|
|
29
40
|
export type LyricsDocument = CrLyric;
|
|
30
41
|
export interface TrackMetadata {
|
|
42
|
+
/** Optional platform hash; not a plugin owner or routing key. */
|
|
43
|
+
hash?: string;
|
|
44
|
+
/** Original display sizes when exact bytes are unavailable. Never infer bytes from these labels. */
|
|
45
|
+
qualitySizeLabels?: Record<string, string>;
|
|
31
46
|
artists: string[];
|
|
32
47
|
album?: {
|
|
33
48
|
id?: string;
|
|
34
49
|
title: string;
|
|
35
50
|
};
|
|
36
51
|
qualities?: string[];
|
|
52
|
+
/** Actual file sizes in bytes, keyed by the same IDs as qualities. Omit unknown sizes. */
|
|
53
|
+
qualitySizes?: Record<string, number>;
|
|
37
54
|
artworkUrl?: string;
|
|
38
55
|
durationMs?: number;
|
|
39
56
|
}
|
|
@@ -66,6 +83,8 @@ export interface MusicChart extends ContentEntity {
|
|
|
66
83
|
chart?: ChartMetadata;
|
|
67
84
|
}
|
|
68
85
|
export declare function assertResourceRef(value: unknown): asserts value is ResourceRef;
|
|
86
|
+
/** Retarget a public track without disclosing the original plugin's private data. */
|
|
87
|
+
export declare function retargetTrackRef(ref: ResourceRef, pluginId: string): ResourceRef;
|
|
69
88
|
export declare function assertContentPage(value: unknown): void;
|
|
70
89
|
export declare function assertResolveResult(value: unknown): asserts value is ResolveResult;
|
|
71
90
|
export declare function assertLyricsDocument(value: unknown): asserts value is LyricsDocument;
|
package/dist/music.js
CHANGED
|
@@ -1,10 +1,47 @@
|
|
|
1
1
|
const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
|
|
2
2
|
const text = (value, max = 4096) => typeof value === 'string' && value.length <= max;
|
|
3
3
|
const milliseconds = (value) => Number.isFinite(value) && Number(value) >= 0;
|
|
4
|
+
function assertLyricWords(value, minimumStartTimeMs) {
|
|
5
|
+
if (!Array.isArray(value) || value.length > 10000)
|
|
6
|
+
throw new Error('Invalid lyric words');
|
|
7
|
+
let lastWord = minimumStartTimeMs;
|
|
8
|
+
for (const word of value) {
|
|
9
|
+
if (!record(word) ||
|
|
10
|
+
!milliseconds(word.startTimeMs) ||
|
|
11
|
+
!milliseconds(word.endTimeMs) ||
|
|
12
|
+
word.endTimeMs < word.startTimeMs ||
|
|
13
|
+
word.startTimeMs < lastWord ||
|
|
14
|
+
!text(word.text, 65536) ||
|
|
15
|
+
(word.translation !== undefined && !text(word.translation, 65536)) ||
|
|
16
|
+
(word.romanization !== undefined && !text(word.romanization, 65536)))
|
|
17
|
+
throw new Error('Invalid lyric word');
|
|
18
|
+
lastWord = word.startTimeMs;
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
function assertLyricSubLines(value) {
|
|
22
|
+
if (!Array.isArray(value) || value.length > 16)
|
|
23
|
+
throw new Error('Invalid lyric alternatives');
|
|
24
|
+
for (const item of value) {
|
|
25
|
+
if (!record(item) ||
|
|
26
|
+
!text(item.text, 65536) ||
|
|
27
|
+
(item.language !== undefined && !text(item.language, 128)))
|
|
28
|
+
throw new Error('Invalid lyric alternative');
|
|
29
|
+
if (item.words !== undefined)
|
|
30
|
+
assertLyricWords(item.words, 0);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
4
33
|
export function assertResourceRef(value) {
|
|
5
34
|
if (!record(value) ||
|
|
6
|
-
!['
|
|
35
|
+
!['providerId', 'kind', 'id'].every((key) => text(value[key], 2048) && value[key].length > 0) ||
|
|
36
|
+
(value.pluginId !== undefined && (!text(value.pluginId, 2048) || !value.pluginId)))
|
|
7
37
|
throw new Error('Invalid resource reference');
|
|
38
|
+
if (value.connectionId !== undefined && (!text(value.connectionId, 2048) || !value.connectionId))
|
|
39
|
+
throw new Error('Invalid resource connection');
|
|
40
|
+
if (value.scope !== undefined &&
|
|
41
|
+
(value.scope !== 'provider' || value.kind !== 'track' || value.connectionId !== undefined))
|
|
42
|
+
throw new Error('Provider scope requires a public track without a connection');
|
|
43
|
+
if (value.pluginId === undefined && value.scope !== 'provider')
|
|
44
|
+
throw new Error('Private resources require an owning plugin');
|
|
8
45
|
if (value.data !== undefined) {
|
|
9
46
|
if (!record(value.data))
|
|
10
47
|
throw new Error('Invalid resource private data');
|
|
@@ -19,6 +56,19 @@ export function assertResourceRef(value) {
|
|
|
19
56
|
throw new Error('Resource private data exceeds 64 KiB');
|
|
20
57
|
}
|
|
21
58
|
}
|
|
59
|
+
/** Retarget a public track without disclosing the original plugin's private data. */
|
|
60
|
+
export function retargetTrackRef(ref, pluginId) {
|
|
61
|
+
assertResourceRef(ref);
|
|
62
|
+
if (ref.kind !== 'track')
|
|
63
|
+
throw new Error('Expected a track reference');
|
|
64
|
+
if (!text(pluginId, 2048) || !pluginId)
|
|
65
|
+
throw new Error('Invalid target plugin');
|
|
66
|
+
if (ref.pluginId === pluginId)
|
|
67
|
+
return ref;
|
|
68
|
+
if (ref.scope !== 'provider')
|
|
69
|
+
throw new Error('Private tracks must stay with their owner');
|
|
70
|
+
return { pluginId, providerId: ref.providerId, kind: 'track', id: ref.id, scope: 'provider' };
|
|
71
|
+
}
|
|
22
72
|
export function assertContentPage(value) {
|
|
23
73
|
if (!record(value) || !Array.isArray(value.items) || value.items.length > 10000)
|
|
24
74
|
throw new Error('Invalid content page');
|
|
@@ -38,6 +88,24 @@ export function assertContentPage(value) {
|
|
|
38
88
|
throw new Error('Track metadata must contain artists');
|
|
39
89
|
if (item.metadata.durationMs !== undefined && !milliseconds(item.metadata.durationMs))
|
|
40
90
|
throw new Error('Invalid track duration');
|
|
91
|
+
const { qualities, qualitySizes, qualitySizeLabels, hash } = item.metadata;
|
|
92
|
+
if (hash !== undefined && !text(hash, 4096))
|
|
93
|
+
throw new Error('Invalid track hash');
|
|
94
|
+
if (qualitySizeLabels !== undefined &&
|
|
95
|
+
(!record(qualitySizeLabels) ||
|
|
96
|
+
Object.keys(qualitySizeLabels).length > 128 ||
|
|
97
|
+
Object.entries(qualitySizeLabels).some(([quality, label]) => !qualities?.includes(quality) || !text(label, 128))))
|
|
98
|
+
throw new Error('Invalid track quality size labels');
|
|
99
|
+
if (qualities !== undefined &&
|
|
100
|
+
(!Array.isArray(qualities) ||
|
|
101
|
+
qualities.length > 128 ||
|
|
102
|
+
!qualities.every((quality) => text(quality, 128) && !!quality)))
|
|
103
|
+
throw new Error('Invalid track qualities');
|
|
104
|
+
if (qualitySizes !== undefined &&
|
|
105
|
+
(!record(qualitySizes) ||
|
|
106
|
+
Object.keys(qualitySizes).length > 128 ||
|
|
107
|
+
Object.entries(qualitySizes).some(([quality, bytes]) => !qualities?.includes(quality) || !Number.isSafeInteger(bytes) || Number(bytes) <= 0)))
|
|
108
|
+
throw new Error('Invalid track quality sizes');
|
|
41
109
|
}
|
|
42
110
|
if (item.ref.kind === 'playlist' && item.playlist !== undefined) {
|
|
43
111
|
if (!record(item.playlist))
|
|
@@ -103,21 +171,12 @@ export function assertLyricsDocument(value) {
|
|
|
103
171
|
for (const field of ['translation', 'romanization'])
|
|
104
172
|
if (line[field] !== undefined && !text(line[field], 65536))
|
|
105
173
|
throw new Error('Invalid lyric translation');
|
|
106
|
-
if (line.
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
!milliseconds(word.startTimeMs) ||
|
|
113
|
-
!milliseconds(word.endTimeMs) ||
|
|
114
|
-
word.endTimeMs < word.startTimeMs ||
|
|
115
|
-
word.startTimeMs < lastWord ||
|
|
116
|
-
!text(word.text, 65536))
|
|
117
|
-
throw new Error('Invalid lyric word');
|
|
118
|
-
lastWord = word.startTimeMs;
|
|
119
|
-
}
|
|
120
|
-
}
|
|
174
|
+
if (line.translations !== undefined)
|
|
175
|
+
assertLyricSubLines(line.translations);
|
|
176
|
+
if (line.romanizations !== undefined)
|
|
177
|
+
assertLyricSubLines(line.romanizations);
|
|
178
|
+
if (line.words !== undefined)
|
|
179
|
+
assertLyricWords(line.words, line.startTimeMs);
|
|
121
180
|
}
|
|
122
181
|
if (value.plainText !== undefined && !text(value.plainText, 1048576))
|
|
123
182
|
throw new Error('Invalid plain lyrics');
|
package/dist/services.d.ts
CHANGED
|
@@ -119,6 +119,7 @@ export interface HostServiceEvents {
|
|
|
119
119
|
keys: string[];
|
|
120
120
|
};
|
|
121
121
|
}
|
|
122
|
+
export declare const HOST_SERVICE_EVENT_NAMES: readonly ["account.changed", "library.changed", "player.changed", "queue.changed", "lyrics.changed", "downloads.changed", "settings.changed", "theme.changed", "rooms.changed", "devices.changed", "permissions.changed"];
|
|
122
123
|
/** Contract first: availability must be checked before using services not connected by this Host. */
|
|
123
124
|
export interface HostServices {
|
|
124
125
|
capabilities: {
|
package/dist/services.js
CHANGED
|
@@ -1,3 +1,16 @@
|
|
|
1
|
+
export const HOST_SERVICE_EVENT_NAMES = [
|
|
2
|
+
'account.changed',
|
|
3
|
+
'library.changed',
|
|
4
|
+
'player.changed',
|
|
5
|
+
'queue.changed',
|
|
6
|
+
'lyrics.changed',
|
|
7
|
+
'downloads.changed',
|
|
8
|
+
'settings.changed',
|
|
9
|
+
'theme.changed',
|
|
10
|
+
'rooms.changed',
|
|
11
|
+
'devices.changed',
|
|
12
|
+
'permissions.changed',
|
|
13
|
+
];
|
|
1
14
|
/** Explicit allowlist for future Core routing; never forward arbitrary IPC channel names. */
|
|
2
15
|
export const HOST_SERVICE_METHODS = {
|
|
3
16
|
capabilities: ['list', 'get'],
|