@rexai/pulse-react 1.0.0

package/README.md

@@ -0,0 +1,158 @@
+# @rexai/pulse-react
+
+React SDK for PulseAI - measure vital signs from any camera using remote photoplethysmography (rPPG).
+
+## 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. No need to pass `apiUrl` if it's already configured.
+
+## 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
+const vitals = await client.analyze({
+  video: videoBlob,
+  age: 30,
+  sex: 'male'
+});
+
+console.log(vitals.heart_rate);  // 72
+console.log(vitals.spo2);        // 98
+```
+
+## 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
+
+| 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 |
+
+## Getting an API Key
+
+1. Visit [pulseai.com/developer/login](https://pulseai.com/developer/login)
+2. Sign in with Google
+3. Generate an API key from the dashboard
+
+## Support
+
+- Documentation: [pulseai.com/docs](https://pulseai.com/docs)
+- Email: support@pulseai.com
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,432 @@
+import React$1 from 'react';
+
+/**
+ * PulseAI SDK Type Definitions
+ */
+interface BloodPressure {
+    systolic: number;
+    diastolic: number;
+}
+interface ArrhythmiaResult {
+    has_arrhythmia: boolean;
+    irregularity_score: number;
+    details: string;
+}
+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;
+    };
+}
+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;
+    };
+}
+interface CompositeScores {
+    cardio_score: number;
+    resilience_score: number;
+    metabolic_score: number;
+    vitality_score: number;
+}
+interface BMIEstimate {
+    value: number;
+    category: string;
+    fwhr: number;
+    confidence?: string;
+    method?: string;
+}
+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;
+    manual_bmi?: number;
+    metabolic_score: number;
+    skin_temperature: number;
+    composite_scores: CompositeScores;
+    visual_analysis?: VisualAnalysis;
+    mental_wellness?: MentalWellness;
+    fusion_weights: Record<string, number>;
+}
+interface BeautySummary {
+    overall_score: number;
+    skin_age: number;
+}
+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;
+    };
+}
+interface BeautyGeometry {
+    symmetry_score: number;
+    face_shape: string;
+    eye_openness: number;
+    ptosis_indices: {
+        status: string;
+        youth_ratio?: number;
+    };
+}
+interface BeautyPhysiology {
+    glow_index: number;
+    stress_level: string;
+    elasticity: number;
+}
+interface BeautyRecommendations {
+    routine: string[];
+    tips: string[];
+}
+interface BeautyResult {
+    summary: BeautySummary;
+    surface: BeautySurface;
+    geometry: BeautyGeometry;
+    physiology: BeautyPhysiology;
+    recommendations: BeautyRecommendations;
+}
+interface APIResponse<T> {
+    status: 'success' | 'error';
+    data: T;
+    meta?: {
+        privacy: string;
+    };
+    message?: string;
+}
+interface APIError {
+    detail: string;
+    status_code?: number;
+}
+
+/**
+ * Props for PulseScanner component
+ */
+interface PulseScannerProps {
+    /** Your PulseAI API key */
+    apiKey: string;
+    /** API URL (optional - defaults to VITE_API_URL env var) */
+    apiUrl?: string;
+    /** Scan duration in seconds (default: 10) */
+    duration?: number;
+    /** Callback when vitals are successfully extracted */
+    onResult: (vitals: VitalsResult) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+    /** Callback for status updates */
+    onStatusChange?: (status: ScannerStatus) => void;
+    /** Show camera preview (default: true) */
+    showPreview?: boolean;
+    /** Show face detection overlay (default: true) */
+    showOverlay?: boolean;
+    /** Show face mesh lines overlay (default: false) */
+    showMesh?: boolean;
+    /** Show countdown during recording (default: true) */
+    showCountdown?: boolean;
+    /** Custom CSS class */
+    className?: string;
+    /** Theme variant */
+    theme?: 'light' | 'dark' | 'minimal';
+    /** User data for calibration */
+    userData?: {
+        age?: number;
+        sex?: 'male' | 'female';
+        weight?: number;
+        height?: number;
+    };
+    /** Auto-start camera on mount */
+    autoStart?: boolean;
+}
+type ScannerStatus = 'idle' | 'loading' | 'ready' | 'recording' | 'uploading' | 'analyzing' | 'complete' | 'error';
+/**
+ * PulseScanner - Main component for capturing and analyzing vitals
+ *
+ * @example
+ * ```tsx
+ * <PulseScanner
+ *   apiKey="pk_live_..."
+ *   duration={10}
+ *   onResult={(vitals) => console.log(vitals)}
+ *   onError={(err) => console.error(err)}
+ * />
+ * ```
+ */
+declare const PulseScanner: React$1.FC<PulseScannerProps>;
+
+/**
+ * Props for VitalsCard component
+ */
+interface VitalsCardProps {
+    /** Heart rate in BPM */
+    heartRate?: number;
+    /** Oxygen saturation percentage */
+    spo2?: number;
+    /** Stress index (0-100) */
+    stressIndex?: number;
+    /** HRV SDNN in milliseconds */
+    hrvSdnn?: number;
+    /** HRV RMSSD in milliseconds */
+    hrvRmssd?: number;
+    /** Respiratory rate per minute */
+    respiratoryRate?: number;
+    /** Blood pressure readings */
+    bloodPressure?: BloodPressure;
+    /** Recovery score percentage */
+    recoveryScore?: number;
+    /** Show loading state */
+    loading?: boolean;
+    /** Error message to display */
+    error?: string | null;
+    /** Compact layout */
+    compact?: boolean;
+    /** Show all metrics or just primary ones */
+    showAll?: boolean;
+    /** Custom CSS class */
+    className?: string;
+    /** Theme variant */
+    theme?: 'light' | 'dark';
+}
+/**
+ * VitalsCard - Display component for vital sign results
+ *
+ * @example
+ * ```tsx
+ * <VitalsCard
+ *   heartRate={72}
+ *   spo2={98}
+ *   stressIndex={25}
+ *   hrvSdnn={45}
+ * />
+ * ```
+ */
+declare const VitalsCard: React$1.FC<VitalsCardProps>;
+/**
+ * Helper component to create VitalsCard from full VitalsResult object
+ */
+declare const VitalsCardFromResult: React$1.FC<{
+    result: VitalsResult | null;
+    loading?: boolean;
+    error?: string | null;
+    showAll?: boolean;
+    compact?: boolean;
+    className?: string;
+    theme?: 'light' | 'dark';
+}>;
+
+/**
+ * Configuration for PulseClient
+ */
+interface PulseClientConfig {
+    /** Your PulseAI API key (starts with pk_live_ or pk_test_) */
+    apiKey: string;
+    /** API base URL (optional - defaults to VITE_API_URL env var or localhost) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+/**
+ * Options for medical vitals analysis
+ */
+interface AnalyzeOptions {
+    /** Video blob to analyze (webm or mp4) */
+    video: Blob;
+    /** User's age for calibration */
+    age?: number;
+    /** User's biological sex */
+    sex?: 'male' | 'female';
+    /** User's weight in kg (for BMI calculation) */
+    weight?: number;
+    /** User's height in cm (for BMI calculation) */
+    height?: number;
+}
+/**
+ * Options for beauty skin analysis
+ */
+interface BeautyAnalyzeOptions {
+    /** Video blob to analyze */
+    video: Blob;
+    /** User's age */
+    age?: number;
+    /** User's gender */
+    gender?: 'male' | 'female';
+}
+/**
+ * PulseAI API Client
+ *
+ * @example
+ * ```typescript
+ * const client = new PulseClient({ apiKey: 'pk_live_...' });
+ * const vitals = await client.analyze({ video: videoBlob });
+ * console.log(vitals.heart_rate);
+ * ```
+ */
+declare class PulseClient {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(config: PulseClientConfig);
+    /**
+     * Analyze video for medical vital signs
+     * Returns heart rate, HRV, SpO2, stress index, and more.
+     */
+    analyze(options: AnalyzeOptions): Promise<VitalsResult>;
+    /**
+     * Analyze video for beauty/skin metrics
+     * Returns skin age, texture, hydration, symmetry, and recommendations.
+     */
+    analyzeBeauty(options: BeautyAnalyzeOptions): Promise<BeautyResult>;
+    /**
+     * Check API health status
+     */
+    health(): Promise<{
+        status: string;
+        service: string;
+    }>;
+    /**
+     * Internal request handler with timeout and error handling
+     */
+    private request;
+}
+
+interface UseCameraOptions {
+    width?: number;
+    height?: number;
+    facingMode?: 'user' | 'environment';
+    autoStart?: boolean;
+}
+interface UseCameraReturn {
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    stream: MediaStream | null;
+    isActive: boolean;
+    error: string | null;
+    start: () => Promise<void>;
+    stop: () => void;
+}
+/**
+ * Hook for managing camera stream.
+ * Handles permissions and stream lifecycle.
+ */
+declare function useCamera(options?: UseCameraOptions): UseCameraReturn;
+
+interface FaceDetectionResult {
+    detected: boolean;
+    landmarks: any[] | null;
+    qualityMessage: string;
+    isQualityGood: boolean;
+    brightness: number;
+}
+interface UseFaceDetectionOptions {
+    enabled?: boolean;
+    /** Canvas element for drawing mesh overlay */
+    meshCanvas?: HTMLCanvasElement | null;
+    /** Enable mesh drawing (default: false) */
+    drawMesh?: boolean;
+}
+interface UseFaceDetectionReturn extends FaceDetectionResult {
+    isLoading: boolean;
+    latestLandmarks: React.MutableRefObject<any[] | null>;
+}
+/**
+ * Hook for face detection using MediaPipe FaceLandmarker.
+ * Provides real-time face tracking and quality assessment.
+ */
+declare function useFaceDetection(videoElement: HTMLVideoElement | null, options?: UseFaceDetectionOptions): UseFaceDetectionReturn;
+
+interface UseRecordingOptions {
+    duration?: number;
+    mimeType?: string;
+    onComplete?: (blob: Blob) => void;
+}
+interface UseRecordingReturn {
+    isRecording: boolean;
+    timeLeft: number;
+    blob: Blob | null;
+    start: () => void;
+    stop: () => void;
+    reset: () => void;
+}
+/**
+ * Hook for managing video recording from a MediaStream.
+ * Handles countdown timer and blob generation.
+ */
+declare function useRecording(stream: MediaStream | null, options?: UseRecordingOptions): UseRecordingReturn;
+
+/**
+ * PulseAI React SDK
+ *
+ * Measure vital signs from any camera using remote photoplethysmography (rPPG).
+ *
+ * @example
+ * ```tsx
+ * import { PulseScanner, VitalsCard, PulseClient } from '@pulseai/react';
+ * import '@pulseai/react/styles.css';
+ *
+ * function App() {
+ *   const [vitals, setVitals] = useState(null);
+ *
+ *   return (
+ *     <>
+ *       <PulseScanner
+ *         apiKey="pk_live_..."
+ *         duration={10}
+ *         onResult={setVitals}
+ *       />
+ *       {vitals && (
+ *         <VitalsCard
+ *           heartRate={vitals.heart_rate}
+ *           spo2={vitals.spo2}
+ *           stressIndex={vitals.stress_index}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "1.0.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 };