dougbot/bridge/src/protocol.ts

/**
 * Shared protocol types for Python <-> Node.js WebSocket communication.
 * Both sides must agree on these message formats.
 */

// ============================================================
// Message Envelope Types
// ============================================================

export interface RequestMessage {
  id: string;
  type: 'request';
  action: string;
  params: Record<string, any>;
}

export interface ResponseMessage {
  id: string;
  type: 'response';
  status: 'success' | 'error';
  data: Record<string, any>;
  error?: string;
}

export interface EventMessage {
  type: 'event';
  event: string;
  data: Record<string, any>;
  timestamp: number;
}

export type BridgeMessage = RequestMessage | ResponseMessage | EventMessage;

// ============================================================
// Action Types (Python -> Node requests)
// ============================================================

export type ActionType =
  // Connection
  | 'connect'
  | 'disconnect'
  | 'status'
  // Movement
  | 'move_to'
  | 'jump'
  | 'sprint'
  | 'sneak'
  | 'stop'
  | 'look_at'
  // Blocks
  | 'place_block'
  | 'break_block'
  | 'get_block_at'
  // Inventory
  | 'get_inventory'
  | 'equip'
  | 'drop'
  | 'swap_slots'
  | 'use_item'
  // Combat
  | 'attack_entity'
  | 'use_shield'
  | 'eat'
  // Interaction
  | 'open_container'
  | 'close_container'
  | 'trade_with'
  | 'craft'
  // Chat
  | 'send_chat'
  // World Queries
  | 'get_nearby_entities'
  | 'get_nearby_blocks'
  | 'get_time'
  | 'get_health'
  | 'get_position';

// ============================================================
// Event Types (Node -> Python unsolicited)
// ============================================================

export type EventType =
  | 'chat_message'
  | 'health_changed'
  | 'entity_spawned'
  | 'entity_removed'
  | 'player_joined'
  | 'player_left'
  | 'block_changed'
  | 'damage_taken'
  | 'death'
  | 'inventory_changed'
  | 'time_update'
  | 'spawn_complete'
  | 'connected'
  | 'disconnected'
  | 'error'
  | 'auth_device_code'
  | 'movement_complete';

// ============================================================
// Data Structures
// ============================================================

export interface Vec3 {
  x: number;
  y: number;
  z: number;
}

export interface EntityData {
  id: number | bigint;
  type: string;
  name?: string;
  position: Vec3;
  health?: number;
}

export interface ItemData {
  id: number;
  name: string;
  count: number;
  slot: number;
  metadata?: number;
}

export interface BlockData {
  position: Vec3;
  name: string;
  id: number;
}

export interface PlayerData {
  username: string;
  position?: Vec3;
  entityId?: number | bigint;
}

// ============================================================
// Helper: Create messages
// ============================================================

export function createResponse(
  requestId: string,
  status: 'success' | 'error',
  data: Record<string, any> = {},
  error?: string
): ResponseMessage {
  return { id: requestId, type: 'response', status, data, error };
}

export function createEvent(
  event: EventType,
  data: Record<string, any> = {}
): EventMessage {
  return { type: 'event', event, data, timestamp: Date.now() };
}