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 (WebSocket transport) or playback metadata (LiveKit transport).

interface BotVoice {
  audio?: string;           // Base64-encoded PCM audio data. Omitted for LiveKit metadata events.
  messageId: string;        // Message this audio belongs to
  chunkIndex: number;       // Sequential audio chunk index
  isFinal?: boolean;        // true if this is the last audio chunk
  isLivekit?: boolean;      // true when this is a LiveKit metadata event (audio is omitted; the
                            // bytes flow over the WebRTC track instead)
}

info

For the LiveKit transport, bot_voice events arrive as metadata-only (no audio field). The actual audio bytes are streamed as a WebRTC media track and played by the browser directly. Always guard against voice.audio being undefined if you handle this event yourself.

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 by the memory API and in MemoryUpdatedEvent.newMemories.

interface MemoryData {
  id: string;                     // Unique memory ID
  userId: string;                 // Owning user ID
  agentId: string;                // Character (agent) ID
  playerId: string;               // Player 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
  source?: string;                // Origin tag (e.g., extraction source)
  topic?: string;                 // Primary memory topic
  secondaryTopics?: string[];     // Additional topics
  lastAccessedAt?: string | null; // ISO timestamp of last access
  accessCount?: number;           // Number of times this memory was retrieved
  extractedAt?: string | null;    // ISO timestamp of extraction
  createdAt?: string | null;      // ISO timestamp of creation
  updatedAt?: string | null;      // ISO timestamp of last update
}

---

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
}

---

Character

CharacterInfo

Returned by client.getCharacter().

interface CharacterInfo {
  id: string;
  name: string;
  tagline: string | null;
  avatar: string | null;            // Avatar image URL
  modelUrl: string | null;          // 3D model (e.g., GLB) URL
  modelPreviewUrl: string | null;   // Preview render of the 3D model
  modelStatus: string | null;       // Generation/processing status
  sourceImageUrl: string | null;    // Source image used for generation
}

---

Sharing

ShareOpenResponse

Returned by EstuaryClient.openShare(). Contains everything needed to construct a session-token-authenticated client.

interface ShareOpenResponse {
  sessionToken: string;       // Pass to EstuaryConfig.sessionToken (starts with "sst_")
  characterId: string;        // Pass to EstuaryConfig.characterId
  playerId: string;           // Pass to EstuaryConfig.playerId
  serverUrl: string;          // Pass to EstuaryConfig.serverUrl
  character: CharacterInfo & { personality?: string | null };  // Character details for UI
}

---

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: MemoryData[];               // 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: MemoryData[];
  }[];
  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
}

MemoryGraphNode

interface MemoryGraphNode {
  id: string;
  type: 'user' | 'cluster' | 'memory' | 'entity';
  label?: string;

  // Cluster fields
  level?: number;
  memoryCount?: number;
  typeDistribution?: Record<string, number>;
  expanded?: boolean;
  parentClusterId?: string | null;
  childClusterIds?: string[];
  labelPending?: boolean;

  // Memory fields
  memoryType?: string;
  content?: string;
  confidence?: number;
  clusterId?: string;
  sourceQuote?: string | null;
  sourceConversationId?: string | null;
  createdAt?: string | null;
  accessCount?: number;

  // Entity fields
  entityType?: string | null;
  name?: string;
  mentionCount?: number;
  extraData?: Record<string, string>;
}

MemoryGraphEdge

interface MemoryGraphEdge {
  source: string;                       // Source node id
  target: string;                       // Target node id
  type: 'has_cluster' | 'contains' | 'mentions' | 'relationship';
  relationshipType?: string;
  label?: string | null;
  confidence?: number;
}

MemoryGraphResponse

Response from client.memory.getGraph().

interface MemoryGraphResponse {
  nodes: MemoryGraphNode[];
  edges: MemoryGraphEdge[];
  stats: {
    totalMemories: number;
    totalEntities: number;
    clusterCount: number;
    clusters: Record<string, number>;   // Memories per cluster id
  };
  stale?: boolean;                      // true if a fresh graph build is in progress
}

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: MemoryData;                // The matching memory
    score: number;                     // Relevance score
    similarityScore: number;           // Semantic similarity score
  }[];
  query: string;                       // Original query
  total: number;                       // Total matches
}

CoreFact

Individual core-fact object.

interface CoreFact {
  id: string;
  userId: string;
  agentId: string;
  playerId: string;
  factKey: string;                     // Stable key (e.g., "favorite_color")
  factValue: string;                   // Current value (e.g., "blue")
  sourceMemoryId?: string | null;      // Memory this fact was distilled from
  createdAt?: string | null;
  updatedAt?: string | null;
}

CoreFactsResponse

Response from client.memory.getCoreFacts().

interface CoreFactsResponse {
  coreFacts: CoreFact[];
}

MemoryStatsResponse

Response from client.memory.getStats().

interface MemoryStatsResponse {
  totalActive: number;                 // Active memories
  totalSuperseded: number;             // Memories replaced by newer info
  totalDecayed: number;                // Memories that have decayed out
  byType: Record<string, number>;      // Active count per memory type
  coreFacts: number;                   // Total core facts
}