@nativesquare/soma 0.7.3 → 0.9.0

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

@@ -1,78 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { mapActivityType } from "./activity-type.js";
-
-describe("mapActivityType", () => {
-  it("maps running types to Terra Running (8)", () => {
-    expect(mapActivityType("RUNNING")).toBe(8);
-    expect(mapActivityType("INDOOR_RUNNING")).toBe(8);
-    expect(mapActivityType("TRAIL_RUNNING")).toBe(8);
-    expect(mapActivityType("TREADMILL_RUNNING")).toBe(8);
-  });
-
-  it("maps cycling types to Terra Biking (1)", () => {
-    expect(mapActivityType("CYCLING")).toBe(1);
-    expect(mapActivityType("INDOOR_CYCLING")).toBe(1);
-    expect(mapActivityType("MOUNTAIN_BIKING")).toBe(1);
-    expect(mapActivityType("GRAVEL_CYCLING")).toBe(1);
-    expect(mapActivityType("VIRTUAL_RIDE")).toBe(1);
-  });
-
-  it("maps WALKING to Terra Walking (7)", () => {
-    expect(mapActivityType("WALKING")).toBe(7);
-  });
-
-  it("maps HIKING to Terra Hiking (35)", () => {
-    expect(mapActivityType("HIKING")).toBe(35);
-  });
-
-  it("maps swimming types to Terra Swimming (82)", () => {
-    expect(mapActivityType("SWIMMING")).toBe(82);
-    expect(mapActivityType("OPEN_WATER_SWIMMING")).toBe(82);
-    expect(mapActivityType("LAP_SWIMMING")).toBe(82);
-    expect(mapActivityType("POOL_SWIMMING")).toBe(82);
-  });
-
-  it("maps snow sports correctly", () => {
-    expect(mapActivityType("ALPINE_SKIING")).toBe(66);
-    expect(mapActivityType("CROSS_COUNTRY_SKIING")).toBe(67);
-    expect(mapActivityType("SNOWBOARDING")).toBe(73);
-    expect(mapActivityType("SNOWSHOEING")).toBe(74);
-  });
-
-  it("maps water sports correctly", () => {
-    expect(mapActivityType("ROWING")).toBe(53);
-    expect(mapActivityType("INDOOR_ROWING")).toBe(53);
-    expect(mapActivityType("KAYAKING")).toBe(40);
-    expect(mapActivityType("SAILING")).toBe(59);
-    expect(mapActivityType("SURFING")).toBe(81);
-    expect(mapActivityType("KITESURFING")).toBe(41);
-  });
-
-  it("maps racket sports correctly", () => {
-    expect(mapActivityType("TENNIS")).toBe(87);
-    expect(mapActivityType("TABLE_TENNIS")).toBe(85);
-    expect(mapActivityType("BADMINTON")).toBe(10);
-    expect(mapActivityType("SQUASH")).toBe(76);
-  });
-
-  it("maps gym/fitness activities correctly", () => {
-    expect(mapActivityType("STRENGTH_TRAINING")).toBe(80);
-    expect(mapActivityType("CROSSFIT")).toBe(113);
-    expect(mapActivityType("YOGA")).toBe(100);
-    expect(mapActivityType("PILATES")).toBe(49);
-    expect(mapActivityType("HIIT")).toBe(114);
-    expect(mapActivityType("ELLIPTICAL")).toBe(25);
-    expect(mapActivityType("STAIR_CLIMBING")).toBe(78);
-  });
-
-  it("maps team sports correctly", () => {
-    expect(mapActivityType("SOCCER")).toBe(29);
-    expect(mapActivityType("BASKETBALL")).toBe(11);
-    expect(mapActivityType("VOLLEYBALL")).toBe(94);
-  });
-
-  it("returns Terra Other (108) for unknown types", () => {
-    expect(mapActivityType("UNKNOWN_SPORT" as never)).toBe(108);
-    expect(mapActivityType("" as never)).toBe(108);
-  });
-});

package/src/garmin/menstruation.ts

