@nativesquare/soma 0.7.3 → 0.8.0

package/src/garmin/daily.ts

@@ -3,6 +3,10 @@
 
 import type { GarminDailySummary } from "./types.js";
 
+// GarminDailySummary is an alias for GarminDailyExtended which includes
+// both spec fields and additional fields the API returns (stress time-series,
+// SpO2, body battery, respiration).
+
 export type DailyData = ReturnType<typeof transformDaily>;
 
 /**
@@ -12,8 +16,8 @@ export type DailyData = ReturnType<typeof transformDaily>;
  * @returns Soma Daily fields (without connectionId/userId)
  */
 export function transformDaily(daily: GarminDailySummary) {
-  const startMs = daily.startTimeInSeconds * 1000;
-  const endMs = startMs + daily.durationInSeconds * 1000;
+  const startMs = (daily.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (daily.durationInSeconds ?? 0) * 1000;
 
   return {
     metadata: {
@@ -198,13 +202,13 @@ function buildStressData(daily: GarminDailySummary) {
  * This converts to `{ timestamp: ISO-8601, ...fields }[]`.
  */
 function buildTimeOffsetSamples<T extends Record<string, unknown>>(
-  startTimeInSeconds: number,
+  startTimeInSeconds: number | undefined,
   offsets: Record<string, number>,
   mapValue: (value: number) => T,
 ): Array<{ timestamp: string } & T> {
   return Object.entries(offsets).map(([offset, value]) => ({
     timestamp: new Date(
-      (startTimeInSeconds + parseInt(offset, 10)) * 1000,
+      ((startTimeInSeconds ?? 0) + parseInt(offset, 10)) * 1000,
     ).toISOString(),
     ...mapValue(value),
   }));

package/src/garmin/hrv.ts

@@ -0,0 +1,57 @@
+// ─── HRV Transformer ─────────────────────────────────────────────────────────
+// Transforms Garmin HRV summary data into fields that enrich a Soma Daily record.
+
+import type { GarminHRVSummary } from "./types.js";
+
+export type HRVData = ReturnType<typeof transformHRV>;
+
+/**
+ * Transform a Garmin HRV summary into heart rate data fields for a Soma Daily.
+ *
+ * This produces a partial daily shape that can be merged into a matching
+ * daily record by date.
+ *
+ * @param hrv - The Garmin HRV summary from the Health API
+ * @returns Partial Soma Daily heart_rate_data fields
+ */
+export function transformHRV(hrv: GarminHRVSummary) {
+  const startMs = (hrv.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (hrv.durationInSeconds ?? 0) * 1000;
+
+  const hasSummary = hrv.lastNightAvg != null || hrv.lastNight5MinHigh != null;
+  const hasSamples =
+    hrv.hrvValues != null && Object.keys(hrv.hrvValues).length > 0;
+
+  if (!hasSummary && !hasSamples) {
+    return {
+      calendar_date: hrv.calendarDate,
+      heart_rate_data: undefined,
+    };
+  }
+
+  const startTime = hrv.startTimeInSeconds ?? 0;
+  const hrvSamples = hasSamples
+    ? Object.entries(hrv.hrvValues!).map(([offset, rmssd]) => ({
+        timestamp: new Date(
+          (startTime + parseInt(offset, 10)) * 1000,
+        ).toISOString(),
+        hrv_rmssd: rmssd,
+      }))
+    : undefined;
+
+  return {
+    calendar_date: hrv.calendarDate,
+    heart_rate_data: {
+      summary: hasSummary
+        ? {
+            avg_hrv_rmssd: hrv.lastNightAvg,
+            max_hrv_rmssd: hrv.lastNight5MinHigh,
+          }
+        : undefined,
+      detailed:
+        hrvSamples && hrvSamples.length > 0
+          ? { hrv_samples_rmssd: hrvSamples }
+          : undefined,
+    },
+  };
+}

package/src/garmin/index.ts

@@ -20,6 +20,27 @@ export type { BodyData } from "./body.js";
 export { transformMenstruation } from "./menstruation.js";
 export type { MenstruationData } from "./menstruation.js";
 
+export { transformBloodPressure } from "./bloodPressure.js";
+export type { BloodPressureData } from "./bloodPressure.js";
+
+export { transformSkinTemp } from "./skinTemp.js";
+export type { SkinTempData } from "./skinTemp.js";
+
+export { transformUserMetrics } from "./userMetrics.js";
+export type { UserMetricsData } from "./userMetrics.js";
+
+export { transformHRV } from "./hrv.js";
+export type { HRVData } from "./hrv.js";
+
+export { transformStressDetails } from "./stressDetails.js";
+export type { StressDetailsData } from "./stressDetails.js";
+
+export { transformPulseOx } from "./pulseOx.js";
+export type { PulseOxData } from "./pulseOx.js";
+
+export { transformRespiration } from "./respiration.js";
+export type { RespirationData } from "./respiration.js";
+
 // ── Enum Maps ────────────────────────────────────────────────────────────────
 export { mapActivityType } from "./maps/activity-type.js";
 export { mapSleepLevel } from "./maps/sleep-level.js";
@@ -51,6 +72,13 @@ export {
   syncSleep,
   syncBody,
   syncMenstruation,
+  syncBloodPressures,
+  syncSkinTemp,
+  syncUserMetrics,
+  syncHRV,
+  syncStressDetails,
+  syncPulseOx,
+  syncRespiration,
 } from "./sync.js";
 export type {
   SyncOptions,
@@ -60,16 +88,58 @@ export type {
 
 // ── Types ────────────────────────────────────────────────────────────────────
 export type {
+  // Wellness API types (aliases for generated spec types)
   GarminActivity,
-  GarminActivityLap,
-  GarminActivitySample,
-  GarminDailySummary,
+  GarminActivityDetail,
+  GarminDaily,
   GarminSleep,
-  GarminSleepLevel,
   GarminBodyComposition,
+  GarminMenstrualCycle,
+  GarminUserMetrics,
+  GarminStressDetail,
+  GarminSkinTemperature,
+  GarminRespiration,
+  GarminPulseOx,
+  GarminHRVSummary,
+  GarminHealthSnapshot,
+  GarminEpoch,
+  GarminBloodPressure,
+  GarminMoveIQEvent,
+  GarminSolar,
+  GarminSample,
+  GarminLap,
+  GarminTimeRange,
+  GarminSleepScoreItem,
+  GarminNap,
+  // Extended types (spec + undocumented fields)
+  GarminDailyExtended,
+  GarminSleepExtended,
+  GarminActivityExtended,
+  // Backward compatibility aliases
+  GarminDailySummary,
   GarminMenstrualCycleData,
-  GarminUserProfile,
-  GarminActivityType,
+  GarminSleepLevel,
+  GarminActivityLap,
+  GarminActivitySample,
+  // Training API types
+  GarminWorkout,
+  GarminWorkoutStep,
+  GarminWorkoutRepeatStep,
+  GarminWorkoutSegment,
+  GarminWorkoutSchedule,
+  GarminWorkoutSport,
+  // OAuth
   GarminOAuth2TokenResponse,
-  GarminWebhookPayload,
+  // Webhook payloads
+  GarminWebhookActivityPayload,
+  GarminWebhookDailyPayload,
+  GarminWebhookSleepPayload,
+  GarminWebhookBodyPayload,
+  GarminWebhookBloodPressurePayload,
+  GarminWebhookSkinTempPayload,
+  GarminWebhookUserMetricsPayload,
+  GarminWebhookHRVPayload,
+  GarminWebhookStressDetailPayload,
+  GarminWebhookPulseOxPayload,
+  GarminWebhookRespirationPayload,
 } from "./types.js";

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

@@ -5,7 +5,7 @@
 // Garmin values: Garmin Health API activity type strings
 // Terra values:  https://docs.tryterra.co/reference/health-and-fitness-api/data-models#activitytype
 
-import type { GarminActivityType } from "../types.js";
+// Garmin activityType is a free-form string in the spec
 
 const activityTypeMap: Record<string, number> = {
   // ── Running ─────────────────────────────────────────────────────────────
@@ -111,6 +111,6 @@ const activityTypeMap: Record<string, number> = {
  * Map a Garmin activity type string to the Terra ActivityType enum.
  * Returns Terra "Other" (108) for unknown types.
  */
-export function mapActivityType(activityType: GarminActivityType): number {
+export function mapActivityType(activityType: string): number {
   return activityTypeMap[activityType] ?? 108;
 }

package/src/garmin/menstruation.ts

@@ -1,7 +1,7 @@
 // ─── Menstruation Transformer ────────────────────────────────────────────────
 // Transforms Garmin menstrual cycle data into the Soma Menstruation schema shape.
 
-import type { GarminMenstrualCycleData } from "./types.js";
+import type { GarminMenstrualCycle } from "./types.js";
 
 export type MenstruationData = ReturnType<typeof transformMenstruation>;
 
@@ -11,16 +11,15 @@ export type MenstruationData = ReturnType<typeof transformMenstruation>;
  * @param data - The Garmin menstrual cycle data from the Health API
  * @returns Soma Menstruation fields (without connectionId/userId)
  */
-export function transformMenstruation(data: GarminMenstrualCycleData) {
-  const dateStr = data.calendarDate;
-  const startTime = data.startTimeInSeconds
-    ? new Date(data.startTimeInSeconds * 1000).toISOString()
-    : `${dateStr}T00:00:00.000Z`;
-  const endTime = data.startTimeInSeconds
-    ? new Date(
-        (data.startTimeInSeconds + 86400) * 1000,
-      ).toISOString()
-    : `${dateStr}T23:59:59.999Z`;
+export function transformMenstruation(data: GarminMenstrualCycle) {
+  // Spec uses periodStartDate (date string like "2021-01-04")
+  const dateStr = data.periodStartDate;
+  const startTime = dateStr
+    ? `${dateStr}T00:00:00.000Z`
+    : undefined;
+  const endTime = dateStr
+    ? `${dateStr}T23:59:59.999Z`
+    : undefined;
 
   return {
     metadata: {
@@ -30,10 +29,13 @@ export function transformMenstruation(data: GarminMenstrualCycleData) {
 
     menstruation_data: {
       day_in_cycle: data.dayInCycle,
-      current_phase: data.currentPhase?.toLowerCase(),
+      // Spec has currentPhaseType (string) replacing deprecated currentPhase (int)
+      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,
       is_predicted_cycle: data.isPredictedCycle != null
         ? String(data.isPredictedCycle)
         : undefined,

package/src/garmin/pulseOx.ts

@@ -0,0 +1,45 @@
+// ─── Pulse Ox Transformer ────────────────────────────────────────────────────
+// Transforms Garmin pulse ox data into fields that enrich a Soma Daily record.
+
+import type { GarminPulseOx } from "./types.js";
+
+export type PulseOxData = ReturnType<typeof transformPulseOx>;
+
+/**
+ * Transform a Garmin pulse ox record into oxygen data fields for a Soma Daily.
+ *
+ * This produces a partial daily shape that can be merged into a matching
+ * daily record by date.
+ *
+ * @param pulseOx - The Garmin pulse ox data from the Health API
+ * @returns Partial Soma Daily oxygen_data fields
+ */
+export function transformPulseOx(pulseOx: GarminPulseOx) {
+  const hasSamples =
+    pulseOx.timeOffsetSpo2Values != null &&
+    Object.keys(pulseOx.timeOffsetSpo2Values).length > 0;
+
+  if (!hasSamples) {
+    return {
+      calendar_date: pulseOx.calendarDate,
+      oxygen_data: undefined,
+    };
+  }
+
+  const startTime = pulseOx.startTimeInSeconds ?? 0;
+  const samples = Object.entries(pulseOx.timeOffsetSpo2Values!).map(
+    ([offset, percentage]) => ({
+      timestamp: new Date(
+        (startTime + parseInt(offset, 10)) * 1000,
+      ).toISOString(),
+      percentage,
+    }),
+  );
+
+  return {
+    calendar_date: pulseOx.calendarDate,
+    oxygen_data: {
+      saturation_samples: samples.length > 0 ? samples : undefined,
+    },
+  };
+}

package/src/garmin/respiration.ts

@@ -0,0 +1,55 @@
+// ─── Respiration Transformer ─────────────────────────────────────────────────
+// Transforms Garmin respiration data into fields that enrich a Soma Daily record.
+
+import type { GarminRespiration } from "./types.js";
+
+export type RespirationData = ReturnType<typeof transformRespiration>;
+
+/**
+ * Transform a Garmin respiration record into respiration data fields for a Soma Daily.
+ *
+ * This produces a partial daily shape that can be merged into a matching
+ * daily record by date.
+ *
+ * @param resp - The Garmin respiration data from the Health API
+ * @returns Partial Soma Daily respiration_data fields
+ */
+export function transformRespiration(resp: GarminRespiration) {
+  const hasSamples =
+    resp.timeOffsetEpochToBreaths != null &&
+    Object.keys(resp.timeOffsetEpochToBreaths).length > 0;
+
+  if (!hasSamples) {
+    return {
+      calendar_date: undefined,
+      respiration_data: undefined,
+    };
+  }
+
+  const startTime = resp.startTimeInSeconds ?? 0;
+  const samples = Object.entries(resp.timeOffsetEpochToBreaths!).map(
+    ([offset, breaths_per_min]) => ({
+      timestamp: new Date(
+        (startTime + parseInt(offset, 10)) * 1000,
+      ).toISOString(),
+      breaths_per_min,
+    }),
+  );
+
+  // Compute summary stats from samples
+  const values = samples.map((s) => s.breaths_per_min);
+  const avg = values.reduce((sum, v) => sum + v, 0) / values.length;
+
+  return {
+    // Respiration endpoint doesn't have calendarDate, derive from startTime
+    calendar_date: new Date(startTime * 1000).toISOString().split("T")[0],
+    respiration_data: {
+      breaths_data: {
+        avg_breaths_per_min: Math.round(avg * 10) / 10,
+        min_breaths_per_min: Math.min(...values),
+        max_breaths_per_min: Math.max(...values),
+        samples: samples.length > 0 ? samples : undefined,
+      },
+    },
+  };
+}

package/src/garmin/skinTemp.ts

@@ -0,0 +1,42 @@
+// ─── Skin Temperature Transformer ────────────────────────────────────────────
+// Transforms Garmin skin temperature data into the Soma Body schema shape.
+
+import type { GarminSkinTemperature } from "./types.js";
+
+export type SkinTempData = ReturnType<typeof transformSkinTemp>;
+
+/**
+ * Transform a Garmin skin temperature record into a Soma Body document shape.
+ *
+ * @param skinTemp - The Garmin skin temperature data from the Health API
+ * @returns Soma Body fields (without connectionId/userId)
+ */
+export function transformSkinTemp(skinTemp: GarminSkinTemperature) {
+  const startMs = (skinTemp.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (skinTemp.durationInSeconds ?? 0) * 1000;
+  const startTime = new Date(startMs).toISOString();
+  const endTime = new Date(endMs).toISOString();
+
+  if (skinTemp.avgDeviationCelsius == null) {
+    return {
+      metadata: { start_time: startTime, end_time: endTime },
+      temperature_data: undefined,
+    };
+  }
+
+  return {
+    metadata: {
+      start_time: startTime,
+      end_time: endTime,
+    },
+
+    temperature_data: {
+      skin_temperature_samples: [
+        {
+          timestamp: startTime,
+          temperature_celsius: skinTemp.avgDeviationCelsius,
+        },
+      ],
+    },
+  };
+}

package/src/garmin/sleep.test.ts

@@ -1,10 +1,9 @@
 import { describe, expect, it } from "vitest";
 import { transformSleep } from "./sleep.js";
-import type { GarminSleep } from "./types.js";
+import type { GarminSleepExtended } from "./types.js";
 
-const baseSleep: GarminSleep = {
+const baseSleep: GarminSleepExtended = {
   userId: "garmin_user_1",
-  userAccessToken: "token",
   summaryId: "sleep_001",
   calendarDate: "2023-11-14",
   startTimeInSeconds: 1700000000,
@@ -36,7 +35,7 @@ describe("transformSleep", () => {
   });
 
   it("maps sleep stage durations", () => {
-    const withStages: GarminSleep = {
+    const withStages: GarminSleepExtended = {
       ...baseSleep,
       deepSleepDurationInSeconds: 7200,
       lightSleepDurationInSeconds: 14400,
@@ -55,7 +54,7 @@ describe("transformSleep", () => {
   });
 
   it("maps sleep levels hypnogram", () => {
-    const withLevels: GarminSleep = {
+    const withLevels: GarminSleepExtended = {
       ...baseSleep,
       sleepLevelsMap: {
         deep: [
@@ -85,7 +84,7 @@ describe("transformSleep", () => {
   });
 
   it("maps respiration data", () => {
-    const withResp: GarminSleep = {
+    const withResp: GarminSleepExtended = {
       ...baseSleep,
       averageRespirationInBreathsPerMinute: 16,
       lowestRespirationInBreathsPerMinute: 12,

package/src/garmin/sleep.ts

@@ -1,7 +1,7 @@
 // ─── Sleep Transformer ───────────────────────────────────────────────────────
 // Transforms a Garmin sleep session into the Soma Sleep schema shape.
 
-import type { GarminSleep, GarminSleepLevel } from "./types.js";
+import type { GarminSleepExtended, GarminTimeRange } from "./types.js";
 import { mapSleepLevel } from "./maps/sleep-level.js";
 
 export type SleepData = ReturnType<typeof transformSleep>;
@@ -12,9 +12,9 @@ export type SleepData = ReturnType<typeof transformSleep>;
  * @param sleep - The Garmin sleep data from the Health API
  * @returns Soma Sleep fields (without connectionId/userId)
  */
-export function transformSleep(sleep: GarminSleep) {
-  const startMs = sleep.startTimeInSeconds * 1000;
-  const endMs = startMs + sleep.durationInSeconds * 1000;
+export function transformSleep(sleep: GarminSleepExtended) {
+  const startMs = (sleep.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (sleep.durationInSeconds ?? 0) * 1000;
 
   const uploadTypeMap: Record<string, number> = {
     ENHANCED_FINAL: 2,      // Automatic
@@ -22,6 +22,7 @@ export function transformSleep(sleep: GarminSleep) {
     AUTO_FINAL: 2,          // Automatic
     AUTO_TENTATIVE: 4,      // Indeterminate
     MANUAL: 1,              // Manual
+    DEVICE: 2,              // From device
   };
 
   return {
@@ -29,7 +30,7 @@ export function transformSleep(sleep: GarminSleep) {
       summary_id: sleep.summaryId,
       start_time: new Date(startMs).toISOString(),
       end_time: new Date(endMs).toISOString(),
-      upload_type: uploadTypeMap[sleep.validation] ?? 0,
+      upload_type: uploadTypeMap[sleep.validation ?? ""] ?? 0,
     },
 
     sleep_durations_data: buildSleepDurationsData(sleep),
@@ -42,7 +43,7 @@ export function transformSleep(sleep: GarminSleep) {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-function buildSleepDurationsData(sleep: GarminSleep) {
+function buildSleepDurationsData(sleep: GarminSleepExtended) {
   const totalAsleep =
     (sleep.deepSleepDurationInSeconds ?? 0) +
     (sleep.lightSleepDurationInSeconds ?? 0) +
@@ -66,7 +67,7 @@ function buildSleepDurationsData(sleep: GarminSleep) {
   };
 }
 
-function buildHypnogramSamples(sleep: GarminSleep) {
+function buildHypnogramSamples(sleep: GarminSleepExtended) {
   if (!sleep.sleepLevelsMap) return undefined;
 
   const samples: Array<{ timestamp: string; level: number }> = [];
@@ -75,7 +76,8 @@ function buildHypnogramSamples(sleep: GarminSleep) {
     if (!levels) continue;
     const terraLevel = mapSleepLevel(stage);
 
-    for (const level of levels as GarminSleepLevel[]) {
+    for (const level of levels as GarminTimeRange[]) {
+      if (level.startTimeInSeconds == null) continue;
       samples.push({
         timestamp: new Date(level.startTimeInSeconds * 1000).toISOString(),
         level: terraLevel,
@@ -90,7 +92,7 @@ function buildHypnogramSamples(sleep: GarminSleep) {
   return samples.length > 0 ? samples : undefined;
 }
 
-function buildHeartRateData(sleep: GarminSleep) {
+function buildHeartRateData(sleep: GarminSleepExtended) {
   if (
     !sleep.timeOffsetHeartRateSamples ||
     Object.keys(sleep.timeOffsetHeartRateSamples).length === 0
@@ -98,10 +100,11 @@ function buildHeartRateData(sleep: GarminSleep) {
     return undefined;
   }
 
+  const startTime = sleep.startTimeInSeconds ?? 0;
   const hrSamples = Object.entries(sleep.timeOffsetHeartRateSamples).map(
     ([offset, bpm]) => ({
       timestamp: new Date(
-        (sleep.startTimeInSeconds + parseInt(offset, 10)) * 1000,
+        (startTime + parseInt(offset, 10)) * 1000,
       ).toISOString(),
       bpm,
     }),
@@ -112,25 +115,28 @@ function buildHeartRateData(sleep: GarminSleep) {
   };
 }
 
-function buildRespirationData(sleep: GarminSleep) {
+function buildRespirationData(sleep: GarminSleepExtended) {
   const hasBreathSummary =
     sleep.averageRespirationInBreathsPerMinute != null;
   const hasBreathSamples =
     sleep.timeOffsetSleepRespiration != null &&
     Object.keys(sleep.timeOffsetSleepRespiration).length > 0;
+  // Check both spec field (timeOffsetSleepSpo2) and extended field
+  const spo2Map = sleep.timeOffsetSleepSpo2 ?? sleep.timeOffsetSpo2Values;
   const hasSpO2Samples =
-    sleep.timeOffsetSpo2Values != null &&
-    Object.keys(sleep.timeOffsetSpo2Values).length > 0;
+    spo2Map != null && Object.keys(spo2Map).length > 0;
 
   if (!hasBreathSummary && !hasBreathSamples && !hasSpO2Samples) {
     return undefined;
   }
 
+  const startTime = sleep.startTimeInSeconds ?? 0;
+
   const breathSamples = hasBreathSamples
     ? Object.entries(sleep.timeOffsetSleepRespiration!).map(
         ([offset, rate]) => ({
           timestamp: new Date(
-            (sleep.startTimeInSeconds + parseInt(offset, 10)) * 1000,
+            (startTime + parseInt(offset, 10)) * 1000,
           ).toISOString(),
           breaths_per_min: rate,
         }),
@@ -138,9 +144,9 @@ function buildRespirationData(sleep: GarminSleep) {
     : undefined;
 
   const spo2Samples = hasSpO2Samples
-    ? Object.entries(sleep.timeOffsetSpo2Values!).map(([offset, pct]) => ({
+    ? Object.entries(spo2Map!).map(([offset, pct]) => ({
         timestamp: new Date(
-          (sleep.startTimeInSeconds + parseInt(offset, 10)) * 1000,
+          (startTime + parseInt(offset, 10)) * 1000,
         ).toISOString(),
         percentage: pct,
       }))