@nativesquare/soma 0.11.0 → 0.13.0

package/src/component/garmin/webhooks.ts

@@ -1,858 +1,899 @@
-// ─── Garmin 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.
-
-import { v } from "convex/values";
-import { action, type ActionCtx } from "../_generated/server";
-import { api, internal } from "../_generated/api";
-import {
-  garminSkinTemperaturePingPayloadSchema,
-  garminSkinTemperaturePushPayloadSchema,
-} from "./schemas/skinTemperature.js";
-import {
-  garminSleepsPingPayloadSchema,
-  garminSleepsPushPayloadSchema,
-} from "./schemas/sleeps.js";
-import {
-  garminStressPingPayloadSchema,
-  garminStressPushPayloadSchema,
-} from "./schemas/stress.js";
-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 {
-  garminEpochPingPayloadSchema,
-  garminEpochPushPayloadSchema,
-} from "./schemas/epochs.js";
-import {
-  garminHealthSnapshotPingPayloadSchema,
-  garminHealthSnapshotPushPayloadSchema,
-} from "./schemas/healthSnapshot.js";
-import {
-  garminHRVSummaryPingPayloadSchema,
-  garminHRVSummaryPushPayloadSchema,
-} from "./schemas/hrvSummary.js";
-import {
-  garminPulseOxPingPayloadSchema,
-  garminPulseOxPushPayloadSchema,
-} from "./schemas/pulseOx.js";
-import {
-  garminRespirationPingPayloadSchema,
-  garminRespirationPushPayloadSchema,
-} from "./schemas/respiration.js";
-import {
-  garminUserMetricsPingPayloadSchema,
-  garminUserMetricsPushPayloadSchema,
-} from "./schemas/userMetrics.js";
-import {
-  garminMenstrualCycleTrackingPingPayloadSchema,
-  garminMenstrualCycleTrackingPushPayloadSchema,
-} from "./schemas/menstrualCycleTracking.js";
-
-/**
- * Discriminate push vs ping webhook payloads.
- *
- * Per the Garmin Activity API docs:
- *   - Ping items always carry `callbackURL` (absent only for deregistrations)
- *   - Push items never carry `callbackURL`, they contain the full summary data
- *
- * Zod schema validation alone can't distinguish the two because both schemas
- * have all-optional fields and would accept either payload shape.
- */
-function isWebhookPushMode(payload: unknown): boolean {
-  if (payload == null || typeof payload !== "object") return false;
-
-  // The payload is either a keyed object like { activities: [...] }
-  // or a flat array of items. Extract the first item either way.
-  let firstItem: unknown;
-  if (Array.isArray(payload)) {
-    firstItem = payload[0];
-  } else {
-    const key = Object.keys(payload)[0];
-    const list = (payload as Record<string, unknown>)[key];
-    firstItem = Array.isArray(list) ? list[0] : undefined;
-  }
-
-  if (firstItem == null || typeof firstItem !== "object") return false;
-  return !("callbackURL" in firstItem);
-}
-
-type WebhookResult = {
-  processed: number;
-  errors: Array<{ type: string; id: string; error: string }>;
-  affectedUsers: Array<{ userId: string; connectionId: string }>;
-};
-
-type ProcessResult = {
-  items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }>;
-  errors: Array<{ type: string; id: string; error: string }>;
-};
-
-/**
- * Ingest transformed items from a private handler and update connections.
- * Shared orchestration logic for all push-mode webhook handlers.
- */
-async function ingestAndUpdate(
-  ctx: ActionCtx,
-  result: ProcessResult,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ingestMutation: any,
-): Promise<WebhookResult> {
-  let processed = 0;
-  const errors = [...result.errors];
-  const connectionsToUpdate = new Set<string>();
-  const userMap = new Map<string, { userId: string; connectionId: string }>();
-
-  for (const item of result.items) {
-    try {
-      await ctx.runMutation(ingestMutation, {
-        connectionId: item.connectionId,
-        userId: item.userId,
-        ...item.data,
-      } as never);
-      processed++;
-      connectionsToUpdate.add(item.connectionId);
-      userMap.set(`${item.userId}:${item.connectionId}`, {
-        userId: item.userId,
-        connectionId: item.connectionId,
-      });
-    } catch (err) {
-      errors.push({
-        type: "ingest",
-        id: "unknown",
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-  }
-
-  for (const connectionId of connectionsToUpdate) {
-    await ctx.runMutation(api.public.updateConnection, {
-      connectionId,
-      lastDataUpdate: new Date().toISOString(),
-    } as never);
-  }
-
-  return { processed, errors, affectedUsers: [...userMap.values()] };
-}
-
-// ─── Webhook Handlers ────────────────────────────────────────────────────────
-
-/**
- * Handle a webhook for Garmin activities (push or ping mode).
- */
-export const handleGarminWebhookActivities = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult = garminActivityPushPayloadSchema.safeParse(args.payload);
-      if (pushResult.success && pushResult.data.activities.length > 0) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processActivityPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
-      }
-    } else {
-      const pingResult = garminActivityPingPayloadSchema.safeParse(args.payload);
-      if (pingResult.success && pingResult.data.activities.length > 0) {
-        return await ctx.runAction(
-          internal.garmin.private.processActivityPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:activities] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin activity details (push or ping mode).
- */
-export const handleGarminWebhookActivityDetails = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminActivityDetailsPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.activityDetails.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processActivityDetailsPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
-      }
-    } else {
-      const pingResult =
-        garminActivityDetailsPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.activityDetails.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processActivityDetailsPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:activityDetails] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin manually updated activities (push or ping mode).
- */
-export const handleGarminWebhookManuallyUpdatedActivities = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminManuallyUpdatedActivitiesPushPayloadSchema.safeParse(
-          args.payload,
-        );
-      if (
-        pushResult.success &&
-        pushResult.data.manuallyUpdatedActivities.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private
-            .processManuallyUpdatedActivitiesPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
-      }
-    } else {
-      const pingResult =
-        garminManuallyUpdatedActivitiesPingPayloadSchema.safeParse(
-          args.payload,
-        );
-      if (
-        pingResult.success &&
-        pingResult.data.manuallyUpdatedActivities.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private
-            .processManuallyUpdatedActivitiesPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:manuallyUpdatedActivities] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin Move IQ auto-detected activities (push or ping mode).
- */
-export const handleGarminWebhookMoveIQ = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminMoveIQPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.moveIQActivities.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processMoveIQPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
-      }
-    } else {
-      const pingResult =
-        garminMoveIQPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.moveIQActivities.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processMoveIQPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:moveIQ] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin blood pressure summaries (push or ping mode).
- */
-export const handleGarminWebhookBloodPressures = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminBloodPressurePushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.bloodPressures.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processBloodPressurePushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
-      }
-    } else {
-      const pingResult =
-        garminBloodPressurePingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.bloodPressures.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processBloodPressurePingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:bloodPressures] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin body composition summaries (push or ping mode).
- */
-export const handleGarminWebhookBodyCompositions = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminBodyCompositionsPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.bodyComps.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processBodyCompositionsPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
-      }
-    } else {
-      const pingResult =
-        garminBodyCompositionsPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.bodyComps.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processBodyCompositionsPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:bodyCompositions] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin daily summaries (push or ping mode).
- */
-export const handleGarminWebhookDailies = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminDailiesPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.dailies.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processDailiesPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminDailiesPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.dailies.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processDailiesPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:dailies] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin epoch summaries (push or ping mode).
- */
-export const handleGarminWebhookEpochs = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminEpochPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.epochs.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processEpochPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminEpochPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.epochs.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processEpochPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:epochs] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin health snapshot summaries (push or ping mode).
- */
-export const handleGarminWebhookHealthSnapshot = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminHealthSnapshotPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.healthSnapshot.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processHealthSnapshotPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminHealthSnapshotPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.healthSnapshot.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processHealthSnapshotPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:healthSnapshot] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin sleep summaries (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookSleeps = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminSleepsPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.sleeps.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processSleepsPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestSleep);
-      }
-    } else {
-      const pingResult =
-        garminSleepsPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.sleeps.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processSleepsPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:sleeps] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin skin temperature summaries (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookSkinTemp = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminSkinTemperaturePushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.skinTemp.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processSkinTemperaturePushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
-      }
-    } else {
-      const pingResult =
-        garminSkinTemperaturePingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.skinTemp.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processSkinTemperaturePingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:skinTemperature] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin user metrics (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookUserMetrics = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminUserMetricsPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.userMetrics.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processUserMetricsPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
-      }
-    } else {
-      const pingResult =
-        garminUserMetricsPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.userMetrics.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processUserMetricsPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:userMetrics] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin menstrual cycle tracking (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookMenstrualCycleTracking = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminMenstrualCycleTrackingPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.mct.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processMenstrualCycleTrackingPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestMenstruation);
-      }
-    } else {
-      const pingResult =
-        garminMenstrualCycleTrackingPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.mct.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processMenstrualCycleTrackingPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:menstrualCycleTracking] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin HRV summaries (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookHRVSummary = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminHRVSummaryPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.hrv.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processHRVSummaryPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminHRVSummaryPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.hrv.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processHRVSummaryPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:hrvSummary] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin stress detail summaries (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookStress = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminStressPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.stressDetails.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processStressPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminStressPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.stressDetails.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processStressPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:stressDetails] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin pulse oximetry (SpO2) summaries (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookPulseOx = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminPulseOxPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.pulseox.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processPulseOxPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminPulseOxPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.pulseox.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processPulseOxPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:pulseOx] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
-});
-
-/**
- * Handle a webhook for Garmin respiration summaries (push or ping mode).
- * Follows the structured dispatch pattern: validates with Zod, then delegates
- * to internal actions for processing.
- */
-export const handleGarminWebhookRespiration = action({
-  args: { payload: v.any() },
-  handler: async (ctx, args): Promise<WebhookResult> => {
-    if (isWebhookPushMode(args.payload)) {
-      const pushResult =
-        garminRespirationPushPayloadSchema.safeParse(args.payload);
-      if (
-        pushResult.success &&
-        pushResult.data.allDayRespiration.length > 0
-      ) {
-        const result: ProcessResult = await ctx.runAction(
-          internal.garmin.private.processRespirationPushPayload,
-          { payload: args.payload },
-        );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
-      }
-    } else {
-      const pingResult =
-        garminRespirationPingPayloadSchema.safeParse(args.payload);
-      if (
-        pingResult.success &&
-        pingResult.data.allDayRespiration.length > 0
-      ) {
-        return await ctx.runAction(
-          internal.garmin.private.processRespirationPingPayload,
-          { payload: args.payload },
-        );
-      }
-    }
-
-    console.warn(
-      `[garmin:webhook:respiration] Payload matched neither ping nor push schema`,
-    );
-    return { processed: 0, errors: [], affectedUsers: [] };
-  },
+// ─── Garmin 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.
+
+import { v } from "convex/values";
+import { action, type ActionCtx } from "../_generated/server";
+import { api, internal } from "../_generated/api";
+import {
+  garminSkinTemperaturePingPayloadSchema,
+  garminSkinTemperaturePushPayloadSchema,
+} from "./schemas/skinTemperature.js";
+import {
+  garminSleepsPingPayloadSchema,
+  garminSleepsPushPayloadSchema,
+} from "./schemas/sleeps.js";
+import {
+  garminStressPingPayloadSchema,
+  garminStressPushPayloadSchema,
+} from "./schemas/stress.js";
+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 {
+  garminEpochPingPayloadSchema,
+  garminEpochPushPayloadSchema,
+} from "./schemas/epochs.js";
+import {
+  garminHealthSnapshotPingPayloadSchema,
+  garminHealthSnapshotPushPayloadSchema,
+} from "./schemas/healthSnapshot.js";
+import {
+  garminHRVSummaryPingPayloadSchema,
+  garminHRVSummaryPushPayloadSchema,
+} from "./schemas/hrvSummary.js";
+import {
+  garminPulseOxPingPayloadSchema,
+  garminPulseOxPushPayloadSchema,
+} from "./schemas/pulseOx.js";
+import {
+  garminRespirationPingPayloadSchema,
+  garminRespirationPushPayloadSchema,
+} from "./schemas/respiration.js";
+import {
+  garminUserMetricsPingPayloadSchema,
+  garminUserMetricsPushPayloadSchema,
+} from "./schemas/userMetrics.js";
+import {
+  garminMenstrualCycleTrackingPingPayloadSchema,
+  garminMenstrualCycleTrackingPushPayloadSchema,
+} from "./schemas/menstrualCycleTracking.js";
+
+/**
+ * Discriminate push vs ping webhook payloads.
+ *
+ * Per the Garmin Activity API docs:
+ *   - Ping items always carry `callbackURL` (absent only for deregistrations)
+ *   - Push items never carry `callbackURL`, they contain the full summary data
+ *
+ * Zod schema validation alone can't distinguish the two because both schemas
+ * have all-optional fields and would accept either payload shape.
+ */
+function isWebhookPushMode(payload: unknown): boolean {
+  if (payload == null || typeof payload !== "object") return false;
+
+  // The payload is either a keyed object like { activities: [...] }
+  // or a flat array of items. Extract the first item either way.
+  let firstItem: unknown;
+  if (Array.isArray(payload)) {
+    firstItem = payload[0];
+  } else {
+    const key = Object.keys(payload)[0];
+    const list = (payload as Record<string, unknown>)[key];
+    firstItem = Array.isArray(list) ? list[0] : undefined;
+  }
+
+  if (firstItem == null || typeof firstItem !== "object") return false;
+  return !("callbackURL" in firstItem);
+}
+
+/** Shape returned by every public webhook handler action to the HTTP layer. */
+type WebhookResult = {
+  errors: Array<{ type: string; id: string; message: string }>;
+  items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }>;
+};
+
+/** Shape returned by internal push-processing actions (transform only, no DB writes). */
+type ProcessResult = {
+  items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }>;
+  errors: Array<{ type: string; id: string; message: string }>;
+};
+
+/**
+ * Build a WebhookResult from a ProcessResult without writing to the database.
+ * Used when `autoIngest` is disabled — the host app still gets the full set of
+ * transformed items in its callbacks, but no data is persisted.
+ */
+function toWebhookResult(result: ProcessResult): WebhookResult {
+  return {
+    errors: result.errors,
+    items: result.items,
+  };
+}
+
+/**
+ * Ingest transformed items from a private handler and update connections.
+ * Shared orchestration logic for all push-mode webhook handlers.
+ */
+async function ingestAndUpdate(
+  ctx: ActionCtx,
+  result: ProcessResult,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ingestMutation: any,
+): Promise<WebhookResult> {
+  const errors = [...result.errors];
+  const connectionsToUpdate = new Set<string>();
+
+  for (const item of result.items) {
+    try {
+      await ctx.runMutation(ingestMutation, {
+        connectionId: item.connectionId,
+        userId: item.userId,
+        ...item.data,
+      });
+      connectionsToUpdate.add(item.connectionId);
+    } catch (err) {
+      errors.push({
+        type: "ingest",
+        id: "unknown",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  for (const connectionId of connectionsToUpdate) {
+    await ctx.runMutation(api.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    } as never);
+  }
+
+  return { errors, items: result.items };
+}
+
+// ─── Webhook Handlers ────────────────────────────────────────────────────────
+
+/**
+ * Handle a webhook for Garmin activities (push or ping mode).
+ */
+export const handleGarminWebhookActivities = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult = garminActivityPushPayloadSchema.safeParse(args.payload);
+      if (pushResult.success && pushResult.data.activities.length > 0) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processActivityPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult = garminActivityPingPayloadSchema.safeParse(args.payload);
+      if (pingResult.success && pingResult.data.activities.length > 0) {
+        return await ctx.runAction(
+          internal.garmin.private.processActivityPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:activities] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin activity details (push or ping mode).
+ */
+export const handleGarminWebhookActivityDetails = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminActivityDetailsPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.activityDetails.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processActivityDetailsPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminActivityDetailsPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.activityDetails.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processActivityDetailsPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:activityDetails] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin manually updated activities (push or ping mode).
+ */
+export const handleGarminWebhookManuallyUpdatedActivities = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminManuallyUpdatedActivitiesPushPayloadSchema.safeParse(
+          args.payload,
+        );
+      if (
+        pushResult.success &&
+        pushResult.data.manuallyUpdatedActivities.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private
+            .processManuallyUpdatedActivitiesPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminManuallyUpdatedActivitiesPingPayloadSchema.safeParse(
+          args.payload,
+        );
+      if (
+        pingResult.success &&
+        pingResult.data.manuallyUpdatedActivities.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private
+            .processManuallyUpdatedActivitiesPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:manuallyUpdatedActivities] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin Move IQ auto-detected activities (push or ping mode).
+ */
+export const handleGarminWebhookMoveIQ = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminMoveIQPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.moveIQActivities.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processMoveIQPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminMoveIQPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.moveIQActivities.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processMoveIQPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:moveIQ] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin blood pressure summaries (push or ping mode).
+ */
+export const handleGarminWebhookBloodPressures = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminBloodPressurePushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.bloodPressures.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processBloodPressurePushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminBloodPressurePingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.bloodPressures.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processBloodPressurePingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:bloodPressures] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin body composition summaries (push or ping mode).
+ */
+export const handleGarminWebhookBodyCompositions = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminBodyCompositionsPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.bodyComps.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processBodyCompositionsPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminBodyCompositionsPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.bodyComps.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processBodyCompositionsPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:bodyCompositions] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin daily summaries (push or ping mode).
+ */
+export const handleGarminWebhookDailies = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminDailiesPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.dailies.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processDailiesPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminDailiesPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.dailies.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processDailiesPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:dailies] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin epoch summaries (push or ping mode).
+ */
+export const handleGarminWebhookEpochs = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminEpochPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.epochs.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processEpochPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminEpochPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.epochs.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processEpochPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:epochs] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin health snapshot summaries (push or ping mode).
+ */
+export const handleGarminWebhookHealthSnapshot = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminHealthSnapshotPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.healthSnapshot.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processHealthSnapshotPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminHealthSnapshotPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.healthSnapshot.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processHealthSnapshotPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:healthSnapshot] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin sleep summaries (push or ping mode).
+ */
+export const handleGarminWebhookSleeps = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminSleepsPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.sleeps.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processSleepsPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestSleep)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminSleepsPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.sleeps.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processSleepsPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:sleeps] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin skin temperature summaries (push or ping mode).
+ */
+export const handleGarminWebhookSkinTemp = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminSkinTemperaturePushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.skinTemp.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processSkinTemperaturePushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminSkinTemperaturePingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.skinTemp.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processSkinTemperaturePingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:skinTemperature] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin user metrics (push or ping mode).
+ */
+export const handleGarminWebhookUserMetrics = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminUserMetricsPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.userMetrics.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processUserMetricsPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminUserMetricsPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.userMetrics.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processUserMetricsPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:userMetrics] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin menstrual cycle tracking (push or ping mode).
+ */
+export const handleGarminWebhookMenstrualCycleTracking = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminMenstrualCycleTrackingPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.mct.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processMenstrualCycleTrackingPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestMenstruation)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminMenstrualCycleTrackingPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.mct.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processMenstrualCycleTrackingPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:menstrualCycleTracking] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin HRV summaries (push or ping mode).
+ */
+export const handleGarminWebhookHRVSummary = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminHRVSummaryPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.hrv.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processHRVSummaryPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminHRVSummaryPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.hrv.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processHRVSummaryPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:hrvSummary] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin stress detail summaries (push or ping mode).
+ */
+export const handleGarminWebhookStress = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminStressPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.stressDetails.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processStressPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminStressPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.stressDetails.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processStressPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:stressDetails] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin pulse oximetry (SpO2) summaries (push or ping mode).
+ */
+export const handleGarminWebhookPulseOx = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminPulseOxPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.pulseox.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processPulseOxPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminPulseOxPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.pulseox.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processPulseOxPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:pulseOx] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
+});
+
+/**
+ * Handle a webhook for Garmin respiration summaries (push or ping mode).
+ */
+export const handleGarminWebhookRespiration = action({
+  args: { payload: v.any(), autoIngest: v.optional(v.boolean()) },
+  handler: async (ctx, args): Promise<WebhookResult> => {
+    const shouldIngest = args.autoIngest !== false;
+    if (isWebhookPushMode(args.payload)) {
+      const pushResult =
+        garminRespirationPushPayloadSchema.safeParse(args.payload);
+      if (
+        pushResult.success &&
+        pushResult.data.allDayRespiration.length > 0
+      ) {
+        const result: ProcessResult = await ctx.runAction(
+          internal.garmin.private.processRespirationPushPayload,
+          { payload: args.payload },
+        );
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
+      }
+    } else {
+      const pingResult =
+        garminRespirationPingPayloadSchema.safeParse(args.payload);
+      if (
+        pingResult.success &&
+        pingResult.data.allDayRespiration.length > 0
+      ) {
+        return await ctx.runAction(
+          internal.garmin.private.processRespirationPingPayload,
+          { payload: args.payload },
+        );
+      }
+    }
+
+    console.warn(
+      `[garmin:webhook:respiration] Payload matched neither ping nor push schema`,
+    );
+    return { errors: [], items: [] };
+  },
 });