@nativesquare/soma 0.9.4 → 0.10.1

package/src/client/index.ts

@@ -7,7 +7,6 @@ import {
   type GenericDataModel,
   type HttpRouter,
 } from "convex/server";
-import { buildAuthUrl } from "../strava/auth.js";
 
 export type SomaComponent = ComponentApi;
 
@@ -30,12 +29,6 @@ export interface SomaStravaConfig {
   clientId: string;
   /** Your Strava application's Client Secret. */
   clientSecret: string;
-  /**
-   * Base URL of the Strava API (without `/api/v3` suffix).
-   * Defaults to `https://www.strava.com`.
-   * Override to point at a mock server during development.
-   */
-  baseUrl?: string;
 }
 
 /**
@@ -73,7 +66,7 @@ export interface SomaGarminConfig {
  *
  * // Or with explicit Strava config:
  * // const soma = new Soma(components.soma, {
- * //   strava: { clientId: "...", clientSecret: "...", baseUrl: "..." },
+ * //   strava: { clientId: "...", clientSecret: "..." },
  * // });
  *
  * // Connect a user to a provider:
@@ -82,8 +75,11 @@ export interface SomaGarminConfig {
  *   provider: "GARMIN",
  * });
  *
- * // Connect via Strava (handles OAuth, token storage, and initial sync):
- * const result = await soma.connectStrava(ctx, { userId: "user_123", code: "..." });
+ * // Start Strava OAuth (redirects user, callback handled by registerRoutes):
+ * const { authUrl } = await soma.getStravaAuthUrl(ctx, {
+ *   userId: "user_123",
+ *   redirectUri: "https://your-app.convex.site/api/strava/callback",
+ * });
  * ```
  */
 export class Soma {
@@ -109,7 +105,6 @@ export class Soma {
     return {
       clientId,
       clientSecret,
-      baseUrl: process.env.STRAVA_BASE_URL,
     };
   }
 
@@ -885,76 +880,40 @@ export class Soma {
   // environment variables or the constructor.
 
   /**
-   * Build the Strava OAuth authorization URL.
+   * Generate a Strava OAuth authorization URL.
    *
-   * This is a pure computation (no DB or HTTP calls), so it doesn't need
-   * a Convex context. Redirect the user to this URL to begin the OAuth flow.
+   * 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")
-   * @param opts.state - Optional state parameter for CSRF protection
-   * @returns The authorization URL string
+   * @returns `{ authUrl, state }`
    *
    * @example
    * ```ts
-   * const url = soma.getStravaAuthUrl({
-   *   redirectUri: "https://your-app.com/api/strava/callback",
+   * 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
    * ```
    */
-  getStravaAuthUrl(opts: {
-    redirectUri: string;
-    scope?: string;
-    state?: string;
-  }): string {
+  async getStravaAuthUrl(
+    ctx: ActionCtx,
+    opts: { userId: string; redirectUri: string; scope?: string },
+  ) {
     const config = this.requireStravaConfig();
-    return buildAuthUrl({
+    return await ctx.runAction(this.component.strava.public.getStravaAuthUrl, {
       clientId: config.clientId,
       redirectUri: opts.redirectUri,
       scope: opts.scope,
-      state: opts.state,
-      baseUrl: config.baseUrl,
+      userId: opts.userId,
     });
   }
 
-  /**
-   * Handle the Strava OAuth callback.
-   *
-   * Exchanges the authorization code for tokens, creates/reactivates the
-   * Soma connection, stores tokens securely in the component, syncs the
-   * athlete profile, and syncs all activities.
-   *
-   * Call this from your OAuth callback endpoint after receiving the `code`
-   * query parameter from Strava.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.code - The authorization code from the OAuth callback
-   * @param args.includeStreams - Fetch detailed streams per activity (default: false)
-   * @returns `{ connectionId, synced, errors }`
-   *
-   * @example
-   * ```ts
-   * export const handleStravaCallback = action({
-   *   args: { userId: v.string(), code: v.string() },
-   *   handler: async (ctx, { userId, code }) => {
-   *     return await soma.connectStrava(ctx, { userId, code });
-   *   },
-   * });
-   * ```
-   */
-  async connectStrava(
-    ctx: ActionCtx,
-    args: { userId: string; code: string; includeStreams?: boolean },
-  ) {
-    const config = this.requireStravaConfig();
-    return await ctx.runAction(this.component.strava.public.connectStrava, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-      baseUrl: config.baseUrl,
-    });
-  }
 
   /**
    * Sync activities from Strava for an already-connected user.
@@ -964,7 +923,6 @@ export class Soma {
    *
    * @param ctx - Action context from the host app
    * @param args.userId - The host app's user identifier
-   * @param args.includeStreams - Fetch detailed streams per activity (default: false)
    * @param args.after - Only sync activities after this Unix epoch timestamp (for incremental sync)
    * @returns `{ synced, errors }`
    *
@@ -973,21 +931,20 @@ export class Soma {
    * export const syncStrava = action({
    *   args: { userId: v.string() },
    *   handler: async (ctx, { userId }) => {
-   *     return await soma.syncStrava(ctx, { userId, includeStreams: true });
+   *     return await soma.syncStrava(ctx, { userId });
    *   },
    * });
    * ```
    */
   async syncStrava(
     ctx: ActionCtx,
-    args: { userId: string; includeStreams?: boolean; after?: number },
+    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,
-      baseUrl: config.baseUrl,
     });
   }
 
@@ -1019,7 +976,6 @@ export class Soma {
       ...args,
       clientId: config.clientId,
       clientSecret: config.clientSecret,
-      baseUrl: config.baseUrl,
     });
   }
 
