realtime-avatar 0.16.0 → 0.17.1

package/README.md

@@ -4,7 +4,7 @@ A live character your users can talk to — voice, or voice and video. She liste
 speaks, so you can interrupt her mid-sentence and she stops, the way a person stops.
 
 ```bash
-npm install --save-exact realtime-avatar@0.16.0
+npm install --save-exact realtime-avatar@0.17.0
 ```
 
 ```ts
@@ -57,6 +57,24 @@ default); each URL expires at `expiresAt` (up to one hour, capped by retention).
 access before replaying or seeking after expiry. An expired URL does not delete the file.
 Treat the URL as private: anyone who has it can play that file until it expires.
 
+## Optional connection history
+
+Set `connectionHistory: true` in the server's `startCall` policy when the caller needs a
+tenant-scoped LiveKit quality timeline. The SDK enables its collector only when RTA grants the
+single-session capability. It receives the bridge's existing LiveKit connection snapshots,
+deduplicates changes, batches at most 32 observations, and stops at 240; it does not poll WebRTC
+statistics or own reconnect logic. Upload failures are bounded and never interrupt a call.
+
+```ts
+const call = await rta.startCall({ avatarId, connectionHistory: true });
+// Relay call.raw unchanged. The browser SDK uploads capability-gated observations automatically.
+const history = await rta.getConnectionHistory(call.sessionId);
+```
+
+History is an observation of native connection state and publisher quality. It is not a recording,
+packet-loss report, or proof that a device rendered or played a track. The read requires
+`usage:read`; store the session ID and fetch history from your authorized backend.
+
 Transcript delivery remains the signed `transcript` webhook configured on `startCall`. Join the
 transcript and recordings by `sessionId`; keep your own script revision with that call. Transcript
 timestamps describe conversation turns and do not by themselves establish frame-accurate media
@@ -137,13 +155,14 @@ all), and the `video` policy types are deliberately not one-to-one with the wire
 
 ```ts
 // calls
-rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, recording?, transcript?, metadata? })
+rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, recording?, connectionHistory?, transcript?, metadata? })
 rta.endCall(sessionId, { reason? })     // free an abandoned call's slot; idempotent, never throws
 
 // optional recordings; server only, requires recordings:read
 rta.listRecordings({ sessionId, limit?, cursor? })
 rta.getRecording(recordingId)
 rta.getRecordingAccess(recordingId)
+rta.getConnectionHistory(sessionId)    // bounded LiveKit observations; requires usage:read
 
 // avatars
 rta.createAvatarFromImage({ displayName, imageUrl, motionPrompt?, voice? })  // the only lane

package/dist/{chunk-V26PE2M3.js → chunk-4OLLYAJT.js}

@@ -1,3 +1,4 @@
+import { connectionHistoryGrantSchema } from './chunk-MCIXU6XP.js';
 import { z } from 'zod';
 
 // ../http-client/src/errors.ts
