@nativesquare/soma 0.13.0 → 0.14.0

package/src/component/private.ts

@@ -1,5 +1,9 @@
 import { v } from "convex/values";
-import { internalMutation, internalQuery } from "./_generated/server.js";
+import { internalAction, internalMutation, internalQuery } from "./_generated/server.js";
+import { internal } from "./_generated/api.js";
+import { refreshToken as refreshGarminToken } from "./garmin/auth.js";
+import { refreshToken as refreshStravaToken } from "./strava/auth.js";
+import type { Doc, Id } from "./_generated/dataModel.js";
 
 // ─── Internal Connection Helpers ────────────────────────────────────────────
 // Used by component-internal operations (sync crons, data ingestion, etc.).
@@ -69,3 +73,243 @@ export const updateLastDataUpdate = internalMutation({
     });
   },
 });
+
+// ─── Internal Pending OAuth CRUD ─────────────────────────────────────────────
+// Temporary storage for in-progress OAuth flows.
+// Bridges auth-URL generation and the OAuth callback for all providers.
+
+export const storePendingOAuth = internalMutation({
+  args: {
+    provider: v.string(),
+    state: v.string(),
+    codeVerifier: v.optional(v.string()),
+    userId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.insert("pendingOAuth", {
+      ...args,
+      createdAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+export const getPendingOAuth = internalQuery({
+  args: { state: v.string() },
+  returns: v.union(
+    v.object({
+      _id: v.id("pendingOAuth"),
+      _creationTime: v.number(),
+      provider: v.string(),
+      state: v.string(),
+      codeVerifier: v.optional(v.string()),
+      userId: v.string(),
+      createdAt: v.number(),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("pendingOAuth")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .first();
+  },
+});
+
+export const deletePendingOAuth = internalMutation({
+  args: { state: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const pending = await ctx.db
+      .query("pendingOAuth")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .first();
+    if (pending) {
+      await ctx.db.delete(pending._id);
+    }
+    return null;
+  },
+});
+
+// ─── Internal Token CRUD ─────────────────────────────────────────────────────
+
+/**
+ * Store or update OAuth tokens for a connection.
+ * Upserts by connectionId — one token record per connection.
+ */
+export const storeTokens = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    accessToken: v.string(),
+    refreshToken: v.string(),
+    expiresAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        accessToken: args.accessToken,
+        refreshToken: args.refreshToken,
+        expiresAt: args.expiresAt,
+      });
+      return null;
+    }
+
+    await ctx.db.insert("providerTokens", args);
+    return null;
+  },
+});
+
+/**
+ * Get stored tokens for a connection.
+ */
+export const getTokens = internalQuery({
+  args: { connectionId: v.id("connections") },
+  returns: v.union(
+    v.object({
+      _id: v.id("providerTokens"),
+      _creationTime: v.number(),
+      connectionId: v.id("connections"),
+      accessToken: v.string(),
+      refreshToken: v.optional(v.string()),
+      expiresAt: v.optional(v.number()),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+  },
+});
+
+/**
+ * Delete stored tokens for a connection.
+ */
+export const deleteTokens = internalMutation({
+  args: { connectionId: v.id("connections") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.delete(existing._id);
+    }
+    return null;
+  },
+});
+
+// ─── Resolve Connection & Access Token ──────────────────────────────────────
+// Shared across providers. Looks up the connection, retrieves stored tokens,
+// auto-refreshes if expired, persists the new tokens, and returns a valid
+// { connectionId, accessToken } pair ready for API calls.
+
+const REFRESH_BUFFER_SECONDS = 600;
+
+const refreshByProvider: Record<
+  string,
+  (opts: { clientId: string; clientSecret: string; refreshToken: string }) =>
+    Promise<import("./utils.js").OAuthRefreshResult>
+> = {
+  GARMIN: refreshGarminToken,
+  STRAVA: refreshStravaToken,
+};
+
+export const resolveConnectionAndAccessToken = internalAction({
+  args: {
+    userId: v.string(),
+    provider: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+  },
+  handler: async (ctx, args): Promise<{
+    connectionId: Id<"connections">;
+    accessToken: string;
+  }> => {
+    const connection: Doc<"connections"> | null = await ctx.runQuery(
+      internal.private.getConnectionByProvider,
+      { userId: args.userId, provider: args.provider },
+    );
+
+    if (!connection) {
+      throw new Error(
+        `No ${args.provider} connection found for user "${args.userId}". ` +
+        `Connect to ${args.provider} first.`,
+      );
+    }
+
+    if (!connection.active) {
+      throw new Error(
+        `${args.provider} connection for user "${args.userId}" is inactive. Reconnect first.`,
+      );
+    }
+
+    const connectionId = connection._id;
+
+    const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(
+      internal.private.getTokens,
+      { connectionId },
+    );
+
+    if (!tokenDoc) {
+      throw new Error(
+        `No ${args.provider} tokens found for this connection. ` +
+        "The connection may have been created before token storage was available.",
+      );
+    }
+
+    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 refresh = refreshByProvider[args.provider];
+      if (!refresh) {
+        throw new Error(`No refresh handler registered for provider "${args.provider}"`);
+      }
+
+      const refreshed = await refresh({
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        refreshToken: tokenDoc.refreshToken,
+      });
+
+      accessToken = refreshed.access_token;
+
+      await ctx.runMutation(
+        internal.private.storeTokens,
+        {
+          connectionId,
+          accessToken: refreshed.access_token,
+          refreshToken: refreshed.refresh_token,
+          expiresAt: refreshed.expiresAt,
+        },
+      );
+    }
+
+    return {
+      connectionId,
+      accessToken,
+    };
+  },
+});

package/src/component/strava/auth.ts

@@ -2,6 +2,8 @@
 // Pure helper functions for the Strava OAuth 2.0 Authorization Code flow.
 // No external dependencies — uses the global `fetch`.
 
+import type { OAuthRefreshResult } from "../utils.js";
+
 export interface StravaOAuthTokenResponse {
   token_type: string;
   expires_at: number; // Unix timestamp
@@ -120,7 +122,7 @@ export interface RefreshTokenOptions {
  */
 export async function refreshToken(
   opts: RefreshTokenOptions,
-): Promise<StravaOAuthTokenResponse> {
+): Promise<OAuthRefreshResult> {
   const response = await fetch("https://www.strava.com/oauth/token", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -139,5 +141,10 @@ export async function refreshToken(
     );
   }
 
-  return (await response.json()) as StravaOAuthTokenResponse;
+  const raw = (await response.json()) as StravaOAuthTokenResponse;
+  return {
+    access_token: raw.access_token,
+    refresh_token: raw.refresh_token,
+    expiresAt: raw.expires_at,
+  };
 }

package/src/component/strava/public.ts

@@ -1,5 +1,5 @@
-// ─── Strava Component Actions ────────────────────────────────────────────────
-// Public actions that handle the full Strava OAuth + sync lifecycle.
+// ─── Strava Public Actions ──────────────────────────────────────────────────
+// Public actions that handle the full Strava OAuth + pull lifecycle.
 // The host app calls these through the Soma class, which threads the
 // credentials automatically from env vars or constructor config.
 
@@ -18,20 +18,13 @@ import { generateState } from "../utils.js";
 import {
   buildAuthUrl,
   exchangeCode,
-  refreshToken as refreshStravaToken,
 } from "./auth.js";
 import { transformActivity } from "./transform/activity.js";
 import { transformAthlete } from "./transform/athlete.js";
+import type { SomaError } from "../validators/shared.js";
 
-// ─── Public Actions ──────────────────────────────────────────────────────────
+// ─── OAuth ──────────────────────────────────────────────────────────────────
 
-/**
- * Generate a Strava OAuth authorization URL.
- *
- * The state parameter is stored in the component's `pendingOAuth` table
- * so that `completeStravaOAuth` can look it up automatically when the
- * callback fires via `registerRoutes`.
- */
 export const getStravaAuthUrl = action({
   args: {
     clientId: v.string(),
@@ -49,7 +42,7 @@ export const getStravaAuthUrl = action({
       state,
     });
 
-    await ctx.runMutation(internal.strava.private.storePendingOAuth, {
+    await ctx.runMutation(internal.private.storePendingOAuth, {
       provider: "STRAVA",
       state,
       userId: args.userId,
@@ -59,17 +52,6 @@ export const getStravaAuthUrl = action({
   },
 });
 
-/**
- * Complete a Strava OAuth flow using stored pending state.
- *
- * Called internally by `registerRoutes` — the callback handler calls
- * this with the `code` and `state` from the redirect. The action looks
- * up the pending state (userId) stored during `getStravaAuthUrl`,
- * exchanges for tokens, creates the connection, stores tokens, and
- * cleans up the pending entry.
- *
- * The host app is responsible for calling `syncStrava` afterwards.
- */
 export const completeStravaOAuth = action({
   args: {
     code: v.string(),
@@ -87,7 +69,7 @@ export const completeStravaOAuth = action({
   }> => {
     // 1. Look up pending state
     const pending: Doc<"pendingOAuth"> | null = await ctx.runQuery(
-      internal.strava.private.getPendingOAuth,
+      internal.private.getPendingOAuth,
       { state: args.state },
     );
     if (!pending) {
@@ -106,7 +88,7 @@ export const completeStravaOAuth = action({
 
     // 3. Clean up pending entry
     await ctx.runMutation(
-      internal.strava.private.deletePendingOAuth,
+      internal.private.deletePendingOAuth,
       { state: args.state },
     );
 
@@ -116,12 +98,13 @@ export const completeStravaOAuth = action({
       {
         userId: pending.userId,
         provider: "STRAVA",
+        providerUserId: String(tokens.athlete.id),
       },
     );
 
     // 5. Store OAuth tokens
     await ctx.runMutation(
-      internal.strava.private.storeTokens,
+      internal.private.storeTokens,
       {
         connectionId,
         accessToken: tokens.access_token,
@@ -137,31 +120,14 @@ export const completeStravaOAuth = action({
   },
 });
 
-/**
- * Incremental Strava sync for an already-connected user.
- *
- * Looks up the stored tokens, auto-refreshes if expired, then syncs
- * the athlete profile and activities.
- *
- * Returns `{ synced, errors }`.
- */
-export const syncStrava = action({
+export const disconnectStrava = action({
   args: {
     userId: v.string(),
     clientId: v.string(),
     clientSecret: v.string(),
-    after: v.optional(v.number()),
   },
-  returns: v.object({
-    data: v.object({ synced: v.object({ athletes: v.number(), activities: v.number() }) }),
-    errors: v.array(
-      v.object({ type: v.string(), id: v.string(), message: v.string() }),
-    ),
-  }),
-  handler: async (ctx, args): Promise<{
-    data: { synced: { athletes: number; activities: number } };
-    errors: Array<{ type: string; id: string; message: string }>;
-  }> => {
+  returns: v.null(),
+  handler: async (ctx, args) => {
     // 1. Look up connection
     const connection: Doc<"connections"> | null = await ctx.runQuery(
       internal.private.getConnectionByProvider,
@@ -169,110 +135,72 @@ export const syncStrava = action({
     );
     if (!connection) {
       throw new Error(
-        `No Strava connection found for user "${args.userId}". ` +
-        "Connect to Strava first via getStravaAuthUrl.",
-      );
-    }
-    if (!connection.active) {
-      throw new Error(
-        `Strava connection for user "${args.userId}" is inactive. Reconnect first.`,
+        `No Strava connection found for user "${args.userId}".`,
       );
     }
 
     const connectionId = connection._id;
 
-    // 2. Get stored tokens
+    // 2. Revoke token at Strava (best-effort, don't fail if it errors)
     const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(
-      internal.strava.private.getTokens,
+      internal.private.getTokens,
       { connectionId },
     );
-    if (!tokenDoc) {
-      throw new Error(
-        `No tokens found for Strava connection. ` +
-        "The connection may have been created before token storage was available.",
-      );
-    }
+    if (tokenDoc) {
+      try {
+        await fetch("https://www.strava.com/oauth/deauthorize", {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: `access_token=${tokenDoc.accessToken}`,
+        });
+      } catch {
+        // Deauthorization is best-effort — clean up locally regardless
+      }
 
-    // 3. Auto-refresh if token is expired or expiring within 5 minutes
-    let accessToken = tokenDoc.accessToken;
-    const now = Math.floor(Date.now() / 1000);
-    if (!tokenDoc.refreshToken || !tokenDoc.expiresAt) {
-      throw new Error(
-        "Strava tokens are missing refreshToken or expiresAt. " +
-        "This connection may have been created with an incompatible version.",
-      );
-    }
-    if (tokenDoc.expiresAt < now + 300) {
-      const refreshed = await refreshStravaToken({
-        clientId: args.clientId,
-        clientSecret: args.clientSecret,
-        refreshToken: tokenDoc.refreshToken,
-      });
-      accessToken = refreshed.access_token;
-      await ctx.runMutation(
-        internal.strava.private.storeTokens,
-        {
-          connectionId,
-          accessToken: refreshed.access_token,
-          refreshToken: refreshed.refresh_token,
-          expiresAt: refreshed.expires_at,
-        },
+      // 3. Delete stored tokens
+      const _deleted: null = await ctx.runMutation(
+        internal.private.deleteTokens,
+        { connectionId },
       );
     }
 
-    // 4. Sync all data types
-    const result = await ctx.runAction(api.strava.public.syncAllTypes, {
-      accessToken,
-      connectionId,
+    // 4. Set connection inactive
+    const _disconnected: null = await ctx.runMutation(api.public.disconnect, {
       userId: args.userId,
-      after: args.after,
+      provider: "STRAVA",
     });
 
-    // 5. Update lastDataUpdate timestamp
-    await ctx.runMutation(
-      api.public.updateConnection,
-      {
-        connectionId,
-        lastDataUpdate: new Date().toISOString(),
-      },
-    );
-
-    return { data: { synced: result.data.synced }, errors: result.errors };
+    return null;
   },
 });
 
-// ─── Sync Engine ────────────────────────────────────────────────────────────
+// ─── Pull ───────────────────────────────────────────────────────────────────
 
-/**
- * Fetch and ingest all Strava data types for a connected user.
- *
- * Called by syncStrava after obtaining a valid access token.
- */
-export const syncAllTypes = action({
+export const pullAthlete = action({
   args: {
-    accessToken: v.string(),
-    connectionId: v.id("connections"),
     userId: v.string(),
-    after: v.optional(v.number()),
-    before: v.optional(v.number()),
+    clientId: v.string(),
+    clientSecret: v.string(),
   },
   handler: async (ctx, args) => {
-    const { accessToken, connectionId, userId } = args;
-    const client = createStravaClient(accessToken);
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, provider: "STRAVA", clientId: args.clientId, clientSecret: args.clientSecret },
+    );
 
-    const synced = { athletes: 0, activities: 0 };
-    const errors: Array<{ type: string; id: string; message: string }> = [];
+    const client = createStravaClient(accessToken);
+    const synced = { athletes: 0 };
+    const errors: SomaError[] = [];
 
-    // ── Athlete ──────────────────────────────────────────────────────────
     try {
       const { data: athlete, error } = await getLoggedInAthlete({ client });
       if (error || !athlete) throw new Error(error ? JSON.stringify(error) : "No athlete data");
       const data = transformAthlete(athlete);
       await ctx.runMutation(api.public.ingestAthlete, {
         connectionId,
-        userId,
+        userId: args.userId,
         ...data,
-      } as never);
+      });
       synced.athletes++;
     } catch (err) {
       errors.push({
@@ -282,7 +210,33 @@ export const syncAllTypes = action({
       });
     }
 
-    // ── Activities ───────────────────────────────────────────────────────
+    await ctx.runMutation(api.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
+    return { data: { synced }, errors };
+  },
+});
+
+export const pullActivities = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    after: v.optional(v.number()),
+    before: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, provider: "STRAVA", clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const client = createStravaClient(accessToken);
+    const synced = { activities: 0 };
+    const errors: SomaError[] = [];
+
     try {
       const summaries = await listAllActivities(client, {
         after: args.after,
@@ -306,9 +260,9 @@ export const syncAllTypes = action({
           const data = transformActivity(detailed, { streams: streams ?? undefined });
           await ctx.runMutation(api.public.ingestActivity, {
             connectionId,
-            userId,
+            userId: args.userId,
             ...data,
-          } as never);
+          });
           synced.activities++;
         } catch (err) {
           errors.push({
@@ -326,68 +280,48 @@ export const syncAllTypes = action({
       });
     }
 
+    await ctx.runMutation(api.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
     return { data: { synced }, errors };
   },
 });
 
-// ─── Disconnect ─────────────────────────────────────────────────────────────
-
-/**
- * Disconnect a user from Strava.
- *
- * Revokes the token at Strava (best-effort), deletes stored tokens,
- * and sets the connection to inactive.
- */
-export const disconnectStrava = action({
+export const pullAll = action({
   args: {
     userId: v.string(),
     clientId: v.string(),
     clientSecret: v.string(),
+    after: v.optional(v.number()),
+    before: v.optional(v.number()),
   },
-  returns: v.null(),
   handler: async (ctx, args) => {
-    // 1. Look up connection
-    const connection: Doc<"connections"> | null = await ctx.runQuery(
-      internal.private.getConnectionByProvider,
-      { userId: args.userId, provider: "STRAVA" },
-    );
-    if (!connection) {
-      throw new Error(
-        `No Strava connection found for user "${args.userId}".`,
-      );
-    }
-
-    const connectionId = connection._id;
-
-    // 2. Revoke token at Strava (best-effort, don't fail if it errors)
-    const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(
-      internal.strava.private.getTokens,
-      { connectionId },
-    );
-    if (tokenDoc) {
+    const sharedArgs = {
+      userId: args.userId,
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+    };
+    const pullFns = [
+      { ref: api.strava.public.pullAthlete, name: "athlete", args: sharedArgs },
+      { ref: api.strava.public.pullActivities, name: "activities", args: { ...sharedArgs, after: args.after, before: args.before } },
+    ];
+    const synced: Record<string, number> = {};
+    const errors: SomaError[] = [];
+    for (const { ref, name, args: fnArgs } of pullFns) {
       try {
-        await fetch("https://www.strava.com/oauth/deauthorize", {
-          method: "POST",
-          headers: { "Content-Type": "application/x-www-form-urlencoded" },
-          body: `access_token=${tokenDoc.accessToken}`,
+        const result = await ctx.runAction(ref, fnArgs);
+        Object.assign(synced, result.data.synced);
+        errors.push(...result.errors);
+      } catch (err) {
+        errors.push({
+          type: name,
+          id: "pull",
+          message: err instanceof Error ? err.message : String(err),
         });
-      } catch {
-        // Deauthorization is best-effort — clean up locally regardless
       }
-
-      // 3. Delete stored tokens
-      const _deleted: null = await ctx.runMutation(
-        internal.strava.private.deleteTokens,
-        { connectionId },
-      );
     }
-
-    // 4. Set connection inactive
-    const _disconnected: null = await ctx.runMutation(api.public.disconnect, {
-      userId: args.userId,
-      provider: "STRAVA",
-    });
-
-    return null;
+    return { data: { synced }, errors };
   },
-});
+});