@nativesquare/soma 0.7.2 → 0.8.0

package/src/component/garmin.ts

@@ -26,6 +26,13 @@ import { transformDaily } from "../garmin/daily.js";
 import { transformSleep } from "../garmin/sleep.js";
 import { transformBody } from "../garmin/body.js";
 import { transformMenstruation } from "../garmin/menstruation.js";
+import { transformBloodPressure } from "../garmin/bloodPressure.js";
+import { transformSkinTemp } from "../garmin/skinTemp.js";
+import { transformUserMetrics } from "../garmin/userMetrics.js";
+import { transformHRV } from "../garmin/hrv.js";
+import { transformStressDetails } from "../garmin/stressDetails.js";
+import { transformPulseOx } from "../garmin/pulseOx.js";
+import { transformRespiration } from "../garmin/respiration.js";
 import { transformPlannedWorkoutToGarmin } from "../garmin/plannedWorkout.js";
 
 // Use anyApi to avoid circular type references between this file and _generated/api.ts.
@@ -37,6 +44,22 @@ const internalApi: any = anyApi;
 // Default sync window: last 30 days
 const DEFAULT_SYNC_DAYS = 30;
 
+// Shared synced counter validator for all sync actions
+const syncedValidator = v.object({
+  activities: v.number(),
+  dailies: v.number(),
+  sleep: v.number(),
+  body: v.number(),
+  menstruation: v.number(),
+  bloodPressures: v.number(),
+  skinTemp: v.number(),
+  userMetrics: v.number(),
+  hrv: v.number(),
+  stressDetails: v.number(),
+  pulseOx: v.number(),
+  respiration: v.number(),
+});
+
 // Refresh buffer: refresh tokens 10 minutes before expiry
 const REFRESH_BUFFER_SECONDS = 600;
 
