@nativesquare/soma 0.6.0 → 0.7.0

package/src/component/_generated/component.ts

@@ -85,6 +85,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { authUrl: string; codeVerifier: string; state: string },
         Name
       >;
+      pushPlannedWorkout: FunctionReference<
+        "action",
+        "internal",
+        {
+          clientId: string;
+          clientSecret: string;
+          plannedWorkoutId: string;
+          userId: string;
+          workoutProvider?: string;
+        },
+        { garminScheduleId: number | null; garminWorkoutId: number },
+        Name
+      >;
       syncGarmin: FunctionReference<
         "action",
         "internal",
@@ -123,6 +136,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         null,
         Name
       >;
+      deletePlannedWorkout: FunctionReference<
+        "mutation",
+        "internal",
+        { plannedWorkoutId: string },
+        null,
+        Name
+      >;
       disconnect: FunctionReference<
         "mutation",
         "internal",
@@ -165,6 +185,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         },
         Name
       >;
+      getPlannedWorkout: FunctionReference<
+        "query",
+        "internal",
+        { plannedWorkoutId: string },
+        any,
+        Name
+      >;
       ingestActivity: FunctionReference<
         "mutation",
         "internal",
@@ -1019,6 +1046,89 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         string,
         Name
       >;
+      ingestPlannedWorkout: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          connectionId: string;
+          metadata: {
+            created_date?: string;
+            description?: string;
+            estimated_calories?: number;
+            estimated_distance_meters?: number;
+            estimated_duration_seconds?: number;
+            estimated_elevation_gain_meters?: number;
+            estimated_energy_kj?: number;
+            estimated_if?: number;
+            estimated_pace_minutes_per_kilometer?: number;
+            estimated_speed_meters_per_second?: number;
+            estimated_tscore?: number;
+            estimated_tss?: number;
+            id?: string;
+            name?: string;
+            planned_date?: string;
+            pool_length_meters?: number;
+            provider?: string;
+            type?: string;
+          };
+          steps?: Array<{
+            description?: string;
+            durations?: Array<{
+              calories?: number;
+              distance_meters?: number;
+              duration_type?: string;
+              hr_above_bpm?: number;
+              hr_below_bpm?: number;
+              power_above_watts?: number;
+              power_below_watts?: number;
+              reps?: number;
+              rest_seconds?: number;
+              seconds?: number;
+              steps?: number;
+            }>;
+            equipment_type?: string;
+            exercise_category?: string;
+            exercise_name?: string;
+            intensity?: string | number;
+            name?: string;
+            order?: number;
+            steps?: Array<any>;
+            stroke_type?: string;
+            targets?: Array<{
+              cadence?: number;
+              cadence_high?: number;
+              cadence_low?: number;
+              hr_bpm_high?: number;
+              hr_bpm_low?: number;
+              hr_percentage?: number;
+              hr_percentage_high?: number;
+              hr_percentage_low?: number;
+              if_high?: number;
+              if_low?: number;
+              pace_minutes_per_kilometer?: number;
+              power_percentage?: number;
+              power_percentage_high?: number;
+              power_percentage_low?: number;
+              power_watt?: number;
+              power_watt_high?: number;
+              power_watt_low?: number;
+              repetitions?: number;
+              speed_meters_per_second?: number;
+              speed_percentage?: number;
+              speed_percentage_high?: number;
+              speed_percentage_low?: number;
+              swim_strokes?: number;
+              target_type?: string;
+              tss?: number;
+            }>;
+            type?: string;
+            weight_kg?: number;
+          }>;
+          userId: string;
+        },
+        string,
+        Name
+      >;
       ingestSleep: FunctionReference<
         "mutation",
         "internal",
@@ -1243,6 +1353,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
+      listPlannedWorkouts: FunctionReference<
+        "query",
+        "internal",
+        {
+          endDate?: string;
+          limit?: number;
+          order?: "asc" | "desc";
+          startDate?: string;
+          userId: string;
+        },
+        any,
+        Name
+      >;
       listSleep: FunctionReference<
         "query",
         "internal",
@@ -1351,6 +1474,25 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
+      paginatePlannedWorkouts: FunctionReference<
+        "query",
+        "internal",
+        {
+          endDate?: string;
+          paginationOpts: {
+            cursor: string | null;
+            endCursor?: string | null;
+            id?: number;
+            maximumBytesRead?: number;
+            maximumRowsRead?: number;
+            numItems: number;
+          };
+          startDate?: string;
+          userId: string;
+        },
+        any,
+        Name
+      >;
       paginateSleep: FunctionReference<
         "query",
         "internal",

