@nativesquare/soma 0.7.3 → 0.9.0

package/src/component/garmin/webhooks.ts

@@ -0,0 +1,852 @@
+// ─── 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 }>;
+};
+
+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>();
+
+  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);
+    } 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 };
+}
+
+// ─── 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});
+
+/**
+ * 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: [] };
+  },
+});