@nativesquare/soma 0.8.0 → 0.9.1

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

@@ -0,0 +1,179 @@
+// ─── Dailies Transformer ─────────────────────────────────────────────────────
+// Transforms a Garmin daily summary push item into the Soma Daily schema shape.
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientDaily } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin daily summary push item into a Soma Daily document shape.
+ *
+ * Daily summaries are ingested into the `daily` table via `ingestDaily`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when no meaningful data is present.
+ */
+export function transformDailies(daily: ClientDaily): SomaDaily | null {
+  const startMs = (daily.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (daily.durationInSeconds ?? 0) * 1000;
+
+  const activeDurations = buildActiveDurationsData(daily);
+  const calories = buildCaloriesData(daily);
+  const distance = buildDistanceData(daily);
+  const heartRate = buildHeartRateData(daily);
+  const stress = buildStressData(daily);
+
+  // Skip if there's no meaningful data at all
+  if (
+    activeDurations == null &&
+    calories == null &&
+    distance == null &&
+    heartRate == null &&
+    stress == null
+  ) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: 1, // Automatic
+    },
+
+    active_durations_data: activeDurations,
+    calories_data: calories,
+    distance_data: distance,
+    heart_rate_data: heartRate,
+    stress_data: stress,
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildActiveDurationsData(daily: ClientDaily) {
+  if (
+    daily.activeTimeInSeconds == null &&
+    daily.moderateIntensityDurationInSeconds == null &&
+    daily.vigorousIntensityDurationInSeconds == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    activity_seconds: daily.activeTimeInSeconds,
+    moderate_intensity_seconds: daily.moderateIntensityDurationInSeconds,
+    vigorous_intensity_seconds: daily.vigorousIntensityDurationInSeconds,
+  };
+}
+
+function buildCaloriesData(daily: ClientDaily) {
+  if (daily.activeKilocalories == null && daily.bmrKilocalories == null) {
+    return undefined;
+  }
+
+  const total =
+    (daily.activeKilocalories ?? 0) + (daily.bmrKilocalories ?? 0);
+
+  return {
+    net_activity_calories: daily.activeKilocalories,
+    BMR_calories: daily.bmrKilocalories,
+    total_burned_calories: total || undefined,
+  };
+}
+
+function buildDistanceData(daily: ClientDaily) {
+  if (
+    daily.distanceInMeters == null &&
+    daily.steps == null &&
+    daily.floorsClimbed == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    distance_meters: daily.distanceInMeters,
+    steps: daily.steps,
+    floors_climbed: daily.floorsClimbed,
+  };
+}
+
+function buildHeartRateData(daily: ClientDaily) {
+  if (
+    daily.averageHeartRateInBeatsPerMinute == null &&
+    daily.maxHeartRateInBeatsPerMinute == null &&
+    daily.restingHeartRateInBeatsPerMinute == null &&
+    (daily.timeOffsetHeartRateSamples == null ||
+      Object.keys(daily.timeOffsetHeartRateSamples).length === 0)
+  ) {
+    return undefined;
+  }
+
+  const hasSummary =
+    daily.averageHeartRateInBeatsPerMinute != null ||
+    daily.maxHeartRateInBeatsPerMinute != null ||
+    daily.restingHeartRateInBeatsPerMinute != null;
+
+  const hasSamples =
+    daily.timeOffsetHeartRateSamples != null &&
+    Object.keys(daily.timeOffsetHeartRateSamples).length > 0;
+
+  const hrSamples = hasSamples
+    ? buildTimeOffsetSamples(
+      daily.startTimeInSeconds,
+      daily.timeOffsetHeartRateSamples ?? {},
+      (bpm) => ({ bpm }),
+    )
+    : undefined;
+
+  return {
+    summary: hasSummary
+      ? {
+        avg_hr_bpm: daily.averageHeartRateInBeatsPerMinute,
+        max_hr_bpm: daily.maxHeartRateInBeatsPerMinute,
+        min_hr_bpm: daily.minHeartRateInBeatsPerMinute,
+        resting_hr_bpm: daily.restingHeartRateInBeatsPerMinute,
+      }
+      : undefined,
+    detailed:
+      hrSamples && hrSamples.length > 0
+        ? { hr_samples: hrSamples }
+        : undefined,
+  };
+}
+
+function buildStressData(daily: ClientDaily) {
+  if (
+    daily.averageStressLevel == null &&
+    daily.maxStressLevel == null &&
+    daily.stressDurationInSeconds == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    avg_stress_level: daily.averageStressLevel,
+    max_stress_level: daily.maxStressLevel,
+    stress_duration_seconds: daily.stressDurationInSeconds,
+    rest_stress_duration_seconds: daily.restStressDurationInSeconds,
+    activity_stress_duration_seconds: daily.activityStressDurationInSeconds,
+    low_stress_duration_seconds: daily.lowStressDurationInSeconds,
+    medium_stress_duration_seconds: daily.mediumStressDurationInSeconds,
+    high_stress_duration_seconds: daily.highStressDurationInSeconds,
+  };
+}
+
+/**
+ * Convert Garmin offset-keyed time-series data into timestamped samples.
+ */
+function buildTimeOffsetSamples<T extends Record<string, unknown>>(
+  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 ?? 0) + parseInt(offset, 10)) * 1000,
+    ).toISOString(),
+    ...mapValue(value),
+  }));
+}

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

