API Documentation

// Recommended authentication middleware
import { BearerTokenAuthenticationPolicy } from '@azure/core-auth';

app.use('/api', async (req, res, next) => {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '');
    if (!token) {
      return res.status(401).json({ error: 'Authentication required' });
    }
    
    // Validate Azure AD token
    const credentials = new DefaultAzureCredential();
    const tokenInfo = await credentials.getToken(['https://graph.microsoft.com/.default']);
    
    // Add user context to request
    req.user = await validateAndDecodeToken(token);
    next();
  } catch (error) {
    return res.status(401).json({ error: 'Invalid authentication token' });
  }
});

// Alternative API key authentication
app.use('/api', (req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey || !validateApiKey(apiKey)) {
    return res.status(401).json({ error: 'Valid API key required' });
  }
  next();
});

// Current CORS configuration
app.use(cors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || '*',
  methods: ['GET', 'POST', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
  credentials: true
}));

interface HealthCheckResponse {
  status: 'OK' | 'DEGRADED' | 'UNHEALTHY';
  timestamp: string;
  version: string;
  environment: string;
  dependencies: {
    mcp_servers: Record<string, 'healthy' | 'unhealthy' | 'unknown'>;
    external_services: Record<string, 'healthy' | 'unhealthy' | 'unknown'>;
  };
  performance?: {
    response_time_ms: number;
    memory_usage_mb: number;
    cpu_usage_percent: number;
  };
}

interface ChatRequest {
  message: string;
  tools: ToolSelection[];
  context?: {
    conversation_id?: string;
    user_preferences?: UserPreferences;
    session_data?: Record<string, any>;
  };
  options?: {
    stream?: boolean;
    max_tokens?: number;
    temperature?: number;
    timeout_ms?: number;
  };
}

interface ToolSelection {
  id: string;
  name: string;
  selected: boolean;
  configuration?: Record<string, any>;
}

interface UserPreferences {
  language?: string;
  currency?: string;
  measurement_system?: 'metric' | 'imperial';
  accessibility_needs?: string[];
  dietary_restrictions?: string[];
}

interface SSEEvent {
  type: 'metadata' | 'stream' | 'error' | 'end';
  agent?: string;
  event?: string;
  data: any;
  timestamp?: string;
}

interface MetadataEvent {
  type: 'metadata';
  agent: string;
  event: 'AgentSetup' | 'AgentInput' | 'AgentOutput' | 'AgentStream' | 
         'AgentStepEvent' | 'AgentToolCall' | 'ToolResultsEvent' | 
         'ToolCallsEvent' | 'AgentHandoff';
  data: Record<string, any>;
}

interface StreamEvent {
  type: 'stream';
  data: {
    content: string;
    metadata?: Record<string, any>;
  };
}

interface ErrorEvent {
  type: 'error';
  data: {
    error: string;
    code?: string;
    agent?: string;
    tool?: string;
    recoverable: boolean;
  };
}

interface EndEvent {
  type: 'end';
  data: {
    conversation_id?: string;
    total_processing_time_ms: number;
    tokens_used?: number;
    agents_used: string[];
    tools_called: string[];
  };
}

interface UserMessage {
  content: string;
  timestamp: Date;
  metadata?: {
    language?: string;
    source?: 'web' | 'mobile' | 'api';
    user_agent?: string;
  };
}

interface AgentResponse {
  agent_name: string;
  content: string;
  confidence_score?: number;
  sources?: Source[];
  metadata: {
    processing_time_ms: number;
    tokens_used?: number;
    tools_called: string[];
  };
}

interface ToolCall {
  tool_name: string;
  server_id: string;
  input: Record<string, any>;
  output?: Record<string, any>;
  execution_time_ms: number;
  success: boolean;
  error?: string;
}

interface TravelPreferences {
  destinations?: string[];
  budget?: {
    amount: number;
    currency: string;
    flexibility: 'strict' | 'flexible' | 'very_flexible';
  };
  duration?: {
    days: number;
    flexibility_days?: number;
  };
  dates?: {
    start_date?: Date;
    end_date?: Date;
    flexible?: boolean;
    peak_season_ok?: boolean;
  };
  group?: {
    size: number;
    composition: 'solo' | 'couple' | 'family' | 'friends' | 'business';
    ages?: number[];
  };
  accommodation?: {
    type: 'hotel' | 'airbnb' | 'hostel' | 'resort' | 'mixed';
    quality_level: 'budget' | 'mid-range' | 'luxury';
    amenities?: string[];
  };
  transportation?: {
    preferred_modes: string[];
    domestic_flights_ok: boolean;
    rental_car_needed: boolean;
  };
  activities?: {
    interests: string[];
    activity_level: 'low' | 'moderate' | 'high';
    cultural_experiences: boolean;
    outdoor_activities: boolean;
    nightlife: boolean;
  };
  constraints?: {
    dietary_restrictions?: string[];
    accessibility_needs?: string[];
    language_requirements?: string[];
    visa_restrictions?: string[];
  };
}

