@vivix-ai/ivi-frontend-sdk 0.3.7 → 0.3.9

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { ReceiveSessionSourceReadyPayload, IviStream, IviConversationItem, IviRealtimeSessionConfig, IviStageComposition, IviTrack, IviSourceAsset, ReceiveSessionSourceFailedPayload, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, IviClientConfig } from '@vivix-ai/ivi-sdk-ts';
 import { LiveKitBrowserTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/livekit-browser';
+import { WebSocketTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/websocket';
 import { ReactNode, CSSProperties, ReactElement, VideoHTMLAttributes, ImgHTMLAttributes } from 'react';
 import { IviClientLogEntry } from '@vivix-ai/ivi-sdk-ts/client';
 
@@ -18,6 +19,7 @@ interface IviRuntimeState {
     streams: Map<string, IviRuntimeStream>;
     conversationItems: Map<string, IviRuntimeConversationItem>;
     conversations: IviRuntimeConversationItem[];
+    bootstrap?: IviRuntimeBootstrapViewState | null;
 }
 /**
  * Runtime 层归一化后的 stream 视图。
@@ -37,6 +39,7 @@ interface IviRuntimeSourcePreloadState {
      */
     autoclearAfterPlay: boolean;
 }
+type IviRuntimeSourceOrigin = "prebuilt-session-response";
 interface IviRuntimeSource {
     source: IviSourceAsset;
     status: "created" | "ready" | "failed";
@@ -52,6 +55,27 @@ interface IviRuntimeSource {
      * - 不存在：不进行预加载（active source 由上层独立决定是否渲染）。
      */
     preload?: IviRuntimeSourcePreloadState;
+    origin?: IviRuntimeSourceOrigin;
+    provisional?: boolean;
+}
+interface IviRuntimeBootstrapSource {
+    sourceId: string;
+    streamId?: string;
+    slot: string;
+    trackId: string;
+    playback: IviSourcePlayback;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    hasAudio?: boolean;
+    source?: Partial<IviSourceAsset>;
+}
+interface IviRuntimeBootstrapViewState {
+    active: boolean;
+    slot: string;
+    trackId: string;
+    sourceId: string;
+    streamId?: string;
 }
 type IviRuntimeLogLevel = "info" | "warn" | "error";
 interface IviRuntimeLogEntry {
@@ -239,6 +263,7 @@ declare class TrtcSourceManager {
     attachView(sourceId: string, viewId: string, container: HTMLElement, muted: boolean): Promise<void>;
     detachView(sourceId: string, viewId: string): void;
     updateViewMuted(sourceId: string, viewId: string, muted: boolean): void;
+    reassignView(fromSourceId: string, toSourceId: string, viewId: string): boolean;
     private unlinkSourceFromSession;
     private getSession;
     private snapshotFromSession;
@@ -315,9 +340,10 @@ type LivekitSourceListener = (snapshot: LivekitSourceSnapshot) => void;
  */
 declare class LivekitSourceManager {
     private readonly onLog?;
+    private readonly onRemoteVideoAvailable?;
     private readonly sessions;
     private readonly listeners;
-    constructor(onLog?: IviRuntimeLogCallback | undefined);
+    constructor(onLog?: IviRuntimeLogCallback | undefined, onRemoteVideoAvailable?: ((sourceId: string) => void) | undefined);
     /**
      * 与 runtime 当前 sources 对齐：
      * - 对 ready + livekit 的 source 进行 upsert（必要时建立连接）；
@@ -428,6 +454,7 @@ declare class IviRuntimeCoordinator {
     private userTextFlowCounter;
     private waitingTracksListValidation;
     private waitingSourcesListValidation;
+    private bootstrapSource;
     private state;
     /**
      * @param client 底层实时客户端，负责实际事件收发。
@@ -448,6 +475,7 @@ declare class IviRuntimeCoordinator {
     onEvent(listener: IviRuntimeEventListener): () => void;
     onTrtcEvent(listener: IviRuntimeTrtcEventListener): () => void;
     emitLog(entry: IviRuntimeLogEntry): void;
+    setBootstrapSource(source: IviRuntimeBootstrapSource | null): void;
     /**
      * 编排一次"用户文本输入 -> 触发模型回复"链路。
      *
@@ -484,8 +512,15 @@ declare class IviRuntimeCoordinator {
     private onStreamsChanged;
     private onConversationsChanged;
     private setState;
+    private composeBootstrapState;
+    private shouldExposeBootstrap;
+    private isReadyForBootstrapHandoff;
+    private recomposeBootstrapState;
+    private ensureBootstrapSourceRegistered;
+    private syncPlaybackManagers;
     private emitEvent;
     private emitTrtcEvent;
+    private onTrtcManagerEvent;
     private resetStoppedState;
     private ensureSourcesSyncedForTracks;
     private validateSourcesListRefreshed;
@@ -523,10 +558,107 @@ declare class IviRuntimeDispatcher {
     private dispatchEvent;
 }
 
+type IviCreateSessionStreamType = "TRTC" | "LIVEKIT" | string;
+interface IviCreateIVISessionPrebuiltCharacter {
+    characterId: string;
+    characterPayload: unknown;
+}
+interface IviCreateIVISessionPrebuiltStream {
+    streamId?: string;
+    sourceId?: string;
+    mode: "character" | string;
+    streamConfig: unknown;
+}
+interface IviCreateIVISessionRequest {
+    idempotencyKey?: string;
+    streamType?: IviCreateSessionStreamType;
+    iviVersion?: string;
+    sessionParameters?: Record<string, string>;
+    enableDecoderPublish?: boolean;
+    sessionRecording?: {
+        enabled: boolean;
+        aspectRatio?: string;
+    };
+    prebuiltCharacters?: IviCreateIVISessionPrebuiltCharacter[];
+    prebuiltStream?: IviCreateIVISessionPrebuiltStream;
+    [key: string]: unknown;
+}
+interface IviCreateIVISessionHttpOptions {
+    baseUrl?: string;
+    path?: string;
+    url?: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+}
+interface IviPrebuiltPlayback {
+    sourceId: string;
+    streamId?: string;
+    kind: "trtc" | "livekit";
+    playback: IviSourcePlayback;
+    provisional: true;
+}
+interface IviCreateIVISessionResult {
+    iviSessionId: string;
+    endpoint: string;
+    tokenInfo?: unknown;
+    trtcInfo?: IviSourcePlaybackTrtc;
+    livekitInfo?: IviSourcePlaybackLivekit;
+    prebuildTrtcInfo?: {
+        trtcInfo?: IviSourcePlaybackTrtc;
+        livekitInfo?: IviSourcePlaybackLivekit;
+    };
+    prebuiltPlayback?: IviPrebuiltPlayback;
+    raw: unknown;
+    requestBody: Record<string, unknown>;
+}
+interface IviRuntimeWebSocketOptions {
+    url?: string;
+    protocols?: WebSocketTransportConfig["protocols"];
+    query?: Record<string, string | undefined | null>;
+    socketFactory?: WebSocketTransportConfig["socketFactory"];
+}
+interface IviRuntimeFromSessionOptions {
+    fastStart?: boolean;
+    bootstrapSlot?: string;
+    bootstrapTrackId?: string;
+    clientConfig?: Omit<IviClientConfig, "transport">;
+    runtimeConfig?: IviRuntimeCoordinatorConfig;
+    websocket?: IviRuntimeWebSocketOptions;
+}
+interface IviSessionRuntime {
+    session: IviCreateIVISessionResult;
+    client: IviClient;
+    runtime: IviRuntimeCoordinator;
+}
+interface IviCreateIVISessionRuntimeOptions extends IviRuntimeFromSessionOptions {
+    http: IviCreateIVISessionHttpOptions;
+}
+declare class IviCreateIVISessionError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+declare function createIVISession(request: IviCreateIVISessionRequest, options: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+declare function createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+declare function createIVISessionRuntime(request: IviCreateIVISessionRequest, options: IviCreateIVISessionRuntimeOptions): Promise<IviSessionRuntime>;
+declare function toCpCreateIVISessionRequestBody(request: IviCreateIVISessionRequest): Record<string, unknown>;
+declare function normalizeCreateIVISessionResponse(responseBody: unknown, request?: IviCreateIVISessionRequest, requestBody?: Record<string, unknown>): IviCreateIVISessionResult;
+
 type IviFrontendClientConfig = IviClientConfig;
+interface IviFrontendSdkConfig {
+    http?: IviCreateIVISessionHttpOptions;
+}
 declare class IviFrontendSdk {
+    private readonly config;
+    constructor(config?: IviFrontendSdkConfig);
     createClient(config: IviFrontendClientConfig): IviClient;
     createRuntimeCoordinator(clientConfig: IviFrontendClientConfig, runtimeConfig?: IviRuntimeCoordinatorConfig): IviRuntimeCoordinator;
+    createIVISession(request: IviCreateIVISessionRequest, options?: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+    createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+    createIVISessionRuntime(request: IviCreateIVISessionRequest, options?: Partial<IviCreateIVISessionRuntimeOptions>): Promise<IviSessionRuntime>;
 }
 
 interface IviStageSlotBinding {
@@ -800,6 +932,24 @@ interface IviManagedRuntimeConfig {
 }
 declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordinator | null;
 
+type IviSessionRuntimeHookStatus = "idle" | "creating" | "connecting" | "running" | "error" | "stopped";
+interface UseIviSessionRuntimeConfig extends IviCreateIVISessionRuntimeOptions {
+    request: IviCreateIVISessionRequest | null | undefined;
+    enabled?: boolean;
+    autoStart?: boolean;
+    onCreated?: (session: IviCreateIVISessionResult) => void;
+    onRuntimeReady?: (runtime: IviRuntimeCoordinator, client: IviClient) => void;
+    onError?: (error: unknown) => void;
+}
+interface UseIviSessionRuntimeResult {
+    status: IviSessionRuntimeHookStatus;
+    session: IviCreateIVISessionResult | null;
+    runtime: IviRuntimeCoordinator | null;
+    client: IviClient | null;
+    error: Error | null;
+}
+declare function useIviSessionRuntime(config: UseIviSessionRuntimeConfig): UseIviSessionRuntimeResult;
+
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, IviCreateIVISessionError, type IviCreateIVISessionHttpOptions, type IviCreateIVISessionPrebuiltCharacter, type IviCreateIVISessionPrebuiltStream, type IviCreateIVISessionRequest, type IviCreateIVISessionResult, type IviCreateIVISessionRuntimeOptions, type IviCreateSessionStreamType, type IviFrontendClientConfig, IviFrontendSdk, type IviFrontendSdkConfig, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviPrebuiltPlayback, type IviRuntimeBootstrapSource, type IviRuntimeBootstrapViewState, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeFromSessionOptions, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourceOrigin, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviRuntimeWebSocketOptions, type IviSessionRuntime, type IviSessionRuntimeHookStatus, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, type UseIviSessionRuntimeConfig, type UseIviSessionRuntimeResult, createIVISession, createIVISessionRuntime, createRuntimeFromSession, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, normalizeCreateIVISessionResponse, toCpCreateIVISessionRequestBody, useIviSessionRuntime, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ReceiveSessionSourceReadyPayload, IviStream, IviConversationItem, IviRealtimeSessionConfig, IviStageComposition, IviTrack, IviSourceAsset, ReceiveSessionSourceFailedPayload, IviConversationItemContent, ReceiveSessionEndedEvent, ParsedIviEvent, IviRealtimeResponseCreateParams, ReceiveConversationItemAddedEvent, ReceiveConversationItemDoneEvent, ReceiveResponseCreatedEvent, IviClient, IviClientConfig } from '@vivix-ai/ivi-sdk-ts';
 import { LiveKitBrowserTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/livekit-browser';
+import { WebSocketTransportConfig } from '@vivix-ai/ivi-sdk-ts/transports/websocket';
 import { ReactNode, CSSProperties, ReactElement, VideoHTMLAttributes, ImgHTMLAttributes } from 'react';
 import { IviClientLogEntry } from '@vivix-ai/ivi-sdk-ts/client';
 
@@ -18,6 +19,7 @@ interface IviRuntimeState {
     streams: Map<string, IviRuntimeStream>;
     conversationItems: Map<string, IviRuntimeConversationItem>;
     conversations: IviRuntimeConversationItem[];
+    bootstrap?: IviRuntimeBootstrapViewState | null;
 }
 /**
  * Runtime 层归一化后的 stream 视图。
@@ -37,6 +39,7 @@ interface IviRuntimeSourcePreloadState {
      */
     autoclearAfterPlay: boolean;
 }
+type IviRuntimeSourceOrigin = "prebuilt-session-response";
 interface IviRuntimeSource {
     source: IviSourceAsset;
     status: "created" | "ready" | "failed";
@@ -52,6 +55,27 @@ interface IviRuntimeSource {
      * - 不存在：不进行预加载（active source 由上层独立决定是否渲染）。
      */
     preload?: IviRuntimeSourcePreloadState;
+    origin?: IviRuntimeSourceOrigin;
+    provisional?: boolean;
+}
+interface IviRuntimeBootstrapSource {
+    sourceId: string;
+    streamId?: string;
+    slot: string;
+    trackId: string;
+    playback: IviSourcePlayback;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    hasAudio?: boolean;
+    source?: Partial<IviSourceAsset>;
+}
+interface IviRuntimeBootstrapViewState {
+    active: boolean;
+    slot: string;
+    trackId: string;
+    sourceId: string;
+    streamId?: string;
 }
 type IviRuntimeLogLevel = "info" | "warn" | "error";
 interface IviRuntimeLogEntry {
@@ -239,6 +263,7 @@ declare class TrtcSourceManager {
     attachView(sourceId: string, viewId: string, container: HTMLElement, muted: boolean): Promise<void>;
     detachView(sourceId: string, viewId: string): void;
     updateViewMuted(sourceId: string, viewId: string, muted: boolean): void;
+    reassignView(fromSourceId: string, toSourceId: string, viewId: string): boolean;
     private unlinkSourceFromSession;
     private getSession;
     private snapshotFromSession;
@@ -315,9 +340,10 @@ type LivekitSourceListener = (snapshot: LivekitSourceSnapshot) => void;
  */
 declare class LivekitSourceManager {
     private readonly onLog?;
+    private readonly onRemoteVideoAvailable?;
     private readonly sessions;
     private readonly listeners;
-    constructor(onLog?: IviRuntimeLogCallback | undefined);
+    constructor(onLog?: IviRuntimeLogCallback | undefined, onRemoteVideoAvailable?: ((sourceId: string) => void) | undefined);
     /**
      * 与 runtime 当前 sources 对齐：
      * - 对 ready + livekit 的 source 进行 upsert（必要时建立连接）；
@@ -428,6 +454,7 @@ declare class IviRuntimeCoordinator {
     private userTextFlowCounter;
     private waitingTracksListValidation;
     private waitingSourcesListValidation;
+    private bootstrapSource;
     private state;
     /**
      * @param client 底层实时客户端，负责实际事件收发。
@@ -448,6 +475,7 @@ declare class IviRuntimeCoordinator {
     onEvent(listener: IviRuntimeEventListener): () => void;
     onTrtcEvent(listener: IviRuntimeTrtcEventListener): () => void;
     emitLog(entry: IviRuntimeLogEntry): void;
+    setBootstrapSource(source: IviRuntimeBootstrapSource | null): void;
     /**
      * 编排一次"用户文本输入 -> 触发模型回复"链路。
      *
@@ -484,8 +512,15 @@ declare class IviRuntimeCoordinator {
     private onStreamsChanged;
     private onConversationsChanged;
     private setState;
+    private composeBootstrapState;
+    private shouldExposeBootstrap;
+    private isReadyForBootstrapHandoff;
+    private recomposeBootstrapState;
+    private ensureBootstrapSourceRegistered;
+    private syncPlaybackManagers;
     private emitEvent;
     private emitTrtcEvent;
+    private onTrtcManagerEvent;
     private resetStoppedState;
     private ensureSourcesSyncedForTracks;
     private validateSourcesListRefreshed;
@@ -523,10 +558,107 @@ declare class IviRuntimeDispatcher {
     private dispatchEvent;
 }
 
+type IviCreateSessionStreamType = "TRTC" | "LIVEKIT" | string;
+interface IviCreateIVISessionPrebuiltCharacter {
+    characterId: string;
+    characterPayload: unknown;
+}
+interface IviCreateIVISessionPrebuiltStream {
+    streamId?: string;
+    sourceId?: string;
+    mode: "character" | string;
+    streamConfig: unknown;
+}
+interface IviCreateIVISessionRequest {
+    idempotencyKey?: string;
+    streamType?: IviCreateSessionStreamType;
+    iviVersion?: string;
+    sessionParameters?: Record<string, string>;
+    enableDecoderPublish?: boolean;
+    sessionRecording?: {
+        enabled: boolean;
+        aspectRatio?: string;
+    };
+    prebuiltCharacters?: IviCreateIVISessionPrebuiltCharacter[];
+    prebuiltStream?: IviCreateIVISessionPrebuiltStream;
+    [key: string]: unknown;
+}
+interface IviCreateIVISessionHttpOptions {
+    baseUrl?: string;
+    path?: string;
+    url?: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    fetch?: typeof fetch;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+}
+interface IviPrebuiltPlayback {
+    sourceId: string;
+    streamId?: string;
+    kind: "trtc" | "livekit";
+    playback: IviSourcePlayback;
+    provisional: true;
+}
+interface IviCreateIVISessionResult {
+    iviSessionId: string;
+    endpoint: string;
+    tokenInfo?: unknown;
+    trtcInfo?: IviSourcePlaybackTrtc;
+    livekitInfo?: IviSourcePlaybackLivekit;
+    prebuildTrtcInfo?: {
+        trtcInfo?: IviSourcePlaybackTrtc;
+        livekitInfo?: IviSourcePlaybackLivekit;
+    };
+    prebuiltPlayback?: IviPrebuiltPlayback;
+    raw: unknown;
+    requestBody: Record<string, unknown>;
+}
+interface IviRuntimeWebSocketOptions {
+    url?: string;
+    protocols?: WebSocketTransportConfig["protocols"];
+    query?: Record<string, string | undefined | null>;
+    socketFactory?: WebSocketTransportConfig["socketFactory"];
+}
+interface IviRuntimeFromSessionOptions {
+    fastStart?: boolean;
+    bootstrapSlot?: string;
+    bootstrapTrackId?: string;
+    clientConfig?: Omit<IviClientConfig, "transport">;
+    runtimeConfig?: IviRuntimeCoordinatorConfig;
+    websocket?: IviRuntimeWebSocketOptions;
+}
+interface IviSessionRuntime {
+    session: IviCreateIVISessionResult;
+    client: IviClient;
+    runtime: IviRuntimeCoordinator;
+}
+interface IviCreateIVISessionRuntimeOptions extends IviRuntimeFromSessionOptions {
+    http: IviCreateIVISessionHttpOptions;
+}
+declare class IviCreateIVISessionError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+declare function createIVISession(request: IviCreateIVISessionRequest, options: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+declare function createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+declare function createIVISessionRuntime(request: IviCreateIVISessionRequest, options: IviCreateIVISessionRuntimeOptions): Promise<IviSessionRuntime>;
+declare function toCpCreateIVISessionRequestBody(request: IviCreateIVISessionRequest): Record<string, unknown>;
+declare function normalizeCreateIVISessionResponse(responseBody: unknown, request?: IviCreateIVISessionRequest, requestBody?: Record<string, unknown>): IviCreateIVISessionResult;
+
 type IviFrontendClientConfig = IviClientConfig;
+interface IviFrontendSdkConfig {
+    http?: IviCreateIVISessionHttpOptions;
+}
 declare class IviFrontendSdk {
+    private readonly config;
+    constructor(config?: IviFrontendSdkConfig);
     createClient(config: IviFrontendClientConfig): IviClient;
     createRuntimeCoordinator(clientConfig: IviFrontendClientConfig, runtimeConfig?: IviRuntimeCoordinatorConfig): IviRuntimeCoordinator;
+    createIVISession(request: IviCreateIVISessionRequest, options?: IviCreateIVISessionHttpOptions): Promise<IviCreateIVISessionResult>;
+    createRuntimeFromSession(session: IviCreateIVISessionResult, options?: IviRuntimeFromSessionOptions): IviSessionRuntime;
+    createIVISessionRuntime(request: IviCreateIVISessionRequest, options?: Partial<IviCreateIVISessionRuntimeOptions>): Promise<IviSessionRuntime>;
 }
 
 interface IviStageSlotBinding {
@@ -800,6 +932,24 @@ interface IviManagedRuntimeConfig {
 }
 declare function useManagedIviRuntime(config: IviManagedRuntimeConfig): IviRuntimeCoordinator | null;
 
+type IviSessionRuntimeHookStatus = "idle" | "creating" | "connecting" | "running" | "error" | "stopped";
+interface UseIviSessionRuntimeConfig extends IviCreateIVISessionRuntimeOptions {
+    request: IviCreateIVISessionRequest | null | undefined;
+    enabled?: boolean;
+    autoStart?: boolean;
+    onCreated?: (session: IviCreateIVISessionResult) => void;
+    onRuntimeReady?: (runtime: IviRuntimeCoordinator, client: IviClient) => void;
+    onError?: (error: unknown) => void;
+}
+interface UseIviSessionRuntimeResult {
+    status: IviSessionRuntimeHookStatus;
+    session: IviCreateIVISessionResult | null;
+    runtime: IviRuntimeCoordinator | null;
+    client: IviClient | null;
+    error: Error | null;
+}
+declare function useIviSessionRuntime(config: UseIviSessionRuntimeConfig): UseIviSessionRuntimeResult;
+
 declare function useIviStageView(): IviStageViewContextValue;
 
-export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, type IviFrontendClientConfig, IviFrontendSdk, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };
+export { DEFAULT_HIDE_COMPLETED_SUBTITLE_AFTER_MS, EMPTY_RUNTIME_STATE, IVILivekitPlayer, type IVILivekitPlayerProps, IVIStageView, type IVIStageViewProps, IVISubtitleOverlay, type IVISubtitleOverlayProps, type IVISubtitleOverlayStyle, IVITrackSlot, type IVITrackSlotProps, IVITrtcPlayer, type IVITrtcPlayerProps, type IviCompletedSubtitleDecision, type IviCompletedSubtitleDecisionResult, IviCreateIVISessionError, type IviCreateIVISessionHttpOptions, type IviCreateIVISessionPrebuiltCharacter, type IviCreateIVISessionPrebuiltStream, type IviCreateIVISessionRequest, type IviCreateIVISessionResult, type IviCreateIVISessionRuntimeOptions, type IviCreateSessionStreamType, type IviFrontendClientConfig, IviFrontendSdk, type IviFrontendSdkConfig, type IviManagedRuntimeConfig, type IviManagedRuntimeLogCallback, type IviManagedRuntimeLogEntry, type IviManagedRuntimeLogLevel, type IviManagedRuntimeLogSource, type IviPrebuiltPlayback, type IviRuntimeBootstrapSource, type IviRuntimeBootstrapViewState, type IviRuntimeConversationItem, type IviRuntimeConversationLifecycle, type IviRuntimeConversationStatus, IviRuntimeCoordinator, type IviRuntimeCoordinatorConfig, IviRuntimeDispatcher, type IviRuntimeDispatcherConfig, type IviRuntimeEventListener, type IviRuntimeFromSessionOptions, type IviRuntimeLogCallback, type IviRuntimeLogEntry, type IviRuntimeLogLevel, type IviRuntimeSource, type IviRuntimeSourceOrigin, type IviRuntimeSourcePreloadState, type IviRuntimeState, type IviRuntimeStatus, type IviRuntimeStream, type IviRuntimeTrtcAIDenoiserMode, type IviRuntimeTrtcAIDenoiserOptions, type IviRuntimeTrtcEvent, type IviRuntimeTrtcEventListener, type IviRuntimeTrtcEventType, type IviRuntimeUserTextToResponseCallbacks, type IviRuntimeUserTextToResponseOptions, type IviRuntimeUserTextToResponseResult, type IviRuntimeWebSocketOptions, type IviSessionRuntime, type IviSessionRuntimeHookStatus, type IviSourcePlaybackLivekit, type IviSourcePlaybackLivekitDescriptor, type IviStageSlotBinding, type IviStageViewContextValue, type IviSubtitleCompletedContext, type IviSubtitleCompletedHandler, type IviSubtitleCompletedReason, type IviSubtitleItem, type IviSubtitleRole, type IviSubtitleSource, type IviUseSubtitlesOptions, LivekitSourceManager, TrtcSourceManager, type UseIviSessionRuntimeConfig, type UseIviSessionRuntimeResult, createIVISession, createIVISessionRuntime, createRuntimeFromSession, isLivekitSourcePlayback, isReadyLivekitRuntimeSource, isSameLivekitConfig, normalizeCreateIVISessionResponse, toCpCreateIVISessionRequestBody, useIviSessionRuntime, useIviStageView, useIviSubtitles, useManagedIviRuntime, useRuntimeState };