realtime-avatar 0.24.1 → 0.26.0

package/README.md

@@ -224,6 +224,7 @@ all), and the `video` policy types are deliberately not one-to-one with the wire
 // calls
 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
+rta.leaveQueue(queueTicketId, { reason? }) // give up a queued call's place in line; idempotent, never throws
 
 // optional recordings; server only, requires recordings:read
 rta.listRecordings({ sessionId, limit?, cursor? })
@@ -294,6 +295,61 @@ call. Policy — `instructions`, `maxSeconds`, `voice`, `video` — is decided i
 your server. A route that spreads the request body into `startCall` hands your caller your
 system prompt and your bill.
 
+### Styling
+
+`AvatarCall` and `AvatarVideoSurface` lay themselves out with inline styles, so they need no
+CSS build and no configuration: no stylesheet to import and no Tailwind `@source` for this
+package. The surface fills its container; give that container a definite size (an aspect
+ratio plus a height, say). `className` on the surface adds your own classes; to change a
+property the surface sets itself, such as its 100% size, pass `style`.
+
+`AvatarCall`'s `children` render in a layer that fills the call's box above the video and
+the live badge, so an absolutely positioned control places itself against the box and stays
+clickable while she is live.
+
+### Microphone and sound
+
+The handle reports the two local failures a "live" call can hide. `call.microphone` says
+whether she can hear the user (`off`, `pending`, `on`, `muted`, `blocked`, `unavailable`; the
+last two carry `reason`, `message` and `hint`), and `onMicrophoneProblem` fires once per new
+problem. A device that stops mid-call reads `pending` while LiveKit retries the default device,
+and `unavailable` (`device-lost`) only once that fails. `call.retryMicrophone()` asks again after
+the user fixes it, and `call.setMicrophoneEnabled(enabled)` mutes and unmutes. While the call is
+waiting or connecting those only record the choice (nothing is captured before the room
+connects), a mute made then is kept when the call goes live, and after `end()` they do nothing.
+
+`call.audio` says whether the user can hear her (`unknown`, `allowed`, `blocked`; `unknown` again
+once the call ended). While it is `blocked`, `AvatarCall` shows a "Tap to turn on sound" button,
+top-centre in a polite live region, that calls `call.startAudio()`. Pass `audioUnlockPrompt` a
+function to render your own (your words, your placement), or `false` for nothing.
+`startAudio()` must run inside a click or tap handler; it never rejects and resolves whether
+playback is allowed afterwards.
+
+Every state is derived from LiveKit's public events, and LiveKit still owns the device: it
+captures on connect and stops when the room leaves. A microphone error from an earlier call on
+the same room is not reported for the next one. A publish that fails after the microphone was
+captured reaches only the room's `onError` and stays `pending`: that callback also carries
+unrelated failures, so it is not guessed into a microphone problem.
+
+### Ending a call
+
+`call.end()` (and `useRealtimeSession().end()`) is terminal from every phase, including
+`waiting` in the queue and `connecting`. It stops the queue retry and the reconnect ladder,
+releases the held session or the queue ticket, leaves the room (which stops the microphone),
+moves `status` to `"ended"` and fires `onEnded({ reason: "user_ended" })` once. Ending a call
+that is already over does nothing. `sayAndEnd(text)` is the graceful path when she should speak
+a last line first.
+
+**After `end()`, nothing starts a call except you, explicitly.** Changing `avatarId`, `mode` or
+`listen` on an ended `AvatarCall` does not redial; remount it, for example with a `key`:
+
+```tsx
+<AvatarCall key={callId} client={client} avatarId={avatarId} />   // new callId → new call
+```
+
+On the lower-level hooks, `reconnect()` redials (a double tap mints once), and so does setting
+`active` to false and back. `reset()` does not undo an end.
+
 ### Optional connection details
 
 `AvatarCall` provides call status, actions and end reasons for your default UI. To show
