@nativesquare/soma 0.1.0

package/src/healthkit/index.ts

@@ -0,0 +1,59 @@
+// ─── @nativesquare/soma/healthkit ─────────────────────────────────────────────
+// Apple HealthKit → Soma schema transformers.
+//
+// Pure TypeScript functions with zero runtime dependencies.
+// Compatible with any HealthKit library (react-native-health, expo-health, etc.)
+
+// ── Transformers ─────────────────────────────────────────────────────────────
+export { transformWorkout } from "./activity.js";
+export type { ActivityData } from "./activity.js";
+
+export { transformSleep } from "./sleep.js";
+export type { SleepData } from "./sleep.js";
+
+export { transformBody } from "./body.js";
+export type { BodyData } from "./body.js";
+
+export { transformDaily, transformDailyFromSummary } from "./daily.js";
+export type { DailyData } from "./daily.js";
+
+export { transformNutrition } from "./nutrition.js";
+export type { NutritionData } from "./nutrition.js";
+
+export { transformMenstruation } from "./menstruation.js";
+export type { MenstruationData } from "./menstruation.js";
+
+export { transformAthlete } from "./athlete.js";
+export type { AthleteData } from "./athlete.js";
+
+// ── Enum Maps ────────────────────────────────────────────────────────────────
+export { mapActivityType } from "./maps/activity-type.js";
+export { mapSleepLevel, isAsleepCategory } from "./maps/sleep-level.js";
+export { mapMenstruationFlow } from "./maps/menstruation-flow.js";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type {
+  HKQuantitySample,
+  HKCategorySample,
+  HKWorkout,
+  HKWorkoutRoute,
+  HKActivitySummary,
+  HKDevice,
+  HKSource,
+  HKCharacteristics,
+  HKBiologicalSex,
+  HKQuantityTypeIdentifier,
+  HKCategoryTypeIdentifier,
+  HKSleepCategoryValue,
+  HKMenstrualFlowCategoryValue,
+} from "./types.js";
+
+export { HKSleepCategory, HKMenstrualFlowCategory } from "./types.js";
+
+// ── Utilities ────────────────────────────────────────────────────────────────
+export {
+  diffSeconds,
+  dayRange,
+  sampleTimeRange,
+  buildDeviceData,
+} from "./utils.js";

package/src/healthkit/maps/activity-type.ts

