openvod-jssdk 0.0.0-stage → 1.2.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/LICENSE +203 -0
- package/README.md +274 -2
- package/dist/index.cjs +1209 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +278 -0
- package/dist/index.d.ts +278 -0
- package/dist/index.js +1202 -0
- package/dist/index.js.map +1 -0
- package/package.json +44 -4
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
/** `GET /v1/media` 列表项(恒为 READY 媒资) */
|
|
2
|
+
interface MediaListItem {
|
|
3
|
+
id: string;
|
|
4
|
+
title: string;
|
|
5
|
+
poster_url: string | null;
|
|
6
|
+
duration_ms: number | null;
|
|
7
|
+
/** 自定义元数据公开白名单(spec.md §8.4);展示前用 `parseCustomMetadata` 收敛 */
|
|
8
|
+
custom: Record<string, unknown> | null;
|
|
9
|
+
}
|
|
10
|
+
/** ffprobe 摘要(系统 probe 元数据,ADR-0008) */
|
|
11
|
+
interface MediaProbe {
|
|
12
|
+
width: number | null;
|
|
13
|
+
height: number | null;
|
|
14
|
+
video_codec: string | null;
|
|
15
|
+
audio_codec: string | null;
|
|
16
|
+
bitrate_bps: number | null;
|
|
17
|
+
}
|
|
18
|
+
/** 字幕轨道元信息(无 URL;播放链路用 `PlaybackSubtitle`) */
|
|
19
|
+
interface MediaSubtitle {
|
|
20
|
+
id: string;
|
|
21
|
+
/** BCP-47 */
|
|
22
|
+
lang: string;
|
|
23
|
+
label: string;
|
|
24
|
+
is_default: boolean;
|
|
25
|
+
}
|
|
26
|
+
/** `GET /v1/media/{id}` 详情(非 READY 仍返回详情,`playable=false`) */
|
|
27
|
+
interface MediaDetail extends MediaListItem {
|
|
28
|
+
status: string;
|
|
29
|
+
probe: MediaProbe | null;
|
|
30
|
+
subtitles: MediaSubtitle[];
|
|
31
|
+
playable: boolean;
|
|
32
|
+
}
|
|
33
|
+
/** `GET /v1/media` 分页响应(`next_cursor` v1 恒 null,原样透传) */
|
|
34
|
+
interface MediaPage {
|
|
35
|
+
items: MediaListItem[];
|
|
36
|
+
next_cursor: string | null;
|
|
37
|
+
}
|
|
38
|
+
/** 播放链路字幕轨道(play 下发):`url` 为带 `typ=v` 签名 token 的 .vtt 地址 */
|
|
39
|
+
interface PlaybackSubtitle extends MediaSubtitle {
|
|
40
|
+
/** 签名 URL(原样透出,SDK 不拼接不裁剪) */
|
|
41
|
+
url: string;
|
|
42
|
+
}
|
|
43
|
+
/** 清晰度选项 = 该媒资实际存在的模板产物(旧布局为 `[]`) */
|
|
44
|
+
interface PlaybackTemplate {
|
|
45
|
+
id: string;
|
|
46
|
+
/** 模板行已删除(历史产物)为 null */
|
|
47
|
+
name: string | null;
|
|
48
|
+
is_default: boolean;
|
|
49
|
+
}
|
|
50
|
+
/** `POST /v1/media/{id}/play` 请求体(SDK 内部组装;`templateId` → `template_id` 单点映射) */
|
|
51
|
+
interface PlaybackRequest {
|
|
52
|
+
/** 同媒资未过期会话默认复用;true 强制新会话(仍受并发上限约束) */
|
|
53
|
+
force_new?: boolean;
|
|
54
|
+
/** 指定模板产物;`""` = 显式请求旧布局产物,缺省 = 服务端自动选择 */
|
|
55
|
+
template_id?: string | null;
|
|
56
|
+
}
|
|
57
|
+
/** 服务端错误码(api.md §0.2 全表;与共享包 ERROR_CODES、契约 ErrorCode 逐字对齐) */
|
|
58
|
+
type DeliveryErrorCode = "unauthorized" | "invalid_credentials" | "forbidden" | "bad_request" | "bad_token" | "not_found" | "not_playable" | "session_limit" | "rate_limited" | "not_implemented" | "internal";
|
|
59
|
+
|
|
60
|
+
/** 错误码 → 排查建议(未知码给出兜底文案;仅用于提示,不参与任何安全判断) */
|
|
61
|
+
declare function describeError(code: string | null | undefined): string;
|
|
62
|
+
/** 分发端错误(服务端错误码 / 网络失败统一形态) */
|
|
63
|
+
declare class DeliveryError extends Error {
|
|
64
|
+
/** 服务端错误码(api.md §0.2 全表);网络 / 超时 / 非 JSON 响应统一 "internal" */
|
|
65
|
+
readonly code: DeliveryErrorCode;
|
|
66
|
+
/** HTTP 状态码;网络层失败 = 0 */
|
|
67
|
+
readonly status: number;
|
|
68
|
+
/** SDK 附加排查建议(不覆盖服务端 message,见 §8) */
|
|
69
|
+
readonly hint?: string;
|
|
70
|
+
constructor(code: DeliveryErrorCode, message: string, status: number, hint?: string);
|
|
71
|
+
}
|
|
72
|
+
/** SDK 自身错误码 */
|
|
73
|
+
type PlayerSdkErrorCode = "sdk_invalid_config" | "sdk_no_credential" | "sdk_disposed" | "sdk_bad_response";
|
|
74
|
+
/** SDK 自身错误(配置非法 / 无凭据 / 已 dispose / 关键响应结构无法解析) */
|
|
75
|
+
declare class PlayerSdkError extends Error {
|
|
76
|
+
readonly code: PlayerSdkErrorCode;
|
|
77
|
+
constructor(code: PlayerSdkErrorCode, message: string);
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** fetch 形态(与全局 fetch 兼容;RN / 测试 / 自定义代理可注入) */
|
|
81
|
+
type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
|
|
82
|
+
|
|
83
|
+
/** 事件类型全表(payload 字段与契约 / api.md 逐字一致,零映射) */
|
|
84
|
+
type PlayerSdkEvent = {
|
|
85
|
+
type: "auth:changed";
|
|
86
|
+
reason: "login" | "refresh" | "switched" | "expired";
|
|
87
|
+
} | {
|
|
88
|
+
type: "playback:refreshed";
|
|
89
|
+
media_id: string;
|
|
90
|
+
manifest_url: string;
|
|
91
|
+
expires_at: string;
|
|
92
|
+
reason: "auto" | "manual" | "retry";
|
|
93
|
+
} | {
|
|
94
|
+
type: "playback:template_changed";
|
|
95
|
+
media_id: string;
|
|
96
|
+
template_id: string;
|
|
97
|
+
manifest_url: string;
|
|
98
|
+
} | {
|
|
99
|
+
type: "error";
|
|
100
|
+
operation: SdkOperation;
|
|
101
|
+
error: DeliveryError | PlayerSdkError;
|
|
102
|
+
};
|
|
103
|
+
/** error 事件的 operation 取值(SDK 的对外操作面) */
|
|
104
|
+
type SdkOperation = "login" | "list_media" | "get_media" | "play" | "refresh" | "switch_template" | "subtitle" | "auto_refresh";
|
|
105
|
+
type PlayerSdkEventListener = (event: PlayerSdkEvent) => void;
|
|
106
|
+
|
|
107
|
+
interface PlayerSdkConfig {
|
|
108
|
+
/** delivery 基址(必填;仅 http/https,自动去尾斜杠) */
|
|
109
|
+
baseUrl: string;
|
|
110
|
+
/** 凭据源;缺省 = attach 模式(仅 attachPlayback 可用) */
|
|
111
|
+
credential?: CredentialSource;
|
|
112
|
+
/** 注入 fetch(RN / 测试 / 自定义代理);缺省 globalThis.fetch */
|
|
113
|
+
fetch?: FetchLike;
|
|
114
|
+
/** 单请求超时(ms),缺省 10000 */
|
|
115
|
+
timeoutMs?: number;
|
|
116
|
+
/** 幂等 GET 的网络层重试次数(不含 §4.4 的 401 / 403 流程),缺省 0 */
|
|
117
|
+
retries?: number;
|
|
118
|
+
/** JWT 到期前多久触发重登(秒),缺省 300 */
|
|
119
|
+
jwtRefreshLeewaySec?: number;
|
|
120
|
+
/** 会话 / 清单 token 到期前多久触发自动重签(秒),缺省 300 */
|
|
121
|
+
refreshLeewaySec?: number;
|
|
122
|
+
/** 到期前自动重签(§4.3),缺省 true */
|
|
123
|
+
autoRefresh?: boolean;
|
|
124
|
+
/** JWT 持久化注入(§3.4);缺省纯内存 */
|
|
125
|
+
storage?: PlayerSdkStorage;
|
|
126
|
+
/** 全局事件监听(等价 sdk.on(listener)) */
|
|
127
|
+
onEvent?: (event: PlayerSdkEvent) => void;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** tokenProvider 可返回裸 token(TTL 未知)或带到期时间的对象(spec §3.1) */
|
|
131
|
+
interface TokenProviderResult {
|
|
132
|
+
access_token: string;
|
|
133
|
+
/** 支持 ISO 8601 字符串或 Unix 秒;缺省 = TTL 未知(缓存至 401 重取) */
|
|
134
|
+
expires_at?: string | number;
|
|
135
|
+
}
|
|
136
|
+
/** 四种鉴权模式(缺省 = attach:不配置 credential,仅 attachPlayback 可用) */
|
|
137
|
+
type CredentialSource = {
|
|
138
|
+
mode: "password";
|
|
139
|
+
username: string;
|
|
140
|
+
password: string;
|
|
141
|
+
} | {
|
|
142
|
+
mode: "tokenProvider";
|
|
143
|
+
getToken: () => string | TokenProviderResult | Promise<string | TokenProviderResult>;
|
|
144
|
+
} | {
|
|
145
|
+
mode: "static";
|
|
146
|
+
token: string;
|
|
147
|
+
expires_at?: string | number;
|
|
148
|
+
};
|
|
149
|
+
/**
|
|
150
|
+
* JWT 持久化注入(spec §3.4)。默认纯内存;SDK 不内置 localStorage(XSS 面,安全责任交宿主显式选择)。
|
|
151
|
+
* 仅存 `{ access_token, expires_at, identity }`,键 `openvod.player-sdk.token`;
|
|
152
|
+
* **绝不存口令、播放 URL、会话信息**。
|
|
153
|
+
*/
|
|
154
|
+
interface PlayerSdkStorage {
|
|
155
|
+
get(key: string): string | null | Promise<string | null>;
|
|
156
|
+
set(key: string, value: string): void | Promise<void>;
|
|
157
|
+
remove(key: string): void | Promise<void>;
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** custom 公开白名单(spec.md §8.4):分发端只下发 category / description / tags 三个键 */
|
|
161
|
+
interface CustomMetadata {
|
|
162
|
+
category?: {
|
|
163
|
+
id: string;
|
|
164
|
+
name: string;
|
|
165
|
+
path: string;
|
|
166
|
+
};
|
|
167
|
+
description?: string;
|
|
168
|
+
tags?: string[];
|
|
169
|
+
}
|
|
170
|
+
/**
|
|
171
|
+
* custom 公开白名单的防御性解析(spec §7):
|
|
172
|
+
* - `category` 需 `id` 与 `path` 均为非空字符串,否则丢弃;
|
|
173
|
+
* - `description` trim 后非空才保留;`tags` 丢弃空项、按首现去重;
|
|
174
|
+
* - 输入为 null / 非对象 / 脏结构 → 返回 `{}`,**解析失败不阻断播放**(容错口径同 spec.md §8.4)。
|
|
175
|
+
*/
|
|
176
|
+
declare function parseCustomMetadata(custom: unknown): CustomMetadata;
|
|
177
|
+
/** 清晰度选项展示名(spec §5.1):`name` 可为 null(模板行已删) */
|
|
178
|
+
declare function templateLabel(template: {
|
|
179
|
+
id: string;
|
|
180
|
+
name: string | null;
|
|
181
|
+
}): string;
|
|
182
|
+
|
|
183
|
+
interface PlayOptions {
|
|
184
|
+
/** 指定模板产物(proceed/{id}/{templateId}/);缺省 / null = 按服务端自动选择(spec.md §6.3) */
|
|
185
|
+
templateId?: string | null;
|
|
186
|
+
/** 强制新建会话(仍受并发上限约束,§4.5);缺省复用 */
|
|
187
|
+
forceNew?: boolean;
|
|
188
|
+
signal?: AbortSignal;
|
|
189
|
+
}
|
|
190
|
+
/** attach 接管(§5.4):零请求注册已有签名 URL 的播放描述 */
|
|
191
|
+
interface AttachedPlayback {
|
|
192
|
+
media_id: string;
|
|
193
|
+
manifest_url: string;
|
|
194
|
+
expires_at?: string | null;
|
|
195
|
+
sid?: string;
|
|
196
|
+
template_id?: string | null;
|
|
197
|
+
subtitles?: PlaybackSubtitle[];
|
|
198
|
+
templates?: PlaybackTemplate[];
|
|
199
|
+
}
|
|
200
|
+
/** 播放句柄:可更新视图(同一媒资同一实例,getter 读取最新值;switchTemplate / refresh 原位更新并返回自身) */
|
|
201
|
+
interface PlaybackHandle {
|
|
202
|
+
/** SDK 字段:play 传入的媒资 ID(服务端无此 wire 字段) */
|
|
203
|
+
readonly media_id: string;
|
|
204
|
+
/** 以下字段与 play 响应逐字一致(spec.md §6.1 / §11.1) */
|
|
205
|
+
readonly sid: string;
|
|
206
|
+
readonly manifest_url: string;
|
|
207
|
+
/** ISO 8601(会话到期时间) */
|
|
208
|
+
readonly expires_at: string;
|
|
209
|
+
/** `""` = 旧布局 */
|
|
210
|
+
readonly template_id: string;
|
|
211
|
+
readonly subtitles: PlaybackSubtitle[];
|
|
212
|
+
readonly templates: PlaybackTemplate[];
|
|
213
|
+
/** SDK 字段 */
|
|
214
|
+
readonly disposed: boolean;
|
|
215
|
+
/** 复用会话换源:指定另一套模板产物(§5.2);返回同一 handle(视图更新) */
|
|
216
|
+
switchTemplate(templateId: string, options?: {
|
|
217
|
+
signal?: AbortSignal;
|
|
218
|
+
}): Promise<PlaybackHandle>;
|
|
219
|
+
/** 重新签发(复用会话):force=true 跳过本地缓存强制请求 */
|
|
220
|
+
refresh(options?: {
|
|
221
|
+
force?: boolean;
|
|
222
|
+
signal?: AbortSignal;
|
|
223
|
+
}): Promise<PlaybackHandle>;
|
|
224
|
+
/** 拉取本句柄字幕的 VTT 文本(403 bad_token 自动重签重试一次,§4.4 / §6) */
|
|
225
|
+
fetchSubtitleText(track: PlaybackSubtitle, options?: {
|
|
226
|
+
signal?: AbortSignal;
|
|
227
|
+
}): Promise<string>;
|
|
228
|
+
/** 停自动续签 + 本地失效(服务端无释放端点,会话按 TTL 自然过期,§4.6) */
|
|
229
|
+
dispose(): void;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/** SDK 实例(spec §2.3) */
|
|
233
|
+
interface PlayerSdk {
|
|
234
|
+
readonly auth: {
|
|
235
|
+
/** 取有效 JWT:缓存命中零请求;到期前按 jwtRefreshLeewaySec 重登;401 强制重登(§4.4) */
|
|
236
|
+
getAccessToken(options?: {
|
|
237
|
+
force?: boolean;
|
|
238
|
+
}): Promise<string>;
|
|
239
|
+
/** 运行时切换身份:清 token / 会话缓存 / 定时器,旧句柄全部失效(§3.5);null = 退化为 attach 模式 */
|
|
240
|
+
setCredential(source: CredentialSource | null): void;
|
|
241
|
+
};
|
|
242
|
+
/** 媒资列表(GET /v1/media;恒为 READY;next_cursor v1 恒 null,透传) */
|
|
243
|
+
listMedia(options?: {
|
|
244
|
+
limit?: number;
|
|
245
|
+
signal?: AbortSignal;
|
|
246
|
+
}): Promise<MediaPage>;
|
|
247
|
+
/** 媒资详情(GET /v1/media/{id};非 READY 仍返回详情,playable=false) */
|
|
248
|
+
getMedia(mediaId: string, options?: {
|
|
249
|
+
signal?: AbortSignal;
|
|
250
|
+
}): Promise<MediaDetail>;
|
|
251
|
+
/** 建 / 复用播放会话并签发签名 URL(§4.1 / §4.2);同媒资默认命中本地缓存(零请求) */
|
|
252
|
+
play(mediaId: string, options?: PlayOptions): Promise<PlaybackHandle>;
|
|
253
|
+
/** 接管已有签名 URL:零请求(§5.4);无 credential 时 refresh / switchTemplate 抛 sdk_no_credential */
|
|
254
|
+
attachPlayback(descriptor: AttachedPlayback): PlaybackHandle;
|
|
255
|
+
/** 拉取字幕 VTT 文本(自动定位所属句柄以支持 403 重签重试;未命中句柄则直接请求按原样失败) */
|
|
256
|
+
fetchSubtitleText(track: PlaybackSubtitle, options?: {
|
|
257
|
+
signal?: AbortSignal;
|
|
258
|
+
}): Promise<string>;
|
|
259
|
+
/** 事件订阅(按类型收窄 payload);返回取消函数 */
|
|
260
|
+
on<T extends PlayerSdkEvent["type"]>(type: T, listener: (event: Extract<PlayerSdkEvent, {
|
|
261
|
+
type: T;
|
|
262
|
+
}>) => void): () => void;
|
|
263
|
+
on(listener: PlayerSdkEventListener): () => void;
|
|
264
|
+
/** 清全部定时器与缓存(不释放服务端会话,§4.6) */
|
|
265
|
+
dispose(): void;
|
|
266
|
+
}
|
|
267
|
+
/**
|
|
268
|
+
* 创建播放器 SDK(**同步构造、零网络请求**;配置非法抛 `PlayerSdkError("sdk_invalid_config")`)。
|
|
269
|
+
*
|
|
270
|
+
* ```ts
|
|
271
|
+
* const sdk = createPlayerSdk({ baseUrl: "https://vod.example.com", credential: { mode: "password", username, password } });
|
|
272
|
+
* const handle = await sdk.play("55395830");
|
|
273
|
+
* video.src = handle.manifest_url; // 清单 / 密钥 / 分片全链路已带签名
|
|
274
|
+
* ```
|
|
275
|
+
*/
|
|
276
|
+
declare function createPlayerSdk(config: PlayerSdkConfig): PlayerSdk;
|
|
277
|
+
|
|
278
|
+
export { type AttachedPlayback, type CredentialSource, type CustomMetadata, DeliveryError, type DeliveryErrorCode, type FetchLike, type MediaDetail, type MediaListItem, type MediaPage, type MediaProbe, type MediaSubtitle, type MediaPage as PageResponse, type PlayOptions, type PlaybackHandle, type PlaybackRequest, type PlaybackSubtitle, type PlaybackTemplate, type PlayerSdk, type PlayerSdkConfig, PlayerSdkError, type PlayerSdkErrorCode, type PlayerSdkEvent, type PlayerSdkEventListener, type PlayerSdkStorage, type SdkOperation, type TokenProviderResult, createPlayerSdk, describeError, parseCustomMetadata, templateLabel };
|