@nativesquare/soma 0.3.0 → 0.4.0

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/NativeSquare/soma/issues"
   },
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -24,6 +24,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 +74,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 +113,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 +861,158 @@ 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. The host app must store `token` and `tokenSecret`
+   * temporarily (e.g., in session/cookie) and pass them to `connectGarmin`
+   * after the user authorizes.
+   *
+   * @param ctx - Action context from the host app
+   * @param opts.callbackUrl - The URL Garmin will redirect to after authorization
+   * @returns `{ token, tokenSecret, authUrl }`
+   *
+   * @example
+   * ```ts
+   * const { token, tokenSecret, authUrl } = await soma.getGarminRequestToken(ctx, {
+   *   callbackUrl: "https://your-app.com/api/garmin/callback",
+   * });
+   * // Store token + tokenSecret in session, redirect user to authUrl
+   * ```
+   */
+  async getGarminRequestToken(
+    ctx: ActionCtx,
+    opts: { callbackUrl?: string },
+  ) {
+    const config = this.requireGarminConfig();
+    return await ctx.runAction(this.component.garmin.getGarminRequestToken, {
+      consumerKey: config.consumerKey,
+      consumerSecret: config.consumerSecret,
+      callbackUrl: opts.callbackUrl,
+    });
+  }
+
+  /**
+   * 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,
+    });
+  }
+
+  /**
+   * 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 ────────────────────────────────────────────────────────────

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,68 @@ import type { FunctionReference } from "convex/server";
  */
 export type ComponentApi<Name extends string | undefined = string | undefined> =
   {
+    garmin: {
+      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 },
+        { 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",