@nativesquare/soma 0.8.0 → 0.9.1

package/src/{garmin/maps/activity-type.ts → component/garmin/transform/maps/activityType.ts}

@@ -1,116 +1,116 @@
-// ─── Garmin ActivityType → Terra ActivityType ─────────────────────────────────
-// Maps Garmin activity type strings to Terra's ActivityType numeric enum
-// used by the Soma schema.
-//
-// Garmin values: Garmin Health API activity type strings
-// Terra values:  https://docs.tryterra.co/reference/health-and-fitness-api/data-models#activitytype
-
-// Garmin activityType is a free-form string in the spec
-
-const activityTypeMap: Record<string, number> = {
-  // ── Running ─────────────────────────────────────────────────────────────
-  // Terra Running = 8
-  RUNNING: 8,
-  INDOOR_RUNNING: 8,
-  TRAIL_RUNNING: 8,
-  TREADMILL_RUNNING: 8,
-
-  // ── Cycling ─────────────────────────────────────────────────────────────
-  // Terra Biking = 1
-  CYCLING: 1,
-  INDOOR_CYCLING: 1,
-  MOUNTAIN_BIKING: 1,
-  GRAVEL_CYCLING: 1,
-  VIRTUAL_RIDE: 1,
-
-  // ── Walking ─────────────────────────────────────────────────────────────
-  // Terra Walking = 7
-  WALKING: 7,
-
-  // ── Hiking ──────────────────────────────────────────────────────────────
-  // Terra Hiking = 35
-  HIKING: 35,
-
-  // ── Swimming ────────────────────────────────────────────────────────────
-  // Terra Swimming = 82
-  SWIMMING: 82,
-  OPEN_WATER_SWIMMING: 82,
-  LAP_SWIMMING: 82,
-  POOL_SWIMMING: 82,
-
-  // ── Gym / Fitness ───────────────────────────────────────────────────────
-  STRENGTH_TRAINING: 80,  // Terra Strength Training
-  YOGA: 100,              // Terra Yoga
-  PILATES: 49,            // Terra Pilates
-  CARDIO: 108,            // Terra Other
-  ELLIPTICAL: 25,         // Terra Elliptical
-  STAIR_CLIMBING: 78,     // Terra Stair Climbing Machine
-  CROSSFIT: 113,          // Terra Crossfit
-  HIIT: 114,              // Terra HIIT
-  FITNESS_EQUIPMENT: 108, // Terra Other
-  BREATHWORK: 108,        // Terra Other
-
-  // ── Snow Sports ─────────────────────────────────────────────────────────
-  CROSS_COUNTRY_SKIING: 67, // Terra Cross Country Skiing
-  ALPINE_SKIING: 66,        // Terra Alpine Skiing
-  SNOWBOARDING: 73,         // Terra Snowboarding
-  SNOWSHOEING: 74,          // Terra Snowshoeing
-
-  // ── Water Sports ────────────────────────────────────────────────────────
-  ROWING: 53,           // Terra Rowing
-  INDOOR_ROWING: 53,    // Terra Rowing
-  KAYAKING: 40,         // Terra Kayaking
-  CANOEING: 22,         // Terra Canoeing
-  SAILING: 59,          // Terra Sailing
-  SURFING: 81,          // Terra Surfing
-  KITESURFING: 41,      // Terra Kitesurfing
-  WINDSURFING: 99,      // Terra Windsurfing
-  PADDLEBOARDING: 129,  // Terra Paddling
-
-  // ── Skating ─────────────────────────────────────────────────────────────
-  SKATING: 62,        // Terra Skating
-  INLINE_SKATING: 62, // Terra Skating
-
-  // ── Racket Sports ───────────────────────────────────────────────────────
-  TENNIS: 87,       // Terra Tennis
-  TABLE_TENNIS: 85, // Terra Table Tennis
-  BADMINTON: 10,    // Terra Badminton
-  RACQUETBALL: 51,  // Terra Racquetball
-  SQUASH: 76,       // Terra Squash
-
-  // ── Climbing ────────────────────────────────────────────────────────────
-  ROCK_CLIMBING: 52, // Terra Rock Climbing
-  BOULDERING: 52,    // Terra Rock Climbing
-
-  // ── Team Sports ─────────────────────────────────────────────────────────
-  SOCCER: 29,       // Terra English Football
-  BASKETBALL: 11,   // Terra Basketball
-  VOLLEYBALL: 94,   // Terra Volleyball
-  CRICKET: 23,      // Terra Cricket
-  RUGBY: 57,        // Terra Rugby
-
-  // ── Combat Sports ───────────────────────────────────────────────────────
-  BOXING: 16,        // Terra Boxing
-  MARTIAL_ARTS: 44,  // Terra Martial Arts
-
-  // ── Golf ────────────────────────────────────────────────────────────────
-  GOLF: 32, // Terra Golf
-
-  // ── Accessibility ───────────────────────────────────────────────────────
-  HANDCYCLING: 14,            // Terra Handbiking
-  WHEELCHAIR_PUSH_WALKING: 98, // Terra Wheelchair
-  WHEELCHAIR_PUSH_RUNNING: 98, // Terra Wheelchair
-
-  // ── Other ───────────────────────────────────────────────────────────────
-  OTHER: 108,        // Terra Other
-  MULTI_SPORT: 108,  // Terra Other
-  FLOOR_CLIMBING: 78, // Terra Stair Climbing Machine
-};
-
-/**
- * Map a Garmin activity type string to the Terra ActivityType enum.
- * Returns Terra "Other" (108) for unknown types.
- */
-export function mapActivityType(activityType: string): number {
-  return activityTypeMap[activityType] ?? 108;
-}
+// ─── Garmin ActivityType → Terra ActivityType ─────────────────────────────────
+// Maps Garmin activity type strings to Terra's ActivityType numeric enum
+// used by the Soma schema.
+//
+// Garmin values: Garmin Health API activity type strings
+// Terra values:  https://docs.tryterra.co/reference/health-and-fitness-api/data-models#activitytype
+
+// Garmin activityType is a free-form string in the spec
+
+const activityTypeMap: Record<string, number> = {
+  // ── Running ─────────────────────────────────────────────────────────────
+  // Terra Running = 8
+  RUNNING: 8,
+  INDOOR_RUNNING: 8,
+  TRAIL_RUNNING: 8,
+  TREADMILL_RUNNING: 8,
+
+  // ── Cycling ─────────────────────────────────────────────────────────────
+  // Terra Biking = 1
+  CYCLING: 1,
+  INDOOR_CYCLING: 1,
+  MOUNTAIN_BIKING: 1,
+  GRAVEL_CYCLING: 1,
+  VIRTUAL_RIDE: 1,
+
+  // ── Walking ─────────────────────────────────────────────────────────────
+  // Terra Walking = 7
+  WALKING: 7,
+
+  // ── Hiking ──────────────────────────────────────────────────────────────
+  // Terra Hiking = 35
+  HIKING: 35,
+
+  // ── Swimming ────────────────────────────────────────────────────────────
+  // Terra Swimming = 82
+  SWIMMING: 82,
+  OPEN_WATER_SWIMMING: 82,
+  LAP_SWIMMING: 82,
+  POOL_SWIMMING: 82,
+
+  // ── Gym / Fitness ───────────────────────────────────────────────────────
+  STRENGTH_TRAINING: 80,  // Terra Strength Training
+  YOGA: 100,              // Terra Yoga
+  PILATES: 49,            // Terra Pilates
+  CARDIO: 108,            // Terra Other
+  ELLIPTICAL: 25,         // Terra Elliptical
+  STAIR_CLIMBING: 78,     // Terra Stair Climbing Machine
+  CROSSFIT: 113,          // Terra Crossfit
+  HIIT: 114,              // Terra HIIT
+  FITNESS_EQUIPMENT: 108, // Terra Other
+  BREATHWORK: 108,        // Terra Other
+
+  // ── Snow Sports ─────────────────────────────────────────────────────────
+  CROSS_COUNTRY_SKIING: 67, // Terra Cross Country Skiing
+  ALPINE_SKIING: 66,        // Terra Alpine Skiing
+  SNOWBOARDING: 73,         // Terra Snowboarding
+  SNOWSHOEING: 74,          // Terra Snowshoeing
+
+  // ── Water Sports ────────────────────────────────────────────────────────
+  ROWING: 53,           // Terra Rowing
+  INDOOR_ROWING: 53,    // Terra Rowing
+  KAYAKING: 40,         // Terra Kayaking
+  CANOEING: 22,         // Terra Canoeing
+  SAILING: 59,          // Terra Sailing
+  SURFING: 81,          // Terra Surfing
+  KITESURFING: 41,      // Terra Kitesurfing
+  WINDSURFING: 99,      // Terra Windsurfing
+  PADDLEBOARDING: 129,  // Terra Paddling
+
+  // ── Skating ─────────────────────────────────────────────────────────────
+  SKATING: 62,        // Terra Skating
+  INLINE_SKATING: 62, // Terra Skating
+
+  // ── Racket Sports ───────────────────────────────────────────────────────
+  TENNIS: 87,       // Terra Tennis
+  TABLE_TENNIS: 85, // Terra Table Tennis
+  BADMINTON: 10,    // Terra Badminton
+  RACQUETBALL: 51,  // Terra Racquetball
+  SQUASH: 76,       // Terra Squash
+
+  // ── Climbing ────────────────────────────────────────────────────────────
+  ROCK_CLIMBING: 52, // Terra Rock Climbing
+  BOULDERING: 52,    // Terra Rock Climbing
+
+  // ── Team Sports ─────────────────────────────────────────────────────────
+  SOCCER: 29,       // Terra English Football
+  BASKETBALL: 11,   // Terra Basketball
+  VOLLEYBALL: 94,   // Terra Volleyball
+  CRICKET: 23,      // Terra Cricket
+  RUGBY: 57,        // Terra Rugby
+
+  // ── Combat Sports ───────────────────────────────────────────────────────
+  BOXING: 16,        // Terra Boxing
+  MARTIAL_ARTS: 44,  // Terra Martial Arts
+
+  // ── Golf ────────────────────────────────────────────────────────────────
+  GOLF: 32, // Terra Golf
+
+  // ── Accessibility ───────────────────────────────────────────────────────
+  HANDCYCLING: 14,            // Terra Handbiking
+  WHEELCHAIR_PUSH_WALKING: 98, // Terra Wheelchair
+  WHEELCHAIR_PUSH_RUNNING: 98, // Terra Wheelchair
+
+  // ── Other ───────────────────────────────────────────────────────────────
+  OTHER: 108,        // Terra Other
+  MULTI_SPORT: 108,  // Terra Other
+  FLOOR_CLIMBING: 78, // Terra Stair Climbing Machine
+};
+
+/**
+ * Map a Garmin activity type string to the Terra ActivityType enum.
+ * Returns Terra "Other" (108) for unknown types.
+ */
+export function mapActivityType(activityType: string): number {
+  return activityTypeMap[activityType] ?? 108;
+}

