@streamoji/aitwin 0.6.5 → 0.6.8

package/dist/index.d.ts

@@ -17,6 +17,11 @@ export declare type AiTwinCaptionsOptions = {
 
 export declare type AiTwinHandle = {
     speakText: (text: string, options?: AvatarTtsSpeakOptions) => Promise<void>;
+    /**
+     * Generate an LLM reply and speak it in one `/avatar_ttsWithPoses` request
+     * (`generateReply: true`). Prefer this over `/avatarReply` + `speakText`.
+     */
+    speakWithReply: (message: string, options?: SpeakWithReplyOptions) => Promise<SpeakWithReplyResult>;
     stop: () => void;
     setTtsEngineId: (engineId: TtsEngineId) => void;
     renderViseme: (toViseme: string, options?: AiTwinRenderVisemeOptions) => Promise<void>;
@@ -49,10 +54,12 @@ export declare type AiTwinHandle = {
     /** Mute/unmute bot audio output (TTS + voice). */
     setMuted: (muted: boolean) => void;
     isMuted: () => boolean;
-    /** Brain id from getAiTwin (for /avatarReply and /ws/voice). */
+    /** Brain id from getAiTwin (for speakWithReply and /ws/voice). */
     getBrainId: () => string | null;
     /** @deprecated Use `getBrainId`. */
     getPersonaId: () => string | null;
+    /** Client SSE brain URL from getAiTwin (for speakWithReply / /ws/voice). */
+    getBrainUrl: () => string | null;
 };
 
 export declare class AiTwinNotFoundError extends Error {
@@ -159,6 +166,8 @@ export declare type AiTwinRecord = {
     brainId?: string;
     /** @deprecated Use `brainId`. */
     knowledgeContextId?: string;
+    /** Client SSE brain URL. Passed as `brainUrl` on `/ws/voice`. */
+    brainUrl?: string;
     gender?: string;
     createdAt?: string;
     updatedAt?: string;
@@ -182,6 +191,7 @@ export declare const AiTwinWidget: ForwardRefExoticComponent<AiTwinWidgetProps &
 /** Imperative API shared by React ref and HTML widget handle. */
 export declare type AiTwinWidgetHandle = {
     speakText: (text: string, options?: AvatarTtsSpeakOptions) => Promise<void>;
+    speakWithReply: (message: string, options?: SpeakWithReplyOptions) => Promise<SpeakWithReplyResult>;
     connect: (options?: VoiceConnectOptions) => Promise<void>;
     disconnect: () => Promise<void>;
     stop: () => void;
@@ -232,12 +242,17 @@ export declare type AiTwinWidgetProps = {
      */
     float?: boolean;
     /**
-     * Brain id for /avatarReply (Text mode).
+     * Brain id for `speakWithReply` (Text mode) and `/ws/voice`.
      * When omitted, uses getAiTwin `brainId` if available.
      */
     brainId?: string;
     /** @deprecated Use `brainId`. */
     personaId?: string;
+    /**
+     * Client SSE brain URL for `speakWithReply` / `/ws/voice`.
+     * When omitted, uses getAiTwin `brainUrl` if available.
+     */
+    brainUrl?: string;
     /**
      * Optional poster shown (blurred) on `<AiTwin>` while sil/atlas/idle assets load.
      * When omitted, AiTwin derives it from `faceId`/`avatarId`.
@@ -265,6 +280,11 @@ export declare type AvatarTtsLipsyncController = {
     setTtsEngineId: (engineId: TtsEngineId) => void;
     getTtsEngineId: () => TtsEngineId;
     speak: (userQuery: string, options?: AvatarTtsSpeakOptions) => Promise<void>;
+    /**
+     * LLM reply + TTS in one `/avatar_ttsWithPoses` request (`generateReply: true`).
+     * Avoids a separate `/avatarReply` round-trip.
+     */
+    speakWithReply: (message: string, options?: SpeakWithReplyOptions) => Promise<SpeakWithReplyResult>;
     stop: () => void;
     getVisemeQueue: () => VisemeQueueItem[];
     getWordQueue: () => WordQueueItem[];
@@ -454,6 +474,12 @@ export declare function parsePackedVoiceId(raw?: string): {
     voiceId?: string;
 };
 
+/**
+ * Validate a client SSE brain URL. Empty/whitespace is unset.
+ * Must be http(s) with a host and no fragment — same rules as `/ws/voice`.
+ */
+export declare function parseTwinBrainUrl(value?: string | null): string | undefined;
+
 export declare const PLAYBACK_SAMPLE_RATE = 16000;
 
 declare type RawVisemeTransition = {
@@ -517,6 +543,8 @@ export declare function resolveDirectFaceId(avatarId?: string, faceId?: string):
 /** Canonical `brainId`, then legacy `knowledgeContextId`, then extra fallbacks. */
 export declare function resolveTwinBrainId(source?: TwinBrainFields | string | null, ...fallbacks: Array<string | null | undefined>): string | undefined;
 
+export declare function resolveTwinBrainUrl(source?: TwinBrainFields | string | null, ...fallbacks: Array<string | null | undefined>): string | undefined;
+
 /** Pick the active viseme at playback offset (latest vtime wins on overlap). */
 export declare function resolveVisemeAtTime(queue: VisemeQueueItem[], elapsedMs: number): string;
 
@@ -557,6 +585,27 @@ export declare const SPEAKING_RATE_MAX = 1.5;
 
 export declare const SPEAKING_RATE_MIN = 0.5;
 
+export declare type SpeakWithReplyMessage = {
+    role: "user" | "assistant";
+    content: string;
+};
+
+/** Options for `/avatar_ttsWithPoses` with `generateReply: true`. */
+export declare type SpeakWithReplyOptions = AvatarTtsSpeakOptions & {
+    brainId?: string;
+    brainUrl?: string;
+    history?: SpeakWithReplyMessage[];
+    /** Called as soon as spokenText arrives on the SSE stream. */
+    onSpokenText?: (spokenText: string) => void;
+    /** Called as soon as displayText arrives on the SSE stream. */
+    onDisplayText?: (displayText: string) => void;
+};
+
+export declare type SpeakWithReplyResult = {
+    displayText: string;
+    spokenText: string;
+};
+
 /** Merge explicit `ttsEngineId` with a possibly packed `voiceId`. Packed engine wins only if engine is omitted. */
 export declare function splitVoiceIdSpec(ttsEngineId?: TtsEngineId, voiceId?: string): {
     ttsEngineId?: TtsEngineId;
@@ -845,6 +894,8 @@ declare type TwinBrainFields = {
     brainId?: string | null;
     /** @deprecated Use `brainId`. Older getAiTwin responses still send this. */
     knowledgeContextId?: string | null;
+    /** Client SSE brain URL. When set, `/ws/voice` skips hosted brainId / Grok / OpenAI. */
+    brainUrl?: string | null;
 };
 
 export declare const VISEME_IDS: readonly ["aa", "E", "I", "O", "U", "PP", "FF", "DD", "SS", "TH", "CH", "RR", "kk", "nn"];
@@ -889,6 +940,11 @@ export declare type VoiceConnectOptions = {
     brainId?: string;
     /** @deprecated Use `brainId`. */
     personaId?: string;
+    /**
+     * Client SSE brain URL. When set, `/ws/voice` skips hosted brainId / Grok / OpenAI
+     * and GETs this URL with socket query params plus `text=<user turn>`.
+     */
+    brainUrl?: string;
     speakingRate?: number;
     /** Default true — server streams TTS + avatar messages. */
     ttsStream?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamoji/aitwin",
-  "version": "0.6.5",
+  "version": "0.6.8",
   "description": "Embeddable React AI twin face with TTS lipsync",
   "type": "module",
   "main": "./dist/aitwin.cjs",