@@ -0,0 +1,94 @@
+// ─── Epochs Transformer ──────────────────────────────────────────────────────
+// Transforms a Garmin epoch summary push item into the Soma Daily schema shape.
+// Epoch summaries are 15-minute wellness monitoring records with per-activity-type
+// granularity (steps, distance, calories, MET). They are ingested into the daily
+// table just like daily summaries.
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientEpoch } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin epoch summary push item into a Soma Daily document shape.
+ *
+ * Epoch summaries represent 15-minute time slices of wellness monitoring data.
+ * They are ingested into the `daily` table via `ingestDaily`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when no meaningful data is present.
+ */
+export function transformEpoch(epoch: ClientEpoch): SomaDaily | null {
+  const startMs = (epoch.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (epoch.durationInSeconds ?? 0) * 1000;
+
+  const activeDurations = buildActiveDurationsData(epoch);
+  const calories = buildCaloriesData(epoch);
+  const distance = buildDistanceData(epoch);
+  const met = buildMETData(epoch);
+
+  // Skip if there's no meaningful data at all
+  if (
+    activeDurations == null &&
+    calories == null &&
+    distance == null &&
+    met == null
+  ) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: 1, // Automatic
+    },
+
+    active_durations_data: activeDurations,
+    calories_data: calories,
+    distance_data: distance,
+    MET_data: met,
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildActiveDurationsData(epoch: ClientEpoch) {
+  if (epoch.activeTimeInSeconds == null) {
+    return undefined;
+  }
+
+  return {
+    activity_seconds: epoch.activeTimeInSeconds,
+  };
+}
+
+function buildCaloriesData(epoch: ClientEpoch) {
+  if (epoch.activeKilocalories == null) {
+    return undefined;
+  }
+
+  return {
+    net_activity_calories: epoch.activeKilocalories,
+    total_burned_calories: epoch.activeKilocalories,
+  };
+}
+
+function buildDistanceData(epoch: ClientEpoch) {
+  if (epoch.distanceInMeters == null && epoch.steps == null) {
+    return undefined;
+  }
+
+  return {
+    distance_meters: epoch.distanceInMeters,
+    steps: epoch.steps,
+  };
+}
+
+function buildMETData(epoch: ClientEpoch) {
+  if (epoch.met == null) {
+    return undefined;
+  }
+
+  return {
+    avg_level: epoch.met,
+  };
+}

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

@@ -0,0 +1,152 @@
+// ─── Health Snapshot Transformer ─────────────────────────────────────────────
+// Transforms a Garmin Health Snapshot push item into the Soma Daily schema shape.
+//
+// Health Snapshots are 2-minute sessions containing heart rate, stress, SpO2,
+// respiration, and HRV data. We map these into the Daily model since the data
+// types (HR, stress, oxygen, respiration) align with Daily's sub-fields.
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientHealthSnapshot } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin Health Snapshot push item into a Soma Daily document shape.
+ *
+ * Health Snapshot summaries contain epoch-level readings for heart rate, stress,
+ * SpO2, respiration, and HRV over a ~2-minute window.
+ *
+ * Returns `null` when no meaningful data is present.
+ */
+export function transformHealthSnapshot(
+  snapshot: ClientHealthSnapshot,
+): SomaDaily | null {
+  const startMs = (snapshot.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (snapshot.durationInSeconds ?? 0) * 1000;
+
+  const summaries = snapshot.summaries;
+  if (!summaries || summaries.length === 0) return null;
+
+  const heartRate = buildHeartRateData(snapshot);
+  const stress = buildStressData(snapshot);
+  const oxygen = buildOxygenData(snapshot);
+  const respiration = buildRespirationData(snapshot);
+
+  // Skip if there's no meaningful data at all
+  if (
+    heartRate == null &&
+    stress == null &&
+    oxygen == null &&
+    respiration == null
+  ) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: 1, // Automatic
+    },
+
+    heart_rate_data: heartRate,
+    stress_data: stress,
+    oxygen_data: oxygen,
+    respiration_data: respiration,
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+type SnapshotSummary = NonNullable<ClientHealthSnapshot["summaries"]>[number];
+
+function findSummary(
+  snapshot: ClientHealthSnapshot,
+  type: string,
+): SnapshotSummary | undefined {
+  return snapshot.summaries?.find((s) => s.summaryType === type);
+}
+
+function buildHeartRateData(snapshot: ClientHealthSnapshot) {
+  const hr = findSummary(snapshot, "heart_rate");
+  const rmssd = findSummary(snapshot, "rmssd_hrv");
+  const sdrr = findSummary(snapshot, "sdrr_hrv");
+
+  if (!hr && !rmssd && !sdrr) return undefined;
+
+  const hasSummary =
+    hr?.avgValue != null || hr?.maxValue != null || hr?.minValue != null;
+  const hasHrvSummary = rmssd?.avgValue != null || sdrr?.avgValue != null;
+
+  const hrSamples =
+    hr?.epochSummaries && Object.keys(hr.epochSummaries).length > 0
+      ? buildEpochSamples(
+        snapshot.startTimeInSeconds,
+        hr.epochSummaries,
+        (bpm) => ({ bpm }),
+      )
+      : undefined;
+
+  return {
+    summary:
+      hasSummary || hasHrvSummary
+        ? {
+          avg_hr_bpm: hr?.avgValue,
+          max_hr_bpm: hr?.maxValue,
+          min_hr_bpm: hr?.minValue,
+          avg_hrv_rmssd: rmssd?.avgValue,
+          avg_hrv_sdnn: sdrr?.avgValue,
+        }
+        : undefined,
+    detailed:
+      hrSamples && hrSamples.length > 0
+        ? { hr_samples: hrSamples }
+        : undefined,
+  };
+}
+
+function buildStressData(snapshot: ClientHealthSnapshot) {
+  const stress = findSummary(snapshot, "stress");
+  if (!stress) return undefined;
+
+  return {
+    avg_stress_level: stress.avgValue,
+    max_stress_level: stress.maxValue,
+  };
+}
+
+function buildOxygenData(snapshot: ClientHealthSnapshot) {
+  const spo2 = findSummary(snapshot, "spo2");
+  if (!spo2) return undefined;
+
+  return {
+    avg_saturation_percentage: spo2.avgValue,
+  };
+}
+
+function buildRespirationData(snapshot: ClientHealthSnapshot) {
+  const resp = findSummary(snapshot, "respiration");
+  if (!resp) return undefined;
+
+  return {
+    breaths_data: {
+      avg_breaths_per_min: resp.avgValue,
+      max_breaths_per_min: resp.maxValue,
+      min_breaths_per_min: resp.minValue,
+    },
+  };
+}
+
+/**
+ * Convert Garmin epoch-keyed summaries into timestamped samples.
+ */
+function buildEpochSamples<T extends Record<string, unknown>>(
+  startTimeInSeconds: number | undefined,
+  epochs: Record<string, number>,
+  mapValue: (value: number) => T,
+): Array<{ timestamp: string } & T> {
+  return Object.entries(epochs).map(([offset, value]) => ({
+    timestamp: new Date(
+      ((startTimeInSeconds ?? 0) + parseInt(offset, 10)) * 1000,
+    ).toISOString(),
+    ...mapValue(value),
+  }));
+}

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

@@ -0,0 +1,56 @@
+// ─── HRV Summary Transformer ─────────────────────────────────────────────────
+// Transforms a Garmin HRV summary push item into a partial Soma Daily schema
+// shape. HRV data enriches daily records with heart_rate_data (HRV fields).
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientHrvSummary } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin HRV summary push item into a partial Soma Daily shape.
+ *
+ * HRV summaries are ingested into the `daily` table via `ingestDaily`,
+ * enriching the daily record with HRV-specific heart rate data.
+ *
+ * Returns `null` when no meaningful HRV data is present.
+ */
+export function transformHRVSummary(hrv: ClientHrvSummary): SomaDaily | null {
+  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 null;
+  }
+
+  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 {
+    metadata: {
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: 1, // Automatic
+    },
+    heart_rate_data: {
+      summary: hasSummary
+        ? {
+          avg_hrv_rmssd: hrv.lastNightAvg,
+        }
+        : undefined,
+      detailed:
+        hrvSamples && hrvSamples.length > 0
+          ? { hrv_samples_rmssd: hrvSamples }
+          : undefined,
+    },
+  };
+}

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

@@ -0,0 +1,27 @@
+// ─── Manually Updated Activity Transformer ───────────────────────────────────
+// Transforms a Garmin manually updated activity into the Soma Activity schema.
+//
+// Manually updated activities share the same data model as regular activities,
+// so we delegate to transformActivity but force upload_type = 2 (manual).
+
+import type { SomaActivity } from "../../validators/activity.js";
+import type { ClientActivity } from "../types/wellnessApi/types.gen.js";
+import { transformActivity } from "./activity.js";
+
+/**
+ * Transform a Garmin manually updated activity into a Soma Activity shape.
+ *
+ * Per the Garmin API, manually updated activities always have `manual: true`.
+ * We enforce `upload_type: 2` regardless, since these items are by definition
+ * manual edits from Garmin Connect.
+ */
+export function transformManuallyUpdatedActivity(
+  activity: ClientActivity,
+): SomaActivity {
+  const result = transformActivity(activity);
+
+  // Force manual upload type — these are always user-edited on Garmin Connect
+  result.metadata.upload_type = 2;
+
+  return result;
+}