package/src/{garmin/maps/sleep-level.ts → component/garmin/transform/maps/sleepLevel.ts}

@@ -1,22 +1,22 @@
-// ─── Garmin Sleep Stage → Terra SleepLevel ────────────────────────────────────
-// Maps Garmin sleep stage names to Terra's SleepLevel numeric enum.
-//
-// Garmin provides sleep levels as named map keys in sleepLevelsMap:
-//   { deep: [...], light: [...], rem: [...], awake: [...] }
-//
-// Terra SleepLevel: 0=Unknown, 1=Awake, 2=Sleeping, 3=OutOfBed, 4=Light, 5=Deep, 6=REM
-
-const sleepLevelMap: Record<string, number> = {
-  deep: 5,   // Deep → Terra Deep
-  light: 4,  // Light → Terra Light
-  rem: 6,    // REM → Terra REM
-  awake: 1,  // Awake → Terra Awake
-};
-
-/**
- * Map a Garmin sleep stage name to the Terra SleepLevel enum.
- * Returns 0 (Unknown) for unrecognized stages.
- */
-export function mapSleepLevel(stage: string): number {
-  return sleepLevelMap[stage] ?? 0;
-}
+// ─── Garmin Sleep Stage → Terra SleepLevel ────────────────────────────────────
+// Maps Garmin sleep stage names to Terra's SleepLevel numeric enum.
+//
+// Garmin provides sleep levels as named map keys in sleepLevelsMap:
+//   { deep: [...], light: [...], rem: [...], awake: [...] }
+//
+// Terra SleepLevel: 0=Unknown, 1=Awake, 2=Sleeping, 3=OutOfBed, 4=Light, 5=Deep, 6=REM
+
+const sleepLevelMap: Record<string, number> = {
+  deep: 5,   // Deep → Terra Deep
+  light: 4,  // Light → Terra Light
+  rem: 6,    // REM → Terra REM
+  awake: 1,  // Awake → Terra Awake
+};
+
+/**
+ * Map a Garmin sleep stage name to the Terra SleepLevel enum.
+ * Returns 0 (Unknown) for unrecognized stages.
+ */
+export function mapSleepLevel(stage: string): number {
+  return sleepLevelMap[stage] ?? 0;
+}