interface Destination {
  id: string;
  name: string;
  country: string;
  region?: string;
  coordinates: {
    latitude: number;
    longitude: number;
  };
  description: string;
  highlights: string[];
  best_time_to_visit: {
    months: string[];
    weather_info: string;
  };
  budget_estimates: {
    budget: { daily_cost: number; description: string; };
    mid_range: { daily_cost: number; description: string; };
    luxury: { daily_cost: number; description: string; };
  };
  activities: Activity[];
  practical_info: {
    languages: string[];
    currency: string;
    visa_required: boolean;
    safety_rating: number;
    internet_quality: 'poor' | 'fair' | 'good' | 'excellent';
  };
  metadata: {
    popularity_score: number;
    last_updated: Date;
    data_sources: string[];
  };
}

interface Itinerary {
  id: string;
  title: string;
  description: string;
  duration_days: number;
  destinations: string[];
  daily_plans: DailyPlan[];
  cost_estimate: CostEstimate;
  practical_info: {
    packing_suggestions: string[];
    health_recommendations: string[];
    cultural_tips: string[];
    emergency_contacts: EmergencyContact[];
  };
  metadata: {
    created_at: Date;
    last_modified: Date;
    version: string;
    customization_level: 'basic' | 'detailed' | 'comprehensive';
  };
}

interface DailyPlan {
  day: number;
  date?: Date;
  location: string;
  theme: string;
  activities: ScheduledActivity[];
  meals: MealRecommendation[];
  accommodation?: AccommodationInfo;
  transportation: TransportationSegment[];
  estimated_cost: number;
  alternatives: {
    weather_backup: ScheduledActivity[];
    budget_options: ScheduledActivity[];
  };
  notes: string[];
}

interface ScheduledActivity {
  id: string;
  name: string;
  description: string;
  location: {
    name: string;
    address: string;
    coordinates: { latitude: number; longitude: number; };
  };
  start_time: string; // HH:MM format
  duration_minutes: number;
  cost: number;
  booking_info?: {
    booking_required: boolean;
    booking_url?: string;
    booking_notes?: string;
  };
  difficulty_level: 'easy' | 'moderate' | 'challenging';
  weather_dependent: boolean;
  age_appropriate: number[]; // Minimum ages
  accessibility: {
    wheelchair_accessible: boolean;
    notes?: string;
  };
}

interface CostEstimate {
  currency: string;
  total: number;
  breakdown: {
    accommodation: number;
    transportation: {
      flights: number;
      local_transport: number;
      car_rental?: number;
    };
    activities: number;
    meals: number;
    shopping: number;
    miscellaneous: number;
  };
  per_person: number;
  per_day: number;
  confidence_level: number; // 0-1 score
  last_updated: Date;
  assumptions: string[];
  cost_saving_tips: string[];
}

interface APIError {
  error: string;
  code: string;
  message: string;
  details?: Record<string, any>;
  timestamp: string;
  request_id?: string;
  documentation_url?: string;
}

import rateLimit from 'express-rate-limit';

const chatLimiter = rateLimit({
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 50, // limit each IP to 50 requests per windowMs
  message: {
    error: 'RATE_LIMIT_EXCEEDED',
    code: 'TOO_MANY_REQUESTS',
    message: 'Rate limit exceeded for chat endpoint'
  },
  standardHeaders: true,
  legacyHeaders: false,
});

app.use('/api/chat', chatLimiter);

class ChatClient {
  async streamChat(message: string, tools: ToolSelection[]): Promise<AsyncIterable<SSEEvent>> {
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'text/event-stream',
      },
      body: JSON.stringify({ message, tools })
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    return {
      async *[Symbol.asyncIterator]() {
        try {
          while (true) {
            const { done, value } = await reader!.read();
            if (done) break;

            const chunk = decoder.decode(value);
            const lines = chunk.split('\n\n').filter(line => line.trim());

            for (const line of lines) {
              try {
                const event: SSEEvent = JSON.parse(line);
                yield event;
              } catch (e) {
                console.warn('Failed to parse SSE event:', line);
              }
            }
          }
        } finally {
          reader?.releaseLock();
        }
      }
    };
  }
}

