@nativesquare/soma 0.2.0 → 0.4.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 }>;
+}

package/src/validators.ts

@@ -0,0 +1,89 @@
+// ─── Soma Validators ─────────────────────────────────────────────────────────
+// Re-exports the Convex validators for each Soma table so host apps can use
+// them for type-safe argument validation in their own mutations.
+//
+// Two flavors are exported for each table:
+//
+//   *Validator  — Full validator including connectionId (v.string()) and userId.
+//                 Use when the mutation args map 1:1 to a soma.ingestX() call.
+//
+//   *Data       — Data-only validator (no connectionId/userId).
+//                 Use when connection is resolved server-side and the client
+//                 only sends the health data payload.
+//
+// ─── Examples ────────────────────────────────────────────────────────────────
+//
+// Direct ingest (client provides connectionId):
+//
+//   import { activityValidator } from "@nativesquare/soma/validators";
+//
+//   export const storeActivity = mutation({
+//     args: activityValidator,
+//     handler: async (ctx, args) => {
+//       await soma.ingestActivity(ctx, args);
+//     },
+//   });
+//
+// Batch sync (connection resolved server-side):
+//
+//   import { activityData } from "@nativesquare/soma/validators";
+//
+//   export const syncHealthKit = mutation({
+//     args: { activities: v.array(v.object(activityData)) },
+//     handler: async (ctx, args) => {
+//       const connectionId = await soma.connect(ctx, { userId, provider: "HEALTHKIT" });
+//       for (const activity of args.activities) {
+//         await soma.ingestActivity(ctx, { connectionId, userId, ...activity });
+//       }
+//     },
+//   });
+
+import { v } from "convex/values";
+import { connectionValidator as _connectionValidator } from "./component/validators/connection.js";
+import { athleteValidator as _athleteValidator } from "./component/validators/athlete.js";
+import { activityValidator as _activityValidator } from "./component/validators/activity.js";
+import { bodyValidator as _bodyValidator } from "./component/validators/body.js";
+import { dailyValidator as _dailyValidator } from "./component/validators/daily.js";
+import { sleepValidator as _sleepValidator } from "./component/validators/sleep.js";
+import { menstruationValidator as _menstruationValidator } from "./component/validators/menstruation.js";
+import { nutritionValidator as _nutritionValidator } from "./component/validators/nutrition.js";
+import { plannedWorkoutValidator as _plannedWorkoutValidator } from "./component/validators/plannedWorkout.js";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const asString = { connectionId: v.string() };
+
+type WithConnection = { connectionId: unknown; userId: unknown };
+
+function stripConnection<T extends WithConnection>(
+  validator: T,
+): Omit<T, "connectionId" | "userId"> {
+  const { connectionId, userId, ...rest } = validator;
+  return rest as Omit<T, "connectionId" | "userId">;
+}
+
+// ─── Full validators (connectionId as v.string() + userId) ───────────────────
+
+export const connectionValidator = _connectionValidator;
+export const athleteValidator = { ..._athleteValidator, ...asString };
+export const activityValidator = { ..._activityValidator, ...asString };
+export const bodyValidator = { ..._bodyValidator, ...asString };
+export const dailyValidator = { ..._dailyValidator, ...asString };
+export const sleepValidator = { ..._sleepValidator, ...asString };
+export const menstruationValidator = { ..._menstruationValidator, ...asString };
+export const nutritionValidator = { ..._nutritionValidator, ...asString };
+export const plannedWorkoutValidator = {
+  ..._plannedWorkoutValidator,
+  ...asString,
+};
+
+// ─── Data-only validators (no connectionId / userId) ─────────────────────────
+
+export const athleteData = stripConnection(_athleteValidator);
+export const activityData = stripConnection(_activityValidator);
+export const bodyData = stripConnection(_bodyValidator);
+export const dailyData = stripConnection(_dailyValidator);
+export const sleepData = stripConnection(_sleepValidator);
+export const menstruationData = stripConnection(_menstruationValidator);
+export const nutritionData = stripConnection(_nutritionValidator);
+export const plannedWorkoutData = stripConnection(_plannedWorkoutValidator);