@nativesquare/soma 0.14.0 → 0.14.1

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/NativeSquare/soma/issues"
   },
-  "version": "0.14.0",
+  "version": "0.14.1",
   "license": "Apache-2.0",
   "keywords": [
     "convex",

package/src/client/index.ts

@@ -12,6 +12,7 @@ import type {
 export type {
   ActionCtx,
   SomaError,
+  SomaErrorType,
   SomaResult,
   SomaStravaConfig,
   SomaGarminConfig,

package/src/client/types.ts

@@ -53,6 +53,8 @@ export interface SomaGarminConfig {
 
 // ─── Shared Error & Result Types ───────────────────────────────────────────
 
+export type { SomaErrorType } from "../component/validators/shared.js";
+
 /**
  * A structured error from a Soma operation.
  *
@@ -61,8 +63,8 @@ export interface SomaGarminConfig {
  * (missing connection, nonexistent document) are thrown as exceptions.
  */
 export interface SomaError {
-  /** Category of the failed item (e.g. `"activity"`, `"pushWorkout"`, `"ingest"`). */
-  type: string;
+  /** Category of the failed item — see {@link SomaErrorType} for valid values. */
+  type: import("../component/validators/shared.js").SomaErrorType;
   /** Identifier of the failed item, or `"fetch"` for API-level failures. */
   id: string;
   /** Human-readable error description. */

package/src/component/_generated/component.ts

@@ -25,6 +25,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
   {
     garmin: {
       public: {
+        backfillAll: FunctionReference<
+          "action",
+          "internal",
+          {
+            clientId: string;
+            clientSecret: string;
+            endTimeInSeconds?: number;
+            startTimeInSeconds?: number;
+            userId: string;
+          },
+          any,
+          Name
+        >;
         completeGarminOAuth: FunctionReference<
           "action",
           "internal",

package/src/component/garmin/private.ts

@@ -585,7 +585,7 @@ export const processBodyCompositionsPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "bodyCompositions",
+            type: "body",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -596,7 +596,7 @@ export const processBodyCompositionsPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "bodyCompositions",
+            type: "body",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -611,7 +611,7 @@ export const processBodyCompositionsPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "bodyCompositions",
+            type: "body",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });
@@ -677,7 +677,7 @@ export const processDailiesPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "dailies",
+            type: "daily",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -688,7 +688,7 @@ export const processDailiesPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "dailies",
+            type: "daily",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -703,7 +703,7 @@ export const processDailiesPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "dailies",
+            type: "daily",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });
@@ -861,7 +861,7 @@ export const processHRVSummaryPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "hrvSummary",
+            type: "hrv",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -872,7 +872,7 @@ export const processHRVSummaryPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "hrvSummary",
+            type: "hrv",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -887,7 +887,7 @@ export const processHRVSummaryPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "hrvSummary",
+            type: "hrv",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });
@@ -1594,7 +1594,7 @@ export const processMenstrualCycleTrackingPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "menstrualCycleTracking",
+            type: "menstruation",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -1605,7 +1605,7 @@ export const processMenstrualCycleTrackingPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "menstrualCycleTracking",
+            type: "menstruation",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -1619,7 +1619,7 @@ export const processMenstrualCycleTrackingPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "menstrualCycleTracking",
+            type: "menstruation",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });

package/src/component/garmin/public.ts

@@ -18,7 +18,7 @@ import {
   createWellnessClient,
   createTrainingClient,
 } from "./client.js";
