@nativesquare/soma 0.7.3 → 0.9.0

package/src/component/garmin/private.ts

@@ -0,0 +1,1798 @@
+// ─── Garmin Internal Mutations ───────────────────────────────────────────────
+// Token CRUD and pending OAuth state management.
+// Called only from garmin/public.ts and garmin/webhooks.ts.
+
+import { v } from "convex/values";
+import {
+  internalAction,
+  internalMutation,
+  internalQuery,
+} from "../_generated/server";
+import { internal } from "../_generated/api";
+import {
+  garminActivityPingPayloadSchema,
+  garminActivityPushPayloadSchema,
+} from "./schemas/activity.js";
+import {
+  garminActivityDetailsPingPayloadSchema,
+  garminActivityDetailsPushPayloadSchema,
+} from "./schemas/activityDetails.js";
+import {
+  garminManuallyUpdatedActivitiesPingPayloadSchema,
+  garminManuallyUpdatedActivitiesPushPayloadSchema,
+} from "./schemas/manuallyUpdatedActivities.js";
+import {
+  garminMoveIQPingPayloadSchema,
+  garminMoveIQPushPayloadSchema,
+} from "./schemas/moveIQ.js";
+import {
+  garminBloodPressurePingPayloadSchema,
+  garminBloodPressurePushPayloadSchema,
+} from "./schemas/bloodPressure.js";
+import {
+  garminBodyCompositionsPingPayloadSchema,
+  garminBodyCompositionsPushPayloadSchema,
+} from "./schemas/bodyCompositions.js";
+import {
+  garminDailiesPingPayloadSchema,
+  garminDailiesPushPayloadSchema,
+} from "./schemas/dailies.js";
+import {
+  garminHealthSnapshotPingPayloadSchema,
+  garminHealthSnapshotPushPayloadSchema,
+} from "./schemas/healthSnapshot.js";
+import {
+  garminHRVSummaryPingPayloadSchema,
+  garminHRVSummaryPushPayloadSchema,
+} from "./schemas/hrvSummary.js";
+import {
+  garminEpochPingPayloadSchema,
+  garminEpochPushPayloadSchema,
+} from "./schemas/epochs.js";
+import {
+  garminPulseOxPingPayloadSchema,
+  garminPulseOxPushPayloadSchema,
+} from "./schemas/pulseOx.js";
+import {
+  garminRespirationPingPayloadSchema,
+  garminRespirationPushPayloadSchema,
+} from "./schemas/respiration.js";
+import {
+  garminSkinTemperaturePingPayloadSchema,
+  garminSkinTemperaturePushPayloadSchema,
+} from "./schemas/skinTemperature.js";
+import {
+  garminStressPingPayloadSchema,
+  garminStressPushPayloadSchema,
+} from "./schemas/stress.js";
+import {
+  garminSleepsPingPayloadSchema,
+  garminSleepsPushPayloadSchema,
+} from "./schemas/sleeps.js";
+import { transformActivity } from "./transform/activity.js";
+import { transformActivityDetails } from "./transform/activityDetails.js";
+import { transformManuallyUpdatedActivity } from "./transform/manuallyUpdatedActivities.js";
+import { transformMoveIQ } from "./transform/moveIQ.js";
+import { transformBloodPressure } from "./transform/bloodPressure.js";
+import { transformBodyComposition } from "./transform/bodyCompositions.js";
+import { transformDailies } from "./transform/dailies.js";
+import { transformEpoch } from "./transform/epochs.js";
+import { transformHealthSnapshot } from "./transform/healthSnapshot.js";
+import { transformHRVSummary } from "./transform/hrvSummary.js";
+import { transformPulseOx } from "./transform/pulseOx.js";
+import { transformRespiration } from "./transform/respiration.js";
+import { transformSkinTemperature } from "./transform/skinTemperature.js";
+import { transformSleeps } from "./transform/sleeps.js";
+import { transformStress } from "./transform/stress.js";
+import {
+  garminUserMetricsPingPayloadSchema,
+  garminUserMetricsPushPayloadSchema,
+} from "./schemas/userMetrics.js";
+import { transformUserMetrics } from "./transform/userMetrics.js";
+import {
+  garminMenstrualCycleTrackingPingPayloadSchema,
+  garminMenstrualCycleTrackingPushPayloadSchema,
+} from "./schemas/menstrualCycleTracking.js";
+import { transformMenstrualCycleTracking } from "./transform/menstrualCycleTracking.js";
+// ─── Internal Pending OAuth CRUD ─────────────────────────────────────────────
+// Temporary storage for in-progress Garmin OAuth 2.0 PKCE flows.
+// Bridges getGarminAuthUrl and completeGarminOAuth.
+
+export const storePendingOAuth = internalMutation({
+  args: {
+    provider: v.string(),
+    state: v.string(),
+    codeVerifier: v.string(),
+    userId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.insert("pendingOAuth", {
+      ...args,
+      createdAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+export const getPendingOAuth = internalQuery({
+  args: { state: v.string() },
+  returns: v.union(
+    v.object({
+      _id: v.id("pendingOAuth"),
+      _creationTime: v.number(),
+      provider: v.string(),
+      state: v.string(),
+      codeVerifier: v.string(),
+      userId: v.string(),
+      createdAt: v.number(),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("pendingOAuth")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .first();
+  },
+});
+
+export const deletePendingOAuth = internalMutation({
+  args: { state: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const pending = await ctx.db
+      .query("pendingOAuth")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .first();
+    if (pending) {
+      await ctx.db.delete(pending._id);
+    }
+    return null;
+  },
+});
+
+// ─── Internal Token CRUD ─────────────────────────────────────────────────────
+
+/**
+ * Store OAuth 2.0 tokens for a Garmin connection.
+ * Upserts by connectionId — one token record per connection.
+ */
+export const storeTokens = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    accessToken: v.string(),
+    refreshToken: v.string(),
+    expiresAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        accessToken: args.accessToken,
+        refreshToken: args.refreshToken,
+        expiresAt: args.expiresAt,
+      });
+      return null;
+    }
+
+    await ctx.db.insert("providerTokens", {
+      connectionId: args.connectionId,
+      accessToken: args.accessToken,
+      refreshToken: args.refreshToken,
+      expiresAt: args.expiresAt,
+    });
+    return null;
+  },
+});
+
+/**
+ * Get stored tokens for a connection.
+ */
+export const getTokens = internalQuery({
+  args: { connectionId: v.id("connections") },
+  returns: v.union(
+    v.object({
+      _id: v.id("providerTokens"),
+      _creationTime: v.number(),
+      connectionId: v.id("connections"),
+      accessToken: v.string(),
+      refreshToken: v.optional(v.string()),
+      expiresAt: v.optional(v.number()),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+  },
+});
+
+/**
+ * Delete stored tokens for a connection.
+ */
+export const deleteTokens = internalMutation({
+  args: { connectionId: v.id("connections") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.delete(existing._id);
+    }
+    return null;
+  },
+});
+
+// ─── Activity Push Processing ───────────────────────────────────────────────
+
+/**
+ * Process a Garmin activity push payload.
+ * Parses the full activity data, groups by user, resolves connections,
+ * transforms, and ingests each activity.
+ */
+export const processActivityPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { activities } = garminActivityPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof activities>();
+    for (const item of activities) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "activity",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "activity",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformActivity(item);
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "activity",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Activity Ping Processing ──────────────────────────────────────────────
+
+/**
+ * Process a Garmin activity ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processActivityPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { activities } = garminActivityPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:activities] Ping mode not yet implemented, acknowledging ${activities.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Activity Details Push Processing ─────────────────────────────────────
+
+/**
+ * Process a Garmin activity details push payload.
+ * Parses the full activity detail data (summary + samples + laps),
+ * groups by user, resolves connections, transforms, and ingests each activity.
+ */
+export const processActivityDetailsPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { activityDetails } =
+      garminActivityDetailsPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof activityDetails>();
+    for (const item of activityDetails) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "activityDetails",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "activityDetails",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformActivityDetails(item);
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "activityDetails",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Activity Details Ping Processing ─────────────────────────────────────
+
+/**
+ * Process a Garmin activity details ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processActivityDetailsPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { activityDetails } =
+      garminActivityDetailsPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:activityDetails] Ping mode not yet implemented, acknowledging ${activityDetails.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Manually Updated Activities Push Processing ────────────────────────────
+
+/**
+ * Process a Garmin manually updated activities push payload.
+ * Parses the full activity data, groups by user, resolves connections,
+ * transforms, and ingests each activity.
+ */
+export const processManuallyUpdatedActivitiesPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { manuallyUpdatedActivities } =
+      garminManuallyUpdatedActivitiesPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof manuallyUpdatedActivities>();
+    for (const item of manuallyUpdatedActivities) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "manuallyUpdatedActivities",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "manuallyUpdatedActivities",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformManuallyUpdatedActivity(item);
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "manuallyUpdatedActivities",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Manually Updated Activities Ping Processing ────────────────────────────
+
+/**
+ * Process a Garmin manually updated activities ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processManuallyUpdatedActivitiesPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { manuallyUpdatedActivities } =
+      garminManuallyUpdatedActivitiesPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:manuallyUpdatedActivities] Ping mode not yet implemented, acknowledging ${manuallyUpdatedActivities.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Move IQ Push Processing ──────────────────────────────────────────────
+
+/**
+ * Process a Garmin Move IQ push payload.
+ * Parses the auto-detected activity events, groups by user, resolves
+ * connections, transforms, and ingests each event as an activity.
+ */
+export const processMoveIQPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { moveIQActivities } = garminMoveIQPushPayloadSchema.parse(
+      args.payload,
+    );
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof moveIQActivities>();
+    for (const item of moveIQActivities) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "moveIQ",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "moveIQ",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformMoveIQ(item);
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "moveIQ",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Move IQ Ping Processing ─────────────────────────────────────────────
+
+/**
+ * Process a Garmin Move IQ ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processMoveIQPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { moveIQActivities } = garminMoveIQPingPayloadSchema.parse(
+      args.payload,
+    );
+    console.log(
+      `[garmin:webhook:moveIQ] Ping mode not yet implemented, acknowledging ${moveIQActivities.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Blood Pressure Push Processing ─────────────────────────────────────────
+
+/**
+ * Process a Garmin blood pressure push payload.
+ * Parses the full blood pressure data, groups by user, resolves connections,
+ * transforms, and ingests each record into the body table.
+ */
+export const processBloodPressurePushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { bloodPressures } =
+      garminBloodPressurePushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof bloodPressures>();
+    for (const item of bloodPressures) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "bloodPressure",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "bloodPressure",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformBloodPressure(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "bloodPressure",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Blood Pressure Ping Processing ─────────────────────────────────────────
+
+/**
+ * Process a Garmin blood pressure ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processBloodPressurePingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { bloodPressures } =
+      garminBloodPressurePingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:bloodPressures] Ping mode not yet implemented, acknowledging ${bloodPressures.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Body Compositions Push Processing ─────────────────────────────────────
+
+/**
+ * Process a Garmin body compositions push payload.
+ * Parses the full body composition data, groups by user, resolves connections,
+ * transforms, and ingests each record into the body table.
+ */
+export const processBodyCompositionsPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { bodyComps } =
+      garminBodyCompositionsPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof bodyComps>();
+    for (const item of bodyComps) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "bodyCompositions",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "bodyCompositions",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformBodyComposition(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "bodyCompositions",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Body Compositions Ping Processing ─────────────────────────────────────
+
+/**
+ * Process a Garmin body compositions ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processBodyCompositionsPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { bodyComps } =
+      garminBodyCompositionsPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:bodyCompositions] Ping mode not yet implemented, acknowledging ${bodyComps.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Dailies Push Processing ──────────────────────────────────────────────
+
+/**
+ * Process a Garmin dailies push payload.
+ * Parses the full daily summary data, groups by user, resolves connections,
+ * transforms, and ingests each record into the daily table.
+ */
+export const processDailiesPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { dailies } =
+      garminDailiesPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof dailies>();
+    for (const item of dailies) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "dailies",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "dailies",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformDailies(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "dailies",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Dailies Ping Processing ──────────────────────────────────────────────
+
+/**
+ * Process a Garmin dailies ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processDailiesPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { dailies } =
+      garminDailiesPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:dailies] Ping mode not yet implemented, acknowledging ${dailies.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Health Snapshot Push Processing ────────────────────────────────────────
+
+/**
+ * Process a Garmin health snapshot push payload.
+ * Parses the full health snapshot data, groups by user, resolves connections,
+ * transforms, and ingests each record into the daily table.
+ */
+export const processHealthSnapshotPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { healthSnapshot } =
+      garminHealthSnapshotPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof healthSnapshot>();
+    for (const item of healthSnapshot) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "healthSnapshot",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "healthSnapshot",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformHealthSnapshot(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "healthSnapshot",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Health Snapshot Ping Processing ────────────────────────────────────────
+
+/**
+ * Process a Garmin health snapshot ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processHealthSnapshotPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { healthSnapshot } =
+      garminHealthSnapshotPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:healthSnapshot] Ping mode not yet implemented, acknowledging ${healthSnapshot.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── HRV Summary Push Processing ────────────────────────────────────────────
+
+/**
+ * Process a Garmin HRV summary push payload.
+ * Parses the full HRV summary data, groups by user, resolves connections,
+ * transforms, and ingests each record into the daily table.
+ */
+export const processHRVSummaryPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { hrv } =
+      garminHRVSummaryPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof hrv>();
+    for (const item of hrv) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "hrvSummary",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "hrvSummary",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformHRVSummary(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "hrvSummary",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── HRV Summary Ping Processing ────────────────────────────────────────────
+
+/**
+ * Process a Garmin HRV summary ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processHRVSummaryPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { hrv } =
+      garminHRVSummaryPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:hrvSummary] Ping mode not yet implemented, acknowledging ${hrv.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Epoch Push Processing ──────────────────────────────────────────────────
+
+/**
+ * Process a Garmin epoch push payload.
+ * Parses the full epoch summary data (15-min wellness slices), groups by user,
+ * resolves connections, transforms, and ingests each record into the daily table.
+ */
+export const processEpochPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { epochs } =
+      garminEpochPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof epochs>();
+    for (const item of epochs) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "epochs",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "epochs",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformEpoch(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "epochs",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Epoch Ping Processing ──────────────────────────────────────────────────
+
+/**
+ * Process a Garmin epoch ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processEpochPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { epochs } =
+      garminEpochPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:epochs] Ping mode not yet implemented, acknowledging ${epochs.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Pulse Ox Push Processing ──────────────────────────────────────────────
+
+/**
+ * Process a Garmin Pulse Ox push payload.
+ * Parses the full SpO2 data, groups by user, resolves connections,
+ * transforms, and ingests each record into the daily table.
+ */
+export const processPulseOxPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { pulseox } =
+      garminPulseOxPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof pulseox>();
+    for (const item of pulseox) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "pulseOx",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "pulseOx",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformPulseOx(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "pulseOx",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Pulse Ox Ping Processing ──────────────────────────────────────────────
+
+/**
+ * Process a Garmin Pulse Ox ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processPulseOxPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { pulseox } =
+      garminPulseOxPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:pulseOx] Ping mode not yet implemented, acknowledging ${pulseox.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Respiration Push Processing ──────────────────────────────────────────
+
+/**
+ * Process a Garmin Respiration push payload.
+ * Parses the full breathing rate data, groups by user, resolves connections,
+ * transforms, and ingests each record into the daily table.
+ */
+export const processRespirationPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { allDayRespiration } =
+      garminRespirationPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof allDayRespiration>();
+    for (const item of allDayRespiration) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "respiration",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "respiration",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformRespiration(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "respiration",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Respiration Ping Processing ──────────────────────────────────────────
+
+/**
+ * Process a Garmin Respiration ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processRespirationPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { allDayRespiration } =
+      garminRespirationPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:respiration] Ping mode not yet implemented, acknowledging ${allDayRespiration.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Stress Details Push Processing ──────────────────────────────────────────
+
+/**
+ * Process a Garmin stress details push payload.
+ * Parses the full stress data, groups by user, resolves connections,
+ * transforms, and ingests each record into the daily table.
+ */
+export const processStressPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { stressDetails } =
+      garminStressPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof stressDetails>();
+    for (const item of stressDetails) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "stressDetails",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "stressDetails",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformStress(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "stressDetails",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Stress Details Ping Processing ─────────────────────────────────────────
+
+/**
+ * Process a Garmin stress details ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processStressPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { stressDetails } =
+      garminStressPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:stressDetails] Ping mode not yet implemented, acknowledging ${stressDetails.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Skin Temperature Push Processing ───────────────────────────────────────
+
+/**
+ * Process a Garmin skin temperature push payload.
+ * Parses the full skin temperature data, groups by user, resolves connections,
+ * transforms, and ingests each record into the body table.
+ */
+export const processSkinTemperaturePushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { skinTemp } =
+      garminSkinTemperaturePushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof skinTemp>();
+    for (const item of skinTemp) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "skinTemperature",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "skinTemperature",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformSkinTemperature(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "skinTemperature",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Skin Temperature Ping Processing ───────────────────────────────────────
+
+/**
+ * Process a Garmin skin temperature ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processSkinTemperaturePingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { skinTemp } =
+      garminSkinTemperaturePingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:skinTemperature] Ping mode not yet implemented, acknowledging ${skinTemp.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Sleeps Push Processing ─────────────────────────────────────────────────
+
+/**
+ * Process a Garmin sleep summary push payload.
+ * Parses the full sleep data, groups by user, resolves connections,
+ * transforms, and ingests each sleep record.
+ */
+export const processSleepsPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { sleeps } = garminSleepsPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof sleeps>();
+    for (const item of sleeps) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "sleep",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "sleep",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformSleeps(item);
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "sleep",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Sleeps Ping Processing ─────────────────────────────────────────────────
+
+/**
+ * Process a Garmin sleep summary ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processSleepsPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { sleeps } = garminSleepsPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:sleeps] Ping mode not yet implemented, acknowledging ${sleeps.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── User Metrics Push Processing ──────────────────────────────────────────
+
+/**
+ * Process a Garmin user metrics push payload.
+ * Parses the full user metrics data, groups by user, resolves connections,
+ * transforms, and ingests each user metrics record.
+ */
+export const processUserMetricsPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { userMetrics } =
+      garminUserMetricsPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof userMetrics>();
+    for (const item of userMetrics) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "userMetrics",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "userMetrics",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformUserMetrics(item);
+          if (data == null) continue;
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "userMetrics",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── User Metrics Ping Processing ──────────────────────────────────────────
+
+/**
+ * Process a Garmin user metrics ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processUserMetricsPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { userMetrics } =
+      garminUserMetricsPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:userMetrics] Ping mode not yet implemented, acknowledging ${userMetrics.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+
+// ─── Menstrual Cycle Tracking Push Processing ───────────────────────────────
+
+/**
+ * Process a Garmin MCT (Women's Health API) push payload.
+ * Parses full MCT summary data, groups by user, resolves connections,
+ * transforms, and ingests each record into the menstruation table.
+ */
+export const processMenstrualCycleTrackingPushPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (ctx, args) => {
+    const { mct } =
+      garminMenstrualCycleTrackingPushPayloadSchema.parse(args.payload);
+
+    const items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }> = [];
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    // Group items by Garmin userId
+    const byUser = new Map<string, typeof mct>();
+    for (const item of mct) {
+      const existing = byUser.get(item.userId);
+      if (existing) {
+        existing.push(item);
+      } else {
+        byUser.set(item.userId, [item]);
+      }
+    }
+
+    for (const [garminUserId, userItems] of byUser) {
+      const connection = await ctx.runQuery(
+        internal.private.getConnectionByProviderUserId,
+        { providerUserId: garminUserId, provider: "GARMIN" },
+      );
+
+      if (!connection) {
+        for (const item of userItems) {
+          errors.push({
+            type: "menstrualCycleTracking",
+            id: item.summaryId ?? "unknown",
+            error: `No Soma connection found for Garmin userId "${garminUserId}"`,
+          });
+        }
+        continue;
+      }
+
+      if (!connection.active) {
+        for (const item of userItems) {
+          errors.push({
+            type: "menstrualCycleTracking",
+            id: item.summaryId ?? "unknown",
+            error: `Garmin connection for userId "${garminUserId}" is inactive`,
+          });
+        }
+        continue;
+      }
+
+      for (const item of userItems) {
+        try {
+          const data = transformMenstrualCycleTracking(item);
+          items.push({ connectionId: connection._id, userId: connection.userId, data });
+        } catch (err) {
+          errors.push({
+            type: "menstrualCycleTracking",
+            id: item.summaryId ?? "unknown",
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+
+    return { items, errors };
+  },
+});
+
+// ─── Menstrual Cycle Tracking Ping Processing ───────────────────────────────
+
+/**
+ * Process a Garmin MCT ping payload.
+ * Stub — acknowledges the notification without fetching data.
+ */
+export const processMenstrualCycleTrackingPingPayload = internalAction({
+  args: { payload: v.any() },
+  handler: async (_ctx, args) => {
+    const { mct } =
+      garminMenstrualCycleTrackingPingPayloadSchema.parse(args.payload);
+    console.log(
+      `[garmin:webhook:menstrualCycleTracking] Ping mode not yet implemented, acknowledging ${mct.length} items`,
+    );
+    return { processed: 0, errors: [] };
+  },
+});
+