@@ -1031,20 +987,13 @@ export class Soma {
   /**
    * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
    *
-   * Returns the `authUrl` to redirect the user to, along with the `state`
-   * and `codeVerifier` used for the PKCE flow.
-   *
-   * If `userId` is provided, the PKCE state is stored inside the component
-   * automatically, and the callback handler registered by `registerRoutes`
-   * will complete the flow without further host-app intervention. This is
-   * the recommended approach.
-   *
-   * If `userId` is omitted, the host app must store the returned
-   * `codeVerifier` itself and pass it to `connectGarmin` manually.
+   * The PKCE state 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 Garmin will redirect to after authorization
-   * @param opts.userId - The host app's user identifier (required for `registerRoutes` flow)
    * @returns `{ authUrl, state, codeVerifier }`
    *
    * @example
@@ -1058,7 +1007,7 @@ export class Soma {
    */
   async getGarminAuthUrl(
     ctx: ActionCtx,
-    opts: { redirectUri?: string; userId?: string },
+    opts: { userId: string; redirectUri?: string },
   ) {
     const config = this.requireGarminConfig();
     return await ctx.runAction(this.component.garmin.public.getGarminAuthUrl, {
@@ -1068,73 +1017,208 @@ export class Soma {
     });
   }
 
-  /**
-   * Handle the Garmin OAuth 2.0 callback (manual flow).
-   *
-   * Exchanges the authorization code for tokens, creates/reactivates the
-   * Soma connection, stores tokens securely, and syncs the last 30 days
-   * of all data types.
-   *
-   * Call this from your OAuth callback endpoint after receiving the `code`
-   * query parameter from Garmin.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.userId - The host app's user identifier
-   * @param args.code - The authorization code from the callback
-   * @param args.codeVerifier - The PKCE code verifier from Step 1
-   * @param args.redirectUri - The redirect URI used in the authorization request
-   * @returns `{ connectionId, synced, errors }`
-   *
-   * @example
-   * ```ts
-   * export const handleGarminCallback = action({
-   *   args: {
-   *     userId: v.string(),
-   *     code: v.string(),
-   *     codeVerifier: v.string(),
-   *   },
-   *   handler: async (ctx, args) => {
-   *     return await soma.connectGarmin(ctx, args);
-   *   },
-   * });
-   * ```
-   */
-  async connectGarmin(
+  async pullGarminActivities(
     ctx: ActionCtx,
     args: {
       userId: string;
-      code: string;
-      codeVerifier: string;
-      redirectUri?: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
     },
   ) {
     const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.public.connectGarmin, {
+    return await ctx.runAction(this.component.garmin.public.pullActivities, {
       ...args,
       clientId: config.clientId,
       clientSecret: config.clientSecret,
     });
   }
 
-  /**
-   * Complete a Garmin OAuth 2.0 flow using stored pending state.
-   *
-   * This is called automatically by the `registerRoutes` callback handler.
-   * It looks up the pending OAuth state stored during `getGarminAuthUrl`,
-   * exchanges for tokens, creates the connection, and syncs data.
-   *
-   * @param ctx - Action context from the host app
-   * @param args.code - The authorization code from the callback query params
-   * @param args.state - The state parameter from the callback query params
-   * @param args.redirectUri - The redirect URI used in the authorization request
-   * @returns `{ connectionId, synced, errors }`
-   */
-  async completeGarminOAuth(
+  async pullGarminDailies(
     ctx: ActionCtx,
-    args: { code: string; state: string; redirectUri?: string },
+    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.completeGarminOAuth, {
+    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,
@@ -1253,28 +1337,38 @@ type PaginateTimeRangeArgs = TimeRangeArgs & {
 /**
  * Per-provider options for `registerRoutes`.
  */
-export interface StravaRouteOptions {
+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;
-  /** Override STRAVA_BASE_URL env var. */
-  baseUrl?: string;
   /** URL to redirect the user to after a successful connection. */
-  onSuccess?: string;
+  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 + initial sync. */
+/** Data passed to `oauth.onComplete` after Garmin OAuth completes. */
 export interface GarminConnectEvent {
   provider: "GARMIN";
   userId: string;
   connectionId: string;
-  synced: Record<string, number>;
-  errors: Array<{ type: string; id: string; error: string }>;
 }
 
 /** Data passed to webhook `events` handlers and `onEvent` after data ingestion. */
@@ -1297,7 +1391,7 @@ export interface GarminOAuthOptions {
   clientSecret?: string;
   /** URL to redirect the user to after a successful connection. */
   redirectTo?: string;
-  /** Called after Garmin OAuth completes and initial data sync finishes. */
+  /** Called after Garmin OAuth completes and the connection is established. */
   onComplete?: (
     ctx: GenericActionCtx<GenericDataModel>,
     event: GarminConnectEvent,
@@ -1327,7 +1421,10 @@ export interface GarminWebhookOptions {
 }
 
 export interface RegisterRoutesOptions {
-  strava?: StravaRouteOptions;
+  strava?: {
+    /** OAuth callback configuration. */
+    oauth?: StravaOAuthOptions;
+  };
   garmin?: {
     /** OAuth callback configuration. */
     oauth?: GarminOAuthOptions;
@@ -1341,8 +1438,8 @@ export interface RegisterRoutesOptions {
  *
  * Call this from your `convex/http.ts` to set up the callback endpoints
  * that Strava and Garmin redirect to after user authorization. The handlers
- * complete the OAuth exchange, create the connection, and sync data
- * automatically.
+ * complete the OAuth exchange, create the connection, and store tokens.
+ * The host app is responsible for calling sync separately.
  *
  * When called with no `opts`, registers both Strava and Garmin routes with
  * default paths and credentials from environment variables. When `opts` is
@@ -1369,14 +1466,23 @@ export interface RegisterRoutesOptions {
  * // With Garmin OAuth callbacks and per-type webhook handlers
  * registerRoutes(http, components.soma, {
  *   strava: {
- *     path: "/oauth/strava/callback",
- *     onSuccess: "https://myapp.com/settings",
+ *     oauth: {
+ *       path: "/oauth/strava/callback",
+ *       redirectTo: "https://myapp.com/settings",
+ *       onComplete: async (ctx, event) => {
+ *         // Runs after OAuth completes and connection is established
+ *         await ctx.runMutation(internal.users.markConnected, {
+ *           userId: event.userId,
+ *           provider: event.provider,
+ *         });
+ *       },
+ *     },
  *   },
  *   garmin: {
  *     oauth: {
  *       redirectTo: "https://myapp.com/settings",
  *       onComplete: async (ctx, event) => {
- *         // Runs after OAuth + initial sync completes
+ *         // Runs after OAuth completes and connection is established
  *         await ctx.runMutation(internal.users.markConnected, {
  *           userId: event.userId,
  *           provider: event.provider,
@@ -1406,8 +1512,9 @@ export function registerRoutes(
   const registerAll = opts === undefined;
 
   if (registerAll || opts?.strava) {
-    const strava = opts?.strava ?? {};
-    const path = strava.path ?? STRAVA_CALLBACK_PATH;
+    const stravaOpts = opts?.strava ?? {};
+    const oauth = stravaOpts.oauth ?? {};
+    const path = oauth.path ?? STRAVA_CALLBACK_PATH;
 
     http.route({
       path,
@@ -1415,23 +1522,23 @@ export function registerRoutes(
       handler: httpActionGeneric(async (ctx, request) => {
         const url = new URL(request.url);
         const code = url.searchParams.get("code");
-        const userId = url.searchParams.get("state");
+        const state = url.searchParams.get("state");
 
         if (!code) {
           return new Response("Missing authorization code", { status: 400 });
         }
-        if (!userId) {
+        if (!state) {
           return new Response(
-            "Missing state parameter (userId). Pass the userId as the state " +
-            "parameter when building the Strava auth URL.",
+            "Missing state parameter. Ensure the state was included " +
+            "when building the Strava auth URL via getStravaAuthUrl.",
             { status: 400 },
           );
         }
 
         const clientId =
-          strava.clientId ?? process.env.STRAVA_CLIENT_ID;
+          oauth.clientId ?? process.env.STRAVA_CLIENT_ID;
         const clientSecret =
-          strava.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
+          oauth.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
 
         if (!clientId || !clientSecret) {
           return new Response(
@@ -1441,13 +1548,16 @@ export function registerRoutes(
           );
         }
 
+        let result: {
+          connectionId: string;
+          userId: string;
+        };
         try {
-          await ctx.runAction(component.strava.public.connectStrava, {
-            userId,
+          result = await ctx.runAction(component.strava.public.completeStravaOAuth, {
             code,
+            state,
             clientId,
             clientSecret,
-            baseUrl: strava.baseUrl ?? process.env.STRAVA_BASE_URL,
           });
         } catch (error) {
           const message =
@@ -1457,10 +1567,25 @@ export function registerRoutes(
           });
         }
 
-        if (strava.onSuccess) {
+        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: strava.onSuccess },
+            headers: { Location: oauth.redirectTo },
           });
         }
 
@@ -1513,8 +1638,6 @@ export function registerRoutes(
         let result: {
           connectionId: string;
           userId: string;
-          synced: Record<string, number>;
-          errors: Array<{ type: string; id: string; error: string }>;
         };
         try {
           result = await ctx.runAction(component.garmin.public.completeGarminOAuth, {
@@ -1537,8 +1660,6 @@ export function registerRoutes(
               provider: "GARMIN",
               userId: result.userId,
               connectionId: result.connectionId,
-              synced: result.synced,
-              errors: result.errors,
             });
           } catch (callbackError) {
             console.error(