realtime-avatar 0.14.0 → 0.16.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.14.0
+npm install --save-exact realtime-avatar@0.16.0
 ```
 
 ```ts
@@ -25,6 +25,61 @@ 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.
+
+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 +137,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?, transcript?, metadata? })
+rta.startCall({ avatarId, mode?, instructions?, context?, maxSeconds?, video?, recording?, 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)
+
 // avatars
 rta.createAvatarFromImage({ displayName, imageUrl, motionPrompt?, voice? })  // the only lane
 rta.createAvatarFromVideo({ displayName, videoUrl, voice? })                 // DEPRECATED — closed, 422
@@ -141,22 +201,65 @@ 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
 your server. A route that spreads the request body into `startCall` hands your caller your
 system prompt and your bill.
 
-### Native connection facts
+### Optional connection details
+
+`AvatarCall` provides call status, actions and end reasons for your default UI. To show
+connection diagnostics, opt in with `onConnectionDetailsChange`. It supplies data for
+your own UI; enabling it adds no built-in network notice or controls.
+
+```tsx
+import { useState } from "react";
+import { AvatarCall, type AvatarCallProps, type AvatarConnectionDetails } from "realtime-avatar/react";
+
+function CallWithDetails(props: Pick<AvatarCallProps, "client" | "avatarId">) {
+  const [details, setDetails] = useState<AvatarConnectionDetails | null>(null);
 
-LiveKit owns media transport, connection state, and reconnection. Use its
-`useConnectionState()` and `useConnectionQualityIndicator({ participant })` hooks, or
-`RoomEvent` callbacks, to build your product's network UI. Their values already use
-`ConnectionState`, `ConnectionQuality`, and `Track.StreamState` from `livekit-client`.
-For current receiver measurements, `RemoteVideoTrack.getReceiverStats()` and
-`RemoteAudioTrack.getReceiverStats()` return LiveKit's exported `VideoReceiverStats` and
-`AudioReceiverStats` types.
-Keep these native types in process; there is no SDK-specific JSON mirror to maintain.
+  return (
+    <>
+      <AvatarCall {...props} onConnectionDetailsChange={setDetails} />
+      {details && <p>Connection: {details.connectionState}. Local quality: {details.localQuality}.</p>}
+    </>
+  );
+}
+```
+
+Once bound to a call, the callback receives an initial snapshot, then changed facts only. It receives `null`
+when its room or session binding is retired, before a replacement binding's snapshot.
+Clearing the session grant keeps details reset until a new grant arrives.
+Keep this state scoped to one call and clear it on `null`, as the example does. This is
+a current snapshot, not a lossless event history. Replacing the handler does not restart
+the call, and errors in your handler do not interrupt it. Omitting the callback adds no
+reporting listeners; the callback adds no timers, stats polling or uploads.
+
+Each field preserves LiveKit's native type and meaning:
+
+| Field | Source |
+| --- | --- |
+| `connectionState` | The bound room's `state`. |
+| `localQuality` | The local participant's `connectionQuality`. |
+| `audio.publisherQuality` | The selected audio publisher's `connectionQuality`. |
+| `video.publisherQuality` | The selected video publisher's `connectionQuality`. |
+| `audio.streamState`, `video.streamState` | The corresponding remote track's `streamState`, or `null` before the track exists. |
+
+Audio and video publishers are selected independently and can differ. Neither field
+substitutes the control agent or an arbitrary remote participant. `audio` or `video` is
+`null` when no corresponding track reference is selected; LiveKit's `Unknown` quality
+means a publisher exists but its quality is unknown. An active or subscribed track does
+not prove that video has rendered or audio is audible. Continue using call status for
+the call lifecycle.
+
+Native and custom integrations pass the same optional callback to their existing
+`SessionLifecycleRoomBridge` inside `RealtimeAvatarLiveKitRoom`. Both
+`realtime-avatar/react` and `realtime-avatar/react-native` export `AvatarConnectionDetails`.
+For deeper receiver measurements, use LiveKit's public `RemoteVideoTrack.getReceiverStats()`
+and `RemoteAudioTrack.getReceiverStats()` methods and their native return types.
 
 Retain the app's session-to-room association (`room_name`, timestamps and participant
 identity), adding the server-observed room SID when exact room-lifetime lookup needs it.

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

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

package/dist/{chunk-UZQXZH2Z.js → chunk-V26PE2M3.js}

@@ -214,6 +214,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 +271,332 @@ 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()
+}).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()
+}).strict();
+var liveKitSessionGrantSchema = z.object({
+  recording: recordingArtifactSchema.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.14.0";
+var SDK_VERSION = "0.16.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -281,6 +641,7 @@ 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.clientTools) body.capabilities = ["client_tools"];
     if (options.transcript !== void 0) {
       body.transcript_webhook = { url: options.transcript.url, secret: options.transcript.secret };
@@ -299,20 +660,23 @@ 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
+      raw
     };
   }
   /**
@@ -632,6 +996,24 @@ 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`)));
+  }
   async creditBalance() {
     return await this.#json(await this.#request("GET", "/credits/balance"));
   }
@@ -811,4 +1193,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/express.d.ts

@@ -1,5 +1,6 @@
-import { P as ProxyConfig } from './types-CJcTowDB.js';
-import './types-B9GTrpx0.js';
+import { P as ProxyConfig } from './types-Bphj69NC.js';
+import './types-VOv0vsFs.js';
+import 'zod';
 
 type Expressish = {
     method: string;

package/dist/express.js

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

package/dist/hono.d.ts

@@ -1,5 +1,6 @@
-import { P as ProxyConfig } from './types-CJcTowDB.js';
-import './types-B9GTrpx0.js';
+import { P as ProxyConfig } from './types-Bphj69NC.js';
+import './types-VOv0vsFs.js';
+import 'zod';
 
 /**
  * Hono (and anything else built on Fetch handlers — Workers, Bun, Deno).

package/dist/hono.js

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