@nativesquare/soma 0.5.0 → 0.6.0

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/NativeSquare/soma/issues"
   },
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "Apache-2.0",
   "keywords": [
     "convex",

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;
@@ -870,68 +870,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 +936,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 +949,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 +992,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 +1021,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 +1115,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 +1253,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 =

package/src/component/_generated/component.ts

@@ -28,10 +28,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          consumerKey: string;
-          consumerSecret: string;
-          oauthToken: string;
-          oauthVerifier: string;
+          clientId: string;
+          clientSecret: string;
+          code: string;
+          redirectUri?: string;
+          state: string;
         },
         {
           connectionId: string;
@@ -50,12 +51,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         "action",
         "internal",
         {
-          consumerKey: string;
-          consumerSecret: string;
-          token: string;
-          tokenSecret: string;
+          clientId: string;
+          clientSecret: string;
+          code: string;
+          codeVerifier: string;
+          redirectUri?: string;
           userId: string;
-          verifier: string;
         },
         {
           connectionId: string;
@@ -77,24 +78,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         null,
         Name
       >;
-      getGarminRequestToken: FunctionReference<
+      getGarminAuthUrl: FunctionReference<
         "action",
         "internal",
-        {
-          callbackUrl?: string;
-          consumerKey: string;
-          consumerSecret: string;
-          userId?: string;
-        },
-        { authUrl: string; token: string; tokenSecret: string },
+        { clientId: string; redirectUri?: string; userId?: string },
+        { authUrl: string; codeVerifier: string; state: string },
         Name
       >;
       syncGarmin: FunctionReference<
         "action",
         "internal",
         {
-          consumerKey: string;
-          consumerSecret: string;
+          clientId: string;
+          clientSecret: string;
           endTimeInSeconds?: number;
           startTimeInSeconds?: number;
           userId: string;