Data Models

Data structures used throughout the Estuary SDK.

SessionInfo

Returned when a connection is successfully established.

interface SessionInfo {
    sessionId: string;       // Unique session ID
    conversationId: string;  // Persistent conversation ID
    characterId: string;     // Character UUID
    playerId: string;        // User identifier
}

Usage:

character.on('connected', (session: SessionInfo) => {
    print(`Session: ${session.sessionId}`);
    print(`Conversation: ${session.conversationId}`);
});

---

BotResponse

AI text responses, received as streaming chunks or complete messages.

interface BotResponse {
    text: string;            // Response text
    isFinal: boolean;        // Complete response?
    partial: boolean;        // Streaming chunk?
    messageId: string;       // Message ID (for interrupt tracking)
    chunkIndex: number;      // Chunk number
    isInterjection: boolean; // Proactive message?
}

Usage:

character.on('botResponse', (response: BotResponse) => {
    if (response.isFinal) {
        print(`Complete: ${response.text}`);
    } else {
        // Streaming update
        updateUI(response.text);
    }
});

---

BotVoice

AI voice audio data, received as Base64-encoded PCM chunks.

interface BotVoice {
    audio: string;           // Base64 PCM16 audio
    sampleRate: number;      // Audio sample rate (server-determined, typically 24000)
    chunkIndex: number;      // Audio chunk number
    messageId: string;       // Message ID (for interrupt tracking)
    isInterjection: boolean; // Whether from a proactive interjection
}

Usage:

character.on('voiceReceived', (voice: BotVoice) => {
    const pcmBytes = Base64.decode(voice.audio);
    audioOutput.addAudioFrame(pcmBytes, 1);
});

---

SttResponse

Speech-to-text transcription results.

interface SttResponse {
    text: string;            // Transcribed text
    isFinal: boolean;        // Final transcription?
    confidence: number;      // Confidence (0-1)
    language: string;        // Detected language (default: 'en')
}

Usage:

character.on('transcript', (stt: SttResponse) => {
    if (stt.isFinal) {
        print(`You said: ${stt.text} (${stt.language})`);
    }
});

---

InterruptData

Information about conversation interrupts.

interface InterruptData {
    messageId: string;       // The message ID that was interrupted
    reason: string;          // Interrupt reason
}

Usage:

character.on('interrupt', (data: InterruptData) => {
    audioOutput.interruptAudioOutput();
    print(`Interrupted message ${data.messageId}: ${data.reason}`);
});

---

CameraCaptureRequest

Request sent by the server when the AI agent decides it needs to see something.

interface CameraCaptureRequest {
    request_id: string;      // Unique identifier for this request
    text?: string;           // Optional context text
}

Usage:

character.on('cameraCaptureRequest', (request: CameraCaptureRequest) => {
    print(`Server wants to see: ${request.request_id}`);
    // Capture image and send back via sendCameraImage()
});

---

AgentResponse

Character/agent data returned by the REST API (e.g., image-to-character, character listing).

interface AgentResponse {
    id: string;                    // Unique agent identifier (UUID)
    name: string;                  // Character display name
    tagline: string | null;        // Short tagline
    personality: string | null;    // Personality description
    background: string | null;     // Character backstory
    avatar: string | null;         // Avatar image URL
    appearance: string | null;     // Appearance description
    modelUrl: string | null;       // URL to textured 3D model (GLB)
    modelPreviewUrl: string | null; // URL to preview 3D model (GLB)
    modelStatus: string | null;    // "generating" | "preview_ready" | "completed" | "failed" | "texture_failed"
    sourceImageUrl: string | null; // URL to original source image
    playerId: string | null;       // Player who created this character
    ttsProvider: string;           // TTS provider identifier
    ttsModel: string;              // TTS model name
    ttsVoice: string | null;       // TTS voice identifier
    llmProvider: string;           // LLM provider identifier
    llmModel: string;              // LLM model name
    createdAt: string | null;      // ISO 8601 creation timestamp
    updatedAt: string | null;      // ISO 8601 last-updated timestamp
}

Helper:

// Parse from raw JSON (handles both camelCase and snake_case keys)
const agent = parseAgentResponse(jsonData);

---

ModelStatusResponse

Response from the 3D model generation status endpoint.

interface ModelStatusResponse {
    modelStatus: string;              // "generating" | "preview_ready" | "completed" | "failed" | "texture_failed"
    modelPreviewUrl: string | null;   // URL to preview GLB model
    modelUrl: string | null;          // URL to textured GLB model
    thumbnailUrl: string | null;      // URL to model thumbnail image
    progress: number;                 // Generation progress (0-100)
}

Helper Functions:

import {
    isModelInProgress,
    isModelCompleted,
    isModelFailed,
    isModelTextureFailed
} from 'estuary-lens-studio-sdk';

if (isModelInProgress(status)) {
    print(`Generating: ${status.progress}%`);
} else if (isModelCompleted(status)) {
    print(`Done! GLB URL: ${status.modelUrl}`);
} else if (isModelTextureFailed(status)) {
    // Preview model is still usable
    print(`Texture failed, but preview available: ${status.modelPreviewUrl}`);
} else if (isModelFailed(status)) {
    print('Model generation failed');
}

---

CharacterListResponse

Paginated list of characters from GET /api/v1/characters.

interface CharacterListResponse {
    characters: AgentResponse[];  // Array of character objects
    total: number;                // Total matching characters
    limit: number;                // Page size
    offset: number;               // Current offset
}

Usage:

const httpClient = new EstuaryHttpClient(config);
const list = await httpClient.getCharacters(20, 0);

print(`Showing ${list.characters.length} of ${list.total} characters`);
for (const character of list.characters) {
    print(`${character.name}: ${character.tagline}`);
}