API Reference

Complete API documentation for the VitalClaw SDK.

VitalClawEngine

The core engine for health data aggregation, analysis, and alerting.

Constructor

const engine = new VitalClawEngine(config: VitalClawConfig)

Option	Type	Description
`userId`	`string`	Unique user identifier
`providers`	`ProviderConfig[]`	Wearable provider configurations
`alertRules`	`AlertRule[]`	Custom alert rules (optional)
`goals`	`HealthGoal[]`	Health goals (optional)
`privacy`	`PrivacyConfig`	Privacy settings (retention, anonymization)

Ingestion

// Ingest data points, returns triggered alerts
engine.ingest(points: VitalDataPoint[]): HealthAlert[]

Query

// Query raw data points
engine.query({ userId, metrics?, sources?, from?, to?, limit?, order? }): VitalDataPoint[]

// Aggregate by period
engine.aggregate({ ...query, groupBy, aggregation }): { period: string, value: number }[]

// Get latest reading for a metric
engine.getLatest(metric: MetricType): VitalDataPoint | undefined

Summaries

// Daily summary with wellness score
engine.getDailySummary(date?: string): DailySummary

// Weekly summary with trends and insights
engine.getWeeklySummary(weekStart?: string): WeeklySummary

Trends

// Analyze trends over period
engine.getTrends(
  period: "7d" | "14d" | "30d" | "90d",
  metrics?: MetricType[]
): TrendAnalysis

Alerts

engine.getAlerts(unacknowledgedOnly?: boolean): HealthAlert[]
engine.acknowledgeAlert(alertId: string): void
engine.addAlertRule(rule: AlertRule): void

Events

engine.events.on("alert:triggered", handler)
engine.events.on("data:ingested", handler)
engine.events.on("goal:achieved", handler)
engine.events.on("summary:daily", handler)
engine.events.on("summary:weekly", handler)

Event	Payload
`sync:start`	provider
`sync:complete`	provider, count
`sync:error`	provider, error
`data:ingested`	metric, count
`alert:triggered`	alert: HealthAlert
`alert:resolved`	alertId
`goal:progress`	goal: HealthGoal
`goal:achieved`	goal: HealthGoal
`summary:daily`	summary: DailySummary
`summary:weekly`	summary: WeeklySummary

FHIRConverter

import { FHIRConverter } from "@vitalclaw/sdk";

const fhir = new FHIRConverter();

fhir.toObservation(point)         // → FHIRObservation
fhir.fromObservation(observation)  // → VitalDataPoint
fhir.toBundle(points)              // → FHIR Bundle
fhir.getSupportedCodes()          // → { metric, loinc, display }[]

DailySummary Interface

interface DailySummary {
  userId: string;
  date: string;
  sources: ProviderType[];
  cardiac: {
    restingHeartRate?: number;
    averageHeartRate?: number;
    maxHeartRate?: number;
    hrv?: number;
    bloodOxygen?: number;
  };
  activity: { steps?, distance?, caloriesBurned?, activeMinutes? };
  sleep: { duration?, score?, stages?, efficiency? };
  body: { weight?, bodyFat?, bmi? };
  stress: { averageLevel? };
  metabolic: { bloodGlucose?: { average, min, max } };
  wellnessScore: number; // 0-100
  alerts: HealthAlert[];
}