@nativesquare/soma 0.9.3 → 0.10.0

package/src/client/index.ts

@@ -7,7 +7,6 @@ import {
   type GenericDataModel,
   type HttpRouter,
 } from "convex/server";
-import { buildAuthUrl } from "../strava/auth.js";
 
 export type SomaComponent = ComponentApi;
 
@@ -30,12 +29,6 @@ export interface SomaStravaConfig {
   clientId: string;
   /** Your Strava application's Client Secret. */
   clientSecret: string;
-  /**
-   * Base URL of the Strava API (without `/api/v3` suffix).
-   * Defaults to `https://www.strava.com`.
-   * Override to point at a mock server during development.
-   */
-  baseUrl?: string;
 }
 
 /**
@@ -73,7 +66,7 @@ export interface SomaGarminConfig {
  *
  * // Or with explicit Strava config:
  * // const soma = new Soma(components.soma, {
- * //   strava: { clientId: "...", clientSecret: "...", baseUrl: "..." },
+ * //   strava: { clientId: "...", clientSecret: "..." },
  * // });
  *
  * // Connect a user to a provider:
@@ -109,7 +102,6 @@ export class Soma {
     return {
       clientId,
       clientSecret,
-      baseUrl: process.env.STRAVA_BASE_URL,
     };
   }
 
@@ -885,35 +877,41 @@ export class Soma {
   // environment variables or the constructor.
 
   /**
-   * Build the Strava OAuth authorization URL.
+   * 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.
    *
-   * This is a pure computation (no DB or HTTP calls), so it doesn't need
-   * a Convex context. Redirect the user to this URL to begin the OAuth flow.
+   * If `userId` is omitted, the host app must store the returned `state`
+   * itself and handle the callback via `connectStrava`.
    *
+   * @param ctx - Action context from the host app
    * @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.state - Optional state parameter for CSRF protection
-   * @returns The authorization URL string
+   * @param opts.userId - The host app's user identifier (required for `registerRoutes` flow)
+   * @returns `{ authUrl, state }`
    *
    * @example
    * ```ts
-   * const url = soma.getStravaAuthUrl({
-   *   redirectUri: "https://your-app.com/api/strava/callback",
+   * const { authUrl } = await soma.getStravaAuthUrl(ctx, {
+   *   userId: "user_123",
+   *   redirectUri: "https://your-app.convex.site/api/strava/callback",
    * });
+   * // Redirect user to authUrl — the callback is handled automatically
    * ```
    */
