localgreenchain/lib/realtime/types.ts

/**
 * Real-Time System Types for LocalGreenChain
 *
 * Defines all types used in the WebSocket/SSE real-time communication system.
 */

import type { TransparencyEventType, EventPriority, TransparencyEvent } from '../transparency/EventStream';

// Re-export for convenience
export type { TransparencyEventType, EventPriority, TransparencyEvent };

/**
 * Room types for Socket.io subscriptions
 */
export type RoomType =
  | 'global'           // All events
  | 'plants'           // All plant events
  | 'transport'        // All transport events
  | 'farms'            // All farm events
  | 'demand'           // All demand events
  | 'system'           // System events
  | `plant:${string}`  // Specific plant
  | `farm:${string}`   // Specific farm
  | `user:${string}`;  // User-specific events

/**
 * Connection status states
 */
export type ConnectionStatus =
  | 'connecting'
  | 'connected'
  | 'disconnected'
  | 'reconnecting'
  | 'error';

/**
 * Socket authentication payload
 */
export interface SocketAuthPayload {
  userId?: string;
  token?: string;
  sessionId?: string;
}

/**
 * Socket handshake data
 */
export interface SocketHandshake {
  auth: SocketAuthPayload;
  rooms?: RoomType[];
}

/**
 * Client-to-server events
 */
export interface ClientToServerEvents {
  // Room management
  'room:join': (room: RoomType, callback?: (success: boolean) => void) => void;
  'room:leave': (room: RoomType, callback?: (success: boolean) => void) => void;

  // Event subscriptions
  'subscribe:types': (types: TransparencyEventType[], callback?: (success: boolean) => void) => void;
  'unsubscribe:types': (types: TransparencyEventType[], callback?: (success: boolean) => void) => void;

  // Ping for connection health
  'ping': (callback: (timestamp: number) => void) => void;

  // Request recent events
  'events:recent': (limit: number, callback: (events: TransparencyEvent[]) => void) => void;
}

/**
 * Server-to-client events
 */
export interface ServerToClientEvents {
  // Real-time events
  'event': (event: TransparencyEvent) => void;
  'event:batch': (events: TransparencyEvent[]) => void;

  // Connection status
  'connection:established': (data: { socketId: string; serverTime: number }) => void;
  'connection:error': (error: { code: string; message: string }) => void;

  // Room notifications
  'room:joined': (room: RoomType) => void;
  'room:left': (room: RoomType) => void;

  // System messages
  'system:message': (message: { type: 'info' | 'warning' | 'error'; text: string }) => void;
  'system:heartbeat': (timestamp: number) => void;
}

/**
 * Inter-server events (for scaling)
 */
export interface InterServerEvents {
  'event:broadcast': (event: TransparencyEvent, rooms: RoomType[]) => void;
}

/**
 * Socket data attached to each connection
 */
export interface SocketData {
  userId?: string;
  sessionId: string;
  connectedAt: number;
  rooms: Set<RoomType>;
  subscribedTypes: Set<TransparencyEventType>;
}

/**
 * Real-time notification for UI display
 */
export interface RealtimeNotification {
  id: string;
  type: 'success' | 'info' | 'warning' | 'error';
  title: string;
  message: string;
  timestamp: number;
  eventType?: TransparencyEventType;
  data?: Record<string, unknown>;
  read: boolean;
  dismissed: boolean;
}

/**
 * Connection metrics for monitoring
 */
export interface ConnectionMetrics {
  status: ConnectionStatus;
  connectedAt?: number;
  lastEventAt?: number;
  eventsReceived: number;
  reconnectAttempts: number;
  latency?: number;
  rooms: RoomType[];
}

/**
 * Live feed item for display
 */
export interface LiveFeedItem {
  id: string;
  event: TransparencyEvent;
  timestamp: number;
  formatted: {
    title: string;
    description: string;
    icon: string;
    color: string;
  };
}