realtime-avatar 0.5.2 → 0.5.4

package/dist/chunk-I3BFZHMQ.js

@@ -0,0 +1,678 @@
+// ../http-client/src/errors.ts
+var RealtimeAvatarError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "RealtimeAvatarError";
+  }
+};
+var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
+  status;
+  code;
+  body;
+  constructor(status, code, body) {
+    super(`Realtime Avatar API ${status}${code ? ` (${code})` : ""}: ${body || "no body"}`);
+    this.name = "RealtimeAvatarHttpError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+  }
+  /** Out of credits, or over this key's spend limit. Surface a paywall, not an error. */
+  get isBilling() {
+    return this.status === 402;
+  }
+};
+
+// ../http-client/src/retry.ts
+var RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 500, 502, 503, 504]);
+var MUTATING = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+function newIdempotencyKey() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+}
+function backoffMs(attempt, retryAfter) {
+  const server = retryAfter ? Number(retryAfter) * 1e3 : NaN;
+  if (Number.isFinite(server) && server >= 0) return Math.min(server, 2e4);
+  return Math.random() * Math.min(500 * 2 ** attempt, 8e3);
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function isTransient(cause) {
+  const name = cause?.name;
+  return name === "TimeoutError" || name === "TypeError" || name === "FetchError";
+}
+
+// ../http-client/src/client.ts
+var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
+var SDK_VERSION = "0.5.4";
+var RealtimeAvatar = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  #timeoutMs;
+  #maxRetries;
+  #userAgent;
+  constructor(options) {
+    if (typeof document !== "undefined") {
+      throw new RealtimeAvatarError(
+        "RealtimeAvatar is server-only \u2014 it holds your API key. Call it from your backend and hand the browser only the connection payload it returns."
+      );
+    }
+    if (!options.apiKey) throw new RealtimeAvatarError("apiKey is required");
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    this.#timeoutMs = options.timeoutMs ?? 6e4;
+    this.#maxRetries = Math.max(0, options.maxRetries ?? 2);
+    this.#userAgent = [`realtime-avatar-sdk/${SDK_VERSION}`, runtimeTag(), options.userAgent].filter(Boolean).join(" ");
+  }
+  // ── calls ────────────────────────────────────────────────────────────────
+  /**
+   * Start a call and get back what the client needs to join.
+   *
+   * Returns `{ queued: true, … }` when every slot is busy — that is a normal state, not a
+   * failure. Render the position and retry after `retryAfterMs`.
+   *
+   * Everything in `options` beyond `avatarId`/`mode` is a POLICY: it is what your server has
+   * decided about this call. Never populate it from a request body.
+   */
+  async startCall(options) {
+    const body = {
+      avatar_id: options.avatarId,
+      mode: options.mode ?? "avatar",
+      stt_mode: options.listen === false ? "off" : "server"
+    };
+    if (options.instructions !== void 0) body.instructions = options.instructions;
+    if (options.context !== void 0) {
+      body.initial_context = options.context.map((m) => ({ role: m.role, content: m.content }));
+    }
+    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.clientTools) body.capabilities = ["client_tools"];
+    if (options.transcript !== void 0) {
+      body.transcript_webhook = { url: options.transcript.url, secret: options.transcript.secret };
+    }
+    if (options.video !== void 0) Object.assign(body, videoToWire(options.video));
+    const response = await this.#request("POST", "/realtime/livekit/session", { json: body });
+    if (response.status === 429) {
+      const busy = await response.json();
+      return {
+        queued: true,
+        position: typeof busy.queue_position === "number" ? busy.queue_position : null,
+        size: typeof busy.queue_size === "number" ? busy.queue_size : 0,
+        retryAfterMs: typeof busy.recommended_retry_ms === "number" ? busy.recommended_retry_ms : 3e3,
+        queueTicketId: typeof busy.queue_ticket_id === "string" ? busy.queue_ticket_id : null
+      };
+    }
+    const grant = await this.#json(response);
+    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),
+      // 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
+    };
+  }
+  /**
+   * End a call and free its slot NOW, instead of when a timeout notices.
+   *
+   * The slot is held from the moment `startCall` returns — **including the window before
+   * your user has joined the room**. Someone who closes the tab right there leaves the call
+   * running until the join timeout reclaims it. Give the page a same-origin route that calls
+   * this, hit it with `navigator.sendBeacon` on `pagehide`, and the abandoned call ends the
+   * moment they leave. The demo apps carry the whole pattern.
+   *
+   * Best-effort, like the hang-up it is: `true` when the platform acknowledged the release,
+   * `false` for anything else — never a throw. Ending is idempotent (an unknown or
+   * already-ended session still acks), so a pagehide beacon and a disconnect handler may
+   * both fire for the same call without error. A release that is lost is a slower release,
+   * not a leak — the join timeout is the backstop.
+   *
+   * This ends whatever the id names, so only pass ids YOUR SERVER minted — remember them at
+   * `startCall` time and refuse the rest. A route that relays an arbitrary id from the
+   * request body lets any visitor hang up any call on your account.
+   */
+  async endCall(sessionId, options = {}) {
+    if (!sessionId) return false;
+    const body = { session_id: sessionId };
+    if (options.reason !== void 0) body.reason = options.reason;
+    if (options.capacityPool !== void 0) body.capacity_pool = options.capacityPool;
+    try {
+      const response = await this.#request("POST", "/realtime/livekit/session/release", { json: body });
+      await response.body?.cancel().catch(() => {
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  // ── avatars ──────────────────────────────────────────────────────────────
+  /**
+   * Register a character from a looping clip you host.
+   *
+   * @deprecated CLOSED to new callers — this answers `422` unless your tenant was already
+   * creating from video, in which case it keeps working and your existing avatars are
+   * untouched. Use {@link createAvatarFromImage}: one still, and the platform renders the
+   * resting loop and the motion library from it.
+   *
+   * The reason it closed is not arbitrary. Every clip has to start and end on ONE rest pose
+   * or a state switch reads as a jump, and the platform can only guarantee that when it
+   * rendered the loop and the clips from the same portrait. A supplied video cannot honour
+   * it, so the lane could never be made to look right.
+   */
+  async createAvatarFromVideo(input) {
+    const asset = await this.createRemoteAsset({ kind: "video", remoteUrl: input.videoUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "video",
+      sourceAssetId: asset.id,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
+  /**
+   * Register a character from ONE still image. The platform generates everything moving:
+   * the resting loop she idles in, then a starter motion library rendered against her rest
+   * pose. No footage, no clip URLs, nothing to shoot.
+   *
+   * `motionPrompt` directs the RESTING LOOP — the video she plays when nothing else is
+   * happening — and it is the only chance to direct it, because there is no API today that
+   * re-generates a loop after creation (see {@link updateAvatar} for the one thing that can
+   * be re-pointed). Describe a small closed arc that returns to where it started: "settles
+   * into frame, breathes gently, a slow blink". Omit it and the house default is used.
+   *
+   * Creation returns while the avatar is still `preprocessing`; poll {@link getAvatar} until
+   * it leaves that state. The loop is load-bearing, so a failure there settles `failed` with
+   * a readable error — the motion library is not, and a library failure degrades to
+   * loop-only rather than demoting the character.
+   */
+  async createAvatarFromImage(input) {
+    const asset = await this.createRemoteAsset({ kind: "image", remoteUrl: input.imageUrl });
+    return this.createAvatar({
+      displayName: input.displayName,
+      sourceKind: "image",
+      sourceAssetId: asset.id,
+      motionPrompt: input.motionPrompt,
+      voice: input.voice,
+      settings: input.settings,
+      metadata: input.metadata
+    });
+  }
+  async createAvatar(input) {
+    const body = {
+      displayName: input.displayName,
+      sourceKind: input.sourceKind,
+      sourceAssetId: input.sourceAssetId
+    };
+    if (input.motionPrompt !== void 0) body.motionPrompt = input.motionPrompt;
+    if (input.voice !== void 0) body.voice = input.voice;
+    if (input.settings !== void 0) body.settings = input.settings;
+    if (input.metadata !== void 0) body.metadata = input.metadata;
+    return toAvatar(await this.#json(await this.#request("POST", "/avatars", { json: body })));
+  }
+  async listAvatars() {
+    const data = await this.#json(await this.#request("GET", "/avatars"));
+    return (data.data ?? []).map(toAvatar);
+  }
+  async getAvatar(avatarId) {
+    return toAvatar(await this.#json(await this.#request("GET", `/avatars/${avatarId}`)));
+  }
+  /**
+   * Re-point what an avatar already is. `defaultVoiceId: null` clears the default voice.
+   *
+   * Cheap metadata only. The three things that cost a render have their own methods, because
+   * putting them in a patch alongside a rename would hide minutes of GPU work behind a field:
+   * {@link retimeAnchor} moves the rest frame, {@link swapSource} replaces the footage, and
+   * the resting loop is re-directed by description at `PUT /v1/avatars/{id}/loop`.
+   */
+  async updateAvatar(avatarId, patch) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
+    );
+  }
+  /**
+   * Re-shoot the character — swap in new footage as her resting loop.
+   *
+   * ASYNCHRONOUS, and that is the whole design. This returns as soon as the swap is
+   * accepted; the avatar keeps serving its CURRENT loop, cache and clips the entire time,
+   * and cuts over to the new generation in one step once the replacement is prepared.
+   * A call minted a second after this returns is a normal call on the old footage.
+   *
+   * Two consequences worth designing for:
+   *
+   * - **The clip library empties and refills.** Old takes are footage of the old source and
+   *   cannot splice against the new loop, so they are dropped and re-rendered. Between the
+   *   cutover and the last re-render she rests on the new loop with less variety — never
+   *   broken, just plainer. Do not gate your UI on the library being full.
+   * - **A failed swap does not fail the avatar.** She keeps serving, `status` stays `ready`,
+   *   and the reason lands on `error`. So poll `getAvatar` and read `error` — a non-null
+   *   `error` on a `ready` avatar is the swap that did not take, not an unhealthy character.
+   *
+   * The frame this rests on comes from the new footage: pass `anchorTimeMs` when frame 0 of
+   * the take is mid-blink. Video-sourced avatars only — a portrait-anchored one is a 422.
+   */
+  async swapSource(avatarId, input) {
+    const json = { sourceAssetId: input.sourceAssetId };
+    if (input.anchorTimeMs !== void 0) json.anchorTimeMs = input.anchorTimeMs;
+    return toAvatar(await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json })));
+  }
+  /**
+   * Re-point the anchor at a different frame of the loop she ALREADY has — same footage,
+   * different rest pose. `swapSource` replaces the footage; this only moves the frame.
+   *
+   * Re-renders the clip library the same way, with the same degradation window, and is
+   * clamped server-side to the loop's last extractable frame (read the avatar back to see
+   * what was actually cut). Video-sourced avatars only.
+   */
+  async retimeAnchor(avatarId, anchorTimeMs) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: { anchorTimeMs } }))
+    );
+  }
+  async deleteAvatar(avatarId) {
+    await this.#json(await this.#request("DELETE", `/avatars/${avatarId}`));
+  }
+  // A clip envelope missing `revision` would silently drop `expectedRevision` from the
+  // next declare — CAS degrades to unconditional with zero signal — so it throws instead.
+  #clipEnvelope(out) {
+    if (typeof out.revision !== "number" || !Array.isArray(out.data)) {
+      throw new RealtimeAvatarError("clip library response did not match the contract");
+    }
+    return out;
+  }
+  /**
+   * Declare the avatar's full desired clip library — a declaration, not a delta. The
+   * platform reconciles it against what exists: unchanged clips are `kept` (still
+   * serving), new or changed ones are `queued` to render, and clips you dropped are
+   * `retired`. The 202 is acceptance, not readiness — poll `listClips` until no row is
+   * `queued` or `generating`. A rejected upload settles `failed`, which is terminal, so
+   * waiting for all-`ready` waits forever. While a re-render is in flight the previous
+   * take keeps serving, so a declaration never blanks a live avatar.
+   *
+   * `expectedRevision` is compare-and-set: pass the `revision` you last read and a
+   * concurrent writer surfaces as a 409 instead of a lost update. Omit it to declare
+   * unconditionally.
+   *
+   * At most 12 clips: one `idle`, up to two `listen`, the rest `gesture`. An uploaded
+   * clip (`source: { assetId }`) must start AND end on the avatar's rest pose — pose
+   * validation rejects it otherwise (`status: "failed"`, the verdict in `poseCheck`),
+   * and the rest of the library is untouched.
+   */
+  async setClipLibrary(avatarId, library) {
+    const body = { clips: library.clips };
+    if (library.expectedRevision !== void 0) body.expectedRevision = library.expectedRevision;
+    return this.#clipEnvelope(
+      await this.#json(
+        await this.#request("PUT", `/avatars/${avatarId}/clips`, { json: body })
+      )
+    );
+  }
+  /**
+   * Re-direct the RESTING LOOP — the video she plays when nothing else is happening — from
+   * a new one-sentence description.
+   *
+   * Not a clip, and this is the distinction integrations get wrong: a clip with
+   * `role: "idle"` is a variant spliced OVER the loop, and declaring one never changes what
+   * she rests in. This is the only thing that does.
+   *
+   * `202`, because the render takes minutes. Three properties, all measured against a real
+   * render rather than asserted:
+   *
+   * - **She never goes dark.** She stays `ready` and keeps serving her previous loop for the
+   *   entire render — returned as `servingUrl` — then the swap publishes in one step.
+   * - **Your clip library is untouched.** Clips render against the portrait, not against the
+   *   loop, so a re-direct re-queues nothing and does not move `revision`.
+   * - **It bills once**, at the rendering model's rate, per re-direct.
+   *
+   * Refusals worth telling apart: `409 loop_pending` (one is already in flight — wait) and
+   * `422 loop_not_generatable` (a grandfathered video-sourced avatar has no portrait to
+   * re-animate — terminal, do not retry).
+   */
+  async setLoop(avatarId, loop) {
+    return await this.#json(
+      await this.#request("PUT", `/avatars/${avatarId}/loop`, { json: { motionPrompt: loop.motionPrompt } })
+    );
+  }
+  /**
+   * Block until a loop re-direct settles, and throw if it did not take.
+   *
+   * `setLoop` returns on ACCEPTANCE; the render runs for minutes afterwards. Every caller
+   * therefore writes the same polling loop, and the obvious version of it never terminates
+   * on failure — a failed re-direct leaves her `ready` (she is still serving the old loop)
+   * and writes nothing to `error`. `idleVideoStatus` is the only field that moves, which is
+   * why this exists rather than a doc line telling you to poll.
+   *
+   * Race-free without a baseline: the platform commits `queued` before `setLoop` returns, so
+   * by the time you can call this the status has already left `ready`.
+   *
+   * Resolves with the settled avatar — `sourceAssetId` is now the new loop. Throws on a
+   * failed render and on timeout; a timeout is not a failure, so re-poll or call again.
+   */
+  async waitForLoop(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const avatar = await this.getAvatar(avatarId);
+      if (avatar.idleVideoStatus === "failed") {
+        throw new RealtimeAvatarError(
+          `Loop re-direct failed for ${avatarId}. She is still serving her previous loop \u2014 nothing was lost, and you can send another description.`
+        );
+      }
+      if (avatar.idleVideoStatus === "ready" || avatar.idleVideoStatus === "none") return avatar;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `Loop re-direct for ${avatarId} was still ${avatar.idleVideoStatus} after ${Math.round(timeoutMs / 1e3)}s. This is a timeout, not a failure \u2014 the render may still land.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /**
+   * Block until every clip in the library has stopped moving.
+   *
+   * Settled means no row is `queued` or `generating` — NOT that every row is `ready`.
+   * Waiting for all-`ready` is the intuitive version and it hangs forever: a clip rejected
+   * by pose validation settles `failed`, which is terminal. So this returns the library
+   * with the failures in it and lets you decide; a partial library is a legitimate outcome
+   * and the rest of it is already serving.
+   *
+   * Throws only on timeout.
+   */
+  async waitForClips(avatarId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 20 * 6e4;
+    const pollMs = Math.max(1e3, options.pollMs ?? 1e4);
+    const deadline = Date.now() + timeoutMs;
+    for (; ; ) {
+      const library = await this.listClips(avatarId);
+      const moving = library.data.filter((c) => c.status === "queued" || c.status === "generating");
+      if (moving.length === 0) return library;
+      if (Date.now() >= deadline) {
+        throw new RealtimeAvatarError(
+          `${moving.length} clip(s) on ${avatarId} were still rendering after ${Math.round(timeoutMs / 1e3)}s: ${moving.map((c) => c.clipId).join(", ")}. This is a timeout, not a failure.`
+        );
+      }
+      await sleep(pollMs);
+    }
+  }
+  /** The avatar's clip library: every non-retired clip, plus revision, anchor and eligibility. */
+  async listClips(avatarId) {
+    return this.#clipEnvelope(
+      await this.#json(
+        await this.#request("GET", `/avatars/${avatarId}/clips`)
+      )
+    );
+  }
+  /**
+   * Reconcile an avatar's clip set after it changes.
+   *
+   * Required, not optional: clips are prepared once and cached by URL hash, and the serve
+   * path only LOADS that cache. A clip that has never been prepared silently does nothing on
+   * the first call after you add it. Idempotent, so calling it on every write is cheap.
+   *
+   * **At most 32 URLs per call.** This is the whole set for the avatar, not a delta, and the
+   * endpoint rejects an oversize list rather than truncating it — so a library that outgrows
+   * 32 needs the set trimmed, not split across two calls.
+   *
+   * @deprecated The externally-hosted clip tier this serves is sunsetting. Declare the
+   * library with {@link setClipLibrary} instead — the platform renders and hosts the
+   * clips, and pose-validates uploads against the avatar's rest pose.
+   */
+  async syncClips(avatarId, clipUrls) {
+    const out = await this.#json(
+      await this.#request("POST", `/avatars/${avatarId}/clips`, { json: { clipUrls } })
+    );
+    return { queued: out.queued ?? [], ready: out.ready ?? [], retired: out.retired ?? [] };
+  }
+  // ── assets ───────────────────────────────────────────────────────────────
+  /** Hand us a URL and we stream it into storage. Prefer this for anything large. */
+  async createRemoteAsset(input) {
+    return toAsset(await this.#json(await this.#request("POST", "/assets/remote", { json: input })));
+  }
+  /** Upload bytes you already hold. */
+  async uploadAsset(file, options = {}) {
+    const form = new FormData();
+    form.append("file", file, options.filename ?? "upload");
+    if (options.kind) form.append("kind", options.kind);
+    return toAsset(await this.#json(await this.#request("POST", "/assets", { body: form })));
+  }
+  // ── billing ──────────────────────────────────────────────────────────────
+  /**
+   * Billable sessions, newest first — the itemised half of the bill that `creditBalance`
+   * cannot give you.
+   *
+   * Works with no setup: every session is listed with its times, duration and cost. To also
+   * know WHICH of your users a session belongs to, tag the call when you start it:
+   *
+   * ```ts
+   * await rta.startCall({ avatarId, metadata: { user_id: user.id } });
+   * // ...later
+   * await rta.listSessions({ endUserId: user.id });
+   * ```
+   *
+   * Tagging is optional and nothing degrades without it — you just cannot attribute a
+   * session to one of your users. Requires a key with the `usage:read` scope.
+   */
+  async listSessions(options = {}) {
+    const query = new URLSearchParams();
+    if (options.from) query.set("from", options.from);
+    if (options.to) query.set("to", options.to);
+    if (options.limit !== void 0) query.set("limit", String(options.limit));
+    if (options.cursor) query.set("cursor", options.cursor);
+    if (options.endUserId) query.set("endUserId", options.endUserId);
+    const suffix = query.size > 0 ? `?${query}` : "";
+    const page = await this.#json(await this.#request("GET", `/usage/sessions${suffix}`));
+    return toUsageSessionPage(page);
+  }
+  /**
+   * Every session in a window, following the cursor for you.
+   *
+   * An async iterator rather than an array, because a busy month is a lot of rows and a
+   * caller writing a monthly report should not have to hold all of them to start writing.
+   */
+  async *iterateSessions(options = {}) {
+    let cursor = options.cursor;
+    do {
+      const page = await this.listSessions({ ...options, cursor });
+      yield* page.sessions;
+      cursor = page.nextCursor ?? void 0;
+    } while (cursor);
+  }
+  async creditBalance() {
+    return await this.#json(await this.#request("GET", "/credits/balance"));
+  }
+  // ── internals ────────────────────────────────────────────────────────────
+  async #request(method, path, init = {}) {
+    const headers = {
+      authorization: `Bearer ${this.#apiKey}`,
+      "user-agent": this.#userAgent
+    };
+    let body = init.body;
+    if (init.json !== void 0) {
+      headers["content-type"] = "application/json";
+      body = JSON.stringify(init.json);
+    }
+    if (MUTATING.has(method)) headers["idempotency-key"] = newIdempotencyKey();
+    let lastError;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const signal = AbortSignal.timeout(this.#timeoutMs);
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, { method, headers, body, signal });
+        if (attempt >= this.#maxRetries || !RETRYABLE_STATUS.has(response.status)) return response;
+        await response.body?.cancel().catch(() => {
+        });
+        await sleep(backoffMs(attempt, response.headers.get("retry-after")));
+      } catch (cause) {
+        lastError = cause;
+        if (attempt >= this.#maxRetries || !isTransient(cause) || isStream(body)) {
+          throw new RealtimeAvatarError(
+            `${method} ${path} failed after ${attempt + 1} attempt(s): ${cause.message}`,
+            { cause: lastError }
+          );
+        }
+        await sleep(backoffMs(attempt, null));
+      }
+    }
+  }
+  /** Throw a useful error rather than letting a 4xx flow on as `undefined`. */
+  async #json(response) {
+    if (response.ok) return response.json();
+    const text = await response.text().catch(() => "");
+    let code;
+    try {
+      code = JSON.parse(text).code;
+    } catch {
+    }
+    throw new RealtimeAvatarHttpError(response.status, code, text.slice(0, 400));
+  }
+};
+function toUsageSessionPage(raw) {
+  const body = isRecord(raw) ? raw : {};
+  const rows = Array.isArray(body.data) ? body.data : [];
+  return {
+    sessions: rows.filter(isRecord).map((row) => ({
+      sessionId: String(row.sessionId ?? ""),
+      avatarId: typeof row.avatarId === "string" ? row.avatarId : null,
+      status: usageStatus(row.status),
+      startedAt: typeof row.startedAt === "string" ? row.startedAt : null,
+      endedAt: typeof row.endedAt === "string" ? row.endedAt : null,
+      activeSeconds: typeof row.activeSeconds === "number" ? row.activeSeconds : null,
+      billedCreditMicros: typeof row.billedCreditMicros === "number" ? row.billedCreditMicros : null,
+      metadata: isRecord(row.metadata) ? row.metadata : {},
+      createdAt: String(row.createdAt ?? "")
+    })),
+    nextCursor: typeof body.nextCursor === "string" ? body.nextCursor : null,
+    from: String(body.from ?? ""),
+    to: String(body.to ?? "")
+  };
+}
+var USAGE_STATUSES = ["reserved", "started", "released", "failed"];
+function usageStatus(value) {
+  return USAGE_STATUSES.find((s) => s === value) ?? "failed";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function videoToWire(video) {
+  if (video.mode === "generative") return { render_backend: "generative" };
+  const out = {};
+  if (video.edits) {
+    const edits = { instruction: video.edits.instruction };
+    if (video.edits.referenceUrl !== void 0) edits.reference_url = video.edits.referenceUrl;
+    if (video.edits.live !== void 0) {
+      const live = { rules: video.edits.live.rules };
+      if (video.edits.live.cooldownSeconds !== void 0) {
+        live.cooldown_seconds = Math.floor(video.edits.live.cooldownSeconds);
+      }
+      if (video.edits.live.renderer !== void 0) live.renderer = video.edits.live.renderer;
+      edits.live_edit = live;
+    }
+    out.support_edits = edits;
+  }
+  if (video.states) {
+    out.clip_library = Object.entries(video.states).map(([id, state]) => {
+      const clip = {
+        clip_id: id,
+        source_video_url: state.url,
+        trigger: "directive",
+        // `when` is the public name for this cue. The wire also still accepts the older
+        // `hint`; send one name only, and prefer the one the docs and types use.
+        when: state.when
+      };
+      if (state.weight !== void 0) clip.weight = state.weight;
+      return clip;
+    });
+  }
+  return out;
+}
+function toAvatar(raw) {
+  const a = raw;
+  return {
+    id: String(a.id),
+    displayName: String(a.displayName ?? ""),
+    sourceKind: a.sourceKind === "video" ? "video" : "image",
+    status: a.status ?? "draft",
+    defaultVoiceId: a.defaultVoiceId ? String(a.defaultVoiceId) : null,
+    sourceAssetId: a.sourceAssetId ? String(a.sourceAssetId) : null,
+    // Carried because it is the ONLY channel a failed source swap has: she stays `ready`
+    // and serving, and this says why the re-shoot did not take.
+    error: a.error ? String(a.error) : null,
+    // The loop lane's terminal signal, and the reason it is here: a re-direct that fails
+    // leaves `status` on `ready` (she is still serving the old loop, which is the whole
+    // design) and writes nothing to `error`. Without this field a caller polling after
+    // `setLoop` has NO way to distinguish "still rendering" from "gave up", and waits
+    // forever. queued → generating → ready | failed.
+    idleVideoStatus: a.idleVideoStatus ?? "none"
+  };
+}
+function toAsset(raw) {
+  const a = raw;
+  const url = a.publicUrl ?? a.url;
+  if (typeof url !== "string" || !url) {
+    throw new RealtimeAvatarError(`asset ${String(a.id)} came back without a public URL`);
+  }
+  return {
+    id: String(a.id),
+    kind: a.kind ?? "video",
+    url,
+    status: typeof a.status === "string" ? a.status : "ready",
+    contentType: typeof a.contentType === "string" ? a.contentType : null,
+    sizeBytes: typeof a.sizeBytes === "number" ? a.sizeBytes : null
+  };
+}
+function runtimeTag() {
+  const g = globalThis;
+  if ("Deno" in g) return "deno";
+  if ("Bun" in g) return "bun";
+  if ("navigator" in g && typeof navigator?.userAgent === "string" && navigator.userAgent.includes("Cloudflare-Workers")) return "workerd";
+  if ("process" in g && typeof process?.versions?.node === "string") return `node/${process.versions.node}`;
+  return "unknown";
+}
+function isStream(body) {
+  return typeof ReadableStream !== "undefined" && body instanceof ReadableStream;
+}
+
+// ../http-client/src/webhook.ts
+async function verifyTranscript(rawBody, headers, secret, options = {}) {
+  const get = (name) => headers instanceof Headers ? headers.get(name) ?? void 0 : headers[name];
+  const signature = get("x-rta-signature");
+  const timestamp = get("x-rta-timestamp");
+  if (!signature || !timestamp) throw new Error("missing x-rta-signature / x-rta-timestamp");
+  const skew = Math.abs(Date.now() / 1e3 - Number(timestamp));
+  if (!Number.isFinite(skew) || skew > (options.toleranceSeconds ?? 300)) {
+    throw new Error("transcript webhook timestamp is outside the replay window");
+  }
+  const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${timestamp}.${text}`));
+  const expected = `v1=${[...new Uint8Array(mac)].map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+  if (!timingSafeEqual(expected, signature)) throw new Error("transcript webhook signature mismatch");
+  return JSON.parse(text);
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+// ../http-client/src/types.ts
+function isQueued(result) {
+  return "queued" in result;
+}
+
+export { RealtimeAvatar, RealtimeAvatarError, RealtimeAvatarHttpError, isQueued, verifyTranscript };