@@ -0,0 +1,185 @@
+// ─── HKWorkoutActivityType → Terra ActivityType ──────────────────────────────
+// Maps Apple HealthKit workout activity type raw values to Terra's ActivityType
+// enum used by the Soma schema.
+//
+// HK values: https://developer.apple.com/documentation/healthkit/hkworkoutactivitytype
+// Terra values: https://docs.tryterra.co/reference/health-and-fitness-api/data-models#activitytype
+
+const activityTypeMap: Record<number, number> = {
+  // HK AmericanFootball (1) → Terra American Football (27)
+  1: 27,
+  // HK Archery (2) → Terra Archery (119)
+  2: 119,
+  // HK AustralianFootball (3) → Terra Australian Football (28)
+  3: 28,
+  // HK Badminton (4) → Terra Badminton (10)
+  4: 10,
+  // HK Baseball (5) → Terra Baseball (11)
+  5: 11,
+  // HK Basketball (6) → Terra Basketball (12)
+  6: 12,
+  // HK Bowling (7) → Terra Other (108)
+  7: 108,
+  // HK Boxing (8) → Terra Boxing (20)
+  8: 20,
+  // HK Climbing (9) → Terra Rock Climbing (52)
+  9: 52,
+  // HK Cricket (10) → Terra Cricket (23)
+  10: 23,
+  // HK CrossTraining (11) → Terra Crossfit (113)
+  11: 113,
+  // HK Curling (12) → Terra Curling (106)
+  12: 106,
+  // HK Cycling (13) → Terra Biking (1)
+  13: 1,
+  // HK Dance (14) → Terra Dancing (24)
+  14: 24,
+  // HK DanceInspiredTraining (15) → Terra Dancing (24)
+  15: 24,
+  // HK Elliptical (16) → Terra Elliptical (25)
+  16: 25,
+  // HK EquestrianSports (17) → Terra Horseback Riding (37)
+  17: 37,
+  // HK Fencing (18) → Terra Fencing (26)
+  18: 26,
+  // HK Fishing (19) → Terra Fishing (131)
+  19: 131,
+  // HK FunctionalStrengthTraining (20) → Terra Strength Training (80)
+  20: 80,
+  // HK Golf (21) → Terra Golf (32)
+  21: 32,
+  // HK Gymnastics (22) → Terra Gymnastics (33)
+  22: 33,
+  // HK Handball (23) → Terra Handball (34)
+  23: 34,
+  // HK Hiking (24) → Terra Hiking (35)
+  24: 35,
+  // HK Hockey (25) → Terra Hockey (36)
+  25: 36,
+  // HK Hunting (26) → Terra Other (108)
+  26: 108,
+  // HK Lacrosse (27) → Terra Lacrosse (124)
+  27: 124,
+  // HK MartialArts (28) → Terra Martial Arts (44)
+  28: 44,
+  // HK MindAndBody (29) → Terra Meditation (45)
+  29: 45,
+  // HK MixedMetabolicCardioTraining (30) → Terra Cardio Training (123)
+  30: 123,
+  // HK PaddleSports (31) → Terra Paddling (129)
+  31: 129,
+  // HK Play (32) → Terra Other (108)
+  32: 108,
+  // HK PreparationAndRecovery (33) → Terra Stretching (125)
+  33: 125,
+  // HK Racquetball (34) → Terra Racquetball (51)
+  34: 51,
+  // HK Rowing (35) → Terra Rowing (53)
+  35: 53,
+  // HK Rugby (36) → Terra Rugby (55)
+  36: 55,
+  // HK Running (37) → Terra Running (8)
+  37: 8,
+  // HK Sailing (38) → Terra Sailing (59)
+  38: 59,
+  // HK SkatingSports (39) → Terra Skating (62)
+  39: 62,
+  // HK SnowSports (40) → Terra Skiing (65)
+  40: 65,
+  // HK Soccer (41) → Terra English Football (29)
+  41: 29,
+  // HK Softball (42) → Terra Softball (120)
+  42: 120,
+  // HK Squash (43) → Terra Squash (76)
+  43: 76,
+  // HK StairClimbing (44) → Terra Stair Climbing (77)
+  44: 77,
+  // HK SurfingSports (45) → Terra Surfing (81)
+  45: 81,
+  // HK Swimming (46) → Terra Swimming (82)
+  46: 82,
+  // HK TableTennis (47) → Terra Table Tennis (85)
+  47: 85,
+  // HK Tennis (48) → Terra Tennis (87)
+  48: 87,
+  // HK TrackAndField (49) → Terra Running (8)
+  49: 8,
+  // HK TraditionalStrengthTraining (50) → Terra Strength Training (80)
+  50: 80,
+  // HK Volleyball (51) → Terra Volleyball (89)
+  51: 89,
+  // HK Walking (52) → Terra Walking (7)
+  52: 7,
+  // HK WaterFitness (53) → Terra Swimming (82)
+  53: 82,
+  // HK WaterPolo (54) → Terra Waterpolo (96)
+  54: 96,
+  // HK WaterSports (55) → Terra Other (108)
+  55: 108,
+  // HK Wrestling (56) → Terra Martial Arts (44)
+  56: 44,
+  // HK Yoga (57) → Terra Yoga (100)
+  57: 100,
+  // HK Barre (58) → Terra Dancing (24)
+  58: 24,
+  // HK CoreTraining (59) → Terra Calisthenics (21)
+  59: 21,
+  // HK CrossCountrySkiing (60) → Terra Cross Country Skiing (67)
+  60: 67,
+  // HK DownhillSkiing (61) → Terra Downhill Skiing (68)
+  61: 68,
+  // HK Flexibility (62) → Terra Stretching (125)
+  62: 125,
+  // HK HighIntensityIntervalTraining (63) → Terra HIIT (114)
+  63: 114,
+  // HK JumpRope (64) → Terra Jumping Rope (39)
+  64: 39,
+  // HK Kickboxing (65) → Terra Kickboxing (42)
+  65: 42,
+  // HK Pilates (66) → Terra Pilates (49)
+  66: 49,
+  // HK Snowboarding (67) → Terra Snowboarding (73)
+  67: 73,
+  // HK Stairs (68) → Terra Stair Climbing (77)
+  68: 77,
+  // HK StepTraining (69) → Terra Stair Climbing Machine (78)
+  69: 78,
+  // HK WheelchairWalkPace (70) → Terra Wheelchair (98)
+  70: 98,
+  // HK WheelchairRunPace (71) → Terra Wheelchair (98)
+  71: 98,
+  // HK TaiChi (72) → Terra Meditation (45)
+  72: 45,
+  // HK MixedCardio (73) → Terra Cardio Training (123)
+  73: 123,
+  // HK HandCycling (74) → Terra Handbiking (14)
+  74: 14,
+  // HK DiscSports (75) → Terra Frisbee (30)
+  75: 30,
+  // HK FitnessGaming (76) → Terra Other (108)
+  76: 108,
+  // HK CardioDance (77) → Terra Dancing (24)
+  77: 24,
+  // HK SocialDance (78) → Terra Dancing (24)
+  78: 24,
+  // HK Pickleball (79) → Terra Other (108)
+  79: 108,
+  // HK Cooldown (80) → Terra Stretching (125)
+  80: 125,
+  // HK SwimBikeRun (82) → Terra Triathlon (126)
+  82: 126,
+  // HK Transition (83) → Terra Other (108)
+  83: 108,
+  // HK UnderwaterDiving (84) → Terra Diving (102)
+  84: 102,
+  // HK Other (3000) → Terra Other (108)
+  3000: 108,
+};
+
+/**
+ * Map an HKWorkoutActivityType raw value to the Terra ActivityType enum.
+ * Returns Terra "Other" (108) for unknown types.
+ */
+export function mapActivityType(hkActivityType: number): number {
+  return activityTypeMap[hkActivityType] ?? 108;
+}