-import { buildTimeRangeQuery } from "./utils.js";
+import { buildTimeRangeQuery, buildChunkedTimeRangeQueries, buildBackfillQuery, buildChunkedBackfillQueries } from "./utils.js";
 import {
   createWorkoutV2 as sdkCreateWorkoutV2,
   createWorkoutSchedule as sdkCreateWorkoutSchedule,
@@ -42,6 +42,19 @@ import {
   getStressDetails,
   getPulseox,
   getRespiration,
+  getBackfillDailies,
+  getBackfillSleeps,
+  getBackfillBodycomps,
+  getBackfillMct,
+  getBackfillBloodPressures,
+  getBackfillSkinTemp,
+  getBackfillUserMetrics,
+  getBackfillHrv,
+  getBackfillStressDetails,
+  getBackfillPulseox,
+  getBackfillRespirationEpoch,
+  getBackfillActivities,
+  getBackfillActivityDetails,
 } from "./types/wellnessApi/sdk.gen";
 import { transformActivity } from "./transform/activity.js";
 import { transformDailies } from "./transform/dailies.js";
@@ -57,7 +70,7 @@ import { transformPulseOx } from "./transform/pulseOx.js";
 import { transformRespiration } from "./transform/respiration.js";
 import { transformPlannedWorkoutToGarmin } from "./transform/plannedWorkout.js";
 import { api, internal } from "../_generated/api";
-import type { SomaError } from "../validators/shared.js";
+import type { SomaError, SomaErrorType } from "../validators/shared.js";
 
 // ─── OAuth ──────────────────────────────────────────────────────────────────
 
@@ -187,8 +200,8 @@ export const disconnectGarmin = action({
       try {
         const wellnessClient = createWellnessClient(tokenDoc.accessToken);
         await sdkDereg({ client: wellnessClient });
-      } catch {
-        // Deregistration is best-effort; proceed with local cleanup
+      } catch (err) {
+        console.warn("[garmin:disconnect] Best-effort deregistration failed:", err instanceof Error ? err.message : err);
       }
     }
 
@@ -507,11 +520,11 @@ export const pullSkinTemperature = action({
           await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
           synced.skinTemp++;
         } catch (err) {
-          errors.push({ type: "skinTemp", id: skin.summaryId ?? skin.calendarDate ?? "unknown", message: err instanceof Error ? err.message : String(err) });
+          errors.push({ type: "skinTemperature", id: skin.summaryId ?? skin.calendarDate ?? "unknown", message: err instanceof Error ? err.message : String(err) });
         }
       }
     } catch (err) {
-      errors.push({ type: "skinTemp", id: "fetch", message: err instanceof Error ? err.message : String(err) });
+      errors.push({ type: "skinTemperature", id: "fetch", message: err instanceof Error ? err.message : String(err) });
     }
 
     await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
@@ -740,14 +753,15 @@ export const pullAll = action({
       startTimeInSeconds: args.startTimeInSeconds,
       endTimeInSeconds: args.endTimeInSeconds,
     };
-    const pullFns = [
-      { ref: api.garmin.public.pullActivities, name: "activities" },
-      { ref: api.garmin.public.pullDailies, name: "dailies" },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pullFns: Array<{ ref: any; name: SomaErrorType }> = [
+      { ref: api.garmin.public.pullActivities, name: "activity" },
+      { ref: api.garmin.public.pullDailies, name: "daily" },
       { ref: api.garmin.public.pullSleep, name: "sleep" },
       { ref: api.garmin.public.pullBody, name: "body" },
       { ref: api.garmin.public.pullMenstruation, name: "menstruation" },
-      { ref: api.garmin.public.pullBloodPressures, name: "bloodPressures" },
-      { ref: api.garmin.public.pullSkinTemperature, name: "skinTemp" },
+      { ref: api.garmin.public.pullBloodPressures, name: "bloodPressure" },
+      { ref: api.garmin.public.pullSkinTemperature, name: "skinTemperature" },
       { ref: api.garmin.public.pullUserMetrics, name: "userMetrics" },
       { ref: api.garmin.public.pullHRV, name: "hrv" },
       { ref: api.garmin.public.pullStressDetails, name: "stressDetails" },
@@ -774,6 +788,147 @@ export const pullAll = action({
 });
 
 
+// ─── Backfill ─────────────────────────────────────────────────────────────
+
+/**
+ * Request historical data from Garmin's backfill API for all summary types.
+ *
+ * Unlike pull functions (which query by upload time with a 24h max window),
+ * backfill requests data by the time it was *recorded* on the device.
+ * Garmin processes backfill asynchronously (HTTP 202) and delivers data
+ * via push/ping webhooks — no data is returned synchronously.
+ *
+ * Health endpoints accept up to 90 days per request.
+ * Activity endpoints accept up to 30 days per request (auto-chunked).
+ *
+ * Defaults to the last 90 days when no time range is provided.
+ */
+export const backfillAll = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.private.resolveConnectionAndAccessToken,
+      {
+        userId: args.userId,
+        provider: "GARMIN",
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+      },
+    );
+
+    const wellnessClient = createWellnessClient(accessToken);
+    const timeInput = {
+      startTimeInSeconds: args.startTimeInSeconds,
+      endTimeInSeconds: args.endTimeInSeconds,
+    };
+
+    // Health endpoints: up to 90 days, single request each
+    const healthQuery = buildBackfillQuery(timeInput);
+
+    // Activity endpoints: max 30 days per request, chunked
+    const activityChunks = buildChunkedBackfillQueries(timeInput);
+
+    const requested: string[] = [];
+    const errors: SomaError[] = [];
+
+    // ── Health backfills (90-day window) ──
+    const healthBackfills: Array<{
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      fn: (opts: any) => Promise<any>;
+      name: string;
+    }> = [
+      { fn: getBackfillDailies, name: "dailies" },
+      { fn: getBackfillSleeps, name: "sleeps" },
+      { fn: getBackfillBodycomps, name: "bodyComps" },
+      { fn: getBackfillMct, name: "mct" },
+      { fn: getBackfillBloodPressures, name: "bloodPressures" },
+      { fn: getBackfillSkinTemp, name: "skinTemp" },
+      { fn: getBackfillUserMetrics, name: "userMetrics" },
+      { fn: getBackfillHrv, name: "hrv" },
+      { fn: getBackfillStressDetails, name: "stressDetails" },
+      { fn: getBackfillPulseox, name: "pulseOx" },
+      { fn: getBackfillRespirationEpoch, name: "respiration" },
+    ];
+
+    for (const { fn, name } of healthBackfills) {
+      try {
+        const { error } = await fn({
+          client: wellnessClient,
+          query: healthQuery,
+        });
+        if (error) {
+          errors.push({
+            type: name as SomaErrorType,
+            id: "backfill",
+            message: JSON.stringify(error),
+          });
+        } else {
+          requested.push(name);
+        }
+      } catch (err) {
+        errors.push({
+          type: name as SomaErrorType,
+          id: "backfill",
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // ── Activity backfills (30-day chunked windows) ──
+    const activityBackfills: Array<{
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      fn: (opts: any) => Promise<any>;
+      name: string;
+    }> = [
+      { fn: getBackfillActivities, name: "activities" },
+      { fn: getBackfillActivityDetails, name: "activityDetails" },
+    ];
+
+    for (const { fn, name } of activityBackfills) {
+      let chunkErrors = 0;
+      for (const chunk of activityChunks) {
+        try {
+          const { error } = await fn({
+            client: wellnessClient,
+            query: chunk,
+          });
+          if (error) {
+            chunkErrors++;
+            errors.push({
+              type: name as SomaErrorType,
+              id: "backfill",
+              message: JSON.stringify(error),
+            });
+          }
+        } catch (err) {
+          chunkErrors++;
+          errors.push({
+            type: name as SomaErrorType,
+            id: "backfill",
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+      if (chunkErrors < activityChunks.length) {
+        requested.push(name);
+      }
+    }
+
+    await ctx.runMutation(api.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
+    return { data: { requested }, errors };
+  },
+});
+
 // ─── Push ───────────────────────────────────────────────────────────────────
 
 export const pushWorkout = action({

package/src/component/garmin/utils.ts

@@ -39,4 +39,106 @@ export function buildTimeRangeQuery(
     uploadEndTimeInSeconds: String(uploadEndTimeInSeconds),
     token: accessToken,
   };
+}
+
+/**
+ * Build an array of time-range query objects, each spanning at most
+ * `maxRangeSeconds`.
+ *
+ * Garmin's intraday endpoints (respiration, stress, pulse-ox, epochs, HRV)
+ * enforce a maximum query window of 86 400 s (24 h). This helper splits the
+ * full requested range into consecutive, non-overlapping chunks so the caller
+ * can issue one API call per chunk and merge the results.
+ */
+export function buildChunkedTimeRangeQueries(
+  input: { startTimeInSeconds?: number; endTimeInSeconds?: number },
+  accessToken: string,
+  maxRangeSeconds: number,
+  nowSeconds = Math.floor(Date.now() / 1000),
+  defaultSyncDays = 30,
+) {
+  const start =
+    input.startTimeInSeconds ?? nowSeconds - defaultSyncDays * 86400;
+  const end = input.endTimeInSeconds ?? nowSeconds;
+
+  const chunks: Array<{
+    uploadStartTimeInSeconds: string;
+    uploadEndTimeInSeconds: string;
+    token: string;
+  }> = [];
+
+  for (let chunkStart = start; chunkStart < end; chunkStart += maxRangeSeconds) {
+    const chunkEnd = Math.min(chunkStart + maxRangeSeconds, end);
+    chunks.push({
+      uploadStartTimeInSeconds: String(chunkStart),
+      uploadEndTimeInSeconds: String(chunkEnd),
+      token: accessToken,
+    });
+  }
+
+  return chunks;
+}
+
+// ─── Backfill Query Helpers ────────────────────────────────────────────────
+
+const BACKFILL_MAX_HEALTH_DAYS = 90;
+const BACKFILL_MAX_ACTIVITY_DAYS = 30;
+
+/**
+ * Build a backfill query object for Garmin's `/rest/backfill/*` endpoints.
+ *
+ * Backfill uses `summaryStartTimeInSeconds` / `summaryEndTimeInSeconds`
+ * (based on when data was *recorded*, not uploaded) and does NOT take a
+ * `token` query param — auth is via Bearer header only.
+ *
+ * Health endpoints accept up to 90 days per request.
+ * Activity endpoints accept up to 30 days per request.
+ */
+export function buildBackfillQuery(
+  input: { startTimeInSeconds?: number; endTimeInSeconds?: number },
+  nowSeconds = Math.floor(Date.now() / 1000),
+  defaultDays = BACKFILL_MAX_HEALTH_DAYS,
+) {
+  const summaryStartTimeInSeconds =
+    input.startTimeInSeconds ?? nowSeconds - defaultDays * 86400;
+  const summaryEndTimeInSeconds = input.endTimeInSeconds ?? nowSeconds;
+
+  return {
+    summaryStartTimeInSeconds: String(summaryStartTimeInSeconds),
+    summaryEndTimeInSeconds: String(summaryEndTimeInSeconds),
+  };
+}
+
+/**
+ * Build an array of backfill query objects, each spanning at most
+ * `maxDays` days.
+ *
+ * Activity backfill endpoints enforce a 30-day max per request.
+ * This splits a wider range into consecutive, non-overlapping chunks.
+ */
+export function buildChunkedBackfillQueries(
+  input: { startTimeInSeconds?: number; endTimeInSeconds?: number },
+  maxDays = BACKFILL_MAX_ACTIVITY_DAYS,
+  nowSeconds = Math.floor(Date.now() / 1000),
+  defaultDays = BACKFILL_MAX_HEALTH_DAYS,
+) {
+  const start =
+    input.startTimeInSeconds ?? nowSeconds - defaultDays * 86400;
+  const end = input.endTimeInSeconds ?? nowSeconds;
+
+  const maxRangeSeconds = maxDays * 86400;
+  const chunks: Array<{
+    summaryStartTimeInSeconds: string;
+    summaryEndTimeInSeconds: string;
+  }> = [];
+
+  for (let chunkStart = start; chunkStart < end; chunkStart += maxRangeSeconds) {
+    const chunkEnd = Math.min(chunkStart + maxRangeSeconds, end);
+    chunks.push({
+      summaryStartTimeInSeconds: String(chunkStart),
+      summaryEndTimeInSeconds: String(chunkEnd),
+    });
+  }
+
+  return chunks;
 }

package/src/component/garmin/webhooks.ts

@@ -6,7 +6,7 @@
 import { v } from "convex/values";
 import { action, type ActionCtx } from "../_generated/server";
 import { api, internal } from "../_generated/api";
-import type { SomaError } from "../validators/shared.js";
+import type { SomaError, WebhookResult } from "../validators/shared.js";
 import {
   garminSkinTemperaturePingPayloadSchema,
   garminSkinTemperaturePushPayloadSchema,
@@ -104,12 +104,6 @@ function isWebhookPushMode(payload: unknown): boolean {
   return !("callbackURL" in firstItem);
 }
 
-/** Shape returned by webhook handler actions (both internal processors and public handlers). */
-type WebhookResult = {
-  errors: SomaError[];
-  items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }>;
-};
-
 /**
  * Ingest transformed items from a private handler and update connections.
  * Shared orchestration logic for all push-mode webhook handlers.

package/src/component/strava/public.ts

@@ -21,7 +21,7 @@ import {
 } from "./auth.js";
 import { transformActivity } from "./transform/activity.js";
 import { transformAthlete } from "./transform/athlete.js";
-import type { SomaError } from "../validators/shared.js";
+import type { SomaError, SomaErrorType } from "../validators/shared.js";
 
 // ─── OAuth ──────────────────────────────────────────────────────────────────
 
@@ -153,8 +153,8 @@ export const disconnectStrava = action({
           headers: { "Content-Type": "application/x-www-form-urlencoded" },
           body: `access_token=${tokenDoc.accessToken}`,
         });
-      } catch {
-        // Deauthorization is best-effort — clean up locally regardless
+      } catch (err) {
+        console.warn("[strava:disconnect] Best-effort deauthorization failed:", err instanceof Error ? err.message : err);
       }
 
       // 3. Delete stored tokens
@@ -303,9 +303,10 @@ export const pullAll = action({
       clientId: args.clientId,
       clientSecret: args.clientSecret,
     };
-    const pullFns = [
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pullFns: Array<{ ref: any; name: SomaErrorType; args: Record<string, unknown> }> = [
       { ref: api.strava.public.pullAthlete, name: "athlete", args: sharedArgs },
-      { ref: api.strava.public.pullActivities, name: "activities", args: { ...sharedArgs, after: args.after, before: args.before } },
+      { ref: api.strava.public.pullActivities, name: "activity", args: { ...sharedArgs, after: args.after, before: args.before } },
     ];
     const synced: Record<string, number> = {};
     const errors: SomaError[] = [];

package/src/component/strava/webhooks.ts

@@ -17,7 +17,7 @@ import {
 } from "./types/stravaApi/sdk.gen.js";
 import { transformActivity } from "./transform/activity.js";
 import { transformAthlete } from "./transform/athlete.js";
-import type { SomaError } from "../validators/shared.js";
+import type { SomaError, SomaErrorType, WebhookResult } from "../validators/shared.js";
 
 // ─── Schema ─────────────────────────────────────────────────────────────────
 
@@ -41,10 +41,8 @@ const VALID_EVENT_NAMES = new Set([
   "athlete-deauthorize",
 ]);
 
-type WebhookResult = {
-  errors: SomaError[];
-  items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> | null }>;
-};
+// Strava webhooks use WebhookResult with nullable data (for delete/deauthorize events).
+type StravaWebhookResult = WebhookResult<Record<string, unknown> | null>;
 
 // ─── Handler ────────────────────────────────────────────────────────────────
 
@@ -55,7 +53,7 @@ export const handleStravaWebhook = action({
     clientSecret: v.string(),
     autoIngest: v.optional(v.boolean()),
   },
-  handler: async (ctx, args): Promise<WebhookResult> => {
+  handler: async (ctx, args): Promise<StravaWebhookResult> => {
     const payload = stravaWebhookPayloadSchema.parse(args.payload);
     const { clientId, clientSecret } = args;
     const shouldIngest = args.autoIngest !== false;
@@ -74,7 +72,7 @@ export const handleStravaWebhook = action({
     if (!connection) {
       return {
         errors: [{
-          type: payload.object_type,
+          type: payload.object_type as SomaErrorType,
           id: String(payload.object_id),
           message: `No Soma connection found for Strava owner_id "${payload.owner_id}". ` +
             "The user may need to reconnect to populate the provider user ID.",
@@ -87,7 +85,7 @@ export const handleStravaWebhook = action({
     if (!connection.active && eventName !== "athlete-deauthorize") {
       return {
         errors: [{
-          type: payload.object_type,
+          type: payload.object_type as SomaErrorType,
           id: String(payload.object_id),
           message: `Strava connection for owner_id "${payload.owner_id}" is inactive`,
         }],
@@ -141,7 +139,7 @@ async function handleActivityCreateOrUpdate(
     clientSecret: string;
     shouldIngest: boolean;
   },
-): Promise<WebhookResult> {
+): Promise<StravaWebhookResult> {
   const errors: SomaError[] = [];
 
   let accessToken: string;
@@ -219,7 +217,7 @@ async function handleAthleteUpdate(
     clientSecret: string;
     shouldIngest: boolean;
   },
-): Promise<WebhookResult> {
+): Promise<StravaWebhookResult> {
   let accessToken: string;
   try {
     const resolved = await ctx.runAction(
@@ -283,7 +281,7 @@ async function handleAthleteDeauthorize(
     userId: string;
     shouldIngest: boolean;
   },
-): Promise<WebhookResult> {
+): Promise<StravaWebhookResult> {
   if (args.shouldIngest) {
     try {
       await ctx.runMutation(internal.private.deleteTokens, {