@nativesquare/soma 0.16.2 → 0.16.3

package/src/component/healthkit/types.ts

@@ -1,112 +1,49 @@
 // ─── Apple HealthKit Input Types ──────────────────────────────────────────────
-// Library-agnostic TypeScript interfaces representing HealthKit data shapes.
+// Library-agnostic TypeScript types representing HealthKit data shapes.
 // Compatible with @kingstinct/react-native-healthkit, react-native-health,
 // expo-health, or any custom native module.
 //
-// These types define the CONTRACT that the host app must satisfy when passing
-// HealthKit data to Soma's transformer functions. They intentionally do NOT
-// depend on any specific React Native library.
-
-// ─── Device ──────────────────────────────────────────────────────────────────
-
-export interface HKDevice {
-  name?: string;
-  manufacturer?: string;
-  model?: string;
-  hardwareVersion?: string;
-  softwareVersion?: string;
-}
-
-// ─── Source ──────────────────────────────────────────────────────────────────
-
-export interface HKSource {
-  name: string;
-  bundleIdentifier: string;
-}
-
-// ─── Quantity Sample ─────────────────────────────────────────────────────────
-// Represents a numeric measurement from HealthKit (heart rate, steps, etc.)
-
-export interface HKQuantitySample {
-  uuid: string;
-  sampleType: HKQuantityTypeIdentifier;
-  startDate: string; // ISO-8601
-  endDate: string; // ISO-8601
-  value: number;
-  unit: string; // "count", "count/min", "kcal", "m", "mg/dL", etc.
-  source?: HKSource;
-  device?: HKDevice;
-}
-
-// ─── Category Sample ─────────────────────────────────────────────────────────
-// Represents a categorized observation (sleep stage, menstrual flow, etc.)
-
-export interface HKCategorySample {
-  uuid: string;
-  sampleType: HKCategoryTypeIdentifier;
-  startDate: string; // ISO-8601
-  endDate: string; // ISO-8601
-  value: number; // Category-specific enum value
-  source?: HKSource;
-  device?: HKDevice;
-}
-
-// ─── Workout ─────────────────────────────────────────────────────────────────
-
-export interface HKWorkoutRoute {
-  locations: Array<{
-    latitude: number;
-    longitude: number;
-    altitude?: number;
-    timestamp: string; // ISO-8601
-  }>;
-}
-
-export interface HKWorkout {
-  uuid: string;
-  workoutActivityType: number; // HKWorkoutActivityType raw value
-  startDate: string; // ISO-8601
-  endDate: string; // ISO-8601
-  duration: number; // seconds
-  totalEnergyBurned?: number; // kcal
-  totalDistance?: number; // meters
-  totalSwimmingStrokeCount?: number;
-  totalFlightsClimbed?: number;
-  source?: HKSource;
-  device?: HKDevice;
-  // Associated samples (queried separately in HealthKit, attached by host app)
-  heartRateSamples?: HKQuantitySample[];
-  routeData?: HKWorkoutRoute[];
-}
-
-// ─── Activity Summary ────────────────────────────────────────────────────────
-// Daily activity ring data from HealthKit
-
-export interface HKActivitySummary {
-  activeEnergyBurned: number; // kcal
-  activeEnergyBurnedGoal: number; // kcal
-  appleExerciseTime: number; // minutes
-  appleExerciseTimeGoal: number; // minutes
-  appleStandHours: number; // count
-  appleStandHoursGoal: number; // count
-  dateComponents: { year: number; month: number; day: number };
-}
-
-// ─── User Characteristics ────────────────────────────────────────────────────
-// Static user profile data from HealthKit
-
-export interface HKCharacteristics {
-  biologicalSex?: HKBiologicalSex;
-  dateOfBirth?: string; // ISO-8601 date
-  bloodType?: string;
-  fitzpatrickSkinType?: number;
-  wheelchairUse?: boolean;
-}
-
-export type HKBiologicalSex = "female" | "male" | "other" | "notSet";
+// These types are INFERRED from the Convex validators in ./validators.js —
+// edit validators.ts to change shapes, not this file. The identifier unions
+// and runtime enum constants at the bottom are hand-written: they exist as
+// documentation / autocomplete aids only and are not enforced at runtime.
+
+import type { Infer } from "convex/values";
+import {
+  hkDeviceValidator,
+  hkSourceValidator,
+  hkQuantitySampleValidator,
+  hkCategorySampleValidator,
+  hkWorkoutRouteValidator,
+  hkWorkoutValidator,
+  hkActivitySummaryValidator,
+  hkCharacteristicsValidator,
+  hkBiologicalSexValidator,
+  hkSleepCategoryValueValidator,
+  hkMenstrualFlowCategoryValueValidator,
+} from "./validators.js";
+
+// ─── Inferred shapes ─────────────────────────────────────────────────────────
+
+export type HKDevice = Infer<typeof hkDeviceValidator>;
+export type HKSource = Infer<typeof hkSourceValidator>;
+export type HKQuantitySample = Infer<typeof hkQuantitySampleValidator>;
+export type HKCategorySample = Infer<typeof hkCategorySampleValidator>;
+export type HKWorkoutRoute = Infer<typeof hkWorkoutRouteValidator>;
+export type HKWorkout = Infer<typeof hkWorkoutValidator>;
+export type HKActivitySummary = Infer<typeof hkActivitySummaryValidator>;
+export type HKCharacteristics = Infer<typeof hkCharacteristicsValidator>;
+export type HKBiologicalSex = Infer<typeof hkBiologicalSexValidator>;
+export type HKSleepCategoryValue = Infer<typeof hkSleepCategoryValueValidator>;
+export type HKMenstrualFlowCategoryValue = Infer<
+  typeof hkMenstrualFlowCategoryValueValidator
+>;
 
 // ─── HealthKit Quantity Type Identifiers ─────────────────────────────────────
