realtime-avatar 0.15.0 → 0.17.0

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.15.0
+npm install --save-exact realtime-avatar@0.17.0
 ```
 
 ```ts
@@ -25,6 +25,79 @@ return call.raw;   // relay to the browser byte-for-byte
 
 That is the whole server half. The client joins with the payload and renders her.
 
+## Optional call recordings
+
+Your server decides whether to record after your application obtains consent:
+
+```ts
+const call = await rta.startCall({ avatarId, recording: "audio_video" });
+if (!isQueued(call) && call.recording) {
+  await saveRecordingId(call.sessionId, call.recording.recordingId);
+}
+
+// Later, in your authenticated admin backend:
+const recording = await rta.getRecording(recordingId);
+if (recording.status === "ready") {
+  const { url, expiresAt } = await rta.getRecordingAccess(recordingId);
+  // Return this short-lived access to the authorized viewer.
+}
+```
+
+Omitted or `"off"` disables recording. `"audio"` records published user and avatar audio;
+`"video"` records published video without audio; `"audio_video"` keeps both on one media timeline.
+Recording does not enable the microphone, camera, or screen sharing. Only tracks that participants
+authorize and publish can be recorded. Camera controls remain a future SDK feature.
+
+Recordings may finish processing after a call ends. Use `listRecordings({ sessionId })` to find
+them, or refresh `getRecording(recordingId)` while processing. These methods and
+`getRecordingAccess` require a server key with `recordings:read`.
+
+Save `recordingId`, not a playback URL. Files are retained until `retainedUntil` (30 days by
+default); each URL expires at `expiresAt` (up to one hour, capped by retention). Obtain fresh
+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
+alignment for lip-sync analysis.
+
+Client-safe Zod schemas and derived types are available from `realtime-avatar/recording`.
+They are the same executable contract used by the service, verified against the published digest.
+
+```mermaid
+---
+title: Recording ownership and private playback
+---
+flowchart LR
+  App[Application server: consent and recording policy] --> RTA[RTA: call and recording lifecycle]
+  RTA --> Media[Media provider: record published tracks]
+  Media --> Storage[Private media storage]
+  RTA --> Metadata[Recording ID and session ID]
+  Admin[Authorized admin backend] --> RTA
+  RTA --> Access[Temporary playback URL]
+  Access --> Player[Video or audio player]
+  Storage --> Player
+```
+
 New here? The [quickstart](https://realtimeavatar.ai/docs/quickstart) goes from an API key to a
 working call, and a [sandbox key](https://realtimeavatar.ai/signup) is free with no card. Mount
 the server half on your framework:
@@ -82,9 +155,15 @@ 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?, 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
 rta.createAvatarFromVideo({ displayName, videoUrl, voice? })                 // DEPRECATED — closed, 422
@@ -141,6 +220,7 @@ Browser — these never can:
 | `realtime-avatar/react-native` | The same surface for Expo / React Native |
 | `realtime-avatar/browser` | `enableMicrophone`, `attachRemoteAudio`, `prepareAvatarRoom` — no React |
 | `realtime-avatar/tools` | `attachAvatarTools` — the browser tool plane |
+| `realtime-avatar/recording` | Client-safe Zod recording schemas and derived types |
 
 Every adapter takes the same two hooks: `authorize` gates the request, `session` decides the
 call. Policy — `instructions`, `maxSeconds`, `voice`, `video` — is decided in `session`, on

package/dist/{chunk-LZMJJX7C.js → chunk-27BB4DQ2.js}

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

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-PKKTFUA7.js → chunk-OESXLLQB.js}

@@ -1,3 +1,4 @@
+import { connectionHistoryGrantSchema } from './chunk-MCIXU6XP.js';
 import { z } from 'zod';
 
 // ../http-client/src/errors.ts
@@ -214,6 +215,44 @@ var schema26 = z.strictObject({
 });
 var clipLibraryResponseSchema = schema24;
 var clipLibraryUpdateSchema = schema26;
+var RECORDED_MEDIA_MODES = ["audio", "video", "audio_video"];
+var recordingModeSchema = z.enum(["off", ...RECORDED_MEDIA_MODES]).describe("Server-owned recording policy; omitted means off. Audio includes user and avatar audio.");
+var RECORDING_STATUSES = ["pending", "recording", "processing", "ready", "failed", "expired"];
+z.enum(RECORDING_STATUSES);
+var recordingMetadataSchema = z.object({
+  sessionId: z.string().min(1),
+  recordingId: z.string().min(1),
+  mode: recordingModeSchema.exclude(["off"]),
+  createdAt: z.string().datetime({ offset: true }),
+  retainedUntil: z.string().datetime({ offset: true })
+});
+var recordingArtifactSchema = z.discriminatedUnion("status", [
+  recordingMetadataSchema.extend({ status: z.enum(["pending", "recording", "processing", "expired"]) }).strict(),
+  recordingMetadataSchema.extend({
+    status: z.literal("ready"),
+    mediaType: z.enum(["audio/mp4", "video/mp4"]),
+    sizeBytes: z.number().int().positive(),
+    durationMs: z.number().int().nonnegative().nullable()
+  }).strict(),
+  recordingMetadataSchema.extend({
+    status: z.literal("failed"),
+    errorCode: z.enum(["recording_failed", "recording_unavailable"])
+  }).strict()
+]);
+var listRecordingsQuerySchema = z.object({
+  sessionId: z.string().min(1).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  cursor: z.string().min(1).optional()
+}).strict();
+var listRecordingsResponseSchema = z.object({
+  data: z.array(recordingArtifactSchema),
+  nextCursor: z.string().nullable()
+}).strict();
+var recordingAccessResponseSchema = z.object({
+  recordingId: z.string().min(1),
+  url: z.string().url(),
+  expiresAt: z.string().datetime({ offset: true })
+}).strict();
 
 // ../http-client/src/retry.ts
 var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 500, 502, 503, 504]);