// Usage example
const client = new ChatClient();
const stream = client.streamChat("Plan a trip to Japan", selectedTools);

for await (const event of stream) {
  switch (event.type) {
    case 'metadata':
      console.log(`Agent ${event.agent} event: ${event.event}`);
      break;
    case 'stream':
      console.log(`Response chunk: ${event.data.content}`);
      break;
    case 'error':
      console.error(`Error: ${event.data.error}`);
      break;
    case 'end':
      console.log('Processing completed');
      break;
  }
}

// SSE connection with automatic reconnection
class RobustChatClient {
  private maxRetries = 3;
  private retryDelay = 1000;

  async streamChatWithRetry(
    message: string, 
    tools: ToolSelection[],
    onEvent: (event: SSEEvent) => void,
    onError: (error: Error) => void
  ): Promise<void> {
    let attempts = 0;

    while (attempts < this.maxRetries) {
      try {
        const stream = await this.streamChat(message, tools);
        
        for await (const event of stream) {
          onEvent(event);
          
          if (event.type === 'end') {
            return; // Successful completion
          }
          
          if (event.type === 'error' && !event.data.recoverable) {
            throw new Error(event.data.error);
          }
        }
        
        return; // Stream ended normally
        
      } catch (error) {
        attempts++;
        
        if (attempts >= this.maxRetries) {
          onError(error as Error);
          return;
        }
        
        await new Promise(resolve => 
          setTimeout(resolve, this.retryDelay * attempts)
        );
      }
    }
  }
}

// NPM package: @azure-ai-travel-agents/client
import { TravelAgentsClient } from '@azure-ai-travel-agents/client';

const client = new TravelAgentsClient({
  baseUrl: 'https://your-api.azurecontainerapps.io/api',
  apiKey: 'your-api-key', // when authentication is implemented
  timeout: 30000,
  retries: 3
});

// Get available tools
const tools = await client.getTools();

// Stream chat response
for await (const event of client.streamChat(message, selectedTools)) {
  // Handle streaming events
}

// Non-streaming chat (convenience method)
const response = await client.chat(message, selectedTools);

import express from 'express';
import { TravelAgentsClient } from '@azure-ai-travel-agents/client';

const app = express();
const travelClient = new TravelAgentsClient({
  baseUrl: process.env.TRAVEL_API_URL
});

// Middleware to add travel planning capabilities
app.use('/api/travel', async (req, res, next) => {
  req.travelClient = travelClient;
  next();
});

// Endpoint to process travel requests
app.post('/api/travel/plan', async (req, res) => {
  const { message, preferences } = req.body;
  
  try {
    // Get available tools
    const availableTools = await req.travelClient.getTools();
    const selectedTools = availableTools.filter(tool => 
      ['customer-query', 'destination-recommendation', 'itinerary-planning']
        .includes(tool.id)
    );

    // Set up SSE response
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');

    // Stream response to client
    for await (const event of req.travelClient.streamChat(message, selectedTools)) {
      res.write(`data: ${JSON.stringify(event)}\n\n`);
    }

    res.end();
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// React Native with real-time chat
import { useState, useEffect } from 'react';

const useTravelChat = () => {
  const [client] = useState(() => new TravelAgentsClient({
    baseUrl: 'https://your-api.azurecontainerapps.io/api'
  }));

  const streamTravelPlan = async (
    message: string,
    onUpdate: (content: string) => void,
    onComplete: () => void,
    onError: (error: Error) => void
  ) => {
    try {
      const tools = await client.getTools();
      const selectedTools = tools.filter(tool => tool.selected);

      for await (const event of client.streamChat(message, selectedTools)) {
        switch (event.type) {
          case 'stream':
            onUpdate(event.data.content);
            break;
          case 'end':
            onComplete();
            break;
          case 'error':
            onError(new Error(event.data.error));
            break;
        }
      }
    } catch (error) {
      onError(error as Error);
    }
  };

  return { streamTravelPlan };
};

// Usage in component
export const TravelPlanScreen = () => {
  const [plan, setPlan] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const { streamTravelPlan } = useTravelChat();

  const handlePlanRequest = async (message: string) => {
    setIsLoading(true);
    setPlan('');

    await streamTravelPlan(
      message,
      (content) => setPlan(prev => prev + content),
      () => setIsLoading(false),
      (error) => {
        console.error('Planning error:', error);
        setIsLoading(false);
      }
    );
  };

  // Component JSX...
};