realtime-avatar 0.5.0 → 0.5.2

package/dist/tanstack-start.js

@@ -43,7 +43,7 @@ var RealtimeAvatarHttpError = class extends RealtimeAvatarError {
 
 // ../http-client/src/client.ts
 var DEFAULT_BASE_URL = "https://realtimeavatar.ai/api/v1";
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.5.2";
 var RealtimeAvatar = class {
   #apiKey;
   #baseUrl;
@@ -157,10 +157,15 @@ var RealtimeAvatar = class {
   /**
    * 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.
+   * @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 });
@@ -173,12 +178,41 @@ var RealtimeAvatar = class {
       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;
@@ -191,7 +225,14 @@ var RealtimeAvatar = class {
   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. */
+  /**
+   * 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 }))
@@ -274,6 +315,94 @@ var RealtimeAvatar = class {
       )
     );
   }
+  /**
+   * 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(
@@ -475,7 +604,13 @@ function toAvatar(raw) {
     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
+    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) {

package/dist/{types-DLxz6uFE.d.ts → types-BeGuvyra.d.ts}

@@ -525,6 +525,16 @@ interface components {
                 retired: string[];
             };
         };
+        PutAvatarLoopRequest: {
+            motionPrompt: string;
+        };
+        PutAvatarLoopResponse: {
+            avatarId: string;
+            /** @enum {string} */
+            loopStatus: "generating" | "ready" | "failed";
+            motionPrompt: string;
+            servingUrl: string | null;
+        };
         SyncAvatarClipsRequest: {
             clipUrls: string[];
         };
@@ -843,7 +853,7 @@ type Asset = Pick<Wire["Asset"], "id" | "kind"> & {
      */
     status: Wire["Asset"]["status"] | (string & {});
 };
-type Avatar = Pick<Wire["Avatar"], "id" | "displayName" | "sourceKind" | "status" | "defaultVoiceId" | "sourceAssetId" | "error">;
+type Avatar = Pick<Wire["Avatar"], "id" | "displayName" | "sourceKind" | "status" | "defaultVoiceId" | "sourceAssetId" | "error" | "idleVideoStatus">;
 /**
  * The patch `updateAvatar` sends — the two fields an integrator re-points after creation.
  * The contract's `UpdateAvatarRequest` carries more (llm, persona, art direction…); that is
@@ -931,6 +941,13 @@ type ClipLibrary = Wire["ListAvatarClipsResponse"];
 type ClipLibraryPlan = Wire["PutAvatarClipsResponse"]["plan"];
 /** The accepted declaration's answer: the post-apply library plus how it reconciled. */
 type ClipLibraryUpdate = Wire["PutAvatarClipsResponse"];
+/**
+ * The accepted re-direct. `servingUrl` is the loop she is playing RIGHT NOW — the previous
+ * one, which keeps serving for the whole render. A caller that treated the new description
+ * as live on acceptance would be lying to its user for minutes; this is the field that lets
+ * it say "being re-directed" while still showing the real thing.
+ */
+type LoopRedirect = Wire["PutAvatarLoopResponse"];
 /**
  * DERIVATION: hand-written, because the contract does not describe it.
  *
@@ -978,4 +995,4 @@ interface TranscriptPayload {
     client_metadata: Record<string, string>;
 }
 
-export { type Avatar as A, type CallMode as C, type EndCallOptions as E, type ListSessionsOptions as L, type StartCallResult as S, type TranscriptPayload as T, type UsageSessionPage as U, type VideoPolicy as V, type CallPolicy as a, type AvatarUpdate as b, type AvatarSourceSwap as c, type ClipDeclaration as d, type ClipLibraryUpdate as e, type ClipLibrary as f, type ClipSyncResult as g, type AssetKind as h, type Asset as i, type UsageSession as j, type CreditBalance as k, type AvatarClip as l, type CallConnection as m, type CallQueued as n, type ClipLibraryPlan as o, type ClipSource as p, type ContextMessage as q, type EndCallReason as r, type VideoState as s, isQueued as t };
+export { type Avatar as A, type CallMode as C, type EndCallOptions as E, type LoopRedirect as L, type StartCallResult as S, type TranscriptPayload as T, type UsageSessionPage as U, type VideoPolicy as V, type CallPolicy as a, type AvatarUpdate as b, type AvatarSourceSwap as c, type ClipDeclaration as d, type ClipLibraryUpdate as e, type ClipLibrary as f, type ClipSyncResult as g, type AssetKind as h, type Asset as i, type ListSessionsOptions as j, type UsageSession as k, type CreditBalance as l, type AvatarClip as m, type CallConnection as n, type CallQueued as o, type ClipLibraryPlan as p, type ClipSource as q, type ContextMessage as r, type EndCallReason as s, type VideoState as t, isQueued as u };

package/dist/{types-B45GgjrV.d.ts → types-CHrhuhYb.d.ts}

@@ -1,4 +1,4 @@
-import { C as CallMode, a as CallPolicy } from './types-DLxz6uFE.js';
+import { C as CallMode, a as CallPolicy } from './types-BeGuvyra.js';
 
 /** The three things a caller can ask the proxy to do. Gate on these, not on URLs. */
 type ProxyOperation = "connect" | "end" | "avatars" | "credits";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Realtime Avatar SDK. `realtime-avatar` and the route adapters hold your API key and are server-only; `realtime-avatar/react`, `/browser` and `/tools` never can — importing a server entry into a browser build throws at bundle time.",
   "license": "MIT",
   "author": "The Influence Company",