@nativesquare/soma 0.5.0 → 0.7.0

package/src/garmin/client.ts

@@ -1,7 +1,6 @@
 // ─── Garmin Health API Client ────────────────────────────────────────────────
 // Lightweight, fetch-based client for the Garmin Health API.
-// Every request is signed with OAuth 1.0a using the consumer and user tokens.
-// Uses the Web Crypto API for HMAC-SHA1 signing and global `fetch`.
+// Authenticates requests with an OAuth 2.0 Bearer token.
 
 import type {
   GarminActivity,
@@ -9,28 +8,18 @@ import type {
   GarminSleep,
   GarminBodyComposition,
   GarminMenstrualCycleData,
+  GarminWorkout,
+  GarminWorkoutSchedule,
 } from "./types.js";
-import {
-  generateNonce,
-  getTimestamp,
-  buildOAuthSignature,
-  buildOAuthHeader,
-} from "./auth.js";
 
 const DEFAULT_BASE_URL = "https://apis.garmin.com";
 
 export interface GarminClientOptions {
-  /** Your application's consumer key (from Garmin Developer Portal). */
-  consumerKey: string;
-  /** Your application's consumer secret. */
-  consumerSecret: string;
-  /** The user's permanent OAuth access token. */
+  /** The user's OAuth 2.0 access token. */
   accessToken: string;
-  /** The user's permanent OAuth token secret. */
-  tokenSecret: string;
   /**
    * Base URL of the Garmin Health API.
-   * Defaults to `https://apis.garmin.com`.
+   * @default "https://apis.garmin.com"
    */
   baseUrl?: string;
 }
@@ -38,17 +27,14 @@ export interface GarminClientOptions {
 /**
  * A lightweight client for the Garmin Health API.
  *
- * All requests are signed with OAuth 1.0a. Time-range parameters
+ * All requests are authenticated with a Bearer token. Time-range parameters
  * use Unix epoch seconds for `uploadStartTimeInSeconds` and
  * `uploadEndTimeInSeconds`.
  *
  * @example
  * ```ts
  * const client = new GarminClient({
- *   consumerKey: "your_key",
- *   consumerSecret: "your_secret",
- *   accessToken: "user_token",
- *   tokenSecret: "user_secret",
+ *   accessToken: "user_access_token",
  * });
  *
  * const dailies = await client.getDailies({
@@ -58,17 +44,11 @@ export interface GarminClientOptions {
  * ```
  */
 export class GarminClient {
-  private readonly consumerKey: string;
-  private readonly consumerSecret: string;
   private readonly accessToken: string;
-  private readonly tokenSecret: string;
   private readonly baseUrl: string;
 
   constructor(opts: GarminClientOptions) {
-    this.consumerKey = opts.consumerKey;
-    this.consumerSecret = opts.consumerSecret;
     this.accessToken = opts.accessToken;
-    this.tokenSecret = opts.tokenSecret;
     this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
   }
 
@@ -168,6 +148,128 @@ 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 ──────────────────────────────────────────────
+
+  /**
+   * Delete the user's registration with Garmin.
+   *
+   * Must be called when the user disconnects or deletes their account
+   * to comply with Garmin's API requirements.
+   */
+  async deleteUserRegistration(): Promise<void> {
+    const url = `${this.baseUrl}/wellness-api/rest/user/registration`;
+    const response = await fetch(url, {
+      method: "DELETE",
+      headers: {
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new GarminApiError(
+        `Garmin API error: ${response.status} ${response.statusText}`,
+        response.status,
+        body,
+      );
+    }
+  }
+
   // ─── Internal ─────────────────────────────────────────────────────────
 
   private async get<T>(
@@ -180,33 +282,10 @@ export class GarminClient {
       : "";
     const requestUrl = `${fullUrl}${qs}`;
 
-    const nonce = generateNonce();
-    const timestamp = getTimestamp();
-
-    const oauthParams: Record<string, string> = {
-      oauth_consumer_key: this.consumerKey,
-      oauth_nonce: nonce,
-      oauth_signature_method: "HMAC-SHA1",
-      oauth_timestamp: timestamp,
-      oauth_token: this.accessToken,
-      oauth_version: "1.0",
-    };
-
-    // OAuth signature must include both OAuth params and query params
-    const allParams = { ...oauthParams, ...(queryParams ?? {}) };
-    const signature = await buildOAuthSignature(
-      "GET",
-      fullUrl,
-      allParams,
-      this.consumerSecret,
-      this.tokenSecret,
-    );
-    oauthParams.oauth_signature = signature;
-
     const response = await fetch(requestUrl, {
       method: "GET",
       headers: {
-        Authorization: buildOAuthHeader(oauthParams),
+        Authorization: `Bearer ${this.accessToken}`,
         Accept: "application/json",
       },
     });
@@ -222,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 ──────────────────────────────────────────────────────────────────

package/src/garmin/index.ts

@@ -1,7 +1,7 @@
 // ─── @nativesquare/soma/garmin ───────────────────────────────────────────────
-// Garmin Health API → Soma schema transformers, API client, OAuth helpers, and sync.
+// Garmin Health API → Soma schema transformers, API client, OAuth 2.0 PKCE helpers, and sync.
 //
-// Uses the Web Crypto API for OAuth 1.0a HMAC-SHA1 signing.
+// Uses the Web Crypto API for PKCE code challenge generation.
 // Compatible with both the Convex V8 runtime and Node.js environments.
 
 // ── Transformers ─────────────────────────────────────────────────────────────
@@ -28,19 +28,19 @@ export { mapSleepLevel } from "./maps/sleep-level.js";
 export { GarminClient, GarminApiError } from "./client.js";
 export type { GarminClientOptions, TimeRangeParams } from "./client.js";
 
-// ── OAuth Helpers ────────────────────────────────────────────────────────────
+// ── OAuth 2.0 PKCE Helpers ───────────────────────────────────────────────────
 export {
-  getRequestToken,
-  getAccessToken,
-  buildOAuthSignature,
-  buildOAuthHeader,
-  percentEncode,
-  generateNonce,
-  getTimestamp,
+  generateCodeVerifier,
+  generateCodeChallenge,
+  generateState,
+  buildAuthUrl,
+  exchangeCode,
+  refreshToken,
 } from "./auth.js";
 export type {
-  GetRequestTokenOptions,
-  GetAccessTokenOptions,
+  BuildAuthUrlOptions,
+  ExchangeCodeOptions,
+  RefreshTokenOptions,
 } from "./auth.js";
 
 // ── Sync Helpers ─────────────────────────────────────────────────────────────
@@ -70,7 +70,6 @@ export type {
   GarminMenstrualCycleData,
   GarminUserProfile,
   GarminActivityType,
-  GarminOAuthRequestTokenResponse,
-  GarminOAuthAccessTokenResponse,
+  GarminOAuth2TokenResponse,
   GarminWebhookPayload,
 } from "./types.js";

package/src/garmin/plannedWorkout.ts

@@ -0,0 +1,333 @@
+// ─── Soma → Garmin Training API V2 Transformer ─────────────────────────────
+// Maps Soma's Terra-style planned workout model to the Garmin Training API V2
+// JSON format for workout creation and scheduling.
+
+import type {
+  GarminWorkout,
+  GarminWorkoutSegment,
+  GarminWorkoutStep,
+  GarminWorkoutRepeatStep,
+  GarminWorkoutSport,
+  GarminStepIntensity,
+  GarminDurationType,
+  GarminTargetType,
+} from "./types.js";
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SomaPlannedWorkout = Record<string, any>;
+
+/**
+ * Transform a Soma planned workout document into a Garmin Training API V2
+ * workout payload ready for `POST /workoutportal/workout/v2`.
+ *
+ * @param somaWorkout - The planned workout document from the Soma DB
+ * @param providerName - Name shown to the user in Garmin Connect (20 chars max)
+ */
+export function transformPlannedWorkoutToGarmin(
+  somaWorkout: SomaPlannedWorkout,
+  providerName: string,
+): GarminWorkout {
+  const metadata = somaWorkout.metadata ?? {};
+  const sport = mapSportType(metadata.type);
+  const steps = transformSteps(somaWorkout.steps ?? []);
+
+  const segment: GarminWorkoutSegment = {
+    segmentOrder: 1,
+    sport,
+    poolLength: metadata.pool_length_meters ?? null,
+    poolLengthUnit: metadata.pool_length_meters != null ? "METER" : null,
+    estimatedDurationInSecs: null,
+    estimatedDistanceInMeters: null,
+    steps,
+  };
+
+  return {
+    workoutName: metadata.name ?? "Workout",
+    description: metadata.description ?? null,
+    sport,
+    estimatedDurationInSecs: null,
+    estimatedDistanceInMeters: null,
+    poolLength: metadata.pool_length_meters ?? null,
+    poolLengthUnit: metadata.pool_length_meters != null ? "METER" : null,
+    workoutProvider: providerName.slice(0, 20),
+    workoutSourceId: providerName.slice(0, 20),
+    isSessionTransitionEnabled: false,
+    segments: [segment],
+  };
+}
+
+// ─── Step Transformation ─────────────────────────────────────────────────────
+
+function transformSteps(
+  somaSteps: Array<Record<string, unknown>>,
+): Array<GarminWorkoutStep | GarminWorkoutRepeatStep> {
+  const result: Array<GarminWorkoutStep | GarminWorkoutRepeatStep> = [];
+  let order = 1;
+
+  for (const step of somaSteps) {
+    const stepType = String(step.type ?? "STEP").toUpperCase();
+
+    if (stepType === "REPEAT_STEP") {
+      const nestedSteps = Array.isArray(step.steps) ? step.steps : [];
+      const reps = extractRepeatCount(step);
+
+      const repeatStep: GarminWorkoutRepeatStep = {
+        type: "WorkoutRepeatStep",
+        stepOrder: order++,
+        repeatType: "REPEAT_UNTIL_STEPS_CMPLT",
+        repeatValue: reps,
+        steps: transformSteps(nestedSteps),
+      };
+      result.push(repeatStep);
+    } else {
+      const workoutStep = transformSingleStep(step, order++);
+      result.push(workoutStep);
+    }
+  }
+
+  return result;
+}
+
+function transformSingleStep(
+  step: Record<string, unknown>,
+  stepOrder: number,
+): GarminWorkoutStep {
+  const { durationType, durationValue, durationValueType } =
+    extractDuration(step);
+  const { targetType, targetValueLow, targetValueHigh, targetValueType } =
+    extractTarget(step);
+
+  return {
+    type: "WorkoutStep",
+    stepOrder,
+    intensity: mapIntensity(step.intensity),
+    description: (step.description as string) ?? null,
+    durationType,
+    durationValue,
+    durationValueType,
+    targetType,
+    targetValue: null,
+    targetValueLow,
+    targetValueHigh,
+    targetValueType,
+    secondaryTargetType: null,
+    secondaryTargetValue: null,
+    secondaryTargetValueLow: null,
+    secondaryTargetValueHigh: null,
+    secondaryTargetValueType: null,
+    strokeType: (step.stroke_type as string) ?? null,
+    drillType: null,
+    equipmentType: (step.equipment_type as string) ?? null,
+    exerciseCategory: (step.exercise_category as string) ?? null,
+    exerciseName: (step.exercise_name as string) ?? null,
+    weightValue: (step.weight_kg as number) ?? null,
+    weightDisplayUnit: step.weight_kg != null ? "KILOGRAM" : null,
+  };
+}
+
+// ─── Duration Extraction ─────────────────────────────────────────────────────
+
+interface DurationResult {
+  durationType: GarminDurationType;
+  durationValue: number | null;
+  durationValueType: string | null;
+}
+
+function extractDuration(step: Record<string, unknown>): DurationResult {
+  const durations = step.durations as Array<Record<string, unknown>> | undefined;
+  if (!durations || durations.length === 0) {
+    return { durationType: "OPEN", durationValue: null, durationValueType: null };
+  }
+
+  const dur = durations[0];
+  const type = String(dur.duration_type ?? "OPEN").toUpperCase();
+
+  switch (type) {
+    case "TIME":
+      return {
+        durationType: "TIME",
+        durationValue: (dur.seconds as number) ?? null,
+        durationValueType: null,
+      };
+    case "DISTANCE_METERS":
+    case "DISTANCE":
+      return {
+        durationType: "DISTANCE",
+        durationValue: (dur.distance_meters as number) ?? null,
+        durationValueType: null,
+      };
+    case "HR_LESS_THAN":
+      return {
+        durationType: "HR_LESS_THAN",
+        durationValue: (dur.hr_below_bpm as number) ?? null,
+        durationValueType: null,
+      };
+    case "HR_GREATER_THAN":
+      return {
+        durationType: "HR_GREATER_THAN",
+        durationValue: (dur.hr_above_bpm as number) ?? null,
+        durationValueType: null,
+      };
+    case "CALORIES":
+      return {
+        durationType: "CALORIES",
+        durationValue: (dur.calories as number) ?? null,
+        durationValueType: null,
+      };
+    case "POWER_LESS_THAN":
+      return {
+        durationType: "POWER_LESS_THAN",
+        durationValue: (dur.power_below_watts as number) ?? null,
+        durationValueType: null,
+      };
+    case "POWER_GREATER_THAN":
+      return {
+        durationType: "POWER_GREATER_THAN",
+        durationValue: (dur.power_above_watts as number) ?? null,
+        durationValueType: null,
+      };
+    case "REPS":
+      return {
+        durationType: "REPS",
+        durationValue: (dur.reps as number) ?? null,
+        durationValueType: null,
+      };
+    case "FIXED_REST":
+      return {
+        durationType: "FIXED_REST",
+        durationValue: (dur.rest_seconds as number) ?? (dur.seconds as number) ?? null,
+        durationValueType: null,
+      };
+    default:
+      return { durationType: "OPEN", durationValue: null, durationValueType: null };
+  }
+}
+
+// ─── Target Extraction ───────────────────────────────────────────────────────
+
+interface TargetResult {
+  targetType: GarminTargetType | null;
+  targetValueLow: number | null;
+  targetValueHigh: number | null;
+  targetValueType: string | null;
+}
+
+function extractTarget(step: Record<string, unknown>): TargetResult {
+  const targets = step.targets as Array<Record<string, unknown>> | undefined;
+  if (!targets || targets.length === 0) {
+    return { targetType: null, targetValueLow: null, targetValueHigh: null, targetValueType: null };
+  }
+
+  const target = targets[0];
+  const type = String(target.target_type ?? "OPEN").toUpperCase();
+
+  switch (type) {
+    case "HEART_RATE":
+      if (target.hr_percentage_low != null || target.hr_percentage_high != null) {
+        return {
+          targetType: "HEART_RATE",
+          targetValueLow: (target.hr_percentage_low as number) ?? null,
+          targetValueHigh: (target.hr_percentage_high as number) ?? null,
+          targetValueType: "PERCENT",
+        };
+      }
+      return {
+        targetType: "HEART_RATE",
+        targetValueLow: (target.hr_bpm_low as number) ?? null,
+        targetValueHigh: (target.hr_bpm_high as number) ?? null,
+        targetValueType: null,
+      };
+
+    case "SPEED":
+    case "PACE":
+      return {
+        targetType: "SPEED",
+        targetValueLow: (target.speed_meters_per_second as number) ?? null,
+        targetValueHigh: (target.speed_meters_per_second as number) ?? null,
+        targetValueType: null,
+      };
+
+    case "CADENCE":
+      return {
+        targetType: "CADENCE",
+        targetValueLow: (target.cadence_low as number) ?? (target.cadence as number) ?? null,
+        targetValueHigh: (target.cadence_high as number) ?? (target.cadence as number) ?? null,
+        targetValueType: null,
+      };
+
+    case "POWER":
+      if (target.power_percentage_low != null || target.power_percentage_high != null) {
+        return {
+          targetType: "POWER",
+          targetValueLow: (target.power_percentage_low as number) ?? null,
+          targetValueHigh: (target.power_percentage_high as number) ?? null,
+          targetValueType: "PERCENT",
+        };
+      }
+      return {
+        targetType: "POWER",
+        targetValueLow: (target.power_watt_low as number) ?? (target.power_watt as number) ?? null,
+        targetValueHigh: (target.power_watt_high as number) ?? (target.power_watt as number) ?? null,
+        targetValueType: null,
+      };
+
+    case "OPEN":
+      return { targetType: "OPEN", targetValueLow: null, targetValueHigh: null, targetValueType: null };
+
+    default:
+      return { targetType: null, targetValueLow: null, targetValueHigh: null, targetValueType: null };
+  }
+}
+
+// ─── Enum Mapping ────────────────────────────────────────────────────────────
+
+const SPORT_MAP: Record<string, GarminWorkoutSport> = {
+  RUNNING: "RUNNING",
+  BIKING: "CYCLING",
+  CYCLING: "CYCLING",
+  SWIMMING: "LAP_SWIMMING",
+  LAP_SWIMMING: "LAP_SWIMMING",
+  STRENGTH_TRAINING: "STRENGTH_TRAINING",
+  STRENGTH: "STRENGTH_TRAINING",
+  CARDIO: "CARDIO_TRAINING",
+  CARDIO_TRAINING: "CARDIO_TRAINING",
+  YOGA: "YOGA",
+  PILATES: "PILATES",
+  MULTI_SPORT: "MULTI_SPORT",
+  GENERIC: "GENERIC",
+  HIIT: "CARDIO_TRAINING",
+};
+
+function mapSportType(type: string | undefined): GarminWorkoutSport {
+  if (!type) return "RUNNING";
+  return SPORT_MAP[type.toUpperCase()] ?? "GENERIC";
+}
+
+const INTENSITY_MAP: Record<string, GarminStepIntensity> = {
+  REST: "REST",
+  WARMUP: "WARMUP",
+  WARM_UP: "WARMUP",
+  COOLDOWN: "COOLDOWN",
+  COOL_DOWN: "COOLDOWN",
+  RECOVERY: "RECOVERY",
+  ACTIVE: "ACTIVE",
+  INTERVAL: "INTERVAL",
+  MAIN: "MAIN",
+};
+
+function mapIntensity(value: unknown): GarminStepIntensity {
+  if (value == null) return "ACTIVE";
+  const str = String(value).toUpperCase();
+  return INTENSITY_MAP[str] ?? "ACTIVE";
+}
+
+function extractRepeatCount(step: Record<string, unknown>): number {
+  const durations = step.durations as Array<Record<string, unknown>> | undefined;
+  if (durations && durations.length > 0) {
+    const reps = durations[0].reps as number | undefined;
+    if (reps != null) return reps;
+  }
+  return 1;
+}