package/src/component/garmin/transform/menstrualCycleTracking.ts

@@ -0,0 +1,48 @@
+// ─── Menstrual Cycle Tracking Transformer ────────────────────────────────────
+// Transforms a Garmin MCT (Women's Health API) push item into the Soma
+// Menstruation schema shape.
+//
+// MCT summaries contain cycle schedule data (phase, length, fertile window,
+// pregnancy snapshot). We map these into the Menstruation model's
+// menstruation_data fields.
+
+import type { SomaMenstruation } from "../../validators/menstruation.js";
+import type { ClientSummarizedMenstrualCycle } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin MCT push item into a Soma Menstruation document shape.
+ *
+ * MCT records are ingested into the `menstruation` table via
+ * `ingestMenstruation`, keyed by `metadata.start_time + metadata.end_time`.
+ */
+export function transformMenstrualCycleTracking(data: ClientSummarizedMenstrualCycle): SomaMenstruation {
+  const dateStr = data.periodStartDate;
+  const startTime = dateStr
+    ? `${dateStr}T00:00:00.000Z`
+    : new Date(0).toISOString();
+  const endTime = dateStr
+    ? `${dateStr}T23:59:59.999Z`
+    : new Date(0).toISOString();
+
+  return {
+    metadata: {
+      start_time: startTime,
+      end_time: endTime,
+    },
+
+    menstruation_data: {
+      day_in_cycle: data.dayInCycle,
+      current_phase: data.currentPhaseType?.toLowerCase(),
+      length_of_current_phase_days: data.lengthOfCurrentPhase,
+      days_until_next_phase: data.daysUntilNextPhase,
+      period_length_days: data.periodLength,
+      predicted_cycle_length_days: data.predictedCycleLength,
+      cycle_length_days: data.cycleLength != null
+        ? String(data.cycleLength)
+        : undefined,
+      is_predicted_cycle: data.isPredictedCycle != null
+        ? String(data.isPredictedCycle)
+        : undefined,
+    },
+  };
+}

