@nativesquare/soma 0.11.0 → 0.13.0

package/src/client/index.ts

@@ -1,50 +1,47 @@
 import type { ComponentApi } from "../component/_generated/component.js";
-import type { ActionCtx, MutationCtx, QueryCtx } from "./types.js";
-import {
-  httpActionGeneric,
-  type FunctionReference,
-  type GenericActionCtx,
-  type GenericDataModel,
-  type HttpRouter,
-} from "convex/server";
+import type {
+  MutationCtx,
+  QueryCtx,
+  SomaStravaConfig,
+  SomaGarminConfig,
+  IngestArgs,
+  ListTimeRangeArgs,
+  PaginateTimeRangeArgs,
+  RegisterRoutesOptions,
+} from "./types.js";
+export type {
+  ActionCtx,
+  SomaError,
+  SomaResult,
+  SomaStravaConfig,
+  SomaGarminConfig,
+  IngestArgs,
+  TimeRangeArgs,
+  ListTimeRangeArgs,
+  PaginateTimeRangeArgs,
+  StravaOAuthOptions,
+  StravaConnectEvent,
+  GarminConnectEvent,
+  GarminWebhookActionArgs,
+  GarminWebhookActionResult,
+  GarminWebhookEvent,
+  GarminOAuthOptions,
+  GarminWebhookEventName,
+  GarminWebhookHandler,
+  GarminWebhookOptions,
+  RegisterRoutesOptions,
+} from "./types.js";
+import type { HttpRouter } from "convex/server";
+import { SomaGarmin } from "./garmin.js";
+import { SomaStrava } from "./strava.js";
+
+export { SomaGarmin } from "./garmin.js";
+export { SomaStrava } from "./strava.js";
+export { STRAVA_CALLBACK_PATH } from "./strava.js";
+export { GARMIN_OAUTH_CALLBACK_PATH, GARMIN_WEBHOOK_BASE_PATH } from "./garmin.js";
 
 export type SomaComponent = ComponentApi;
 