package/src/component/garmin.ts

@@ -26,6 +26,7 @@ import { transformDaily } from "../garmin/daily.js";
 import { transformSleep } from "../garmin/sleep.js";
 import { transformBody } from "../garmin/body.js";
 import { transformMenstruation } from "../garmin/menstruation.js";
+import { transformPlannedWorkoutToGarmin } from "../garmin/plannedWorkout.js";
 
 // Use anyApi to avoid circular type references between this file and _generated/api.ts.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -562,6 +563,123 @@ export const disconnectGarmin = action({
   },
 });
 
+// ─── Training API ────────────────────────────────────────────────────────────
+
+/**
+ * Push a planned workout from Soma's DB to Garmin Connect.
+ *
+ * Reads the planned workout document, transforms it to Garmin Training API V2
+ * format, creates the workout at Garmin, and optionally schedules it if a
+ * `planned_date` is set in the metadata.
+ *
+ * Returns the Garmin workout ID and schedule ID (if scheduled).
+ */
+export const pushPlannedWorkout = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    plannedWorkoutId: v.string(),
+    workoutProvider: v.optional(v.string()),
+  },
+  returns: v.object({
+    garminWorkoutId: v.number(),
+    garminScheduleId: v.union(v.number(), v.null()),
+  }),
+  handler: async (ctx, args) => {
+    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;
+
+    const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
+      connectionId,
+    });
+    if (!tokenDoc) {
+      throw new Error(
+        "No Garmin tokens found for this connection. " +
+          "The connection may have been created before token storage was available.",
+      );
+    }
+
+    let accessToken = tokenDoc.accessToken;
+
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (
+      tokenDoc.expiresAt &&
+      tokenDoc.refreshToken &&
+      nowSeconds >= tokenDoc.expiresAt - REFRESH_BUFFER_SECONDS
+    ) {
+      const refreshed = await refreshToken({
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        refreshToken: tokenDoc.refreshToken,
+      });
+
+      accessToken = refreshed.access_token;
+      const newExpiresAt = nowSeconds + refreshed.expires_in;
+      await ctx.runMutation(internalApi.garmin.storeTokens, {
+        connectionId,
+        accessToken: refreshed.access_token,
+        refreshToken: refreshed.refresh_token,
+        expiresAt: newExpiresAt,
+      });
+    }
+
+    const plannedWorkout = await ctx.runQuery(
+      publicApi.public.getPlannedWorkout,
+      { plannedWorkoutId: args.plannedWorkoutId as never },
+    );
+    if (!plannedWorkout) {
+      throw new Error(
+        `Planned workout "${args.plannedWorkoutId}" not found.`,
+      );
+    }
+
+    const providerName = args.workoutProvider ?? "Soma";
+    const garminWorkout = transformPlannedWorkoutToGarmin(
+      plannedWorkout,
+      providerName,
+    );
+
+    const client = new GarminClient({ accessToken });
+    const created = await client.createWorkout(garminWorkout);
+
+    if (!created.workoutId) {
+      throw new Error("Garmin API did not return a workoutId after creation.");
+    }
+
+    let garminScheduleId: number | null = null;
+
+    const plannedDate = plannedWorkout.metadata?.planned_date;
+    if (plannedDate) {
+      const schedule = await client.createSchedule(
+        created.workoutId,
+        plannedDate,
+      );
+      garminScheduleId = schedule.scheduleId ?? null;
+    }
+
+    return {
+      garminWorkoutId: created.workoutId,
+      garminScheduleId,
+    };
+  },
+});
+
 // ─── Internal Helpers ────────────────────────────────────────────────────────
 
 interface SyncAllConfig {

package/src/component/public.ts

@@ -8,6 +8,7 @@ import { dailyValidator } from "./validators/daily.js";
 import { sleepValidator } from "./validators/sleep.js";
 import { menstruationValidator } from "./validators/menstruation.js";
 import { nutritionValidator } from "./validators/nutrition.js";
+import { plannedWorkoutValidator } from "./validators/plannedWorkout.js";
 
 // ─── Return Validators ──────────────────────────────────────────────────────
 
@@ -776,6 +777,140 @@ export const paginateMenstruation = query({
   },
 });
 
