npm package: @rexai/pulse-react
Description: React SDK for rPPG health analysis - measure heart rate, HRV, SpO2, voice biomarkers from any camera
Author: RexAI
Latest version: 2.1.0

# @rexai/pulse-react

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

```bash
npm install @rexai/pulse-react
# or
yarn add @rexai/pulse-react
# or
pnpm add @rexai/pulse-react
```

## Quick Start

```tsx
import { PulseScanner, VitalsCard } from '@rexai/pulse-react';
import '@rexai/pulse-react/styles.css';
import { useState } from 'react';

function App() {
  const [vitals, setVitals] = useState(null);

  return (
    <div>
      <PulseScanner
        apiKey="pk_live_YOUR_API_KEY"
        duration={10}
        showMesh={true}  // Show face mesh overlay
        onResult={(result) => setVitals(result)}
        onError={(err) => console.error(err)}
      />
      
      {vitals && (
        <VitalsCard
          heartRate={vitals.heart_rate}
          spo2={vitals.spo2}
          stressIndex={vitals.stress_index}
          hrvSdnn={vitals.hrv_sdnn}
        />
      )}
    </div>
  );
}
```

**Note:** The SDK automatically uses your `VITE_API_URL` environment variable for the backend URL.

## Components

### PulseScanner

The main component for capturing and analyzing vital signs.

```tsx
<PulseScanner
  apiKey="pk_live_..."           // Required: Your API key
  duration={10}                   // Scan duration in seconds (default: 10)
  onResult={(vitals) => {...}}    // Called with results
  onError={(error) => {...}}      // Called on error
  theme="light"                   // "light" | "dark" | "minimal"
  showPreview={true}              // Show camera preview
  showOverlay={true}              // Show face detection overlay
  showMesh={true}                 // Show face mesh lines (default: false)
  showCountdown={true}            // Show countdown during recording
  userData={{                     // Optional user data for calibration
    age: 30,
    sex: 'male'
  }}
/>
```

### VitalsCard

Display component for vital sign results.

```tsx
<VitalsCard
  heartRate={72}
  spo2={98}
  stressIndex={25}
  hrvSdnn={45}
  respiratoryRate={16}
  bloodPressure={{ systolic: 120, diastolic: 80 }}
  recoveryScore={85}
  showAll={true}                  // Show extended metrics
  compact={false}                 // Compact layout
  theme="light"                   // "light" | "dark"
/>
```

## API Client

For programmatic access without the UI components:

```typescript
import { PulseClient } from '@rexai/pulse-react';

const client = new PulseClient({
  apiKey: 'pk_live_YOUR_API_KEY'
});

// Analyze a video blob for medical vitals
const vitals = await client.analyze({
  video: videoBlob,
  age: 30,
  sex: 'male'
});

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

For building custom UI:

```tsx
import { useCamera, useFaceDetection, useRecording } from '@rexai/pulse-react';

function CustomScanner() {
  const { videoRef, isActive, start, stop } = useCamera();
  const { detected, qualityMessage, isQualityGood } = useFaceDetection(videoRef.current);
  const { isRecording, timeLeft, blob, start: startRecording } = useRecording(stream);
  
  // Build your own UI...
}
```

## Vitals Returned

### Medical Analysis (`analyze`)

| Metric | Type | Description |
|--------|------|-------------|
| `heart_rate` | number | Heart rate in BPM |
| `spo2` | number | Oxygen saturation % |
| `hrv_sdnn` | number | HRV (SDNN) in ms |
| `hrv_rmssd` | number | HRV (RMSSD) in ms |
| `stress_index` | number | Stress index (0-100) |
| `respiratory_rate` | number | Breaths per minute |
| `blood_pressure` | object | Estimated BP (systolic/diastolic) |
| `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.

## License

MIT