-// ─── Default OAuth Callback Paths ────────────────────────────────────────────
-// Used by `registerRoutes` as defaults. Override per-provider in the opts.
-
-export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
-export const GARMIN_OAUTH_CALLBACK_PATH = "/api/garmin/callback";
-export const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
-
-/**
- * Configuration for the Strava integration.
- *
- * If not provided to the constructor, the Soma class will attempt to
- * read `STRAVA_CLIENT_ID`, `STRAVA_CLIENT_SECRET`, and `STRAVA_BASE_URL`
- * from environment variables automatically.
- */
-export interface SomaStravaConfig {
-  /** Your Strava application's Client ID. */
-  clientId: string;
-  /** Your Strava application's Client Secret. */
-  clientSecret: string;
-}
-
-/**
- * Configuration for the Garmin integration.
- *
- * If not provided to the constructor, the Soma class will attempt to
- * read `GARMIN_CLIENT_ID` and `GARMIN_CLIENT_SECRET` from
- * environment variables automatically.
- */
-export interface SomaGarminConfig {
-  /** Your Garmin application's Client ID. */
-  clientId: string;
-  /** Your Garmin application's Client Secret. */
-  clientSecret: string;
-}
-
 /**
  * Client class for the @nativesquare/soma Convex component.
  *
@@ -52,7 +49,7 @@ export interface SomaGarminConfig {
  * and querying normalized health & fitness data.
  *
  * All capabilities are also accessible via direct component function calls:
- * `ctx.runMutation(components.soma.public.connect, { userId, provider: "GARMIN" })`
+ * `ctx.runQuery(components.soma.public.listActivities, { userId: "user_123" })`
  *
  * @example
  * ```ts
@@ -61,37 +58,42 @@ export interface SomaGarminConfig {
  * import { components } from "./_generated/api";
  *
  * // Zero config if env vars are set in Convex dashboard:
- * //   STRAVA_CLIENT_ID, STRAVA_CLIENT_SECRET, STRAVA_BASE_URL (optional)
+ * //   STRAVA_CLIENT_ID, STRAVA_CLIENT_SECRET
+ * //   GARMIN_CLIENT_ID, GARMIN_CLIENT_SECRET
  * const soma = new Soma(components.soma);
  *
- * // Or with explicit Strava config:
+ * // Or with explicit config:
  * // const soma = new Soma(components.soma, {
  * //   strava: { clientId: "...", clientSecret: "..." },
+ * //   garmin: { clientId: "...", clientSecret: "..." },
  * // });
  *
- * // Connect a user to a provider:
- * const connectionId = await soma.connect(ctx, {
- *   userId: "user_123",
- *   provider: "GARMIN",
- * });
- *
  * // Start Strava OAuth (redirects user, callback handled by registerRoutes):
- * const { authUrl } = await soma.getStravaAuthUrl(ctx, {
+ * const { authUrl } = await soma.strava.getAuthUrl(ctx, {
  *   userId: "user_123",
  *   redirectUri: "https://your-app.convex.site/api/strava/callback",
  * });
+ *
+ * // Pull all Garmin data:
+ * await soma.garmin.pullAll(ctx, { userId: "user_123" });
  * ```
  */
 export class Soma {
   private stravaConfig?: SomaStravaConfig;
   private garminConfig?: SomaGarminConfig;
 
+  public readonly garmin: SomaGarmin;
+  public readonly strava: SomaStrava;
+
   constructor(
     public component: SomaComponent,
     options?: { strava?: SomaStravaConfig; garmin?: SomaGarminConfig },
   ) {
     this.stravaConfig = options?.strava ?? this.readStravaEnv();
     this.garminConfig = options?.garmin ?? this.readGarminEnv();
+
+    this.garmin = new SomaGarmin(this.component, () => this.requireGarminConfig());
+    this.strava = new SomaStrava(this.component, () => this.requireStravaConfig());
   }
 
   /**
@@ -147,66 +149,6 @@ export class Soma {
     return this.garminConfig;
   }
 
-  // ─── Connect / Disconnect ───────────────────────────────────────────────────
-
-  /**
-   * Connect a user to a wearable provider.
-   *
-   * Creates the connection if it doesn't exist, or re-activates it if it was
-   * previously disconnected. Idempotent — calling twice is a no-op.
-   *
-   * Use this when the host app has completed the provider's auth flow and
-   * wants to register the connection in Soma.
-   *
-   * @param ctx - Mutation context from the host app
-   * @param args.userId - The host app's user identifier (Clerk ID, etc.)
-   * @param args.provider - The wearable provider name ("GARMIN", "FITBIT", "OURA", etc.)
-   * @returns The connection document ID
-   *
-   * @example
-   * ```ts
-   * // "Connect to Garmin" button handler
-   * const connectionId = await soma.connect(ctx, {
-   *   userId: "user_123",
-   *   provider: "GARMIN",
-   * });
-   * ```
-   */
-  async connect(
-    ctx: MutationCtx,
-    args: { userId: string; provider: string },
-  ): Promise<string> {
-    return await ctx.runMutation(this.component.public.connect, args);
-  }
-
-  /**
-   * Disconnect a user from a wearable provider.
-   *
-   * Sets the connection to inactive. Does not delete any synced data,
-   * so re-connecting later preserves historical records.
-   *
-   * @param ctx - Mutation context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.provider - The wearable provider name
-   *
-   * @throws Error if no connection exists for the given user–provider pair
-   *
-   * @example
-   * ```ts
-   * // "Disconnect Garmin" button handler
-   * await soma.disconnect(ctx, {
-   *   userId: "user_123",
-   *   provider: "GARMIN",
-   * });
-   * ```
-   */
-  async disconnect(
-    ctx: MutationCtx,
-    args: { userId: string; provider: string },
-  ): Promise<null> {
-    return await ctx.runMutation(this.component.public.disconnect, args);
-  }
-
   // ─── Connection Queries ─────────────────────────────────────────────────────
 
   /**
@@ -812,7 +754,7 @@ export class Soma {
   ) {
     return await ctx.runMutation(
       this.component.public.deletePlannedWorkout,
-      args as never,
+      args,
     );
   }
 
@@ -828,563 +770,10 @@ export class Soma {
   ) {
     return await ctx.runQuery(
       this.component.public.getPlannedWorkout,
-      args as never,
+      args,
     );
   }
 
-  // ─── Strava Integration ──────────────────────────────────────────────────────
-  // High-level methods that handle OAuth, token storage, and data syncing
-  // for Strava. Requires Strava credentials to be configured either via
-  // environment variables or the constructor.
-
-  /**
-   * Generate a Strava OAuth authorization URL.
-   *
-   * The state parameter is stored inside the component automatically,
-   * and the callback handler registered by `registerRoutes` will
-   * complete 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 - The URL Strava will redirect to after authorization
-   * @param opts.scope - Comma-separated Strava OAuth scopes (default: "read,activity:read_all,profile:read_all")
-   * @returns `{ authUrl, state }`
-   *
-   * @example
-   * ```ts
-   * const { authUrl } = await soma.getStravaAuthUrl(ctx, {
-   *   userId: "user_123",
-   *   redirectUri: "https://your-app.convex.site/api/strava/callback",
-   * });
-   * // Redirect user to authUrl — the callback is handled automatically
-   * ```
-   */
-  async getStravaAuthUrl(
-    ctx: ActionCtx,
-    opts: { userId: string; redirectUri: string; scope?: string },
-  ) {
-    const config = this.requireStravaConfig();
-    return await ctx.runAction(this.component.strava.public.getStravaAuthUrl, {
-      clientId: config.clientId,
-      redirectUri: opts.redirectUri,
-      scope: opts.scope,
-      userId: opts.userId,
-    });
-  }
-
-
-  /**
-   * Sync activities from Strava for an already-connected user.
-   *
-   * Automatically refreshes the access token if expired. Fetches the
-   * athlete profile and activities, transforms them, and ingests into Soma.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.after - Only sync activities after this Unix epoch timestamp (for incremental sync)
-   * @returns `{ synced, errors }`
-   *
-   * @example
-   * ```ts
-   * export const syncStrava = action({
-   *   args: { userId: v.string() },
-   *   handler: async (ctx, { userId }) => {
-   *     return await soma.syncStrava(ctx, { userId });
-   *   },
-   * });
-   * ```
-   */
-  async syncStrava(
-    ctx: ActionCtx,
-    args: { userId: string; after?: number },
-  ) {
-    const config = this.requireStravaConfig();
-    return await ctx.runAction(this.component.strava.public.syncStrava, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Disconnect a user from Strava.
-   *
-   * Revokes the token at Strava (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
-   * export const disconnectStrava = action({
-   *   args: { userId: v.string() },
-   *   handler: async (ctx, { userId }) => {
-   *     await soma.disconnectStrava(ctx, { userId });
-   *   },
-   * });
-   * ```
-   */
-  async disconnectStrava(
-    ctx: ActionCtx,
-    args: { userId: string },
-  ) {
-    const config = this.requireStravaConfig();
-    return await ctx.runAction(this.component.strava.public.disconnectStrava, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  // ─── Garmin ──────────────────────────────────────────────────────
-
-  async getGarminAuthUrl(
-    ctx: ActionCtx,
-    opts: { userId: string; redirectUri?: string },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.getGarminAuthUrl, {
-      clientId: config.clientId,
-      redirectUri: opts.redirectUri,
-      userId: opts.userId,
-    });
-  }
-
-  async disconnectGarmin(
-    ctx: ActionCtx,
-    args: { userId: string },
-  ) {
-    return await ctx.runAction(this.component.garmin.public.disconnectGarmin, args);
-  }
-
-  async pullGarminActivities(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullActivities, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminDailies(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullDailies, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminSleep(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullSleep, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminBody(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullBody, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminMenstruation(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullMenstruation, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminBloodPressures(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullBloodPressures, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminSkinTemperature(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullSkinTemperature, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminUserMetrics(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullUserMetrics, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminHRV(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullHRV, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminStressDetails(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullStressDetails, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminPulseOx(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullPulseOx, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminRespiration(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullRespiration, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pullGarminAll(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      startTimeInSeconds?: number;
-      endTimeInSeconds?: number;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pullAll, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pushPlannedWorkoutToGarmin(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-      workoutProvider?: string;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pushPlannedWorkout, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pushWorkoutToGarmin(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-      workoutProvider?: string;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pushWorkout, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async pushScheduleToGarmin(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-      date?: string;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.pushSchedule, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async deleteWorkoutFromGarmin(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.deleteWorkout, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  async deleteScheduleFromGarmin(
-    ctx: ActionCtx,
-    args: {
-      userId: string;
-      plannedWorkoutId: string;
-    },
-  ) {
-    const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.deleteSchedule, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-}
-
-// ─── Shared Types ────────────────────────────────────────────────────────────
-
-/**
- * Common args shape for all ingestion methods.
- *
- * Requires `connectionId` and `userId` at minimum — additional fields
- * come from the transformer output (e.g., `metadata`, `calories_data`, etc.)
- * and are validated server-side by Convex validators.
- */
-type IngestArgs = {
-  connectionId: string;
-  userId: string;
-} & Record<string, unknown>;
-
-/**
- * Base args for time-range filtered queries.
- *
- * - `userId` is required for all health data queries.
- * - `startTime` / `endTime` are optional ISO-8601 bounds on `metadata.start_time`.
- */
-type TimeRangeArgs = {
-  userId: string;
-  startTime?: string;
-  endTime?: string;
-};
-
-/**
- * Args for list (collect-all) queries with optional ordering and limit.
- */
-type ListTimeRangeArgs = TimeRangeArgs & {
-  order?: "asc" | "desc";
-  limit?: number;
-};
-
-/**
- * Args for paginated queries with Convex pagination options.
- */
-type PaginateTimeRangeArgs = TimeRangeArgs & {
-  paginationOpts: { numItems: number; cursor: string | null };
-};
-
-// ─── Route Registration ──────────────────────────────────────────────────────
-
-/**
- * Per-provider options for `registerRoutes`.
- */
-export interface StravaOAuthOptions {
-  /** HTTP path for the OAuth callback. @default "/api/strava/callback" */
-  path?: string;
-  /** Override STRAVA_CLIENT_ID env var. */
-  clientId?: string;
-  /** Override STRAVA_CLIENT_SECRET env var. */
-  clientSecret?: string;
-  /** URL to redirect the user to after a successful connection. */
-  redirectTo?: string;
-  /** Called after Strava OAuth completes and the connection is established. */
-  onComplete?: (
-    ctx: GenericActionCtx<GenericDataModel>,
-    event: StravaConnectEvent,
-  ) => Promise<void>;
-}
-
-// ─── Strava Callback Event Types ────────────────────────────────────────────
-
-/** Data passed to `onComplete` after Strava OAuth completes. */
-export interface StravaConnectEvent {
-  provider: "STRAVA";
-  userId: string;
-  connectionId: string;
-}
-
-// ─── Garmin Callback Event Types ─────────────────────────────────────────────
-
-/** Data passed to `oauth.onComplete` after Garmin OAuth completes. */
-export interface GarminConnectEvent {
-  provider: "GARMIN";
-  userId: string;
-  connectionId: string;
-}
-
-/** Data passed to webhook `events` handlers and `onEvent` after data ingestion. */
-export interface GarminWebhookEvent {
-  dataType: string;
-  processed: number;
-  errors: Array<{ type: string; id: string; error: string }>;
-  /** Users whose data was affected by this webhook. */
-  affectedUsers: Array<{ userId: string; connectionId: string }>;
-}
-
-// ─── Garmin Route Options ───────────────────────────────────────────────────
-
-export interface GarminOAuthOptions {
-  /** HTTP path for the OAuth callback. @default "/api/garmin/callback" */
-  path?: string;
-  /** Override GARMIN_CLIENT_ID env var. */
-  clientId?: string;
-  /** Override GARMIN_CLIENT_SECRET env var. */
-  clientSecret?: string;
-  /** URL to redirect the user to after a successful connection. */
-  redirectTo?: string;
-  /** Called after Garmin OAuth completes and the connection is established. */
-  onComplete?: (
-    ctx: GenericActionCtx<GenericDataModel>,
-    event: GarminConnectEvent,
-  ) => Promise<void>;
-}
-
-/** Webhook endpoint names matching the Garmin API data types. */
-export type GarminWebhookEventName =
-  | "activities" | "activity-details" | "manually-updated-activities" | "move-iq"
-  | "blood-pressures" | "body-compositions" | "dailies" | "epochs"
-  | "health-snapshot" | "sleeps" | "hrv" | "stress" | "pulse-ox"
-  | "respiration" | "skin-temp" | "user-metrics" | "menstrual-cycle-tracking";
-
-/** Handler for a specific webhook event or the catch-all `onEvent`. */
-export type GarminWebhookHandler = (
-  ctx: GenericActionCtx<GenericDataModel>,
-  event: GarminWebhookEvent,
-) => Promise<void>;
-
-export interface GarminWebhookOptions {
-  /** Base path prefix for all webhook routes. @default "/api/garmin/webhook" */
-  basePath?: string;
-  /** Called after every webhook payload is processed, regardless of data type. */
-  onEvent?: GarminWebhookHandler;
-  /** Per-data-type handlers. Only subscribe to the types you care about. */
-  events?: Partial<Record<GarminWebhookEventName, GarminWebhookHandler>>;
-}
-
-export interface RegisterRoutesOptions {
-  strava?: {
-    /** OAuth callback configuration. */
-    oauth?: StravaOAuthOptions;
-  };
-  garmin?: {
-    /** OAuth callback configuration. */
-    oauth?: GarminOAuthOptions;
-    /** Webhook route configuration. Set to `false` to skip webhook registration. */
-    webhook?: GarminWebhookOptions | false;
-  };
 }
 
 /**
@@ -1444,14 +833,18 @@ export interface RegisterRoutesOptions {
  *       },
  *     },
  *     webhook: {
- *       onEvent: async (ctx, event) => {
- *         // Catch-all: runs for every webhook
- *         console.log(`Garmin ${event.dataType}: ${event.processed} processed`);
- *       },
+ *       // Only listed data types get an HTTP route registered.
+ *       // Pass a handler for custom logic, or `true` for default processing.
  *       events: {
  *         "activities": async (ctx, event) => {
- *           // Runs only for activity webhooks
+ *           // Custom side-effect after activity ingestion
  *         },
+ *         "sleeps": true,   // register route, default processing only
+ *         "dailies": true,
+ *       },
+ *       // Optional catch-all, runs for every registered event
+ *       onEvent: async (ctx, event) => {
+ *         console.log(`Garmin ${event.dataType}: ${event.items.length} items`);
  *       },
  *     },
  *   },
@@ -1466,268 +859,10 @@ export function registerRoutes(
   const registerAll = opts === undefined;
 
   if (registerAll || opts?.strava) {
-    const stravaOpts = opts?.strava ?? {};
-    const oauth = stravaOpts.oauth ?? {};
-    const path = oauth.path ?? STRAVA_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 Strava auth URL via getStravaAuthUrl.",
-            { status: 400 },
-          );
-        }
-
-        const clientId =
-          oauth.clientId ?? process.env.STRAVA_CLIENT_ID;
-        const clientSecret =
-          oauth.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
-
-        if (!clientId || !clientSecret) {
-          return new Response(
-            "Strava credentials not configured. Set STRAVA_CLIENT_ID and " +
-            "STRAVA_CLIENT_SECRET environment variables, or pass them to registerRoutes.",
-            { status: 500 },
-          );
-        }
-
-        let result: {
-          connectionId: string;
-          userId: string;
-        };
-        try {
-          result = await ctx.runAction(component.strava.public.completeStravaOAuth, {
-            code,
-            state,
-            clientId,
-            clientSecret,
-          });
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : "Unknown error";
-          return new Response(`Strava OAuth callback failed: ${message}`, {
-            status: 500,
-          });
-        }
-
-        if (oauth.onComplete) {
-          try {
-            await oauth.onComplete(ctx, {
-              provider: "STRAVA",
-              userId: result.userId,
-              connectionId: result.connectionId,
-            });
-          } catch (callbackError) {
-            console.error(
-              "[soma] strava 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 Strava!", {
-          status: 200,
-        });
-      }),
-    });
+    SomaStrava.registerRoutes(http, component, opts?.strava);
   }
 
   if (registerAll || opts?.garmin) {
-    const garminOpts = opts?.garmin ?? {};
-    const oauth = garminOpts.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 =
-          oauth.clientId ?? process.env.GARMIN_CLIENT_ID;
-        const clientSecret =
-          oauth.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,
-          }) as typeof result;
-        } 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 ──────────────────────────────────
-    if (garminOpts.webhook !== false) {
-      const webhookCfg = typeof garminOpts.webhook === "object" ? garminOpts.webhook : {};
-      const webhookBase = webhookCfg.basePath ?? GARMIN_WEBHOOK_BASE_PATH;
-
-      const webhookRoutes: Array<{
-        suffix: string;
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        action: FunctionReference<"action", "internal", { payload: any }>;
-      }> = [
-          // ACTIVITY category
-          { suffix: "/activities", action: component.garmin.webhooks.handleGarminWebhookActivities },
-          { suffix: "/activity-details", action: component.garmin.webhooks.handleGarminWebhookActivityDetails },
-          { suffix: "/manually-updated-activities", action: component.garmin.webhooks.handleGarminWebhookManuallyUpdatedActivities },
-          { suffix: "/move-iq", action: component.garmin.webhooks.handleGarminWebhookMoveIQ },
-          // HEALTH category
-          { suffix: "/blood-pressures", action: component.garmin.webhooks.handleGarminWebhookBloodPressures },
-          { suffix: "/body-compositions", action: component.garmin.webhooks.handleGarminWebhookBodyCompositions },
-          { suffix: "/dailies", action: component.garmin.webhooks.handleGarminWebhookDailies },
-          { suffix: "/epochs", action: component.garmin.webhooks.handleGarminWebhookEpochs },
-          { suffix: "/health-snapshot", action: component.garmin.webhooks.handleGarminWebhookHealthSnapshot },
-          { suffix: "/sleeps", action: component.garmin.webhooks.handleGarminWebhookSleeps },
-          { suffix: "/hrv", action: component.garmin.webhooks.handleGarminWebhookHRVSummary },
-          { suffix: "/stress", action: component.garmin.webhooks.handleGarminWebhookStress },
-          { suffix: "/pulse-ox", action: component.garmin.webhooks.handleGarminWebhookPulseOx },
-          { suffix: "/respiration", action: component.garmin.webhooks.handleGarminWebhookRespiration },
-          { suffix: "/skin-temp", action: component.garmin.webhooks.handleGarminWebhookSkinTemp },
-          { suffix: "/user-metrics", action: component.garmin.webhooks.handleGarminWebhookUserMetrics },
-          // WOMEN_HEALTH category
-          { suffix: "/menstrual-cycle-tracking", action: component.garmin.webhooks.handleGarminWebhookMenstrualCycleTracking },
-        ];
-
-      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 });
-            }
-
-            let result: { processed: number; errors: Array<{ type: string; id: string; error: string }>; affectedUsers: Array<{ userId: string; connectionId: string }> } | undefined;
-            try {
-              result = await ctx.runAction(route.action, { payload }) as typeof result;
-            } catch (error) {
-              // Log but return 200 to prevent Garmin from retrying
-              console.error(
-                `Garmin webhook error (${route.suffix}):`,
-                error instanceof Error ? error.message : error,
-              );
-            }
-
-            if (result) {
-              const dataType = route.suffix.slice(1) as GarminWebhookEventName;
-              const event: GarminWebhookEvent = {
-                dataType,
-                processed: result.processed,
-                errors: result.errors,
-                affectedUsers: result.affectedUsers,
-              };
-
-              const specificHandler = webhookCfg.events?.[dataType];
-              if (specificHandler) {
-                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 });
-          }),
-        });
-      }
-    }
+    SomaGarmin.registerRoutes(http, component, opts?.garmin);
   }
 }