+// ── Planned Workouts ────────────────────────────────────────────────────────
+
+/**
+ * Ingest a planned workout record.
+ *
+ * Upserts by `connectionId + metadata.id` when an id is present.
+ * Falls back to insert if no id is provided.
+ */
+export const ingestPlannedWorkout = mutation({
+  args: plannedWorkoutValidator,
+  returns: v.id("plannedWorkouts"),
+  handler: async (ctx, args) => {
+    const metadataId = args.metadata.id;
+    if (metadataId) {
+      const results = await ctx.db
+        .query("plannedWorkouts")
+        .withIndex("by_connectionId", (q) =>
+          q.eq("connectionId", args.connectionId),
+        )
+        .collect();
+      const existing = results.find((r) => r.metadata.id === metadataId);
+
+      if (existing) {
+        await ctx.db.patch(existing._id, args);
+        return existing._id;
+      }
+    }
+    return await ctx.db.insert("plannedWorkouts", args);
+  },
+});
+
+/**
+ * List planned workout records for a user, optionally filtered by planned date range.
+ *
+ * @param args.userId - The host app's user identifier
+ * @param args.startDate - Optional lower bound (inclusive) on metadata.planned_date (YYYY-MM-DD)
+ * @param args.endDate - Optional upper bound (inclusive) on metadata.planned_date (YYYY-MM-DD)
+ * @param args.order - Sort order: "asc" or "desc" (default: "desc")
+ * @param args.limit - Optional max number of results to return
+ */
+export const listPlannedWorkouts = query({
+  args: {
+    userId: v.string(),
+    startDate: v.optional(v.string()),
+    endDate: v.optional(v.string()),
+    order: v.optional(v.union(v.literal("asc"), v.literal("desc"))),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const q = ctx.db
+      .query("plannedWorkouts")
+      .withIndex("by_userId_plannedDate", (q) => {
+        const base = q.eq("userId", args.userId);
+        if (args.startDate !== undefined && args.endDate !== undefined) {
+          return base
+            .gte("metadata.planned_date", args.startDate)
+            .lte("metadata.planned_date", args.endDate);
+        }
+        if (args.startDate !== undefined) {
+          return base.gte("metadata.planned_date", args.startDate);
+        }
+        if (args.endDate !== undefined) {
+          return base.lte("metadata.planned_date", args.endDate);
+        }
+        return base;
+      })
+      .order(args.order ?? "desc");
+    return args.limit ? await q.take(args.limit) : await q.collect();
+  },
+});
+
+/**
+ * Paginate planned workout records for a user, optionally filtered by planned date range.
+ *
+ * Returns `{ page, isDone, continueCursor }` for cursor-based pagination.
+ */
+export const paginatePlannedWorkouts = query({
+  args: {
+    userId: v.string(),
+    startDate: v.optional(v.string()),
+    endDate: v.optional(v.string()),
+    paginationOpts: paginationOptsValidator,
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("plannedWorkouts")
+      .withIndex("by_userId_plannedDate", (q) => {
+        const base = q.eq("userId", args.userId);
+        if (args.startDate !== undefined && args.endDate !== undefined) {
+          return base
+            .gte("metadata.planned_date", args.startDate)
+            .lte("metadata.planned_date", args.endDate);
+        }
+        if (args.startDate !== undefined) {
+          return base.gte("metadata.planned_date", args.startDate);
+        }
+        if (args.endDate !== undefined) {
+          return base.lte("metadata.planned_date", args.endDate);
+        }
+        return base;
+      })
+      .order("desc")
+      .paginate(args.paginationOpts);
+  },
+});
+
+/**
+ * Delete a planned workout by document ID.
+ */
+export const deletePlannedWorkout = mutation({
+  args: { plannedWorkoutId: v.id("plannedWorkouts") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db.get(args.plannedWorkoutId);
+    if (!existing) {
+      throw new Error(
+        `Planned workout "${args.plannedWorkoutId}" not found`,
+      );
+    }
+    await ctx.db.delete(existing._id);
+    return null;
+  },
+});
+
+/**
+ * Get a single planned workout by document ID.
+ */
+export const getPlannedWorkout = query({
+  args: { plannedWorkoutId: v.id("plannedWorkouts") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.plannedWorkoutId);
+  },
+});
+
 // ── Athletes ────────────────────────────────────────────────────────────────
 
 /**

package/src/garmin/client.ts

@@ -8,6 +8,8 @@ import type {
   GarminSleep,
   GarminBodyComposition,
   GarminMenstrualCycleData,
+  GarminWorkout,
+  GarminWorkoutSchedule,
 } from "./types.js";
 
 const DEFAULT_BASE_URL = "https://apis.garmin.com";
@@ -146,6 +148,101 @@ export class GarminClient {
     );
   }
 
+  // ─── Training API V2 ────────────────────────────────────────────────
+
+  /**
+   * Check which permissions the user has granted.
+   *
+   * Garmin API: `GET /userPermissions/`
+   */
+  async getUserPermissions(): Promise<string[]> {
+    return this.get<string[]>("/userPermissions/");
+  }
+
+  /**
+   * Create a workout in Garmin Connect.
+   *
+   * Garmin API: `POST /workoutportal/workout/v2`
+   * Note: uses a different base path than other Training API endpoints.
+   */
+  async createWorkout(workout: GarminWorkout): Promise<GarminWorkout> {
+    return this.post<GarminWorkout>("/workoutportal/workout/v2", workout);
+  }
+
+  /**
+   * Retrieve a workout by ID.
+   *
+   * Garmin API: `GET /training-api/workout/v2/{workoutId}`
+   */
+  async getWorkout(workoutId: number): Promise<GarminWorkout> {
+    return this.get<GarminWorkout>(
+      `/training-api/workout/v2/${workoutId}`,
+    );
+  }
+
+  /**
+   * Update a workout by ID.
+   *
+   * Garmin API: `PUT /training-api/workout/v2/{workoutId}`
+   */
+  async updateWorkout(
+    workoutId: number,
+    workout: GarminWorkout,
+  ): Promise<GarminWorkout> {
+    return this.put<GarminWorkout>(
+      `/training-api/workout/v2/${workoutId}`,
+      workout,
+    );
+  }
+
+  /**
+   * Delete a workout by ID.
+   *
+   * Garmin API: `DELETE /training-api/workout/v2/{workoutId}`
+   */
+  async deleteWorkout(workoutId: number): Promise<void> {
+    await this.del(`/training-api/workout/v2/${workoutId}`);
+  }
+
+  /**
+   * Schedule a workout to a specific date on the user's calendar.
+   *
+   * Garmin API: `POST /training-api/schedule/`
+   */
+  async createSchedule(
+    workoutId: number,
+    date: string,
+  ): Promise<GarminWorkoutSchedule> {
+    return this.post<GarminWorkoutSchedule>("/training-api/schedule/", {
+      workoutId,
+      date,
+    });
+  }
+
+  /**
+   * Retrieve workout schedules for a date range.
+   *
+   * Garmin API: `GET /training-api/schedule?startDate=...&endDate=...`
+   */
+  async getSchedulesByDate(
+    startDate: string,
+    endDate: string,
+  ): Promise<GarminWorkoutSchedule[]> {
+    return this.get<GarminWorkoutSchedule[]>("/training-api/schedule", {
+      startDate,
+      endDate,
+    });
+  }
+
+  /**
+   * Delete a workout schedule by ID.
+   *
+   * Garmin API: `DELETE /training-api/schedule/{scheduleId}`
+   */
+  async deleteSchedule(scheduleId: number): Promise<void> {
+    await this.del(`/training-api/schedule/${scheduleId}`);
+  }
+
   // ─── User Deregistration ──────────────────────────────────────────────
 
   /**
@@ -204,6 +301,73 @@ export class GarminClient {
 
     return (await response.json()) as T;
   }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new GarminApiError(
+        `Garmin API error: ${response.status} ${response.statusText}`,
+        response.status,
+        text,
+      );
+    }
+
+    return (await response.json()) as T;
+  }
+
+  private async put<T>(path: string, body: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new GarminApiError(
+        `Garmin API error: ${response.status} ${response.statusText}`,
+        response.status,
+        text,
+      );
+    }
+
+    return (await response.json()) as T;
+  }
+
+  private async del(path: string): Promise<void> {
+    const url = `${this.baseUrl}${path}`;
+    const response = await fetch(url, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new GarminApiError(
+        `Garmin API error: ${response.status} ${response.statusText}`,
+        response.status,
+        text,
+      );
+    }
+  }
 }
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────