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 ADDED
@@ -0,0 +1,203 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 上海绫中信息技术有限公司 (Shanghai Lingzhong Information Technology Co., Ltd.)
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
202
+
203
+ Copyright 2026 上海绫中信息技术有限公司 (Shanghai Lingzhong Information Technology Co., Ltd.)
package/README.md CHANGED
@@ -1,3 +1,275 @@
1
- # Temporary Holding Version
1
+ # openvod-jssdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ OpenVOD 播放器接入 SDK(v1):把「登录 → 媒资 → 播放会话 → 签名 URL → 续签 → 换清晰度」的接入逻辑收敛为唯一公共 API,
4
+ 宿主只负责播放器元素与 UI。**零运行时依赖**(仅 `fetch`,可注入),浏览器 / Node 18+ / React Native 同一份实现。
5
+
6
+ 权威设计:`docs/vod/player-sdk-intent.md`(定位与范围)、`docs/vod/player-sdk-spec.md`(接口与语义)。
7
+ 接口参考:`docs/vod/api.md §2`(分发端 HTTP API)。首个消费方:`apps/player`。
8
+
9
+ ## 安装
10
+
11
+ ```bash
12
+ # npm 官方
13
+ npm i openvod-jssdk
14
+
15
+ # CNB 制品库(组织级 npm 制品库;地址在「制品库 → 设置 → 基础设置」查看)
16
+ npm i openvod-jssdk --registry=https://npm.cnb.cool/<组织>/<制品库>/-/packages/
17
+ # 长期使用建议写进项目 .npmrc:
18
+ # registry=https://npm.cnb.cool/<组织>/<制品库>/-/packages/
19
+ # always-auth=true
20
+ # //npm.cnb.cool/<组织>/<制品库>/-/packages/:_authToken=${CNB_TOKEN}
21
+ ```
22
+
23
+ 发布产物为 **ESM + CJS + 打包后的 `.d.ts`**,零运行时依赖(连 `@openvod/*` 私有包也不需要——公共 DTO 类型
24
+ 在 `src/types.ts` 是自包含镜像,一致性由 `bun run typecheck` 的编译期断言守住)。
25
+
26
+ ## 设计边界(不变量)
27
+
28
+ | 编号 | 不变量 |
29
+ |---|---|
30
+ | N1 | SDK **永不接触视频字节与密钥材料**:不请求 `/key`、不下载分片、不持有 CEK(解密在播放器 / 浏览器本地完成) |
31
+ | N2 | 全部签名 URL **一律来自 `play` 响应原样透出**,SDK 不生成 / 不校验 / 不拼接 |
32
+ | N3 | 业务语义以服务端为准:`limit` 回退、模板自动选择、会话复用、`expires_at` 判定都不在客户端复制 |
33
+ | N4 | **错误保真**:服务端错误码 / 文案 / HTTP 状态原样透出,SDK 只附加 `hint` 排查建议 |
34
+ | N5 | 重登一律经配置的凭据源重新 `login`(v1 无 refresh token) |
35
+
36
+ ## 快速开始
37
+
38
+ ```ts
39
+ import { createPlayerSdk } from "openvod-jssdk";
40
+
41
+ // ① 口令模式(SDK 负责 login / JWT 缓存 / 到期重登)
42
+ const sdk = createPlayerSdk({
43
+ baseUrl: "https://vod.example.com", // delivery 基址(http/https,自动去尾斜杠)
44
+ credential: { mode: "password", username: "viewer", password: "******" },
45
+ });
46
+
47
+ // ② tokenProvider 模式(宿主自治登录,推荐 Web 宿主经自己的后端换 JWT,口令不下发浏览器)
48
+ const sdk2 = createPlayerSdk({
49
+ baseUrl: "https://vod.example.com",
50
+ credential: {
51
+ mode: "tokenProvider",
52
+ getToken: async () => {
53
+ const res = await fetch("/api/session"); // 宿主的后端路由
54
+ const body = await res.json();
55
+ return { access_token: body.access_token, expires_at: body.expires_at };
56
+ },
57
+ },
58
+ });
59
+
60
+ // ③ static 模式(宿主已有 JWT 且自行负责续期):无重登能力,过期即抛错 + auth:changed{expired}
61
+ const sdk3 = createPlayerSdk({
62
+ baseUrl: "https://vod.example.com",
63
+ credential: { mode: "static", token: jwtFromHost, expires_at: "2026-10-17T08:00:00Z" }, // expires_at 可省(缺省缓存至 401)
64
+ });
65
+
66
+ // ④ attach 模式(不配置 credential):仅接管已有签名 URL,零请求
67
+ const sdk4 = createPlayerSdk({ baseUrl: "https://vod.example.com" });
68
+ const attached = sdk4.attachPlayback({ media_id: "55395830", manifest_url: signedUrlFromServer });
69
+ ```
70
+
71
+ ### 生命周期时序
72
+
73
+ ```
74
+ 宿主 SDK delivery
75
+ │ createPlayerSdk(config) ──▶ 同步构造(零网络请求)
76
+ │ sdk.listMedia() ─────────▶ getAccessToken ── login(或 getToken) ──▶ POST /v1/auth/login
77
+ │ ◀── JWT 缓存(leeway 内零请求;401 → 重登一次并重试)
78
+ │ sdk.play(id) ────────────▶ 会话缓存命中? ── 命中 → 零请求返回 handle
79
+ │ │ 未命中/将过期 → POST /v1/media/{id}/play
80
+ │ ◀── handle{ sid, manifest_url, expires_at, template_id, templates, subtitles }
81
+ │ video.src = manifest_url ─▶ (播放器自行取 /key 与分片;SDK 不介入)
82
+ │ ├─ 到期前 refreshLeewaySec:自动 play 重签 ─▶ emit playback:refreshed{auto}
83
+ │ sdk.on("playback:refreshed") ─ 宿主换源(保留进度,见下)
84
+ │ handle.switchTemplate(id) ▶ POST play(template_id) → 原位更新 ─▶ emit playback:template_changed
85
+ │ handle.dispose() / sdk.dispose() ▶ 停定时器 + 本地失效(服务端会话按 TTL 过期)
86
+ ```
87
+
88
+ ### 从列表到播放(完整生命周期)
89
+
90
+ ```ts
91
+ const page = await sdk.listMedia({ limit: 50 }); // 仅 READY 媒资;next_cursor v1 恒 null
92
+ const detail = await sdk.getMedia("55395830"); // probe / poster / custom(公开白名单)
93
+ const custom = parseCustomMetadata(detail.custom); // { category?, description?, tags? }(脏数据容错)
94
+
95
+ const handle = await sdk.play("55395830"); // 建 / 复用播放会话,签发签名主清单 URL
96
+ video.src = handle.manifest_url; // 清单 → 密钥 → 分片全链路已带签名
97
+
98
+ // 清晰度:handle.templates 是「该媒资实际存在的模板产物」,不是全部模板
99
+ const options = handle.templates.map((t) => ({ label: templateLabel(t), value: t.id }));
100
+ await handle.switchTemplate("ctemplate00000000000002"); // 复用会话换源;返回值仍是同一 handle
101
+ video.src = handle.manifest_url; // 换源后读最新字段(见下方「可变视图」)
102
+
103
+ // 字幕:URL 是 typ=v 签名地址;403 时 SDK 自动重签一次
104
+ const tracks = handle.subtitles;
105
+ const vtt = await handle.fetchSubtitleText(tracks[0]);
106
+
107
+ // 播放中 token 到期:SDK 自动重签并通知宿主换源
108
+ const off = sdk.on("playback:refreshed", (event) => {
109
+ video.src = event.manifest_url; // 事件 payload 与字段逐字一致
110
+ });
111
+
112
+ handle.dispose(); // 停自动续签 + 本地失效(不释放服务端会话)
113
+ ```
114
+
115
+ ### 变更订阅与生命周期
116
+
117
+ ```ts
118
+ const off = sdk.on((event) => console.log(event.type, event)); // 全量订阅
119
+ sdk.on("playback:template_changed", (e) => {/* 切清晰度成功 */});
120
+ sdk.on("error", (e) => {/* e.operation:login / list_media / get_media / play / refresh / switch_template / subtitle / auto_refresh */});
121
+ sdk.dispose(); // 清全部定时器与缓存(服务端会话按 TTL 自然过期)
122
+ ```
123
+
124
+ ## API 速览(完整签名见 spec §2.3)
125
+
126
+ | 调用 | 说明 |
127
+ |---|---|
128
+ | `sdk.auth.getAccessToken({ force? })` | 取有效 JWT(缓存命中零请求;到期前按 leeway 重登;401 兜底强制重登) |
129
+ | `sdk.auth.setCredential(source \| null)` | 运行时切换身份:清 token / 会话缓存 / 定时器,旧句柄全部 `disposed` |
130
+ | `sdk.listMedia({ limit?, signal? })` | 媒资列表(`limit` 原样传给服务端,由服务端裁决) |
131
+ | `sdk.getMedia(id, { signal? })` | 媒资详情(非 READY 也返回,`playable=false`) |
132
+ | `sdk.play(id, { templateId?, forceNew?, signal? })` | 建 / 复用会话;**本地缓存新鲜时零请求**;并发同语义调用 single-flight |
133
+ | `sdk.attachPlayback(descriptor)` | 接管已有签名 URL(零请求;无凭据时 `refresh` / `switchTemplate` 抛 `sdk_no_credential`) |
134
+ | `sdk.fetchSubtitleText(track)` | 拉 VTT 文本(自动定位所属句柄以支持 403 重签重试) |
135
+ | `handle.switchTemplate(id)` | 复用会话换源(`id === 当前 template_id` 时空操作;失败不打断当前播放) |
136
+ | `handle.refresh({ force? })` | 重新签发;`force: true` 强制请求(用于「重新播放」) |
137
+ | `handle.fetchSubtitleText(track)` | 句柄内字幕文本(403 → 重签 → 新 URL 重试一次) |
138
+ | `handle.dispose()` | 停定时器 + 句柄失效(服务端无释放端点) |
139
+ | `sdk.dispose()` | 清全部定时器与缓存;销毁后所有入口抛 `sdk_disposed` |
140
+
141
+ ### 配置项(`PlayerSdkConfig`)
142
+
143
+ | 字段 | 默认 | 说明 |
144
+ |---|---|---|
145
+ | `baseUrl` | 必填 | delivery 基址,仅 http/https;非法抛 `sdk_invalid_config` |
146
+ | `credential` | 无 | 见上文三种模式 + attach |
147
+ | `fetch` | 全局 `fetch` | 注入自定义实现(RN / 测试 / 代理) |
148
+ | `timeoutMs` | `10000` | 单请求超时 |
149
+ | `retries` | `0` | **幂等 GET** 的网络层重试次数(5xx / 网络失败;POST 不重试) |
150
+ | `jwtRefreshLeewaySec` | `300` | JWT 到期前多久重登 |
151
+ | `refreshLeewaySec` | `300` | 会话 / 清单 token 到期前多久自动重签 |
152
+ | `autoRefresh` | `true` | 关掉后只提供手动 `refresh()` |
153
+ | `storage` | 无(纯内存) | 注入 JWT 持久化(仅存 `{ access_token, expires_at, identity }`,**不存口令 / 播放 URL**)。安全建议:**不推荐 `localStorage`**;浏览器用内存或 `sessionStorage`,移动端用 Keychain / Keystore 等安全存储 |
154
+ | `onEvent` | 无 | 全局事件监听(等价 `sdk.on(listener)`) |
155
+
156
+ ## 错误处理
157
+
158
+ ```ts
159
+ import { DeliveryError, PlayerSdkError, describeError } from "openvod-jssdk";
160
+
161
+ try {
162
+ await sdk.play(mediaId);
163
+ } catch (e) {
164
+ if (e instanceof DeliveryError) {
165
+ e.code; // api.md §0.2 错误码(类型来自契约 ErrorCode)
166
+ e.status; // HTTP 状态;0 = 网络 / 超时 / 取消
167
+ e.message; // 服务端文案原样(N4)
168
+ e.hint; // SDK 排查建议(describeError(code))
169
+ } else if (e instanceof PlayerSdkError) {
170
+ e.code; // sdk_invalid_config | sdk_no_credential | sdk_disposed | sdk_bad_response
171
+ }
172
+ }
173
+ ```
174
+
175
+ 高频错误:
176
+
177
+ | 场景 | 表现 | 处理 |
178
+ |---|---|---|
179
+ | 分发端未启动 / CORS 未放行 | `DeliveryError{code:"internal", status:0}` | 检查 `DELIVERY_CORS_ORIGINS` 是否放行宿主源站 |
180
+ | 账号被禁 / 口令已变 | `unauthorized`(重登一次后仍 401)+ `auth:changed{expired}` | 引导重新登录或 `setCredential()` |
181
+ | 播放器内清单 / 密钥 / 分片 403 | 播放中断(SDK 无法感知播放器内部请求) | 调 `handle.refresh({ force: true })` 换源 |
182
+ | 并发会话达上限 | `session_limit`(**`forceNew` 不绕过上限**) | 等旧会话过期或管理端调大 `max_concurrent_sessions` |
183
+ | 媒资未就绪 / 模板无产物 | `not_playable` | 回列表或从 `handle.templates` 重选 |
184
+
185
+ ## 两段必备的宿主代码
186
+
187
+ ### 换源保留进度(自动续签 / 切清晰度通用)
188
+
189
+ `switchTemplate` / `refresh` 会换掉 `manifest_url`(新 token),播放器换源后应恢复进度:
190
+
191
+ ```ts
192
+ let resume: { time: number; wasPlaying: boolean } | null = null;
193
+
194
+ sdk.on("playback:refreshed", (event) => {
195
+ resume = { time: video.currentTime, wasPlaying: !video.paused };
196
+ video.src = event.manifest_url; // 换源(hls.js 需 destroy + attachMedia 重建)
197
+ });
198
+
199
+ video.addEventListener("loadedmetadata", () => {
200
+ if (!resume) return;
201
+ video.currentTime = resume.time; // 恢复失败请静默从头,不要抛给用户
202
+ if (resume.wasPlaying) void video.play().catch(() => {});
203
+ resume = null;
204
+ });
205
+ ```
206
+
207
+ ### 播放器内 403 处置(清单 / 密钥 / 分片)
208
+
209
+ 浏览器原生 HLS 与 hls.js 的分片 / 密钥请求 SDK 无法感知(SDK 不接触视频字节,N1)。播放器报错或长时间
210
+ 黑屏时,用它换一套新 token 再重载:
211
+
212
+ ```ts
213
+ async function recoverPlayback(errorCode?: number) {
214
+ if (errorCode !== 403) return; // 只在 403 bad_token 场景重签
215
+ await handle.refresh({ force: true }); // 复用会话重签(不新建会话、不消耗并发额度)
216
+ video.src = handle.manifest_url; // 再换源;必要时 resume 进度
217
+ }
218
+ ```
219
+
220
+ ## 排错清单
221
+
222
+ | 现象 | 排查顺序 |
223
+ |---|---|
224
+ | 列表页报 `internal / status 0` | ① 分发端是否启动:`curl <baseUrl>/healthz`;② 宿主源站是否在 `DELIVERY_CORS_ORIGINS`;③ 浏览器直连地址是否可达(运行时 `delivery_base` 是否正确) |
225
+ | 列表能出、点进播放黑屏 | ① token 是否过期(`handle.expires_at`);② 桶(COS / RustFS)是否放行宿主源站 CORS(分片直连对象存储);③ 产物是否完整(管理端产物列表) |
226
+ | 播到一半 403 / 后段失败 | token 与分片预签名过期:调大 `refreshLeewaySec` 观察自动重签,或按上文「播放器内 403 处置」手动重签 |
227
+ | `session_limit`(409) | 同账号并发会话达上限(`forceNew` **不绕过**):等 TTL 过期或管理端调大 `max_concurrent_sessions` |
228
+ | `not_playable`(409) | 媒资未就绪或所选模板无产物:回列表,或从 `handle.templates` 重选 |
229
+ | `auth:changed{expired}` | 账号被禁 / 口令已变:`setCredential()` 换凭据,或引导重新登录 |
230
+ | React 视图不更新 | `handle` 是可变视图:`switchTemplate` / `refresh` 后需重读字段重建快照(见「换源保留进度」) |
231
+
232
+ ## 已知约束与宿主职责
233
+
234
+ - **`PlaybackHandle` 是可变视图**:`switchTemplate` / `refresh` 原位更新并返回**同一实例**。React 用快照驱动渲染
235
+ (参考 `apps/player/src/components/PlayView.tsx` 的 `snapshot(handle)`),不要靠引用比较触发重渲染。
236
+ - **换源是宿主职责**:SDK 只发事件(`playback:refreshed` / `playback:template_changed`),把新 `manifest_url`
237
+ 赋给播放器元素由宿主完成;换源后的进度保留同样由宿主实现。
238
+ - **字幕挂载与渲染**:SDK 只给轨道数据与 VTT 文本,不做解析 / 样式 / 重排。
239
+ - **自动续签失败**:先等 30s 重试一次,仍失败发 `error{operation:"auto_refresh"}` 并停止(防故障放大)。
240
+ - **多标签 / 多账号**:`storage` 默认不启用(纯内存,关标签即失效);启用时仅按 `identity` 校验,切换身份自动清除。
241
+ - 客户端不复制服务端策略:`limit` 非法回退、模板自动选择、会话并发上限一律由服务端裁决。
242
+
243
+ ## 开发
244
+
245
+ ```bash
246
+ bun test packages/player-sdk # 单测矩阵(注入 fetch + 假时钟,无真实网络)
247
+ bun run --cwd packages/player-sdk test:coverage # 同上 + 覆盖率(text + coverage/lcov.info)
248
+ bun run --cwd packages/player-sdk typecheck # tsc(含契约镜像的编译期一致性断言)
249
+ bun run --cwd packages/player-sdk build # tsup → dist/{index.js,index.cjs,index.d.ts}
250
+ ```
251
+
252
+ - 源码:`src/{index,config,client,auth,media,playback,subtitles,events,errors,types}.ts`
253
+ - `src/types.ts` 是公共 DTO 的**自包含镜像**(发布包零依赖,声明文件不得出现私有包 import);
254
+ 与 `packages/contracts` 的一致性由 `test/contract-parity.ts`(编译期,随 `typecheck`)+ `test/errors.test.ts`
255
+ (运行时逐字比对 ERROR_CODES)守住。
256
+ - 新增能力必须同步:`docs/vod/player-sdk-spec.md`(接口语义)→ 单测(T 编号)→ 本 README。
257
+
258
+ ## 发布(npm 官方 + CNB 制品库)
259
+
260
+ ```bash
261
+ bun run --cwd packages/player-sdk publish:dry # 演练:构建 + 打包清单(不联网、无需令牌)
262
+ bun run --cwd packages/player-sdk publish:npm # 只发 npm 官方
263
+ bun run --cwd packages/player-sdk publish:cnb # 只发 CNB 制品库
264
+ bun run --cwd packages/player-sdk publish:both # 两个都发(= 发版流水线用的命令)
265
+ ```
266
+
267
+ - **版本号唯一真源是根 `package.json` 的 `version`**(本包刻意不声明 `version`,仓库守卫见
268
+ `apps/admin/test/version-source.test.ts`);脚本读它并注入发布清单,`--version` 可显式覆盖(补发历史版本)。
269
+ - 发布清单在 `.run/sdk-publish/` 暂存生成:`exports` 指向 `dist/`(仓库内仍指向 `src/`,供 workspace 直引);
270
+ 脚本还会断言产物自包含(4 个产物文件不得 import 私有包)。
271
+ - 令牌只经环境变量传入、临时 `.npmrc` 权限 600 且用后即删:`NPM_TOKEN`(npm 官方)、
272
+ `CNB_NPM_TOKEN`(CNB,流水线内缺省回退内置 `CNB_TOKEN`)、`CNB_NPM_REGISTRY`(制品库地址)。
273
+ - **CI**:`.cnb.yml` 的 `.publish-sdk` 任务在 **`tag_push`** 时自动执行(也可用仓库页「发布播放器SDK」按钮手动触发):
274
+ 单测覆盖率 → `testing:coverage` 上报 CNB 洞察/徽章(红线 95%)→ 发布到两个制品库;
275
+ `NPM_TOKEN` 经密钥仓库 `arsrna/env` 的 `npm.yml` 注入。tag 名与根版本不一致时脚本会拒绝发布。