@nativesquare/soma 0.12.0 → 0.13.0

package/src/component/garmin/webhooks.ts

@@ -103,17 +103,30 @@ function isWebhookPushMode(payload: unknown): boolean {
   return !("callbackURL" in firstItem);
 }
 
+/** Shape returned by every public webhook handler action to the HTTP layer. */
 type WebhookResult = {
-  processed: number;
-  errors: Array<{ type: string; id: string; error: string }>;
-  affectedUsers: Array<{ userId: string; connectionId: string }>;
+  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; error: string }>;
+  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.
@@ -124,10 +137,8 @@ async function ingestAndUpdate(
   // 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 {
@@ -135,18 +146,13 @@ async function ingestAndUpdate(
         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,
       });
+      connectionsToUpdate.add(item.connectionId);
     } catch (err) {
       errors.push({
         type: "ingest",
         id: "unknown",
-        error: err instanceof Error ? err.message : String(err),
+        message: err instanceof Error ? err.message : String(err),
       });
     }
   }
@@ -158,7 +164,7 @@ async function ingestAndUpdate(
     } as never);
   }
 
-  return { processed, errors, affectedUsers: [...userMap.values()] };
+  return { errors, items: result.items };
 }
 
 // ─── Webhook Handlers ────────────────────────────────────────────────────────
