@nativesquare/soma 0.6.0 → 0.7.0

package/dist/component/garmin.js

@@ -1,5 +1,5 @@
 // ─── Garmin Component Actions ────────────────────────────────────────────────
-// Public actions that handle the full Garmin OAuth + sync lifecycle.
+// Public actions that handle the full Garmin OAuth 2.0 PKCE + sync lifecycle.
 // The host app calls these through the Soma class, which threads the
 // credentials automatically from env vars or constructor config.
 //
@@ -7,13 +7,14 @@
 import { v } from "convex/values";
 import { anyApi } from "convex/server";
 import { action, internalMutation, internalQuery, } from "./_generated/server.js";
-import { getRequestToken, getAccessToken } from "../garmin/auth.js";
+import { generateCodeVerifier, generateCodeChallenge, generateState, buildAuthUrl, exchangeCode, refreshToken, } from "../garmin/auth.js";
 import { GarminClient } from "../garmin/client.js";
 import { transformActivity } from "../garmin/activity.js";
 import { transformDaily } from "../garmin/daily.js";
 import { transformSleep } from "../garmin/sleep.js";
 import { transformBody } from "../garmin/body.js";
 import { transformMenstruation } from "../garmin/menstruation.js";
+import { transformPlannedWorkoutToGarmin } from "../garmin/plannedWorkout.js";
 // Use anyApi to avoid circular type references between this file and _generated/api.ts.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const publicApi = anyApi;
@@ -21,14 +22,16 @@ const publicApi = anyApi;
 const internalApi = anyApi;
 // Default sync window: last 30 days
 const DEFAULT_SYNC_DAYS = 30;
+// Refresh buffer: refresh tokens 10 minutes before expiry
+const REFRESH_BUFFER_SECONDS = 600;
 // ─── Internal Pending OAuth CRUD ─────────────────────────────────────────────
