aionboarding/ai-patient-onboarding/docs/FRONTEND_EXAMPLES.md

Frontend Developer Integration Examples (React & TypeScript)

Language: TypeScript / JavaScript (React 18+)

---

1. Complete API Client (src/api/client.ts)

const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';

export interface PatientContext {
  id: string;
  name?: string;
  age?: number;
  gender?: string;
  phone?: string;
  abha_id?: string;
  insurance_scheme?: string;
  dietary_habits?: string;
}

export interface CategoryContext {
  type: 'general' | 'speciality';
  code: string;
  name: string;
}

export interface StartOnboardingResponse {
  success: boolean;
  session_id: string;
  patient_id: string;
  category: CategoryContext;
  language: string;
  status: string;
  stage: string;
  message: string;
}

export interface SendMessageResponse {
  success: boolean;
  session_id: string;
  stage: string;
  message: string;
  status: string;
  response_time_ms?: number;
  response_time_sec?: number;
}

export interface CompleteOnboardingResponse {
  success: boolean;
  session_id: string;
  status: string;
  result?: any;
  message: string;
  response_time_ms?: number;
  response_time_sec?: number;
}

/**
 * Generic Fetch Wrapper with Authorization & Error Handling
 */
async function fetchApi<T>(endpoint: string, options: RequestInit = {}, patientId: string): Promise<T> {
  const token = `test_token_${patientId}`;
  const headers = new Headers(options.headers || {});
  headers.set('Authorization', `Bearer ${token}`);
  if (!(options.body instanceof FormData)) {
    headers.set('Content-Type', 'application/json');
  }

  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    ...options,
    headers,
  });

  if (!response.ok) {
    const errorBody = await response.json().catch(() => ({ detail: 'Network response error' }));
    throw new Error(errorBody.detail || `HTTP Error ${response.status}`);
  }

  return response.json();
}

/**
 * Start Text Onboarding Session
 */
export async function startOnboarding(
  patient: PatientContext,
  category: CategoryContext,
  language: string = 'en'
): Promise<StartOnboardingResponse> {
  return fetchApi<StartOnboardingResponse>(
    '/v1/onboarding/start',
    {
      method: 'POST',
      body: JSON.stringify({ patient, category, language }),
    },
    patient.id
  );
}

/**
 * Send Intake Chat Message
 */
export async function sendMessage(
  sessionId: string,
  patientId: string,
  message: string
): Promise<SendMessageResponse> {
  return fetchApi<SendMessageResponse>(
    `/v1/onboarding/${sessionId}/message`,
    {
      method: 'POST',
      body: JSON.stringify({ message }),
    },
    patientId
  );
}

/**
 * Upload Medical Document (Report / Prescription)
 */
export async function uploadDocument(
  sessionId: string,
  patientId: string,
  file: File
): Promise<any> {
  const formData = new FormData();
  formData.append('file', file);

  return fetchApi<any>(
    `/v1/documents/${sessionId}/upload`,
    {
      method: 'POST',
      body: formData,
    },
    patientId
  );
}

/**
 * Finalize Session & Extract Structured EHR
 */
export async function completeOnboarding(
  sessionId: string,
  patientId: string,
  confirmed: boolean = true
): Promise<CompleteOnboardingResponse> {
  return fetchApi<CompleteOnboardingResponse>(
    `/v1/onboarding/${sessionId}/complete`,
    {
      method: 'POST',
      body: JSON.stringify({ confirmed }),
    },
    patientId
  );
}

---

2. Voice Onboarding Hook (src/hooks/useVoiceOnboarding.ts)

import { useState, useRef } from 'react';

export function useVoiceOnboarding(patientId: string) {
  const [sessionId, setSessionId] = useState<string | null>(null);
  const [isRecording, setIsRecording] = useState(false);
  const [isPlayingAudio, setIsPlayingAudio] = useState(false);
  const mediaRecorderRef = useRef<MediaRecorder | null>(null);
  const audioChunksRef = useRef<Blob[]>([]);

  const startVoiceSession = async (patient: any, language: string = 'en-IN') => {
    const res = await fetch('http://localhost:8000/v1/voice-onboarding/start', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer test_token_${patientId}`,
      },
      body: JSON.stringify({
        patient,
        category: { type: 'general', code: 'general_medicine', name: 'General Medicine' },
        language,
      }),
    });
    const data = await res.json();
    setSessionId(data.session_id);
    if (data.audio_url) {
      playAudioResponse(data.audio_url);
    }
    return data;
  };

  const playAudioResponse = (audioUrl: string) => {
    setIsPlayingAudio(true);
    const audio = new Audio(`http://localhost:8000${audioUrl}`);
    audio.onended = () => setIsPlayingAudio(false);
    audio.onerror = () => setIsPlayingAudio(false);
    audio.play();
  };

  const startRecording = async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
    const mediaRecorder = new MediaRecorder(stream);
    mediaRecorderRef.current = mediaRecorder;
    audioChunksRef.current = [];

    mediaRecorder.ondataavailable = (event) => {
      if (event.data.size > 0) audioChunksRef.current.push(event.data);
    };

    mediaRecorder.start();
    setIsRecording(true);
  };

  const stopRecordingAndSend = async () => {
    if (!mediaRecorderRef.current || !sessionId) return;

    return new Promise((resolve) => {
      mediaRecorderRef.current!.onstop = async () => {
        setIsRecording(false);
        const audioBlob = new Blob(audioChunksRef.current, { type: 'audio/wav' });
        const formData = new FormData();
        formData.append('audio', audioBlob, 'speech.wav');

        const res = await fetch(`http://localhost:8000/v1/voice-onboarding/${sessionId}/turn`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer test_token_${patientId}`,
          },
          body: formData,
        });

        const turnData = await res.json();
        if (turnData.audio_url) {
          playAudioResponse(turnData.audio_url);
        }
        resolve(turnData);
      };

      mediaRecorderRef.current!.stop();
    });
  };

  return {
    sessionId,
    isRecording,
    isPlayingAudio,
    startVoiceSession,
    startRecording,
    stopRecordingAndSend,
  };
}