@nativesquare/soma 0.10.0 → 0.10.2

package/src/client/index.ts

@@ -75,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 {
@@ -879,18 +882,14 @@ export class Soma {
   /**
    * Generate a Strava OAuth authorization URL.
    *
-   * If `userId` is provided, 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. This is the recommended approach.
-   *
-   * If `userId` is omitted, the host app must store the returned `state`
-   * itself and handle the callback via `connectStrava`.
+   * 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.userId - The host app's user identifier (required for `registerRoutes` flow)
    * @returns `{ authUrl, state }`
    *
    * @example
@@ -904,7 +903,7 @@ export class Soma {
    */
   async getStravaAuthUrl(
     ctx: ActionCtx,
-    opts: { redirectUri: string; scope?: string; userId?: string },
+    opts: { userId: string; redirectUri: string; scope?: string },
   ) {
     const config = this.requireStravaConfig();
     return await ctx.runAction(this.component.strava.public.getStravaAuthUrl, {
@@ -915,69 +914,6 @@ export class Soma {
     });
   }
 
-  /**
-   * 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
-   * @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 },
-  ) {
-    const config = this.requireStravaConfig();
-    return await ctx.runAction(this.component.strava.public.connectStrava, {
-      ...args,
-      clientId: config.clientId,
-      clientSecret: config.clientSecret,
-    });
-  }
-
-  /**
-   * Complete a Strava OAuth flow using stored pending state.
-   *
-   * This is called automatically by the `registerRoutes` callback handler.
-   * It looks up the pending OAuth state stored during `getStravaAuthUrl`,
-   * 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
-   * @returns `{ connectionId, userId, synced, errors }`
-   */
-  async completeStravaOAuth(
-    ctx: ActionCtx,
-    args: { code: string; state: string },
-  ) {
-    const config = this.requireStravaConfig();
-    return await ctx.runAction(
-      this.component.strava.public.completeStravaOAuth,
-      {
-        ...args,
-        clientId: config.clientId,
-        clientSecret: config.clientSecret,
-      },
-    );
-  }
 
   /**
    * Sync activities from Strava for an already-connected user.
@@ -1051,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
@@ -1078,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, {
@@ -1088,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: {
+      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: { 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.completeGarminOAuth, {
+    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,
@@ -1282,7 +1346,7 @@ export interface StravaOAuthOptions {
   clientSecret?: string;
   /** URL to redirect the user to after a successful connection. */
   redirectTo?: string;
-  /** Called after Strava OAuth completes and initial data sync finishes. */
+  /** Called after Strava OAuth completes and the connection is established. */
   onComplete?: (
     ctx: GenericActionCtx<GenericDataModel>,
     event: StravaConnectEvent,
@@ -1291,24 +1355,20 @@ export interface StravaOAuthOptions {
 
 // ─── Strava Callback Event Types ────────────────────────────────────────────
 
-/** Data passed to `onComplete` after Strava OAuth + initial sync. */
+/** Data passed to `onComplete` after Strava OAuth completes. */
 export interface StravaConnectEvent {
   provider: "STRAVA";
   userId: string;
   connectionId: string;
-  synced: Record<string, number>;
-  errors: Array<{ type: string; id: string; error: 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. */
@@ -1331,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,
@@ -1378,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
@@ -1410,7 +1470,7 @@ export interface RegisterRoutesOptions {
  *       path: "/oauth/strava/callback",
  *       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,
@@ -1422,7 +1482,7 @@ export interface RegisterRoutesOptions {
  *     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,
@@ -1491,8 +1551,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.strava.public.completeStravaOAuth, {
@@ -1515,8 +1573,6 @@ export function registerRoutes(
               provider: "STRAVA",
               userId: result.userId,
               connectionId: result.connectionId,
-              synced: result.synced,
-              errors: result.errors,
             });
           } catch (callbackError) {
             console.error(
@@ -1582,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, {
@@ -1606,8 +1660,6 @@ export function registerRoutes(
               provider: "GARMIN",
               userId: result.userId,
               connectionId: result.connectionId,
-              synced: result.synced,
-              errors: result.errors,
             });
           } catch (callbackError) {
             console.error(