@nativesquare/soma 0.11.0 → 0.12.0

package/src/client/index.ts

@@ -1,12 +1,44 @@
 import type { ComponentApi } from "../component/_generated/component.js";
-import type { ActionCtx, MutationCtx, QueryCtx } from "./types.js";
+import type {
+  MutationCtx,
+  QueryCtx,
+  SomaStravaConfig,
+  SomaGarminConfig,
+  IngestArgs,
+  ListTimeRangeArgs,
+  PaginateTimeRangeArgs,
+  RegisterRoutesOptions,
+  GarminWebhookEventName,
+  GarminWebhookEvent,
+} from "./types.js";
+export type {
+  ActionCtx,
+  SomaStravaConfig,
+  SomaGarminConfig,
+  IngestArgs,
+  TimeRangeArgs,
+  ListTimeRangeArgs,
+  PaginateTimeRangeArgs,
+  StravaOAuthOptions,
+  StravaConnectEvent,
+  GarminConnectEvent,
+  GarminWebhookEvent,
+  GarminOAuthOptions,
+  GarminWebhookEventName,
+  GarminWebhookHandler,
+  GarminWebhookOptions,
+  RegisterRoutesOptions,
+} from "./types.js";
 import {
   httpActionGeneric,
   type FunctionReference,
-  type GenericActionCtx,
-  type GenericDataModel,
   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 type SomaComponent = ComponentApi;
 
@@ -17,34 +49,6 @@ 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 +56,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 +65,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 +156,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 +761,7 @@ export class Soma {
   ) {
     return await ctx.runMutation(
       this.component.public.deletePlannedWorkout,
-      args as never,
+      args,
     );
   }
 
@@ -828,563 +777,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 +840,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.processed} processed`);
  *       },
  *     },
  *   },
@@ -1637,8 +1037,8 @@ export function registerRoutes(
     });
 
     // ── Garmin Webhook Routes ──────────────────────────────────
-    if (garminOpts.webhook !== false) {
-      const webhookCfg = typeof garminOpts.webhook === "object" ? garminOpts.webhook : {};
+    const webhookCfg = typeof garminOpts.webhook === "object" ? garminOpts.webhook : undefined;
+    if (webhookCfg?.events) {
       const webhookBase = webhookCfg.basePath ?? GARMIN_WEBHOOK_BASE_PATH;
 
       const webhookRoutes: Array<{
@@ -1669,6 +1069,11 @@ export function registerRoutes(
         ];
 
       for (const route of webhookRoutes) {
+        const dataType = route.suffix.slice(1) as GarminWebhookEventName;
+
+        // Only register routes the host app explicitly opted into
+        if (!webhookCfg.events?.[dataType]) continue;
+
         http.route({
           path: `${webhookBase}${route.suffix}`,
           method: "POST",
@@ -1692,7 +1097,6 @@ export function registerRoutes(
             }
 
             if (result) {
-              const dataType = route.suffix.slice(1) as GarminWebhookEventName;
               const event: GarminWebhookEvent = {
                 dataType,
                 processed: result.processed,
@@ -1701,7 +1105,7 @@ export function registerRoutes(
               };
 
               const specificHandler = webhookCfg.events?.[dataType];
-              if (specificHandler) {
+              if (typeof specificHandler === "function") {
                 try {
                   await specificHandler(ctx, event);
                 } catch (callbackError) {