@nativesquare/soma 0.4.0 → 0.5.0

package/src/client/index.ts

@@ -1,9 +1,16 @@
 import type { ComponentApi } from "../component/_generated/component.js";
 import type { ActionCtx, MutationCtx, QueryCtx } from "./types.js";
+import { httpActionGeneric, type HttpRouter } from "convex/server";
 import { buildAuthUrl } from "../strava/auth.js";
 
 export type SomaComponent = ComponentApi;
 
+// ─── Default OAuth Callback Paths ────────────────────────────────────────────
+// Used by `registerRoutes` as defaults. Override per-provider in the opts.
+
+export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
+export const GARMIN_CALLBACK_PATH = "/api/garmin/callback";
+
 /**
  * Configuration for the Strava integration.
  *
@@ -871,31 +878,41 @@ export class Soma {
    * Step 1 of the Garmin OAuth 1.0a flow: obtain a request token.
    *
    * Returns the temporary `token`, `tokenSecret`, and the `authUrl` to
-   * redirect the user to. The host app must store `token` and `tokenSecret`
-   * temporarily (e.g., in session/cookie) and pass them to `connectGarmin`
-   * after the user authorizes.
+   * redirect the user to.
+   *
+   * 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 omitted, the host app must store `token` and `tokenSecret`
+   * itself and pass them to `connectGarmin` manually.
    *
    * @param ctx - Action context from the host app
    * @param opts.callbackUrl - 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 }`
    *
    * @example
    * ```ts
-   * const { token, tokenSecret, authUrl } = await soma.getGarminRequestToken(ctx, {
-   *   callbackUrl: "https://your-app.com/api/garmin/callback",
+   * // Recommended: pass userId so registerRoutes can handle the callback
+   * const { authUrl } = await soma.getGarminRequestToken(ctx, {
+   *   userId: "user_123",
+   *   callbackUrl: "https://your-app.convex.site/api/garmin/callback",
    * });
-   * // Store token + tokenSecret in session, redirect user to authUrl
+   * // Redirect user to authUrl — the callback is handled automatically
    * ```
    */
   async getGarminRequestToken(
     ctx: ActionCtx,
-    opts: { callbackUrl?: string },
+    opts: { callbackUrl?: string; userId?: string },
   ) {
     const config = this.requireGarminConfig();
     return await ctx.runAction(this.component.garmin.getGarminRequestToken, {
       consumerKey: config.consumerKey,
       consumerSecret: config.consumerSecret,
       callbackUrl: opts.callbackUrl,
+      userId: opts.userId,
     });
   }
 
@@ -949,6 +966,30 @@ export class Soma {
     });
   }
 
