@nativesquare/soma 0.3.0 → 0.5.0

package/src/component/garmin.ts

@@ -0,0 +1,711 @@
+// ─── Garmin Component Actions ────────────────────────────────────────────────
+// Public actions that handle the full Garmin OAuth + sync lifecycle.
+// The host app calls these through the Soma class, which threads the
+// credentials automatically from env vars or constructor config.
+//
+// Internal mutations manage the providerTokens table (token CRUD).
+
+import { v } from "convex/values";
+import { anyApi } from "convex/server";
+import {
+  action,
+  internalMutation,
+  internalQuery,
+} from "./_generated/server.js";
+import { getRequestToken, getAccessToken } from "../garmin/auth.js";
+import { GarminClient } from "../garmin/client.js";
+import { transformActivity } from "../garmin/activity.js";
+import { transformDaily } from "../garmin/daily.js";
+import { transformSleep } from "../garmin/sleep.js";
+import { transformBody } from "../garmin/body.js";
+import { transformMenstruation } from "../garmin/menstruation.js";
+
+// Use anyApi to avoid circular type references between this file and _generated/api.ts.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const publicApi: any = anyApi;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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 ─────────────────────────────────────────────────────
+
+/**
+ * Store OAuth 1.0a tokens for a Garmin connection.
+ * Upserts by connectionId — one token record per connection.
+ */
+export const storeTokens = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    accessToken: v.string(),
+    tokenSecret: v.string(),
+  },
+  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,
+        tokenSecret: args.tokenSecret,
+      });
+      return null;
+    }
+
+    await ctx.db.insert("providerTokens", {
+      connectionId: args.connectionId,
+      accessToken: args.accessToken,
+      tokenSecret: args.tokenSecret,
+    });
+    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()),
+      tokenSecret: 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;
+  },
+});
+
+// ─── Public Actions ──────────────────────────────────────────────────────────
+
+/**
+ * Step 1 of OAuth: obtain a request token and return the authorization URL.
+ *
+ * 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) => {
+    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,
+      authUrl: result.authUrl,
+    };
+  },
+});
+
+/**
+ * Step 3 of OAuth + initial sync.
+ *
+ * Exchanges the request token + verifier for permanent access tokens,
+ * creates/reactivates the Soma connection, stores tokens, and syncs
+ * the last 30 days of all data types.
+ */
+export const connectGarmin = action({
+  args: {
+    userId: v.string(),
+    consumerKey: v.string(),
+    consumerSecret: v.string(),
+    token: v.string(),
+    tokenSecret: v.string(),
+    verifier: 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. Exchange request token for permanent access token
+    const accessTokenResult = await getAccessToken({
+      consumerKey: args.consumerKey,
+      consumerSecret: args.consumerSecret,
+      token: args.token,
+      tokenSecret: args.tokenSecret,
+      verifier: args.verifier,
+    });
+
+    // 2. Create/reactivate the Soma connection
+    const connectionId = await ctx.runMutation(publicApi.public.connect, {
+      userId: args.userId,
+      provider: "GARMIN",
+    });
+
+    // 3. Store permanent OAuth tokens
+    await ctx.runMutation(internalApi.garmin.storeTokens, {
+      connectionId,
+      accessToken: accessTokenResult.oauthToken,
+      tokenSecret: accessTokenResult.oauthTokenSecret,
+    });
+
+    // 4. 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: args.userId,
+      consumerKey: args.consumerKey,
+      consumerSecret: args.consumerSecret,
+      timeRange,
+    });
+
+    // 5. Update lastDataUpdate timestamp
+    await ctx.runMutation(publicApi.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
+    return {
+      connectionId,
+      synced: result.synced,
+      errors: result.errors,
+    };
+  },
+});
+
+/**
+ * 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.
+ *
+ * Looks up the stored tokens and syncs all data types for the specified
+ * time range (defaults to last 30 days).
+ */
+export const syncGarmin = action({
+  args: {
+    userId: v.string(),
+    consumerKey: v.string(),
+    consumerSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  returns: v.object({
+    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 connection
+    const connection = await ctx.runQuery(
+      internalApi.private.getConnectionByProvider,
+      { userId: args.userId, provider: "GARMIN" },
+    );
+    if (!connection) {
+      throw new Error(
+        `No Garmin connection found for user "${args.userId}". ` +
+          "Call connectGarmin first.",
+      );
+    }
+    if (!connection.active) {
+      throw new Error(
+        `Garmin connection for user "${args.userId}" is inactive. Reconnect first.`,
+      );
+    }
+
+    const connectionId = connection._id;
+
+    // 2. Get stored tokens
+    const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
+      connectionId,
+    });
+    if (!tokenDoc || !tokenDoc.tokenSecret) {
+      throw new Error(
+        "No Garmin tokens found for this connection. " +
+          "The connection may have been created before token storage was available.",
+      );
+    }
+
+    // 3. Create client and sync
+    const client = new GarminClient({
+      consumerKey: args.consumerKey,
+      consumerSecret: args.consumerSecret,
+      accessToken: tokenDoc.accessToken,
+      tokenSecret: tokenDoc.tokenSecret,
+    });
+
+    const now = Math.floor(Date.now() / 1000);
+    const timeRange = {
+      uploadStartTimeInSeconds:
+        args.startTimeInSeconds ?? now - DEFAULT_SYNC_DAYS * 86400,
+      uploadEndTimeInSeconds: args.endTimeInSeconds ?? now,
+    };
+
+    const result = await syncAllTypes(ctx, client, {
+      connectionId,
+      userId: args.userId,
+      consumerKey: args.consumerKey,
+      consumerSecret: args.consumerSecret,
+      timeRange,
+    });
+
+    // 4. Update lastDataUpdate timestamp
+    await ctx.runMutation(publicApi.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
+    return result;
+  },
+});
+
+/**
+ * Disconnect a user from Garmin.
+ *
+ * Deletes stored tokens and sets the connection to inactive.
+ * Garmin OAuth 1.0a tokens can't be revoked via API, so we just clean up locally.
+ */
+export const disconnectGarmin = action({
+  args: {
+    userId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    // 1. Look up connection
+    const connection = await ctx.runQuery(
+      internalApi.private.getConnectionByProvider,
+      { userId: args.userId, provider: "GARMIN" },
+    );
+    if (!connection) {
+      throw new Error(
+        `No Garmin connection found for user "${args.userId}".`,
+      );
+    }
+
+    const connectionId = connection._id;
+
+    // 2. Delete stored tokens
+    await ctx.runMutation(internalApi.garmin.deleteTokens, { connectionId });
+
+    // 3. Set connection inactive
+    await ctx.runMutation(publicApi.public.disconnect, {
+      userId: args.userId,
+      provider: "GARMIN",
+    });
+
+    return null;
+  },
+});
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+interface SyncAllConfig {
+  connectionId: string;
+  userId: string;
+  consumerKey: string;
+  consumerSecret: string;
+  timeRange: { uploadStartTimeInSeconds: number; uploadEndTimeInSeconds: number };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ActionContext = { runMutation: (ref: any, args: any) => Promise<any> };
+
+async function syncAllTypes(
+  ctx: ActionContext,
+  client: GarminClient,
+  config: SyncAllConfig,
+) {
+  const { connectionId, userId, timeRange } = config;
+
+  const synced = { activities: 0, dailies: 0, sleep: 0, body: 0, menstruation: 0 };
+  const errors: Array<{ type: string; id: string; error: string }> = [];
+
+  // ── Activities ──────────────────────────────────────────────────────────
+  try {
+    const activities = await client.getActivities(timeRange);
+    for (const activity of activities) {
+      try {
+        const data = transformActivity(activity);
+        await ctx.runMutation(publicApi.public.ingestActivity, {
+          connectionId,
+          userId,
+          ...data,
+        } as never);
+        synced.activities++;
+      } catch (err) {
+        errors.push({
+          type: "activity",
+          id: activity.summaryId ?? String(activity.activityId),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      type: "activity",
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // ── Dailies ─────────────────────────────────────────────────────────────
+  try {
+    const dailies = await client.getDailies(timeRange);
+    for (const daily of dailies) {
+      try {
+        const data = transformDaily(daily);
+        await ctx.runMutation(publicApi.public.ingestDaily, {
+          connectionId,
+          userId,
+          ...data,
+        } as never);
+        synced.dailies++;
+      } catch (err) {
+        errors.push({
+          type: "daily",
+          id: daily.summaryId ?? daily.calendarDate,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      type: "daily",
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // ── Sleep ───────────────────────────────────────────────────────────────
+  try {
+    const sleeps = await client.getSleeps(timeRange);
+    for (const sleep of sleeps) {
+      try {
+        const data = transformSleep(sleep);
+        await ctx.runMutation(publicApi.public.ingestSleep, {
+          connectionId,
+          userId,
+          ...data,
+        } as never);
+        synced.sleep++;
+      } catch (err) {
+        errors.push({
+          type: "sleep",
+          id: sleep.summaryId ?? sleep.calendarDate,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      type: "sleep",
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // ── Body ────────────────────────────────────────────────────────────────
+  try {
+    const bodyComps = await client.getBodyCompositions(timeRange);
+    for (const body of bodyComps) {
+      try {
+        const data = transformBody(body);
+        await ctx.runMutation(publicApi.public.ingestBody, {
+          connectionId,
+          userId,
+          ...data,
+        } as never);
+        synced.body++;
+      } catch (err) {
+        errors.push({
+          type: "body",
+          id: body.summaryId ?? String(body.measurementTimeInSeconds),
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      type: "body",
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  // ── Menstruation ────────────────────────────────────────────────────────
+  try {
+    const records = await client.getMenstrualCycleData(timeRange);
+    for (const record of records) {
+      try {
+        const data = transformMenstruation(record);
+        await ctx.runMutation(publicApi.public.ingestMenstruation, {
+          connectionId,
+          userId,
+          ...data,
+        } as never);
+        synced.menstruation++;
+      } catch (err) {
+        errors.push({
+          type: "menstruation",
+          id: record.summaryId ?? record.calendarDate,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  } catch (err) {
+    errors.push({
+      type: "menstruation",
+      id: "fetch",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return { synced, errors };
+}