package/src/healthkit/maps/menstruation-flow.ts

@@ -0,0 +1,23 @@
+// ─── HK Menstrual Flow → Terra MenstruationFlow ─────────────────────────────
+// Maps Apple HealthKit menstrual flow category values to Terra's MenstruationFlow enum.
+//
+// HK values: https://developer.apple.com/documentation/healthkit/hkcategoryvaluemenstrualflow
+// Terra MenstruationFlow: 0=UNKNOWN, 1=NONE, 2=LIGHT, 3=MEDIUM, 4=HEAVY, 5=HAD
+
+import { HKMenstrualFlowCategory } from "../types.js";
+
+const menstruationFlowMap: Record<number, number> = {
+  [HKMenstrualFlowCategory.Unspecified]: 5, // Unspecified → HAD (flow occurred, amount unknown)
+  [HKMenstrualFlowCategory.Light]: 2, // Light → LIGHT
+  [HKMenstrualFlowCategory.Medium]: 3, // Medium → MEDIUM
+  [HKMenstrualFlowCategory.Heavy]: 4, // Heavy → HEAVY
+  [HKMenstrualFlowCategory.None]: 1, // None → NONE
+};
+
+/**
+ * Map an HKCategoryValueMenstrualFlow value to the Terra MenstruationFlow enum.
+ * Returns 0 (UNKNOWN) for unrecognized values.
+ */
+export function mapMenstruationFlow(hkFlowValue: number): number {
+  return menstruationFlowMap[hkFlowValue] ?? 0;
+}

package/src/healthkit/maps/sleep-level.ts

