@nativesquare/soma 0.7.3 → 0.8.0

package/src/client/index.ts

@@ -10,6 +10,7 @@ export type SomaComponent = ComponentApi;
 
 export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
 export const GARMIN_CALLBACK_PATH = "/api/garmin/callback";
+export const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
 
 /**
  * Configuration for the Strava integration.
@@ -1198,6 +1199,136 @@ export class Soma {
   ) {
     return await ctx.runAction(this.component.garmin.disconnectGarmin, args);
   }
+
+  // ── Garmin Webhook Handlers ──────────────────────────────────────────────
+  // For host apps that handle webhook routes manually instead of using
+  // registerRoutes. Pass the raw JSON body from the Garmin POST request.
+
+  /**
+   * Handle a Garmin activities webhook (push mode).
+   *
+   * @param ctx - Convex action context
+   * @param payload - The raw JSON body from Garmin's POST (array of GarminActivity)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private get garminApi(): any { return this.component.garmin; }
+
+  async handleGarminWebhookActivities(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookActivities,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin dailies webhook (push mode).
+   */
+  async handleGarminWebhookDailies(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookDailies,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin sleeps webhook (push mode).
+   */
+  async handleGarminWebhookSleeps(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookSleeps,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin body composition webhook (push mode).
+   */
+  async handleGarminWebhookBody(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookBody,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin menstrual cycle tracking webhook (push mode).
+   */
+  async handleGarminWebhookMenstruation(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookMenstruation,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin blood pressure webhook (push mode).
+   */
+  async handleGarminWebhookBloodPressures(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookBloodPressures,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin skin temperature webhook (push mode).
+   */
+  async handleGarminWebhookSkinTemp(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookSkinTemp,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin user metrics webhook (push mode).
+   */
+  async handleGarminWebhookUserMetrics(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookUserMetrics,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin HRV webhook (push mode).
+   */
+  async handleGarminWebhookHRV(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookHRV,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin stress details webhook (push mode).
+   */
+  async handleGarminWebhookStressDetails(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookStressDetails,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin pulse oximetry webhook (push mode).
+   */
+  async handleGarminWebhookPulseOx(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookPulseOx,
+      { payload },
+    );
+  }
+
+  /**
+   * Handle a Garmin respiration webhook (push mode).
+   */
+  async handleGarminWebhookRespiration(ctx: ActionCtx, payload: unknown) {
+    return await ctx.runAction(
+      this.garminApi.handleGarminWebhookRespiration,
+      { payload },
+    );
+  }
 }
 
 // ─── Shared Types ────────────────────────────────────────────────────────────
@@ -1259,6 +1390,11 @@ export interface StravaRouteOptions {
   onSuccess?: string;
 }
 
+export interface GarminWebhookRouteOptions {
+  /** Base path prefix for all webhook routes. @default "/api/garmin/webhook" */
+  basePath?: string;
+}
+
 export interface GarminRouteOptions {
   /** HTTP path for the OAuth callback. @default "/api/garmin/callback" */
   path?: string;
@@ -1268,6 +1404,8 @@ export interface GarminRouteOptions {
   clientSecret?: string;
   /** URL to redirect the user to after a successful connection. */
   onSuccess?: string;
+  /** Webhook route configuration. Set to `false` to skip webhook registration. */
+  webhook?: GarminWebhookRouteOptions | false;
 }
 
 export interface RegisterRoutesOptions {
@@ -1456,5 +1594,66 @@ export function registerRoutes(
         });
       }),
     });
+
+    // ── Garmin Webhook Routes (Push Mode) ──────────────────────────────────
+    if (garmin.webhook !== false) {
+      const webhookBase =
+        (garmin.webhook && garmin.webhook.basePath) ?? GARMIN_WEBHOOK_BASE_PATH;
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const garminApi = component.garmin as any;
+      const webhookRoutes: Array<{
+        suffix: string;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        action: any;
+      }> = [
+        // ACTIVITY category
+        { suffix: "/activities", action: garminApi.handleGarminWebhookActivities },
+        { suffix: "/activity-details", action: garminApi.handleGarminWebhookActivities },
+        { suffix: "/manually-updated-activities", action: garminApi.handleGarminWebhookActivities },
+        { suffix: "/move-iq", action: garminApi.handleGarminWebhookActivities },
+        // HEALTH category
+        { suffix: "/dailies", action: garminApi.handleGarminWebhookDailies },
+        { suffix: "/sleeps", action: garminApi.handleGarminWebhookSleeps },
+        { suffix: "/hrv", action: garminApi.handleGarminWebhookHRV },
+        { suffix: "/stress-details", action: garminApi.handleGarminWebhookStressDetails },
+        { suffix: "/pulse-ox", action: garminApi.handleGarminWebhookPulseOx },
+        { suffix: "/respiration", action: garminApi.handleGarminWebhookRespiration },
+        // BODY category
+        { suffix: "/body", action: garminApi.handleGarminWebhookBody },
+        { suffix: "/blood-pressures", action: garminApi.handleGarminWebhookBloodPressures },
+        { suffix: "/skin-temp", action: garminApi.handleGarminWebhookSkinTemp },
+        { suffix: "/user-metrics", action: garminApi.handleGarminWebhookUserMetrics },
+        // WOMEN_HEALTH category
+        { suffix: "/menstruation", action: garminApi.handleGarminWebhookMenstruation },
+      ];
+
+      for (const route of webhookRoutes) {
+        http.route({
+          path: `${webhookBase}${route.suffix}`,
+          method: "POST",
+          handler: httpActionGeneric(async (ctx, request) => {
+            let payload: unknown;
+            try {
+              payload = await request.json();
+            } catch {
+              return new Response("Invalid JSON body", { status: 400 });
+            }
+
+            try {
+              await ctx.runAction(route.action, { payload });
+            } catch (error) {
+              // Log but return 200 to prevent Garmin from retrying
+              console.error(
+                `Garmin webhook error (${route.suffix}):`,
+                error instanceof Error ? error.message : error,
+              );
+            }
+
+            return new Response("OK", { status: 200 });
+          }),
+        });
+      }
+    }
   }
 }

package/src/component/_generated/component.ts

@@ -39,10 +39,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           errors: Array<{ error: string; id: string; type: string }>;
           synced: {
             activities: number;
+            bloodPressures: number;
             body: number;
             dailies: number;
+            hrv: number;
             menstruation: number;
+            pulseOx: number;
+            respiration: number;
+            skinTemp: number;
             sleep: number;
+            stressDetails: number;
+            userMetrics: number;
           };
         },
         Name
@@ -63,10 +70,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           errors: Array<{ error: string; id: string; type: string }>;
           synced: {
             activities: number;
+            bloodPressures: number;
             body: number;
             dailies: number;
+            hrv: number;
             menstruation: number;
+            pulseOx: number;
+            respiration: number;
+            skinTemp: number;
             sleep: number;
+            stressDetails: number;
+            userMetrics: number;
           };
         },
         Name