package/src/component/garmin/transform/moveIQ.ts

@@ -0,0 +1,48 @@
+// ─── Move IQ Transformer ─────────────────────────────────────────────────────
+// Transforms a Garmin Move IQ event into the Soma Activity schema shape.
+//
+// Move IQ events are auto-detected activities (e.g. walking, running, cycling)
+// recognised by the Garmin device without user interaction. They are lightweight
+// — no GPS, heart rate, or calorie data — just type, duration, and device.
+
+import type { ClientAutoActivityMoveIq } from "../types/wellnessApi/types.gen.js";
+import { mapActivityType } from "./maps/activityType.js";
+import type { SomaActivity } from "../../validators/activity.js";
+
+/**
+ * Transform a Garmin Move IQ event into a Soma Activity document shape.
+ *
+ * Move IQ activityType values are lowercase (e.g. "running", "cycling"),
+ * unlike regular activities which use uppercase. We normalise to uppercase
+ * before mapping.
+ *
+ * The returned object is ready to be spread into an `ingestActivity` call
+ * alongside `connectionId` and `userId`.
+ */
+export function transformMoveIQ(event: ClientAutoActivityMoveIq): SomaActivity {
+  const startMs = (event.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (event.durationInSeconds ?? 0) * 1000;
+  const startDate = new Date(startMs).toISOString();
+  const endDate = new Date(endMs).toISOString();
+
+  // Move IQ activityType is lowercase; mapActivityType expects uppercase
+  const activityType = (event.activityType ?? "OTHER").toUpperCase();
+
+  return {
+    metadata: {
+      summary_id: event.summaryId ?? `moveiq-${event.startTimeInSeconds}`,
+      start_time: startDate,
+      end_time: endDate,
+      type: mapActivityType(activityType),
+      upload_type: 1, // device-detected
+    },
+
+    active_durations_data: {
+      activity_seconds: event.durationInSeconds,
+    },
+
+    device_data: event.deviceName
+      ? { name: event.deviceName }
+      : undefined,
+  };
+}