@@ -233,10 +272,335 @@ function isTransient(cause) {
   const name = cause?.name;
   return name === "TimeoutError" || name === "TypeError" || name === "FetchError";
 }
+var DEFAULT_AVATAR_ID = "maria";
+var DEFAULT_BACKGROUND_ID = "plain_white";
+var sessionModeSchema = z.enum(["avatar", "voice"]);
+var DEFAULT_SESSION_MODE = "avatar";
+var DEFAULT_MAX_SESSION_SECONDS = 1800;
+var avatarSourceKindSchema = z.enum(["portrait", "source_video"]);
+var liveKitSttModeSchema = z.enum(["server", "off"]);
+var renderBackendSchema = z.string();
+var sessionLiveEditSchema = z.object({
+  rules: z.string().min(1).max(2e3),
+  cooldown_seconds: z.number().int().min(5).max(600).optional(),
+  // Which machinery runs the re-edit. Absent ⇒ the server default ("editor"). A deploy
+  // that cannot provide the requested renderer serves the editor lane and logs it,
+  // rather than failing a call that would otherwise have connected fine.
+  renderer: z.enum(["editor", "generative"]).optional()
+}).strict();
+var sessionSupportEditsSchema = z.object({
+  instruction: z.string().min(1).max(1e3),
+  reference_url: z.string().url().optional(),
+  live_edit: sessionLiveEditSchema.optional()
+}).strict();
+var LLM_PROVIDERS = ["local", "gemini", "openai"];
+var llmProviderSchema = z.enum(LLM_PROVIDERS);
+var llmConfigSchema = z.object({
+  backend: llmProviderSchema.optional(),
+  model: z.string().max(200).nullable().optional()
+}).strict();
+var llmSelectionSchema = z.object({
+  provider: llmProviderSchema,
+  model: z.string().max(200).nullable().optional()
+}).strict();
+var liveKitInitialContextMessageSchema = z.object({
+  role: z.enum(["system", "user", "assistant"]),
+  content: z.string().min(1).max(4e3)
+}).strict();
+var CARTESIA_TTS_MODELS = [
+  "cartesia/sonic-2",
+  "cartesia/sonic-2-latest",
+  "cartesia/sonic-3",
+  "cartesia/sonic-3-latest",
+  "cartesia/sonic-turbo",
+  "cartesia/sonic-turbo-latest"
+];
+var cartesiaTtsModelSchema = z.enum(CARTESIA_TTS_MODELS);
+var cartesiaVoiceSpecSchema = z.object({
+  provider: z.literal("cartesia"),
+  model: cartesiaTtsModelSchema.default("cartesia/sonic-3"),
+  voice_id: z.string().min(1).max(120),
+  speed: z.number().min(0.5).max(2).nullable().optional(),
+  emotion: z.string().min(1).max(80).nullable().optional(),
+  language: z.string().min(2).max(16).nullable().optional()
+}).strict();
+var FISH_TTS_MODELS = ["speech-1.6", "s1", "s2-pro", "speech-1.5", "s1-mini"];
+var fishTtsModelSchema = z.enum(FISH_TTS_MODELS);
+var breezeVoiceSpecSchema = z.object({
+  provider: z.literal("breezeblue"),
+  model: z.string().min(1).max(80).default("bluebell-v1-en"),
+  voice_id: z.string().min(1).max(120),
+  guidance_scale: z.number().min(1).max(10).nullable().optional(),
+  instructions: z.string().min(1).max(1e3).nullable().optional(),
+  language: z.string().min(2).max(16).nullable().optional()
+}).strict();
+var fishVoiceSpecSchema = z.object({
+  provider: z.literal("fish"),
+  model: fishTtsModelSchema.default("speech-1.6"),
+  voice_id: z.string().min(1).max(120),
+  speed: z.number().min(0.5).max(2).nullable().optional(),
+  emotion: z.string().min(1).max(80).nullable().optional(),
+  language: z.string().min(2).max(16).nullable().optional()
+}).strict();
+var voiceSpecSchema = z.discriminatedUnion("provider", [
+  cartesiaVoiceSpecSchema,
+  breezeVoiceSpecSchema,
+  fishVoiceSpecSchema
+]);
+var nullableUrlSchema = z.string().url().nullable();
+var clipTriggerSchema = z.enum([
+  "idle",
+  "listen",
+  "think",
+  "directive"
+]);
+var sessionClipSchema = z.object({
+  clip_id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, "clip_id must be a slug").refine((id) => id !== "primary", "'primary' is reserved for the avatar's source video"),
+  source_video_url: z.string().url().optional(),
+  video_cache_id: z.string().min(8).max(160).optional(),
+  max_seconds: z.number().min(1).max(10).optional(),
+  trigger: clipTriggerSchema.optional(),
+  loop: z.boolean().optional(),
+  weight: z.number().min(0).max(100).optional(),
+  crossfade_ms: z.number().int().min(0).max(1e3).optional(),
+  trim_start_ms: z.number().int().min(0).max(2e3).optional(),
+  trim_end_ms: z.number().int().min(0).max(2e3).optional(),
+  // The cue the character reads to decide this clip. `when` is the public name and the
+  // one the docs use; `hint` is the name the wire first shipped under and still accepts.
+  // Both are listed because this object is `.strict()` — omitting `when` would make the
+  // public name a validation error. Send one, never both.
+  when: z.string().min(1).max(120).optional(),
+  hint: z.string().min(1).max(120).optional()
+}).strict().refine((clip) => clip.source_video_url || clip.video_cache_id, {
+  message: "a clip needs source_video_url or video_cache_id"
+}).refine((clip) => !(clip.when && clip.hint), {
+  message: "set `when` or `hint`, not both \u2014 they are the same field",
+  path: ["when"]
+});
+var sessionChoreographySchema = z.object({
+  idle_dwell_min_seconds: z.number().min(1).max(60).optional(),
+  idle_dwell_max_seconds: z.number().min(1).max(120).optional(),
+  special_weight: z.number().min(0).max(100).optional(),
+  start_grace_seconds: z.number().min(0).max(60).optional(),
+  crossfade_ms: z.number().int().min(0).max(1e3).optional(),
+  crossfade_easing: z.enum(["linear", "smooth", "ease_out"]).optional(),
+  wrap_crossfade_ms: z.number().int().min(0).max(1e3).optional()
+}).strict().refine(
+  (c) => c.idle_dwell_min_seconds === void 0 || c.idle_dwell_max_seconds === void 0 || c.idle_dwell_min_seconds <= c.idle_dwell_max_seconds,
+  { message: "idle_dwell_min_seconds must be <= idle_dwell_max_seconds" }
+);
+var sessionBehaviorSchema = z.object({
+  gestures_enabled: z.boolean().optional()
+}).strict();
+var transcriptWebhookSchema = z.object({
+  url: z.string().url().max(500),
+  secret: z.string().min(16).max(200)
+}).strict();
+var clientMetadataSchema = z.record(z.string().min(1).max(64), z.string().max(200)).refine((value) => Object.keys(value).length <= 16, {
+  message: "client_metadata carries at most 16 entries"
+});
+var MAX_SESSION_INSTRUCTIONS_CHARS = 8e3;
+z.object({
+  avatar_id: z.string().min(1).max(160).default(DEFAULT_AVATAR_ID),
+  background_id: z.string().min(1).max(160).default(DEFAULT_BACKGROUND_ID),
+  mode: sessionModeSchema.default(DEFAULT_SESSION_MODE),
+  create_room: z.boolean().default(true),
+  dispatch_agent: z.boolean().default(true),
+  instructions: z.string().min(1).max(MAX_SESSION_INSTRUCTIONS_CHARS).optional(),
+  initial_context: z.array(liveKitInitialContextMessageSchema).max(32).default([]),
+  initial_say: z.string().min(1).max(1e3).optional(),
+  llm: llmConfigSchema.nullable().optional(),
+  max_session_seconds: z.number().int().min(1).max(DEFAULT_MAX_SESSION_SECONDS).optional(),
+  participant_identity: z.string().min(1).max(160).optional(),
+  participant_name: z.string().max(160).optional(),
+  queue_ticket_id: z.string().min(1).max(160).optional(),
+  portrait_url: nullableUrlSchema.optional(),
+  room_name: z.string().min(1).max(160).optional(),
+  source_kind: avatarSourceKindSchema.default("portrait"),
+  source_video_url: nullableUrlSchema.optional(),
+  stt_mode: liveKitSttModeSchema.default("server"),
+  video_cache_id: z.string().min(1).max(240).nullable().optional(),
+  voice: voiceSpecSchema.nullable().optional(),
+  voice_id: z.string().min(1).max(240).nullable().optional(),
+  // Deliberately UNBOUNDED. This object is `.strict()`, so it rejects rather than trims:
+  // a count cap here does not mean "use fewer clips", it means "there is no call". How
+  // many a session actually warms is decided where the clips are loaded, and loading
+  // fewer is always safe — so the wire must not hold a number too.
+  clip_library: z.array(sessionClipSchema).optional(),
+  choreography: sessionChoreographySchema.optional(),
+  behavior: sessionBehaviorSchema.optional(),
+  expression_profile: z.string().min(1).max(40).optional(),
+  render_backend: renderBackendSchema.optional(),
+  support_edits: sessionSupportEditsSchema.optional(),
+  transcript_webhook: transcriptWebhookSchema.optional(),
+  client_metadata: clientMetadataSchema.optional(),
+  connection_history: z.boolean().optional()
+}).strict().superRefine((value, ctx) => {
+  if (value.support_edits && value.render_backend === "generative") {
+    ctx.addIssue({
+      code: "custom",
+      message: "support_edits needs a source video to edit; it cannot be combined with render_backend='generative'",
+      path: ["support_edits"]
+    });
+  }
+  if (value.support_edits && value.mode === "voice") {
+    ctx.addIssue({
+      code: "custom",
+      message: "support_edits needs a video session; it cannot be combined with mode='voice'",
+      path: ["support_edits"]
+    });
+  }
+  if (value.source_kind === "portrait") {
+    if (value.source_video_url || value.video_cache_id) {
+      ctx.addIssue({
+        code: "custom",
+        message: "source_video_url/video_cache_id require source_kind='source_video'",
+        path: ["source_kind"]
+      });
+    }
+    return;
+  }
+  if (value.portrait_url) {
+    ctx.addIssue({
+      code: "custom",
+      message: "portrait_url cannot be combined with source_kind='source_video'",
+      path: ["portrait_url"]
+    });
+  }
+  if (!value.source_video_url && !value.video_cache_id) {
+    ctx.addIssue({
+      code: "custom",
+      message: "source_kind='source_video' requires source_video_url or video_cache_id",
+      path: ["source_video_url"]
+    });
+  }
+});
+z.object({
+  avatarId: z.string().min(1).max(160),
+  backgroundId: z.string().min(1).max(160).default(DEFAULT_BACKGROUND_ID),
+  mode: sessionModeSchema.default(DEFAULT_SESSION_MODE),
+  createRoom: z.boolean().default(true),
+  dispatchAgent: z.boolean().default(true),
+  instructions: z.string().min(1).max(MAX_SESSION_INSTRUCTIONS_CHARS).optional(),
+  initialContext: z.array(liveKitInitialContextMessageSchema).max(32).default([]),
+  initialSay: z.string().min(1).max(1e3).optional(),
+  llm: llmSelectionSchema.nullable().optional(),
+  maxSessionSeconds: z.number().int().min(1).max(DEFAULT_MAX_SESSION_SECONDS).optional(),
+  participantIdentity: z.string().min(1).max(160).optional(),
+  participantName: z.string().max(160).optional(),
+  queueTicketId: z.string().min(1).max(160).optional(),
+  roomName: z.string().min(1).max(160).optional(),
+  sttMode: liveKitSttModeSchema.default("server"),
+  voice: voiceSpecSchema.nullable().optional(),
+  voiceId: z.string().min(1).max(240).nullable().optional(),
+  // Unbounded, for the same reason as `clip_library` on the wire schema above.
+  clipLibrary: z.array(sessionClipSchema).optional(),
+  behavior: sessionBehaviorSchema.optional(),
+  renderBackend: renderBackendSchema.optional(),
+  supportEdits: sessionSupportEditsSchema.optional(),
+  transcriptWebhook: transcriptWebhookSchema.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),
+  livekit_url: z.string().min(1),
+  participant_token: z.string().min(1),
+  participant_identity: z.string().min(1),
+  reservation_expires_at: z.string().datetime({ offset: true }),
+  stt_mode: liveKitSttModeSchema.default("server"),
+  room_created: z.boolean().default(false),
+  dispatch_created: z.boolean().default(false),
+  join_timeout_seconds: z.number().int().nonnegative().default(0),
+  idle_timeout_seconds: z.number().int().nonnegative().default(0),
+  max_session_seconds: z.number().int().nonnegative().default(0)
+}).passthrough();
+var sessionEndReasonSchema = z.enum([
+  "user_ended",
+  "session_cap",
+  "idle",
+  "disconnected",
+  "out_of_credits",
+  "agent_ended",
+  "failed"
+]);
+var approachingEndReasonSchema = z.enum(["session_cap", "idle"]);
+var sessionClockFrameSchema = z.object({
+  kind: z.literal("session_clock"),
+  started_at_unix_ms: z.number().int().nonnegative(),
+  max_session_seconds: z.number().int().nonnegative(),
+  idle_timeout_seconds: z.number().int().nonnegative()
+}).strict();
+var endingFrameSchema = z.object({ kind: z.literal("ending"), reason: approachingEndReasonSchema }).strict();
+var closingTurnDoneFrameSchema = z.object({ kind: z.literal("closing_turn_done"), turn_id: z.string().min(1) }).strict();
+var endedFrameSchema = z.object({ kind: z.literal("ended"), reason: sessionEndReasonSchema }).strict();
+var behaviorStateFrameSchema = z.object({
+  kind: z.literal("behavior_state"),
+  state: z.string().min(1).max(32),
+  clip_id: z.string().min(1).max(64).optional(),
+  trigger: clipTriggerSchema.optional(),
+  loop: z.boolean().optional(),
+  prev_clip_id: z.string().min(1).max(64).optional()
+}).strip();
+var clipAckFrameSchema = z.object({
+  kind: z.literal("clip_ack"),
+  request_id: z.string().max(64),
+  accepted: z.boolean(),
+  reason: z.string().max(64)
+}).strip();
+z.discriminatedUnion("kind", [
+  sessionClockFrameSchema,
+  endingFrameSchema,
+  closingTurnDoneFrameSchema,
+  endedFrameSchema,
+  behaviorStateFrameSchema,
+  clipAckFrameSchema
+]);
+var liveKitCapacitySnapshotSchema = z.object({
+  // Placement identity + per-worker session ceiling. These are always present on the
+  // wire (the platform serializes them and they come back on the grant, so a customer
+  // already sees them) but are typed OPTIONAL here on purpose: this SDK is the defensive
+  // READER of that wire, so a consumer must tolerate a response variant that omits them
+  // rather than hard-fail parse. `max_sessions_per_gpu` is how many sessions one waking
+  // worker serves — a queue-depth estimate input a consumer reads off the busy response.
+  capacity_pool: z.string().min(1).optional(),
+  agent_name: z.string().min(1).optional(),
+  max_sessions: z.number().int().nonnegative(),
+  max_sessions_per_gpu: z.number().int().positive().optional(),
+  worker_count: z.number().int().nonnegative(),
+  active_sessions: z.number().int().nonnegative(),
+  reserved_sessions: z.number().int().nonnegative(),
+  observed_worker_active_sessions: z.number().int().nonnegative(),
+  available_sessions: z.number().int().nonnegative(),
+  queue_size: z.number().int().nonnegative(),
+  admission_open: z.boolean(),
+  recommended_retry_ms: z.number().int().nonnegative(),
+  load: z.number().min(0).max(1)
+}).passthrough();
+z.object({
+  message: z.string().min(1),
+  capacity: liveKitCapacitySnapshotSchema,
+  queue_size: z.number().int().nonnegative(),
+  queue_ticket_id: z.string().min(1).optional(),
+  queue_position: z.number().int().positive().optional(),
+  recommended_retry_ms: z.number().int().nonnegative()
+}).strict();
+z.enum([
+  "page_hide",
+  "disconnected",
+  "superseded",
+  "unmount",
+  "manual",
+  "idle_timeout"
+]);
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.15.0";
+var SDK_VERSION = "0.17.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -281,6 +645,8 @@ var RealtimeAvatar = class {
     if (options.maxSeconds !== void 0) body.max_session_seconds = Math.floor(options.maxSeconds);
     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 };