@@ -85,6 +99,126 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { authUrl: string; codeVerifier: string; state: string },
         Name
       >;
+      handleGarminWebhookActivities: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookBloodPressures: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookBody: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookDailies: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookHRV: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookMenstruation: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookPulseOx: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookRespiration: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookSkinTemp: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookSleeps: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookStressDetails: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
+      handleGarminWebhookUserMetrics: FunctionReference<
+        "action",
+        "internal",
+        { payload: any },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          processed: number;
+        },
+        Name
+      >;
       pushPlannedWorkout: FunctionReference<
         "action",
         "internal",
@@ -112,10 +246,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           errors: Array<{ error: string; id: string; type: string }>;
           synced: {
             activities: number;
+            bloodPressures: number;
             body: number;
             dailies: number;
+            hrv: number;
             menstruation: number;
+            pulseOx: number;
+            respiration: number;
+            skinTemp: number;
             sleep: number;
+            stressDetails: number;
+            userMetrics: number;
           };
         },
         Name
@@ -125,7 +266,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       connect: FunctionReference<
         "mutation",
         "internal",
-        { provider: string; userId: string },
+        { provider: string; providerUserId?: string; userId: string },
         string,
         Name
       >;
@@ -167,6 +308,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           active?: boolean;
           lastDataUpdate?: string;
           provider: string;
+          providerUserId?: string;
           userId: string;
         },
         Name
@@ -181,6 +323,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           active?: boolean;
           lastDataUpdate?: string;
           provider: string;
+          providerUserId?: string;
           userId: string;
         },
         Name
@@ -827,6 +970,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             }>;
             vo2max_ml_per_min_per_kg?: number;
           };
+          respiration_data?: {
+            breaths_data?: {
+              avg_breaths_per_min?: number;
+              max_breaths_per_min?: number;
+              min_breaths_per_min?: number;
+              samples?: Array<{ breaths_per_min?: number; timestamp?: string }>;
+            };
+          };
           scores?: {
             activity?: number;
             biological_age?: number;
@@ -1069,6 +1220,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             planned_date?: string;
             pool_length_meters?: number;
             provider?: string;
+            provider_schedule_id?: string;
+            provider_workout_id?: string;
             type?: string;
           };
           steps?: Array<{
@@ -1310,6 +1463,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           active?: boolean;
           lastDataUpdate?: string;
           provider: string;
+          providerUserId?: string;
           userId: string;
         }>,
         Name
@@ -1515,7 +1669,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       updateConnection: FunctionReference<
         "mutation",
         "internal",
-        { active?: boolean; connectionId: string; lastDataUpdate?: string },
+        {
+          active?: boolean;
+          connectionId: string;
+          lastDataUpdate?: string;
+          providerUserId?: string;
+        },
         null,
         Name
       >;