@nativesquare/soma 0.3.0 → 0.4.0

package/src/garmin/sleep.ts

@@ -0,0 +1,170 @@
+// ─── Sleep Transformer ───────────────────────────────────────────────────────
+// Transforms a Garmin sleep session into the Soma Sleep schema shape.
+
+import type { GarminSleep, GarminSleepLevel } from "./types.js";
+import { mapSleepLevel } from "./maps/sleep-level.js";
+
+export type SleepData = ReturnType<typeof transformSleep>;
+
+/**
+ * Transform a Garmin sleep session into a Soma Sleep document shape.
+ *
+ * @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;
+
+  const uploadTypeMap: Record<string, number> = {
+    ENHANCED_FINAL: 2,      // Automatic
+    ENHANCED_TENTATIVE: 4,  // Indeterminate
+    AUTO_FINAL: 2,          // Automatic
+    AUTO_TENTATIVE: 4,      // Indeterminate
+    MANUAL: 1,              // Manual
+  };
+
+  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),
+
+    heart_rate_data: buildHeartRateData(sleep),
+
+    respiration_data: buildRespirationData(sleep),
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildSleepDurationsData(sleep: GarminSleep) {
+  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: GarminSleep) {
+  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 GarminSleepLevel[]) {
+      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 buildHeartRateData(sleep: GarminSleep) {
+  if (
+    !sleep.timeOffsetHeartRateSamples ||
+    Object.keys(sleep.timeOffsetHeartRateSamples).length === 0
+  ) {
+    return undefined;
+  }
+
+  const hrSamples = Object.entries(sleep.timeOffsetHeartRateSamples).map(
+    ([offset, bpm]) => ({
+      timestamp: new Date(
+        (sleep.startTimeInSeconds + parseInt(offset, 10)) * 1000,
+      ).toISOString(),
+      bpm,
+    }),
+  );
+
+  return {
+    detailed: { hr_samples: hrSamples },
+  };
+}
+
+function buildRespirationData(sleep: GarminSleep) {
+  const hasBreathSummary =
+    sleep.averageRespirationInBreathsPerMinute != null;
+  const hasBreathSamples =
+    sleep.timeOffsetSleepRespiration != null &&
+    Object.keys(sleep.timeOffsetSleepRespiration).length > 0;
+  const hasSpO2Samples =
+    sleep.timeOffsetSpo2Values != null &&
+    Object.keys(sleep.timeOffsetSpo2Values).length > 0;
+
+  if (!hasBreathSummary && !hasBreathSamples && !hasSpO2Samples) {
+    return undefined;
+  }
+
+  const breathSamples = hasBreathSamples
+    ? Object.entries(sleep.timeOffsetSleepRespiration!).map(
+        ([offset, rate]) => ({
+          timestamp: new Date(
+            (sleep.startTimeInSeconds + parseInt(offset, 10)) * 1000,
+          ).toISOString(),
+          breaths_per_min: rate,
+        }),
+      )
+    : undefined;
+
+  const spo2Samples = hasSpO2Samples
+    ? Object.entries(sleep.timeOffsetSpo2Values!).map(([offset, pct]) => ({
+        timestamp: new Date(
+          (sleep.startTimeInSeconds + parseInt(offset, 10)) * 1000,
+        ).toISOString(),
+        percentage: pct,
+      }))
+    : undefined;
+
+  return {
+    breaths_data:
+      hasBreathSummary || (breathSamples && breathSamples.length > 0)
+        ? {
+            avg_breaths_per_min: sleep.averageRespirationInBreathsPerMinute,
+            min_breaths_per_min: sleep.lowestRespirationInBreathsPerMinute,
+            max_breaths_per_min: sleep.highestRespirationInBreathsPerMinute,
+            samples:
+              breathSamples && breathSamples.length > 0
+                ? breathSamples
+                : undefined,
+          }
+        : undefined,
+    oxygen_saturation_data:
+      spo2Samples && spo2Samples.length > 0
+        ? {
+            avg_saturation_percentage: sleep.averageSpo2Value,
+            samples: spo2Samples,
+          }
+        : undefined,
+  };
+}

package/src/garmin/sync.ts

@@ -0,0 +1,223 @@
+// ─── Garmin Sync Helpers ─────────────────────────────────────────────────────
+// High-level functions that combine the Garmin client, transformers,
+// and Soma ingestion. Designed to be used inside a Convex action.
+
+import type { Soma } from "../client/index.js";
+import type { ActionCtx } from "../client/types.js";
+import type { GarminClient } from "./client.js";
+import type { TimeRangeParams } from "./client.js";
+import { transformActivity } from "./activity.js";
+import { transformDaily } from "./daily.js";
+import { transformSleep } from "./sleep.js";
+import { transformBody } from "./body.js";
+import { transformMenstruation } from "./menstruation.js";
+
+// ─── Shared Types ────────────────────────────────────────────────────────────
+
+export interface SyncOptions {
+  client: GarminClient;
+  soma: Soma;
+  ctx: ActionCtx;
+  connectionId: string;
+  userId: string;
+  timeRange: TimeRangeParams;
+}
+
+export interface SyncResult {
+  synced: number;
+  errors: Array<{ id: string; error: string }>;
+}
+
+export interface SyncAllResult {
+  activities: SyncResult;
+  dailies: SyncResult;
+  sleep: SyncResult;
+  body: SyncResult;
+  menstruation: SyncResult;
+}
+
+// ─── Sync All ────────────────────────────────────────────────────────────────
+
+/**
+ * Sync all data types from Garmin for a given time range.
+ *
+ * Runs each sync independently so a failure in one type doesn't
+ * block the others.
+ */
+export async function syncAll(opts: SyncOptions): Promise<SyncAllResult> {
+  const [activities, dailies, sleep, body, menstruation] = await Promise.all([
+    syncActivities(opts),
+    syncDailies(opts),
+    syncSleep(opts),
+    syncBody(opts),
+    syncMenstruation(opts),
+  ]);
+
+  return { activities, dailies, sleep, body, menstruation };
+}
+
+// ─── Activities ──────────────────────────────────────────────────────────────
+
+export async function syncActivities(opts: SyncOptions): Promise<SyncResult> {
+  const { client, soma, ctx, connectionId, userId, timeRange } = opts;
+  let synced = 0;
+  const errors: SyncResult["errors"] = [];
+
+  try {
+    const activities = await client.getActivities(timeRange);
+
+    for (const activity of activities) {
+      try {
+        const data = transformActivity(activity);
+        await soma.ingestActivity(ctx, { connectionId, userId, ...data });
+        synced++;
+      } catch (err) {
+        errors.push({
+          id: activity.summaryId ?? String(activity.activityId),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return { synced, errors };
+}
+
+// ─── Dailies ─────────────────────────────────────────────────────────────────
+
+export async function syncDailies(opts: SyncOptions): Promise<SyncResult> {
+  const { client, soma, ctx, connectionId, userId, timeRange } = opts;
+  let synced = 0;
+  const errors: SyncResult["errors"] = [];
+
+  try {
+    const dailies = await client.getDailies(timeRange);
+
+    for (const daily of dailies) {
+      try {
+        const data = transformDaily(daily);
+        await soma.ingestDaily(ctx, { connectionId, userId, ...data });
+        synced++;
+      } catch (err) {
+        errors.push({
+          id: daily.summaryId ?? daily.calendarDate,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return { synced, errors };
+}
+
+// ─── Sleep ───────────────────────────────────────────────────────────────────
+
+export async function syncSleep(opts: SyncOptions): Promise<SyncResult> {
+  const { client, soma, ctx, connectionId, userId, timeRange } = opts;
+  let synced = 0;
+  const errors: SyncResult["errors"] = [];
+
+  try {
+    const sleeps = await client.getSleeps(timeRange);
+
+    for (const sleep of sleeps) {
+      try {
+        const data = transformSleep(sleep);
+        await soma.ingestSleep(ctx, { connectionId, userId, ...data });
+        synced++;
+      } catch (err) {
+        errors.push({
+          id: sleep.summaryId ?? sleep.calendarDate,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return { synced, errors };
+}
+
+// ─── Body Composition ────────────────────────────────────────────────────────
+
+export async function syncBody(opts: SyncOptions): Promise<SyncResult> {
+  const { client, soma, ctx, connectionId, userId, timeRange } = opts;
+  let synced = 0;
+  const errors: SyncResult["errors"] = [];
+
+  try {
+    const bodyComps = await client.getBodyCompositions(timeRange);
+
+    for (const body of bodyComps) {
+      try {
+        const data = transformBody(body);
+        await soma.ingestBody(ctx, { connectionId, userId, ...data });
+        synced++;
+      } catch (err) {
+        errors.push({
+          id: body.summaryId ?? String(body.measurementTimeInSeconds),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return { synced, errors };
+}
+
+// ─── Menstruation ────────────────────────────────────────────────────────────
+
+export async function syncMenstruation(
+  opts: SyncOptions,
+): Promise<SyncResult> {
+  const { client, soma, ctx, connectionId, userId, timeRange } = opts;
+  let synced = 0;
+  const errors: SyncResult["errors"] = [];
+
+  try {
+    const records = await client.getMenstrualCycleData(timeRange);
+
+    for (const record of records) {
+      try {
+        const data = transformMenstruation(record);
+        await soma.ingestMenstruation(ctx, {
+          connectionId,
+          userId,
+          ...data,
+        });
+        synced++;
+      } catch (err) {
+        errors.push({
+          id: record.summaryId ?? record.calendarDate,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return { synced, errors };
+}