@@ -299,20 +665,24 @@ var RealtimeAvatar = class {
         };
       }
     }
-    const grant = await this.#json(response);
+    const raw = await this.#json(response);
+    const grant = liveKitSessionGrantSchema.parse(raw);
+    if (!isRecord(raw)) throw new RealtimeAvatarError("Invalid session grant");
     return {
       status: "ready",
-      sessionId: String(grant.session_id),
-      roomName: String(grant.room_name),
-      livekitUrl: String(grant.livekit_url),
-      participantToken: String(grant.participant_token),
-      participantIdentity: String(grant.participant_identity),
-      maxSessionSeconds: Number(grant.max_session_seconds ?? 0),
-      idleTimeoutSeconds: Number(grant.idle_timeout_seconds ?? 0),
-      reservationExpiresAt: String(grant.reservation_expires_at),
+      ...grant.recording === void 0 ? {} : { recording: grant.recording },
+      sessionId: grant.session_id,
+      roomName: grant.room_name,
+      livekitUrl: grant.livekit_url,
+      participantToken: grant.participant_token,
+      participantIdentity: grant.participant_identity,
+      maxSessionSeconds: grant.max_session_seconds,
+      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.
-      raw: grant
+      // the browser SDK accepts provider-issued capability fields through its passthrough
+      // grant schema; forwarding verbatim preserves capabilities this wrapper does not model.
+      raw
     };
   }
   /**
@@ -632,6 +1002,30 @@ var RealtimeAvatar = class {
       cursor = page.nextCursor ?? void 0;
     } while (cursor);
   }
+  /** Recording metadata for this account, optionally limited to one call. Requires recordings:read. */
+  async listRecordings(options = {}) {
+    const parsed = listRecordingsQuerySchema.parse(options);
+    const query = new URLSearchParams();
+    if (parsed.sessionId !== void 0) query.set("sessionId", parsed.sessionId);
+    if (options.limit !== void 0) query.set("limit", String(parsed.limit));
+    if (parsed.cursor !== void 0) query.set("cursor", parsed.cursor);
+    const suffix = query.size ? `?${query}` : "";
+    return listRecordingsResponseSchema.parse(await this.#json(await this.#request("GET", `/recordings${suffix}`)));
+  }
+  /** Current recording status. Final media can become ready after the call has ended. */
+  async getRecording(recordingId) {
+    return recordingArtifactSchema.parse(await this.#json(await this.#request("GET", `/recordings/${encodeURIComponent(recordingId)}`)));
+  }
+  /** Renewable playback access. Keep recordingId in storage; URLs expire at expiresAt. */
+  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"));
   }
@@ -811,4 +1205,4 @@ function isQueued(result) {
   return "queued" in result;
 }
 
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, verifyTranscript };
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript };

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';