@nativesquare/soma 0.7.3 → 0.8.0

package/src/garmin/types.ts

@@ -1,318 +1,100 @@
 // ─── Garmin Health API Response Types ────────────────────────────────────────
-// TypeScript interfaces representing Garmin Health API data shapes.
-// Derived from the Garmin Connect Developer Program documentation.
+// TypeScript types representing Garmin Health API data shapes.
+//
+// Wellness API types are derived from the OpenAPI spec (wellness-api.d.ts).
+// Training API types are manually defined from the Garmin Connect docs.
 //
 // These types define the CONTRACT for data coming from the Garmin API.
 // They are used by transformers, the API client, and OAuth helpers.
 
-// ─── Activity ─────────────────────────────────────────────────────────────────
-
-export interface GarminActivity {
-  userId: string;
-  userAccessToken: string;
-  summaryId: string;
-  activityId: number;
-  activityName?: string;
-  activityType: string;
-  durationInSeconds: number;
-  startTimeInSeconds: number;
-  startTimeOffsetInSeconds: number;
-  deviceName?: string;
-  manual?: boolean;
-
-  // Distance
-  distanceInMeters?: number;
-  elevationGainInMeters?: number;
-  elevationLossInMeters?: number;
-
-  // Calories
-  activeKilocalories?: number;
-  bmrKilocalories?: number;
-
-  // Heart rate
-  averageHeartRateInBeatsPerMinute?: number;
-  maxHeartRateInBeatsPerMinute?: number;
-
-  // Speed / pace
-  averageSpeedInMetersPerSecond?: number;
-  maxSpeedInMetersPerSecond?: number;
-  averagePaceInMinutesPerKilometer?: number;
-  maxPaceInMinutesPerKilometer?: number;
-
-  // Cadence
-  averageRunCadenceInStepsPerMinute?: number;
-  maxRunCadenceInStepsPerMinute?: number;
-  averageBikeCadenceInRoundsPerMinute?: number;
-  maxBikeCadenceInRoundsPerMinute?: number;
-
-  // Power
-  averagePowerInWatts?: number;
-  maxPowerInWatts?: number;
-  normalizedPowerInWatts?: number;
-
-  // Swimming
-  numberOfActiveLengths?: number;
-  poolLengthInMeters?: number;
-  averageSwimCadenceInStrokesPerMinute?: number;
-
-  // Position
-  startingLatitudeInDegree?: number;
-  startingLongitudeInDegree?: number;
-
-  // Steps
-  steps?: number;
-
-  // Laps
-  laps?: GarminActivityLap[];
-
-  // Samples (time-series)
-  samples?: GarminActivitySample[];
-}
-
-export interface GarminActivityLap {
-  startTimeInSeconds: number;
-  airTemperatureCelsius?: number;
-  heartRate?: number;
-  totalDistanceInMeters?: number;
-  timerDurationInSeconds: number;
-  maxSpeed?: number;
-}
-
-export interface GarminActivitySample {
-  startTimeInSeconds?: number;
-  latitudeInDegree?: number;
-  longitudeInDegree?: number;
-  elevationInMeters?: number;
-  heartRate?: number;
-  speedMetersPerSecond?: number;
-  bikeCadenceInRPM?: number;
-  runCadenceInStepsPerMinute?: number;
-  powerInWatts?: number;
-  timerDurationInSeconds?: number;
-}
-
-// ─── Daily Summary ──────────────────────────────────────────────────────────
-
-export interface GarminDailySummary {
-  userId: string;
-  userAccessToken: string;
-  summaryId: string;
-  calendarDate: string; // "YYYY-MM-DD"
-  startTimeInSeconds: number;
-  startTimeOffsetInSeconds: number;
-  durationInSeconds: number;
-
-  // Activity
-  steps?: number;
-  distanceInMeters?: number;
-  floorsClimbed?: number;
-  activeTimeInSeconds?: number;
-  activeKilocalories?: number;
-  bmrKilocalories?: number;
-  moderateIntensityDurationInSeconds?: number;
-  vigorousIntensityDurationInSeconds?: number;
-  intensityDurationGoalInSeconds?: number;
-
-  // Heart rate
-  minHeartRateInBeatsPerMinute?: number;
-  maxHeartRateInBeatsPerMinute?: number;
-  averageHeartRateInBeatsPerMinute?: number;
-  restingHeartRateInBeatsPerMinute?: number;
-  timeOffsetHeartRateSamples?: Record<string, number>;
-
-  // Stress
-  averageStressLevel?: number;
-  maxStressLevel?: number;
-  stressDurationInSeconds?: number;
-  restStressDurationInSeconds?: number;
-  activityStressDurationInSeconds?: number;
-  lowStressDurationInSeconds?: number;
-  mediumStressDurationInSeconds?: number;
-  highStressDurationInSeconds?: number;
+import type { components } from "./wellness-api.js";
+
+// ─── Wellness API Type Aliases ──────────────────────────────────────────────
+// Convenience aliases for the generated OpenAPI schema types.
+
+export type GarminDaily = components["schemas"]["ClientDaily"];
+export type GarminActivity = components["schemas"]["ClientActivity"];
+export type GarminActivityDetail = components["schemas"]["ClientActivityDetail"];
+export type GarminSleep = components["schemas"]["ClientSleep"];
+export type GarminBodyComposition = components["schemas"]["ClientBodyComp"];
+export type GarminMenstrualCycle = components["schemas"]["ClientSummarizedMenstrualCycle"];
+export type GarminUserMetrics = components["schemas"]["ClientUserMetrics"];
+export type GarminStressDetail = components["schemas"]["ClientStress"];
+export type GarminSkinTemperature = components["schemas"]["ClientSkinTemp"];
+export type GarminRespiration = components["schemas"]["ClientRespiration"];
+export type GarminPulseOx = components["schemas"]["ClientDailySpo2Acclimation"];
+export type GarminMoveIQEvent = components["schemas"]["ClientAutoActivityMoveIq"];
+export type GarminHRVSummary = components["schemas"]["ClientHRVSummary"];
+export type GarminHealthSnapshot = components["schemas"]["ClientHealthSnapshot"];
+export type GarminEpoch = components["schemas"]["ClientEpoch"];
+export type GarminBloodPressure = components["schemas"]["ClientBloodPressure"];
+export type GarminSolar = components["schemas"]["ClientSolar"];
+export type GarminSample = components["schemas"]["Sample"];
+export type GarminLap = components["schemas"]["ClientLap"];
+export type GarminTimeRange = components["schemas"]["TimeRange"];
+export type GarminSleepScoreItem = components["schemas"]["ClientSleepScoreItem"];
+export type GarminNap = components["schemas"]["ClientNaps"];
+
+// ─── Extended Types ─────────────────────────────────────────────────────────
+// The Garmin API returns additional fields beyond what the OpenAPI spec
+// documents. These extended types add those fields so transformers can use them.
+
+// Extended daily type with fields the API returns beyond what the spec documents
+export type GarminDailyExtended = GarminDaily & {
+  // Time-series stress data (returned by API, not in spec)
   timeOffsetStressLevelValues?: Record<string, number>;
-
-  // Body battery
   timeOffsetBodyBatteryValues?: Record<string, number>;
-
-  // Pulse Ox
+  // SpO2 data (returned by API, not in spec)
   averageSpo2Value?: number;
   lowestSpo2Value?: number;
   latestSpo2Value?: number;
   timeOffsetSpo2Values?: Record<string, number>;
-
-  // Respiration
+  // Respiration data (returned by API, not in spec)
   averageRespirationInBreathsPerMinute?: number;
   lowestRespirationInBreathsPerMinute?: number;
   highestRespirationInBreathsPerMinute?: number;
   timeOffsetRespirationSamples?: Record<string, number>;
-}
-
-// ─── Sleep ──────────────────────────────────────────────────────────────────
-
-export interface GarminSleep {
-  userId: string;
-  userAccessToken: string;
-  summaryId: string;
-  calendarDate: string;
-  startTimeInSeconds: number;
-  startTimeOffsetInSeconds: number;
-  durationInSeconds: number;
-  unmeasurableSleepInSeconds?: number;
-
-  // Sleep stages
-  deepSleepDurationInSeconds?: number;
-  lightSleepDurationInSeconds?: number;
-  remSleepInSeconds?: number;
-  awakeDurationInSeconds?: number;
+};
 
-  // Nap
-  totalNapDurationInSeconds?: number;
-
-  // Validation
-  validation: "ENHANCED_TENTATIVE" | "ENHANCED_FINAL" | "AUTO_TENTATIVE" | "AUTO_FINAL" | "MANUAL" | string;
-
-  // Respiration
+// Extended sleep type with fields the API returns beyond what the spec documents
+export type GarminSleepExtended = GarminSleep & {
+  // Respiration aggregates (returned by API, not in spec)
   averageRespirationInBreathsPerMinute?: number;
   lowestRespirationInBreathsPerMinute?: number;
   highestRespirationInBreathsPerMinute?: number;
-  timeOffsetSleepRespiration?: Record<string, number>;
-
-  // SpO2
+  // SpO2 aggregates (returned by API, not in spec)
   averageSpo2Value?: number;
   lowestSpo2Value?: number;
   highestSpo2Value?: number;
-  timeOffsetSpo2Values?: Record<string, number>;
-
-  // Sleep levels (time-series)
-  sleepLevelsMap?: {
-    deep?: GarminSleepLevel[];
-    light?: GarminSleepLevel[];
-    rem?: GarminSleepLevel[];
-    awake?: GarminSleepLevel[];
-  };
-
-  // Heart rate
+  // Heart rate samples (returned by API, not in spec)
   timeOffsetHeartRateSamples?: Record<string, number>;
-}
-
-export interface GarminSleepLevel {
-  startTimeInSeconds: number;
-  endTimeInSeconds: number;
-}
-
-// ─── Body Composition ───────────────────────────────────────────────────────
-
-export interface GarminBodyComposition {
-  userId: string;
-  userAccessToken: string;
-  summaryId?: string;
-  measurementTimeInSeconds: number;
-  measurementTimeOffsetInSeconds?: number;
-
-  muscleMassInGrams?: number;
-  boneMassInGrams?: number;
-  bodyWaterInPercent?: number;
-  bodyFatInPercent?: number;
-  bodyMassIndex?: number;
-  weightInGrams?: number;
-}
-
-// ─── Menstrual Cycle ────────────────────────────────────────────────────────
-
-export interface GarminMenstrualCycleData {
-  userId: string;
-  userAccessToken: string;
-  summaryId?: string;
-  calendarDate: string;
-  startTimeInSeconds?: number;
-  startTimeOffsetInSeconds?: number;
-
-  dayInCycle?: number;
-  currentPhase?: string;
-  lengthOfCurrentPhase?: number;
-  periodLength?: number;
-  predictedCycleLength?: number;
-  isPredictedCycle?: boolean;
-}
-
-// ─── User Profile ───────────────────────────────────────────────────────────
-// Limited profile info available from the Garmin Health API.
-
-export interface GarminUserProfile {
-  userId: string;
-  displayName?: string;
-  weight?: number;
-  height?: number;
-  birthDate?: string;
-  gender?: string;
-}
+  // Alternate SpO2 field name (some responses use this instead of timeOffsetSleepSpo2)
+  timeOffsetSpo2Values?: Record<string, number>;
+};
+
+// Extended activity type for webhook payloads which include detail-level fields
+// (laps, samples, power) that the summary endpoint does not return.
+export type GarminActivityExtended = GarminActivity & {
+  // Fields from /rest/activityDetails and webhook payloads
+  laps?: GarminLap[];
+  samples?: GarminSample[];
+  bmrKilocalories?: number;
+  averagePowerInWatts?: number;
+  maxPowerInWatts?: number;
+  normalizedPowerInWatts?: number;
+  poolLengthInMeters?: number;
+  // Webhook payloads may use these alternate field names
+  elevationGainInMeters?: number;
+  elevationLossInMeters?: number;
+};
 
