vitrus

/** * Vitrus SDK * * TypeScript client for the Vitrus DAO. Actor/Agent communication model with workflow orchestration. * * Communication: All agent–actor traffic (commands, responses, broadcasts, events) goes through * the DAO WebSocket. No Zenoh in the TS SDK (avoids WASM/Node issues). Python SDK uses Zenoh * for Python↔Python; DAO bridges WebSocket ↔ Zenoh for cross-language. */ interface JSONSchema { type: 'object' | 'string' | 'number' | 'boolean' | 'array'; description?: string; properties?: Record<string, JSONSchema>; required?: string[]; items?: JSONSchema; additionalProperties?: boolean; } interface OpenAITool { name: string; description?: string; parameters: JSONSchema; strict?: boolean; } interface WorkflowDefinition { type: 'function'; function: OpenAITool; } /** Supabase-backed actor record (id, info, device_id, state, etc.) */ export interface ActorRecord { id: string; name: string; world_id: string; info: any; device_id?: string | null; state: string; created_at: string; updated_at: string; registeredCommands?: Array<{ name: string; parameterTypes: Array<string>; }>; } declare class Actor { private vitrus; private _name; private metadata; private commandHandlers; /** Supabase actor record (id, info, device_id, state, etc.) when fetched via actor(name) as agent */ private record; constructor(vitrus: Vitrus, name: string, metadata?: any, record?: ActorRecord | null); /** Actor name (always set) */ get name(): string; /** Actor ID from Supabase (when fetched via actor(name)) */ get id(): string | undefined; /** Actor info/metadata from Supabase */ get info(): any; /** Associated device ID from Supabase */ get deviceId(): string | null | undefined; /** Actor state from Supabase (e.g. connected, disconnected) */ get state(): string | undefined; /** Registered commands from DAO/Supabase */ get registeredCommands(): Array<{ name: string; parameterTypes: Array<string>; }> | undefined; /** * Register a command handler */ on(commandName: string, handler: Function): Actor; /** * Run a command on an actor */ run(commandName: string, ...args: any[]): Promise<any>; /** * Broadcast an event to all agents subscribed to this actor's event (actor-side only). * Call when connected as this actor. */ broadcast(eventName: string, data: any): Promise<void>; /** * Subscribe to this actor's broadcast events (agent-side). Callback receives event data. */ event(eventName: string, callback: (data: any) => void): Actor; /** * Alias for event(). Subscribe to this actor's broadcasts (agent-side). e.g. actor.listen('telemetry', (data) => { ... }) */ listen(eventName: string, callback: (data: any) => void): Actor; /** * Get actor metadata */ getMetadata(): any; /** * Update actor metadata */ updateMetadata(newMetadata: any): void; /** * Disconnect the actor if the SDK is currently connected as this actor. */ disconnect(): void; } declare class Scene { private vitrus; private sceneId; constructor(vitrus: Vitrus, sceneId: string); /** * Set a structure to the scene */ set(structure: any): void; /** * Add an object to the scene */ add(object: any): void; /** * Update an object in the scene */ update(params: { id: string; [key: string]: any; }): void; /** * Remove an object from the scene */ remove(objectId: string): void; /** * Get the scene */ get(): any; } /** Vitrus client. All agent/actor traffic over DAO WebSocket (no Zenoh in TS). */ declare class Vitrus { private ws; private apiKey; private worldId?; private clientId; private connected; private authenticated; private messageHandlers; private pendingRequests; private actorCommandHandlers; private actorCommandSignatures; private actorMetadata; private baseUrl; private debug; private actorName?; private actorIds; private actorEventListeners; private connectionPromise; private _connectionReject; private serverIp?; private worldExists?; private static readonly OPEN; constructor({ apiKey, world, baseUrl, debug }: { apiKey: string; world?: string; baseUrl?: string; debug?: boolean; }); /** * Connect to the WebSocket server with authentication * @internal This is mainly for internal use, users should use authenticate() */ connect(actorName?: string, metadata?: any): Promise<void>; private _establishWebSocketConnection; private createBrowserWsWrapper; private waitForConnection; private waitForAuthentication; private sendMessage; private handleMessage; private handleCommand; private sendResponse; /** * Register a command with the server */ registerCommand(actorName: string, commandName: string, parameterTypes: Array<string>): Promise<void>; private generateRequestId; /** * Authenticate with the API */ authenticate(actorName?: string, metadata?: any): Promise<boolean>; /** * Register a command handler for an actor */ registerActorCommandHandler(actorName: string, commandName: string, handler: Function, parameterTypes?: Array<string>): void; private getRegisteredCommands; /** * Actor broadcasts an event to subscribed agents (actor-side). Sent to DAO over WebSocket. */ broadcastActorEvent(actorName: string, eventName: string, data: any): Promise<void>; /** * Agent subscribes to an actor's event (agent-side). Sent to DAO over WebSocket; DAO forwards ACTOR_BROADCAST to this client. */ subscribeActorEvent(actorName: string, eventName: string, callback: (data: any) => void): void; /** * Create or get an actor * If options (metadata) are provided, connects and authenticates as this actor. * If only name is provided, returns a handle for an agent to interact with. */ /** Fetch actor record from DAO/Supabase (id, info, device_id, state, registeredCommands). Agent-only. */ getActorInfo(actorName: string): Promise<ActorRecord | null>; actor(name: string, options?: any): Promise<Actor>; /** * Get a scene */ scene(sceneId: string): Scene; /** * Run a command on an actor */ runCommand(actorName: string, commandName: string, args: any[]): Promise<any>; /** * Run a workflow */ workflow(workflowName: string, args?: any): Promise<any>; /** * Upload an image */ upload_image(image: any, filename?: string): Promise<string>; /** * Add a record */ add_record(data: any, name?: string): Promise<string>; /** * List available workflows on the server, including their definitions (OpenAI Tool Schema) */ list_workflows(): Promise<WorkflowDefinition[]>; /** * Helper to register commands that might have been added via actor.on() * *before* the initial authentication for that actor completed. */ private registerPendingCommands; getIsAuthenticated(): boolean; getActorName(): string | undefined; getDebug(): boolean; /** * Disconnects the WebSocket if the SDK is currently authenticated as the specified actor. * @param actorName The name of the actor to disconnect. */ disconnectIfActor(actorName: string): void; } export default Vitrus;