@@ -252,13 +275,7 @@ export const connectGarmin = action({
   },
   returns: v.object({
     connectionId: v.string(),
-    synced: v.object({
-      activities: v.number(),
-      dailies: v.number(),
-      sleep: v.number(),
-      body: v.number(),
-      menstruation: v.number(),
-    }),
+    synced: syncedValidator,
     errors: v.array(
       v.object({ type: v.string(), id: v.string(), error: v.string() }),
     ),
@@ -289,6 +306,15 @@ export const connectGarmin = action({
       accessToken: tokenResult.access_token,
     });
 
+    // Best-effort: resolve Garmin user ID for webhook mapping
+    const garminUserId = await client.getUserId();
+    if (garminUserId) {
+      await ctx.runMutation(publicApi.public.updateConnection, {
+        connectionId,
+        providerUserId: garminUserId,
+      });
+    }
+
     const now = Math.floor(Date.now() / 1000);
     const thirtyDaysAgo = now - DEFAULT_SYNC_DAYS * 86400;
     const timeRange = {
@@ -334,13 +360,7 @@ export const completeGarminOAuth = action({
   },
   returns: v.object({
     connectionId: v.string(),
-    synced: v.object({
-      activities: v.number(),
-      dailies: v.number(),
-      sleep: v.number(),
-      body: v.number(),
-      menstruation: v.number(),
-    }),
+    synced: syncedValidator,
     errors: v.array(
       v.object({ type: v.string(), id: v.string(), error: v.string() }),
     ),
@@ -385,6 +405,15 @@ export const completeGarminOAuth = action({
       accessToken: tokenResult.access_token,
     });
 
+    // Best-effort: resolve Garmin user ID for webhook mapping
+    const garminUserId = await client.getUserId();
+    if (garminUserId) {
+      await ctx.runMutation(publicApi.public.updateConnection, {
+        connectionId,
+        providerUserId: garminUserId,
+      });
+    }
+
     const now = Math.floor(Date.now() / 1000);
     const thirtyDaysAgo = now - DEFAULT_SYNC_DAYS * 86400;
     const timeRange = {
@@ -426,13 +455,7 @@ export const syncGarmin = action({
     endTimeInSeconds: v.optional(v.number()),
   },
   returns: v.object({
-    synced: v.object({
-      activities: v.number(),
-      dailies: v.number(),
-      sleep: v.number(),
-      body: v.number(),
-      menstruation: v.number(),
-    }),
+    synced: syncedValidator,
     errors: v.array(
       v.object({ type: v.string(), id: v.string(), error: v.string() }),
     ),
@@ -493,6 +516,17 @@ export const syncGarmin = action({
 
     const client = new GarminClient({ accessToken });
 
+    // Lazy backfill: resolve Garmin user ID if missing (for webhook mapping)
+    if (!connection.providerUserId) {
+      const garminUserId = await client.getUserId();
+      if (garminUserId) {
+        await ctx.runMutation(publicApi.public.updateConnection, {
+          connectionId,
+          providerUserId: garminUserId,
+        });
+      }
+    }
+
     const now = Math.floor(Date.now() / 1000);
     const timeRange = {
       uploadStartTimeInSeconds:
@@ -615,28 +649,33 @@ export const pushPlannedWorkout = action({
       );
     }
 
+    // Always force-refresh the token for Training API calls to rule out
+    // stale tokens (the initial sync swallows 401 errors silently).
     let accessToken = tokenDoc.accessToken;
 
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    if (
-      tokenDoc.expiresAt &&
-      tokenDoc.refreshToken &&
-      nowSeconds >= tokenDoc.expiresAt - REFRESH_BUFFER_SECONDS
-    ) {
-      const refreshed = await refreshToken({
-        clientId: args.clientId,
-        clientSecret: args.clientSecret,
-        refreshToken: tokenDoc.refreshToken,
-      });
+    if (tokenDoc.refreshToken) {
+      try {
+        const refreshed = await refreshToken({
+          clientId: args.clientId,
+          clientSecret: args.clientSecret,
+          refreshToken: tokenDoc.refreshToken,
+        });
 
-      accessToken = refreshed.access_token;
-      const newExpiresAt = nowSeconds + refreshed.expires_in;
-      await ctx.runMutation(internalApi.garmin.storeTokens, {
-        connectionId,
-        accessToken: refreshed.access_token,
-        refreshToken: refreshed.refresh_token,
-        expiresAt: newExpiresAt,
-      });
+        accessToken = refreshed.access_token;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        const newExpiresAt = nowSeconds + refreshed.expires_in;
+        await ctx.runMutation(internalApi.garmin.storeTokens, {
+          connectionId,
+          accessToken: refreshed.access_token,
+          refreshToken: refreshed.refresh_token,
+          expiresAt: newExpiresAt,
+        });
+      } catch (refreshErr) {
+        throw new Error(
+          `Garmin token refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}. ` +
+            "The user may need to reconnect their Garmin account.",
+        );
+      }
     }
 
     const plannedWorkout = await ctx.runQuery(
@@ -649,40 +688,13 @@ export const pushPlannedWorkout = action({
       );
     }
 
-    const client = new GarminClient({ accessToken });
-
-    // Verify the user has WORKOUT_IMPORT permission before attempting to create
-    let permissions: string[] = [];
-    try {
-      permissions = await client.getUserPermissions();
-    } catch (permErr) {
-      const status =
-        permErr instanceof Error && "status" in permErr
-          ? (permErr as { status: number }).status
-          : undefined;
-      throw new Error(
-        `Unable to verify Garmin Training API permissions (HTTP ${status ?? "unknown"}). ` +
-          "Ensure your Garmin app is registered for the Training API program " +
-          "(https://developerportal.garmin.com/user/me/apps?program=829) " +
-          "and that the user has completed OAuth with the correct scopes.",
-      );
-    }
-
-    if (!permissions.includes("WORKOUT_IMPORT")) {
-      throw new Error(
-        `Garmin user does not have WORKOUT_IMPORT permission. ` +
-          `Current permissions: [${permissions.join(", ")}]. ` +
-          "The user must grant workout import access, or the Garmin app " +
-          "may not be registered for the Training API program.",
-      );
-    }
-
     const providerName = args.workoutProvider ?? "Soma";
     const garminWorkout = transformPlannedWorkoutToGarmin(
       plannedWorkout,
       providerName,
     );
 
+    const client = new GarminClient({ accessToken });
     const created = await client.createWorkout(garminWorkout);
 
     if (!created.workoutId) {
@@ -700,6 +712,20 @@ export const pushPlannedWorkout = action({
       garminScheduleId = schedule.scheduleId ?? null;
     }
 
+    // Store the Garmin workout/schedule IDs back on the planned workout
+    // so the host app can match completed activities to planned sessions.
+    await ctx.runMutation(publicApi.public.ingestPlannedWorkout, {
+      ...plannedWorkout,
+      _id: undefined,
+      _creationTime: undefined,
+      metadata: {
+        ...plannedWorkout.metadata,
+        provider_workout_id: String(created.workoutId),
+        provider_schedule_id:
+          garminScheduleId != null ? String(garminScheduleId) : undefined,
+      },
+    } as never);
+
     return {
       garminWorkoutId: created.workoutId,
       garminScheduleId,
@@ -707,6 +733,640 @@ export const pushPlannedWorkout = action({
   },
 });
 
+// ─── Webhook Handlers (Push Mode) ────────────────────────────────────────────
+// Each handler receives full Garmin data objects from push-mode webhooks.
+// Separate actions per data type because the Garmin developer portal
+// configures separate URLs per type.
+
+const webhookResultValidator = v.object({
+  processed: v.number(),
+  errors: v.array(
+    v.object({ type: v.string(), id: v.string(), error: v.string() }),
+  ),
+});
+
+/**
+ * Handle a webhook for Garmin activities (push or ping mode).
+ *
+ * Push mode: receives full GarminActivity objects, transforms, and ingests.
+ * Ping mode: receives notifications, fetches data from the Garmin API, transforms, and ingests.
+ */
+export const handleGarminWebhookActivities = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "activity",
+      transform: (item) => transformActivity(item as never),
+      ingest: publicApi.public.ingestActivity,
+      getId: (item) =>
+        (item as { summaryId?: string; activityId?: number }).summaryId ??
+        String((item as { activityId?: number }).activityId ?? "unknown"),
+      fetchData: (client, timeRange) => client.getActivities(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin daily summaries (push or ping mode).
+ */
+export const handleGarminWebhookDailies = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "daily",
+      transform: (item) => transformDaily(item as never),
+      ingest: publicApi.public.ingestDaily,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getDailies(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin sleep summaries (push or ping mode).
+ */
+export const handleGarminWebhookSleeps = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "sleep",
+      transform: (item) => transformSleep(item as never),
+      ingest: publicApi.public.ingestSleep,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getSleeps(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin body composition summaries (push or ping mode).
+ */
+export const handleGarminWebhookBody = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "body",
+      transform: (item) => transformBody(item as never),
+      ingest: publicApi.public.ingestBody,
+      getId: (item) =>
+        (item as { summaryId?: string; measurementTimeInSeconds?: number })
+          .summaryId ??
+        String(
+          (item as { measurementTimeInSeconds?: number })
+            .measurementTimeInSeconds ?? "unknown",
+        ),
+      fetchData: (client, timeRange) => client.getBodyCompositions(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin menstrual cycle tracking (push or ping mode).
+ */
+export const handleGarminWebhookMenstruation = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "menstruation",
+      transform: (item) => transformMenstruation(item as never),
+      ingest: publicApi.public.ingestMenstruation,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getMenstrualCycleData(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin blood pressure summaries (push or ping mode).
+ */
+export const handleGarminWebhookBloodPressures = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "bloodPressure",
+      transform: (item) => transformBloodPressure(item as never),
+      ingest: publicApi.public.ingestBody,
+      getId: (item) =>
+        (item as { summaryId?: string; measurementTimeInSeconds?: number })
+          .summaryId ??
+        String(
+          (item as { measurementTimeInSeconds?: number })
+            .measurementTimeInSeconds ?? "unknown",
+        ),
+      fetchData: (client, timeRange) => client.getBloodPressures(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin skin temperature summaries (push or ping mode).
+ */
+export const handleGarminWebhookSkinTemp = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "skinTemp",
+      transform: (item) => transformSkinTemp(item as never),
+      ingest: publicApi.public.ingestBody,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getSkinTemperature(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin user metrics (push or ping mode).
+ */
+export const handleGarminWebhookUserMetrics = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "userMetrics",
+      transform: (item) => transformUserMetrics(item as never),
+      ingest: publicApi.public.ingestBody,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getUserMetrics(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin HRV summaries (push or ping mode).
+ * Enriches daily records with heart_rate_data.
+ */
+export const handleGarminWebhookHRV = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "hrv",
+      transform: (item) => {
+        const record = item as { startTimeInSeconds?: number; durationInSeconds?: number };
+        const data = transformHRV(item as never);
+        if (!data.heart_rate_data) return null;
+        return {
+          metadata: {
+            start_time: new Date((record.startTimeInSeconds ?? 0) * 1000).toISOString(),
+            end_time: new Date(((record.startTimeInSeconds ?? 0) + (record.durationInSeconds ?? 86400)) * 1000).toISOString(),
+            upload_type: 1,
+          },
+          heart_rate_data: data.heart_rate_data,
+        };
+      },
+      ingest: publicApi.public.ingestDaily,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getHRV(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin stress detail summaries (push or ping mode).
+ * Enriches daily records with stress_data.
+ */
+export const handleGarminWebhookStressDetails = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "stressDetails",
+      transform: (item) => {
+        const record = item as { startTimeInSeconds?: number; durationInSeconds?: number };
+        const data = transformStressDetails(item as never);
+        if (!data.stress_data) return null;
+        return {
+          metadata: {
+            start_time: new Date((record.startTimeInSeconds ?? 0) * 1000).toISOString(),
+            end_time: new Date(((record.startTimeInSeconds ?? 0) + (record.durationInSeconds ?? 86400)) * 1000).toISOString(),
+            upload_type: 1,
+          },
+          stress_data: data.stress_data,
+        };
+      },
+      ingest: publicApi.public.ingestDaily,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getStressDetails(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin pulse oximetry (SpO2) summaries (push or ping mode).
+ * Enriches daily records with oxygen_data.
+ */
+export const handleGarminWebhookPulseOx = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "pulseOx",
+      transform: (item) => {
+        const record = item as { startTimeInSeconds?: number; durationInSeconds?: number };
+        const data = transformPulseOx(item as never);
+        if (!data.oxygen_data) return null;
+        return {
+          metadata: {
+            start_time: new Date((record.startTimeInSeconds ?? 0) * 1000).toISOString(),
+            end_time: new Date(((record.startTimeInSeconds ?? 0) + (record.durationInSeconds ?? 86400)) * 1000).toISOString(),
+            upload_type: 1,
+          },
+          oxygen_data: data.oxygen_data,
+        };
+      },
+      ingest: publicApi.public.ingestDaily,
+      getId: (item) =>
+        (item as { summaryId?: string; calendarDate?: string }).summaryId ??
+        (item as { calendarDate?: string }).calendarDate ??
+        "unknown",
+      fetchData: (client, timeRange) => client.getPulseOx(timeRange),
+    });
+  },
+});
+
+/**
+ * Handle a webhook for Garmin respiration summaries (push or ping mode).
+ * Enriches daily records with respiration_data.
+ */
+export const handleGarminWebhookRespiration = action({
+  args: { payload: v.any() },
+  returns: webhookResultValidator,
+  handler: async (ctx, args) => {
+    return await processWebhookDualMode(ctx, {
+      items: args.payload as Array<{ userId: string; [k: string]: unknown }>,
+      type: "respiration",
+      transform: (item) => {
+        const record = item as { startTimeInSeconds?: number; durationInSeconds?: number };
+        const data = transformRespiration(item as never);
+        if (!data.respiration_data) return null;
+        return {
+          metadata: {
+            start_time: new Date((record.startTimeInSeconds ?? 0) * 1000).toISOString(),
+            end_time: new Date(((record.startTimeInSeconds ?? 0) + (record.durationInSeconds ?? 86400)) * 1000).toISOString(),
+            upload_type: 1,
+          },
+          respiration_data: data.respiration_data,
+        };
+      },
+      ingest: publicApi.public.ingestDaily,
+      getId: (item) =>
+        (item as { summaryId?: string }).summaryId ?? "unknown",
+      fetchData: (client, timeRange) => client.getRespiration(timeRange),
+    });
+  },
+});
+
+// ─── Webhook Internal Helper ─────────────────────────────────────────────────
+
+interface WebhookProcessConfig {
+  items: Array<{ userId: string; [k: string]: unknown }>;
+  type: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  transform: (item: unknown) => any;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ingest: any;
+  getId: (item: unknown) => string;
+}
+
+async function processWebhookPayload(
+  ctx: ActionContext,
+  config: WebhookProcessConfig,
+) {
+  const { items, type, transform, ingest, getId } = config;
+
+  let processed = 0;
+  const errors: Array<{ type: string; id: string; error: string }> = [];
+
+  if (!Array.isArray(items)) {
+    errors.push({ type, id: "payload", error: "Expected an array payload" });
+    return { processed, errors };
+  }
+
+  // Group items by Garmin userId
+  const byUser = new Map<string, Array<unknown>>();
+  for (const item of items) {
+    const garminUserId = item.userId;
+    if (!garminUserId) {
+      errors.push({ type, id: getId(item), error: "Missing userId in payload item" });
+      continue;
+    }
+    if (!byUser.has(garminUserId)) byUser.set(garminUserId, []);
+    byUser.get(garminUserId)!.push(item);
+  }
+
+  // Process each Garmin user's items
+  for (const [garminUserId, userItems] of byUser) {
+    const connection = await ctx.runQuery(
+      internalApi.private.getConnectionByProviderUserId,
+      { providerUserId: garminUserId, provider: "GARMIN" },
+    );
+
+    if (!connection) {
+      for (const item of userItems) {
+        errors.push({
+          type,
+          id: getId(item),
+          error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+        });
+      }
+      continue;
+    }
+
+    if (!connection.active) {
+      for (const item of userItems) {
+        errors.push({
+          type,
+          id: getId(item),
+          error: `Garmin connection for userId "${garminUserId}" is inactive`,
+        });
+      }
+      continue;
+    }
+
+    const connectionId = connection._id;
+    const userId = connection.userId;
+
+    for (const item of userItems) {
+      try {
+        const data = transform(item);
+        if (data == null) continue; // Skip items with no transformable data
+        await ctx.runMutation(ingest, {
+          connectionId,
+          userId,
+          ...data,
+        } as never);
+        processed++;
+      } catch (err) {
+        errors.push({
+          type,
+          id: getId(item),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // Update last data timestamp
+    await ctx.runMutation(publicApi.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+  }
+
+  return { processed, errors };
+}
+
+// ─── Ping Mode Support ───────────────────────────────────────────────────────
+// In ping mode, Garmin sends a lightweight notification instead of full data.
+// The handler fetches the actual data from the Garmin API using stored tokens.
+
+/**
+ * Detect whether a webhook payload is ping mode (notification only) vs push
+ * mode (full data). Ping payloads have `uploadStartTimeInSeconds` and very
+ * few keys; push payloads contain the full summary object.
+ */
+function isPingMode(
+  items: Array<{ [k: string]: unknown }>,
+): boolean {
+  if (items.length === 0) return false;
+  const item = items[0];
+  return (
+    "uploadStartTimeInSeconds" in item &&
+    "uploadEndTimeInSeconds" in item &&
+    Object.keys(item).length <= 6
+  );
+}
+
+interface WebhookDualModeConfig extends WebhookProcessConfig {
+  /** Fetch full records from the Garmin API (used in ping mode only). */
+  fetchData: (
+    client: GarminClient,
+    timeRange: { uploadStartTimeInSeconds: number; uploadEndTimeInSeconds: number },
+  ) => Promise<unknown[]>;
+}
+
+/**
+ * Process a webhook payload in either push or ping mode.
+ *
+ * - Push mode: items contain full data → transform and ingest directly.
+ * - Ping mode: items are notifications → fetch data from the API, then
+ *   transform and ingest.
+ */
+async function processWebhookDualMode(
+  ctx: ActionContext,
+  config: WebhookDualModeConfig,
+) {
+  const mode = isPingMode(config.items) ? "ping" : "push";
+  console.log(
+    `[garmin:webhook:${config.type}] mode=${mode} items=${config.items.length} payload:`,
+    JSON.stringify(config.items, null, 2),
+  );
+  if (mode === "ping") {
+    return await processWebhookPingPayload(ctx, config);
+  }
+  return await processWebhookPayload(ctx, config);
+}
+
+async function processWebhookPingPayload(
+  ctx: ActionContext,
+  config: WebhookDualModeConfig,
+) {
+  const { items, type, fetchData, transform, ingest, getId } = config;
+
+  let processed = 0;
+  const errors: Array<{ type: string; id: string; error: string }> = [];
+
+  if (!Array.isArray(items)) {
+    errors.push({ type, id: "payload", error: "Expected an array payload" });
+    return { processed, errors };
+  }
+
+  // Group by Garmin userId and merge time ranges
+  const byUser = new Map<
+    string,
+    { userAccessToken?: string; minStart: number; maxEnd: number }
+  >();
+  for (const item of items) {
+    const garminUserId = (item as { userId?: string }).userId;
+    if (!garminUserId) {
+      errors.push({ type, id: "unknown", error: "Missing userId in ping notification" });
+      continue;
+    }
+    const existing = byUser.get(garminUserId);
+    const start = (item as { uploadStartTimeInSeconds?: number }).uploadStartTimeInSeconds ?? 0;
+    const end = (item as { uploadEndTimeInSeconds?: number }).uploadEndTimeInSeconds ?? 0;
+    const token = (item as { userAccessToken?: string }).userAccessToken;
+    if (existing) {
+      existing.minStart = Math.min(existing.minStart, start);
+      existing.maxEnd = Math.max(existing.maxEnd, end);
+      if (token && !existing.userAccessToken) existing.userAccessToken = token;
+    } else {
+      byUser.set(garminUserId, { userAccessToken: token, minStart: start, maxEnd: end });
+    }
+  }
+
+  for (const [garminUserId, notification] of byUser) {
+    const connection = await ctx.runQuery(
+      internalApi.private.getConnectionByProviderUserId,
+      { providerUserId: garminUserId, provider: "GARMIN" },
+    );
+
+    if (!connection) {
+      errors.push({
+        type,
+        id: "ping",
+        error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+      });
+      continue;
+    }
+    if (!connection.active) {
+      errors.push({
+        type,
+        id: "ping",
+        error: `Garmin connection for userId "${garminUserId}" is inactive`,
+      });
+      continue;
+    }
+
+    const connectionId = connection._id;
+    const userId = connection.userId;
+
+    // Resolve a valid access token: prefer stored (with refresh), fall back to notification
+    let accessToken: string | null = null;
+    const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
+      connectionId,
+    });
+    if (tokenDoc) {
+      accessToken = tokenDoc.accessToken;
+      const nowSeconds = Math.floor(Date.now() / 1000);
+      if (
+        tokenDoc.expiresAt &&
+        tokenDoc.refreshToken &&
+        nowSeconds >= tokenDoc.expiresAt - REFRESH_BUFFER_SECONDS
+      ) {
+        const clientId = process.env.GARMIN_CLIENT_ID;
+        const clientSecret = process.env.GARMIN_CLIENT_SECRET;
+        if (clientId && clientSecret) {
+          try {
+            const refreshed = await refreshToken({
+              clientId,
+              clientSecret,
+              refreshToken: tokenDoc.refreshToken,
+            });
+            accessToken = refreshed.access_token;
+            await ctx.runMutation(internalApi.garmin.storeTokens, {
+              connectionId,
+              accessToken: refreshed.access_token,
+              refreshToken: refreshed.refresh_token,
+              expiresAt: nowSeconds + refreshed.expires_in,
+            });
+          } catch {
+            // Refresh failed — fall through to notification token
+          }
+        }
+      }
+    }
+    if (!accessToken) {
+      accessToken = notification.userAccessToken ?? null;
+    }
+    if (!accessToken) {
+      errors.push({
+        type,
+        id: "ping",
+        error: `No access token available for Garmin userId "${garminUserId}"`,
+      });
+      continue;
+    }
+
+    const client = new GarminClient({ accessToken });
+
+    // Use the merged time range from all notifications for this user
+    let { minStart, maxEnd } = notification;
+    if (minStart === 0 && maxEnd === 0) {
+      const now = Math.floor(Date.now() / 1000);
+      minStart = now - 86400;
+      maxEnd = now;
+    }
+
+    try {
+      const records = await fetchData(client, {
+        uploadStartTimeInSeconds: minStart,
+        uploadEndTimeInSeconds: maxEnd,
+      });
+
+      for (const record of records) {
+        try {
+          const data = transform(record);
+          if (data == null) continue;
+          await ctx.runMutation(ingest, {
+            connectionId,
+            userId,
+            ...data,
+          } as never);
+          processed++;
+        } catch (err) {
+          errors.push({
+            type,
+            id: getId(record),
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    } catch (err) {
+      errors.push({
+        type,
+        id: "fetch",
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    await ctx.runMutation(publicApi.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+  }
+
+  return { processed, errors };
+}
+
 // ─── Internal Helpers ────────────────────────────────────────────────────────
 
 interface SyncAllConfig {
@@ -716,7 +1376,7 @@ interface SyncAllConfig {
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type ActionContext = { runMutation: (ref: any, args: any) => Promise<any> };
+type ActionContext = { runMutation: (ref: any, args: any) => Promise<any>; runQuery: (ref: any, args: any) => Promise<any> };
 
 async function syncAllTypes(
   ctx: ActionContext,
@@ -725,7 +1385,11 @@ async function syncAllTypes(
 ) {
   const { connectionId, userId, timeRange } = config;
 
-  const synced = { activities: 0, dailies: 0, sleep: 0, body: 0, menstruation: 0 };
+  const synced = {
+    activities: 0, dailies: 0, sleep: 0, body: 0, menstruation: 0,
+    bloodPressures: 0, skinTemp: 0, userMetrics: 0,
+    hrv: 0, stressDetails: 0, pulseOx: 0, respiration: 0,
+  };
   const errors: Array<{ type: string; id: string; error: string }> = [];
 
   // ── Activities ──────────────────────────────────────────────────────────
@@ -771,7 +1435,7 @@ async function syncAllTypes(
       } catch (err) {
         errors.push({
           type: "daily",
-          id: daily.summaryId ?? daily.calendarDate,
+          id: daily.summaryId ?? daily.calendarDate ?? "unknown",
           error: err instanceof Error ? err.message : String(err),
         });
       }
@@ -799,7 +1463,7 @@ async function syncAllTypes(
       } catch (err) {
         errors.push({
           type: "sleep",
-          id: sleep.summaryId ?? sleep.calendarDate,
+          id: sleep.summaryId ?? sleep.calendarDate ?? "unknown",
           error: err instanceof Error ? err.message : String(err),
         });
       }
@@ -855,7 +1519,7 @@ async function syncAllTypes(
       } catch (err) {
         errors.push({
           type: "menstruation",
-          id: record.summaryId ?? record.calendarDate,
+          id: record.summaryId ?? record.periodStartDate ?? "unknown",
           error: err instanceof Error ? err.message : String(err),
         });
       }
@@ -868,5 +1532,191 @@ async function syncAllTypes(
     });
   }
 
+  // ── Blood Pressures (→ body) ───────────────────────────────────────────
+  try {
+    const bpRecords = await client.getBloodPressures(timeRange);
+    for (const bp of bpRecords) {
+      try {
+        const data = transformBloodPressure(bp);
+        await ctx.runMutation(publicApi.public.ingestBody, {
+          connectionId, userId, ...data,
+        } as never);
+        synced.bloodPressures++;
+      } catch (err) {
+        errors.push({
+          type: "bloodPressure",
+          id: bp.summaryId ?? String(bp.measurementTimeInSeconds),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "bloodPressure", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
+  // ── Skin Temperature (→ body) ──────────────────────────────────────────
+  try {
+    const skinRecords = await client.getSkinTemperature(timeRange);
+    for (const skin of skinRecords) {
+      try {
+        const data = transformSkinTemp(skin);
+        await ctx.runMutation(publicApi.public.ingestBody, {
+          connectionId, userId, ...data,
+        } as never);
+        synced.skinTemp++;
+      } catch (err) {
+        errors.push({
+          type: "skinTemp",
+          id: skin.summaryId ?? skin.calendarDate ?? "unknown",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "skinTemp", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
+  // ── User Metrics (→ body) ──────────────────────────────────────────────
+  try {
+    const metricsRecords = await client.getUserMetrics(timeRange);
+    for (const metrics of metricsRecords) {
+      try {
+        const data = transformUserMetrics(metrics);
+        await ctx.runMutation(publicApi.public.ingestBody, {
+          connectionId, userId, ...data,
+        } as never);
+        synced.userMetrics++;
+      } catch (err) {
+        errors.push({
+          type: "userMetrics",
+          id: metrics.summaryId ?? metrics.calendarDate ?? "unknown",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "userMetrics", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
+  // ── HRV (enriches daily) ──────────────────────────────────────────────
+  try {
+    const hrvRecords = await client.getHRV(timeRange);
+    for (const hrv of hrvRecords) {
+      try {
+        const data = transformHRV(hrv);
+        if (data.heart_rate_data) {
+          await ctx.runMutation(publicApi.public.ingestDaily, {
+            connectionId, userId,
+            metadata: {
+              start_time: new Date((hrv.startTimeInSeconds ?? 0) * 1000).toISOString(),
+              end_time: new Date(((hrv.startTimeInSeconds ?? 0) + (hrv.durationInSeconds ?? 86400)) * 1000).toISOString(),
+              upload_type: 1,
+            },
+            heart_rate_data: data.heart_rate_data,
+          } as never);
+          synced.hrv++;
+        }
+      } catch (err) {
+        errors.push({
+          type: "hrv",
+          id: hrv.summaryId ?? hrv.calendarDate ?? "unknown",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "hrv", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
+  // ── Stress Details (enriches daily) ────────────────────────────────────
+  try {
+    const stressRecords = await client.getStressDetails(timeRange);
+    for (const stress of stressRecords) {
+      try {
+        const data = transformStressDetails(stress);
+        if (data.stress_data) {
+          await ctx.runMutation(publicApi.public.ingestDaily, {
+            connectionId, userId,
+            metadata: {
+              start_time: new Date((stress.startTimeInSeconds ?? 0) * 1000).toISOString(),
+              end_time: new Date(((stress.startTimeInSeconds ?? 0) + (stress.durationInSeconds ?? 86400)) * 1000).toISOString(),
+              upload_type: 1,
+            },
+            stress_data: data.stress_data,
+          } as never);
+          synced.stressDetails++;
+        }
+      } catch (err) {
+        errors.push({
+          type: "stressDetails",
+          id: stress.summaryId ?? stress.calendarDate ?? "unknown",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "stressDetails", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
+  // ── Pulse Ox (enriches daily) ──────────────────────────────────────────
+  try {
+    const pulseOxRecords = await client.getPulseOx(timeRange);
+    for (const po of pulseOxRecords) {
+      try {
+        const data = transformPulseOx(po);
+        if (data.oxygen_data) {
+          await ctx.runMutation(publicApi.public.ingestDaily, {
+            connectionId, userId,
+            metadata: {
+              start_time: new Date((po.startTimeInSeconds ?? 0) * 1000).toISOString(),
+              end_time: new Date(((po.startTimeInSeconds ?? 0) + (po.durationInSeconds ?? 86400)) * 1000).toISOString(),
+              upload_type: 1,
+            },
+            oxygen_data: data.oxygen_data,
+          } as never);
+          synced.pulseOx++;
+        }
+      } catch (err) {
+        errors.push({
+          type: "pulseOx",
+          id: po.summaryId ?? po.calendarDate ?? "unknown",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "pulseOx", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
+  // ── Respiration (enriches daily) ───────────────────────────────────────
+  try {
+    const respRecords = await client.getRespiration(timeRange);
+    for (const resp of respRecords) {
+      try {
+        const data = transformRespiration(resp);
+        if (data.respiration_data) {
+          await ctx.runMutation(publicApi.public.ingestDaily, {
+            connectionId, userId,
+            metadata: {
+              start_time: new Date((resp.startTimeInSeconds ?? 0) * 1000).toISOString(),
+              end_time: new Date(((resp.startTimeInSeconds ?? 0) + (resp.durationInSeconds ?? 86400)) * 1000).toISOString(),
+              upload_type: 1,
+            },
+            respiration_data: data.respiration_data,
+          } as never);
+          synced.respiration++;
+        }
+      } catch (err) {
+        errors.push({
+          type: "respiration",
+          id: resp.summaryId ?? "unknown",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({ type: "respiration", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+  }
+
   return { synced, errors };
 }