-// ─── Garmin Activity Type ───────────────────────────────────────────────────
-// Known Garmin activity type strings from the API.
+// ─── Backward Compatibility Aliases ─────────────────────────────────────────
 
-export type GarminActivityType =
-  | "RUNNING"
-  | "INDOOR_RUNNING"
-  | "TRAIL_RUNNING"
-  | "TREADMILL_RUNNING"
-  | "CYCLING"
-  | "INDOOR_CYCLING"
-  | "MOUNTAIN_BIKING"
-  | "GRAVEL_CYCLING"
-  | "VIRTUAL_RIDE"
-  | "WALKING"
-  | "HIKING"
-  | "SWIMMING"
-  | "OPEN_WATER_SWIMMING"
-  | "LAP_SWIMMING"
-  | "POOL_SWIMMING"
-  | "STRENGTH_TRAINING"
-  | "YOGA"
-  | "PILATES"
-  | "CARDIO"
-  | "ELLIPTICAL"
-  | "STAIR_CLIMBING"
-  | "ROWING"
-  | "INDOOR_ROWING"
-  | "CROSS_COUNTRY_SKIING"
-  | "ALPINE_SKIING"
-  | "SNOWBOARDING"
-  | "SNOWSHOEING"
-  | "SKATING"
-  | "INLINE_SKATING"
-  | "GOLF"
-  | "TENNIS"
-  | "TABLE_TENNIS"
-  | "BADMINTON"
-  | "RACQUETBALL"
-  | "SQUASH"
-  | "PADDLEBOARDING"
-  | "KAYAKING"
-  | "CANOEING"
-  | "SAILING"
-  | "SURFING"
-  | "KITESURFING"
-  | "WINDSURFING"
-  | "ROCK_CLIMBING"
-  | "BOULDERING"
-  | "SOCCER"
-  | "BASKETBALL"
-  | "VOLLEYBALL"
-  | "CRICKET"
-  | "RUGBY"
-  | "BOXING"
-  | "MARTIAL_ARTS"
-  | "CROSSFIT"
-  | "HIIT"
-  | "BREATHWORK"
-  | "FLOOR_CLIMBING"
-  | "HANDCYCLING"
-  | "WHEELCHAIR_PUSH_WALKING"
-  | "WHEELCHAIR_PUSH_RUNNING"
-  | "OTHER"
-  | "MULTI_SPORT"
-  | "FITNESS_EQUIPMENT"
-  | (string & {});
+export type GarminDailySummary = GarminDailyExtended;
+export type GarminMenstrualCycleData = GarminMenstrualCycle;
+export type GarminSleepLevel = GarminTimeRange;
+export type GarminActivityLap = GarminLap;
+export type GarminActivitySample = GarminSample;
 
 // ─── OAuth 2.0 ──────────────────────────────────────────────────────────────
 