-// Temporary storage for in-progress Garmin OAuth 1.0a flows.
-// Bridges Step 1 (getGarminRequestToken) and Step 3 (completeGarminOAuth).
+// Temporary storage for in-progress Garmin OAuth 2.0 PKCE flows.
+// Bridges getGarminAuthUrl and completeGarminOAuth.
 export const storePendingOAuth = internalMutation({
     args: {
         provider: v.string(),
-        oauthToken: v.string(),
-        tokenSecret: v.string(),
+        state: v.string(),
+        codeVerifier: v.string(),
         userId: v.string(),
     },
     returns: v.null(),
@@ -41,30 +44,30 @@ export const storePendingOAuth = internalMutation({
     },
 });
 export const getPendingOAuth = internalQuery({
-    args: { oauthToken: v.string() },
+    args: { state: v.string() },
     returns: v.union(v.object({
         _id: v.id("pendingOAuth"),
         _creationTime: v.number(),
         provider: v.string(),
-        oauthToken: v.string(),
-        tokenSecret: v.string(),
+        state: v.string(),
+        codeVerifier: v.string(),
         userId: v.string(),
         createdAt: v.number(),
     }), v.null()),
     handler: async (ctx, args) => {
         return await ctx.db
             .query("pendingOAuth")
-            .withIndex("by_oauthToken", (q) => q.eq("oauthToken", args.oauthToken))
+            .withIndex("by_state", (q) => q.eq("state", args.state))
             .first();
     },
 });
 export const deletePendingOAuth = internalMutation({
-    args: { oauthToken: v.string() },
+    args: { state: v.string() },
     returns: v.null(),
     handler: async (ctx, args) => {
         const pending = await ctx.db
             .query("pendingOAuth")
-            .withIndex("by_oauthToken", (q) => q.eq("oauthToken", args.oauthToken))
+            .withIndex("by_state", (q) => q.eq("state", args.state))
             .first();
         if (pending) {
             await ctx.db.delete(pending._id);
@@ -74,14 +77,15 @@ export const deletePendingOAuth = internalMutation({
 });
 // ─── Internal Token CRUD ─────────────────────────────────────────────────────
 /**
- * Store OAuth 1.0a tokens for a Garmin connection.
+ * Store OAuth 2.0 tokens for a Garmin connection.
  * Upserts by connectionId — one token record per connection.
  */
 export const storeTokens = internalMutation({
     args: {
         connectionId: v.id("connections"),
         accessToken: v.string(),
-        tokenSecret: v.string(),
+        refreshToken: v.string(),
+        expiresAt: v.number(),
     },
     returns: v.null(),
     handler: async (ctx, args) => {
@@ -92,14 +96,16 @@ export const storeTokens = internalMutation({
         if (existing) {
             await ctx.db.patch(existing._id, {
                 accessToken: args.accessToken,
-                tokenSecret: args.tokenSecret,
+                refreshToken: args.refreshToken,
+                expiresAt: args.expiresAt,
             });
             return null;
         }
         await ctx.db.insert("providerTokens", {
             connectionId: args.connectionId,
             accessToken: args.accessToken,
-            tokenSecret: args.tokenSecret,
+            refreshToken: args.refreshToken,
+            expiresAt: args.expiresAt,
         });
         return null;
     },
@@ -115,7 +121,6 @@ export const getTokens = internalQuery({
         connectionId: v.id("connections"),
         accessToken: v.string(),
         refreshToken: v.optional(v.string()),
-        tokenSecret: v.optional(v.string()),
         expiresAt: v.optional(v.number()),
     }), v.null()),
     handler: async (ctx, args) => {
@@ -144,64 +149,62 @@ export const deleteTokens = internalMutation({
 });
 // ─── Public Actions ──────────────────────────────────────────────────────────
 /**
- * Step 1 of OAuth: obtain a request token and return the authorization URL.
+ * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
  *
- * If `userId` is provided, the request token and secret are stored in the
+ * If `userId` is provided, the PKCE code verifier and state are stored in the
  * component's `pendingOAuth` table so that `completeGarminOAuth` can look
  * them up automatically when the callback fires. This is the recommended
  * flow when using `registerRoutes`.
  *
- * If `userId` is omitted, the host app must store the returned `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.
  */
-export const getGarminRequestToken = action({
+export const getGarminAuthUrl = action({
     args: {
-        consumerKey: v.string(),
-        consumerSecret: v.string(),
-        callbackUrl: v.optional(v.string()),
+        clientId: v.string(),
+        redirectUri: v.optional(v.string()),
         userId: v.optional(v.string()),
     },
     returns: v.object({
-        token: v.string(),
-        tokenSecret: v.string(),
         authUrl: v.string(),
+        state: v.string(),
+        codeVerifier: v.string(),
     }),
     handler: async (ctx, args) => {
-        const result = await getRequestToken({
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
-            callbackUrl: args.callbackUrl,
+        const codeVerifier = generateCodeVerifier();
+        const codeChallenge = await generateCodeChallenge(codeVerifier);
+        const state = generateState();
+        const authUrl = buildAuthUrl({
+            clientId: args.clientId,
+            codeChallenge,
+            redirectUri: args.redirectUri,
+            state,
         });
         if (args.userId) {
             await ctx.runMutation(internalApi.garmin.storePendingOAuth, {
                 provider: "GARMIN",
-                oauthToken: result.oauthToken,
-                tokenSecret: result.oauthTokenSecret,
+                state,
+                codeVerifier,
                 userId: args.userId,
             });
         }
-        return {
-            token: result.oauthToken,
-            tokenSecret: result.oauthTokenSecret,
-            authUrl: result.authUrl,
-        };
+        return { authUrl, state, codeVerifier };
     },
 });
 /**
- * Step 3 of OAuth + initial sync.
+ * Exchange an authorization code for tokens + initial sync.
  *
- * Exchanges the request token + verifier for permanent access tokens,
- * creates/reactivates the Soma connection, stores tokens, and syncs
- * the last 30 days of all data types.
+ * Used in the manual flow where the host app stores the code verifier
+ * and handles the callback itself.
  */
 export const connectGarmin = action({
     args: {
         userId: v.string(),
-        consumerKey: v.string(),
-        consumerSecret: v.string(),
-        token: v.string(),
-        tokenSecret: v.string(),
-        verifier: v.string(),
+        clientId: v.string(),
+        clientSecret: v.string(),
+        code: v.string(),
+        codeVerifier: v.string(),
+        redirectUri: v.optional(v.string()),
     },
     returns: v.object({
         connectionId: v.string(),
@@ -215,31 +218,26 @@ export const connectGarmin = action({
         errors: v.array(v.object({ type: v.string(), id: v.string(), error: v.string() })),
     }),
     handler: async (ctx, args) => {
-        // 1. Exchange request token for permanent access token
-        const accessTokenResult = await getAccessToken({
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
-            token: args.token,
-            tokenSecret: args.tokenSecret,
-            verifier: args.verifier,
+        const tokenResult = await exchangeCode({
+            clientId: args.clientId,
+            clientSecret: args.clientSecret,
+            code: args.code,
+            codeVerifier: args.codeVerifier,
+            redirectUri: args.redirectUri,
         });
-        // 2. Create/reactivate the Soma connection
         const connectionId = await ctx.runMutation(publicApi.public.connect, {
             userId: args.userId,
             provider: "GARMIN",
         });
-        // 3. Store permanent OAuth tokens
+        const expiresAt = Math.floor(Date.now() / 1000) + tokenResult.expires_in;
         await ctx.runMutation(internalApi.garmin.storeTokens, {
             connectionId,
-            accessToken: accessTokenResult.oauthToken,
-            tokenSecret: accessTokenResult.oauthTokenSecret,
+            accessToken: tokenResult.access_token,
+            refreshToken: tokenResult.refresh_token,
+            expiresAt,
         });
-        // 4. Sync last 30 days of all data types
         const client = new GarminClient({
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
-            accessToken: accessTokenResult.oauthToken,
-            tokenSecret: accessTokenResult.oauthTokenSecret,
+            accessToken: tokenResult.access_token,
         });
         const now = Math.floor(Date.now() / 1000);
         const thirtyDaysAgo = now - DEFAULT_SYNC_DAYS * 86400;
@@ -250,11 +248,8 @@ export const connectGarmin = action({
         const result = await syncAllTypes(ctx, client, {
             connectionId,
             userId: args.userId,
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
             timeRange,
         });
-        // 5. Update lastDataUpdate timestamp
         await ctx.runMutation(publicApi.public.updateConnection, {
             connectionId,
             lastDataUpdate: new Date().toISOString(),
@@ -267,20 +262,21 @@ export const connectGarmin = action({
     },
 });
 /**
- * Complete a Garmin OAuth flow using stored pending state.
+ * Complete a Garmin OAuth 2.0 flow using stored pending state.
  *
  * Used by `registerRoutes` — the callback handler calls this with the
- * `oauth_token` and `oauth_verifier` from the redirect. The action looks
- * up the pending state (tokenSecret, userId) stored during Step 1,
- * exchanges for permanent tokens, creates the connection, syncs data,
- * and cleans up the pending entry.
+ * `code` and `state` from the redirect. The action looks up the pending
+ * state (codeVerifier, userId) stored during `getGarminAuthUrl`,
+ * exchanges for tokens, creates the connection, syncs data, and
+ * cleans up the pending entry.
  */
 export const completeGarminOAuth = action({
     args: {
-        oauthToken: v.string(),
-        oauthVerifier: v.string(),
-        consumerKey: v.string(),
-        consumerSecret: v.string(),
+        code: v.string(),
+        state: v.string(),
+        clientId: v.string(),
+        clientSecret: v.string(),
+        redirectUri: v.optional(v.string()),
     },
     returns: v.object({
         connectionId: v.string(),
@@ -294,43 +290,36 @@ export const completeGarminOAuth = action({
         errors: v.array(v.object({ type: v.string(), id: v.string(), error: v.string() })),
     }),
     handler: async (ctx, args) => {
-        // 1. Look up pending state
         const pending = await ctx.runQuery(internalApi.garmin.getPendingOAuth, {
-            oauthToken: args.oauthToken,
+            state: args.state,
         });
         if (!pending) {
-            throw new Error("No pending Garmin OAuth state found for this token. " +
-                "The request token may have expired or was already used.");
+            throw new Error("No pending Garmin OAuth state found for this state parameter. " +
+                "The authorization may have expired or was already used.");
         }
-        // 2. Exchange request token for permanent access token
-        const accessTokenResult = await getAccessToken({
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
-            token: args.oauthToken,
-            tokenSecret: pending.tokenSecret,
-            verifier: args.oauthVerifier,
+        const tokenResult = await exchangeCode({
+            clientId: args.clientId,
+            clientSecret: args.clientSecret,
+            code: args.code,
+            codeVerifier: pending.codeVerifier,
+            redirectUri: args.redirectUri,
         });
-        // 3. Delete pending state (no longer needed)
         await ctx.runMutation(internalApi.garmin.deletePendingOAuth, {
-            oauthToken: args.oauthToken,
+            state: args.state,
         });
-        // 4. Create/reactivate the Soma connection
         const connectionId = await ctx.runMutation(publicApi.public.connect, {
             userId: pending.userId,
             provider: "GARMIN",
         });
-        // 5. Store permanent OAuth tokens
+        const expiresAt = Math.floor(Date.now() / 1000) + tokenResult.expires_in;
         await ctx.runMutation(internalApi.garmin.storeTokens, {
             connectionId,
-            accessToken: accessTokenResult.oauthToken,
-            tokenSecret: accessTokenResult.oauthTokenSecret,
+            accessToken: tokenResult.access_token,
+            refreshToken: tokenResult.refresh_token,
+            expiresAt,
         });
-        // 6. Sync last 30 days of all data types
         const client = new GarminClient({
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
-            accessToken: accessTokenResult.oauthToken,
-            tokenSecret: accessTokenResult.oauthTokenSecret,
+            accessToken: tokenResult.access_token,
         });
         const now = Math.floor(Date.now() / 1000);
         const thirtyDaysAgo = now - DEFAULT_SYNC_DAYS * 86400;
@@ -341,11 +330,8 @@ export const completeGarminOAuth = action({
         const result = await syncAllTypes(ctx, client, {
             connectionId,
             userId: pending.userId,
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
             timeRange,
         });
-        // 7. Update lastDataUpdate timestamp
         await ctx.runMutation(publicApi.public.updateConnection, {
             connectionId,
             lastDataUpdate: new Date().toISOString(),
@@ -360,14 +346,14 @@ export const completeGarminOAuth = action({
 /**
  * Incremental Garmin sync for an already-connected user.
  *
- * Looks up the stored tokens and syncs all data types for the specified
- * time range (defaults to last 30 days).
+ * Looks up the stored tokens, refreshes if expired, and syncs all data
+ * types for the specified time range (defaults to last 30 days).
  */
 export const syncGarmin = action({
     args: {
         userId: v.string(),
-        consumerKey: v.string(),
-        consumerSecret: v.string(),
+        clientId: v.string(),
+        clientSecret: v.string(),
         startTimeInSeconds: v.optional(v.number()),
         endTimeInSeconds: v.optional(v.number()),
     },
@@ -382,7 +368,6 @@ export const syncGarmin = action({
         errors: v.array(v.object({ type: v.string(), id: v.string(), error: v.string() })),
     }),
     handler: async (ctx, args) => {
-        // 1. Look up connection
         const connection = await ctx.runQuery(internalApi.private.getConnectionByProvider, { userId: args.userId, provider: "GARMIN" });
         if (!connection) {
             throw new Error(`No Garmin connection found for user "${args.userId}". ` +
@@ -392,21 +377,34 @@ export const syncGarmin = action({
             throw new Error(`Garmin connection for user "${args.userId}" is inactive. Reconnect first.`);
         }
         const connectionId = connection._id;
-        // 2. Get stored tokens
         const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
             connectionId,
         });
-        if (!tokenDoc || !tokenDoc.tokenSecret) {
+        if (!tokenDoc) {
             throw new Error("No Garmin tokens found for this connection. " +
                 "The connection may have been created before token storage was available.");
         }
-        // 3. Create client and sync
-        const client = new GarminClient({
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
-            accessToken: tokenDoc.accessToken,
-            tokenSecret: tokenDoc.tokenSecret,
-        });
+        let accessToken = tokenDoc.accessToken;
+        // Refresh the token if it's expired or about to expire
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (tokenDoc.expiresAt &&
+            tokenDoc.refreshToken &&
+            nowSeconds >= tokenDoc.expiresAt - REFRESH_BUFFER_SECONDS) {
+            const refreshed = await refreshToken({
+                clientId: args.clientId,
+                clientSecret: args.clientSecret,
+                refreshToken: tokenDoc.refreshToken,
+            });
+            accessToken = refreshed.access_token;
+            const newExpiresAt = nowSeconds + refreshed.expires_in;
+            await ctx.runMutation(internalApi.garmin.storeTokens, {
+                connectionId,
+                accessToken: refreshed.access_token,
+                refreshToken: refreshed.refresh_token,
+                expiresAt: newExpiresAt,
+            });
+        }
+        const client = new GarminClient({ accessToken });
         const now = Math.floor(Date.now() / 1000);
         const timeRange = {
             uploadStartTimeInSeconds: args.startTimeInSeconds ?? now - DEFAULT_SYNC_DAYS * 86400,
@@ -415,11 +413,8 @@ export const syncGarmin = action({
         const result = await syncAllTypes(ctx, client, {
             connectionId,
             userId: args.userId,
-            consumerKey: args.consumerKey,
-            consumerSecret: args.consumerSecret,
             timeRange,
         });
-        // 4. Update lastDataUpdate timestamp
         await ctx.runMutation(publicApi.public.updateConnection, {
             connectionId,
             lastDataUpdate: new Date().toISOString(),
@@ -430,8 +425,8 @@ export const syncGarmin = action({
 /**
  * Disconnect a user from Garmin.
  *
- * Deletes stored tokens and sets the connection to inactive.
- * Garmin OAuth 1.0a tokens can't be revoked via API, so we just clean up locally.
+ * Deregisters the user via the Garmin API (best-effort), deletes stored
+ * tokens, and sets the connection to inactive.
  */
 export const disconnectGarmin = action({
     args: {
@@ -439,15 +434,25 @@ export const disconnectGarmin = action({
     },
     returns: v.null(),
     handler: async (ctx, args) => {
-        // 1. Look up connection
         const connection = await ctx.runQuery(internalApi.private.getConnectionByProvider, { userId: args.userId, provider: "GARMIN" });
         if (!connection) {
             throw new Error(`No Garmin connection found for user "${args.userId}".`);
         }
         const connectionId = connection._id;
-        // 2. Delete stored tokens
+        // Best-effort: deregister user at Garmin
+        const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
+            connectionId,
+        });
+        if (tokenDoc) {
+            try {
+                const client = new GarminClient({ accessToken: tokenDoc.accessToken });
+                await client.deleteUserRegistration();
+            }
+            catch {
+                // Deregistration is best-effort; proceed with local cleanup
+            }
+        }
         await ctx.runMutation(internalApi.garmin.deleteTokens, { connectionId });
-        // 3. Set connection inactive
         await ctx.runMutation(publicApi.public.disconnect, {
             userId: args.userId,
             provider: "GARMIN",
@@ -455,6 +460,87 @@ export const disconnectGarmin = action({
         return null;
     },
 });
+// ─── Training API ────────────────────────────────────────────────────────────
+/**
+ * Push a planned workout from Soma's DB to Garmin Connect.
+ *
+ * Reads the planned workout document, transforms it to Garmin Training API V2
+ * format, creates the workout at Garmin, and optionally schedules it if a
+ * `planned_date` is set in the metadata.
+ *
+ * Returns the Garmin workout ID and schedule ID (if scheduled).
+ */
+export const pushPlannedWorkout = action({
+    args: {
+        userId: v.string(),
+        clientId: v.string(),
+        clientSecret: v.string(),
+        plannedWorkoutId: v.string(),
+        workoutProvider: v.optional(v.string()),
+    },
+    returns: v.object({
+        garminWorkoutId: v.number(),
+        garminScheduleId: v.union(v.number(), v.null()),
+    }),
+    handler: async (ctx, args) => {
+        const connection = await ctx.runQuery(internalApi.private.getConnectionByProvider, { userId: args.userId, provider: "GARMIN" });
+        if (!connection) {
+            throw new Error(`No Garmin connection found for user "${args.userId}". ` +
+                "Call connectGarmin first.");
+        }
+        if (!connection.active) {
+            throw new Error(`Garmin connection for user "${args.userId}" is inactive. Reconnect first.`);
+        }
+        const connectionId = connection._id;
+        const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
+            connectionId,
+        });
+        if (!tokenDoc) {
+            throw new Error("No Garmin tokens found for this connection. " +
+                "The connection may have been created before token storage was available.");
+        }
+        let accessToken = tokenDoc.accessToken;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (tokenDoc.expiresAt &&
+            tokenDoc.refreshToken &&
+            nowSeconds >= tokenDoc.expiresAt - REFRESH_BUFFER_SECONDS) {
+            const refreshed = await refreshToken({
+                clientId: args.clientId,
+                clientSecret: args.clientSecret,
+                refreshToken: tokenDoc.refreshToken,
+            });
+            accessToken = refreshed.access_token;
+            const newExpiresAt = nowSeconds + refreshed.expires_in;
+            await ctx.runMutation(internalApi.garmin.storeTokens, {
+                connectionId,
+                accessToken: refreshed.access_token,
+                refreshToken: refreshed.refresh_token,
+                expiresAt: newExpiresAt,
+            });
+        }
+        const plannedWorkout = await ctx.runQuery(publicApi.public.getPlannedWorkout, { plannedWorkoutId: args.plannedWorkoutId });
+        if (!plannedWorkout) {
+            throw new Error(`Planned workout "${args.plannedWorkoutId}" not found.`);
+        }
+        const providerName = args.workoutProvider ?? "Soma";
+        const garminWorkout = transformPlannedWorkoutToGarmin(plannedWorkout, providerName);
+        const client = new GarminClient({ accessToken });
+        const created = await client.createWorkout(garminWorkout);
+        if (!created.workoutId) {
+            throw new Error("Garmin API did not return a workoutId after creation.");
+        }
+        let garminScheduleId = null;
+        const plannedDate = plannedWorkout.metadata?.planned_date;
+        if (plannedDate) {
+            const schedule = await client.createSchedule(created.workoutId, plannedDate);
+            garminScheduleId = schedule.scheduleId ?? null;
+        }
+        return {
+            garminWorkoutId: created.workoutId,
+            garminScheduleId,
+        };
+    },
+});
 async function syncAllTypes(ctx, client, config) {
     const { connectionId, userId, timeRange } = config;
     const synced = { activities: 0, dailies: 0, sleep: 0, body: 0, menstruation: 0 };