@vivix-ai/ivi-frontend-sdk 0.3.8 → 0.3.10

package/README.md

@@ -3,7 +3,9 @@
 用于前端应用集成 IVI 实时能力的 TypeScript SDK，包含：
 
 - 基于 `@vivix-ai/ivi-sdk-ts` 的 runtime 协调层
+- 通过 API 网关创建 IVI Session 的 HTTP 辅助方法
 - 面向舞台渲染的 React 组件与 hooks
+- 基于 OpenTelemetry API 的链路 span（SDK 不内置 exporter/provider）
 
 ## 安装依赖
 
@@ -111,6 +113,147 @@ const runtime = sdk.createRuntimeCoordinator(
 await runtime.start();
 ```
 
+### 1.1）通过 API 网关创建 IVI Session 并启动 runtime
+
+如果业务侧已经接入 API 网关，可直接使用 SDK 内置的 `createIVISession` HTTP 封装。该方法会调用 `POST /v1/ivi/sessions`，拿到 `ivi_session_id` / `endpoint` 后创建 WebSocket runtime。
+
+当创建会话响应里包含 `prebuild_trtc_info` 时，SDK 会把它转换成一个临时的 bootstrap source，并在 websocket 真实 `stage/track/source` 事件到达前，提前通过 `IVITrackSlot slot="main"` 展示画面。真实 source ready 后会自动接管，业务 UI 不需要区分“快速开播”和“常规开播”。
+
+```ts
+import {
+  createIVISession,
+  createRuntimeFromSession
+} from "@vivix-ai/ivi-frontend-sdk";
+
+const session = await createIVISession(
+  {
+    idempotencyKey: crypto.randomUUID(),
+    streamType: "TRTC",
+    iviVersion: "dev",
+    sessionParameters: {
+      resolution: "720p"
+    },
+    prebuiltCharacters: [
+      {
+        characterId: "character_claire",
+        characterPayload: characterJson
+      }
+    ],
+    prebuiltStream: {
+      streamId: "stream_claire",
+      mode: "character",
+      streamConfig: {
+        scene_description: "Claire on stage",
+        character_ids: ["character_claire"],
+        realtime_cvi_config: { enabled: false }
+      }
+    }
+  },
+  {
+    baseUrl: "https://api.example.com",
+    headers: async () => ({
+      Authorization: `Bearer ${token}`
+    })
+  }
+);
+
+const { runtime } = createRuntimeFromSession(session, {
+  fastStart: true,
+  bootstrapSlot: "main",
+  websocket: {
+    query: {
+      x_auth_jwt: authJwt
+    },
+    protocols: authJwt ? ["ivi", authJwt] : undefined
+  }
+});
+
+await runtime.start();
+```
+
+也可以一步完成创建 session 与 runtime：
+
+```ts
+import { createIVISessionRuntime } from "@vivix-ai/ivi-frontend-sdk";
+
+const { session, runtime } = await createIVISessionRuntime(request, {
+  http: {
+    baseUrl: "https://api.example.com",
+    headers: { Authorization: `Bearer ${token}` }
+  },
+  fastStart: true,
+  bootstrapSlot: "main"
+});
+
+await runtime.start();
+```
+
+`createIVISession` 返回值会保留原始 response，同时提供 SDK 归一化字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `iviSessionId` | `string` | 会话 ID，对应后端 `ivi_session_id` |
+| `endpoint` | `string` | IVI realtime websocket 地址 |
+| `trtcInfo` / `livekitInfo` | — | 会话级播放/传输信息（如果后端返回） |
+| `prebuildTrtcInfo` | — | 后端 `prebuild_trtc_info` 的 camelCase 视图 |
+| `prebuiltPlayback` | — | SDK 归一化后的快速开播播放源；存在时可用于 bootstrap source |
+| `raw` | `unknown` | 原始 HTTP response body |
+| `requestBody` | `Record<string, unknown>` | 实际发给网关的 snake_case JSON |
+
+`IviCreateIVISessionRequest` 使用 camelCase 字段，SDK 会在发送前转换为 CP transcoder 需要的 snake_case JSON：
+
+| SDK 字段 | HTTP 字段 |
+|----------|-----------|
+| `idempotencyKey` | `idempotency_key` |
+| `streamType` | `stream_type` |
+| `iviVersion` | `ivi_version` |
+| `sessionParameters` | `session_parameters` |
+| `prebuiltCharacters` | `prebuilt_characters` |
+| `prebuiltStream` | `prebuilt_stream` |
+| `enableDecoderPublish` | `enable_decoder_publish` |
+| `sessionRecording` | `session_recording` |
+
+> 浏览器侧不应依赖 TRTC `secret_key`。SDK 在归一化 TRTC 信息时会丢弃 `secret_key` / `secretKey`，播放器只使用拉流所需的 `app_id`、`room_id`、`user_id`、`user_sig`。
+
+### 1.2）OpenTelemetry 链路观测
+
+SDK 只依赖 `@opentelemetry/api` 并创建 spans，不配置上报目的地。业务应用只要在入口处配置自己的 OpenTelemetry provider/exporter，随后把 `telemetry` 透传给 SDK 即可；未配置 provider 时这些调用会自动 no-op。
+
+```ts
+import { context, trace } from "@opentelemetry/api";
+import { createIVISessionRuntime } from "@vivix-ai/ivi-frontend-sdk";
+
+const telemetry = {
+  tracer: trace.getTracer("my-live-page"),
+  context: context.active(), // 可接上按钮点击、页面路由等外部父链路
+  attributes: {
+    "app.feature": "ivi-live"
+  }
+};
+
+const { runtime } = await createIVISessionRuntime(request, {
+  http: {
+    baseUrl: "https://api.example.com",
+    headers: { Authorization: `Bearer ${token}` }
+  },
+  telemetry,
+  fastStart: true,
+  bootstrapSlot: "main"
+});
+
+await runtime.start();
+```
+
+会被串联的关键 spans 包括：
+
+- `ivi.session.create`：HTTP 创建 IVI Session
+- `ivi.runtime.create` / `ivi.runtime.start` / `ivi.runtime.stop`
+- `ivi.runtime.state_change`
+- `ivi.client.*`：底层 `@vivix-ai/ivi-sdk-ts` WebSocket 连接、发送、接收等 spans
+- `ivi.media.trtc.*` / `ivi.media.livekit.*`：远端视频可用、开始渲染、渲染完成等首屏关键点
+
+SDK span 不会写入 token、`user_sig`、TRTC `secret_key` 或完整业务 payload。低基数字段可以放在 `telemetry.attributes` 中统一附加。
+
 **使用自定义 WebSocket 运行时**（Node.js / 自定义环境）：
 
 ```ts
@@ -141,6 +284,7 @@ await runtime.start();
 | `transport` | `IviRealtimeTransport` | 通用 transport，直接透传给 `@vivix-ai/ivi-sdk-ts`；浏览器 LiveKit 场景可传 `LiveKitBrowserTransport` |
 | `onParseError` | `(error, rawMessage) => void` | 事件解析失败回调 |
 | `onLog` | `(entry) => void` | `IviClient` 链路日志回调，包含发送、transport 状态和重连链路 |
+| `telemetry` | `IviClientTelemetryOptions` | OpenTelemetry 配置；通常由上层 SDK 透传 |
 | `reconnect` | `IviClientReconnectOptions` | 自动重连配置；默认启用，指数退避 |
 | `sendWaitTimeoutMs` | `number` | 发送时等待连接恢复的超时，默认 `30000` ms，`<=0` 表示无限等待 |
 
@@ -219,6 +363,7 @@ runtime.sendSessionSourcePlaybackCompleted("source_001", "track_001");
 | `sources` | `Map<string, IviRuntimeSource>` | 所有 source（含 `status: created \| ready \| failed`） |
 | `conversationItems` | `Map<string, IviRuntimeConversationItem>` | 对话条目映射 |
 | `conversations` | `IviRuntimeConversationItem[]` | 对话有序列表 |
+| `bootstrap` | `IviRuntimeBootstrapViewState \| null` | prebuild 快速开播的临时 slot/track/source 绑定状态 |
 
 ---
 
@@ -298,6 +443,59 @@ export function AutoStagePage({ livekitToken }: { livekitToken: string }) {
 3. 浏览器 LiveKit 场景可传 `LiveKitBrowserTransport`
 4. WebSocket、测试 fake transport 或其它 transport 也通过同一个 `transport` 字段传入
 
+### 方式 C：使用 `useIviSessionRuntime` 创建会话并管理 runtime
+
+当希望把 `createIVISession` 也放进 SDK 接入流程时，可以使用 `useIviSessionRuntime`。它会在挂载后创建 IVI Session、构造 WebSocket runtime，并在 `autoStart` 为 `true` 时自动启动。
+
+```tsx
+import {
+  IVIStageView,
+  IVITrackSlot,
+  useIviSessionRuntime,
+  type IviCreateIVISessionRequest
+} from "@vivix-ai/ivi-frontend-sdk";
+
+export function FastStartStagePage({
+  request,
+  token,
+  authJwt
+}: {
+  request: IviCreateIVISessionRequest;
+  token: string;
+  authJwt?: string;
+}) {
+  const { runtime, session, status, error } = useIviSessionRuntime({
+    request,
+    http: {
+      baseUrl: "https://api.example.com",
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    },
+    fastStart: true,
+    bootstrapSlot: "main",
+    websocket: {
+      query: {
+        x_auth_jwt: authJwt
+      },
+      protocols: authJwt ? ["ivi", authJwt] : undefined
+    }
+  });
+
+  if (error) return <div>{error.message}</div>;
+
+  return (
+    <IVIStageView runtime={runtime}>
+      <IVITrackSlot slot="main" showVolumeControl showSubtitle />
+      <span>{status}</span>
+      <span>{session?.iviSessionId}</span>
+    </IVIStageView>
+  );
+}
+```
+
+`request` 变化会重新创建 session/runtime；业务侧应使用 `useMemo` 或稳定引用控制重启时机。
+
 ---
 
 ## React Hooks
@@ -323,6 +521,7 @@ function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordi
 | `clientConfig` | `Partial<IviFrontendClientConfig>` | — | `IviClient` 配置；`transport` 为空时不创建 runtime |
 | `autoStart` | `boolean` | `true` | 是否自动启动 runtime |
 | `runtimeConfig` | `IviRuntimeCoordinatorConfig` | — | 透传给 `IviRuntimeCoordinator` |
+| `clientConfig.telemetry` / `runtimeConfig.telemetry` | `IviFrontendTelemetryOptions` | — | OpenTelemetry 透传；两处使用同一个配置即可串联 |
 | `onRuntimeInitError` | `(error) => void` | — | 初始化或启动失败回调 |
 | `onLog` | `(entry) => void` | — | 统一日志回调，覆盖 `[IVI-SEND]`、`[IVI-TRANSPORT]`、`[IVI-RECONNECT]`、`[IVI-EVT]`、`[IVI-STATE]`、`[IVI-TRTC]`、`[IVI-LIVEKIT]` |
 
@@ -339,6 +538,43 @@ interface IviManagedRuntimeLogEntry {
 }
 ```
 
+### `useIviSessionRuntime`
+
+```ts
+function useIviSessionRuntime(config: UseIviSessionRuntimeConfig): UseIviSessionRuntimeResult;
+```
+
+负责把 `createIVISession`、WebSocket transport 和 `IviRuntimeCoordinator` 组合起来。适合希望通过 API 网关创建会话，并在 prebuild 成功时自动快速开播的 React 接入。
+
+`UseIviSessionRuntimeConfig` 关键字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `request` | `IviCreateIVISessionRequest \| null \| undefined` | — | 创建会话请求；为空时不创建 runtime |
+| `http` | `IviCreateIVISessionHttpOptions` | — | HTTP 网关配置，包含 `baseUrl` / `url` / `headers` / `fetch` |
+| `fastStart` | `boolean` | `true` | 是否启用 prebuild bootstrap source |
+| `bootstrapSlot` | `string` | `"main"` | 快速开播临时绑定的 slot |
+| `bootstrapTrackId` | `string` | `"__ivi_bootstrap_track"` | 快速开播临时 track id |
+| `websocket` | `IviRuntimeWebSocketOptions` | — | websocket 地址、query、protocols、socketFactory |
+| `runtimeConfig` | `IviRuntimeCoordinatorConfig` | — | 透传给 runtime |
+| `clientConfig` | `Omit<IviClientConfig, "transport">` | — | 透传给 `IviClient` 的非 transport 配置 |
+| `telemetry` | `IviFrontendTelemetryOptions` | — | 同时串联创建 session、runtime 和底层 WebSocket spans |
+| `enabled` | `boolean` | `true` | 是否启用 hook |
+| `autoStart` | `boolean` | `true` | 是否创建后自动调用 `runtime.start()` |
+| `onCreated` | `(session) => void` | — | HTTP 创建会话成功回调 |
+| `onRuntimeReady` | `(runtime, client) => void` | — | runtime 构造完成回调 |
+| `onError` | `(error) => void` | — | 创建或启动失败回调 |
+
+返回值：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | `"idle" \| "creating" \| "connecting" \| "running" \| "error" \| "stopped"` | hook 生命周期状态 |
+| `session` | `IviCreateIVISessionResult \| null` | 创建会话结果 |
+| `runtime` | `IviRuntimeCoordinator \| null` | runtime 实例 |
+| `client` | `IviClient \| null` | 底层 realtime client |
+| `error` | `Error \| null` | 最近一次错误 |
+
 ### `useIviStageView`
 
 ```ts
@@ -440,7 +676,7 @@ function useApplyVolumeToSlot(
 
 ## React 组件
 
-当前公开导出的 React 组件包括 `IVIStageView`、`IVITrackSlot`、`IVITrtcPlayer`、`IVILivekitPlayer` 与 `IVISubtitleOverlay`；当前公开导出的 React hooks 包括 `useManagedIviRuntime`、`useRuntimeState`、`useIviStageView` 与 `useIviSubtitles`。
+当前公开导出的 React 组件包括 `IVIStageView`、`IVITrackSlot`、`IVITrtcPlayer`、`IVILivekitPlayer` 与 `IVISubtitleOverlay`；当前公开导出的 React hooks 包括 `useManagedIviRuntime`、`useIviSessionRuntime`、`useRuntimeState`、`useIviStageView` 与 `useIviSubtitles`。
 
 ### `IVIStageView`