@nativesquare/soma 0.7.3 → 0.8.0

package/src/component/private.ts

@@ -34,6 +34,27 @@ export const getConnectionByProvider = internalQuery({
   },
 });
 
+/**
+ * Get a connection by provider's external user ID + provider (internal).
+ * Used by webhook handlers to map Garmin's userId to a Soma connection.
+ */
+export const getConnectionByProviderUserId = internalQuery({
+  args: {
+    providerUserId: v.string(),
+    provider: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("connections")
+      .withIndex("by_providerUserId_provider", (q) =>
+        q
+          .eq("providerUserId", args.providerUserId)
+          .eq("provider", args.provider),
+      )
+      .first();
+  },
+});
+
 /**
  * Update the lastDataUpdate timestamp after a successful sync.
  */

package/src/component/public.ts

@@ -17,6 +17,7 @@ const connectionDoc = v.object({
   _creationTime: v.number(),
   userId: v.string(),
   provider: v.string(),
+  providerUserId: v.optional(v.string()),
   active: v.optional(v.boolean()),
   lastDataUpdate: v.optional(v.string()),
 });
@@ -33,6 +34,7 @@ export const connect = mutation({
   args: {
     userId: v.string(),
     provider: v.string(),
+    providerUserId: v.optional(v.string()),
   },
   returns: v.id("connections"),
   handler: async (ctx, args) => {
@@ -44,8 +46,13 @@ export const connect = mutation({
       .first();
 
     if (existing) {
-      if (!existing.active) {
-        await ctx.db.patch(existing._id, { active: true });
+      const patch: Record<string, unknown> = {};
+      if (!existing.active) patch.active = true;
+      if (args.providerUserId && !existing.providerUserId) {
+        patch.providerUserId = args.providerUserId;
+      }
+      if (Object.keys(patch).length > 0) {
+        await ctx.db.patch(existing._id, patch);
       }
       return existing._id;
     }
@@ -53,6 +60,7 @@ export const connect = mutation({
     return await ctx.db.insert("connections", {
       userId: args.userId,
       provider: args.provider,
+      providerUserId: args.providerUserId,
       active: true,
     });
   },
@@ -142,6 +150,7 @@ export const listConnections = query({
 export const updateConnection = mutation({
   args: {
     connectionId: v.id("connections"),
+    providerUserId: v.optional(v.string()),
     active: v.optional(v.boolean()),
     lastDataUpdate: v.optional(v.string()),
   },

package/src/component/schema.ts

@@ -29,7 +29,8 @@ export default defineSchema({
   connections: defineTable(connectionValidator)
     .index("by_userId", ["userId"])
     .index("by_provider", ["provider"])
-    .index("by_userId_provider", ["userId", "provider"]),
+    .index("by_userId_provider", ["userId", "provider"])
+    .index("by_providerUserId_provider", ["providerUserId", "provider"]),
 
   // ── Athletes ───────────────────────────────────────────────────────────────
   // User profile/identifying information from the provider.

package/src/component/validators/connection.ts

@@ -9,6 +9,8 @@ export const connectionValidator = {
   userId: v.string(),
   // The wearable provider: "FITBIT", "GARMIN", "APPLE", "OURA", etc.
   provider: v.string(),
+  // The provider's external user ID (e.g. Garmin's userId for webhook mapping)
+  providerUserId: v.optional(v.string()),
   // Whether the connection is active
   active: v.optional(v.boolean()),
   // ISO-8601 timestamp of last data update

package/src/component/validators/daily.ts

@@ -1,6 +1,7 @@
 import { v } from "convex/values";
 import {
   activityLevelSample,
+  breathSample,
   calorieSample,
   distanceSample,
   elevationSample,
@@ -120,6 +121,20 @@ export const dailyValidator = {
     upload_type: v.number(), // UploadType enum
   }),
 
+  // ── respiration_data ────────────────────────────────────────────────────
+  respiration_data: v.optional(
+    v.object({
+      breaths_data: v.optional(
+        v.object({
+          avg_breaths_per_min: v.optional(v.number()),
+          max_breaths_per_min: v.optional(v.number()),
+          min_breaths_per_min: v.optional(v.number()),
+          samples: v.optional(v.array(breathSample)),
+        }),
+      ),
+    }),
+  ),
+
   // ── oxygen_data ──────────────────────────────────────────────────────────
   oxygen_data: v.optional(
     v.object({

package/src/component/validators/plannedWorkout.ts

@@ -106,5 +106,9 @@ export const plannedWorkoutValidator = {
     pool_length_meters: v.optional(v.number()),
     estimated_calories: v.optional(v.number()),
     estimated_duration_seconds: v.optional(v.number()),
+    // Provider-assigned workout ID (e.g. Garmin workoutId after push)
+    provider_workout_id: v.optional(v.string()),
+    // Provider-assigned schedule ID (e.g. Garmin scheduleId after push)
+    provider_schedule_id: v.optional(v.string()),
   }),
 };

package/src/garmin/activity.test.ts

@@ -1,10 +1,9 @@
 import { describe, expect, it } from "vitest";
 import { transformActivity } from "./activity.js";
-import type { GarminActivity } from "./types.js";
+import type { GarminActivityExtended } from "./types.js";
 
-const baseActivity: GarminActivity = {
+const baseActivity: GarminActivityExtended = {
   userId: "garmin_user_1",
-  userAccessToken: "token",
   summaryId: "summary_12345",
   activityId: 12345,
   activityName: "Morning Run",
@@ -38,7 +37,7 @@ describe("transformActivity", () => {
   });
 
   it("maps calories data", () => {
-    const withCalories: GarminActivity = {
+    const withCalories: GarminActivityExtended = {
       ...baseActivity,
       activeKilocalories: 450,
       bmrKilocalories: 75,
@@ -57,7 +56,7 @@ describe("transformActivity", () => {
   });
 
   it("maps distance data", () => {
-    const withDistance: GarminActivity = {
+    const withDistance: GarminActivityExtended = {
       ...baseActivity,
       distanceInMeters: 10000,
       elevationGainInMeters: 150,
@@ -73,7 +72,7 @@ describe("transformActivity", () => {
   });
 
   it("maps heart rate summary", () => {
-    const withHR: GarminActivity = {
+    const withHR: GarminActivityExtended = {
       ...baseActivity,
       averageHeartRateInBeatsPerMinute: 155,
       maxHeartRateInBeatsPerMinute: 185,
@@ -86,7 +85,7 @@ describe("transformActivity", () => {
   });
 
   it("maps movement data with speed and cadence", () => {
-    const withMovement: GarminActivity = {
+    const withMovement: GarminActivityExtended = {
       ...baseActivity,
       averageSpeedInMetersPerSecond: 3.5,
       maxSpeedInMetersPerSecond: 5.2,
@@ -103,7 +102,7 @@ describe("transformActivity", () => {
   });
 
   it("maps device data", () => {
-    const withDevice: GarminActivity = {
+    const withDevice: GarminActivityExtended = {
       ...baseActivity,
       deviceName: "Garmin Forerunner 265",
     };
@@ -114,7 +113,7 @@ describe("transformActivity", () => {
   });
 
   it("maps position data", () => {
-    const withPosition: GarminActivity = {
+    const withPosition: GarminActivityExtended = {
       ...baseActivity,
       startingLatitudeInDegree: 37.7749,
       startingLongitudeInDegree: -122.4194,
@@ -126,7 +125,7 @@ describe("transformActivity", () => {
   });
 
   it("maps power data", () => {
-    const withPower: GarminActivity = {
+    const withPower: GarminActivityExtended = {
       ...baseActivity,
       activityType: "CYCLING",
       averagePowerInWatts: 200,
@@ -140,22 +139,14 @@ describe("transformActivity", () => {
   });
 
   it("maps lap data", () => {
-    const withLaps: GarminActivity = {
+    const withLaps: GarminActivityExtended = {
       ...baseActivity,
       laps: [
         {
           startTimeInSeconds: 1700000000,
-          timerDurationInSeconds: 600,
-          totalDistanceInMeters: 1600,
-          heartRate: 150,
-          maxSpeed: 4.5,
         },
         {
           startTimeInSeconds: 1700000600,
-          timerDurationInSeconds: 600,
-          totalDistanceInMeters: 1650,
-          heartRate: 158,
-          maxSpeed: 4.8,
         },
       ],
     };
@@ -163,8 +154,9 @@ describe("transformActivity", () => {
 
     expect(result.lap_data).toBeDefined();
     expect(result.lap_data!.laps).toHaveLength(2);
-    expect(result.lap_data!.laps![0].distance_meters).toBe(1600);
-    expect(result.lap_data!.laps![0].avg_hr_bpm).toBe(150);
+    expect(result.lap_data!.laps![0].start_time).toBe(
+      new Date(1700000000 * 1000).toISOString(),
+    );
   });
 
   it("uses summaryId as summary_id and falls back to activityId", () => {

package/src/garmin/activity.ts

@@ -1,7 +1,7 @@
 // ─── Activity Transformer ────────────────────────────────────────────────────
 // Transforms a Garmin activity into the Soma Activity schema shape.
 
-import type { GarminActivity } from "./types.js";
+import type { GarminActivityExtended, GarminLap, GarminSample } from "./types.js";
 import { mapActivityType } from "./maps/activity-type.js";
 
 export type ActivityData = ReturnType<typeof transformActivity>;
@@ -9,21 +9,16 @@ export type ActivityData = ReturnType<typeof transformActivity>;
 /**
  * Transform a Garmin activity into a Soma Activity document shape.
  *
+ * Accepts both activity summaries (from `/rest/activities`) and detailed
+ * activities (from `/rest/activityDetails` or webhook payloads) which
+ * include laps, samples, and power data.
+ *
  * The returned object is ready to be spread into an `ingestActivity` call
  * alongside `connectionId` and `userId`.
- *
- * @param activity - The Garmin activity from the Health API
- * @returns Soma Activity fields (without connectionId/userId)
- *
- * @example
- * ```ts
- * const data = transformActivity(garminActivity);
- * await soma.ingestActivity(ctx, { connectionId, userId, ...data });
- * ```
  */
-export function transformActivity(activity: GarminActivity) {
-  const startMs = activity.startTimeInSeconds * 1000;
-  const endMs = startMs + activity.durationInSeconds * 1000;
+export function transformActivity(activity: GarminActivityExtended) {
+  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();
 
@@ -32,7 +27,7 @@ export function transformActivity(activity: GarminActivity) {
       summary_id: activity.summaryId ?? String(activity.activityId),
       start_time: startDate,
       end_time: endDate,
-      type: mapActivityType(activity.activityType),
+      type: mapActivityType(activity.activityType ?? "OTHER"),
       upload_type: activity.manual ? 2 : 1,
       name: activity.activityName,
     },
@@ -63,7 +58,7 @@ export function transformActivity(activity: GarminActivity) {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-function buildCaloriesData(activity: GarminActivity) {
+function buildCaloriesData(activity: GarminActivityExtended) {
   if (
     activity.activeKilocalories == null &&
     activity.bmrKilocalories == null
@@ -81,8 +76,12 @@ function buildCaloriesData(activity: GarminActivity) {
   };
 }
 
-function buildDistanceData(activity: GarminActivity) {
-  if (activity.distanceInMeters == null && activity.elevationGainInMeters == null) {
+function buildDistanceData(activity: GarminActivityExtended) {
+  // Spec uses totalElevationGainInMeters; webhooks may use elevationGainInMeters
+  const elevGain = activity.totalElevationGainInMeters ?? activity.elevationGainInMeters;
+  const elevLoss = activity.totalElevationLossInMeters ?? activity.elevationLossInMeters;
+
+  if (activity.distanceInMeters == null && elevGain == null) {
     return undefined;
   }
 
@@ -91,17 +90,17 @@ function buildDistanceData(activity: GarminActivity) {
       distance_meters: activity.distanceInMeters,
       steps: activity.steps,
       elevation:
-        activity.elevationGainInMeters != null
+        elevGain != null
           ? {
-              gain_actual_meters: activity.elevationGainInMeters,
-              loss_actual_meters: activity.elevationLossInMeters,
+              gain_actual_meters: elevGain,
+              loss_actual_meters: elevLoss,
             }
           : undefined,
     },
   };
 }
 
-function buildHeartRateData(activity: GarminActivity) {
+function buildHeartRateData(activity: GarminActivityExtended) {
   const hasHrSummary =
     activity.averageHeartRateInBeatsPerMinute != null ||
     activity.maxHeartRateInBeatsPerMinute != null;
@@ -111,8 +110,8 @@ function buildHeartRateData(activity: GarminActivity) {
 
   const hrSamples = hasSamples
     ? activity.samples!
-        .filter((s) => s.heartRate != null && s.startTimeInSeconds != null)
-        .map((s) => ({
+        .filter((s: GarminSample) => s.heartRate != null && s.startTimeInSeconds != null)
+        .map((s: GarminSample) => ({
           timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
           bpm: s.heartRate!,
         }))
@@ -132,7 +131,7 @@ function buildHeartRateData(activity: GarminActivity) {
   };
 }
 
-function buildMovementData(activity: GarminActivity) {
+function buildMovementData(activity: GarminActivityExtended) {
   const avgCadence =
     activity.averageRunCadenceInStepsPerMinute ??
     activity.averageBikeCadenceInRoundsPerMinute;
@@ -152,10 +151,10 @@ function buildMovementData(activity: GarminActivity) {
   const speedSamples = hasSamples
     ? activity.samples!
         .filter(
-          (s) =>
+          (s: GarminSample) =>
             s.speedMetersPerSecond != null && s.startTimeInSeconds != null,
         )
-        .map((s) => ({
+        .map((s: GarminSample) => ({
           timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
           speed_meters_per_second: s.speedMetersPerSecond!,
         }))
@@ -164,15 +163,15 @@ function buildMovementData(activity: GarminActivity) {
   const cadenceSamples = hasSamples
     ? activity.samples!
         .filter(
-          (s) =>
-            (s.runCadenceInStepsPerMinute != null ||
+          (s: GarminSample) =>
+            (s.stepsPerMinute != null ||
               s.bikeCadenceInRPM != null) &&
             s.startTimeInSeconds != null,
         )
-        .map((s) => ({
+        .map((s: GarminSample) => ({
           timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
           cadence_rpm:
-            s.runCadenceInStepsPerMinute ?? s.bikeCadenceInRPM ?? 0,
+            s.stepsPerMinute ?? s.bikeCadenceInRPM ?? 0,
         }))
     : undefined;
 
@@ -192,7 +191,7 @@ function buildMovementData(activity: GarminActivity) {
   };
 }
 
-function buildPositionData(activity: GarminActivity) {
+function buildPositionData(activity: GarminActivityExtended) {
   const hasStartPos =
     activity.startingLatitudeInDegree != null &&
     activity.startingLongitudeInDegree != null;
@@ -203,12 +202,12 @@ function buildPositionData(activity: GarminActivity) {
   const positionSamples = hasSamples
     ? activity.samples!
         .filter(
-          (s) =>
+          (s: GarminSample) =>
             s.latitudeInDegree != null &&
             s.longitudeInDegree != null &&
             s.startTimeInSeconds != null,
         )
-        .map((s) => ({
+        .map((s: GarminSample) => ({
           timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
           coords_lat_lng_deg: [s.latitudeInDegree!, s.longitudeInDegree!],
         }))
@@ -228,7 +227,7 @@ function buildPositionData(activity: GarminActivity) {
   };
 }
 
-function buildPowerData(activity: GarminActivity) {
+function buildPowerData(activity: GarminActivityExtended) {
   const hasPowerSummary =
     activity.averagePowerInWatts != null ||
     activity.maxPowerInWatts != null;
@@ -239,9 +238,9 @@ function buildPowerData(activity: GarminActivity) {
   const powerSamples = hasSamples
     ? activity.samples!
         .filter(
-          (s) => s.powerInWatts != null && s.startTimeInSeconds != null,
+          (s: GarminSample) => s.powerInWatts != null && s.startTimeInSeconds != null,
         )
-        .map((s) => ({
+        .map((s: GarminSample) => ({
           timestamp: new Date(s.startTimeInSeconds! * 1000).toISOString(),
           watts: s.powerInWatts!,
         }))
@@ -255,18 +254,12 @@ function buildPowerData(activity: GarminActivity) {
   };
 }
 
-function buildLapData(activity: GarminActivity) {
+function buildLapData(activity: GarminActivityExtended) {
   if (!activity.laps || activity.laps.length === 0) return undefined;
 
   return {
-    laps: activity.laps.map((lap) => ({
-      start_time: new Date(lap.startTimeInSeconds * 1000).toISOString(),
-      end_time: new Date(
-        (lap.startTimeInSeconds + lap.timerDurationInSeconds) * 1000,
-      ).toISOString(),
-      distance_meters: lap.totalDistanceInMeters,
-      avg_hr_bpm: lap.heartRate,
-      avg_speed_meters_per_second: lap.maxSpeed,
+    laps: activity.laps.map((lap: GarminLap) => ({
+      start_time: new Date((lap.startTimeInSeconds ?? 0) * 1000).toISOString(),
     })),
   };
 }

package/src/garmin/bloodPressure.ts

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

package/src/garmin/body.ts

@@ -12,7 +12,7 @@ export type BodyData = ReturnType<typeof transformBody>;
  * @returns Soma Body fields (without connectionId/userId)
  */
 export function transformBody(body: GarminBodyComposition) {
-  const measurementMs = body.measurementTimeInSeconds * 1000;
+  const measurementMs = (body.measurementTimeInSeconds ?? 0) * 1000;
   const timestamp = new Date(measurementMs).toISOString();
 
   return {