@nativesquare/soma 0.8.0 → 0.9.1

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

@@ -0,0 +1,64 @@
+// ─── Pulse Ox Transformer ────────────────────────────────────────────────────
+// Transforms a Garmin Pulse Ox push item into the Soma Daily schema shape.
+//
+// Pulse Ox summaries contain SpO2 (blood oxygen saturation) readings
+// throughout the day. We map these into the Daily model's oxygen_data field.
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientDailySpo2Acclimation } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin Pulse Ox push item into a Soma Daily document shape.
+ *
+ * Pulse Ox 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 transformPulseOx(pulseOx: ClientDailySpo2Acclimation): SomaDaily | null {
+  const startMs = (pulseOx.startTimeInSeconds ?? 0) * 1000;
+  const endMs =
+    startMs + (pulseOx.durationInSeconds ?? 0) * 1000;
+
+  const oxygenData = buildOxygenData(pulseOx);
+
+  if (oxygenData == null) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: 1, // Automatic
+    },
+
+    oxygen_data: oxygenData,
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildOxygenData(pulseOx: ClientDailySpo2Acclimation) {
+  const hasSamples =
+    pulseOx.timeOffsetSpo2Values != null &&
+    Object.keys(pulseOx.timeOffsetSpo2Values).length > 0;
+
+  if (!hasSamples) {
+    return 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 {
+    saturation_samples: samples.length > 0 ? samples : undefined,
+  };
+}

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

@@ -0,0 +1,73 @@
+// ─── Respiration Transformer ─────────────────────────────────────────────────
+// Transforms a Garmin Respiration push item into the Soma Daily schema shape.
+//
+// Respiration summaries contain breathing rate readings throughout the day.
+// We map these into the Daily model's respiration_data field.
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientRespiration } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin Respiration push item into a Soma Daily document shape.
+ *
+ * Respiration 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 transformRespiration(resp: ClientRespiration): SomaDaily | null {
+  const startMs = (resp.startTimeInSeconds ?? 0) * 1000;
+  const endMs =
+    startMs + (resp.durationInSeconds ?? 0) * 1000;
+
+  const respirationData = buildRespirationData(resp);
+
+  if (respirationData == null) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: 1, // Automatic
+    },
+
+    respiration_data: respirationData,
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildRespirationData(resp: ClientRespiration) {
+  const hasSamples =
+    resp.timeOffsetEpochToBreaths != null &&
+    Object.keys(resp.timeOffsetEpochToBreaths).length > 0;
+
+  if (!hasSamples) {
+    return 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 {
+    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/component/garmin/transform/skinTemperature.ts

@@ -0,0 +1,44 @@
+// ─── Skin Temperature Transformer ────────────────────────────────────────────
+// Transforms a Garmin Skin Temperature push item into the Soma Body schema shape.
+//
+// Skin temperature summaries contain the average deviation of the user's
+// skin temperature during their sleep window. We map this into the Body
+// model's temperature_data.skin_temperature_samples field.
+
+import type { SomaBody } from "../../validators/body.js";
+import type { ClientSkinTemp } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin Skin Temperature push item into a Soma Body document shape.
+ *
+ * Skin temperature records are ingested into the `body` table via `ingestBody`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when no meaningful temperature data is present.
+ */
+export function transformSkinTemperature(skinTemp: ClientSkinTemp): SomaBody | null {
+  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 null;
+  }
+
+  return {
+    metadata: {
+      start_time: startTime,
+      end_time: endTime,
+    },
+
+    temperature_data: {
+      skin_temperature_samples: [
+        {
+          timestamp: startTime,
+          temperature_celsius: skinTemp.avgDeviationCelsius,
+        },
+      ],
+    },
+  };
+}

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

@@ -0,0 +1,159 @@
+// ─── Sleeps Transformer ──────────────────────────────────────────────────────
+// Transforms a Garmin sleep summary push item into the Soma Sleep schema shape.
+
+import { mapSleepLevel } from "./maps/sleepLevel.js";
+import type { ClientSleep } from "../types/wellnessApi/types.gen.js";
+
+type TimeRange = {
+  startTimeInSeconds?: number;
+  endTimeInSeconds?: number;
+};
+
+/**
+ * Transform a Garmin sleep summary push item into a Soma Sleep document shape.
+ *
+ * Sleep summaries are ingested into the `sleep` table via `ingestSleep`,
+ * keyed by `metadata.summary_id`.
+ *
+ * The returned object is ready to be spread into an `ingestSleep` call
+ * alongside `connectionId` and `userId`.
+ */
+export function transformSleeps(sleep: ClientSleep) {
+  const startMs = (sleep.startTimeInSeconds ?? 0) * 1000;
+  const endMs =
+    startMs +
+    ((sleep.durationInSeconds ?? 0) + (sleep.awakeDurationInSeconds ?? 0)) *
+    1000;
+
+  const uploadTypeMap: Record<string, number> = {
+    ENHANCED_FINAL: 2,
+    ENHANCED_TENTATIVE: 4,
+    AUTO_FINAL: 2,
+    AUTO_TENTATIVE: 4,
+    AUTO_MANUAL: 2,
+    MANUAL: 1,
+    DEVICE: 2,
+    OFF_WRIST: 0,
+  };
+
+  return {
+    metadata: {
+      summary_id: sleep.summaryId,
+      start_time: new Date(startMs).toISOString(),
+      end_time: new Date(endMs).toISOString(),
+      upload_type: uploadTypeMap[sleep.validation ?? ""] ?? 0,
+    },
+
+    sleep_durations_data: buildSleepDurationsData(sleep),
+
+    respiration_data: buildRespirationData(sleep),
+
+    scores: buildScoresData(sleep),
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildSleepDurationsData(sleep: ClientSleep) {
+  const totalAsleep =
+    (sleep.deepSleepDurationInSeconds ?? 0) +
+    (sleep.lightSleepDurationInSeconds ?? 0) +
+    (sleep.remSleepInSeconds ?? 0);
+
+  return {
+    asleep: {
+      duration_asleep_state_seconds: totalAsleep || undefined,
+      duration_deep_sleep_state_seconds: sleep.deepSleepDurationInSeconds,
+      duration_light_sleep_state_seconds: sleep.lightSleepDurationInSeconds,
+      duration_REM_sleep_state_seconds: sleep.remSleepInSeconds,
+    },
+    awake: {
+      duration_awake_state_seconds: sleep.awakeDurationInSeconds,
+    },
+    other: {
+      duration_in_bed_seconds: sleep.durationInSeconds,
+      duration_unmeasurable_sleep_seconds: sleep.unmeasurableSleepInSeconds,
+    },
+    hypnogram_samples: buildHypnogramSamples(sleep),
+  };
+}
+
+function buildHypnogramSamples(sleep: ClientSleep) {
+  if (!sleep.sleepLevelsMap) return undefined;
+
+  const samples: Array<{ timestamp: string; level: number }> = [];
+
+  for (const [stage, levels] of Object.entries(sleep.sleepLevelsMap)) {
+    if (!levels) continue;
+    const terraLevel = mapSleepLevel(stage);
+
+    for (const level of levels as TimeRange[]) {
+      if (level.startTimeInSeconds == null) continue;
+      samples.push({
+        timestamp: new Date(level.startTimeInSeconds * 1000).toISOString(),
+        level: terraLevel,
+      });
+    }
+  }
+
+  samples.sort(
+    (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+  );
+
+  return samples.length > 0 ? samples : undefined;
+}
+
+function buildRespirationData(sleep: ClientSleep) {
+  const hasBreathSamples =
+    sleep.timeOffsetSleepRespiration != null &&
+    Object.keys(sleep.timeOffsetSleepRespiration).length > 0;
+  const hasSpO2Samples =
+    sleep.timeOffsetSleepSpo2 != null &&
+    Object.keys(sleep.timeOffsetSleepSpo2).length > 0;
+
+  if (!hasBreathSamples && !hasSpO2Samples) {
+    return undefined;
+  }
+
+  const startTime = sleep.startTimeInSeconds ?? 0;
+
+  const breathSamples = hasBreathSamples
+    ? Object.entries(sleep.timeOffsetSleepRespiration ?? {}).map(
+      ([offset, rate]) => ({
+        timestamp: new Date(
+          (startTime + parseInt(offset, 10)) * 1000,
+        ).toISOString(),
+        breaths_per_min: rate,
+      }),
+    )
+    : undefined;
+
+  const spo2Samples = hasSpO2Samples
+    ? Object.entries(sleep.timeOffsetSleepSpo2 ?? {}).map(([offset, pct]) => ({
+      timestamp: new Date(
+        (startTime + parseInt(offset, 10)) * 1000,
+      ).toISOString(),
+      percentage: pct,
+    }))
+    : undefined;
+
+  return {
+    breaths_data:
+      breathSamples && breathSamples.length > 0
+        ? { samples: breathSamples }
+        : undefined,
+    oxygen_saturation_data:
+      spo2Samples && spo2Samples.length > 0
+        ? { samples: spo2Samples }
+        : undefined,
+  };
+}
+
+function buildScoresData(sleep: ClientSleep) {
+  const overallScore = sleep.overallSleepScore?.value;
+  if (overallScore == null) return undefined;
+
+  return {
+    sleep: overallScore,
+  };
+}

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

@@ -0,0 +1,78 @@
+// ─── Stress Details Transformer ──────────────────────────────────────────────
+// Transforms a Garmin Stress Details push item into the Soma Daily schema shape.
+//
+// Stress details summaries contain 3-minute stress level averages and body
+// battery values throughout the day. We map these into the Daily model's
+// stress_data field.
+
+import type { SomaDaily } from "../../validators/daily.js";
+import type { ClientStress } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin Stress Details push item into a Soma Daily document shape.
+ *
+ * Stress records are ingested into the `daily` table via `ingestDaily`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when no meaningful stress data is present.
+ */
+export function transformStress(stress: ClientStress): SomaDaily | null {
+  const hasSummary =
+    stress.averageStressLevel != null || stress.maxStressLevel != null;
+  const hasStressSamples =
+    stress.timeOffsetStressLevelValues != null &&
+    Object.keys(stress.timeOffsetStressLevelValues).length > 0;
+  const hasBodyBatterySamples =
+    stress.timeOffsetBodyBatteryValues != null &&
+    Object.keys(stress.timeOffsetBodyBatteryValues).length > 0;
+
+  if (!hasSummary && !hasStressSamples && !hasBodyBatterySamples) {
+    return null;
+  }
+
+  const startSeconds = stress.startTimeInSeconds ?? 0;
+  const durationSeconds = stress.durationInSeconds ?? 86400;
+  const startTime = new Date(startSeconds * 1000).toISOString();
+  const endTime = new Date((startSeconds + durationSeconds) * 1000).toISOString();
+
+  const stressSamples = hasStressSamples
+    ? Object.entries(stress.timeOffsetStressLevelValues ?? {}).map(
+      ([offset, level]) => ({
+        timestamp: new Date(
+          (startSeconds + parseInt(offset, 10)) * 1000,
+        ).toISOString(),
+        level,
+      }),
+    )
+    : undefined;
+
+  const bodyBatterySamples = hasBodyBatterySamples
+    ? Object.entries(stress.timeOffsetBodyBatteryValues ?? {}).map(
+      ([offset, level]) => ({
+        timestamp: new Date(
+          (startSeconds + parseInt(offset, 10)) * 1000,
+        ).toISOString(),
+        level,
+      }),
+    )
+    : undefined;
+
+  return {
+    metadata: {
+      start_time: startTime,
+      end_time: endTime,
+      upload_type: 1,
+    },
+
+    stress_data: {
+      avg_stress_level: stress.averageStressLevel,
+      max_stress_level: stress.maxStressLevel,
+      samples:
+        stressSamples && stressSamples.length > 0 ? stressSamples : undefined,
+      body_battery_samples:
+        bodyBatterySamples && bodyBatterySamples.length > 0
+          ? bodyBatterySamples
+          : undefined,
+    },
+  };
+}

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

@@ -0,0 +1,56 @@
+// ─── User Metrics Transformer ────────────────────────────────────────────────
+// Transforms a Garmin User Metrics push item into the Soma Body schema shape.
+//
+// User Metrics summaries contain VO2 Max, VO2 Max Cycling, fitness age, and
+// an enhanced flag. We map these into the Body model's oxygen_data and
+// measurements_data fields.
+
+import type { SomaBody } from "../../validators/body.js";
+import type { ClientUserMetrics } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin User Metrics push item into a Soma Body document shape.
+ *
+ * User metrics records are ingested into the `body` table via `ingestBody`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when no meaningful metrics data is present.
+ */
+export function transformUserMetrics(metrics: ClientUserMetrics): SomaBody | null {
+  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 null;
+  }
+
+  return {
+    metadata: {
+      start_time: startTime,
+      end_time: endTime,
+    },
+
+    oxygen_data: hasVo2
+      ? { vo2max_ml_per_min_per_kg: metrics.vo2Max ?? metrics.vo2MaxCycling }
+      : undefined,
+
+    measurements_data: hasFitnessAge
+      ? {
+        measurements: [
+          {
+            measurement_time: startTime,
+            estimated_fitness_age: String(metrics.fitnessAge),
+          },
+        ],
+      }
+      : undefined,
+  };
+}