-// Subset covering types that map to the Soma schema.
+// Documentary union of known identifiers. The runtime validator is a bare
+// `v.string()` — any string is accepted. Use this type for host-side
+// autocomplete by annotating values you construct, e.g.
+// `const t: HKQuantityTypeIdentifier = "HKQuantityTypeIdentifierHeartRate"`.
 
 export type HKQuantityTypeIdentifier =
   // Body measurements
@@ -178,9 +115,9 @@ export type HKQuantityTypeIdentifier =
   | "HKQuantityTypeIdentifierDietaryCaffeine"
   | "HKQuantityTypeIdentifierDietaryIodine"
   | "HKQuantityTypeIdentifierDietaryChloride"
-  // Hydration
   | "HKQuantityTypeIdentifierDietaryPanthothenicAcid"
-  // Catch-all for future types
+  // Catch-all for future types (preserves autocomplete on the known literals
+  // while accepting any string, matching the runtime `v.string()` validator).
   | (string & {});
 
 // ─── HealthKit Category Type Identifiers ─────────────────────────────────────
@@ -191,7 +128,9 @@ export type HKCategoryTypeIdentifier =
   | "HKCategoryTypeIdentifierAppleStandHour"
   | (string & {});
 
-// ─── HealthKit Sleep Category Values ─────────────────────────────────────────
+// ─── Runtime enum constants ──────────────────────────────────────────────────
+// Kept as real values (not just types) so host code can compare against them
+// at runtime: `if (sample.value === HKSleepCategory.AsleepREM) { ... }`
 
 export const HKSleepCategory = {
   InBed: 0,
@@ -202,11 +141,6 @@ export const HKSleepCategory = {
   AsleepREM: 5,
 } as const;
 
-export type HKSleepCategoryValue =
-  (typeof HKSleepCategory)[keyof typeof HKSleepCategory];
-
-// ─── HealthKit Menstrual Flow Values ─────────────────────────────────────────
-
 export const HKMenstrualFlowCategory = {
   Unspecified: 1,
   Light: 2,
@@ -214,6 +148,3 @@ export const HKMenstrualFlowCategory = {
   Heavy: 4,
   None: 5,
 } as const;
-
-export type HKMenstrualFlowCategoryValue =
-  (typeof HKMenstrualFlowCategory)[keyof typeof HKMenstrualFlowCategory];

package/src/component/healthkit/validators.ts

@@ -0,0 +1,253 @@
+// ─── HealthKit Input Validators ──────────────────────────────────────────────
+// Convex validators for the library-agnostic HealthKit input shapes the host
+// app hands to Soma. TypeScript types in ./types.js are inferred from these.
+//
+// Keep in lockstep with the documented HKQuantityTypeIdentifier /
+// HKCategoryTypeIdentifier string-literal unions in types.ts. Those unions are
+// documentation / autocomplete aids only; at runtime we accept any string so
+// that future iOS HealthKit identifiers don't require a Soma release.
+
+import { v } from "convex/values";
+import { somaErrorValidator } from "../validators/shared.js";
+
+// ─── Primitive shapes ───────────────────────────────────────────────────────
+
+export const hkDeviceValidator = v.object({
+  name: v.optional(v.string()),
+  manufacturer: v.optional(v.string()),
+  model: v.optional(v.string()),
+  hardwareVersion: v.optional(v.string()),
+  softwareVersion: v.optional(v.string()),
+});
+
+export const hkSourceValidator = v.object({
+  name: v.string(),
+  bundleIdentifier: v.string(),
+});
+
+// ─── Enums ──────────────────────────────────────────────────────────────────
+
+/**
+ * Biological sex values produced by HealthKit.
+ * Matches the `HKBiologicalSex` string union in types.ts.
+ */
+export const hkBiologicalSexValidator = v.union(
+  v.literal("female"),
+  v.literal("male"),
+  v.literal("other"),
+  v.literal("notSet"),
+);
+
+/**
+ * Numeric sleep-stage value from `HKCategoryTypeIdentifierSleepAnalysis`:
+ * 0=InBed, 1=AsleepUnspecified, 2=Awake, 3=AsleepCore, 4=AsleepDeep, 5=AsleepREM.
+ */
+export const hkSleepCategoryValueValidator = v.union(
+  v.literal(0),
+  v.literal(1),
+  v.literal(2),
+  v.literal(3),
+  v.literal(4),
+  v.literal(5),
+);
+
+/**
+ * Numeric menstrual flow value from `HKCategoryTypeIdentifierMenstrualFlow`:
+ * 1=Unspecified, 2=Light, 3=Medium, 4=Heavy, 5=None.
+ */
+export const hkMenstrualFlowCategoryValueValidator = v.union(
+  v.literal(1),
+  v.literal(2),
+  v.literal(3),
+  v.literal(4),
+  v.literal(5),
+);
+
+// ─── Samples ────────────────────────────────────────────────────────────────
+
+/**
+ * Numeric measurement from HealthKit (heart rate, steps, weight, etc.).
+ *
+ * `sampleType` is a bare string for forward-compat with iOS updates that add
+ * new identifiers. The `HKQuantityTypeIdentifier` alias in types.ts lists
+ * known values for host-side autocomplete; it is not enforced at runtime.
+ */
+export const hkQuantitySampleValidator = v.object({
+  uuid: v.string(),
+  sampleType: v.string(),
+  startDate: v.string(),
+  endDate: v.string(),
+  value: v.number(),
+  unit: v.string(),
+  source: v.optional(hkSourceValidator),
+  device: v.optional(hkDeviceValidator),
+});
+
+/**
+ * Categorized observation (sleep stage, menstrual flow, etc.).
+ *
+ * `value` is a category-specific enum integer. `sampleType` is a bare string
+ * for the same forward-compat reason as on `HKQuantitySample`.
+ */
+export const hkCategorySampleValidator = v.object({
+  uuid: v.string(),
+  sampleType: v.string(),
+  startDate: v.string(),
+  endDate: v.string(),
+  value: v.number(),
+  source: v.optional(hkSourceValidator),
+  device: v.optional(hkDeviceValidator),
+});
+
+// ─── Workout ────────────────────────────────────────────────────────────────
+
+export const hkWorkoutRouteValidator = v.object({
+  locations: v.array(
+    v.object({
+      latitude: v.number(),
+      longitude: v.number(),
+      altitude: v.optional(v.number()),
+      timestamp: v.string(),
+    }),
+  ),
+});
+
+export const hkWorkoutValidator = v.object({
+  uuid: v.string(),
+  workoutActivityType: v.number(),
+  startDate: v.string(),
+  endDate: v.string(),
+  duration: v.number(),
+  totalEnergyBurned: v.optional(v.number()),
+  totalDistance: v.optional(v.number()),
+  totalSwimmingStrokeCount: v.optional(v.number()),
+  totalFlightsClimbed: v.optional(v.number()),
+  source: v.optional(hkSourceValidator),
+  device: v.optional(hkDeviceValidator),
+  heartRateSamples: v.optional(v.array(hkQuantitySampleValidator)),
+  routeData: v.optional(v.array(hkWorkoutRouteValidator)),
+});
+
+// ─── Activity Summary ───────────────────────────────────────────────────────
+
+export const hkActivitySummaryValidator = v.object({
+  activeEnergyBurned: v.number(),
+  activeEnergyBurnedGoal: v.number(),
+  appleExerciseTime: v.number(),
+  appleExerciseTimeGoal: v.number(),
+  appleStandHours: v.number(),
+  appleStandHoursGoal: v.number(),
+  dateComponents: v.object({
+    year: v.number(),
+    month: v.number(),
+    day: v.number(),
+  }),
+});
+
+// ─── Characteristics ────────────────────────────────────────────────────────
+
+export const hkCharacteristicsValidator = v.object({
+  biologicalSex: v.optional(hkBiologicalSexValidator),
+  dateOfBirth: v.optional(v.string()),
+  bloodType: v.optional(v.string()),
+  fitzpatrickSkinType: v.optional(v.number()),
+  wheelchairUse: v.optional(v.boolean()),
+});
+
+// ─── Time range ─────────────────────────────────────────────────────────────
+
+export const timeRangeValidator = v.object({
+  start_time: v.string(),
+  end_time: v.string(),
+});
+
+// ─── Per-mutation args ──────────────────────────────────────────────────────
+// Plain object literals so they can be dropped straight into `args:` on a
+// `mutation({ args, ... })` definition.
+
+export const syncActivitiesArgs = {
+  userId: v.string(),
+  workouts: v.array(hkWorkoutValidator),
+};
+
+export const syncSleepArgs = {
+  userId: v.string(),
+  sessions: v.array(v.array(hkCategorySampleValidator)),
+};
+
+export const syncBodyArgs = {
+  userId: v.string(),
+  samples: v.array(hkQuantitySampleValidator),
+  timeRange: v.optional(timeRangeValidator),
+};
+
+export const syncDailyArgs = {
+  userId: v.string(),
+  samples: v.array(hkQuantitySampleValidator),
+  timeRange: v.optional(timeRangeValidator),
+};
+
+export const syncDailyFromSummaryArgs = {
+  userId: v.string(),
+  summaries: v.array(hkActivitySummaryValidator),
+};
+
+export const syncNutritionArgs = {
+  userId: v.string(),
+  samples: v.array(hkQuantitySampleValidator),
+  timeRange: v.optional(timeRangeValidator),
+};
+
+export const syncMenstruationArgs = {
+  userId: v.string(),
+  samples: v.array(hkCategorySampleValidator),
+  timeRange: v.optional(timeRangeValidator),
+};
+
+export const syncAthleteArgs = {
+  userId: v.string(),
+  characteristics: hkCharacteristicsValidator,
+};
+
+/**
+ * Args bag for `syncAll`. Every data-type field is optional — only provided
+ * types are synced. Use as: `mutation({ args: syncAllHealthKitArgs, ... })`
+ * or `args: v.object(syncAllHealthKitArgs)` on the host side.
+ */
+export const syncAllHealthKitArgs = {
+  userId: v.string(),
+  workouts: v.optional(v.array(hkWorkoutValidator)),
+  sleepSessions: v.optional(v.array(v.array(hkCategorySampleValidator))),
+  bodySamples: v.optional(v.array(hkQuantitySampleValidator)),
+  bodyTimeRange: v.optional(timeRangeValidator),
+  dailySamples: v.optional(v.array(hkQuantitySampleValidator)),
+  dailyTimeRange: v.optional(timeRangeValidator),
+  dailySummaries: v.optional(v.array(hkActivitySummaryValidator)),
+  nutritionSamples: v.optional(v.array(hkQuantitySampleValidator)),
+  nutritionTimeRange: v.optional(timeRangeValidator),
+  menstruationSamples: v.optional(v.array(hkCategorySampleValidator)),
+  menstruationTimeRange: v.optional(timeRangeValidator),
+  characteristics: v.optional(hkCharacteristicsValidator),
+};
+
+// ─── Return validators ──────────────────────────────────────────────────────
+
+const countResult = (countKey: string) =>
+  v.object({
+    data: v.object({ [countKey]: v.number() }),
+    errors: v.array(somaErrorValidator),
+  });
+
+export const syncActivitiesReturn = countResult("activities");
+export const syncSleepReturn = countResult("sleep");
+export const syncBodyReturn = countResult("body");
+export const syncDailyReturn = countResult("daily");
+export const syncNutritionReturn = countResult("nutrition");
+export const syncMenstruationReturn = countResult("menstruation");
+export const syncAthleteReturn = countResult("athletes");
+
+/** syncAll aggregates counts across data types; keys are not enumerated. */
+export const syncAllReturn = v.object({
+  data: v.record(v.string(), v.number()),
+  errors: v.array(somaErrorValidator),
+});