@nativesquare/soma 0.10.2 → 0.12.0

package/src/client/garmin.ts

@@ -0,0 +1,487 @@
+import type { SomaComponent } from "./index.js";
+import type { ActionCtx, SomaGarminConfig } from "./types.js";
+
+export class SomaGarmin {
+  constructor(
+    private component: SomaComponent,
+    private requireConfig: () => SomaGarminConfig,
+  ) {}
+
+  /**
+   * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
+   *
+   * The state and code verifier are stored inside the component automatically,
+   * and the callback handler registered by `registerRoutes` completes
+   * the flow without further host-app intervention.
+   *
+   * @param ctx - Action context from the host app
+   * @param opts.userId - The host app's user identifier
+   * @param opts.redirectUri - Optional override for the OAuth callback URL
+   * @returns `{ authUrl, state }`
+   *
+   * @example
+   * ```ts
+   * const { authUrl } = await soma.garmin.getAuthUrl(ctx, {
+   *   userId: "user_123",
+   *   redirectUri: "https://your-app.convex.site/api/garmin/callback",
+   * });
+   * // Redirect user to authUrl — the callback is handled automatically
+   * ```
+   */
+  async getAuthUrl(
+    ctx: ActionCtx,
+    opts: { userId: string; redirectUri?: string },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.getGarminAuthUrl, {
+      clientId: config.clientId,
+      redirectUri: opts.redirectUri,
+      userId: opts.userId,
+    });
+  }
+
+  /**
+   * Disconnect a user from Garmin.
+   *
+   * Deregisters the user at Garmin (best-effort), deletes stored tokens,
+   * and sets the connection to inactive.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   *
+   * @example
+   * ```ts
+   * await soma.garmin.disconnect(ctx, { userId: "user_123" });
+   * ```
+   */
+  async disconnect(
+    ctx: ActionCtx,
+    args: { userId: string },
+  ) {
+    return await ctx.runAction(this.component.garmin.public.disconnectGarmin, args);
+  }
+
+  /**
+   * Pull activity summaries from Garmin.
+   *
+   * Fetches activities, transforms them into the normalized Soma schema,
+   * and ingests them with automatic deduplication.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullActivities(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullActivities, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull daily wellness summaries from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullDailies(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullDailies, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull sleep summaries from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullSleep(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullSleep, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull body composition data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullBody(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullBody, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull menstrual cycle tracking data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullMenstruation(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullMenstruation, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull blood pressure readings from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullBloodPressures(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullBloodPressures, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull skin temperature data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullSkinTemperature(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullSkinTemperature, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull user metrics (VO2 max, fitness age, etc.) from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullUserMetrics(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullUserMetrics, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull heart rate variability (HRV) summaries from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullHRV(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullHRV, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull stress detail data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullStressDetails(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullStressDetails, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull pulse oximetry (SpO2) data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullPulseOx(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullPulseOx, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull respiration (breathing rate) data from Garmin.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   */
+  async pullRespiration(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullRespiration, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull all supported data types from Garmin in a single call.
+   *
+   * Equivalent to calling every individual `pull*` method. Automatically
+   * refreshes the access token if expired.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.startTimeInSeconds - Optional Unix epoch lower bound
+   * @param args.endTimeInSeconds - Optional Unix epoch upper bound
+   *
+   * @example
+   * ```ts
+   * await soma.garmin.pullAll(ctx, { userId: "user_123" });
+   * ```
+   */
+  async pullAll(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      startTimeInSeconds?: number;
+      endTimeInSeconds?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pullAll, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Push a planned workout to Garmin Connect.
+   *
+   * Creates the workout on the user's Garmin account from a planned
+   * workout stored in Soma.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   * @param args.workoutProvider - Optional provider identifier for the workout source
+   */
+  async pushWorkout(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+      workoutProvider?: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pushWorkout, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Schedule a planned workout on the user's Garmin calendar.
+   *
+   * The workout must already exist on Garmin (via `pushWorkout`).
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   * @param args.date - Optional target date (YYYY-MM-DD); defaults to the workout's planned_date
+   */
+  async pushSchedule(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+      date?: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.pushSchedule, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Delete a planned workout from Garmin Connect.
+   *
+   * Removes the workout from the user's Garmin account.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   */
+  async deleteWorkout(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.deleteWorkout, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Remove a scheduled workout from the user's Garmin calendar.
+   *
+   * Unschedules the workout without deleting the workout itself.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.plannedWorkoutId - The Soma planned workout document ID
+   */
+  async deleteSchedule(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      plannedWorkoutId: string;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.garmin.public.deleteSchedule, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+}