@@ -167,8 +173,9 @@ async function ingestAndUpdate(
  * Handle a webhook for Garmin activities (push or ping mode).
  */
 export const handleGarminWebhookActivities = action({
-  args: { payload: v.any() },
+  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) {
@@ -176,7 +183,9 @@ export const handleGarminWebhookActivities = action({
           internal.garmin.private.processActivityPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult = garminActivityPingPayloadSchema.safeParse(args.payload);
@@ -191,7 +200,7 @@ export const handleGarminWebhookActivities = action({
     console.warn(
       `[garmin:webhook:activities] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -199,8 +208,9 @@ export const handleGarminWebhookActivities = action({
  * Handle a webhook for Garmin activity details (push or ping mode).
  */
 export const handleGarminWebhookActivityDetails = action({
-  args: { payload: v.any() },
+  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);
@@ -212,7 +222,9 @@ export const handleGarminWebhookActivityDetails = action({
           internal.garmin.private.processActivityDetailsPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -231,7 +243,7 @@ export const handleGarminWebhookActivityDetails = action({
     console.warn(
       `[garmin:webhook:activityDetails] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -239,8 +251,9 @@ export const handleGarminWebhookActivityDetails = action({
  * Handle a webhook for Garmin manually updated activities (push or ping mode).
  */
 export const handleGarminWebhookManuallyUpdatedActivities = action({
-  args: { payload: v.any() },
+  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(
@@ -255,7 +268,9 @@ export const handleGarminWebhookManuallyUpdatedActivities = action({
             .processManuallyUpdatedActivitiesPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -277,7 +292,7 @@ export const handleGarminWebhookManuallyUpdatedActivities = action({
     console.warn(
       `[garmin:webhook:manuallyUpdatedActivities] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -285,8 +300,9 @@ export const handleGarminWebhookManuallyUpdatedActivities = action({
  * Handle a webhook for Garmin Move IQ auto-detected activities (push or ping mode).
  */
 export const handleGarminWebhookMoveIQ = action({
-  args: { payload: v.any() },
+  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);
@@ -298,7 +314,9 @@ export const handleGarminWebhookMoveIQ = action({
           internal.garmin.private.processMoveIQPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestActivity);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestActivity)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -317,7 +335,7 @@ export const handleGarminWebhookMoveIQ = action({
     console.warn(
       `[garmin:webhook:moveIQ] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -325,8 +343,9 @@ export const handleGarminWebhookMoveIQ = action({
  * Handle a webhook for Garmin blood pressure summaries (push or ping mode).
  */
 export const handleGarminWebhookBloodPressures = action({
-  args: { payload: v.any() },
+  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);
@@ -338,7 +357,9 @@ export const handleGarminWebhookBloodPressures = action({
           internal.garmin.private.processBloodPressurePushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -357,7 +378,7 @@ export const handleGarminWebhookBloodPressures = action({
     console.warn(
       `[garmin:webhook:bloodPressures] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -365,8 +386,9 @@ export const handleGarminWebhookBloodPressures = action({
  * Handle a webhook for Garmin body composition summaries (push or ping mode).
  */
 export const handleGarminWebhookBodyCompositions = action({
-  args: { payload: v.any() },
+  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);
@@ -378,7 +400,9 @@ export const handleGarminWebhookBodyCompositions = action({
           internal.garmin.private.processBodyCompositionsPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -397,7 +421,7 @@ export const handleGarminWebhookBodyCompositions = action({
     console.warn(
       `[garmin:webhook:bodyCompositions] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -405,8 +429,9 @@ export const handleGarminWebhookBodyCompositions = action({
  * Handle a webhook for Garmin daily summaries (push or ping mode).
  */
 export const handleGarminWebhookDailies = action({
-  args: { payload: v.any() },
+  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);
@@ -418,7 +443,9 @@ export const handleGarminWebhookDailies = action({
           internal.garmin.private.processDailiesPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -437,7 +464,7 @@ export const handleGarminWebhookDailies = action({
     console.warn(
       `[garmin:webhook:dailies] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -445,8 +472,9 @@ export const handleGarminWebhookDailies = action({
  * Handle a webhook for Garmin epoch summaries (push or ping mode).
  */
 export const handleGarminWebhookEpochs = action({
-  args: { payload: v.any() },
+  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);
@@ -458,7 +486,9 @@ export const handleGarminWebhookEpochs = action({
           internal.garmin.private.processEpochPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -477,7 +507,7 @@ export const handleGarminWebhookEpochs = action({
     console.warn(
       `[garmin:webhook:epochs] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
@@ -485,8 +515,9 @@ export const handleGarminWebhookEpochs = action({
  * Handle a webhook for Garmin health snapshot summaries (push or ping mode).
  */
 export const handleGarminWebhookHealthSnapshot = action({
-  args: { payload: v.any() },
+  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);
@@ -498,7 +529,9 @@ export const handleGarminWebhookHealthSnapshot = action({
           internal.garmin.private.processHealthSnapshotPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -517,18 +550,17 @@ export const handleGarminWebhookHealthSnapshot = action({
     console.warn(
       `[garmin:webhook:healthSnapshot] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -540,7 +572,9 @@ export const handleGarminWebhookSleeps = action({
           internal.garmin.private.processSleepsPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestSleep);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestSleep)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -559,18 +593,17 @@ export const handleGarminWebhookSleeps = action({
     console.warn(
       `[garmin:webhook:sleeps] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -582,7 +615,9 @@ export const handleGarminWebhookSkinTemp = action({
           internal.garmin.private.processSkinTemperaturePushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -601,18 +636,17 @@ export const handleGarminWebhookSkinTemp = action({
     console.warn(
       `[garmin:webhook:skinTemperature] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -624,7 +658,9 @@ export const handleGarminWebhookUserMetrics = action({
           internal.garmin.private.processUserMetricsPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestBody);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestBody)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -643,18 +679,17 @@ export const handleGarminWebhookUserMetrics = action({
     console.warn(
       `[garmin:webhook:userMetrics] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -666,7 +701,9 @@ export const handleGarminWebhookMenstrualCycleTracking = action({
           internal.garmin.private.processMenstrualCycleTrackingPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestMenstruation);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestMenstruation)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -685,18 +722,17 @@ export const handleGarminWebhookMenstrualCycleTracking = action({
     console.warn(
       `[garmin:webhook:menstrualCycleTracking] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -708,7 +744,9 @@ export const handleGarminWebhookHRVSummary = action({
           internal.garmin.private.processHRVSummaryPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -727,18 +765,17 @@ export const handleGarminWebhookHRVSummary = action({
     console.warn(
       `[garmin:webhook:hrvSummary] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -750,7 +787,9 @@ export const handleGarminWebhookStress = action({
           internal.garmin.private.processStressPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -769,18 +808,17 @@ export const handleGarminWebhookStress = action({
     console.warn(
       `[garmin:webhook:stressDetails] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -792,7 +830,9 @@ export const handleGarminWebhookPulseOx = action({
           internal.garmin.private.processPulseOxPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -811,18 +851,17 @@ export const handleGarminWebhookPulseOx = action({
     console.warn(
       `[garmin:webhook:pulseOx] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });
 
 /**
  * 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() },
+  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);
@@ -834,7 +873,9 @@ export const handleGarminWebhookRespiration = action({
           internal.garmin.private.processRespirationPushPayload,
           { payload: args.payload },
         );
-        return await ingestAndUpdate(ctx, result, api.public.ingestDaily);
+        return shouldIngest
+          ? await ingestAndUpdate(ctx, result, api.public.ingestDaily)
+          : toWebhookResult(result);
       }
     } else {
       const pingResult =
@@ -853,6 +894,6 @@ export const handleGarminWebhookRespiration = action({
     console.warn(
       `[garmin:webhook:respiration] Payload matched neither ping nor push schema`,
     );
-    return { processed: 0, errors: [], affectedUsers: [] };
+    return { errors: [], items: [] };
   },
 });