@rexai/pulse-react 1.0.1 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @rexai/pulse-react
 
-React SDK for rPPG health analysis - measure heart rate, HRV, SpO2, and more from any camera using remote photoplethysmography.
+React SDK for comprehensive health analysis - measure heart rate, HRV, SpO2, skin health, voice biomarkers, and eye health from any camera or microphone using AI-powered analysis.
 
 ## Installation
 
@@ -101,7 +101,7 @@ const client = new PulseClient({
   apiKey: 'pk_live_YOUR_API_KEY'
 });
 
-// Analyze a video blob
+// Analyze a video blob for medical vitals
 const vitals = await client.analyze({
   video: videoBlob,
   age: 30,
@@ -110,6 +110,35 @@ const vitals = await client.analyze({
 
 console.log(vitals.heart_rate);  // 72
 console.log(vitals.spo2);        // 98
+
+// Analyze beauty/skin metrics
+const beauty = await client.analyzeBeauty({
+  video: videoBlob,
+  age: 30,
+  gender: 'female'
+});
+
+console.log(beauty.summary.skin_age);  // 28
+console.log(beauty.surface.hydration); // 75
+
+// Analyze voice for health biomarkers
+const voice = await client.analyzeVoice({
+  audio: audioBlob
+});
+
+console.log(voice.stress_score);       // 35
+console.log(voice.respiratory_rate);   // 16
+console.log(voice.wellness_score);     // 72
+
+// Analyze eye health
+const eye = await client.analyzeEye({
+  video: videoBlob
+});
+
+console.log(eye.overall_score);        // 85
+console.log(eye.cataract.risk_level);  // "low"
+console.log(eye.red_eye.is_inflamed);  // false
+console.log(eye.recommendations);      // ["Maintain regular eye exams", ...]
 ```
 
 ## Hooks
@@ -130,6 +159,8 @@ function CustomScanner() {
 
 ## Vitals Returned
 
+### Medical Analysis (`analyze`)
+
 | Metric | Type | Description |
 |--------|------|-------------|
 | `heart_rate` | number | Heart rate in BPM |
@@ -142,6 +173,41 @@ function CustomScanner() {
 | `recovery_score` | number | Recovery score % |
 | `vascular_age` | number | Estimated vascular age |
 
+### Voice Analysis (`analyzeVoice`)
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `stress_score` | number | Voice stress score (0-100) |
+| `fatigue_score` | number | Fatigue indicator (0-100) |
+| `anxiety_level` | string | Anxiety level (low/mild/moderate/high) |
+| `respiratory_rate` | number | Breathing rate from audio |
+| `respiratory_health` | number | Respiratory health score |
+| `cough_detected` | boolean | Cough presence detected |
+| `depression_risk` | string | Depression risk indicator |
+| `cognitive_load` | string | Mental load level |
+| `wellness_score` | number | Overall wellness (0-100) |
+| `composite_scores` | object | Mental, physical, cognitive, resilience scores |
+
+### Eye Analysis (`analyzeEye`)
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `overall_score` | number | Overall eye health score (0-100) |
+| `health_level` | string | Health level (Excellent/Good/Fair/Needs Attention) |
+| `cataract` | object | Cataract screening results |
+| `cataract.opacity_score` | number | Lens opacity measurement (0-100) |
+| `cataract.risk_level` | string | Risk level (low/mild/moderate/high) |
+| `red_eye` | object | Red eye/inflammation detection |
+| `red_eye.redness_score` | number | Redness measurement (0-100) |
+| `red_eye.is_inflamed` | boolean | Inflammation detected |
+| `lens_clarity` | object | Lens clarity assessment |
+| `pupil` | object | Pupil analysis results |
+| `pterygium` | object | Pterygium detection |
+| `stye` | object | Stye/chalazion detection |
+| `sclera` | object | Sclera health (yellowing/jaundice risk) |
+| `recommendations` | string[] | Personalized recommendations |
+| `analysis_confidence` | number | Analysis confidence % |
+
 ## Getting an API Key
 
 Contact us for API access or visit the developer portal to generate your API key.

package/dist/index.d.mts

@@ -2,130 +2,346 @@ import React$1 from 'react';
 
 /**
  * PulseAI SDK Type Definitions
+ *
+ * Version: 2.1.0
+ *
+ * IMPORTANT: Many metrics now return `null` when calculation fails.
+ * Always check for null before displaying values.
  */
+interface BloodPressureFeatures {
+    rise_time_ms: number | null;
+    pulse_amplitude: number | null;
+    pulse_width_ms: number | null;
+    augmentation_index: number | null;
+    pulses_analyzed: number;
+}
 interface BloodPressure {
-    systolic: number;
-    diastolic: number;
+    systolic: number | null;
+    diastolic: number | null;
+    pulse_pressure: number | null;
+    confidence: 'high' | 'moderate' | 'low' | 'very_low' | null;
+    features?: BloodPressureFeatures;
+    methodology?: string;
+    note?: string;
+    error?: string;
+}
+interface SpO2MethodResult {
+    spo2: number;
+    ratio: number;
+    quality: number;
+}
+interface SpO2Result {
+    spo2: number | null;
+    confidence: 'high' | 'moderate' | 'low' | 'very_low' | null;
+    method_used: 'red_blue' | 'green_red' | null;
+    signal_quality: number | null;
+    methods?: {
+        red_blue?: SpO2MethodResult;
+        green_red?: SpO2MethodResult;
+    };
+    error?: string;
 }
 interface ArrhythmiaResult {
-    has_arrhythmia: boolean;
-    irregularity_score: number;
-    details: string;
+    has_arrhythmia: boolean | null;
+    irregularity_score: number | null;
+    confidence: number | null;
+    details: string | null;
+}
+interface StressResult {
+    score: number | null;
+    level: 'low' | 'mild' | 'moderate' | 'high' | null;
+    confidence: number | null;
+    rmssd_ms: number | null;
+}
+interface RecoveryResult {
+    score: number | null;
+    level: 'poor' | 'moderate' | 'good' | 'excellent' | null;
+    rmssd_ms: number | null;
+}
+interface RespiratoryResult {
+    rate: number | null;
+    confidence: 'high' | 'moderate' | 'low' | null;
+    signal_quality: number | null;
+    breaths_detected: number | null;
+    interval_variability: number | null;
+    error?: string;
+}
+interface VascularAgeResult {
+    vascular_age: number | null;
+    chronological_age: number | null;
+    difference_years: number | null;
+    status: 'younger_than_chronological' | 'close_to_chronological' | 'moderately_elevated' | 'significantly_elevated' | null;
+    methodology?: string;
+}
+interface BMIEstimate {
+    value: number | null;
+    category: 'Underweight' | 'Normal' | 'Overweight' | 'Obese' | null;
+    confidence: 'high' | 'moderate' | 'low' | 'very_low' | 'invalid' | null;
+    fwhr: number | null;
+    source?: 'manual_input' | 'facial_estimation';
+    methodology?: string;
+    note?: string;
+    reason?: string;
+}
+interface SkinTemperatureResult {
+    value: number | null;
+    unit: string;
+    ratio: number | null;
+    confidence: 'proxy_only' | 'invalid_ratio';
+    note?: string;
+}
+interface FatigueIndicators {
+    eye_redness: number | null;
+    under_eye_darkness: number | null;
+    puffiness: number | null;
+    overall_fatigue: string | null;
+}
+interface SkinHealth {
+    evenness: number | null;
+    redness: number | null;
+    oiliness_proxy: number | null;
 }
 interface VisualAnalysis {
-    jaundice_risk: 'Low' | 'Medium' | 'High';
-    anemia_risk: 'Low' | 'Medium' | 'High';
-    bilirubin_proxy: number;
-    pallor_index: number;
-    hydration_level?: string;
-    hydration_score?: number;
-    fatigue_indicators?: {
-        eye_redness: number;
-        under_eye_darkness: number;
-        puffiness: number;
-        overall_fatigue: string;
-    };
-    skin_health?: {
-        evenness: number;
-        redness: number;
-        oiliness_proxy: number;
-    };
+    jaundice_risk: 'Low' | 'Medium' | 'High' | null;
+    anemia_risk: 'Low' | 'Medium' | 'High' | null;
+    bilirubin_proxy: number | null;
+    pallor_index: number | null;
+    hydration_level?: string | null;
+    hydration_score?: number | null;
+    texture_score?: number | null;
+    fatigue_indicators?: FatigueIndicators;
+    skin_health?: SkinHealth;
+}
+interface MentalWellnessComponents {
+    blink_score: number | null;
+    gaze_score: number | null;
+    emotion_score: number | null;
+    hrv_score: number | null;
 }
 interface MentalWellness {
-    wellness_score: number;
-    level: string;
-    emotion: string;
-    emotion_confidence?: number;
-    blink_rate_per_min: number;
-    gaze_stability: number;
-    gaze_direction?: string;
-    components: {
-        blink_score: number;
-        gaze_score: number;
-        emotion_score: number;
-        hrv_score: number;
-    };
+    wellness_score: number | null;
+    level: string | null;
+    emotion: string | null;
+    emotion_confidence?: number | null;
+    blink_rate_per_min: number | null;
+    gaze_stability: number | null;
+    gaze_direction?: string | null;
+    components: MentalWellnessComponents | null;
 }
-interface CompositeScores {
-    cardio_score: number;
-    resilience_score: number;
-    metabolic_score: number;
-    vitality_score: number;
+interface CompositeScoreDetails {
+    cardio?: string[];
+    resilience?: string[];
+    metabolic?: string[];
+    vitality?: string[];
 }
-interface BMIEstimate {
-    value: number;
-    category: string;
-    fwhr: number;
-    confidence?: string;
-    method?: string;
+interface CompositeScores {
+    cardio_score: number | null;
+    resilience_score: number | null;
+    metabolic_score: number | null;
+    vitality_score: number | null;
+    calculation_details?: CompositeScoreDetails;
+    bmi_used?: number;
 }
 interface VitalsResult {
-    heart_rate: number;
-    respiratory_rate: number;
-    hrv_sdnn: number;
-    hrv_rmssd: number;
-    recovery_score: number;
-    stress_index: number;
-    arrhythmia: ArrhythmiaResult;
-    rsa_amplitude: number;
-    blood_pressure: BloodPressure;
-    spo2: number;
-    signal_snippet: number[];
-    vascular_age: number;
-    bmi_est: BMIEstimate;
+    heart_rate: number | null;
+    hr_confidence?: 'high' | 'moderate' | 'low' | 'very_low' | null;
+    hr_snr_db?: number | null;
+    respiratory_rate: RespiratoryResult | number | null;
+    hrv_sdnn: number | null;
+    hrv_rmssd: number | null;
+    stress_index: StressResult | number | null;
+    recovery_score: RecoveryResult | number | null;
+    arrhythmia: ArrhythmiaResult | null;
+    rsa_amplitude: number | null;
+    blood_pressure: BloodPressure | null;
+    spo2: SpO2Result | number | null;
+    vascular_age: VascularAgeResult | number | null;
+    bmi_est: BMIEstimate | null;
     manual_bmi?: number;
-    metabolic_score: number;
-    skin_temperature: number;
-    composite_scores: CompositeScores;
-    visual_analysis?: VisualAnalysis;
-    mental_wellness?: MentalWellness;
-    fusion_weights: Record<string, number>;
+    skin_temperature: SkinTemperatureResult | number | null;
+    composite_scores: CompositeScores | null;
+    visual_analysis?: VisualAnalysis | null;
+    mental_wellness?: MentalWellness | null;
+    signal_snippet?: number[];
+    fusion_weights?: Record<string, number>;
+    metadata?: {
+        video_fps?: number;
+        frames_analyzed?: number;
+    };
+    error?: string | null;
 }
 interface BeautySummary {
-    overall_score: number;
-    skin_age: number;
+    overall_score: number | null;
+    skin_age: number | null;
+    age_provided: boolean;
+    age_difference?: number;
+    calculation_details?: Record<string, number>;
+    skin_age_note?: string;
+    error?: string;
 }
 interface BeautySurface {
-    texture: number;
-    hydration: number;
-    foundation_hex: string;
-    undertone: string;
-    acne_count: number;
-    acne_severity: string;
-    wrinkle_severity: string;
-    wrinkle_density: number;
-    oiliness_index: number;
-    matches: string;
-    skin_health: {
-        evenness: number;
-        redness: number;
-        oiliness_proxy: number;
-    };
+    texture: number | null;
+    hydration: number | null;
+    foundation_hex: string | null;
+    undertone: 'warm' | 'cool' | null;
+    acne_count: number | null;
+    acne_severity: 'minimal' | 'mild' | 'moderate' | 'significant' | null;
+    wrinkle_severity: 'minimal' | 'mild' | 'moderate' | 'significant' | null;
+    wrinkle_density: number | null;
+    oiliness_index: number | null;
+    matches: string | null;
+    skin_health: SkinHealth | null;
+}
+interface PtosisIndices {
+    status: 'none' | 'mild' | 'significant' | null;
+    youth_ratio?: number | null;
+    eye_openness?: number | null;
 }
 interface BeautyGeometry {
-    symmetry_score: number;
-    face_shape: string;
-    eye_openness: number;
-    ptosis_indices: {
-        status: string;
-        youth_ratio?: number;
-    };
+    symmetry_score: number | null;
+    face_shape: 'oval' | 'round' | 'square' | 'oblong' | null;
+    landmarks?: any;
+    ptosis_indices: PtosisIndices;
+    analysis_confidence?: 'high' | 'moderate' | 'low';
+    error?: string;
 }
 interface BeautyPhysiology {
-    glow_index: number;
-    stress_level: string;
-    elasticity: number;
+    glow_index: number | null;
+    stress_level: 'low' | 'moderate' | 'high' | null;
+    elasticity: number | null;
+    heart_rate?: number | null;
 }
 interface BeautyRecommendations {
     routine: string[];
     tips: string[];
+    foundation?: string | null;
 }
 interface BeautyResult {
-    summary: BeautySummary;
-    surface: BeautySurface;
-    geometry: BeautyGeometry;
-    physiology: BeautyPhysiology;
-    recommendations: BeautyRecommendations;
+    summary: BeautySummary | null;
+    surface: BeautySurface | null;
+    geometry: BeautyGeometry | null;
+    physiology: BeautyPhysiology | null;
+    recommendations: BeautyRecommendations | null;
+    meta?: {
+        rppg_source: string;
+        beauty_engine: string;
+    };
+    error?: string | null;
+}
+interface VoiceCompositeScores {
+    mental_score: number | null;
+    physical_score: number | null;
+    cognitive_score: number | null;
+    resilience_score: number | null;
+}
+interface VoiceMoodIndicators {
+    pitch_monotony?: 'high' | 'moderate' | 'low';
+    speech_slowness?: 'high' | 'moderate' | 'low';
+    excessive_pauses?: boolean;
+    flat_affect?: boolean | 'partial';
+}
+interface VoiceResult {
+    status: 'success' | 'error' | null;
+    error?: string | null;
+    stress_score: number | null;
+    fatigue_score: number | null;
+    anxiety_level: 'low' | 'mild' | 'moderate' | 'high' | null;
+    anxiety_confidence: number | null;
+    voice_quality: 'healthy' | 'mild_strain' | 'moderate_strain' | 'significant_strain' | null;
+    pitch_variability: number | null;
+    speech_rate: number | null;
+    pause_ratio: number | null;
+    tremor_index: number | null;
+    energy_variability: number | null;
+    respiratory_rate: number | null;
+    breathing_regularity: number | null;
+    breath_depth: 'shallow' | 'normal' | 'deep' | null;
+    respiratory_health: number | null;
+    cough_detected: boolean | null;
+    cough_count: number | null;
+    wheeze_detected: boolean | null;
+    respiratory_concern: 'none' | 'mild' | 'elevated' | null;
+    depression_risk: 'low' | 'mild' | 'moderate' | 'elevated' | null;
+    depression_score: number | null;
+    mood_indicators: VoiceMoodIndicators | null;
+    cognitive_load: 'low' | 'normal' | 'moderate' | 'high' | null;
+    cognitive_score: number | null;
+    focus_indicator: 'relaxed' | 'stable' | 'engaged' | 'strained' | null;
+    composite_scores: VoiceCompositeScores | null;
+    wellness_score: number | null;
+    wellness_level: 'excellent' | 'good' | 'moderate' | 'fair' | 'poor' | null;
+    pitch_mean: number | null;
+    pitch_range: number | null;
+    energy_dynamics: number | null;
+    rhythm_regularity: number | null;
+    jitter: number | null;
+    shimmer: number | null;
+    duration_seconds: number | null;
+    analysis_confidence: number | null;
+    analysis_version: string;
+}
+interface EyeCataract {
+    opacity_score: number | null;
+    risk_level: 'low' | 'mild' | 'moderate' | 'elevated' | null;
+    confidence: 'high' | 'moderate' | 'low' | null;
+    description: string | null;
+    recommendation: string | null;
+}
+interface EyeRedEye {
+    redness_score: number | null;
+    risk_level: 'low' | 'mild' | 'moderate' | 'elevated' | null;
+    is_inflamed: boolean | null;
+    confidence: 'high' | 'moderate' | 'low' | null;
+    description: string | null;
+}
+interface EyeLensClarity {
+    score: number | null;
+    level: 'clear' | 'good' | 'moderate' | 'reduced' | null;
+    samples?: number;
+}
+interface EyePupil {
+    regularity_score: number | null;
+    circularity: number | null;
+    status: 'normal' | 'irregular' | null;
+    samples_analyzed?: number;
+    detected?: boolean;
+}
+interface EyePterygium {
+    detected: boolean | null;
+    confidence: number | null;
+    severity?: 'minimal' | 'mild' | 'moderate' | 'significant' | null;
+    description?: string;
+    error?: string;
+}
+interface EyeStye {
+    detected: boolean | null;
+    confidence: number | null;
+    note?: string;
+}
+interface EyeSclera {
+    score: number | null;
+    risk: 'low' | 'moderate' | 'elevated' | null;
+    color_health: 'healthy' | 'monitor' | null;
+    samples?: number;
+    error?: string;
+}
+interface EyeResult {
+    status: 'success' | 'error' | null;
+    overall_score: number | null;
+    health_level: 'Excellent' | 'Good' | 'Fair' | 'Needs Attention' | 'Consult Specialist' | null;
+    cataract: EyeCataract | null;
+    red_eye: EyeRedEye | null;
+    lens_clarity: EyeLensClarity | null;
+    pupil: EyePupil | null;
+    pterygium: EyePterygium | null;
+    stye: EyeStye | null;
+    sclera: EyeSclera | null;
+    recommendations: string[] | null;
+    frames_analyzed: number;
+    eyes_detected: number;
+    analysis_confidence: 'high' | 'moderate' | 'low' | null;
+    analysis_version?: string;
+    error?: string | null;
 }
 interface APIResponse<T> {
     status: 'success' | 'error';
@@ -199,21 +415,21 @@ declare const PulseScanner: React$1.FC<PulseScannerProps>;
  */
 interface VitalsCardProps {
     /** Heart rate in BPM */
-    heartRate?: number;
+    heartRate?: number | null;
     /** Oxygen saturation percentage */
-    spo2?: number;
+    spo2?: number | null;
     /** Stress index (0-100) */
-    stressIndex?: number;
+    stressIndex?: number | null;
     /** HRV SDNN in milliseconds */
-    hrvSdnn?: number;
+    hrvSdnn?: number | null;
     /** HRV RMSSD in milliseconds */
-    hrvRmssd?: number;
+    hrvRmssd?: number | null;
     /** Respiratory rate per minute */
-    respiratoryRate?: number;
+    respiratoryRate?: number | null;
     /** Blood pressure readings */
-    bloodPressure?: BloodPressure;
+    bloodPressure?: BloodPressure | null;
     /** Recovery score percentage */
-    recoveryScore?: number;
+    recoveryScore?: number | null;
     /** Show loading state */
     loading?: boolean;
     /** Error message to display */
@@ -291,6 +507,20 @@ interface BeautyAnalyzeOptions {
     /** User's gender */
     gender?: 'male' | 'female';
 }
+/**
+ * Options for voice health analysis
+ */
+interface VoiceAnalyzeOptions {
+    /** Audio blob to analyze (webm, wav, mp3, ogg, m4a) */
+    audio: Blob;
+}
+/**
+ * Options for eye health analysis
+ */
+interface EyeAnalyzeOptions {
+    /** Video blob to analyze (webm or mp4) */
+    video: Blob;
+}
 /**
  * PulseAI API Client
  *
@@ -316,6 +546,30 @@ declare class PulseClient {
      * Returns skin age, texture, hydration, symmetry, and recommendations.
      */
     analyzeBeauty(options: BeautyAnalyzeOptions): Promise<BeautyResult>;
+    /**
+     * Analyze audio for voice health biomarkers
+     * Returns stress, fatigue, respiratory rate, cognitive load, and wellness scores.
+     *
+     * @example
+     * ```typescript
+     * const voiceResult = await client.analyzeVoice({ audio: audioBlob });
+     * console.log(voiceResult.stress_score);
+     * console.log(voiceResult.respiratory_rate);
+     * ```
+     */
+    analyzeVoice(options: VoiceAnalyzeOptions): Promise<VoiceResult>;
+    /**
+     * Analyze video for eye health screening
+     * Returns cataract risk, red eye detection, lens clarity, pupil analysis, and more.
+     *
+     * @example
+     * ```typescript
+     * const eyeResult = await client.analyzeEye({ video: videoBlob });
+     * console.log(eyeResult.overall_score);
+     * console.log(eyeResult.cataract.risk_level);
+     * ```
+     */
+    analyzeEye(options: EyeAnalyzeOptions): Promise<EyeResult>;
     /**
      * Check API health status
      */
@@ -427,6 +681,6 @@ declare function useRecording(stream: MediaStream | null, options?: UseRecording
  * @packageDocumentation
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.2.0";
 
-export { type APIError, type APIResponse, type AnalyzeOptions, type ArrhythmiaResult, type BMIEstimate, type BeautyAnalyzeOptions, type BeautyGeometry, type BeautyPhysiology, type BeautyRecommendations, type BeautyResult, type BeautySummary, type BeautySurface, type BloodPressure, type CompositeScores, type FaceDetectionResult, type MentalWellness, PulseClient, type PulseClientConfig, PulseScanner, type PulseScannerProps, type ScannerStatus, type UseCameraOptions, type UseCameraReturn, type UseFaceDetectionOptions, type UseFaceDetectionReturn, type UseRecordingOptions, type UseRecordingReturn, VERSION, type VisualAnalysis, VitalsCard, VitalsCardFromResult, type VitalsCardProps, type VitalsResult, useCamera, useFaceDetection, useRecording };
+export { type APIError, type APIResponse, type AnalyzeOptions, type ArrhythmiaResult, type BMIEstimate, type BeautyAnalyzeOptions, type BeautyGeometry, type BeautyPhysiology, type BeautyRecommendations, type BeautyResult, type BeautySummary, type BeautySurface, type BloodPressure, type CompositeScores, type EyeAnalyzeOptions, type EyeCataract, type EyeLensClarity, type EyePterygium, type EyePupil, type EyeRedEye, type EyeResult, type EyeSclera, type EyeStye, type FaceDetectionResult, type MentalWellness, PulseClient, type PulseClientConfig, PulseScanner, type PulseScannerProps, type ScannerStatus, type UseCameraOptions, type UseCameraReturn, type UseFaceDetectionOptions, type UseFaceDetectionReturn, type UseRecordingOptions, type UseRecordingReturn, VERSION, type VisualAnalysis, VitalsCard, VitalsCardFromResult, type VitalsCardProps, type VitalsResult, type VoiceAnalyzeOptions, type VoiceCompositeScores, type VoiceMoodIndicators, type VoiceResult, useCamera, useFaceDetection, useRecording };