@nativesquare/soma 0.8.0 → 0.9.1

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

@@ -0,0 +1,43 @@
+// ─── Stress Details Webhook Zod Schemas ───────────────────────────────────────
+// Runtime validation schemas for Garmin Stress Details webhook payloads.
+//
+// The base schema (zClientStress) is auto-generated from the
+// OpenAPI spec. We extend it here with webhook-specific fields (userId,
+// userAccessToken).
+
+import { z } from "zod";
+import { zBodyBatteryActivityEvent, zClientStress } from "../types/wellnessApi/zod.gen.js";
+
+// ─── Push Mode ──────────────────────────────────────────────────────────────
+// Push payloads contain full stress details data plus webhook envelope fields.
+
+export const garminStressPushItemSchema = zClientStress.extend({
+  // Webhook envelope fields
+  userId: z.string(),
+  userAccessToken: z.string().optional(),
+  // Override bigint → number (openapi-ts maps int64 to bigint in zod)
+  bodyBatteryActivityEvents: z.array(
+    zBodyBatteryActivityEvent.extend({ activityId: z.coerce.number().optional() }),
+  ).optional(),
+});
+
+export const garminStressPushPayloadSchema = z.object({
+  stressDetails: z.array(garminStressPushItemSchema),
+});
+
+// ─── Ping Mode ──────────────────────────────────────────────────────────────
+// Ping payloads are lightweight notifications — not in any OpenAPI spec.
+
+export const garminStressPingItemSchema = z.object({
+  userId: z.string(),
+  callbackURL: z.string().optional(), // absent for deregistration notifications
+});
+
+export const garminStressPingPayloadSchema = z.object({
+  stressDetails: z.array(garminStressPingItemSchema),
+});
+
+// ─── Inferred Types ─────────────────────────────────────────────────────────
+
+export type GarminStressPushItem = z.infer<typeof garminStressPushItemSchema>;
+export type GarminStressPingItem = z.infer<typeof garminStressPingItemSchema>;

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

@@ -0,0 +1,39 @@
+// ─── User Metrics Webhook Zod Schemas ─────────────────────────────────────────
+// Runtime validation schemas for Garmin User Metrics webhook payloads.
+//
+// The base schema (zClientUserMetrics) is auto-generated from the
+// OpenAPI spec. We extend it here with webhook-specific fields (userId,
+// userAccessToken).
+
+import { z } from "zod";
+import { zClientUserMetrics } from "../types/wellnessApi/zod.gen.js";
+
+// ─── Push Mode ──────────────────────────────────────────────────────────────
+// Push payloads contain full user metrics data plus webhook envelope fields.
+
+export const garminUserMetricsPushItemSchema = zClientUserMetrics.extend({
+  // Webhook envelope fields
+  userId: z.string(),
+  userAccessToken: z.string().optional(),
+});
+
+export const garminUserMetricsPushPayloadSchema = z.object({
+  userMetrics: z.array(garminUserMetricsPushItemSchema),
+});
+
+// ─── Ping Mode ──────────────────────────────────────────────────────────────
+// Ping payloads are lightweight notifications — not in any OpenAPI spec.
+
+export const garminUserMetricsPingItemSchema = z.object({
+  userId: z.string(),
+  callbackURL: z.string().optional(), // absent for deregistration notifications
+});
+
+export const garminUserMetricsPingPayloadSchema = z.object({
+  userMetrics: z.array(garminUserMetricsPingItemSchema),
+});
+
+// ─── Inferred Types ─────────────────────────────────────────────────────────
+
+export type GarminUserMetricsPushItem = z.infer<typeof garminUserMetricsPushItemSchema>;
+export type GarminUserMetricsPingItem = z.infer<typeof garminUserMetricsPingItemSchema>;

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