+  /**
+   * Complete a Garmin OAuth 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.
+   *
+   * @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
+   * @returns `{ connectionId, synced, errors }`
+   */
+  async completeGarminOAuth(
+    ctx: ActionCtx,
+    args: { oauthToken: string; oauthVerifier: string },
+  ) {
+    const config = this.requireGarminConfig();
+    return await ctx.runAction(this.component.garmin.completeGarminOAuth, {
+      ...args,
+      consumerKey: config.consumerKey,
+      consumerSecret: config.consumerSecret,
+    });
+  }
+
   /**
    * Sync all data types from Garmin for an already-connected user.
    *
@@ -1055,3 +1096,214 @@ type ListTimeRangeArgs = TimeRangeArgs & {
 type PaginateTimeRangeArgs = TimeRangeArgs & {
   paginationOpts: { numItems: number; cursor: string | null };
 };
+
+// ─── Route Registration ──────────────────────────────────────────────────────
+
+/**
+ * Per-provider options for `registerRoutes`.
+ */
+export interface StravaRouteOptions {
+  /** 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;
+}
+
+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;
+  /** URL to redirect the user to after a successful connection. */
+  onSuccess?: string;
+}
+
+export interface RegisterRoutesOptions {
+  strava?: StravaRouteOptions;
+  garmin?: GarminRouteOptions;
+}
+
+/**
+ * Register OAuth callback HTTP routes for Soma providers.
+ *
+ * Call this from your `convex/http.ts` to set up the callback endpoints
+ * that Strava and Garmin redirect to after user authorization. The handlers
+ * complete the OAuth exchange, create the connection, and sync data
+ * automatically.
+ *
+ * When called with no `opts`, registers both Strava and Garmin routes with
+ * default paths and credentials from environment variables. When `opts` is
+ * provided, only registers routes for the providers specified.
+ *
+ * @param http - The Convex HTTP router from `httpRouter()`
+ * @param component - The Soma component reference (`components.soma`)
+ * @param opts - Optional per-provider configuration
+ *
+ * @example
+ * ```ts
+ * // convex/http.ts
+ * import { httpRouter } from "convex/server";
+ * import { registerRoutes } from "@nativesquare/soma";
+ * import { components } from "./_generated/api";
+ *
+ * const http = httpRouter();
+ * registerRoutes(http, components.soma);
+ * export default http;
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With custom paths and redirect
+ * registerRoutes(http, components.soma, {
+ *   strava: {
+ *     path: "/oauth/strava/callback",
+ *     onSuccess: "https://myapp.com/settings",
+ *   },
+ *   garmin: {
+ *     path: "/oauth/garmin/callback",
+ *     onSuccess: "https://myapp.com/settings",
+ *   },
+ * });
+ * ```
+ */
+export function registerRoutes(
+  http: HttpRouter,
+  component: SomaComponent,
+  opts?: RegisterRoutesOptions,
+) {
+  const registerAll = opts === undefined;
+
+  if (registerAll || opts?.strava) {
+    const strava = opts?.strava ?? {};
+    const path = strava.path ?? STRAVA_CALLBACK_PATH;
+
+    http.route({
+      path,
+      method: "GET",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const url = new URL(request.url);
+        const code = url.searchParams.get("code");
+        const userId = url.searchParams.get("state");
+
+        if (!code) {
+          return new Response("Missing authorization code", { status: 400 });
+        }
+        if (!userId) {
+          return new Response(
+            "Missing state parameter (userId). Pass the userId as the state " +
+              "parameter when building the Strava auth URL.",
+            { status: 400 },
+          );
+        }
+
+        const clientId =
+          strava.clientId ?? process.env.STRAVA_CLIENT_ID;
+        const clientSecret =
+          strava.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
+
+        if (!clientId || !clientSecret) {
+          return new Response(
+            "Strava credentials not configured. Set STRAVA_CLIENT_ID and " +
+              "STRAVA_CLIENT_SECRET environment variables, or pass them to registerRoutes.",
+            { status: 500 },
+          );
+        }
+
+        try {
+          await ctx.runAction(component.strava.connectStrava, {
+            userId,
+            code,
+            clientId,
+            clientSecret,
+            baseUrl: strava.baseUrl ?? process.env.STRAVA_BASE_URL,
+          });
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : "Unknown error";
+          return new Response(`Strava OAuth callback failed: ${message}`, {
+            status: 500,
+          });
+        }
+
+        if (strava.onSuccess) {
+          return new Response(null, {
+            status: 302,
+            headers: { Location: strava.onSuccess },
+          });
+        }
+
+        return new Response("Successfully connected to Strava!", {
+          status: 200,
+        });
+      }),
+    });
+  }
+
+  if (registerAll || opts?.garmin) {
+    const garmin = opts?.garmin ?? {};
+    const path = garmin.path ?? GARMIN_CALLBACK_PATH;
+
+    http.route({
+      path,
+      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");
+
+        if (!oauthToken || !oauthVerifier) {
+          return new Response("Missing oauth_token or oauth_verifier", {
+            status: 400,
+          });
+        }
+
+        const consumerKey =
+          garmin.consumerKey ?? process.env.GARMIN_CONSUMER_KEY;
+        const consumerSecret =
+          garmin.consumerSecret ?? process.env.GARMIN_CONSUMER_SECRET;
+
+        if (!consumerKey || !consumerSecret) {
+          return new Response(
+            "Garmin credentials not configured. Set GARMIN_CONSUMER_KEY and " +
+              "GARMIN_CONSUMER_SECRET environment variables, or pass them to registerRoutes.",
+            { status: 500 },
+          );
+        }
+
+        try {
+          await ctx.runAction(component.garmin.completeGarminOAuth, {
+            oauthToken,
+            oauthVerifier,
+            consumerKey,
+            consumerSecret,
+          });
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : "Unknown error";
+          return new Response(`Garmin OAuth callback failed: ${message}`, {
+            status: 500,
+          });
+        }
+
+        if (garmin.onSuccess) {
+          return new Response(null, {
+            status: 302,
+            headers: { Location: garmin.onSuccess },
+          });
+        }
+
+        return new Response("Successfully connected to Garmin!", {
+          status: 200,
+        });
+      }),
+    });
+  }
+}