@@ -390,6 +446,28 @@ room-wide to whatever you render inside it (`playoutDelaySeconds={false}` opts o
 `attachAvatarTools` runs your functions in the page. Nothing is executed on the platform, and
 a tool has **2.5 seconds** to answer before the call gives up on it and tells her it failed.
 
+A failed registration throws `ToolRegistrationError`, whose `retryable` says whether trying again
+can help: the agent not there or not armed by the deadline (a slow start, or a session minted
+without `client_tools`; one attempt cannot tell which), or an RPC transport failure, is retryable;
+an oversized manifest or a request LiveKit or the agent refused is not.
+
+In React, `useCharacterTools(tools)` registers them while the room is connected and returns
+their state: `idle`, `registering` (with `attempt`), `ready` (`registered`, `rejected`) or
+`error`. A retryable failure is retried twice (after 1s, then 3s) while the room stays
+connected; only then is it `error`. It re-registers when the manifest changes (names,
+descriptions, parameters), not when the `tools` object does, so an inline object is fine and
+each call reaches your latest `execute`. With `AvatarCall`, call it from a component you render
+as a child, which runs inside the call's room, and show its state rather than ignore it:
+
+```tsx
+function Tools() {
+  const tools = useCharacterTools(myTools);
+  return tools.status === "error" ? <p role="status">Tools are off for this call: {tools.error}</p> : null;
+}
+
+<AvatarCall client={client} avatarId="ava_…">{() => <Tools />}</AvatarCall>
+```
+
 ## What `/react` exports, and what it deliberately does not
 
 31 names, down from 82 on 2026-08-26. Two groups came out and are not coming back:

package/dist/browser.d.ts

@@ -1,4 +1,4 @@
-export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, P as PlayoutDelayTarget, a as applyAvatarPlayoutDelay, b as applyPlayoutDelay } from './playout-delay-DWOc8iCl.js';
+export { D as DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, E as EnableMicrophoneOptions, M as MicrophoneCapableRoom, a as MicrophoneFailureReason, b as MicrophoneProblem, c as MicrophoneProblemReason, d as MicrophoneResult, P as PlayoutDelayTarget, e as applyAvatarPlayoutDelay, f as applyPlayoutDelay, g as describeMicrophoneFailure, h as enableMicrophone } from './playout-delay-CtRZdtsj.js';
 
 type VideoSupport = {
     supported: true;
@@ -10,91 +10,6 @@ type VideoSupport = {
 /** Check before starting a billed video session; this does not prove negotiated playback. */
 declare function checkVideoSupport(codec?: string): VideoSupport;
 
-/**
- * Turning the microphone on, and saying what went wrong when it does not.
- *
- * WHY THIS EXISTS. `room.localParticipant.setMicrophoneEnabled(true)` is one line, so every
- * integration writes it inline and none of them handle its rejection — the reject path is
- * invisible until a real user is on a real machine. When it fails there is nothing to see:
- * the call is already connected, the page is mid-`await`, and the rejection becomes an
- * unhandled promise nobody is looking at. The reported symptom is always the same sentence —
- * "the mic won't start" — and it covers at least six unrelated causes with different fixes,
- * one of which is not in the browser at all.
- *
- * So this returns a RESULT rather than throwing: the cause becomes a value the caller has to
- * handle, and each one carries the sentence that names its actual fix. `message` is what the
- * browser said; `hint` is what the person should do.
- *
- * It is deliberately structural — it never imports `livekit-client`, so it pins no version
- * and adds no bytes. Anything with a `localParticipant.setMicrophoneEnabled` satisfies it.
- */
-/** The sliver of livekit-client's `Room` this needs. Structural on purpose — see above. */
-interface MicrophoneCapableRoom {
-    localParticipant: {
-        setMicrophoneEnabled(enabled: boolean): Promise<unknown>;
-    };
-}
-/**
- * Why the microphone did not start. Every variant has a DIFFERENT fix, which is the whole
- * reason this is an enum and not a boolean.
- */
-type MicrophoneFailureReason = 
-/** No `navigator.mediaDevices` — the page is not a secure context. */
-"insecure-origin"
-/** The permission prompt was never answered. getUserMedia may never settle; we time out. */
- | "no-answer"
-/** The BROWSER denied it — the site's own permission, resettable from the address bar. */
- | "denied-by-browser"
-/** The OS denied it — macOS System Settings, nothing the page or the site can change. */
- | "denied-by-os"
-/** No input device is connected, or none matches the constraints. */
- | "no-device"
-/** A device exists but something else holds it — another tab, app, or a stale call. */
- | "device-in-use"
-/** Anything unrecognised. `message` still carries what the browser said. */
- | "unknown";
-type MicrophoneResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: MicrophoneFailureReason;
-    /** What the browser reported, verbatim. Show it — it is often exact. */
-    message: string;
-    /** What the person should actually do about it. */
-    hint: string;
-};
-interface EnableMicrophoneOptions {
-    /**
-     * How long to wait before calling it a no-answer. Default 15s.
-     *
-     * This is not belt-and-braces. Per the getUserMedia specification a prompt the user never
-     * dismisses may leave the promise permanently pending — "neither resolve nor reject" — and
-     * a page that awaits it in its connect path hangs on a state that has no error and no end.
-     * A deadline turns that into a reportable outcome.
-     */
-    timeoutMs?: number;
-}
-/**
- * Publish the caller's microphone, and report WHY if it does not start.
- *
- * ```ts
- * const mic = await enableMicrophone(room);
- * if (!mic.ok) {
- *   status.textContent = `Microphone: ${mic.message}`;
- *   help.textContent = mic.hint;          // the sentence that names the fix
- * }
- * ```
- *
- * Never throws. A call that cannot start the microphone is an ordinary outcome of asking a
- * person for a device, not a programmer error, so it belongs in the return type.
- *
- * Note it does NOT hang up on failure — the call is still live and still billing, and only
- * the caller knows whether a text-only session is useful to them. If it is not, disconnect
- * in the `!ok` branch; leaving a room connected against a device the user never granted is
- * how the retry ends up contending with the call that is still holding it.
- */
-declare function enableMicrophone(room: MicrophoneCapableRoom, options?: EnableMicrophoneOptions): Promise<MicrophoneResult>;
-
 /**
  * Making the character AUDIBLE — the half of "audio works" that has nothing to do with the
  * microphone.
@@ -251,4 +166,4 @@ type BoomerangPlayback = {
  */
 declare function attachBoomerangPlayback(video: HTMLVideoElement, options?: BoomerangPlaybackOptions): BoomerangPlayback;
 
-export { type AttachRemoteAudioOptions, type AttachableTrack, type AudioCapableRoom, type BoomerangPlayback, type BoomerangPlaybackOptions, type EnableMicrophoneOptions, type MicrophoneCapableRoom, type MicrophoneFailureReason, type MicrophoneResult, type PreparableParticipant, type PreparableRoom, type PrepareAvatarRoomOptions, type PreparedAvatarRoom, type RemoteAudioAttachment, type VideoSupport, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, enableMicrophone, prepareAvatarRoom };
+export { type AttachRemoteAudioOptions, type AttachableTrack, type AudioCapableRoom, type BoomerangPlayback, type BoomerangPlaybackOptions, type PreparableParticipant, type PreparableRoom, type PrepareAvatarRoomOptions, type PreparedAvatarRoom, type RemoteAudioAttachment, type VideoSupport, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, prepareAvatarRoom };

package/dist/browser.js

@@ -18,6 +18,7 @@ var HINTS = {
   "denied-by-os": "The operating system is blocking the browser itself, so no site can record. On macOS: System Settings > Privacy & Security > Microphone, enable your browser, then RESTART it \u2014 the change does not apply to a running browser.",
   "no-device": "No microphone is available. Connect one, and if you are on Bluetooth headphones check they are in a mode that has a microphone.",
   "device-in-use": "Another application or browser tab is holding the microphone. Close it \u2014 including any call from this page you did not hang up \u2014 and try again.",
+  "device-lost": "The microphone stopped during the call: it was unplugged, or access to it was turned off. Reconnect it or allow access again, then turn the microphone back on.",
   unknown: "Try again, and if it persists include the message above in your report."
 };
 function isOperatingSystemDenial(message) {
@@ -54,6 +55,10 @@ function classify(error) {
 function fail(reason, message) {
   return { ok: false, reason, message, hint: HINTS[reason] };
 }
+function describeMicrophoneFailure(error) {
+  const { reason, message } = classify(error);
+  return { reason, message, hint: HINTS[reason] };
+}
 async function enableMicrophone(room, options = {}) {
   const timeoutMs = options.timeoutMs ?? 15e3;
   if (typeof navigator === "undefined" || !navigator.mediaDevices) {
@@ -253,4 +258,4 @@ function now() {
   return typeof performance !== "undefined" ? performance.now() : Date.now();
 }
 
-export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, applyAvatarPlayoutDelay, applyPlayoutDelay, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, enableMicrophone, prepareAvatarRoom };
+export { DEFAULT_AVATAR_PLAYOUT_DELAY_SECONDS, applyAvatarPlayoutDelay, applyPlayoutDelay, attachBoomerangPlayback, attachRemoteAudio, checkVideoSupport, describeMicrophoneFailure, enableMicrophone, prepareAvatarRoom };

package/dist/{chunk-EODL5S3A.js → chunk-HMESE54B.js}

@@ -8,11 +8,16 @@ var RealtimeAvatarError = class extends Error {
     this.name = "RealtimeAvatarError";
   }
 };
+function isRequestId(value) {
+  return typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value);
+}
 var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
   status;
   code;
   body;
   requestId;
+  /** The platform's own verdict on retrying as-is, when its body gave one. */
+  retryable;
   concurrency;
   constructor(status, code, body, requestId) {
     const bounded = body.slice(0, 400);
@@ -27,8 +32,8 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
       if (value && typeof value === "object" && !Array.isArray(value)) parsed = value;
     } catch {
     }
-    const validId = (value) => typeof value === "string" && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value);
-    this.requestId = validId(parsed.requestId) ? parsed.requestId : validId(requestId) ? requestId : void 0;
+    this.requestId = isRequestId(parsed.requestId) ? parsed.requestId : isRequestId(requestId) ? requestId : void 0;
+    if (typeof parsed.retryable === "boolean") this.retryable = parsed.retryable;
     if (status === 429 && code === "concurrency_limit_reached") {
       this.concurrency = {};
       for (const key of ["maxConcurrentSessions", "liveSessions", "activeSessions", "connectingSessions", "pendingSessions"]) {
@@ -293,6 +298,12 @@ function backoffMs(attempt, retryAfter) {
   return Math.random() * Math.min(500 * 2 ** attempt, 8e3);
 }
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var PROXY_CLIENT_TIMEOUT_MS = 6e4;
+var ROUTE_TIMEOUT_MS = PROXY_CLIENT_TIMEOUT_MS - 1e4;
+function retryFits(attemptStartedAt, waitMs, deadline) {
+  const now = Date.now();
+  return now + waitMs + (now - attemptStartedAt) <= deadline;
+}
 function isTransient(cause) {
   const name = cause?.name;
   return name === "TimeoutError" || name === "TypeError" || name === "FetchError";
@@ -643,7 +654,7 @@ z.object({
   queue_position: z.number().int().positive().optional(),
   recommended_retry_ms: z.number().int().nonnegative()
 }).strict();
-z.enum([
+var liveKitSessionReleaseReasonSchema = z.enum([
   "page_hide",
   "disconnected",
   "superseded",
@@ -654,12 +665,13 @@ z.enum([
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.24.1";
+var SDK_VERSION = "0.26.0";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
   #fetch;
   #timeoutMs;
+  #totalTimeoutMs;
   #maxRetries;
   #userAgent;
   constructor(options) {
@@ -673,6 +685,7 @@ var RealtimeAvatar = class {
     this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
     this.#timeoutMs = options.timeoutMs ?? 6e4;
+    this.#totalTimeoutMs = options.totalTimeoutMs;
     this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
   }
@@ -764,7 +777,25 @@ var RealtimeAvatar = class {
    */
   async endCall(sessionId, options = {}) {
     if (!sessionId) return false;
-    const body = { session_id: sessionId };
+    return this.#release({ session_id: sessionId }, options);
+  }
+  /**
+   * Give up a QUEUED call's place in line, by the `queueTicketId` that `startCall` returned.
+   *
+   * A queued call has no session yet, so {@link endCall} cannot reach it: the release contract
+   * carries the ticket in its own field, and a ticket sent as a session id names nothing and is
+   * acknowledged as an idempotent no-op. The place is then held until its TTL, at the front of
+   * the queue, in front of everyone behind it.
+   *
+   * Same contract as `endCall`: best-effort, `true` only when the platform acknowledged it,
+   * never a throw, and only for tickets YOUR SERVER was handed.
+   */
+  async leaveQueue(queueTicketId, options = {}) {
+    if (!queueTicketId) return false;
+    return this.#release({ queue_ticket_id: queueTicketId }, options);
+  }
+  async #release(target, options) {
+    const body = { ...target };
     if (options.reason !== void 0) body.reason = options.reason;
     if (options.capacityPool !== void 0) body.capacity_pool = options.capacityPool;
     try {
@@ -1099,24 +1130,29 @@ var RealtimeAvatar = class {
       body = JSON.stringify(init.json);
     }
     if (MUTATING.has(method)) headers["idempotency-key"] = newIdempotencyKey();
+    const deadline = this.#totalTimeoutMs === void 0 ? Infinity : Date.now() + this.#totalTimeoutMs;
     let lastError;
     for (let attempt = 0; ; attempt++) {
+      const startedAt = Date.now();
       try {
-        const signal = AbortSignal.timeout(this.#timeoutMs);
+        const signal = AbortSignal.timeout(Math.max(0, Math.min(this.#timeoutMs, deadline - startedAt)));
         const response = await this.#fetch(`${this.#baseUrl}${path}`, { method, headers, body, signal });
         if (attempt >= this.#maxRetries || !RETRYABLE_STATUS.has(response.status)) return response;
+        const wait = backoffMs(attempt, response.headers.get("retry-after"));
+        if (!retryFits(startedAt, wait, deadline)) return response;
         await response.body?.cancel().catch(() => {
         });
-        await sleep(backoffMs(attempt, response.headers.get("retry-after")));
+        await sleep(wait);
       } catch (cause) {
         lastError = cause;
-        if (attempt >= this.#maxRetries || !isTransient(cause) || isStream(body)) {
+        const wait = backoffMs(attempt, null);
+        if (attempt >= this.#maxRetries || !isTransient(cause) || isStream(body) || !retryFits(startedAt, wait, deadline)) {
           throw new RealtimeAvatarError(
             `${method} ${path} failed after ${attempt + 1} attempt(s): ${cause.message}`,
             { cause: lastError }
           );
         }
-        await sleep(backoffMs(attempt, null));
+        await sleep(wait);
       }
     }
   }
@@ -1263,4 +1299,4 @@ function isQueued(result) {
   return "queued" in result;
 }
 
-export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, verifyTranscript };
+export { ROUTE_TIMEOUT_MS, RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, clipLibraryDeclarationSchema, isQueued, listRecordingsResponseSchema, liveKitSessionReleaseReasonSchema, recordingAccessResponseSchema, recordingArtifactSchema, recordingModeSchema, sessionModeSchema, verifyTranscript };

package/dist/chunk-XJPGQMEW.js

@@ -0,0 +1,161 @@
+import { sessionModeSchema, liveKitSessionReleaseReasonSchema, RealtimeAvatar, ROUTE_TIMEOUT_MS, isQueued, RealtimeAvatarHttpError, RealtimeAvatarError } from './chunk-HMESE54B.js';
+import { z } from 'zod';
+
+// ../http-client/src/generated/error-semantics.ts
+var ERROR_SEMANTICS = {
+  "bad_request": { statuses: [400], message: "Check the request and try again.", retryable: false },
+  "unauthorized": { statuses: [401], message: "Authentication is required to use Realtime Avatar.", retryable: false },
+  "payment_required": { statuses: [402], message: "Add credits to continue using realtime avatars.", retryable: false },
+  "forbidden": { statuses: [403], message: "This API key does not have access to that action.", retryable: false },
+  "not_found": { statuses: [404], message: "We could not find that avatar or resource.", retryable: false },
+  "method_not_allowed": { statuses: [405], message: "This request method is not supported.", retryable: false },
+  "not_acceptable": { statuses: [406], message: "The requested response format is not supported.", retryable: false },
+  "request_aborted": { statuses: [408], message: "The session request was cancelled.", retryable: false },
+  "conflict": { statuses: [409], message: "That request is already in progress. Try again in a moment.", retryable: true },
+  "length_required": { statuses: [411], message: "A request content length is required.", retryable: false },
+  "payload_too_large": { statuses: [413], message: "The request is too large.", retryable: false },
+  "unprocessable_entity": { statuses: [422], message: "Check the request and try again.", retryable: false },
+  "rate_limited": { statuses: [429], message: "Too many realtime requests. Please slow down and retry.", retryable: true },
+  "internal_error": { statuses: [500], message: "The session service encountered an error. Try again.", retryable: true },
+  "unavailable": { statuses: [503], message: "Realtime Avatar is temporarily unavailable. Try again in a moment.", retryable: true },
+  "insufficient_scope": { statuses: [403], message: "This API key is missing a required permission.", retryable: false },
+  "loop_pending": { statuses: [409], message: "An avatar loop update is still in progress. Try again shortly.", retryable: true },
+  "rate_limit_exceeded": { statuses: [429], message: "Too many realtime requests. Please slow down and retry.", retryable: true },
+  "upstream_failed": { statuses: [500, 502, 503], message: "The session service could not complete the request. Try again.", retryable: true },
+  "upstream_unreachable": { statuses: [502, 503], message: "The session service could not be reached. Try again.", retryable: true },
+  "invalid_upstream_response": { statuses: [502], message: "The session service returned an invalid response. Try again.", retryable: true },
+  "upstream_timeout": { statuses: [504], message: "The session service took too long to respond. Try again.", retryable: true },
+  "capacity_unavailable": { statuses: [503], message: "Session availability could not be checked. Try again.", retryable: true },
+  "session_dispatch_failed": { statuses: [503], message: "The avatar session could not be started. Try again.", retryable: true },
+  "admission_unavailable": { statuses: [503], message: "Session admission is temporarily unavailable. Try again.", retryable: true },
+  "service_warming": { statuses: [503], message: "Realtime Avatar is warming up. Try again in a moment.", retryable: true },
+  "avatar_not_ready": { statuses: [409], message: "This avatar is still being built \u2014 it is usually ready within a minute. Try again then.", retryable: true },
+  "clip_library_not_ready": { statuses: [409], message: "This avatar's motion clips are still rendering. Try again in a minute.", retryable: true },
+  "recording_unsupported": { statuses: [501], message: "Session recording is not enabled for this deployment.", retryable: false },
+  "recording_requires_new_room": { statuses: [422], message: "Recording requires a new session room. Start a fresh session to record it.", retryable: false },
+  "recording_unavailable": { statuses: [503], message: "Session recording is temporarily unavailable. Try again in a moment.", retryable: true }
+};
+var MESSAGE_SHAPE_PATTERNS = { "machine": { "source": "[_=<>{}\\[\\]|\\\\$`]|\\w+\\.\\w+\\.\\w|\\S:\\d|\\w\\(\\)|^\\s*(?:at|File)\\b|\\bTraceback \\(most recent call last\\)", "flags": "mu" }, "locator": { "source": "https?://|/[\\w.-]+/|[\\w.+-]+@[\\w.-]+\\.[a-z]{2,}|\\bbearer\\s|[\\r\\n]", "flags": "i" } };
+Object.values(MESSAGE_SHAPE_PATTERNS).map(
+  (pattern) => new RegExp(pattern.source, pattern.flags)
+);
+var proxyConnectRequestSchema = z.object({
+  avatarId: z.string().min(1),
+  mode: sessionModeSchema.optional()
+});
+var proxyEndRequestSchema = z.object({
+  session_id: z.string().min(1).optional(),
+  queue_ticket_id: z.string().min(1).optional(),
+  reason: liveKitSessionReleaseReasonSchema.optional().catch(void 0)
+}).strict().refine((body) => body.session_id !== void 0 || body.queue_ticket_id !== void 0, {
+  message: "session_id or queue_ticket_id is required"
+});
+
+// ../proxy/src/config.ts
+var MISCONFIGURED = "internal_error";
+var TIMED_OUT = "upstream_timeout";
+var json = (body, status = 200) => new Response(JSON.stringify(body), {
+  status,
+  headers: { "content-type": "application/json", "cache-control": "no-store" }
+});
+function relayFailure(operation, error) {
+  const misconfigured = error.status === 401 || error.status === 403;
+  const status = misconfigured ? ERROR_SEMANTICS[MISCONFIGURED].statuses[0] : error.status;
+  const verdict = error.retryable === void 0 ? {} : { retryable: error.retryable };
+  const body = misconfigured ? { code: MISCONFIGURED, status, retryable: false } : error.status === 429 ? throttled(error) : { code: error.isBilling ? error.code ?? "insufficient_credits" : error.code, status, ...verdict };
+  console.error(
+    `realtime-avatar: platform answered ${operation} with ${error.status} (code ${error.code ?? "none"}, requestId ${error.requestId ?? "none"}); relayed as ${status}` + (misconfigured ? " \u2014 the platform refused this route's API key" : "")
+  );
+  const response = json({ ...body, ...error.requestId ? { requestId: error.requestId } : {} }, status);
+  if (error.requestId) response.headers.set("X-Request-ID", error.requestId);
+  return response;
+}
+function timedOut(operation) {
+  const { retryable, statuses: [status] } = ERROR_SEMANTICS[TIMED_OUT];
+  console.error(`realtime-avatar: platform did not answer ${operation} inside the route's budget; answered ${status}`);
+  return json({ code: TIMED_OUT, status, retryable }, status);
+}
+function throttled(error) {
+  const concurrency = error.code === "concurrency_limit_reached";
+  const counts = error.concurrency;
+  const message = concurrency ? counts?.maxConcurrentSessions !== void 0 && counts.activeSessions !== void 0 && counts.connectingSessions !== void 0 && counts.pendingSessions !== void 0 ? `Session limit reached (${counts.maxConcurrentSessions} allowed): ${counts.activeSessions} active, ${counts.connectingSessions} connecting, ${counts.pendingSessions} starting. End a session or wait for pending starts to clear, then retry.` : "The concurrent session limit is reached. Active and starting sessions count. End a session or wait for pending starts to clear, then retry." : "Too many requests. Wait before retrying.";
+  return {
+    error: message,
+    code: concurrency ? "concurrency_limit_reached" : "rate_limited",
+    status: 429,
+    retryable: error.retryable ?? true,
+    ...concurrency ? counts : {}
+  };
+}
+function operationFor(pathname, method) {
+  const tail = pathname.replace(/\/+$/, "").split("/").pop() ?? "";
+  if (method === "POST" && (tail === "connect" || tail === "call")) return "connect";
+  if (method === "POST" && (tail === "end" || tail === "release")) return "end";
+  if (method === "GET" && tail === "avatars") return "avatars";
+  if (method === "GET" && tail === "credits") return "credits";
+  return null;
+}
+function createProxyHandler(config) {
+  const minted = /* @__PURE__ */ new Map();
+  const MINTED_TTL_MS = 30 * 6e4;
+  return async (request) => {
+    const url = new URL(request.url);
+    const operation = operationFor(url.pathname, request.method);
+    if (!operation) return json({ error: "not found" }, 404);
+    const refusal = await config.authorize?.({ request, operation });
+    if (refusal instanceof Response) return refusal;
+    const apiKey = typeof config.apiKey === "function" ? await config.apiKey() : config.apiKey;
+    const rta = new RealtimeAvatar({ apiKey, baseUrl: config.baseUrl, totalTimeoutMs: config.timeoutMs ?? ROUTE_TIMEOUT_MS });
+    try {
+      if (operation === "avatars") return json({ data: await rta.listAvatars() });
+      if (operation === "credits") return json(await rta.creditBalance());
+      const raw = await request.json().catch(() => void 0);
+      if (operation === "end") {
+        const parsed2 = proxyEndRequestSchema.safeParse(raw);
+        if (!parsed2.success) return json({ error: "session_id or queue_ticket_id is required" }, 422);
+        const ended = parsed2.data;
+        const reason = ended.reason === "page_hide" || ended.reason === "unmount" ? ended.reason : "manual";
+        const owned = async (id) => config.ownsSession ? await config.ownsSession({ request, sessionId: id }) : minted.delete(id);
+        if (ended.session_id !== void 0 && await owned(ended.session_id)) {
+          await rta.endCall(ended.session_id, { reason });
+        }
+        if (ended.queue_ticket_id !== void 0 && await owned(ended.queue_ticket_id)) {
+          await rta.leaveQueue(ended.queue_ticket_id, { reason });
+        }
+        return new Response(null, { status: 204 });
+      }
+      const parsed = proxyConnectRequestSchema.safeParse(raw);
+      if (!parsed.success) return json({ error: "avatarId is required" }, 422);
+      const body = parsed.data;
+      const mode = body.mode ?? "avatar";
+      const decided = await config.session?.({ request, avatarId: body.avatarId, mode });
+      if (decided instanceof Response) return decided;
+      const call = await rta.startCall({ avatarId: body.avatarId, mode, ...decided ?? {} });
+      if (isQueued(call)) {
+        if (call.queueTicketId) minted.set(call.queueTicketId, Date.now());
+        return json(
+          {
+            queued: true,
+            position: call.position,
+            size: call.size,
+            retryAfterMs: call.retryAfterMs,
+            queue_ticket_id: call.queueTicketId
+          },
+          429
+        );
+      }
+      const now = Date.now();
+      for (const [id, at] of minted) if (now - at > MINTED_TTL_MS) minted.delete(id);
+      minted.set(call.sessionId, now);
+      return json(call.raw);
+    } catch (error) {
+      if (error instanceof RealtimeAvatarHttpError) return relayFailure(operation, error);
+      if (error instanceof RealtimeAvatarError && error.cause instanceof Error && error.cause.name === "TimeoutError") {
+        return timedOut(operation);
+      }
+      throw error;
+    }
+  };
+}
+
+export { createProxyHandler };

package/dist/express.d.ts

@@ -1,4 +1,4 @@
-import { P as ProxyConfig } from './types-CpqMHna3.js';
+import { P as ProxyConfig } from './types-C7B7jOx6.js';
 import './types-D77jgSms.js';
 import 'zod';
 

package/dist/express.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-4PWWEERK.js';
-import './chunk-EODL5S3A.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/express.ts
@@ -16,7 +16,9 @@ function realtimeAvatarExpress(config) {
       body: req.method === "GET" ? void 0 : JSON.stringify(req.body ?? {})
     });
     const response = await handler(request);
-    res.status(response.status).set("content-type", "application/json").send(await response.text());
+    res.status(response.status).set("content-type", "application/json");
+    response.headers.forEach((value, field) => res.set(field, value));
+    res.send(await response.text());
   };
 }
 

package/dist/hono.d.ts

@@ -1,4 +1,4 @@
-import { P as ProxyConfig } from './types-CpqMHna3.js';
+import { P as ProxyConfig } from './types-C7B7jOx6.js';
 import './types-D77jgSms.js';
 import 'zod';
 

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-4PWWEERK.js';
-import './chunk-EODL5S3A.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/hono.ts

package/dist/index.d.ts

@@ -8,8 +8,17 @@ interface RealtimeAvatarOptions {
     apiKey: string;
     baseUrl?: string;
     fetch?: typeof fetch;
-    /** Per-request timeout. Default 60s; starting a call does real work upstream. */
+    /** Per-attempt timeout. Default 60s; starting a call does real work upstream. */
     timeoutMs?: number;
+    /**
+     * The whole request: every attempt and the backoff between them. Default unbounded, so the
+     * worst case is `timeoutMs` per attempt plus up to 20s of `Retry-After` between them.
+     *
+     * Set it when something else is waiting on this request with a deadline of its own (a
+     * browser, a serverless max duration). An attempt is cut off at the budget, and a retry is
+     * started only if it can take as long as the attempt before it and still finish inside it.
+     */
+    totalTimeoutMs?: number;
     /**
      * Extra attempts after a transient failure. Default 2, so 3 attempts in total.
      *
@@ -73,6 +82,18 @@ declare class RealtimeAvatar {
      * request body lets any visitor hang up any call on your account.
      */
     endCall(sessionId: string, options?: EndCallOptions): Promise<boolean>;
+    /**
+     * Give up a QUEUED call's place in line, by the `queueTicketId` that `startCall` returned.
+     *
+     * A queued call has no session yet, so {@link endCall} cannot reach it: the release contract
+     * carries the ticket in its own field, and a ticket sent as a session id names nothing and is
+     * acknowledged as an idempotent no-op. The place is then held until its TTL, at the front of
+     * the queue, in front of everyone behind it.
+     *
+     * Same contract as `endCall`: best-effort, `true` only when the platform acknowledged it,
+     * never a throw, and only for tickets YOUR SERVER was handed.
+     */
+    leaveQueue(queueTicketId: string, options?: Pick<EndCallOptions, "reason">): Promise<boolean>;
     /**
      * Register a character from a looping clip you host.
      *
@@ -319,6 +340,8 @@ declare class RealtimeAvatarHttpError extends RealtimeAvatarError {
     readonly code: string | undefined;
     readonly body: string;
     readonly requestId?: string;
+    /** The platform's own verdict on retrying as-is, when its body gave one. */
+    readonly retryable?: boolean;
     readonly concurrency?: Partial<Record<"maxConcurrentSessions" | "liveSessions" | "activeSessions" | "connectingSessions" | "pendingSessions", number>>;
     constructor(status: number, code: string | undefined, body: string, requestId?: string);
     /** Out of credits, or over this key's spend limit. Surface a paywall, not an error. */

package/dist/index.js

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

package/dist/nextjs.d.ts

@@ -1,4 +1,4 @@
-import { P as ProxyConfig } from './types-CpqMHna3.js';
+import { P as ProxyConfig } from './types-C7B7jOx6.js';
 import './types-D77jgSms.js';
 import 'zod';
 

package/dist/nextjs.js

@@ -1,5 +1,5 @@
-import { createProxyHandler } from './chunk-4PWWEERK.js';
-import './chunk-EODL5S3A.js';
+import { createProxyHandler } from './chunk-XJPGQMEW.js';
+import './chunk-HMESE54B.js';
 import './chunk-MCIXU6XP.js';
 
 // ../proxy/src/nextjs.ts