@@ -468,13 +250,19 @@ export interface GarminWorkoutSchedule {
   date: string;
 }
 
-// ─── API Response Wrappers ──────────────────────────────────────────────────
-
-export interface GarminWebhookPayload {
-  activities?: Array<{ userId: string; summaryId: string; callbackURL: string }>;
-  activityDetails?: Array<{ userId: string; summaryId: string; callbackURL: string }>;
-  dailies?: Array<{ userId: string; summaryId: string; callbackURL: string }>;
-  sleeps?: Array<{ userId: string; summaryId: string; callbackURL: string }>;
-  bodyComps?: Array<{ userId: string; summaryId: string; callbackURL: string }>;
-  stressDetails?: Array<{ userId: string; summaryId: string; callbackURL: string }>;
-}
+// ─── Push-Mode Webhook Payloads ─────────────────────────────────────────────
+// In push mode, Garmin sends full data objects directly in the POST body.
+// Each data type has its own webhook URL configured in the Garmin developer
+// portal, so each payload is a typed array of the corresponding summary type.
+
+export type GarminWebhookActivityPayload = (GarminActivity & { userAccessToken?: string })[];
+export type GarminWebhookDailyPayload = (GarminDailyExtended & { userAccessToken?: string })[];
+export type GarminWebhookSleepPayload = (GarminSleepExtended & { userAccessToken?: string })[];
+export type GarminWebhookBodyPayload = (GarminBodyComposition & { userAccessToken?: string })[];
+export type GarminWebhookBloodPressurePayload = (GarminBloodPressure & { userAccessToken?: string })[];
+export type GarminWebhookSkinTempPayload = (GarminSkinTemperature & { userAccessToken?: string })[];
+export type GarminWebhookUserMetricsPayload = (GarminUserMetrics & { userAccessToken?: string })[];
+export type GarminWebhookHRVPayload = (GarminHRVSummary & { userAccessToken?: string })[];
+export type GarminWebhookStressDetailPayload = (GarminStressDetail & { userAccessToken?: string })[];
+export type GarminWebhookPulseOxPayload = (GarminPulseOx & { userAccessToken?: string })[];
+export type GarminWebhookRespirationPayload = (GarminRespiration & { userAccessToken?: string })[];

