@nativesquare/soma 0.3.0 → 0.5.0

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/NativeSquare/soma/issues"
   },
-  "version": "0.3.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "keywords": [
     "convex",
@@ -57,6 +57,10 @@
       "types": "./dist/strava/index.d.ts",
       "default": "./dist/strava/index.js"
     },
+    "./garmin": {
+      "types": "./dist/garmin/index.d.ts",
+      "default": "./dist/garmin/index.js"
+    },
     "./validators": {
       "types": "./dist/validators.d.ts",
       "default": "./dist/validators.js"

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.
  *
@@ -24,6 +31,20 @@ export interface SomaStravaConfig {
   baseUrl?: string;
 }
 
+/**
+ * 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
+ * environment variables automatically.
+ */
+export interface SomaGarminConfig {
+  /** Your Garmin application's Consumer Key. */
+  consumerKey: string;
+  /** Your Garmin application's Consumer Secret. */
+  consumerSecret: string;
+}
+
 /**
  * Client class for the @nativesquare/soma Convex component.
  *
@@ -60,12 +81,14 @@ export interface SomaStravaConfig {
  */
 export class Soma {
   private stravaConfig?: SomaStravaConfig;
+  private garminConfig?: SomaGarminConfig;
 
   constructor(
     public component: SomaComponent,
-    options?: { strava?: SomaStravaConfig },
+    options?: { strava?: SomaStravaConfig; garmin?: SomaGarminConfig },
   ) {
     this.stravaConfig = options?.strava ?? this.readStravaEnv();
+    this.garminConfig = options?.garmin ?? this.readGarminEnv();
   }
 
   /**
@@ -97,6 +120,31 @@ export class Soma {
     return this.stravaConfig;
   }
 
+  /**
+   * Read Garmin config from environment variables.
+   * 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 };
+  }
+
+  /**
+   * Get the resolved Garmin config, or throw a clear error if not configured.
+   */
+  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.",
+      );
+    }
+    return this.garminConfig;
+  }
+
   // ─── Connect / Disconnect ───────────────────────────────────────────────────
 
   /**
@@ -820,6 +868,192 @@ export class Soma {
       baseUrl: config.baseUrl,
     });
   }
+
+  // ─── 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.
+
+  /**
+   * 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.
+   *
+   * 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
+   * // 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",
+   * });
+   * // Redirect user to authUrl — the callback is handled automatically
+   * ```
+   */
+  async getGarminRequestToken(
+    ctx: ActionCtx,
+    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,
+    });
+  }
+
+  /**
+   * Step 3 of the Garmin OAuth 1.0a flow + initial data sync.
+   *
+   * 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).
+   *
+   * Call this from your OAuth callback endpoint after receiving the
+   * `oauth_verifier` 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
+   * @returns `{ connectionId, synced, errors }`
+   *
+   * @example
+   * ```ts
+   * export const handleGarminCallback = action({
+   *   args: {
+   *     userId: v.string(),
+   *     token: v.string(),
+   *     tokenSecret: v.string(),
+   *     verifier: v.string(),
+   *   },
+   *   handler: async (ctx, args) => {
+   *     return await soma.connectGarmin(ctx, args);
+   *   },
+   * });
+   * ```
+   */
+  async connectGarmin(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      token: string;
+      tokenSecret: string;
+      verifier: string;
+    },
+  ) {
+    const config = this.requireGarminConfig();
+    return await ctx.runAction(this.component.garmin.connectGarmin, {
+      ...args,
+      consumerKey: config.consumerKey,
+      consumerSecret: config.consumerSecret,
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * Fetches activities, dailies, sleep, body composition, and menstruation
+   * data for the specified time range (defaults to last 30 days).
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional start of time range (Unix epoch seconds)
+   * @param args.endTimeInSeconds - Optional end of time range (Unix epoch seconds)
+   * @returns `{ synced, errors }`
+   *
+   * @example
+   * ```ts
+   * export const syncGarmin = action({
+   *   args: { userId: v.string() },
+   *   handler: async (ctx, { userId }) => {
+   *     return await soma.syncGarmin(ctx, { userId });
+   *   },
+   * });
+   * ```
+   */
+  async syncGarmin(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireGarminConfig();
+    return await ctx.runAction(this.component.garmin.syncGarmin, {
+      ...args,
+      consumerKey: config.consumerKey,
+      consumerSecret: config.consumerSecret,
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   *
+   * @example
+   * ```ts
+   * export const disconnectGarmin = action({
+   *   args: { userId: v.string() },
+   *   handler: async (ctx, { userId }) => {
+   *     await soma.disconnectGarmin(ctx, { userId });
+   *   },
+   * });
+   * ```
+   */
+  async disconnectGarmin(
+    ctx: ActionCtx,
+    args: { userId: string },
+  ) {
+    return await ctx.runAction(this.component.garmin.disconnectGarmin, args);
+  }
 }
 
 // ─── Shared Types ────────────────────────────────────────────────────────────
@@ -862,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/api.ts

@@ -8,6 +8,7 @@
  * @module
  */
 
+import type * as garmin from "../garmin.js";
 import type * as private_ from "../private.js";
 import type * as public_ from "../public.js";
 import type * as strava from "../strava.js";
@@ -33,6 +34,7 @@ import type {
 import { anyApi, componentsGeneric } from "convex/server";
 
 const fullApi: ApiFromModules<{
+  garmin: typeof garmin;
   private: typeof private_;
   public: typeof public_;
   strava: typeof strava;

package/src/component/_generated/component.ts

@@ -23,6 +23,95 @@ 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",
+        {
+          consumerKey: string;
+          consumerSecret: string;
+          token: string;
+          tokenSecret: string;
+          userId: string;
+          verifier: string;
+        },
+        {
+          connectionId: string;
+          errors: Array<{ error: string; id: string; type: string }>;
+          synced: {
+            activities: number;
+            body: number;
+            dailies: number;
+            menstruation: number;
+            sleep: number;
+          };
+        },
+        Name
+      >;
+      disconnectGarmin: FunctionReference<
+        "action",
+        "internal",
+        { userId: string },
+        null,
+        Name
+      >;
+      getGarminRequestToken: FunctionReference<
+        "action",
+        "internal",
+        {
+          callbackUrl?: string;
+          consumerKey: string;
+          consumerSecret: string;
+          userId?: string;
+        },
+        { authUrl: string; token: string; tokenSecret: string },
+        Name
+      >;
+      syncGarmin: FunctionReference<
+        "action",
+        "internal",
+        {
+          consumerKey: string;
+          consumerSecret: string;
+          endTimeInSeconds?: number;
+          startTimeInSeconds?: number;
+          userId: string;
+        },
+        {
+          errors: Array<{ error: string; id: string; type: string }>;
+          synced: {
+            activities: number;
+            body: number;
+            dailies: number;
+            menstruation: number;
+            sleep: number;
+          };
+        },
+        Name
+      >;
+    };
     public: {
       connect: FunctionReference<
         "mutation",