@nativesquare/soma 0.3.0 → 0.5.0

package/src/garmin/types.ts

@@ -0,0 +1,338 @@
+// ─── Garmin Health API Response Types ────────────────────────────────────────
+// TypeScript interfaces representing Garmin Health API data shapes.
+// Derived from the Garmin Connect Developer Program documentation.
+//
+// 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;
+  timeOffsetStressLevelValues?: Record<string, number>;
+
+  // Body battery
+  timeOffsetBodyBatteryValues?: Record<string, number>;
+
+  // Pulse Ox
+  averageSpo2Value?: number;
+  lowestSpo2Value?: number;
+  latestSpo2Value?: number;
+  timeOffsetSpo2Values?: Record<string, number>;
+
+  // Respiration
+  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
+  averageRespirationInBreathsPerMinute?: number;
+  lowestRespirationInBreathsPerMinute?: number;
+  highestRespirationInBreathsPerMinute?: number;
+  timeOffsetSleepRespiration?: Record<string, number>;
+
+  // SpO2
+  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
+  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;
+}
+
+// ─── Garmin Activity Type ───────────────────────────────────────────────────
+// Known Garmin activity type strings from the API.
+
+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 & {});
+
+// ─── OAuth ──────────────────────────────────────────────────────────────────
+
+export interface GarminOAuthRequestTokenResponse {
+  oauthToken: string;
+  oauthTokenSecret: string;
+}
+
+export interface GarminOAuthAccessTokenResponse {
+  oauthToken: string;
+  oauthTokenSecret: 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 }>;
+}