@@ -0,0 +1,37 @@
+// ─── HK Sleep Category → Terra SleepLevel ────────────────────────────────────
+// Maps Apple HealthKit sleep analysis category values to Terra's SleepLevel enum.
+//
+// HK values: https://developer.apple.com/documentation/healthkit/hkcategoryvaluesleepanalysis
+// Terra SleepLevel: 0=Unknown, 1=Awake, 2=Sleeping, 3=OutOfBed, 4=Light, 5=Deep, 6=REM
+
+import { HKSleepCategory } from "../types.js";
+
+const sleepLevelMap: Record<number, number> = {
+  [HKSleepCategory.InBed]: 2, // InBed → Sleeping (generic)
+  [HKSleepCategory.AsleepUnspecified]: 2, // AsleepUnspecified → Sleeping
+  [HKSleepCategory.Awake]: 1, // Awake → Awake
+  [HKSleepCategory.AsleepCore]: 4, // AsleepCore → Light
+  [HKSleepCategory.AsleepDeep]: 5, // AsleepDeep → Deep
+  [HKSleepCategory.AsleepREM]: 6, // AsleepREM → REM
+};
+
+/**
+ * Map an HKCategoryValueSleepAnalysis value to the Terra SleepLevel enum.
+ * Returns 0 (Unknown) for unrecognized values.
+ */
+export function mapSleepLevel(hkSleepValue: number): number {
+  return sleepLevelMap[hkSleepValue] ?? 0;
+}
+
+/**
+ * Returns true if the HK sleep category represents an "asleep" state
+ * (not awake, not just in bed).
+ */
+export function isAsleepCategory(hkSleepValue: number): boolean {
+  return (
+    hkSleepValue === HKSleepCategory.AsleepUnspecified ||
+    hkSleepValue === HKSleepCategory.AsleepCore ||
+    hkSleepValue === HKSleepCategory.AsleepDeep ||
+    hkSleepValue === HKSleepCategory.AsleepREM
+  );
+}

package/src/healthkit/menstruation.ts

@@ -0,0 +1,52 @@
+// ─── Menstruation Transformer ─────────────────────────────────────────────────
+// Transforms Apple HealthKit menstrual flow samples into the Soma Menstruation schema.
+
+import type { HKCategorySample } from "./types.js";
+import { mapMenstruationFlow } from "./maps/menstruation-flow.js";
+import { sampleTimeRange } from "./utils.js";
+
+/**
+ * The output shape of {@link transformMenstruation}.
+ */
+export type MenstruationData = ReturnType<typeof transformMenstruation>;
+
+/**
+ * Transform an array of HealthKit menstrual flow category samples into a
+ * Soma Menstruation document shape.
+ *
+ * @param samples - Array of HKCategorySample with sampleType "HKCategoryTypeIdentifierMenstrualFlow"
+ * @param timeRange - Optional explicit time range; auto-detected from samples if omitted
+ * @returns Soma Menstruation fields (without connectionId/userId)
+ *
+ * @example
+ * ```ts
+ * const data = transformMenstruation(hkMenstrualSamples);
+ * await soma.ingestMenstruation(ctx, { connectionId, userId, ...data });
+ * ```
+ */
+export function transformMenstruation(
+  samples: HKCategorySample[],
+  timeRange?: { start_time: string; end_time: string },
+) {
+  if (samples.length === 0) {
+    throw new Error(
+      "transformMenstruation requires at least one menstrual flow sample",
+    );
+  }
+
+  const range = timeRange ?? sampleTimeRange(samples);
+
+  return {
+    metadata: {
+      start_time: range.start_time,
+      end_time: range.end_time,
+    },
+
+    menstruation_data: {
+      menstruation_flow: samples.map((s) => ({
+        timestamp: s.startDate,
+        flow: mapMenstruationFlow(s.value),
+      })),
+    },
+  };
+}

package/src/healthkit/nutrition.ts