@@ -432,7 +433,8 @@ z.object({
   render_backend: renderBackendSchema.optional(),
   support_edits: sessionSupportEditsSchema.optional(),
   transcript_webhook: transcriptWebhookSchema.optional(),
-  client_metadata: clientMetadataSchema.optional()
+  client_metadata: clientMetadataSchema.optional(),
+  connection_history: z.boolean().optional()
 }).strict().superRefine((value, ctx) => {
   if (value.support_edits && value.render_backend === "generative") {
     ctx.addIssue({
@@ -497,10 +499,12 @@ z.object({
   renderBackend: renderBackendSchema.optional(),
   supportEdits: sessionSupportEditsSchema.optional(),
   transcriptWebhook: transcriptWebhookSchema.optional(),
-  clientMetadata: clientMetadataSchema.optional()
+  clientMetadata: clientMetadataSchema.optional(),
+  connectionHistory: z.boolean().optional()
 }).strict();
 var liveKitSessionGrantSchema = z.object({
   recording: recordingArtifactSchema.optional(),
+  connection_history: connectionHistoryGrantSchema.optional(),
   status: z.literal("ready").default("ready"),
   session_id: z.string().min(1),
   room_name: z.string().min(1),
@@ -596,7 +600,7 @@ z.enum([
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.16.0";
+var SDK_VERSION = "0.17.1";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -642,6 +646,7 @@ var RealtimeAvatar = class {
     if (options.voice !== void 0) body.voice = options.voice;
     if (options.metadata !== void 0) body.client_metadata = options.metadata;
     if (options.recording !== void 0) body.recording = recordingModeSchema.parse(options.recording);
+    if (options.connectionHistory !== void 0) body.connection_history = options.connectionHistory;
     if (options.clientTools) body.capabilities = ["client_tools"];
     if (options.transcript !== void 0) {
       body.transcript_webhook = { url: options.transcript.url, secret: options.transcript.secret };
@@ -675,7 +680,8 @@ var RealtimeAvatar = class {
       idleTimeoutSeconds: grant.idle_timeout_seconds,
       reservationExpiresAt: grant.reservation_expires_at,
       // The parsed fields above are for YOUR logic. Relay `raw` to the client untouched:
-      // the browser SDK validates the grant strictly and rejects an added or renamed key.
+      // the browser SDK accepts provider-issued capability fields through its passthrough
+      // grant schema; forwarding verbatim preserves capabilities this wrapper does not model.
       raw
     };
   }
@@ -1014,6 +1020,12 @@ var RealtimeAvatar = class {
   async getRecordingAccess(recordingId) {
     return recordingAccessResponseSchema.parse(await this.#json(await this.#request("GET", `/recordings/${encodeURIComponent(recordingId)}/access`)));
   }
+  /** Read one session's bounded LiveKit connection history. Requires `usage:read`. */
+  async getConnectionHistory(sessionId) {
+    if (!sessionId) throw new RealtimeAvatarError("sessionId is required");
+    const { connectionHistoryResponseSchema } = await import('./connection-history-CXL5QE56.js');
+    return connectionHistoryResponseSchema.parse(await this.#json(await this.#request("GET", `/sessions/${encodeURIComponent(sessionId)}/connection-history`)));
+  }
   async creditBalance() {
     return await this.#json(await this.#request("GET", "/credits/balance"));
   }

package/dist/chunk-MCIXU6XP.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+// ../http-client/src/generated/connection-history.ts
+var ConnectionQuality = { Excellent: "excellent", Good: "good", Poor: "poor", Lost: "lost", Unknown: "unknown" };
+var ConnectionState = { Disconnected: "disconnected", Connecting: "connecting", Connected: "connected", Reconnecting: "reconnecting", SignalReconnecting: "signalReconnecting" };
+var MAX_CONNECTION_HISTORY_OBSERVATIONS = 240;
+var MAX_CONNECTION_HISTORY_BATCH = 32;
+var CONNECTION_HISTORY_RETENTION_MS = 30 * 24 * 60 * 60 * 1e3;
+var quality = z.enum(ConnectionQuality);
+var connectionHistoryObservationSchema = z.object({
+  sequence: z.number().int().min(1).max(MAX_CONNECTION_HISTORY_OBSERVATIONS),
+  elapsedMs: z.number().int().min(0).max(864e5),
+  clientObservedAt: z.string().datetime({ offset: true }).nullable(),
+  connectionState: z.enum(ConnectionState),
+  localQuality: quality,
+  audioQuality: quality.nullable(),
+  videoQuality: quality.nullable()
+}).strict();
+var connectionHistoryGrantSchema = z.object({
+  endpoint: z.string().url().startsWith("https://"),
+  token: z.string().min(32).max(4096),
+  expiresAt: z.string().datetime({ offset: true })
+}).strict();
+var connectionHistoryUploadSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  observations: z.array(connectionHistoryObservationSchema).min(1).max(MAX_CONNECTION_HISTORY_BATCH)
+}).strict();
+var connectionHistoryResponseSchema = z.object({
+  sessionId: z.string().min(1).max(200),
+  observations: z.array(connectionHistoryObservationSchema).max(MAX_CONNECTION_HISTORY_OBSERVATIONS)
+}).strict();
+
+export { CONNECTION_HISTORY_RETENTION_MS, MAX_CONNECTION_HISTORY_BATCH, MAX_CONNECTION_HISTORY_OBSERVATIONS, connectionHistoryGrantSchema, connectionHistoryObservationSchema, connectionHistoryResponseSchema, connectionHistoryUploadSchema };

package/dist/{chunk-2TNFET3Q.js → chunk-Q34WDWEA.js}

@@ -1,4 +1,4 @@
-import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-V26PE2M3.js';
+import { RealtimeAvatar, isQueued, RealtimeAvatarHttpError } from './chunk-4OLLYAJT.js';
 
 // ../proxy/src/config.ts
 var json = (body, status = 200) => new Response(JSON.stringify(body), {

package/dist/connection-history-CXL5QE56.js

@@ -0,0 +1 @@
+export { CONNECTION_HISTORY_RETENTION_MS, MAX_CONNECTION_HISTORY_BATCH, MAX_CONNECTION_HISTORY_OBSERVATIONS, connectionHistoryGrantSchema, connectionHistoryObservationSchema, connectionHistoryResponseSchema, connectionHistoryUploadSchema } from './chunk-MCIXU6XP.js';

package/dist/connection-history.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+
+declare const MAX_CONNECTION_HISTORY_OBSERVATIONS = 240;
+declare const MAX_CONNECTION_HISTORY_BATCH = 32;
+declare const CONNECTION_HISTORY_RETENTION_MS: number;
+declare const connectionHistoryObservationSchema: z.ZodObject<{
+    sequence: z.ZodNumber;
+    elapsedMs: z.ZodNumber;
+    clientObservedAt: z.ZodNullable<z.ZodString>;
+    connectionState: z.ZodEnum<{
+        readonly Disconnected: "disconnected";
+        readonly Connecting: "connecting";
+        readonly Connected: "connected";
+        readonly Reconnecting: "reconnecting";
+        readonly SignalReconnecting: "signalReconnecting";
+    }>;
+    localQuality: z.ZodEnum<{
+        readonly Excellent: "excellent";
+        readonly Good: "good";
+        readonly Poor: "poor";
+        readonly Lost: "lost";
+        readonly Unknown: "unknown";
+    }>;
+    audioQuality: z.ZodNullable<z.ZodEnum<{
+        readonly Excellent: "excellent";
+        readonly Good: "good";
+        readonly Poor: "poor";
+        readonly Lost: "lost";
+        readonly Unknown: "unknown";
+    }>>;
+    videoQuality: z.ZodNullable<z.ZodEnum<{
+        readonly Excellent: "excellent";
+        readonly Good: "good";
+        readonly Poor: "poor";
+        readonly Lost: "lost";
+        readonly Unknown: "unknown";
+    }>>;
+}, z.core.$strict>;
+declare const connectionHistoryGrantSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+}, z.core.$strict>;
+declare const connectionHistoryUploadSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    observations: z.ZodArray<z.ZodObject<{
+        sequence: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+        clientObservedAt: z.ZodNullable<z.ZodString>;
+        connectionState: z.ZodEnum<{
+            readonly Disconnected: "disconnected";
+            readonly Connecting: "connecting";
+            readonly Connected: "connected";
+            readonly Reconnecting: "reconnecting";
+            readonly SignalReconnecting: "signalReconnecting";
+        }>;
+        localQuality: z.ZodEnum<{
+            readonly Excellent: "excellent";
+            readonly Good: "good";
+            readonly Poor: "poor";
+            readonly Lost: "lost";
+            readonly Unknown: "unknown";
+        }>;
+        audioQuality: z.ZodNullable<z.ZodEnum<{
+            readonly Excellent: "excellent";
+            readonly Good: "good";
+            readonly Poor: "poor";
+            readonly Lost: "lost";
+            readonly Unknown: "unknown";
+        }>>;
+        videoQuality: z.ZodNullable<z.ZodEnum<{
+            readonly Excellent: "excellent";
+            readonly Good: "good";
+            readonly Poor: "poor";
+            readonly Lost: "lost";
+            readonly Unknown: "unknown";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+declare const connectionHistoryResponseSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    observations: z.ZodArray<z.ZodObject<{
+        sequence: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+        clientObservedAt: z.ZodNullable<z.ZodString>;
+        connectionState: z.ZodEnum<{
+            readonly Disconnected: "disconnected";
+            readonly Connecting: "connecting";
+            readonly Connected: "connected";
+            readonly Reconnecting: "reconnecting";
+            readonly SignalReconnecting: "signalReconnecting";
+        }>;
+        localQuality: z.ZodEnum<{
+            readonly Excellent: "excellent";
+            readonly Good: "good";
+            readonly Poor: "poor";
+            readonly Lost: "lost";
+            readonly Unknown: "unknown";
+        }>;
+        audioQuality: z.ZodNullable<z.ZodEnum<{
+            readonly Excellent: "excellent";
+            readonly Good: "good";
+            readonly Poor: "poor";
+            readonly Lost: "lost";
+            readonly Unknown: "unknown";
+        }>>;
+        videoQuality: z.ZodNullable<z.ZodEnum<{
+            readonly Excellent: "excellent";
+            readonly Good: "good";
+            readonly Poor: "poor";
+            readonly Lost: "lost";
+            readonly Unknown: "unknown";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type ConnectionHistoryObservation = z.infer<typeof connectionHistoryObservationSchema>;
+type ConnectionHistoryGrant = z.infer<typeof connectionHistoryGrantSchema>;
+type ConnectionHistoryUpload = z.infer<typeof connectionHistoryUploadSchema>;
+type ConnectionHistoryResponse = z.infer<typeof connectionHistoryResponseSchema>;
+
+export { CONNECTION_HISTORY_RETENTION_MS, type ConnectionHistoryGrant, type ConnectionHistoryObservation, type ConnectionHistoryResponse, type ConnectionHistoryUpload, MAX_CONNECTION_HISTORY_BATCH, MAX_CONNECTION_HISTORY_OBSERVATIONS, connectionHistoryGrantSchema, connectionHistoryObservationSchema, connectionHistoryResponseSchema, connectionHistoryUploadSchema };

package/dist/connection-history.js

@@ -0,0 +1 @@
+export { CONNECTION_HISTORY_RETENTION_MS, MAX_CONNECTION_HISTORY_BATCH, MAX_CONNECTION_HISTORY_OBSERVATIONS, connectionHistoryGrantSchema, connectionHistoryObservationSchema, connectionHistoryResponseSchema, connectionHistoryUploadSchema } from './chunk-MCIXU6XP.js';

package/dist/express.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-Bphj69NC.js';
-import './types-VOv0vsFs.js';
+import { P as ProxyConfig } from './types-CFkiNV3f.js';
+import './types-BnlnrYgN.js';
 import 'zod';
 
 type Expressish = {

package/dist/express.js

@@ -1,5 +1,6 @@
-import { createProxyHandler } from './chunk-2TNFET3Q.js';
-import './chunk-V26PE2M3.js';
+import { createProxyHandler } from './chunk-Q34WDWEA.js';
+import './chunk-4OLLYAJT.js';
+import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/express.ts
 function realtimeAvatarExpress(config) {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-Bphj69NC.js';
-import './types-VOv0vsFs.js';
+import { P as ProxyConfig } from './types-CFkiNV3f.js';
+import './types-BnlnrYgN.js';
 import 'zod';
 
 /**

package/dist/hono.js

@@ -1,5 +1,6 @@
-import { createProxyHandler } from './chunk-2TNFET3Q.js';
-import './chunk-V26PE2M3.js';
+import { createProxyHandler } from './chunk-Q34WDWEA.js';
+import './chunk-4OLLYAJT.js';
+import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/hono.ts
 function realtimeAvatarHono(config) {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as ListRecordingsQuery, l as ListRecordingsResponse, R as RecordingArtifact, m as RecordingAccessResponse, n as CreditBalance, T as TranscriptPayload } from './types-VOv0vsFs.js';
-export { o as AvatarClip, p as CallConnection, q as CallQueued, r as ClipDeclaration, s as ClipLibraryPlan, t as ClipSource, u as ContextMessage, v as EndCallReason, w as RecordingArtifactStatus, x as RecordingMode, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-VOv0vsFs.js';
+import { a as CallPolicy, C as CallMode, S as StartCallResult, E as EndCallOptions, A as Avatar, b as AvatarUpdate, c as AvatarSourceSwap, d as ClipLibraryDeclaration, e as ClipLibraryUpdate, L as LoopRedirect, f as ClipLibrary, g as AssetKind, h as Asset, i as ListSessionsOptions, U as UsageSessionPage, j as UsageSession, k as ListRecordingsQuery, l as ListRecordingsResponse, R as RecordingArtifact, m as RecordingAccessResponse, n as CreditBalance, T as TranscriptPayload } from './types-BnlnrYgN.js';
+export { o as AvatarClip, p as CallConnection, q as CallQueued, r as ClipDeclaration, s as ClipLibraryPlan, t as ClipSource, u as ContextMessage, v as EndCallReason, w as RecordingArtifactStatus, x as RecordingMode, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-BnlnrYgN.js';
+import { ConnectionHistoryResponse } from './connection-history.js';
 import { z } from 'zod';
 
 interface RealtimeAvatarOptions {
@@ -271,6 +272,8 @@ declare class RealtimeAvatar {
     getRecording(recordingId: string): Promise<RecordingArtifact>;
     /** Renewable playback access. Keep recordingId in storage; URLs expire at expiresAt. */
     getRecordingAccess(recordingId: string): Promise<RecordingAccessResponse>;
+    /** Read one session's bounded LiveKit connection history. Requires `usage:read`. */
+    getConnectionHistory(sessionId: string): Promise<ConnectionHistoryResponse>;
     creditBalance(): Promise<CreditBalance>;
 }
 

package/dist/index.js

@@ -1 +1,2 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-V26PE2M3.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-4OLLYAJT.js';
+import './chunk-MCIXU6XP.js';

package/dist/nextjs.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-Bphj69NC.js';
-import './types-VOv0vsFs.js';
+import { P as ProxyConfig } from './types-CFkiNV3f.js';
+import './types-BnlnrYgN.js';
 import 'zod';
 
 /**

package/dist/nextjs.js

@@ -1,5 +1,6 @@
-import { createProxyHandler } from './chunk-2TNFET3Q.js';
-import './chunk-V26PE2M3.js';
+import { createProxyHandler } from './chunk-Q34WDWEA.js';
+import './chunk-4OLLYAJT.js';
+import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/nextjs.ts
 function createRealtimeAvatarRoute(config) {

package/dist/{proxy-client-Bu-5QFhA.d.ts → proxy-client-DmJVj18Z.d.ts}

@@ -220,6 +220,7 @@ declare const liveKitSessionRequestSchema: z.ZodObject<{
         secret: z.ZodString;
     }, z.core.$strict>>;
     clientMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    connectionHistory: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 declare const liveKitSessionGrantSchema: z.ZodObject<{
     recording: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -271,6 +272,11 @@ declare const liveKitSessionGrantSchema: z.ZodObject<{
             recording_unavailable: "recording_unavailable";
         }>;
     }, z.core.$strict>], "status">>;
+    connection_history: z.ZodOptional<z.ZodObject<{
+        endpoint: z.ZodString;
+        token: z.ZodString;
+        expiresAt: z.ZodString;
+    }, z.core.$strict>>;
     status: z.ZodDefault<z.ZodLiteral<"ready">>;
     session_id: z.ZodString;
     room_name: z.ZodString;
@@ -291,9 +297,9 @@ declare const liveKitSessionGrantSchema: z.ZodObject<{
 declare const sessionEndReasonSchema: z.ZodEnum<{
     idle: "idle";
     failed: "failed";
+    disconnected: "disconnected";
     user_ended: "user_ended";
     session_cap: "session_cap";
-    disconnected: "disconnected";
     out_of_credits: "out_of_credits";
     agent_ended: "agent_ended";
 }>;

package/dist/react-native.d.ts

@@ -1,8 +1,8 @@
 import { LiveKitRoomProps } from '@livekit/react-native';
 export { AudioSession, VideoTrack, VideoTrackProps, registerGlobals } from '@livekit/react-native';
 import { ReactNode, ReactElement } from 'react';
-import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-Bu-5QFhA.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, h as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ah as SessionLifecycleRoomBridgeProps, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, au as isNativeLiveTrackSubscribed, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aG as useLiveTrackProducing, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-Bu-5QFhA.js';
+import { L as LiveKitSessionGrant, A as AvatarVideoFit } from './proxy-client-DmJVj18Z.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, h as AvatarSessionClient, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ah as SessionLifecycleRoomBridgeProps, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, au as isNativeLiveTrackSubscribed, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aG as useLiveTrackProducing, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-DmJVj18Z.js';
 import { StyleProp, ViewStyle } from 'react-native';
 export { useChat, useConnectionState, useLocalParticipant, useRoomContext, useTrackToggle, useTranscriptions, useVoiceAssistant } from '@livekit/components-react';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';

package/dist/react-native.js

@@ -1426,6 +1426,33 @@ z.object({
   url: z.string().url(),
   expiresAt: z.string().datetime({ offset: true })
 }).strict();
+var ConnectionQuality2 = { Excellent: "excellent", Good: "good", Poor: "poor", Lost: "lost", Unknown: "unknown" };
+var ConnectionState4 = { Disconnected: "disconnected", Connecting: "connecting", Connected: "connected", Reconnecting: "reconnecting", SignalReconnecting: "signalReconnecting" };
+var MAX_CONNECTION_HISTORY_OBSERVATIONS = 240;
+var MAX_CONNECTION_HISTORY_BATCH = 32;
+var quality = z.enum(ConnectionQuality2);
+var connectionHistoryObservationSchema = z.object({
+  sequence: z.number().int().min(1).max(MAX_CONNECTION_HISTORY_OBSERVATIONS),
+  elapsedMs: z.number().int().min(0).max(864e5),
+  clientObservedAt: z.string().datetime({ offset: true }).nullable(),
+  connectionState: z.enum(ConnectionState4),
+  localQuality: quality,
+  audioQuality: quality.nullable(),
+  videoQuality: quality.nullable()
+}).strict();
+var connectionHistoryGrantSchema = z.object({
+  endpoint: z.string().url().startsWith("https://"),
+  token: z.string().min(32).max(4096),
+  expiresAt: z.string().datetime({ offset: true })
+}).strict();
+z.object({
+  sessionId: z.string().min(1).max(200),
+  observations: z.array(connectionHistoryObservationSchema).min(1).max(MAX_CONNECTION_HISTORY_BATCH)
+}).strict();
+z.object({
+  sessionId: z.string().min(1).max(200),
+  observations: z.array(connectionHistoryObservationSchema).max(MAX_CONNECTION_HISTORY_OBSERVATIONS)
+}).strict();
 
 // ../client/src/wire.ts
 var DEFAULT_AVATAR_ID = "maria";
@@ -1589,7 +1616,8 @@ z.object({
   render_backend: renderBackendSchema.optional(),
   support_edits: sessionSupportEditsSchema.optional(),
   transcript_webhook: transcriptWebhookSchema.optional(),
-  client_metadata: clientMetadataSchema.optional()
+  client_metadata: clientMetadataSchema.optional(),
+  connection_history: z.boolean().optional()
 }).strict().superRefine((value, ctx) => {
   if (value.support_edits && value.render_backend === "generative") {
     ctx.addIssue({
@@ -1654,10 +1682,12 @@ z.object({
   renderBackend: renderBackendSchema.optional(),
   supportEdits: sessionSupportEditsSchema.optional(),
   transcriptWebhook: transcriptWebhookSchema.optional(),
-  clientMetadata: clientMetadataSchema.optional()
+  clientMetadata: clientMetadataSchema.optional(),
+  connectionHistory: z.boolean().optional()
 }).strict();
 z.object({
   recording: recordingArtifactSchema.optional(),
+  connection_history: connectionHistoryGrantSchema.optional(),
   status: z.literal("ready").default("ready"),
   session_id: z.string().min(1),
   room_name: z.string().min(1),
@@ -1770,6 +1800,95 @@ function nextBehaviorSnapshot(prev, frame) {
   return next;
 }
 
+// ../client/src/react/connection-history.ts
+function createConnectionHistoryCollector(input) {
+  const fetcher = input.fetch ?? ((request, init) => globalThis.fetch(request, init));
+  const wallMs = input.clock?.wallMs ?? Date.now;
+  const monotonicMs = input.clock?.monotonicMs ?? (() => globalThis.performance?.now() ?? Date.now());
+  const startedAt = monotonicMs();
+  const wallStartedAt = wallMs();
+  const queue2 = [];
+  let sequence = 0;
+  let scheduled = false;
+  let flushing = null;
+  let disposed = false;
+  let lastSnapshot = null;
+  function enqueue(details) {
+    if (disposed || details === null || sequence >= MAX_CONNECTION_HISTORY_OBSERVATIONS) return;
+    const elapsedMs = Math.max(0, Math.min(864e5, Math.round(monotonicMs() - startedAt)));
+    const nextSnapshot = {
+      connectionState: details.connectionState,
+      localQuality: details.localQuality,
+      audioQuality: details.audio?.publisherQuality ?? null,
+      videoQuality: details.video?.publisherQuality ?? null
+    };
+    const prior = lastSnapshot;
+    if (prior && prior.connectionState === nextSnapshot.connectionState && prior.localQuality === nextSnapshot.localQuality && prior.audioQuality === nextSnapshot.audioQuality && prior.videoQuality === nextSnapshot.videoQuality) return;
+    lastSnapshot = nextSnapshot;
+    const value = {
+      sequence: sequence + 1,
+      elapsedMs,
+      clientObservedAt: new Date(wallStartedAt + elapsedMs).toISOString(),
+      ...nextSnapshot
+    };
+    sequence = value.sequence;
+    queue2.push(value);
+    if (queue2.length >= MAX_CONNECTION_HISTORY_BATCH) void flush();
+    else scheduleFlush();
+  }
+  function scheduleFlush() {
+    if (scheduled || disposed) return;
+    scheduled = true;
+    queueMicrotask(() => {
+      scheduled = false;
+      void flush();
+    });
+  }
+  async function send(batch) {
+    if (Date.parse(input.grant.expiresAt) <= wallMs()) return;
+    const payload = { sessionId: input.sessionId, observations: batch };
+    const retries = Math.max(0, Math.min(2, input.maxRetries ?? 2));
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        if (Date.parse(input.grant.expiresAt) <= wallMs()) return;
+        const response = await fetcher(input.grant.endpoint, {
+          method: "POST",
+          headers: { authorization: `Bearer ${input.grant.token}`, "content-type": "application/json" },
+          body: JSON.stringify(payload),
+          signal: AbortSignal.timeout(5e3)
+        });
+        if (response.ok) return;
+        if (response.status < 500 && response.status !== 429) return;
+        await response.body?.cancel().catch(() => {
+        });
+      } catch {
+      }
+      if (attempt < retries) await new Promise((resolve) => setTimeout(resolve, 100 * 2 ** attempt));
+    }
+  }
+  async function flush() {
+    if (queue2.length === 0) return;
+    if (flushing) return flushing;
+    flushing = (async () => {
+      try {
+        while (queue2.length) {
+          const batch = queue2.splice(0, MAX_CONNECTION_HISTORY_BATCH);
+          await send(batch);
+        }
+      } finally {
+        flushing = null;
+      }
+    })();
+    return flushing;
+  }
+  async function dispose() {
+    disposed = true;
+    await flush();
+    queue2.length = 0;
+  }
+  return { enqueue, flush, dispose };
+}
+
 // ../client/src/react/session-lifecycle.ts
 function phaseForReason(reason) {
   switch (reason) {
@@ -2244,11 +2363,35 @@ function SessionLifecycleRoomBridge({
   const prevTranscriptionCountRef = useRef(0);
   const audio = assistant.audioTrack;
   const video = assistant.videoTrack;
-  const detailsEnabled = onConnectionDetailsChange !== void 0 && lifecycle.grant !== null;
+  const connectionHistoryGrant = lifecycle.grant?.connection_history;
+  const detailsEnabled = (onConnectionDetailsChange !== void 0 || connectionHistoryGrant !== void 0) && lifecycle.grant !== null;
   const detailsSessionId = lifecycle.grant?.session_id;
+  const connectionHistoryRef = useRef(null);
   const updateDetailsRef = useRef(null);
   useEffect(() => {
-    if (!detailsEnabled || !onConnectionDetailsChange) return;
+    const sessionId = detailsSessionId;
+    if (!sessionId || !connectionHistoryGrant) {
+      connectionHistoryRef.current = null;
+      return;
+    }
+    const collector = createConnectionHistoryCollector({ sessionId, grant: connectionHistoryGrant });
+    connectionHistoryRef.current = collector;
+    return () => {
+      if (connectionHistoryRef.current === collector) connectionHistoryRef.current = null;
+      void collector.dispose();
+    };
+  }, [connectionHistoryGrant, detailsSessionId]);
+  useEffect(() => {
+    const collector = connectionHistoryRef.current;
+    if (!collector || typeof window === "undefined" || typeof window.addEventListener !== "function" || typeof window.removeEventListener !== "function") return;
+    const flush = () => {
+      void collector.flush();
+    };
+    window.addEventListener("pagehide", flush, true);
+    return () => window.removeEventListener("pagehide", flush, true);
+  }, [connectionHistoryGrant, detailsSessionId]);
+  useEffect(() => {
+    if (!detailsEnabled || !onConnectionDetailsChange && !connectionHistoryGrant) return;
     let callback = onConnectionDetailsChange;
     let audioSource = audio;
     let videoSource = video;
@@ -2256,8 +2399,9 @@ function SessionLifecycleRoomBridge({
     let pending = false;
     let previous;
     const deliver = (details) => {
+      connectionHistoryRef.current?.enqueue(details);
       try {
-        void Promise.resolve(callback(details)).catch(() => {
+        if (onConnectionDetailsChange) void Promise.resolve(callback?.(details)).catch(() => {
         });
       } catch {
       }
@@ -2315,7 +2459,7 @@ function SessionLifecycleRoomBridge({
     };
   }, [room, detailsSessionId, detailsEnabled]);
   useEffect(() => {
-    if (onConnectionDetailsChange) updateDetailsRef.current?.(onConnectionDetailsChange, audio, video);
+    updateDetailsRef.current?.(onConnectionDetailsChange, audio, video);
   }, [
     onConnectionDetailsChange,
     detailsEnabled ? audio?.participant : void 0,

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import { RegisteredTool, ToolRegistration } from './tools.js';
 import { ReactNode } from 'react';
-import { ah as SessionLifecycleRoomBridgeProps, h as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-Bu-5QFhA.js';
-export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, aL as AvatarVideoSurface, aM as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, aN as LivePlaybackKeeper, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, aO as MIC_LEASE_ENDED_TIMEOUT_MS, aP as MicLease, aQ as NETWORK_QUALITY_POLICY, aR as NetworkQualityStatus, aS as PlayableVideoElement, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, aT as RealtimeAvatarCapacityError, aU as RealtimeAvatarLiveKitRoom, aV as RealtimeAvatarLiveKitRoomProps, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aW as shouldReplayPendingTurn, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-Bu-5QFhA.js';
+import { ah as SessionLifecycleRoomBridgeProps, h as AvatarSessionClient, A as AvatarVideoFit } from './proxy-client-DmJVj18Z.js';
+export { a as AdaptivePlayoutController, b as AdaptivePlayoutDecision, c as AdaptivePlayoutOptions, d as AdaptivePlayoutSample, e as ApproachingEndEvent, f as ApproachingEndReason, g as AvatarConnectionDetails, aL as AvatarVideoSurface, aM as AvatarVideoSurfaceProps, B as BehaviorSnapshot, C as CallTranscript, i as CallTranscriptSegment, j as CartesiaTtsModel, k as ClipResult, l as ClosingTurnResult, m as CreditsLowEvent, D as DEFAULT_APPROACHING_END_LEAD_SECONDS, n as DEFAULT_CREDITS_LOW_LEAD_SECONDS, o as DEFAULT_GOVERNOR_CONFIG, p as DEFAULT_GRACE_CEILING_SECONDS, q as DEFAULT_GRACE_WINDOW_LEAD_SECONDS, r as DEFAULT_IDLE_SECONDS, s as DEFAULT_IDLE_WARN_LEAD_SECONDS, t as DEFAULT_TURN_TIMEOUT_SECONDS, E as EndReason, u as EndedEvent, v as ExtendResult, F as FishTtsModel, w as FreezeReadingFn, G as Governor, x as GovernorAction, y as GovernorConfig, z as GovernorSignal, H as GovernorState, I as GraceWindowClosedEvent, J as GraceWindowOpenEvent, K as GraceWindowState, M as IdleWarningEvent, N as InboundRtpCursor, O as InboundRtpReading, P as KnownBehaviorState, Q as LLMProvider, R as LLMSelection, S as LiveKitAvatarGrantState, T as LiveKitAvatarGrantStatus, U as LiveKitCapacityState, V as LiveKitConnectionStatus, W as LiveKitSessionRequest, X as LiveKitSessionStartResult, aN as LivePlaybackKeeper, Y as MAX_RECONNECT_ATTEMPTS, Z as MAX_SESSION_INSTRUCTIONS_CHARS, aO as MIC_LEASE_ENDED_TIMEOUT_MS, aP as MicLease, aQ as NETWORK_QUALITY_POLICY, aR as NetworkQualityStatus, aS as PlayableVideoElement, _ as ProxyClientOptions, $ as QualityCap, a0 as RECONNECT_BACKOFF_MS, aT as RealtimeAvatarCapacityError, aU as RealtimeAvatarLiveKitRoom, aV as RealtimeAvatarLiveKitRoomProps, a1 as RealtimeAvatarRequestOptions, a2 as RealtimeSessionApi, a3 as RealtimeSessionMedia, a4 as RealtimeSessionRoomSinks, a5 as ReconnectPolicy, a6 as ReconnectingEvent, a7 as RecoveryState, a8 as RetryStep, a9 as SessionBehavior, aa as SessionClip, ab as SessionClocks, ac as SessionEndReason, ad as SessionLifecycleApi, ae as SessionLifecyclePhase, af as SessionLifecyclePhaseKind, ag as SessionLifecycleRoomBridge, ai as SurfaceLayers, aj as TurnState, ak as TurnTimeoutEvent, al as UseAvatarQualityGovernorInput, am as UseLiveKitAvatarGrantInput, an as UseRealtimeSessionInput, ao as UseSessionLifecycleInput, ap as VoiceSpec, aq as VoiceSpecInput, ar as capacityErrorFromBusy, as as capacityStateFromGrant, at as createProxyClient, av as knownBehaviorStates, aw as mapTurnState, ax as readInboundRtp, ay as sessionBehaviorSchema, az as sessionClipSchema, aW as shouldReplayPendingTurn, aA as splitCallTranscript, aB as useAvatarAdaptivePlayoutDelay, aC as useAvatarPlayoutDelay, aD as useAvatarQualityGovernor, aE as useCallTranscript, aF as useLiveKitAvatarGrant, aH as useMicLease, aI as useRealtimeSession, aJ as useReleaseMicLeaseOnTrackEnded, aK as useSessionLifecycle } from './proxy-client-DmJVj18Z.js';
 export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS } from './playout-delay-DWOc8iCl.js';
 import 'zod';
 import '@livekit/components-react';

package/dist/react.js

@@ -1960,6 +1960,33 @@ z.object({
   url: z.string().url(),
   expiresAt: z.string().datetime({ offset: true })
 }).strict();
+var ConnectionQuality2 = { Excellent: "excellent", Good: "good", Poor: "poor", Lost: "lost", Unknown: "unknown" };
+var ConnectionState4 = { Disconnected: "disconnected", Connecting: "connecting", Connected: "connected", Reconnecting: "reconnecting", SignalReconnecting: "signalReconnecting" };
+var MAX_CONNECTION_HISTORY_OBSERVATIONS = 240;
+var MAX_CONNECTION_HISTORY_BATCH = 32;
+var quality = z.enum(ConnectionQuality2);
+var connectionHistoryObservationSchema = z.object({
+  sequence: z.number().int().min(1).max(MAX_CONNECTION_HISTORY_OBSERVATIONS),
+  elapsedMs: z.number().int().min(0).max(864e5),
+  clientObservedAt: z.string().datetime({ offset: true }).nullable(),
+  connectionState: z.enum(ConnectionState4),
+  localQuality: quality,
+  audioQuality: quality.nullable(),
+  videoQuality: quality.nullable()
+}).strict();
+var connectionHistoryGrantSchema = z.object({
+  endpoint: z.string().url().startsWith("https://"),
+  token: z.string().min(32).max(4096),
+  expiresAt: z.string().datetime({ offset: true })
+}).strict();
+z.object({
+  sessionId: z.string().min(1).max(200),
+  observations: z.array(connectionHistoryObservationSchema).min(1).max(MAX_CONNECTION_HISTORY_BATCH)
+}).strict();
+z.object({
+  sessionId: z.string().min(1).max(200),
+  observations: z.array(connectionHistoryObservationSchema).max(MAX_CONNECTION_HISTORY_OBSERVATIONS)
+}).strict();
 
 // ../client/src/wire.ts
 var DEFAULT_AVATAR_ID = "maria";
@@ -2123,7 +2150,8 @@ z.object({
   render_backend: renderBackendSchema.optional(),
   support_edits: sessionSupportEditsSchema.optional(),
   transcript_webhook: transcriptWebhookSchema.optional(),
-  client_metadata: clientMetadataSchema.optional()
+  client_metadata: clientMetadataSchema.optional(),
+  connection_history: z.boolean().optional()
 }).strict().superRefine((value, ctx) => {
   if (value.support_edits && value.render_backend === "generative") {
     ctx.addIssue({
@@ -2188,10 +2216,12 @@ z.object({
   renderBackend: renderBackendSchema.optional(),
   supportEdits: sessionSupportEditsSchema.optional(),
   transcriptWebhook: transcriptWebhookSchema.optional(),
-  clientMetadata: clientMetadataSchema.optional()
+  clientMetadata: clientMetadataSchema.optional(),
+  connectionHistory: z.boolean().optional()
 }).strict();
 z.object({
   recording: recordingArtifactSchema.optional(),
+  connection_history: connectionHistoryGrantSchema.optional(),
   status: z.literal("ready").default("ready"),
   session_id: z.string().min(1),
   room_name: z.string().min(1),
@@ -2304,6 +2334,95 @@ function nextBehaviorSnapshot(prev, frame) {
   return next;
 }
 
+// ../client/src/react/connection-history.ts
+function createConnectionHistoryCollector(input) {
+  const fetcher = input.fetch ?? ((request, init) => globalThis.fetch(request, init));
+  const wallMs = input.clock?.wallMs ?? Date.now;
+  const monotonicMs = input.clock?.monotonicMs ?? (() => globalThis.performance?.now() ?? Date.now());
+  const startedAt = monotonicMs();
+  const wallStartedAt = wallMs();
+  const queue2 = [];
+  let sequence = 0;
+  let scheduled = false;
+  let flushing = null;
+  let disposed = false;
+  let lastSnapshot = null;
+  function enqueue(details) {
+    if (disposed || details === null || sequence >= MAX_CONNECTION_HISTORY_OBSERVATIONS) return;
+    const elapsedMs = Math.max(0, Math.min(864e5, Math.round(monotonicMs() - startedAt)));
+    const nextSnapshot = {
+      connectionState: details.connectionState,
+      localQuality: details.localQuality,
+      audioQuality: details.audio?.publisherQuality ?? null,
+      videoQuality: details.video?.publisherQuality ?? null
+    };
+    const prior = lastSnapshot;
+    if (prior && prior.connectionState === nextSnapshot.connectionState && prior.localQuality === nextSnapshot.localQuality && prior.audioQuality === nextSnapshot.audioQuality && prior.videoQuality === nextSnapshot.videoQuality) return;
+    lastSnapshot = nextSnapshot;
+    const value = {
+      sequence: sequence + 1,
+      elapsedMs,
+      clientObservedAt: new Date(wallStartedAt + elapsedMs).toISOString(),
+      ...nextSnapshot
+    };
+    sequence = value.sequence;
+    queue2.push(value);
+    if (queue2.length >= MAX_CONNECTION_HISTORY_BATCH) void flush();
+    else scheduleFlush();
+  }
+  function scheduleFlush() {
+    if (scheduled || disposed) return;
+    scheduled = true;
+    queueMicrotask(() => {
+      scheduled = false;
+      void flush();
+    });
+  }
+  async function send(batch) {
+    if (Date.parse(input.grant.expiresAt) <= wallMs()) return;
+    const payload = { sessionId: input.sessionId, observations: batch };
+    const retries = Math.max(0, Math.min(2, input.maxRetries ?? 2));
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        if (Date.parse(input.grant.expiresAt) <= wallMs()) return;
+        const response = await fetcher(input.grant.endpoint, {
+          method: "POST",
+          headers: { authorization: `Bearer ${input.grant.token}`, "content-type": "application/json" },
+          body: JSON.stringify(payload),
+          signal: AbortSignal.timeout(5e3)
+        });
+        if (response.ok) return;
+        if (response.status < 500 && response.status !== 429) return;
+        await response.body?.cancel().catch(() => {
+        });
+      } catch {
+      }
+      if (attempt < retries) await new Promise((resolve) => setTimeout(resolve, 100 * 2 ** attempt));
+    }
+  }
+  async function flush() {
+    if (queue2.length === 0) return;
+    if (flushing) return flushing;
+    flushing = (async () => {
+      try {
+        while (queue2.length) {
+          const batch = queue2.splice(0, MAX_CONNECTION_HISTORY_BATCH);
+          await send(batch);
+        }
+      } finally {
+        flushing = null;
+      }
+    })();
+    return flushing;
+  }
+  async function dispose() {
+    disposed = true;
+    await flush();
+    queue2.length = 0;
+  }
+  return { enqueue, flush, dispose };
+}
+
 // ../client/src/react/session-lifecycle.ts
 function phaseForReason(reason) {
   switch (reason) {
@@ -2783,11 +2902,35 @@ function SessionLifecycleRoomBridge({
   const prevTranscriptionCountRef = useRef(0);
   const audio = assistant.audioTrack;
   const video = assistant.videoTrack;
-  const detailsEnabled = onConnectionDetailsChange !== void 0 && lifecycle.grant !== null;
+  const connectionHistoryGrant = lifecycle.grant?.connection_history;
+  const detailsEnabled = (onConnectionDetailsChange !== void 0 || connectionHistoryGrant !== void 0) && lifecycle.grant !== null;
   const detailsSessionId = lifecycle.grant?.session_id;
+  const connectionHistoryRef = useRef(null);
   const updateDetailsRef = useRef(null);
   useEffect(() => {
-    if (!detailsEnabled || !onConnectionDetailsChange) return;
+    const sessionId = detailsSessionId;
+    if (!sessionId || !connectionHistoryGrant) {
+      connectionHistoryRef.current = null;
+      return;
+    }
+    const collector = createConnectionHistoryCollector({ sessionId, grant: connectionHistoryGrant });
+    connectionHistoryRef.current = collector;
+    return () => {
+      if (connectionHistoryRef.current === collector) connectionHistoryRef.current = null;
+      void collector.dispose();
+    };
+  }, [connectionHistoryGrant, detailsSessionId]);
+  useEffect(() => {
+    const collector = connectionHistoryRef.current;
+    if (!collector || typeof window === "undefined" || typeof window.addEventListener !== "function" || typeof window.removeEventListener !== "function") return;
+    const flush = () => {
+      void collector.flush();
+    };
+    window.addEventListener("pagehide", flush, true);
+    return () => window.removeEventListener("pagehide", flush, true);
+  }, [connectionHistoryGrant, detailsSessionId]);
+  useEffect(() => {
+    if (!detailsEnabled || !onConnectionDetailsChange && !connectionHistoryGrant) return;
     let callback = onConnectionDetailsChange;
     let audioSource = audio;
     let videoSource = video;
@@ -2795,8 +2938,9 @@ function SessionLifecycleRoomBridge({
     let pending = false;
     let previous;
     const deliver = (details) => {
+      connectionHistoryRef.current?.enqueue(details);
       try {
-        void Promise.resolve(callback(details)).catch(() => {
+        if (onConnectionDetailsChange) void Promise.resolve(callback?.(details)).catch(() => {
         });
       } catch {
       }
@@ -2854,7 +2998,7 @@ function SessionLifecycleRoomBridge({
     };
   }, [room, detailsSessionId, detailsEnabled]);
   useEffect(() => {
-    if (onConnectionDetailsChange) updateDetailsRef.current?.(onConnectionDetailsChange, audio, video);
+    updateDetailsRef.current?.(onConnectionDetailsChange, audio, video);
   }, [
     onConnectionDetailsChange,
     detailsEnabled ? audio?.participant : void 0,

package/dist/server.d.ts

@@ -1,3 +1,4 @@
 export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, RealtimeAvatarOptions, StartCallOptions, clipLibraryDeclarationSchema, verifyTranscript } from './index.js';
-export { h as Asset, g as AssetKind, A as Avatar, o as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, p as CallConnection, C as CallMode, a as CallPolicy, q as CallQueued, r as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, s as ClipLibraryPlan, e as ClipLibraryUpdate, t as ClipSource, u as ContextMessage, n as CreditBalance, E as EndCallOptions, v as EndCallReason, k as ListRecordingsQuery, l as ListRecordingsResponse, i as ListSessionsOptions, L as LoopRedirect, m as RecordingAccessResponse, R as RecordingArtifact, w as RecordingArtifactStatus, x as RecordingMode, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-VOv0vsFs.js';
+export { h as Asset, g as AssetKind, A as Avatar, o as AvatarClip, c as AvatarSourceSwap, b as AvatarUpdate, p as CallConnection, C as CallMode, a as CallPolicy, q as CallQueued, r as ClipDeclaration, f as ClipLibrary, d as ClipLibraryDeclaration, s as ClipLibraryPlan, e as ClipLibraryUpdate, t as ClipSource, u as ContextMessage, n as CreditBalance, E as EndCallOptions, v as EndCallReason, k as ListRecordingsQuery, l as ListRecordingsResponse, i as ListSessionsOptions, L as LoopRedirect, m as RecordingAccessResponse, R as RecordingArtifact, w as RecordingArtifactStatus, x as RecordingMode, S as StartCallResult, T as TranscriptPayload, j as UsageSession, U as UsageSessionPage, V as VideoPolicy, y as isQueued, z as listRecordingsResponseSchema, B as recordingAccessResponseSchema, D as recordingArtifactSchema, F as recordingModeSchema } from './types-BnlnrYgN.js';
+import './connection-history.js';
 import 'zod';

package/dist/server.js

@@ -1 +1,2 @@
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-V26PE2M3.js';
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript } from './chunk-4OLLYAJT.js';
+import './chunk-MCIXU6XP.js';

package/dist/tanstack-start.d.ts

@@ -1,5 +1,5 @@
-import { P as ProxyConfig } from './types-Bphj69NC.js';
-import './types-VOv0vsFs.js';
+import { P as ProxyConfig } from './types-CFkiNV3f.js';
+import './types-BnlnrYgN.js';
 import 'zod';
 
 /**

package/dist/tanstack-start.js

@@ -1,5 +1,6 @@
-import { createProxyHandler } from './chunk-2TNFET3Q.js';
-import './chunk-V26PE2M3.js';
+import { createProxyHandler } from './chunk-Q34WDWEA.js';
+import './chunk-4OLLYAJT.js';
+import './chunk-MCIXU6XP.js';
 
 // src/tanstack-start.ts
 function realtimeAvatarServerRoute(config) {

package/dist/{types-VOv0vsFs.d.ts → types-BnlnrYgN.d.ts}

@@ -163,6 +163,7 @@ interface components {
              * @enum {string}
              */
             recording?: "off" | "audio" | "video" | "audio_video";
+            connection_history?: boolean;
             client_metadata?: {
                 [key: string]: string;
             };
@@ -241,6 +242,13 @@ interface components {
                 /** @enum {string} */
                 errorCode: "recording_failed" | "recording_unavailable";
             };
+            readonly connection_history?: {
+                /** Format: starts_with */
+                endpoint: string;
+                token: string;
+                /** Format: date-time */
+                expiresAt: string;
+            };
         };
         LiveKitCapacitySnapshot: {
             capacity_pool: string;
@@ -573,6 +581,20 @@ interface components {
             /** Format: date-time */
             expiresAt: string;
         };
+        ConnectionHistoryResponse: {
+            sessionId: string;
+            observations: {
+                sequence: number;
+                elapsedMs: number;
+                clientObservedAt: string | null;
+                /** @enum {string} */
+                connectionState: "disconnected" | "connecting" | "connected" | "reconnecting" | "signalReconnecting";
+                /** @enum {string} */
+                localQuality: "excellent" | "good" | "poor" | "lost" | "unknown";
+                audioQuality: ("excellent" | "good" | "poor" | "lost" | "unknown") | null;
+                videoQuality: ("excellent" | "good" | "poor" | "lost" | "unknown") | null;
+            }[];
+        };
         ListAvatarsResponse: {
             data: {
                 id: string;
@@ -1090,6 +1112,8 @@ type VideoPolicy = {
 };
 /** What YOUR SERVER decides about a call. Never accept any of this from a browser. */
 interface CallPolicy {
+    /** Ask the platform to grant the SDK's optional LiveKit connection history collector. */
+    connectionHistory?: boolean;
     /** Optional server recording policy. Omitted means off; obtain user consent before enabling. */
     recording?: RecordingMode;
     /** Her behavior contract — who she is and how she speaks. Max 8000 chars. */

package/dist/{types-Bphj69NC.d.ts → types-CFkiNV3f.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-VOv0vsFs.js';
+import { C as CallMode, a as CallPolicy } from './types-BnlnrYgN.js';
 
 /** The three things a caller can ask the proxy to do. Gate on these, not on URLs. */
 type ProxyOperation = "connect" | "end" | "avatars" | "credits";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",
@@ -89,6 +89,10 @@
       "types": "./dist/recording.d.ts",
       "default": "./dist/recording.js"
     },
+    "./connection-history": {
+      "types": "./dist/connection-history.d.ts",
+      "default": "./dist/connection-history.js"
+    },
     "./tools": {
       "types": "./dist/tools.d.ts",
       "default": "./dist/tools.js"