Skip to main content

TypeScript Type Definitions

TypeScript interfaces and type definitions for entities, API responses, and service contracts in the UIP Backend.

Overview​

graph TB
    subgraph Types
        ENT[Entity Types]
        API[API Types]
        SVC[Service Types]
        AGENT[Agent Types]
    end
    
    subgraph Consumers
        ROUTES[Routes]
        SERVICES[Services]
        AGENTS[Agents]
        UTILS[Utilities]
    end
    
    ENT --> ROUTES
    ENT --> SERVICES
    API --> ROUTES
    SVC --> SERVICES
    AGENT --> AGENTS

Entity Types​

Camera​

export interface Camera {
  id: string;
  name: string;
  location: GeoLocation;
  imageUrl?: string;
  streamUrl?: string;
  status: 'online' | 'offline' | 'maintenance';
  type?: string;
  district?: string;
  dateModified?: string;
}

Weather​

export interface Weather {
  id: string;
  location: GeoLocation;
  temperature?: number;
  humidity?: number;
  precipitation?: number;
  windSpeed?: number;
  windDirection?: number;
  weatherType?: string;
  observedAt: string;
}

Air Quality​

export interface AirQuality {
  id: string;
  location: GeoLocation;
  aqi: number;
  category: string;
  pm25?: number;
  pm10?: number;
  o3?: number;
  no2?: number;
  co?: number;
  so2?: number;
  observedAt: string;
}

Accident​

export interface Accident {
  id: string;
  location: GeoLocation;
  severity: 'minor' | 'moderate' | 'severe';
  description?: string;
  vehiclesInvolved?: number;
  casualties?: number;
  status: 'active' | 'resolved' | 'pending';
  reportedAt: string;
  resolvedAt?: string;
}

Traffic Pattern​

export interface TrafficPattern {
  id: string;
  patternType: string;
  timeOfDay?: string;
  dayOfWeek?: string;
  congestionLevel?: number;
  averageSpeed?: number;
  vehicleCount?: number;
  confidence?: number;
  detectedAt: string;
}

Common Types​

GeoLocation​

export interface GeoLocation {
  latitude: number;
  longitude: number;
}

BoundingBox​

export interface BoundingBox {
  minLat: number;
  minLon: number;
  maxLat: number;
  maxLon: number;
}

GeoJSON Point​

export interface GeoJSONPoint {
  type: 'Point';
  coordinates: [number, number];  // [longitude, latitude]
}

Pagination​

export interface PaginationParams {
  limit: number;
  offset: number;
}

export interface PaginatedResponse<T> {
  data: T[];
  total: number;
  limit: number;
  offset: number;
  hasMore: boolean;
}

API Response Types​

Standard Response​

export interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: ApiError;
  timestamp: string;
}

export interface ApiError {
  message: string;
  code: string;
  details?: any;
}

Health Check Response​

export interface HealthCheckResponse {
  status: 'healthy' | 'degraded' | 'unhealthy';
  timestamp: string;
  uptime: number;
  services: Record<string, ServiceHealth>;
}

export interface ServiceHealth {
  status: 'connected' | 'error' | 'timeout';
  latency?: number;
  error?: string;
}

Agent Types​

Agent Request​

export interface AgentRequest {
  message: string;
  location: GeoLocation;
  context?: AgentContext;
  userProfile?: UserProfile;
}

export interface AgentContext {
  conversationHistory?: Message[];
  sessionId?: string;
  preferences?: Record<string, any>;
}

export interface UserProfile {
  id: string;
  healthConditions?: string[];
  transportMode?: 'walking' | 'cycling' | 'driving' | 'transit';
  preferences?: string[];
}

Agent Response​

export interface AgentResponse {
  message: string;
  type: 'text' | 'analysis' | 'recommendation' | 'alert';
  data?: any;
  sources?: Source[];
  confidence?: number;
}

export interface Source {
  type: 'camera' | 'sensor' | 'api' | 'database';
  id: string;
  name?: string;
  url?: string;
}

Multi-Agent Response​

export interface MultiAgentResponse {
  synthesis: string;
  agents: {
    ecoTwin?: AgentResponse;
    graphInvestigator?: AgentResponse;
    trafficMaestro?: AgentResponse;
  };
  executionTime: number;
}

Service Types​

NGSI-LD Entity​

export interface NgsiLdEntity {
  id: string;
  type: string;
  '@context'?: string | string[];
  [property: string]: NgsiLdProperty | NgsiLdRelationship | any;
}

export interface NgsiLdProperty {
  type: 'Property';
  value: any;
  observedAt?: string;
  unitCode?: string;
}

export interface NgsiLdRelationship {
  type: 'Relationship';
  object: string;
}

export interface NgsiLdGeoProperty {
  type: 'GeoProperty';
  value: GeoJSONPoint;
}

Query Parameters​

export interface EntityQueryParams {
  type?: string;
  q?: string;
  georel?: string;
  geometry?: string;
  coordinates?: string;
  limit?: number;
  offset?: number;
  attrs?: string;
}

WebSocket Types​

export interface WebSocketMessage {
  type: 'entity_update' | 'alert' | 'status' | 'error';
  payload: any;
  timestamp: string;
}

export interface Subscription {
  id: string;
  entityTypes: string[];
  watchedAttributes?: string[];
  geoQuery?: {
    georel: string;
    geometry: string;
    coordinates: string;
  };
}

Usage​

// Import types
import { Camera, GeoLocation, ApiResponse } from '../types';

// Use in route handlers
router.get('/cameras', async (req, res) => {
  const cameras: Camera[] = await cameraService.getAll();
  const response: ApiResponse<Camera[]> = {
    success: true,
    data: cameras,
    timestamp: new Date().toISOString()
  };
  res.json(response);
});

// Use in services
async function getNearbyEntities<T>(
  type: string,
  location: GeoLocation,
  maxDistance: number
): Promise<T[]> {
  // ...
}

References​