@@ -0,0 +1,162 @@
+// ─── Nutrition Transformer ────────────────────────────────────────────────────
+// Transforms Apple HealthKit dietary quantity samples into the Soma Nutrition schema.
+
+import type { HKQuantitySample } from "./types.js";
+import { filterByType, sumValues, sampleTimeRange } from "./utils.js";
+
+/**
+ * The output shape of {@link transformNutrition}.
+ */
+export type NutritionData = ReturnType<typeof transformNutrition>;
+
+/**
+ * Transform an array of HealthKit dietary quantity samples into a
+ * Soma Nutrition document shape.
+ *
+ * Accepts samples with dietary type identifiers (protein, carbs, fat, water,
+ * vitamins, minerals, etc.) and aggregates them into Soma's macros/micros
+ * summary format.
+ *
+ * @param samples - Array of HKQuantitySample with dietary type identifiers
+ * @param timeRange - Optional explicit time range; auto-detected from samples if omitted
+ * @returns Soma Nutrition fields (without connectionId/userId)
+ *
+ * @example
+ * ```ts
+ * const data = transformNutrition(hkDietarySamples);
+ * await soma.ingestNutrition(ctx, { connectionId, userId, ...data });
+ * ```
+ */
+export function transformNutrition(
+  samples: HKQuantitySample[],
+  timeRange?: { start_time: string; end_time: string },
+) {
+  const range = timeRange ?? sampleTimeRange(samples);
+
+  const sum = (type: string) => {
+    const filtered = filterByType(samples, type);
+    return filtered.length > 0 ? sumValues(filtered) : undefined;
+  };
+
+  // ── Macros ─────────────────────────────────────────────────────────────
+  const calories = sum("HKQuantityTypeIdentifierDietaryEnergyConsumed");
+  const protein = sum("HKQuantityTypeIdentifierDietaryProtein");
+  const carbs = sum("HKQuantityTypeIdentifierDietaryCarbohydrates");
+  const fat = sum("HKQuantityTypeIdentifierDietaryFatTotal");
+  const saturatedFat = sum("HKQuantityTypeIdentifierDietaryFatSaturated");
+  const fiber = sum("HKQuantityTypeIdentifierDietaryFiber");
+  const sugar = sum("HKQuantityTypeIdentifierDietarySugar");
+  const cholesterol = sum("HKQuantityTypeIdentifierDietaryCholesterol");
+  const sodium = sum("HKQuantityTypeIdentifierDietarySodium");
+
+  // ── Micros ─────────────────────────────────────────────────────────────
+  const calcium = sum("HKQuantityTypeIdentifierDietaryCalcium");
+  const iron = sum("HKQuantityTypeIdentifierDietaryIron");
+  const potassium = sum("HKQuantityTypeIdentifierDietaryPotassium");
+  const vitaminA = sum("HKQuantityTypeIdentifierDietaryVitaminA");
+  const vitaminB6 = sum("HKQuantityTypeIdentifierDietaryVitaminB6");
+  const vitaminB12 = sum("HKQuantityTypeIdentifierDietaryVitaminB12");
+  const vitaminC = sum("HKQuantityTypeIdentifierDietaryVitaminC");
+  const vitaminD = sum("HKQuantityTypeIdentifierDietaryVitaminD");
+  const vitaminE = sum("HKQuantityTypeIdentifierDietaryVitaminE");
+  const vitaminK = sum("HKQuantityTypeIdentifierDietaryVitaminK");
+  const zinc = sum("HKQuantityTypeIdentifierDietaryZinc");
+  const magnesium = sum("HKQuantityTypeIdentifierDietaryMagnesium");
+  const manganese = sum("HKQuantityTypeIdentifierDietaryManganese");
+  const copper = sum("HKQuantityTypeIdentifierDietaryCopper");
+  const selenium = sum("HKQuantityTypeIdentifierDietarySelenium");
+  const chromium = sum("HKQuantityTypeIdentifierDietaryChromium");
+  const folate = sum("HKQuantityTypeIdentifierDietaryFolate");
+  const biotin = sum("HKQuantityTypeIdentifierDietaryBiotin");
+  const niacin = sum("HKQuantityTypeIdentifierDietaryNiacin");
+  const phosphorus = sum("HKQuantityTypeIdentifierDietaryPhosphorus");
+  const riboflavin = sum("HKQuantityTypeIdentifierDietaryRiboflavin");
+  const thiamin = sum("HKQuantityTypeIdentifierDietaryThiamin");
+  const caffeine = sum("HKQuantityTypeIdentifierDietaryCaffeine");
+  const iodine = sum("HKQuantityTypeIdentifierDietaryIodine");
+  const chloride = sum("HKQuantityTypeIdentifierDietaryChloride");
+  const pantothenicAcid = sum(
+    "HKQuantityTypeIdentifierDietaryPanthothenicAcid",
+  );
+
+  // ── Fats breakdown ─────────────────────────────────────────────────────
+  const monoFat = sum("HKQuantityTypeIdentifierDietaryFatMonounsaturated");
+  const polyFat = sum("HKQuantityTypeIdentifierDietaryFatPolyunsaturated");
+
+  // ── Water ──────────────────────────────────────────────────────────────
+  const waterSamples = filterByType(
+    samples,
+    "HKQuantityTypeIdentifierDietaryWater",
+  );
+  const waterMl =
+    waterSamples.length > 0 ? sumValues(waterSamples) * 1000 : undefined; // L → mL
+
+  const hasMacros =
+    calories != null ||
+    protein != null ||
+    carbs != null ||
+    fat != null;
+
+  const hasMicros =
+    calcium != null ||
+    iron != null ||
+    vitaminC != null ||
+    zinc != null ||
+    magnesium != null;
+
+  return {
+    metadata: {
+      start_time: range.start_time,
+      end_time: range.end_time,
+    },
+
+    summary: {
+      macros: hasMacros
+        ? {
+            calories,
+            protein_g: protein,
+            carbohydrates_g: carbs,
+            fat_g: fat,
+            saturated_fat_g: saturatedFat,
+            fiber_g: fiber,
+            sugar_g: sugar,
+            cholesterol_mg: cholesterol,
+            sodium_mg: sodium,
+          }
+        : undefined,
+      micros: hasMicros
+        ? {
+            calcium_mg: calcium,
+            iron_mg: iron,
+            potassium_mg: potassium,
+            vitamin_A_mg: vitaminA,
+            vitamin_B6_mg: vitaminB6,
+            vitamin_B12_mg: vitaminB12,
+            vitamin_C_mg: vitaminC,
+            vitamin_D_mg: vitaminD,
+            vitamin_E_mg: vitaminE,
+            vitamin_K_mg: vitaminK,
+            zinc_mg: zinc,
+            magnesium_mg: magnesium,
+            manganese_mg: manganese,
+            copper_mg: copper,
+            selenium_mg: selenium,
+            chromium_mg: chromium,
+            folate_mg: folate,
+            biotin_mg: biotin,
+            niacin_mg: niacin,
+            phosphorus_mg: phosphorus,
+            riboflavin_mg: riboflavin,
+            thiamin_mg: thiamin,
+            caffeine_mg: caffeine,
+            iodine_mg: iodine,
+            chloride_mg: chloride,
+            pantothenic_acid_mg: pantothenicAcid,
+            monounsaturated_fat_g: monoFat,
+            polyunsaturated_fat_g: polyFat,
+          }
+        : undefined,
+      water_ml: waterMl,
+    },
+  };
+}