package/src/garmin/userMetrics.ts

@@ -0,0 +1,50 @@
+// ─── User Metrics Transformer ────────────────────────────────────────────────
+// Transforms Garmin user metrics into the Soma Body schema shape.
+
+import type { GarminUserMetrics } from "./types.js";
+
+export type UserMetricsData = ReturnType<typeof transformUserMetrics>;
+
+/**
+ * Transform Garmin user metrics into a Soma Body document shape.
+ *
+ * Maps VO2 Max and fitness age into oxygen_data and scores fields.
+ *
+ * @param metrics - The Garmin user metrics from the Health API
+ * @returns Soma Body fields (without connectionId/userId)
+ */
+export function transformUserMetrics(metrics: GarminUserMetrics) {
+  const dateStr = metrics.calendarDate;
+  const startTime = dateStr
+    ? `${dateStr}T00:00:00.000Z`
+    : new Date(0).toISOString();
+  const endTime = dateStr
+    ? `${dateStr}T23:59:59.999Z`
+    : new Date(0).toISOString();
+
+  const hasVo2 = metrics.vo2Max != null || metrics.vo2MaxCycling != null;
+  const hasFitnessAge = metrics.fitnessAge != null;
+
+  if (!hasVo2 && !hasFitnessAge) {
+    return {
+      metadata: { start_time: startTime, end_time: endTime },
+      oxygen_data: undefined,
+      scores: undefined,
+    };
+  }
+
+  return {
+    metadata: {
+      start_time: startTime,
+      end_time: endTime,
+    },
+
+    oxygen_data: hasVo2
+      ? { vo2max_ml_per_min_per_kg: metrics.vo2Max ?? metrics.vo2MaxCycling }
+      : undefined,
+
+    scores: hasFitnessAge
+      ? { biological_age: metrics.fitnessAge }
+      : undefined,
+  };
+}