Skip to main content

Data Models

All TypeScript interfaces used across the Estuary SDK.

Session​

SessionInfo​

Returned by connect() and emitted with the connected event.

interface SessionInfo {
  sessionId: string;        // Unique session identifier
  conversationId: string;   // Persistent conversation ID for this player-character pair
  characterId: string;      // The character (agent) ID
  playerId: string;         // The player identifier
}

Responses​

BotResponse​

Emitted by the botResponse event. Represents a streaming text response from the character.

interface BotResponse {
  text: string;             // Accumulated response text so far
  isFinal: boolean;         // true when the response is complete
  partial: string;          // Text content of just this chunk
  messageId: string;        // Unique message identifier
  chunkIndex: number;       // Sequential chunk index (starts at 0)
  isInterjection: boolean;  // true if proactive (not a reply to user input)
}

BotVoice​

Emitted by the botVoice event. Contains a chunk of voice audio.

interface BotVoice {
  audio: string;            // Base64-encoded PCM audio data
  messageId: string;        // Message this audio belongs to
  chunkIndex: number;       // Sequential audio chunk index
  isFinal: boolean;         // true if this is the last audio chunk
}

SttResponse​

Emitted by the sttResponse event. Contains speech-to-text transcription.

interface SttResponse {
  text: string;             // Transcribed text
  isFinal: boolean;         // true if this is the final transcription
}

Events​

InterruptData​

Emitted by the interrupt event when a response is interrupted.

interface InterruptData {
  messageId?: string;       // ID of the interrupted message
  reason?: string;          // Reason for interruption
  interruptedAt?: string;   // ISO timestamp of the interruption
}

QuotaExceededData​

Emitted by the quotaExceeded event.

interface QuotaExceededData {
  message: string;          // Human-readable quota message
  current: number;          // Current usage count
  limit: number;            // Usage limit
  remaining: number;        // Remaining quota
  tier: string;             // Account tier
}

CameraCaptureRequest​

Emitted by the cameraCaptureRequest event when the server requests a camera image.

interface CameraCaptureRequest {
  requestId: string;        // ID to include when responding with sendCameraImage()
  text?: string;            // Optional prompt text from the server
}

CharacterAction​

Emitted by the characterAction event. Represents a parsed action tag from a bot response.

interface CharacterAction {
  name: string;                    // Action name (e.g., "navigate", "emote")
  params: Record<string, string>; // All other tag attributes as key-value pairs
  messageId: string;              // Message ID of the bot response that contained this action
}

MemoryUpdatedEvent​

Emitted by the memoryUpdated event when the server extracts memories from a conversation turn. Requires realtimeMemory: true in config.

interface MemoryUpdatedEvent {
  agentId: string;                // Character (agent) ID
  playerId: string;               // Player ID
  memoriesExtracted: number;      // Number of memories extracted this turn
  factsExtracted: number;         // Number of core facts extracted this turn
  conversationId: string;         // Conversation ID
  newMemories: MemoryData[];      // Array of newly extracted memory objects
  timestamp: string;              // ISO timestamp
}

MemoryData​

Individual memory object returned in MemoryUpdatedEvent.newMemories.

interface MemoryData {
  id: string;                     // Unique memory ID
  content: string;                // Memory content text
  memoryType: string;             // Type of memory (e.g., "episodic", "semantic")
  confidence: number;             // Confidence score (0-1)
  status: string;                 // Memory status (e.g., "active")
  sourceConversationId: string;   // Conversation that produced this memory
  sourceQuote?: string;           // Original quote from conversation
  topic?: string;                 // Memory topic
  createdAt: string;              // ISO timestamp
}

LiveKitTokenResponse​

Token data used internally by the LiveKit voice manager.

interface LiveKitTokenResponse {
  token: string;            // LiveKit access token
  url: string;              // LiveKit server URL
  room: string;             // Room name
}

Memory Types​

MemoryListOptions​

Options for client.memory.getMemories().

interface MemoryListOptions {
  memoryType?: string;                                        // Filter by memory type
  status?: string;                                            // Filter by status (e.g., 'active')
  limit?: number;                                             // Max results to return
  offset?: number;                                            // Pagination offset
  sortBy?: 'created_at' | 'confidence' | 'last_accessed_at'; // Sort field
  sortOrder?: 'asc' | 'desc';                                // Sort direction
}

MemoryListResponse​

Response from client.memory.getMemories().

interface MemoryListResponse {
  memories: Record<string, unknown>[];  // Array of memory objects
  total: number;                        // Total matching memories
  limit: number;                        // Limit applied
  offset: number;                       // Offset applied
}

MemoryTimelineOptions​

Options for client.memory.getTimeline().

interface MemoryTimelineOptions {
  startDate?: string;               // ISO date string for range start
  endDate?: string;                 // ISO date string for range end
  groupBy?: 'day' | 'week' | 'month'; // Grouping period
}

MemoryTimelineResponse​

Response from client.memory.getTimeline().

interface MemoryTimelineResponse {
  timeline: {
    date: string;
    memories: Record<string, unknown>[];
  }[];
  totalMemories: number;            // Total memories across all groups
  groupBy: string;                  // Grouping used
}

MemoryGraphOptions​

Options for client.memory.getGraph().

interface MemoryGraphOptions {
  includeEntities?: boolean;           // Include entity nodes
  includeCharacterMemories?: boolean;  // Include character's own memories
}

MemoryGraphResponse​

Response from client.memory.getGraph().

interface MemoryGraphResponse {
  nodes: Record<string, unknown>[];    // Graph nodes
  edges: Record<string, unknown>[];    // Graph edges (relationships)
  stats: Record<string, unknown>;      // Graph statistics
}

MemorySearchOptions​

Options for client.memory.search().

interface MemorySearchOptions {
  query: string;                       // Natural language search query
  limit?: number;                      // Max results
}

MemorySearchResponse​

Response from client.memory.search().

interface MemorySearchResponse {
  results: {
    memory: Record<string, unknown>;   // The matching memory
    score: number;                     // Relevance score
    similarityScore: number;           // Semantic similarity score
  }[];
  query: string;                       // Original query
  total: number;                       // Total matches
}

CoreFactsResponse​

Response from client.memory.getCoreFacts().

interface CoreFactsResponse {
  coreFacts: Record<string, unknown>[];  // Array of core fact objects
}

MemoryStatsResponse​

Response from client.memory.getStats().

interface MemoryStatsResponse {
  [key: string]: unknown;              // Aggregate memory statistics
}
Last updated