package/src/healthkit/sleep.ts

@@ -0,0 +1,136 @@
+// ─── Sleep Transformer ───────────────────────────────────────────────────────
+// Transforms Apple HealthKit sleep analysis samples into the Soma Sleep schema.
+
+import type { HKCategorySample } from "./types.js";
+import { HKSleepCategory } from "./types.js";
+import { mapSleepLevel, isAsleepCategory } from "./maps/sleep-level.js";
+import { diffSeconds, buildDeviceData } from "./utils.js";
+
+/**
+ * The output shape of {@link transformSleep}.
+ */
+export type SleepData = ReturnType<typeof transformSleep>;
+
+/**
+ * Transform an array of HealthKit sleep analysis category samples into a
+ * Soma Sleep document shape.
+ *
+ * HealthKit stores sleep as individual `HKCategorySample` records — one per
+ * sleep stage segment. This function aggregates them into a single session
+ * with computed durations, a hypnogram, and efficiency score.
+ *
+ * @param samples - Array of HKCategorySample with sampleType "HKCategoryTypeIdentifierSleepAnalysis".
+ *                  Should represent a single sleep session (all samples from one night).
+ * @returns Soma Sleep fields (without connectionId/userId)
+ *
+ * @example
+ * ```ts
+ * const data = transformSleep(hkSleepSamples);
+ * await soma.ingestSleep(ctx, { connectionId, userId, ...data });
+ * ```
+ */
+export function transformSleep(samples: HKCategorySample[]) {
+  if (samples.length === 0) {
+    throw new Error("transformSleep requires at least one sleep sample");
+  }
+
+  // Sort by start time
+  const sorted = [...samples].sort(
+    (a, b) => new Date(a.startDate).getTime() - new Date(b.startDate).getTime(),
+  );
+
+  const sessionStart = sorted[0].startDate;
+  const sessionEnd = sorted[sorted.length - 1].endDate;
+
+  // Compute stage durations
+  let deepSeconds = 0;
+  let lightSeconds = 0;
+  let remSeconds = 0;
+  let awakeSeconds = 0;
+  let asleepUnspecifiedSeconds = 0;
+  let inBedSeconds = 0;
+  let wakeupEvents = 0;
+  let remEvents = 0;
+
+  for (const sample of sorted) {
+    const duration = diffSeconds(sample.startDate, sample.endDate);
+
+    switch (sample.value) {
+      case HKSleepCategory.AsleepDeep:
+        deepSeconds += duration;
+        break;
+      case HKSleepCategory.AsleepCore:
+        lightSeconds += duration;
+        break;
+      case HKSleepCategory.AsleepREM:
+        remSeconds += duration;
+        remEvents++;
+        break;
+      case HKSleepCategory.Awake:
+        awakeSeconds += duration;
+        wakeupEvents++;
+        break;
+      case HKSleepCategory.AsleepUnspecified:
+        asleepUnspecifiedSeconds += duration;
+        break;
+      case HKSleepCategory.InBed:
+        inBedSeconds += duration;
+        break;
+    }
+  }
+
+  const totalAsleepSeconds =
+    deepSeconds + lightSeconds + remSeconds + asleepUnspecifiedSeconds;
+  const totalInBedSeconds = diffSeconds(sessionStart, sessionEnd);
+  const sleepEfficiency =
+    totalInBedSeconds > 0 ? totalAsleepSeconds / totalInBedSeconds : undefined;
+
+  // Build hypnogram
+  const hypnogramSamples = sorted
+    .filter((s) => s.value !== HKSleepCategory.InBed)
+    .map((s) => ({
+      timestamp: s.startDate,
+      level: mapSleepLevel(s.value),
+    }));
+
+  // Determine if this is a nap (< 3 hours)
+  const isNap = totalInBedSeconds < 3 * 60 * 60;
+
+  const firstSample = sorted[0];
+
+  return {
+    metadata: {
+      start_time: sessionStart,
+      end_time: sessionEnd,
+      summary_id: firstSample.uuid,
+      upload_type: 2 as const, // Automatic
+      is_nap: isNap,
+    },
+
+    device_data: buildDeviceData(firstSample.source, firstSample.device),
+
+    sleep_durations_data: {
+      asleep: {
+        duration_asleep_state_seconds: totalAsleepSeconds,
+        duration_deep_sleep_state_seconds:
+          deepSeconds > 0 ? deepSeconds : undefined,
+        duration_light_sleep_state_seconds:
+          lightSeconds > 0 ? lightSeconds : undefined,
+        duration_REM_sleep_state_seconds:
+          remSeconds > 0 ? remSeconds : undefined,
+        num_REM_events: remEvents > 0 ? remEvents : undefined,
+      },
+      awake: {
+        duration_awake_state_seconds:
+          awakeSeconds > 0 ? awakeSeconds : undefined,
+        num_wakeup_events: wakeupEvents > 0 ? wakeupEvents : undefined,
+      },
+      hypnogram_samples:
+        hypnogramSamples.length > 0 ? hypnogramSamples : undefined,
+      other: {
+        duration_in_bed_seconds: totalInBedSeconds,
+      },
+      sleep_efficiency: sleepEfficiency,
+    },
+  };
+}