@nativesquare/soma 0.5.0 → 0.7.0

package/src/client/index.ts

@@ -35,14 +35,14 @@ export interface SomaStravaConfig {
  * Configuration for the Garmin integration.
  *
  * If not provided to the constructor, the Soma class will attempt to
- * read `GARMIN_CONSUMER_KEY` and `GARMIN_CONSUMER_SECRET` from
+ * read `GARMIN_CLIENT_ID` and `GARMIN_CLIENT_SECRET` from
  * environment variables automatically.
  */
 export interface SomaGarminConfig {
-  /** Your Garmin application's Consumer Key. */
-  consumerKey: string;
-  /** Your Garmin application's Consumer Secret. */
-  consumerSecret: string;
+  /** Your Garmin application's Client ID. */
+  clientId: string;
+  /** Your Garmin application's Client Secret. */
+  clientSecret: string;
 }
 
 /**
@@ -125,10 +125,10 @@ export class Soma {
    * Returns undefined if the required vars are not set.
    */
   private readGarminEnv(): SomaGarminConfig | undefined {
-    const consumerKey = process.env.GARMIN_CONSUMER_KEY;
-    const consumerSecret = process.env.GARMIN_CONSUMER_SECRET;
-    if (!consumerKey || !consumerSecret) return undefined;
-    return { consumerKey, consumerSecret };
+    const clientId = process.env.GARMIN_CLIENT_ID;
+    const clientSecret = process.env.GARMIN_CLIENT_SECRET;
+    if (!clientId || !clientSecret) return undefined;
+    return { clientId, clientSecret };
   }
 
   /**
@@ -137,9 +137,9 @@ export class Soma {
   private requireGarminConfig(): SomaGarminConfig {
     if (!this.garminConfig) {
       throw new Error(
-        "Garmin is not configured. Either set GARMIN_CONSUMER_KEY and " +
-        "GARMIN_CONSUMER_SECRET environment variables in the Convex dashboard, " +
-        "or pass { garmin: { consumerKey, consumerSecret } } to the Soma constructor.",
+        "Garmin is not configured. Either set GARMIN_CLIENT_ID and " +
+        "GARMIN_CLIENT_SECRET environment variables in the Convex dashboard, " +
+        "or pass { garmin: { clientId, clientSecret } } to the Soma constructor.",
       );
     }
     return this.garminConfig;
@@ -725,6 +725,153 @@ export class Soma {
     return await ctx.runQuery(this.component.public.getAthlete, args);
   }
 
+  // ── Planned Workouts ────────────────────────────────────────────────────────
+
+  /**
+   * Ingest a planned workout record.
+   *
+   * Upserts by `connectionId + metadata.id` when an id is present.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Planned workout data including connectionId, userId, metadata, and steps
+   * @returns The planned workout document ID
+   */
+  async ingestPlannedWorkout(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestPlannedWorkout,
+      args as never,
+    );
+  }
+
+  /**
+   * List planned workout records for a user, optionally filtered by planned date range.
+   *
+   * @param ctx - Query context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startDate - Optional lower bound (inclusive) on metadata.planned_date (YYYY-MM-DD)
+   * @param args.endDate - Optional upper bound (inclusive) on metadata.planned_date (YYYY-MM-DD)
+   * @param args.order - Sort order: "asc" or "desc" (default: "desc")
+   * @param args.limit - Optional max number of results to return
+   */
+  async listPlannedWorkouts(
+    ctx: QueryCtx,
+    args: {
+      userId: string;
+      startDate?: string;
+      endDate?: string;
+      order?: "asc" | "desc";
+      limit?: number;
+    },
+  ) {
+    return await ctx.runQuery(
+      this.component.public.listPlannedWorkouts,
+      args,
+    );
+  }
+
+  /**
+   * Paginate planned workout records for a user, optionally filtered by planned date range.
+   *
+   * Returns `{ page, isDone, continueCursor }` for cursor-based pagination.
+   *
+   * @param ctx - Query context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startDate - Optional lower bound (inclusive) on metadata.planned_date
+   * @param args.endDate - Optional upper bound (inclusive) on metadata.planned_date
+   * @param args.paginationOpts - Convex pagination options `{ numItems, cursor }`
+   */
+  async paginatePlannedWorkouts(
+    ctx: QueryCtx,
+    args: {
+      userId: string;
+      startDate?: string;
+      endDate?: string;
+      paginationOpts: { numItems: number; cursor: string | null };
+    },
+  ) {
+    return await ctx.runQuery(
+      this.component.public.paginatePlannedWorkouts,
+      args,
+    );
+  }
+
+  /**
+   * Delete a planned workout by document ID.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.plannedWorkoutId - The planned workout document ID
+   */
+  async deletePlannedWorkout(
+    ctx: MutationCtx,
+    args: { plannedWorkoutId: string },
+  ) {
+    return await ctx.runMutation(
+      this.component.public.deletePlannedWorkout,
+      args as never,
+    );
+  }
+
+  /**
+   * Get a single planned workout by document ID.
+   *
+   * @param ctx - Query context from the host app
+   * @param args.plannedWorkoutId - The planned workout document ID
+   */
+  async getPlannedWorkout(
+    ctx: QueryCtx,
+    args: { plannedWorkoutId: string },
+  ) {
+    return await ctx.runQuery(
+      this.component.public.getPlannedWorkout,
+      args as never,
+    );
+  }
+
+  /**
+   * Push a planned workout to Garmin Connect.
+   *
+   * Creates the workout on Garmin's Training API and optionally schedules it
+   * to the user's calendar if `metadata.planned_date` is set. The workout
+   * will appear on the user's Garmin device after they sync.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   * @param args.workoutProvider - Name shown to user in Garmin Connect (default: "Soma", 20 chars max)
+   * @returns `{ garminWorkoutId, garminScheduleId }`
+   *
+   * @example
+   * ```ts
+   * export const pushWorkout = action({
+   *   args: { userId: v.string(), workoutId: v.string() },
+   *   handler: async (ctx, { userId, workoutId }) => {
+   *     return await soma.pushPlannedWorkoutToGarmin(ctx, {
+   *       userId,
+   *       plannedWorkoutId: workoutId,
+   *     });
+   *   },
+   * });
+   * ```
+   */
+  async pushPlannedWorkoutToGarmin(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+      workoutProvider?: string;
+    },
+  ) {
+    const config = this.requireGarminConfig();
+    return await ctx.runAction(this.component.garmin.pushPlannedWorkout, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
   // ─── Strava Integration ──────────────────────────────────────────────────────
   // High-level methods that handle OAuth, token storage, and data syncing
   // for Strava. Requires Strava credentials to be configured either via
@@ -870,68 +1017,65 @@ export class Soma {
   }
 
   // ─── Garmin Integration ──────────────────────────────────────────────────────
-  // High-level methods that handle OAuth 1.0a, token storage, and data syncing
-  // for Garmin. Requires Garmin credentials to be configured either via
-  // environment variables or the constructor.
+  // High-level methods that handle OAuth 2.0 PKCE, token storage, and data
+  // syncing for Garmin. Requires Garmin credentials to be configured either
+  // via environment variables or the constructor.
 
   /**
-   * Step 1 of the Garmin OAuth 1.0a flow: obtain a request token.
+   * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
    *
-   * Returns the temporary `token`, `tokenSecret`, and the `authUrl` to
-   * redirect the user to.
+   * Returns the `authUrl` to redirect the user to, along with the `state`
+   * and `codeVerifier` used for the PKCE flow.
    *
-   * If `userId` is provided, the pending OAuth 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 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 `token` and `tokenSecret`
-   * itself and pass them to `connectGarmin` manually.
+   * If `userId` is omitted, the host app must store the returned
+   * `codeVerifier` itself and pass it to `connectGarmin` manually.
    *
    * @param ctx - Action context from the host app
-   * @param opts.callbackUrl - The URL Garmin will redirect to after authorization
+   * @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 `{ token, tokenSecret, authUrl }`
+   * @returns `{ authUrl, state, codeVerifier }`
    *
    * @example
    * ```ts
-   * // Recommended: pass userId so registerRoutes can handle the callback
-   * const { authUrl } = await soma.getGarminRequestToken(ctx, {
+   * const { authUrl } = await soma.getGarminAuthUrl(ctx, {
    *   userId: "user_123",
-   *   callbackUrl: "https://your-app.convex.site/api/garmin/callback",
+   *   redirectUri: "https://your-app.convex.site/api/garmin/callback",
    * });
    * // Redirect user to authUrl — the callback is handled automatically
    * ```
    */
-  async getGarminRequestToken(
+  async getGarminAuthUrl(
     ctx: ActionCtx,
-    opts: { callbackUrl?: string; userId?: string },
+    opts: { redirectUri?: string; userId?: string },
   ) {
     const config = this.requireGarminConfig();
-    return await ctx.runAction(this.component.garmin.getGarminRequestToken, {
-      consumerKey: config.consumerKey,
-      consumerSecret: config.consumerSecret,
-      callbackUrl: opts.callbackUrl,
+    return await ctx.runAction(this.component.garmin.getGarminAuthUrl, {
+      clientId: config.clientId,
+      redirectUri: opts.redirectUri,
       userId: opts.userId,
     });
   }
 
   /**
-   * Step 3 of the Garmin OAuth 1.0a flow + initial data sync.
+   * Handle the Garmin OAuth 2.0 callback (manual flow).
    *
-   * Exchanges the request token + verifier for permanent access tokens,
-   * creates/reactivates the Soma connection, stores tokens securely,
-   * and syncs the last 30 days of all data types (activities, dailies,
-   * sleep, body composition, menstruation).
+   * 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
-   * `oauth_verifier` query parameter from Garmin.
+   * 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.token - The request token from Step 1
-   * @param args.tokenSecret - The request token secret from Step 1
-   * @param args.verifier - The oauth_verifier from the callback
+   * @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
@@ -939,9 +1083,8 @@ export class Soma {
    * export const handleGarminCallback = action({
    *   args: {
    *     userId: v.string(),
-   *     token: v.string(),
-   *     tokenSecret: v.string(),
-   *     verifier: v.string(),
+   *     code: v.string(),
+   *     codeVerifier: v.string(),
    *   },
    *   handler: async (ctx, args) => {
    *     return await soma.connectGarmin(ctx, args);
@@ -953,40 +1096,41 @@ export class Soma {
     ctx: ActionCtx,
     args: {
       userId: string;
-      token: string;
-      tokenSecret: string;
-      verifier: string;
+      code: string;
+      codeVerifier: string;
+      redirectUri?: string;
     },
   ) {
     const config = this.requireGarminConfig();
     return await ctx.runAction(this.component.garmin.connectGarmin, {
       ...args,
-      consumerKey: config.consumerKey,
-      consumerSecret: config.consumerSecret,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
     });
   }
 
   /**
-   * Complete a Garmin OAuth flow using stored pending state.
+   * 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 `getGarminRequestToken`,
-   * exchanges for permanent tokens, creates the connection, and syncs data.
+   * 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.oauthToken - The oauth_token from the callback query params
-   * @param args.oauthVerifier - The oauth_verifier from the callback query params
+   * @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(
     ctx: ActionCtx,
-    args: { oauthToken: string; oauthVerifier: string },
+    args: { code: string; state: string; redirectUri?: string },
   ) {
     const config = this.requireGarminConfig();
     return await ctx.runAction(this.component.garmin.completeGarminOAuth, {
       ...args,
-      consumerKey: config.consumerKey,
-      consumerSecret: config.consumerSecret,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
     });
   }
 
@@ -995,6 +1139,7 @@ export class Soma {
    *
    * Fetches activities, dailies, sleep, body composition, and menstruation
    * data for the specified time range (defaults to last 30 days).
+   * Automatically refreshes expired tokens.
    *
    * @param ctx - Action context from the host app
    * @param args.userId - The host app's user identifier
@@ -1023,17 +1168,16 @@ export class Soma {
     const config = this.requireGarminConfig();
     return await ctx.runAction(this.component.garmin.syncGarmin, {
       ...args,
-      consumerKey: config.consumerKey,
-      consumerSecret: config.consumerSecret,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
     });
   }
 
   /**
    * Disconnect a user from Garmin.
    *
-   * Deletes stored tokens and sets the connection to inactive.
-   * Garmin OAuth 1.0a tokens cannot be revoked via API, so cleanup
-   * is local only.
+   * Deregisters the user at Garmin (best-effort), deletes stored tokens,
+   * and sets the connection to inactive.
    *
    * @param ctx - Action context from the host app
    * @param args.userId - The host app's user identifier
@@ -1118,10 +1262,10 @@ export interface StravaRouteOptions {
 export interface GarminRouteOptions {
   /** HTTP path for the OAuth callback. @default "/api/garmin/callback" */
   path?: string;
-  /** Override GARMIN_CONSUMER_KEY env var. */
-  consumerKey?: string;
-  /** Override GARMIN_CONSUMER_SECRET env var. */
-  consumerSecret?: 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. */
   onSuccess?: string;
 }
@@ -1256,34 +1400,41 @@ export function registerRoutes(
       method: "GET",
       handler: httpActionGeneric(async (ctx, request) => {
         const url = new URL(request.url);
-        const oauthToken = url.searchParams.get("oauth_token");
-        const oauthVerifier = url.searchParams.get("oauth_verifier");
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
 
-        if (!oauthToken || !oauthVerifier) {
-          return new Response("Missing oauth_token or oauth_verifier", {
+        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 consumerKey =
-          garmin.consumerKey ?? process.env.GARMIN_CONSUMER_KEY;
-        const consumerSecret =
-          garmin.consumerSecret ?? process.env.GARMIN_CONSUMER_SECRET;
+        const clientId =
+          garmin.clientId ?? process.env.GARMIN_CLIENT_ID;
+        const clientSecret =
+          garmin.clientSecret ?? process.env.GARMIN_CLIENT_SECRET;
 
-        if (!consumerKey || !consumerSecret) {
+        if (!clientId || !clientSecret) {
           return new Response(
-            "Garmin credentials not configured. Set GARMIN_CONSUMER_KEY and " +
-              "GARMIN_CONSUMER_SECRET environment variables, or pass them to registerRoutes.",
+            "Garmin credentials not configured. Set GARMIN_CLIENT_ID and " +
+              "GARMIN_CLIENT_SECRET environment variables, or pass them to registerRoutes.",
             { status: 500 },
           );
         }
 
         try {
           await ctx.runAction(component.garmin.completeGarminOAuth, {
-            oauthToken,
-            oauthVerifier,
-            consumerKey,
-            consumerSecret,
+            code,
+            state,
+            clientId,
+            clientSecret,
           });
         } catch (error) {
           const message =