@healthcloudai/hc-cameravitals-connector 0.2.0

package/README.md

@@ -0,0 +1,163 @@
+# @healthcloudai/hc-cameravitals-connector
+
+Camera-based vital signs measurement for React Native (Expo). Measure heart rate, HRV, respiratory rate, and SpO2 using the device camera — with a single `<CameraVitalsScan>` component that works on iOS, Android, and Web.
+
+```tsx
+import {
+  CameraVitalsScan,
+  CameraVitalsThemeProvider,
+} from "@healthcloudai/hc-cameravitals-connector";
+
+export default function App() {
+  return (
+    <CameraVitalsThemeProvider>
+      <CameraVitalsScan
+        apiKey="your-api-key"
+        onResult={(result) => console.log("Vitals:", result)}
+      />
+    </CameraVitalsThemeProvider>
+  );
+}
+```
+
+## Features
+
+- **Zero config** — Expo config plugin handles ALL native setup
+- **Single component** — `<CameraVitalsScan>` works on iOS, Android, and Web
+- **Vendor-transparent** — Public API uses generic names (`CameraVitalsConfig`, `CameraVitalsResult`); the underlying SDK is an implementation detail
+- **Headless hook** — `useCameraVitals()` gives you full control over measurement lifecycle
+- **Themable** — `CameraVitalsThemeProvider` + design tokens for complete visual customization
+
+## Installation
+
+```bash
+npm install @healthcloudai/hc-cameravitals-connector
+```
+
+### Expo Config Plugin
+
+Add the plugin to your `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      "@healthcloudai/hc-cameravitals-connector"
+    ]
+  }
+}
+```
+
+This automatically:
+- Adds camera permissions (iOS + Android)
+- Configures the Circadify SDK dependency (Android Maven repo + Gradle dep)
+- Adds linker flags and SPM package references (iOS)
+- Injects RocketSim support for iOS Simulator (debug builds)
+
+After adding the plugin, rebuild your native apps:
+
+```bash
+npx expo prebuild --clean
+npx expo run:ios    # or run:android
+```
+
+### Web
+
+Web measurement requires `@circadify/web-sdk` (optional peer dependency):
+
+```bash
+npm install @circadify/web-sdk
+```
+
+> **Note**: `@circadify/web-sdk` is hosted on GitHub Packages. Configure a `.npmrc` with your GitHub token:
+> ```
+> @circadify:registry=https://npm.pkg.github.com
+> //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+> ```
+
+## API
+
+### Components
+
+#### `<CameraVitalsScan>`
+
+All-in-one scan component with four screens: idle → scanning → results → error.
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `apiKey` | `string` | Yes | API key for the vital signs SDK |
+| `onResult` | `(result: CameraVitalsResult) => void` | No | Called on successful measurement |
+| `onError` | `(error: Error) => void` | No | Called on fatal error |
+
+#### `<CameraVitalsPreview>`
+
+Low-level camera preview. Renders the native viewfinder on iOS/Android.
+
+#### `<CameraVitalsThemeProvider>`
+
+Theme context provider. Wrap your app to customize colors, spacing, radii, fonts, and dimensions.
+
+```tsx
+import {
+  CameraVitalsThemeProvider,
+  DEFAULT_THEME,
+  mergeCameraVitalsTheme,
+} from "@healthcloudai/hc-cameravitals-connector";
+
+const myTheme = mergeCameraVitalsTheme(DEFAULT_THEME, {
+  colors: { accent: "#FF6B35" },
+});
+
+function App() {
+  return (
+    <CameraVitalsThemeProvider value={myTheme}>
+      <CameraVitalsScan apiKey="..." />
+    </CameraVitalsThemeProvider>
+  );
+}
+```
+
+### Hooks
+
+#### `useCameraVitals()`
+
+Headless hook. Returns a `CameraVitalsAPI` object:
+
+```ts
+const {
+  start,      // (config, options?) => Promise<CameraVitalsResult>
+  stop,       // () => Promise<void>
+  progress,   // ProgressUpdate | null
+  quality,    // QualityWarning[]
+  isScanning, // boolean
+  result,     // CameraVitalsResult | null
+  error,      // CameraVitalsError | null
+} = useCameraVitals();
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `CameraVitalsConfig` | `{ apiKey, demographics? }` |
+| `CameraVitalsResult` | `{ heartRate, hrv?, respiratoryRate?, spo2?, systolicBp?, diastolicBp?, confidence? }` |
+| `CameraVitalsError` | `{ code, message }` |
+| `Demographics` | `{ age?, sex?: "male" \| "female", fitzpatrick?: 1-6 }` |
+| `MeasurementOptions` | `{ demographics?, onProgress?, onQualityWarning? }` |
+| `ProgressUpdate` | `{ percent, phase, elapsedSeconds }` |
+| `QualityWarning` | `{ type, message, severity }` |
+| `CameraVitalsAPI` | Return type of `useCameraVitals()` |
+
+## Requirements
+
+| Platform | Minimum Version |
+|----------|----------------|
+| iOS | 17.0+ |
+| Android | API 24+ (Android 7.0) |
+| Expo SDK | 52+ |
+| React Native | 0.72+ |
+| React | 18–19 |
+
+## License
+
+MIT

package/android/build.gradle

@@ -0,0 +1,37 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+group = "expo.modules.circadify"
+version = "0.1.0"
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useDefaultAndroidSdkVersions()
+useExpoPublishing()
+
+android {
+  namespace "expo.modules.circadify"
+  compileSdk rootProject.ext.compileSdkVersion
+  defaultConfig {
+    minSdk rootProject.ext.minSdkVersion
+    versionCode 1
+    versionName "0.1.0"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+
+  kotlinOptions {
+    jvmTarget = "17"
+  }
+}
+
+dependencies {
+  implementation("com.circadify:circadify-android-sdk:0.1.1")
+  implementation("androidx.camera:camera-view:1.3.4")
+  implementation("androidx.camera:camera-lifecycle:1.3.4")
+}

package/android/src/main/java/expo/modules/circadify/CircadifyModule.kt

@@ -0,0 +1,202 @@
+package expo.modules.circadify
+
+import android.Manifest
+import android.content.pm.PackageManager
+import android.util.Log
+import androidx.camera.view.PreviewView
+import androidx.core.content.ContextCompat
+import com.circadify.sdk.CircadifyCallbacks
+import com.circadify.sdk.CircadifyConfig
+import com.circadify.sdk.CircadifyError
+import com.circadify.sdk.CircadifySDK
+import com.circadify.sdk.Demographics
+import com.circadify.sdk.MeasurementOptions
+import com.circadify.sdk.ProgressEvent
+import com.circadify.sdk.QualityState
+import com.circadify.sdk.QualityWarning
+import com.circadify.sdk.Sex
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+
+/**
+ * Expo native module wrapping the Circadify Android SDK.
+ *
+ * Usage from JS:
+ *   const result = await CircadifyModule.measureVitals("ck_live_...", {});
+ */
+class CircadifyModule : Module() {
+    companion object {
+        private const val TAG = "CircadifyModule"
+
+        /** The currently mounted [PreviewView], set by [CircadifyPreviewView]. */
+        var currentPreview: PreviewView? = null
+    }
+
+    private var sdk: CircadifySDK? = null
+    private val scope = CoroutineScope(Dispatchers.Main)
+
+    override fun definition() = ModuleDefinition {
+        Name("CircadifyModule")
+
+        View(CircadifyPreviewView::class) { }
+
+        Events("progress", "qualityWarning", "qualityState")
+
+        AsyncFunction("measureVitals") { apiKey: String, demographicsMap: Map<String, Any>?, promise: Promise ->
+            scope.launch {
+                try {
+                    val activity = appContext.currentActivity
+                    if (activity == null) {
+                        promise.reject("NO_ACTIVITY", "No current activity available", null)
+                        return@launch
+                    }
+
+                    if (!hasCameraPermission()) {
+                        promise.reject(
+                            "CAMERA_PERMISSION_DENIED",
+                            "Camera permission is required for vital sign measurement",
+                            null
+                        )
+                        return@launch
+                    }
+
+                    val previewForSdk = currentPreview
+                    Log.d(TAG, "measureVitals: currentPreview=${previewForSdk}, " +
+                        "surfaceProvider=${previewForSdk?.surfaceProvider}, " +
+                        "implementationMode=${previewForSdk?.implementationMode}")
+
+                    val callbacks = CircadifyCallbacks(
+                        onProgress = { event: ProgressEvent ->
+                            Log.d(TAG, "Progress: ${event.percent}% phase=${event.phase}")
+                            sendEvent("progress", mapOf(
+                                "percent" to event.percent,
+                                "phase" to event.phase.name.lowercase(),
+                                "elapsedSeconds" to event.elapsedSeconds
+                            ))
+                        },
+                        onQualityWarning = { warning: QualityWarning ->
+                            Log.d(TAG, "Quality warning: ${warning.message}")
+                            sendEvent("qualityWarning", mapOf(
+                                "type" to warning.type.name.lowercase(),
+                                "message" to warning.message,
+                                "severity" to warning.severity.name.lowercase()
+                            ))
+                        },
+                        onQualityState = { state: QualityState ->
+                            sendEvent("qualityState", mapOf(
+                                "lighting" to mapOf(
+                                    "brightness" to state.lighting.brightness,
+                                    "isOk" to state.lighting.isOk,
+                                    "isTooDark" to state.lighting.isTooDark
+                                ),
+                                "motion" to mapOf(
+                                    "magnitude" to state.motion.motionMagnitude,
+                                    "isStill" to state.motion.isStill
+                                ),
+                                "pose" to mapOf(
+                                    "yaw" to state.pose.yaw,
+                                    "pitch" to state.pose.pitch,
+                                    "isFacingForward" to state.pose.isFacingForward
+                                ),
+                                "isReady" to state.isReady,
+                                "messages" to state.messages
+                            ))
+                        }
+                    )
+
+                    val config = CircadifyConfig(
+                        apiKey = apiKey,
+                        debug = true,
+                        callbacks = callbacks
+                    )
+
+                    sdk = CircadifySDK(
+                        context = appContext.reactContext ?: activity,
+                        config = config
+                    )
+
+                    val demographics = buildDemographics(demographicsMap)
+
+                    val result = sdk!!.measureVitals(
+                        MeasurementOptions(
+                            lifecycleOwner = activity as androidx.lifecycle.LifecycleOwner,
+                            previewView = previewForSdk,
+                            demographics = demographics
+                        )
+                    )
+
+                    // Build result map — only include keys for values that exist
+                    val resultMap = mutableMapOf<String, Any?>(
+                        "heartRate" to result.heartRate
+                    )
+                    result.confidence?.let { resultMap["confidence"] = it }
+                    result.hrv?.let { resultMap["hrv"] = it }
+                    result.respiratoryRate?.let { resultMap["respiratoryRate"] = it }
+                    result.spo2?.let { resultMap["spo2"] = it }
+                    result.systolicBp?.let { resultMap["systolicBp"] = it }
+                    result.diastolicBp?.let { resultMap["diastolicBp"] = it }
+                    promise.resolve(resultMap)
+                } catch (e: CircadifyError) {
+                    promise.reject(
+                        "CIRCADIFY_ERROR",
+                        "${e.code}: ${e.message}",
+                        e
+                    )
+                } catch (e: Exception) {
+                    promise.reject(
+                        "MEASUREMENT_FAILED",
+                        e.message ?: "Unknown measurement error",
+                        e
+                    )
+                }
+            }
+        }
+
+        AsyncFunction("hasCameraPermission") { promise: Promise ->
+            promise.resolve(hasCameraPermission())
+        }
+
+        AsyncFunction("requestCameraPermission") { promise: Promise ->
+            // Android camera permission uses ActivityResultLauncher which
+            // requires a registry tied to the host Activity/Fragment.
+            // Expo Modules don't expose launcher registration APIs yet.
+            // As a graceful fallback we check current status — consumers
+            // should ensure camera permission is pre-granted on Android
+            // (the Expo config plugin adds CAMERA permission by default).
+            Log.w(TAG, "requestCameraPermission: ActivityResultLauncher not available in Expo Module; returning current status")
+            promise.resolve(hasCameraPermission())
+        }
+
+        AsyncFunction("cancel") { promise: Promise ->
+            scope.launch {
+                try {
+                    sdk?.cancel()
+                    promise.resolve(null)
+                } catch (e: Exception) {
+                    promise.reject("CANCEL_FAILED", e.message, e)
+                }
+            }
+        }
+    }
+
+    private fun hasCameraPermission(): Boolean {
+        val context = appContext.reactContext ?: return false
+        return ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+            PackageManager.PERMISSION_GRANTED
+    }
+
+    private fun buildDemographics(map: Map<String, Any>?): Demographics? {
+        if (map.isNullOrEmpty()) return null
+        return Demographics(
+            age = (map["age"] as? Number)?.toInt(),
+            sex = (map["sex"] as? String)?.let {
+                try { Sex.valueOf(it) } catch (_: Exception) { null }
+            },
+            fitzpatrick = (map["fitzpatrick"] as? Number)?.toInt()
+        )
+    }
+}

package/android/src/main/java/expo/modules/circadify/CircadifyPreviewView.kt

@@ -0,0 +1,60 @@
+package expo.modules.circadify
+
+import android.content.Context
+import android.graphics.Outline
+import android.util.Log
+import android.view.View
+import android.view.ViewGroup
+import android.view.ViewOutlineProvider
+import androidx.camera.view.PreviewView
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.views.ExpoView
+
+/**
+ * Expo native view wrapping a CameraX [PreviewView].
+ *
+ * When mounted in the React Native view tree the [previewView] is registered
+ * as [CircadifyModule.currentPreview] so the measurement flow can bind
+ * CameraX to it. On unmount the reference is cleared.
+ *
+ * Usage from JS:
+ *   <CircadifyPreviewView style={{ flex: 1 }} />
+ */
+class CircadifyPreviewView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+
+    override val shouldUseAndroidLayout: Boolean = true
+
+    val previewView: PreviewView = PreviewView(context).apply {
+        layoutParams = ViewGroup.LayoutParams(
+            ViewGroup.LayoutParams.MATCH_PARENT,
+            ViewGroup.LayoutParams.MATCH_PARENT
+        )
+        implementationMode = PreviewView.ImplementationMode.COMPATIBLE
+        scaleType = PreviewView.ScaleType.FILL_CENTER
+    }
+
+    init {
+        clipToPadding = true
+        addView(previewView)
+        CircadifyModule.currentPreview = previewView
+        Log.d("CircadifyPreviewView", "PreviewView registered: " +
+            "implMode=${previewView.implementationMode}, " +
+            "size=${previewView.width}x${previewView.height}, " +
+            "surfaceProvider=${previewView.surfaceProvider}")
+
+        clipToOutline = true
+        outlineProvider = object : ViewOutlineProvider() {
+            override fun getOutline(view: View, outline: Outline) {
+                val radius = 14f * resources.displayMetrics.density
+                outline.setRoundRect(0, 0, view.width, view.height, radius)
+            }
+        }
+    }
+
+    override fun onDetachedFromWindow() {
+        super.onDetachedFromWindow()
+        if (CircadifyModule.currentPreview == previewView) {
+            CircadifyModule.currentPreview = null
+        }
+    }
+}