@@ -1,42 +0,0 @@
-// ─── Menstruation Transformer ────────────────────────────────────────────────
-// Transforms Garmin menstrual cycle data into the Soma Menstruation schema shape.
-
-import type { GarminMenstrualCycleData } from "./types.js";
-
-export type MenstruationData = ReturnType<typeof transformMenstruation>;
-
-/**
- * Transform a Garmin menstrual cycle record into a Soma Menstruation document shape.
- *
- * @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`;
-
-  return {
-    metadata: {
-      start_time: startTime,
-      end_time: endTime,
-    },
-
-    menstruation_data: {
-      day_in_cycle: data.dayInCycle,
-      current_phase: data.currentPhase?.toLowerCase(),
-      length_of_current_phase_days: data.lengthOfCurrentPhase,
-      period_length_days: data.periodLength,
-      predicted_cycle_length_days: data.predictedCycleLength,
-      is_predicted_cycle: data.isPredictedCycle != null
-        ? String(data.isPredictedCycle)
-        : undefined,
-    },
-  };
-}

package/src/garmin/sleep.test.ts

@@ -1,110 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { transformSleep } from "./sleep.js";
-import type { GarminSleep } from "./types.js";
-
-const baseSleep: GarminSleep = {
-  userId: "garmin_user_1",
-  userAccessToken: "token",
-  summaryId: "sleep_001",
-  calendarDate: "2023-11-14",
-  startTimeInSeconds: 1700000000,
-  startTimeOffsetInSeconds: -18000,
-  durationInSeconds: 28800, // 8 hours
-  validation: "ENHANCED_FINAL",
-};
-
-describe("transformSleep", () => {
-  it("maps metadata correctly", () => {
-    const result = transformSleep(baseSleep);
-
-    expect(result.metadata.summary_id).toBe("sleep_001");
-    expect(result.metadata.start_time).toBe("2023-11-14T22:13:20.000Z");
-    expect(result.metadata.end_time).toBe("2023-11-15T06:13:20.000Z");
-    expect(result.metadata.upload_type).toBe(2); // ENHANCED_FINAL → Automatic
-  });
-
-  it("maps manual upload type", () => {
-    const manual = { ...baseSleep, validation: "MANUAL" as const };
-    const result = transformSleep(manual);
-    expect(result.metadata.upload_type).toBe(1);
-  });
-
-  it("maps tentative as indeterminate", () => {
-    const tentative = { ...baseSleep, validation: "AUTO_TENTATIVE" as const };
-    const result = transformSleep(tentative);
-    expect(result.metadata.upload_type).toBe(4);
-  });
-
-  it("maps sleep stage durations", () => {
-    const withStages: GarminSleep = {
-      ...baseSleep,
-      deepSleepDurationInSeconds: 7200,
-      lightSleepDurationInSeconds: 14400,
-      remSleepInSeconds: 5400,
-      awakeDurationInSeconds: 1800,
-    };
-    const result = transformSleep(withStages);
-
-    const durations = result.sleep_durations_data;
-    expect(durations.asleep.duration_deep_sleep_state_seconds).toBe(7200);
-    expect(durations.asleep.duration_light_sleep_state_seconds).toBe(14400);
-    expect(durations.asleep.duration_REM_sleep_state_seconds).toBe(5400);
-    expect(durations.asleep.duration_asleep_state_seconds).toBe(27000);
-    expect(durations.awake!.duration_awake_state_seconds).toBe(1800);
-    expect(durations.other!.duration_in_bed_seconds).toBe(28800);
-  });
-
-  it("maps sleep levels hypnogram", () => {
-    const withLevels: GarminSleep = {
-      ...baseSleep,
-      sleepLevelsMap: {
-        deep: [
-          { startTimeInSeconds: 1700003600, endTimeInSeconds: 1700007200 },
-        ],
-        light: [
-          { startTimeInSeconds: 1700000000, endTimeInSeconds: 1700003600 },
-        ],
-        rem: [
-          { startTimeInSeconds: 1700010800, endTimeInSeconds: 1700014400 },
-        ],
-        awake: [
-          { startTimeInSeconds: 1700007200, endTimeInSeconds: 1700010800 },
-        ],
-      },
-    };
-    const result = transformSleep(withLevels);
-    const samples = result.sleep_durations_data.hypnogram_samples;
-
-    expect(samples).toBeDefined();
-    expect(samples).toHaveLength(4);
-    // Sorted by timestamp
-    expect(samples![0].level).toBe(4); // Light
-    expect(samples![1].level).toBe(5); // Deep
-    expect(samples![2].level).toBe(1); // Awake
-    expect(samples![3].level).toBe(6); // REM
-  });
-
-  it("maps respiration data", () => {
-    const withResp: GarminSleep = {
-      ...baseSleep,
-      averageRespirationInBreathsPerMinute: 16,
-      lowestRespirationInBreathsPerMinute: 12,
-      highestRespirationInBreathsPerMinute: 22,
-      timeOffsetSleepRespiration: {
-        "0": 16,
-        "3600": 14,
-        "7200": 12,
-      },
-    };
-    const result = transformSleep(withResp);
-
-    expect(result.respiration_data).toBeDefined();
-    expect(result.respiration_data!.breaths_data!.avg_breaths_per_min).toBe(16);
-    expect(result.respiration_data!.breaths_data!.samples).toHaveLength(3);
-  });
-
-  it("returns undefined respiration_data when no respiration fields", () => {
-    const result = transformSleep(baseSleep);
-    expect(result.respiration_data).toBeUndefined();
-  });
-});

package/src/garmin/sleep.ts

@@ -1,170 +0,0 @@
-// ─── 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

@@ -1,223 +0,0 @@
-// ─── 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 };
-}