@nativesquare/soma 0.12.0 → 0.13.0

package/src/client/garmin.ts

@@ -1,487 +1,692 @@
-import type { SomaComponent } from "./index.js";
-import type { ActionCtx, SomaGarminConfig } from "./types.js";
-
-export class SomaGarmin {
-  constructor(
-    private component: SomaComponent,
-    private requireConfig: () => SomaGarminConfig,
-  ) {}
-
-  /**
-   * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
-   *
-   * The state and code verifier are stored inside the component automatically,
-   * and the callback handler registered by `registerRoutes` completes
-   * the flow without further host-app intervention.
-   *
-   * @param ctx - Action context from the host app
-   * @param opts.userId - The host app's user identifier
-   * @param opts.redirectUri - Optional override for the OAuth callback URL
-   * @returns `{ authUrl, state }`
-   *
-   * @example
-   * ```ts
-   * const { authUrl } = await soma.garmin.getAuthUrl(ctx, {
-   *   userId: "user_123",
-   *   redirectUri: "https://your-app.convex.site/api/garmin/callback",
-   * });
-   * // Redirect user to authUrl — the callback is handled automatically
-   * ```
-   */
-  async getAuthUrl(
-    ctx: ActionCtx,
-    opts: { userId: string; redirectUri?: string },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.getGarminAuthUrl, {
-      clientId: config.clientId,
-      redirectUri: opts.redirectUri,
-      userId: opts.userId,
-    });
-  }
-
-  /**
-   * Disconnect a user from Garmin.
-   *
-   * Deregisters the user at Garmin (best-effort), deletes stored tokens,
-   * and sets the connection to inactive.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   *
-   * @example
-   * ```ts
-   * await soma.garmin.disconnect(ctx, { userId: "user_123" });
-   * ```
-   */
-  async disconnect(
-    ctx: ActionCtx,
-    args: { userId: string },
-  ) {
-    return await ctx.runAction(this.component.garmin.public.disconnectGarmin, args);
-  }
-
-  /**
-   * Pull activity summaries from Garmin.
-   *
-   * Fetches activities, transforms them into the normalized Soma schema,
-   * and ingests them with automatic deduplication.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullActivities(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullActivities, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull daily wellness summaries from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullDailies(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullDailies, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull sleep summaries from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullSleep(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullSleep, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull body composition data from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullBody(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullBody, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull menstrual cycle tracking data from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullMenstruation(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullMenstruation, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull blood pressure readings from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullBloodPressures(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullBloodPressures, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull skin temperature data from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullSkinTemperature(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullSkinTemperature, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull user metrics (VO2 max, fitness age, etc.) from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullUserMetrics(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullUserMetrics, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull heart rate variability (HRV) summaries from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullHRV(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullHRV, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull stress detail data from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullStressDetails(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullStressDetails, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull pulse oximetry (SpO2) data from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullPulseOx(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullPulseOx, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull respiration (breathing rate) data from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   */
-  async pullRespiration(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullRespiration, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Pull all supported data types from Garmin in a single call.
-   *
-   * Equivalent to calling every individual `pull*` method. Automatically
-   * refreshes the access token if expired.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
-   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
-   *
-   * @example
-   * ```ts
-   * await soma.garmin.pullAll(ctx, { userId: "user_123" });
-   * ```
-   */
-  async pullAll(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pullAll, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Push a planned workout to Garmin Connect.
-   *
-   * Creates the workout on the user's Garmin account from a planned
-   * workout stored in Soma.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.plannedWorkoutId - The Soma planned workout document ID
-   * @param args.workoutProvider - Optional provider identifier for the workout source
-   */
-  async pushWorkout(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-      workoutProvider?: string;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pushWorkout, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Schedule a planned workout on the user's Garmin calendar.
-   *
-   * The workout must already exist on Garmin (via `pushWorkout`).
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.plannedWorkoutId - The Soma planned workout document ID
-   * @param args.date - Optional target date (YYYY-MM-DD); defaults to the workout's planned_date
-   */
-  async pushSchedule(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-      date?: string;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.pushSchedule, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Delete a planned workout from Garmin Connect.
-   *
-   * Removes the workout from the user's Garmin account.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.plannedWorkoutId - The Soma planned workout document ID
-   */
-  async deleteWorkout(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.deleteWorkout, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Remove a scheduled workout from the user's Garmin calendar.
-   *
-   * Unschedules the workout without deleting the workout itself.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.plannedWorkoutId - The Soma planned workout document ID
-   */
-  async deleteSchedule(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-    },
-  ) {
-    const config = this.requireConfig();
-    return await ctx.runAction(this.component.garmin.public.deleteSchedule, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-}
+import type { SomaComponent } from "./index.js";
+import type {
+  ActionCtx,
+  SomaGarminConfig,
+  RegisterRoutesOptions,
+  GarminWebhookActionArgs,
+  GarminWebhookActionResult,
+  GarminWebhookEventName,
+  GarminWebhookEvent,
+} from "./types.js";
+import {
+  httpActionGeneric,
+  type FunctionReference,
+  type HttpRouter,
+} from "convex/server";
+
+export const GARMIN_OAUTH_CALLBACK_PATH = "/api/garmin/callback";
+export const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
+
+export class SomaGarmin {
+  constructor(
+    private component: SomaComponent,
+    private requireConfig: () => SomaGarminConfig,
+  ) { }
+
+  /**
+   * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
+   *
+   * The state and code verifier are stored inside the component automatically,
+   * and the callback handler registered by `registerRoutes` completes
+   * the flow without further host-app intervention.
+   *
+   * @param ctx - Action context from the host app
+   * @param opts.userId - The host app's user identifier
+   * @param opts.redirectUri - Optional override for the OAuth callback URL
+   * @returns `{ authUrl, state }`
+   *
+   * @example
+   * ```ts
+   * const { authUrl } = await soma.garmin.getAuthUrl(ctx, {
+   *   userId: "user_123",
+   *   redirectUri: "https://your-app.convex.site/api/garmin/callback",
+   * });
+   * // Redirect user to authUrl — the callback is handled automatically
+   * ```
+   */
+  async getAuthUrl(
+    ctx: ActionCtx,
+    opts: { userId: string; redirectUri?: string },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.getGarminAuthUrl, {
+      clientId: config.clientId,
+      redirectUri: opts.redirectUri,
+      userId: opts.userId,
+    });
+  }
+
+  /**
+   * Disconnect a user from Garmin.
+   *
+   * Deregisters the user at Garmin (best-effort), deletes stored tokens,
+   * and sets the connection to inactive.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   *
+   * @example
+   * ```ts
+   * await soma.garmin.disconnect(ctx, { userId: "user_123" });
+   * ```
+   */
+  async disconnect(
+    ctx: ActionCtx,
+    args: { userId: string },
+  ) {
+    return await ctx.runAction(this.component.garmin.public.disconnectGarmin, args);
+  }
+
+  /**
+   * Pull activity summaries from Garmin.
+   *
+   * Fetches activities, transforms them into the normalized Soma schema,
+   * and ingests them with automatic deduplication.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullActivities(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullActivities, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull daily wellness summaries from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullDailies(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullDailies, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull sleep summaries from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullSleep(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullSleep, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull body composition data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullBody(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullBody, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull menstrual cycle tracking data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullMenstruation(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullMenstruation, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull blood pressure readings from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullBloodPressures(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullBloodPressures, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull skin temperature data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullSkinTemperature(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullSkinTemperature, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull user metrics (VO2 max, fitness age, etc.) from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullUserMetrics(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullUserMetrics, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull heart rate variability (HRV) summaries from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullHRV(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullHRV, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull stress detail data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullStressDetails(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullStressDetails, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull pulse oximetry (SpO2) data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullPulseOx(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullPulseOx, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull respiration (breathing rate) data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullRespiration(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullRespiration, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull all supported data types from Garmin in a single call.
+   *
+   * Equivalent to calling every individual `pull*` method. Automatically
+   * refreshes the access token if expired.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   *
+   * @example
+   * ```ts
+   * await soma.garmin.pullAll(ctx, { userId: "user_123" });
+   * ```
+   */
+  async pullAll(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullAll, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Push a planned workout to Garmin Connect.
+   *
+   * Creates the workout on the user's Garmin account from a planned
+   * workout stored in Soma.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   * @param args.workoutProvider - Optional provider identifier for the workout source
+   */
+  async pushWorkout(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+      workoutProvider?: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pushWorkout, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Schedule a planned workout on the user's Garmin calendar.
+   *
+   * The workout must already exist on Garmin (via `pushWorkout`).
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   * @param args.date - Optional target date (YYYY-MM-DD); defaults to the workout's planned_date
+   */
+  async pushSchedule(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+      date?: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pushSchedule, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Delete a planned workout from Garmin Connect.
+   *
+   * Removes the workout from the user's Garmin account.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   */
+  async deleteWorkout(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.deleteWorkout, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Remove a scheduled workout from the user's Garmin calendar.
+   *
+   * Unschedules the workout without deleting the workout itself.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   */
+  async deleteSchedule(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.deleteSchedule, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  static registerRoutes(
+    http: HttpRouter,
+    component: SomaComponent,
+    opts?: RegisterRoutesOptions["garmin"],
+  ) {
+    const oauth = opts?.oauth ?? {};
+    const path = oauth.path ?? GARMIN_OAUTH_CALLBACK_PATH;
+
+    http.route({
+      path,
+      method: "GET",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const url = new URL(request.url);
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+
+        if (!code) {
+          return new Response("Missing authorization code", {
+            status: 400,
+          });
+        }
+        if (!state) {
+          return new Response(
+            "Missing state parameter. Ensure the state was included " +
+            "when building the Garmin auth URL.",
+            { status: 400 },
+          );
+        }
+
+        const clientId =
+          opts?.clientId ?? process.env.GARMIN_CLIENT_ID;
+        const clientSecret =
+          opts?.clientSecret ?? process.env.GARMIN_CLIENT_SECRET;
+
+        if (!clientId || !clientSecret) {
+          return new Response(
+            "Garmin credentials not configured. Set GARMIN_CLIENT_ID and " +
+            "GARMIN_CLIENT_SECRET environment variables, or pass them to registerRoutes.",
+            { status: 500 },
+          );
+        }
+
+        let result: {
+          connectionId: string;
+          userId: string;
+        };
+        try {
+          result = await ctx.runAction(component.garmin.public.completeGarminOAuth, {
+            code,
+            state,
+            clientId,
+            clientSecret,
+          });
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : "Unknown error";
+          return new Response(`Garmin OAuth callback failed: ${message}`, {
+            status: 500,
+          });
+        }
+
+        if (oauth.onComplete) {
+          try {
+            await oauth.onComplete(ctx, {
+              provider: "GARMIN",
+              userId: result.userId,
+              connectionId: result.connectionId,
+            });
+          } catch (callbackError) {
+            console.error(
+              "[soma] garmin oauth.onComplete callback error:",
+              callbackError instanceof Error ? callbackError.message : callbackError,
+            );
+          }
+        }
+
+        if (oauth.redirectTo) {
+          return new Response(null, {
+            status: 302,
+            headers: { Location: oauth.redirectTo },
+          });
+        }
+
+        return new Response("Successfully connected to Garmin!", {
+          status: 200,
+        });
+      }),
+    });
+
+    // ── Garmin Webhook Routes ──────────────────────────────────
+    const webhookCfg = typeof opts?.webhook === "object" ? opts.webhook : undefined;
+    if (webhookCfg?.events) {
+      const webhookBase = webhookCfg.basePath ?? GARMIN_WEBHOOK_BASE_PATH;
+
+      const autoIngest = webhookCfg.autoIngest ?? true;
+
+      const webhookRoutes: Array<{
+        dataType: GarminWebhookEventName;
+        action: FunctionReference<"action", "internal", GarminWebhookActionArgs, GarminWebhookActionResult>;
+      }> = [
+          // ACTIVITY category
+          { dataType: "activities", action: component.garmin.webhooks.handleGarminWebhookActivities },
+          { dataType: "activity-details", action: component.garmin.webhooks.handleGarminWebhookActivityDetails },
+          { dataType: "manually-updated-activities", action: component.garmin.webhooks.handleGarminWebhookManuallyUpdatedActivities },
+          { dataType: "move-iq", action: component.garmin.webhooks.handleGarminWebhookMoveIQ },
+          // HEALTH category
+          { dataType: "blood-pressures", action: component.garmin.webhooks.handleGarminWebhookBloodPressures },
+          { dataType: "body-compositions", action: component.garmin.webhooks.handleGarminWebhookBodyCompositions },
+          { dataType: "dailies", action: component.garmin.webhooks.handleGarminWebhookDailies },
+          { dataType: "epochs", action: component.garmin.webhooks.handleGarminWebhookEpochs },
+          { dataType: "health-snapshot", action: component.garmin.webhooks.handleGarminWebhookHealthSnapshot },
+          { dataType: "sleeps", action: component.garmin.webhooks.handleGarminWebhookSleeps },
+          { dataType: "hrv", action: component.garmin.webhooks.handleGarminWebhookHRVSummary },
+          { dataType: "stress", action: component.garmin.webhooks.handleGarminWebhookStress },
+          { dataType: "pulse-ox", action: component.garmin.webhooks.handleGarminWebhookPulseOx },
+          { dataType: "respiration", action: component.garmin.webhooks.handleGarminWebhookRespiration },
+          { dataType: "skin-temp", action: component.garmin.webhooks.handleGarminWebhookSkinTemp },
+          { dataType: "user-metrics", action: component.garmin.webhooks.handleGarminWebhookUserMetrics },
+          // WOMEN_HEALTH category
+          { dataType: "menstrual-cycle-tracking", action: component.garmin.webhooks.handleGarminWebhookMenstrualCycleTracking },
+        ];
+
+      for (const route of webhookRoutes) {
+        const { dataType } = route;
+
+        // Only register routes the host app explicitly opted into
+        if (!webhookCfg.events?.[dataType]) continue;
+
+        http.route({
+          path: `${webhookBase}/${dataType}`,
+          method: "POST",
+          handler: httpActionGeneric(async (ctx, request) => {
+            let payload: unknown;
+            try {
+              payload = await request.json();
+            } catch {
+              return new Response("Invalid JSON body", { status: 400 });
+            }
+
+            let result: GarminWebhookActionResult | undefined;
+            try {
+              result = await ctx.runAction(route.action, { payload, autoIngest });
+            } catch (error) {
+              // Log but return 200 to prevent Garmin from retrying
+              console.error(
+                `Garmin webhook error (${dataType}):`,
+                error instanceof Error ? error.message : error,
+              );
+            }
+
+            if (result) {
+              const event: GarminWebhookEvent = {
+                dataType,
+                errors: result.errors,
+                rawPayload: payload,
+                items: result.items,
+              };
+
+              const specificHandler = webhookCfg.events?.[dataType];
+              if (typeof specificHandler === "function") {
+                try {
+                  await specificHandler(ctx, event);
+                } catch (callbackError) {
+                  console.error(
+                    `[soma] garmin webhook events["${dataType}"] callback error:`,
+                    callbackError instanceof Error ? callbackError.message : callbackError,
+                  );
+                }
+              }
+
+              if (webhookCfg.onEvent) {
+                try {
+                  await webhookCfg.onEvent(ctx, event);
+                } catch (callbackError) {
+                  console.error(
+                    `[soma] garmin webhook onEvent callback error:`,
+                    callbackError instanceof Error ? callbackError.message : callbackError,
+                  );
+                }
+              }
+            }
+
+            return new Response("OK", { status: 200 });
+          }),
+        });
+      }
+    }
+  }
+}