realtime-avatar 0.3.0

package/dist/index.js

@@ -0,0 +1,453 @@
+// ../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/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 };

package/dist/nextjs.d.ts

@@ -0,0 +1,18 @@
+import { P as ProxyConfig } from './types-E8SrD6sv.js';
+import './types-C_EMPwN7.js';
+
+/**
+ * App Router. Mount at `app/api/realtime-avatar/[...path]/route.ts`:
+ *
+ * ```ts
+ * export const { GET, POST } = createRealtimeAvatarRoute({ apiKey: process.env.KEY!, session });
+ * ```
+ *
+ * Name the variable without `NEXT_PUBLIC_` — that prefix inlines it into the client bundle.
+ */
+declare function createRealtimeAvatarRoute(config: ProxyConfig): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+};
+
+export { createRealtimeAvatarRoute };