@@ -0,0 +1,143 @@
+// ─── Activity Transformer ────────────────────────────────────────────────────
+// Transforms a Garmin activity push item into the Soma Activity schema shape.
+
+import { mapActivityType } from "./maps/activityType.js";
+import type { SomaActivity } from "../../validators/activity.js";
+import type { ClientActivity } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin activity push item into a Soma Activity document shape.
+ *
+ * Accepts activity summaries from webhook push payloads. These contain
+ * summary-level fields only (no laps, samples, or power data).
+ *
+ * The returned object is ready to be spread into an `ingestActivity` call
+ * alongside `connectionId` and `userId`.
+ */
+export function transformActivity(activity: ClientActivity): SomaActivity {
+  const startMs = (activity.startTimeInSeconds ?? 0) * 1000;
+  const endMs = startMs + (activity.durationInSeconds ?? 0) * 1000;
+  const startDate = new Date(startMs).toISOString();
+  const endDate = new Date(endMs).toISOString();
+
+  return {
+    metadata: {
+      summary_id: activity.summaryId ?? String(activity.activityId),
+      start_time: startDate,
+      end_time: endDate,
+      type: mapActivityType(activity.activityType ?? "OTHER"),
+      upload_type: activity.manual ? 2 : 1,
+      name: activity.activityName,
+    },
+
+    active_durations_data: {
+      activity_seconds: activity.durationInSeconds,
+    },
+
+    calories_data: buildCaloriesData(activity),
+
+    device_data: activity.deviceName
+      ? { name: activity.deviceName }
+      : undefined,
+
+    distance_data: buildDistanceData(activity),
+
+    heart_rate_data: buildHeartRateData(activity),
+
+    movement_data: buildMovementData(activity),
+
+    position_data: buildPositionData(activity),
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function buildCaloriesData(activity: ClientActivity) {
+  if (activity.activeKilocalories == null) return undefined;
+
+  return {
+    net_activity_calories: activity.activeKilocalories,
+    total_burned_calories: activity.activeKilocalories,
+  };
+}
+
+function buildDistanceData(activity: ClientActivity) {
+  const elevGain = activity.totalElevationGainInMeters;
+  const elevLoss = activity.totalElevationLossInMeters;
+
+  if (activity.distanceInMeters == null && elevGain == null) {
+    return undefined;
+  }
+
+  return {
+    summary: {
+      distance_meters: activity.distanceInMeters,
+      steps: activity.steps,
+      elevation:
+        elevGain != null
+          ? {
+            gain_actual_meters: elevGain,
+            loss_actual_meters: elevLoss,
+          }
+          : undefined,
+    },
+  };
+}
+
+function buildHeartRateData(activity: ClientActivity) {
+  if (
+    activity.averageHeartRateInBeatsPerMinute == null &&
+    activity.maxHeartRateInBeatsPerMinute == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    summary: {
+      avg_hr_bpm: activity.averageHeartRateInBeatsPerMinute,
+      max_hr_bpm: activity.maxHeartRateInBeatsPerMinute,
+    },
+  };
+}
+
+function buildMovementData(activity: ClientActivity) {
+  const avgCadence =
+    activity.averageRunCadenceInStepsPerMinute ??
+    activity.averageBikeCadenceInRoundsPerMinute;
+  const maxCadence =
+    activity.maxRunCadenceInStepsPerMinute ??
+    activity.maxBikeCadenceInRoundsPerMinute;
+
+  if (
+    activity.averageSpeedInMetersPerSecond == null &&
+    activity.maxSpeedInMetersPerSecond == null &&
+    avgCadence == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    avg_speed_meters_per_second: activity.averageSpeedInMetersPerSecond,
+    max_speed_meters_per_second: activity.maxSpeedInMetersPerSecond,
+    avg_pace_minutes_per_kilometer: activity.averagePaceInMinutesPerKilometer,
+    max_pace_minutes_per_kilometer: activity.maxPaceInMinutesPerKilometer,
+    avg_cadence_rpm: avgCadence,
+    max_cadence_rpm: maxCadence,
+  };
+}
+
+function buildPositionData(activity: ClientActivity) {
+  if (
+    activity.startingLatitudeInDegree == null ||
+    activity.startingLongitudeInDegree == null
+  ) {
+    return undefined;
+  }
+
+  return {
+    start_pos_lat_lng_deg: [
+      activity.startingLatitudeInDegree,
+      activity.startingLongitudeInDegree,
+    ],
+  };
+}

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

@@ -0,0 +1,236 @@
+// ─── Activity Details Transformer ────────────────────────────────────────────
+// Transforms a Garmin activity detail push item into the Soma Activity schema.
+// Enriches the summary-level data from transformActivity with detailed
+// samples (GPS, heart rate, speed, cadence, power, etc.) and lap data.
+
+import type { SomaActivity } from "../../validators/activity.js";
+import type {
+  ClientActivityDetail,
+  ClientLap,
+  Sample,
+} from "../types/wellnessApi/types.gen.js";
+import { transformActivity } from "./activity.js";
+
+/**
+ * Transform a Garmin activity detail push item into a Soma Activity document.
+ *
+ * Accepts activity details from webhook push payloads. These contain
+ * a summary plus per-second samples and lap markers.
+ *
+ * The returned object is ready to be spread into an `ingestActivity` call
+ * alongside `connectionId` and `userId`.
+ */
+export function transformActivityDetails(
+  detail: ClientActivityDetail,
+): SomaActivity {
+  // Start from summary-level transform
+  const summary = detail.summary;
+  if (!summary) {
+    throw new Error(
+      `Activity detail ${detail.summaryId ?? "unknown"} has no summary`,
+    );
+  }
+
+  const base = transformActivity(summary);
+
+  // Override summary_id to use the detail-level one if present
+  if (detail.summaryId) {
+    base.metadata.summary_id = detail.summaryId;
+  }
+
+  const samples = detail.samples ?? [];
+  const laps = detail.laps ?? [];
+
+  // Enrich with detailed sample data
+  return {
+    ...base,
+    heart_rate_data: buildDetailedHeartRateData(base, samples),
+    distance_data: buildDetailedDistanceData(base, samples),
+    movement_data: buildDetailedMovementData(base, samples),
+    position_data: buildDetailedPositionData(base, samples),
+    power_data: buildDetailedPowerData(base, samples),
+    lap_data: buildLapData(laps),
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function toIso(epochSeconds: number): string {
+  return new Date(epochSeconds * 1000).toISOString();
+}
+
+function buildDetailedHeartRateData(
+  base: SomaActivity,
+  samples: Sample[],
+): SomaActivity["heart_rate_data"] {
+  const hrSamples = samples.filter((s) => s.heartRate != null);
+  if (hrSamples.length === 0) return base.heart_rate_data;
+
+  return {
+    ...base.heart_rate_data,
+    detailed: {
+      hr_samples: hrSamples.map((s) => ({
+        timestamp: s.startTimeInSeconds
+          ? toIso(s.startTimeInSeconds)
+          : undefined,
+        bpm: s.heartRate ?? undefined,
+        timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+      })),
+    },
+  };
+}
+
+function buildDetailedDistanceData(
+  base: SomaActivity,
+  samples: Sample[],
+): SomaActivity["distance_data"] {
+  const distanceSamples = samples.filter(
+    (s) => s.totalDistanceInMeters != null,
+  );
+  const elevationSamples = samples.filter(
+    (s) => s.elevationInMeters != null,
+  );
+
+  if (distanceSamples.length === 0 && elevationSamples.length === 0) {
+    return base.distance_data;
+  }
+
+  return {
+    ...base.distance_data,
+    detailed: {
+      distance_samples:
+        distanceSamples.length > 0
+          ? distanceSamples.map((s) => ({
+            timestamp: s.startTimeInSeconds
+              ? toIso(s.startTimeInSeconds)
+              : undefined,
+            distance_meters: s.totalDistanceInMeters ?? undefined,
+            timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+          }))
+          : undefined,
+      elevation_samples:
+        elevationSamples.length > 0
+          ? elevationSamples.map((s) => ({
+            timestamp: s.startTimeInSeconds
+              ? toIso(s.startTimeInSeconds)
+              : undefined,
+            elev_meters: s.elevationInMeters ?? undefined,
+            timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+          }))
+          : undefined,
+    },
+  };
+}
+
+function buildDetailedMovementData(
+  base: SomaActivity,
+  samples: Sample[],
+): SomaActivity["movement_data"] {
+  const speedSamples = samples.filter(
+    (s) => s.speedMetersPerSecond != null,
+  );
+  const cadenceSamples = samples.filter(
+    (s) =>
+      s.stepsPerMinute != null ||
+      s.bikeCadenceInRPM != null ||
+      s.swimCadenceInStrokesPerMinute != null,
+  );
+
+  if (speedSamples.length === 0 && cadenceSamples.length === 0) {
+    return base.movement_data;
+  }
+
+  return {
+    ...base.movement_data,
+    speed_samples:
+      speedSamples.length > 0
+        ? speedSamples.map((s) => ({
+          timestamp: s.startTimeInSeconds
+            ? toIso(s.startTimeInSeconds)
+            : undefined,
+          speed_meters_per_second: s.speedMetersPerSecond ?? undefined,
+          timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+        }))
+        : undefined,
+    cadence_samples:
+      cadenceSamples.length > 0
+        ? cadenceSamples.map((s) => ({
+          timestamp: s.startTimeInSeconds
+            ? toIso(s.startTimeInSeconds)
+            : undefined,
+          cadence_rpm:
+            s.stepsPerMinute ??
+            s.bikeCadenceInRPM ??
+            s.swimCadenceInStrokesPerMinute ??
+            undefined,
+          timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+        }))
+        : undefined,
+  };
+}
+
+function buildDetailedPositionData(
+  base: SomaActivity,
+  samples: Sample[],
+): SomaActivity["position_data"] {
+  const posSamples = samples.filter(
+    (s) => s.latitudeInDegree != null && s.longitudeInDegree != null,
+  );
+
+  if (posSamples.length === 0) return base.position_data;
+
+  return {
+    ...base.position_data,
+    position_samples: posSamples.map((s) => ({
+      timestamp: s.startTimeInSeconds
+        ? toIso(s.startTimeInSeconds)
+        : undefined,
+      coords_lat_lng_deg: [s.latitudeInDegree ?? 0, s.longitudeInDegree ?? 0],
+      timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+    })),
+  };
+}
+
+function buildDetailedPowerData(
+  base: SomaActivity,
+  samples: Sample[],
+): SomaActivity["power_data"] {
+  const powerSamples = samples.filter((s) => s.powerInWatts != null);
+
+  if (powerSamples.length === 0) return base.power_data;
+
+  return {
+    ...base.power_data,
+    power_samples: powerSamples.map((s) => ({
+      timestamp: s.startTimeInSeconds
+        ? toIso(s.startTimeInSeconds)
+        : undefined,
+      watts: s.powerInWatts ?? undefined,
+      timer_duration_seconds: s.timerDurationInSeconds ?? undefined,
+    })),
+  };
+}
+
+function buildLapData(
+  laps: ClientLap[],
+): SomaActivity["lap_data"] {
+  if (laps.length === 0) return undefined;
+
+  return {
+    laps: laps.map((lap, i) => {
+      const startTime = lap.startTimeInSeconds
+        ? toIso(lap.startTimeInSeconds)
+        : undefined;
+      // Estimate end time from next lap's start, if available
+      const nextLap = laps[i + 1];
+      const endTime = nextLap?.startTimeInSeconds
+        ? toIso(nextLap.startTimeInSeconds)
+        : undefined;
+
+      return {
+        start_time: startTime,
+        end_time: endTime,
+      };
+    }),
+  };
+}

package/src/{garmin → component/garmin/transform}/bloodPressure.ts

@@ -1,41 +1,39 @@
-// ─── Blood Pressure Transformer ──────────────────────────────────────────────
-// Transforms Garmin blood pressure data into the Soma Body schema shape.
-
-import type { GarminBloodPressure } from "./types.js";
-
-export type BloodPressureData = ReturnType<typeof transformBloodPressure>;
-
-/**
- * Transform a Garmin blood pressure record into a Soma Body document shape.
- *
- * @param bp - The Garmin blood pressure data from the Health API
- * @returns Soma Body fields (without connectionId/userId)
- */
-export function transformBloodPressure(bp: GarminBloodPressure) {
-  const measurementMs = (bp.measurementTimeInSeconds ?? 0) * 1000;
-  const timestamp = new Date(measurementMs).toISOString();
-
-  if (bp.systolic == null && bp.diastolic == null) {
-    return {
-      metadata: { start_time: timestamp, end_time: timestamp },
-      blood_pressure_data: undefined,
-    };
-  }
-
-  return {
-    metadata: {
-      start_time: timestamp,
-      end_time: timestamp,
-    },
-
-    blood_pressure_data: {
-      blood_pressure_samples: [
-        {
-          timestamp,
-          diastolic_bp: bp.diastolic,
-          systolic_bp: bp.systolic,
-        },
-      ],
-    },
-  };
-}
+// ─── Blood Pressure Transformer ──────────────────────────────────────────────
+// Transforms a Garmin blood pressure push item into the Soma Body schema shape.
+
+import type { SomaBody } from "../../validators/body.js";
+import type { ClientBloodPressure } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin blood pressure push item into a Soma Body document shape.
+ *
+ * Blood pressure records are ingested into the `body` table via `ingestBody`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when neither systolic nor diastolic data is present.
+ */
+export function transformBloodPressure(bp: ClientBloodPressure): SomaBody | null {
+  const measurementMs = (bp.measurementTimeInSeconds ?? 0) * 1000;
+  const timestamp = new Date(measurementMs).toISOString();
+
+  if (bp.systolic == null && bp.diastolic == null) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: timestamp,
+      end_time: timestamp,
+    },
+
+    blood_pressure_data: {
+      blood_pressure_samples: [
+        {
+          timestamp,
+          diastolic_bp: bp.diastolic,
+          systolic_bp: bp.systolic,
+        },
+      ],
+    },
+  };
+}

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

@@ -0,0 +1,51 @@
+// ─── Body Compositions Transformer ───────────────────────────────────────────
+// Transforms a Garmin body composition push item into the Soma Body schema shape.
+
+import type { SomaBody } from "../../validators/body.js";
+import type { ClientBodyComp } from "../types/wellnessApi/types.gen.js";
+
+/**
+ * Transform a Garmin body composition push item into a Soma Body document shape.
+ *
+ * Body composition records are ingested into the `body` table via `ingestBody`,
+ * keyed by `metadata.start_time + metadata.end_time`.
+ *
+ * Returns `null` when no meaningful measurement data is present.
+ */
+export function transformBodyComposition(body: ClientBodyComp): SomaBody | null {
+  const measurementMs = (body.measurementTimeInSeconds ?? 0) * 1000;
+  const timestamp = new Date(measurementMs).toISOString();
+
+  if (
+    body.weightInGrams == null &&
+    body.bodyFatInPercent == null &&
+    body.bodyMassIndex == null &&
+    body.muscleMassInGrams == null &&
+    body.boneMassInGrams == null &&
+    body.bodyWaterInPercent == null
+  ) {
+    return null;
+  }
+
+  return {
+    metadata: {
+      start_time: timestamp,
+      end_time: timestamp,
+    },
+
+    measurements_data: {
+      measurements: [
+        {
+          measurement_time: timestamp,
+          weight_kg:
+            body.weightInGrams != null ? body.weightInGrams / 1000 : undefined,
+          BMI: body.bodyMassIndex,
+          bodyfat_percentage: body.bodyFatInPercent,
+          muscle_mass_g: body.muscleMassInGrams,
+          bone_mass_g: body.boneMassInGrams,
+          water_percentage: body.bodyWaterInPercent,
+        },
+      ],
+    },
+  };
+}