realtime-avatar 0.3.0

package/dist/nextjs.js

@@ -0,0 +1,498 @@
+// ../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/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/client.ts
+var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
+var SDK_VERSION = "0.3.0";
+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 ?? globalThis.fetch;
+    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.
+   *
+   * Use a VIDEO source for anything that will be called live. An avatar built from a still
+   * image reaches `ready`, mints calls, and publishes a BLACK track — the status and the
+   * track dimensions both look fine, only the pixels are wrong. Image sources are for
+   * offline lipsync renders.
+   */
+  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
+    });
+  }
+  async createAvatar(input) {
+    const body = {
+      displayName: input.displayName,
+      sourceKind: input.sourceKind,
+      sourceAssetId: input.sourceAssetId
+    };
+    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. */
+  async updateAvatar(avatarId, patch) {
+    return toAvatar(
+      await this.#json(await this.#request("PATCH", `/avatars/${avatarId}`, { json: patch }))
+    );
+  }
+  async deleteAvatar(avatarId) {
+    await this.#json(await this.#request("DELETE", `/avatars/${avatarId}`));
+  }
+  /**
+   * 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.
+   */
+  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
+  };
+}
+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/types.ts
+function isQueued(result) {
+  return "queued" in result;
+}
+
+// ../proxy/src/config.ts
+var json = (body, status = 200) => new Response(JSON.stringify(body), {
+  status,
+  headers: { "content-type": "application/json", "cache-control": "no-store" }
+});
+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 });
+    try {
+      if (operation === "avatars") return json({ data: await rta.listAvatars() });
+      if (operation === "credits") return json(await rta.creditBalance());
+      if (operation === "end") {
+        const ended = await request.json().catch(() => ({}));
+        const sessionId = ended.session_id ?? ended.queue_ticket_id;
+        if (!sessionId) return json({ error: "session_id or queue_ticket_id is required" }, 422);
+        const owns = config.ownsSession ? await config.ownsSession({ request, sessionId }) : minted.delete(sessionId);
+        if (!owns) return new Response(null, { status: 204 });
+        const reason = ended.reason === "page_hide" || ended.reason === "unmount" ? ended.reason : "manual";
+        await rta.endCall(sessionId, { reason });
+        return new Response(null, { status: 204 });
+      }
+      const body = await request.json().catch(() => ({}));
+      if (!body.avatarId) return json({ error: "avatarId is required" }, 422);
+      const mode = body.mode === "voice" ? "voice" : "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 && error.isBilling) {
+        return json({ code: error.code ?? "insufficient_credits" }, 402);
+      }
+      throw error;
+    }
+  };
+}
+
+// ../proxy/src/nextjs.ts
+function createRealtimeAvatarRoute(config) {
+  const handler = createProxyHandler(config);
+  return { GET: handler, POST: handler };
+}
+
+export { createRealtimeAvatarRoute };