package/src/component/_generated/component.ts

@@ -24,6 +24,28 @@ import type { FunctionReference } from "convex/server";
 export type ComponentApi<Name extends string | undefined = string | undefined> =
   {
     garmin: {
+      completeGarminOAuth: FunctionReference<
+        "action",
+        "internal",
+        {
+          consumerKey: string;
+          consumerSecret: string;
+          oauthToken: string;
+          oauthVerifier: string;
+        },
+        {
+          connectionId: string;
+          errors: Array<{ error: string; id: string; type: string }>;
+          synced: {
+            activities: number;
+            body: number;
+            dailies: number;
+            menstruation: number;
+            sleep: number;
+          };
+        },
+        Name
+      >;
       connectGarmin: FunctionReference<
         "action",
         "internal",
@@ -58,7 +80,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
       getGarminRequestToken: FunctionReference<
         "action",
         "internal",
-        { callbackUrl?: string; consumerKey: string; consumerSecret: string },
+        {
+          callbackUrl?: string;
+          consumerKey: string;
+          consumerSecret: string;
+          userId?: string;
+        },
         { authUrl: string; token: string; tokenSecret: string },
         Name
       >;

package/src/component/garmin.ts

@@ -29,6 +29,64 @@ const internalApi: any = anyApi;
 // Default sync window: last 30 days
 const DEFAULT_SYNC_DAYS = 30;
 
+// ─── Internal Pending OAuth CRUD ─────────────────────────────────────────────
+// Temporary storage for in-progress Garmin OAuth 1.0a flows.
+// Bridges Step 1 (getGarminRequestToken) and Step 3 (completeGarminOAuth).
+
+export const storePendingOAuth = internalMutation({
+  args: {
+    provider: v.string(),
+    oauthToken: v.string(),
+    tokenSecret: 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: { oauthToken: v.string() },
+  returns: v.union(
+    v.object({
+      _id: v.id("pendingOAuth"),
+      _creationTime: v.number(),
+      provider: v.string(),
+      oauthToken: v.string(),
+      tokenSecret: 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))
+      .first();
+  },
+});
+
+export const deletePendingOAuth = internalMutation({
+  args: { oauthToken: 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))
+      .first();
+    if (pending) {
+      await ctx.db.delete(pending._id);
+    }
+    return null;
+  },
+});
+
 // ─── Internal Token CRUD ─────────────────────────────────────────────────────
 
 /**
@@ -120,28 +178,42 @@ export const deleteTokens = internalMutation({
 /**
  * Step 1 of OAuth: obtain a request token and return the authorization URL.
  *
- * The host app must temporarily store the returned `token` and `tokenSecret`,
- * then redirect the user to `authUrl`. After the user authorizes, Garmin
- * redirects back with an `oauth_verifier` which is passed to `connectGarmin`.
+ * If `userId` is provided, the request token and secret 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.
  */
 export const getGarminRequestToken = action({
   args: {
     consumerKey: v.string(),
     consumerSecret: v.string(),
     callbackUrl: v.optional(v.string()),
+    userId: v.optional(v.string()),
   },
   returns: v.object({
     token: v.string(),
     tokenSecret: v.string(),
     authUrl: v.string(),
   }),
-  handler: async (_ctx, args) => {
+  handler: async (ctx, args) => {
     const result = await getRequestToken({
       consumerKey: args.consumerKey,
       consumerSecret: args.consumerSecret,
       callbackUrl: args.callbackUrl,
     });
 
+    if (args.userId) {
+      await ctx.runMutation(internalApi.garmin.storePendingOAuth, {
+        provider: "GARMIN",
+        oauthToken: result.oauthToken,
+        tokenSecret: result.oauthTokenSecret,
+        userId: args.userId,
+      });
+    }
+
     return {
       token: result.oauthToken,
       tokenSecret: result.oauthTokenSecret,
@@ -239,6 +311,111 @@ export const connectGarmin = action({
   },
 });
 
+/**
+ * Complete a Garmin OAuth 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.
+ */
+export const completeGarminOAuth = action({
+  args: {
+    oauthToken: v.string(),
+    oauthVerifier: v.string(),
+    consumerKey: v.string(),
+    consumerSecret: v.string(),
+  },
+  returns: v.object({
+    connectionId: v.string(),
+    synced: v.object({
+      activities: v.number(),
+      dailies: v.number(),
+      sleep: v.number(),
+      body: v.number(),
+      menstruation: v.number(),
+    }),
+    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,
+    });
+    if (!pending) {
+      throw new Error(
+        "No pending Garmin OAuth state found for this token. " +
+          "The request token 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,
+    });
+
+    // 3. Delete pending state (no longer needed)
+    await ctx.runMutation(internalApi.garmin.deletePendingOAuth, {
+      oauthToken: args.oauthToken,
+    });
+
+    // 4. Create/reactivate the Soma connection
+    const connectionId = await ctx.runMutation(publicApi.public.connect, {
+      userId: pending.userId,
+      provider: "GARMIN",
+    });
+
+    // 5. Store permanent OAuth tokens
+    await ctx.runMutation(internalApi.garmin.storeTokens, {
+      connectionId,
+      accessToken: accessTokenResult.oauthToken,
+      tokenSecret: accessTokenResult.oauthTokenSecret,
+    });
+
+    // 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,
+    });
+
+    const now = Math.floor(Date.now() / 1000);
+    const thirtyDaysAgo = now - DEFAULT_SYNC_DAYS * 86400;
+    const timeRange = {
+      uploadStartTimeInSeconds: thirtyDaysAgo,
+      uploadEndTimeInSeconds: now,
+    };
+
+    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(),
+    });
+
+    return {
+      connectionId,
+      synced: result.synced,
+      errors: result.errors,
+    };
+  },
+});
+
 /**
  * Incremental Garmin sync for an already-connected user.
  *

package/src/component/schema.ts

@@ -125,4 +125,16 @@ export default defineSchema({
     tokenSecret: v.optional(v.string()), // OAuth 1.0a providers (Garmin)
     expiresAt: v.optional(v.number()), // Unix epoch seconds; absent for permanent tokens
   }).index("by_connectionId", ["connectionId"]),
+
+  // ── Pending OAuth ─────────────────────────────────────────────────────────
+  // Temporary storage for in-progress OAuth flows. Bridges the gap between
+  // initiating OAuth (Step 1) and the callback (Step 3) for providers like
+  // Garmin that use OAuth 1.0a and don't have a `state` parameter.
+  pendingOAuth: defineTable({
+    provider: v.string(),
+    oauthToken: v.string(),
+    tokenSecret: v.string(),
+    userId: v.string(),
+    createdAt: v.number(),
+  }).index("by_oauthToken", ["oauthToken"]),
 });