-  getStravaAuthUrl(opts: {
-    redirectUri: string;
-    scope?: string;
-    state?: string;
-  }): string {
+  async getStravaAuthUrl(
+    ctx: ActionCtx,
+    opts: { redirectUri: string; scope?: string; userId?: string },
+  ) {
     const config = this.requireStravaConfig();
-    return buildAuthUrl({
+    return await ctx.runAction(this.component.strava.public.getStravaAuthUrl, {
       clientId: config.clientId,
       redirectUri: opts.redirectUri,
       scope: opts.scope,
-      state: opts.state,
-      baseUrl: config.baseUrl,
+      userId: opts.userId,
     });
   }
 
@@ -930,7 +928,6 @@ export class Soma {
    * @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
-   * @param args.includeStreams - Fetch detailed streams per activity (default: false)
    * @returns `{ connectionId, synced, errors }`
    *
    * @example
@@ -945,17 +942,43 @@ export class Soma {
    */
   async connectStrava(
     ctx: ActionCtx,
-    args: { userId: string; code: string; includeStreams?: boolean },
+    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,
-      baseUrl: config.baseUrl,
     });
   }
 
+  /**
+   * 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.
    *
@@ -964,7 +987,6 @@ export class Soma {
    *
    * @param ctx - Action context from the host app
    * @param args.userId - The host app's user identifier
-   * @param args.includeStreams - Fetch detailed streams per activity (default: false)
    * @param args.after - Only sync activities after this Unix epoch timestamp (for incremental sync)
    * @returns `{ synced, errors }`
    *
@@ -973,21 +995,20 @@ export class Soma {
    * export const syncStrava = action({
    *   args: { userId: v.string() },
    *   handler: async (ctx, { userId }) => {
-   *     return await soma.syncStrava(ctx, { userId, includeStreams: true });
+   *     return await soma.syncStrava(ctx, { userId });
    *   },
    * });
    * ```
    */
   async syncStrava(
     ctx: ActionCtx,
-    args: { userId: string; includeStreams?: boolean; after?: number },
+    args: { userId: string; after?: number },
   ) {
     const config = this.requireStravaConfig();
     return await ctx.runAction(this.component.strava.public.syncStrava, {
       ...args,
       clientId: config.clientId,
       clientSecret: config.clientSecret,
-      baseUrl: config.baseUrl,
     });
   }
 
@@ -1019,7 +1040,6 @@ export class Soma {
       ...args,
       clientId: config.clientId,
       clientSecret: config.clientSecret,
-      baseUrl: config.baseUrl,
     });
   }
 
@@ -1253,17 +1273,31 @@ type PaginateTimeRangeArgs = TimeRangeArgs & {
 /**
  * Per-provider options for `registerRoutes`.
  */
-export interface StravaRouteOptions {
+export interface StravaOAuthOptions {
   /** HTTP path for the OAuth callback. @default "/api/strava/callback" */
   path?: string;
   /** Override STRAVA_CLIENT_ID env var. */
   clientId?: string;
   /** Override STRAVA_CLIENT_SECRET env var. */
   clientSecret?: string;
-  /** Override STRAVA_BASE_URL env var. */
-  baseUrl?: string;
   /** URL to redirect the user to after a successful connection. */
-  onSuccess?: string;
+  redirectTo?: string;
+  /** Called after Strava OAuth completes and initial data sync finishes. */
+  onComplete?: (
+    ctx: GenericActionCtx<GenericDataModel>,
+    event: StravaConnectEvent,
+  ) => Promise<void>;
+}
+
+// ─── Strava Callback Event Types ────────────────────────────────────────────
+
+/** Data passed to `onComplete` after Strava OAuth + initial sync. */
+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 ─────────────────────────────────────────────
@@ -1327,7 +1361,10 @@ export interface GarminWebhookOptions {
 }
 
 export interface RegisterRoutesOptions {
-  strava?: StravaRouteOptions;
+  strava?: {
+    /** OAuth callback configuration. */
+    oauth?: StravaOAuthOptions;
+  };
   garmin?: {
     /** OAuth callback configuration. */
     oauth?: GarminOAuthOptions;
@@ -1369,8 +1406,17 @@ export interface RegisterRoutesOptions {
  * // With Garmin OAuth callbacks and per-type webhook handlers
  * registerRoutes(http, components.soma, {
  *   strava: {
- *     path: "/oauth/strava/callback",
- *     onSuccess: "https://myapp.com/settings",
+ *     oauth: {
+ *       path: "/oauth/strava/callback",
+ *       redirectTo: "https://myapp.com/settings",
+ *       onComplete: async (ctx, event) => {
+ *         // Runs after OAuth + initial sync completes
+ *         await ctx.runMutation(internal.users.markConnected, {
+ *           userId: event.userId,
+ *           provider: event.provider,
+ *         });
+ *       },
+ *     },
  *   },
  *   garmin: {
  *     oauth: {
@@ -1406,8 +1452,9 @@ export function registerRoutes(
   const registerAll = opts === undefined;
 
   if (registerAll || opts?.strava) {
-    const strava = opts?.strava ?? {};
-    const path = strava.path ?? STRAVA_CALLBACK_PATH;
+    const stravaOpts = opts?.strava ?? {};
+    const oauth = stravaOpts.oauth ?? {};
+    const path = oauth.path ?? STRAVA_CALLBACK_PATH;
 
     http.route({
       path,
@@ -1415,23 +1462,23 @@ export function registerRoutes(
       handler: httpActionGeneric(async (ctx, request) => {
         const url = new URL(request.url);
         const code = url.searchParams.get("code");
-        const userId = url.searchParams.get("state");
+        const state = url.searchParams.get("state");
 
         if (!code) {
           return new Response("Missing authorization code", { status: 400 });
         }
-        if (!userId) {
+        if (!state) {
           return new Response(
-            "Missing state parameter (userId). Pass the userId as the state " +
-            "parameter when building the Strava auth URL.",
+            "Missing state parameter. Ensure the state was included " +
+            "when building the Strava auth URL via getStravaAuthUrl.",
             { status: 400 },
           );
         }
 
         const clientId =
-          strava.clientId ?? process.env.STRAVA_CLIENT_ID;
+          oauth.clientId ?? process.env.STRAVA_CLIENT_ID;
         const clientSecret =
-          strava.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
+          oauth.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
 
         if (!clientId || !clientSecret) {
           return new Response(
@@ -1441,13 +1488,18 @@ export function registerRoutes(
           );
         }
 
+        let result: {
+          connectionId: string;
+          userId: string;
+          synced: Record<string, number>;
+          errors: Array<{ type: string; id: string; error: string }>;
+        };
         try {
-          await ctx.runAction(component.strava.public.connectStrava, {
-            userId,
+          result = await ctx.runAction(component.strava.public.completeStravaOAuth, {
             code,
+            state,
             clientId,
             clientSecret,
-            baseUrl: strava.baseUrl ?? process.env.STRAVA_BASE_URL,
           });
         } catch (error) {
           const message =
@@ -1457,10 +1509,27 @@ export function registerRoutes(
           });
         }
 
-        if (strava.onSuccess) {
+        if (oauth.onComplete) {
+          try {
+            await oauth.onComplete(ctx, {
+              provider: "STRAVA",
+              userId: result.userId,
+              connectionId: result.connectionId,
+              synced: result.synced,
+              errors: result.errors,
+            });
+          } catch (callbackError) {
+            console.error(
+              "[soma] strava onComplete callback error:",
+              callbackError instanceof Error ? callbackError.message : callbackError,
+            );
+          }
+        }
+
+        if (oauth.redirectTo) {
           return new Response(null, {
             status: 302,
-            headers: { Location: strava.onSuccess },
+            headers: { Location: oauth.redirectTo },
           });
         }
 

package/src/component/_generated/api.ts

@@ -57,8 +57,17 @@ import type * as garmin_utils from "../garmin/utils.js";
 import type * as garmin_webhooks from "../garmin/webhooks.js";
 import type * as private_ from "../private.js";
 import type * as public_ from "../public.js";
+import type * as strava_auth from "../strava/auth.js";
+import type * as strava_client from "../strava/client.js";
 import type * as strava_private from "../strava/private.js";
 import type * as strava_public from "../strava/public.js";
+import type * as strava_transform_activity from "../strava/transform/activity.js";
+import type * as strava_transform_athlete from "../strava/transform/athlete.js";
+import type * as strava_transform_maps_sportType from "../strava/transform/maps/sportType.js";
+import type * as strava_types_stravaApi_client_index from "../strava/types/stravaApi/client/index.js";
+import type * as strava_types_stravaApi_index from "../strava/types/stravaApi/index.js";
+import type * as strava_utils from "../strava/utils.js";
+import type * as utils from "../utils.js";
 import type * as validators_activity from "../validators/activity.js";
 import type * as validators_athlete from "../validators/athlete.js";
 import type * as validators_body from "../validators/body.js";
@@ -130,8 +139,17 @@ const fullApi: ApiFromModules<{
   "garmin/webhooks": typeof garmin_webhooks;
   private: typeof private_;
   public: typeof public_;
+  "strava/auth": typeof strava_auth;
+  "strava/client": typeof strava_client;
   "strava/private": typeof strava_private;
   "strava/public": typeof strava_public;
+  "strava/transform/activity": typeof strava_transform_activity;
+  "strava/transform/athlete": typeof strava_transform_athlete;
+  "strava/transform/maps/sportType": typeof strava_transform_maps_sportType;
+  "strava/types/stravaApi/client/index": typeof strava_types_stravaApi_client_index;
+  "strava/types/stravaApi/index": typeof strava_types_stravaApi_index;
+  "strava/utils": typeof strava_utils;
+  utils: typeof utils;
   "validators/activity": typeof validators_activity;
   "validators/athlete": typeof validators_athlete;
   "validators/body": typeof validators_body;

package/src/component/_generated/component.ts

@@ -1647,34 +1647,69 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
     };
     strava: {
       public: {
+        completeStravaOAuth: FunctionReference<
+          "action",
+          "internal",
+          {
+            clientId: string;
+            clientSecret: string;
+            code: string;
+            state: string;
+          },
+          {
+            connectionId: string;
+            errors: Array<{ error: string; id: string; type: string }>;
+            synced: { activities: number; athletes: number };
+            userId: string;
+          },
+          Name
+        >;
         connectStrava: FunctionReference<
           "action",
           "internal",
           {
-            baseUrl?: string;
             clientId: string;
             clientSecret: string;
             code: string;
-            includeStreams?: boolean;
             userId: string;
           },
           {
             connectionId: string;
-            errors: Array<{ activityId: number; error: string }>;
-            synced: number;
+            errors: Array<{ error: string; id: string; type: string }>;
+            synced: { activities: number; athletes: number };
           },
           Name
         >;
         disconnectStrava: FunctionReference<
+          "action",
+          "internal",
+          { clientId: string; clientSecret: string; userId: string },
+          null,
+          Name
+        >;
+        getStravaAuthUrl: FunctionReference<
           "action",
           "internal",
           {
-            baseUrl?: string;
             clientId: string;
-            clientSecret: string;
+            redirectUri: string;
+            scope?: string;
+            userId?: string;
+          },
+          any,
+          Name
+        >;
+        syncAllTypes: FunctionReference<
+          "action",
+          "internal",
+          {
+            accessToken: string;
+            after?: number;
+            before?: number;
+            connectionId: string;
             userId: string;
           },
-          null,
+          any,
           Name
         >;
         syncStrava: FunctionReference<
@@ -1682,15 +1717,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           "internal",
           {
             after?: number;
-            baseUrl?: string;
             clientId: string;
             clientSecret: string;
-            includeStreams?: boolean;
             userId: string;
           },
           {
-            errors: Array<{ activityId: number; error: string }>;
-            synced: number;
+            errors: Array<{ error: string; id: string; type: string }>;
+            synced: { activities: number; athletes: number };
           },
           Name
         >;

package/src/component/garmin/auth.ts

@@ -32,15 +32,6 @@ export function generateCodeVerifier(length = 64): string {
   );
 }
 
-/**
- * Generate a random state parameter for CSRF protection.
- */
-export function generateState(): string {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-}
-
 /**
  * Compute the S256 code challenge from a code verifier.
  * Returns `base64url(sha256(verifier))`.

package/src/component/garmin/private.ts

@@ -117,18 +117,6 @@ export const storePendingOAuth = internalMutation({
 
 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.string(),
-      userId: v.string(),
-      createdAt: v.number(),
-    }),
-    v.null(),
-  ),
   handler: async (ctx, args) => {
     return await ctx.db
       .query("pendingOAuth")

package/src/component/garmin/public.ts

@@ -6,10 +6,10 @@
 import { v } from "convex/values";
 import { action } from "../_generated/server";
 import type { Doc, Id } from "../_generated/dataModel";
+import { generateState } from "../utils.js";
 import {
   generateCodeVerifier,
   generateCodeChallenge,
-  generateState,
   buildAuthUrl,
   exchangeCode,
   refreshToken,
@@ -219,6 +219,13 @@ export const completeGarminOAuth = action({
       );
     }
 
+    if (!pending.codeVerifier) {
+      throw new Error(
+        "No code verifier found for this state parameter. " +
+        "The authorization may have expired or was already used.",
+      );
+    }
+
     const tokenResult = await exchangeCode({
       clientId: args.clientId,
       clientSecret: args.clientSecret,

package/src/component/schema.ts

@@ -127,13 +127,15 @@ export default defineSchema({
   }).index("by_connectionId", ["connectionId"]),
 
   // ── Pending OAuth ─────────────────────────────────────────────────────────
-  // Temporary storage for in-progress OAuth 2.0 PKCE flows. Bridges the gap
-  // between initiating OAuth (auth URL) and the callback (code exchange).
+  // Temporary storage for in-progress OAuth flows. Bridges the gap between
+  // initiating OAuth (auth URL) and the callback (code exchange).
   // The `state` parameter links the callback back to the pending entry.
+  // `codeVerifier` is required for PKCE providers (Garmin) but absent for
+  // providers that don't use PKCE (Strava).
   pendingOAuth: defineTable({
     provider: v.string(),
     state: v.string(),
-    codeVerifier: v.string(),
+    codeVerifier: v.optional(v.string()),
     userId: v.string(),
     createdAt: v.number(),
   }).index("by_state", ["state"]),