@nativesquare/soma 0.7.3 → 0.9.0

package/src/garmin/client.ts

@@ -1,407 +0,0 @@
-// ─── Garmin Health API Client ────────────────────────────────────────────────
-// Lightweight, fetch-based client for the Garmin Health API.
-// Authenticates requests with an OAuth 2.0 Bearer token.
-
-import type {
-  GarminActivity,
-  GarminDailySummary,
-  GarminSleep,
-  GarminBodyComposition,
-  GarminMenstrualCycleData,
-  GarminWorkout,
-  GarminWorkoutSchedule,
-} from "./types.js";
-
-const DEFAULT_BASE_URL = "https://apis.garmin.com";
-
-export interface GarminClientOptions {
-  /** The user's OAuth 2.0 access token. */
-  accessToken: string;
-  /**
-   * Base URL of the Garmin Health API.
-   * @default "https://apis.garmin.com"
-   */
-  baseUrl?: string;
-}
-
-/**
- * A lightweight client for the Garmin Health API.
- *
- * 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({
- *   accessToken: "user_access_token",
- * });
- *
- * const dailies = await client.getDailies({
- *   uploadStartTimeInSeconds: startEpoch,
- *   uploadEndTimeInSeconds: endEpoch,
- * });
- * ```
- */
-export class GarminClient {
-  private readonly accessToken: string;
-  private readonly baseUrl: string;
-
-  constructor(opts: GarminClientOptions) {
-    this.accessToken = opts.accessToken;
-    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-  }
-
-  // ─── Daily Summaries ────────────────────────────────────────────────────
-
-  /**
-   * Get daily wellness summaries.
-   *
-   * Garmin API: `GET /wellness-api/rest/dailies`
-   */
-  async getDailies(params: TimeRangeParams): Promise<GarminDailySummary[]> {
-    return this.get<GarminDailySummary[]>(
-      "/wellness-api/rest/dailies",
-      timeRangeQuery(params),
-    );
-  }
-
-  // ─── Activities ─────────────────────────────────────────────────────────
-
-  /**
-   * Get activity summaries.
-   *
-   * Garmin API: `GET /wellness-api/rest/activities`
-   */
-  async getActivities(params: TimeRangeParams): Promise<GarminActivity[]> {
-    return this.get<GarminActivity[]>(
-      "/wellness-api/rest/activities",
-      timeRangeQuery(params),
-    );
-  }
-
-  // ─── Sleep ──────────────────────────────────────────────────────────────
-
-  /**
-   * Get sleep summaries.
-   *
-   * Garmin API: `GET /wellness-api/rest/sleeps`
-   */
-  async getSleeps(params: TimeRangeParams): Promise<GarminSleep[]> {
-    return this.get<GarminSleep[]>(
-      "/wellness-api/rest/sleeps",
-      timeRangeQuery(params),
-    );
-  }
-
-  // ─── Body Composition ─────────────────────────────────────────────────
-
-  /**
-   * Get body composition summaries.
-   *
-   * Garmin API: `GET /wellness-api/rest/bodyComps`
-   */
-  async getBodyCompositions(
-    params: TimeRangeParams,
-  ): Promise<GarminBodyComposition[]> {
-    return this.get<GarminBodyComposition[]>(
-      "/wellness-api/rest/bodyComps",
-      timeRangeQuery(params),
-    );
-  }
-
-  // ─── Menstrual Cycle ──────────────────────────────────────────────────
-
-  /**
-   * Get menstrual cycle data.
-   *
-   * Garmin API: `GET /wellness-api/rest/menstrualCycleData`
-   */
-  async getMenstrualCycleData(
-    params: TimeRangeParams,
-  ): Promise<GarminMenstrualCycleData[]> {
-    return this.get<GarminMenstrualCycleData[]>(
-      "/wellness-api/rest/menstrualCycleData",
-      timeRangeQuery(params),
-    );
-  }
-
-  // ─── Backfill ─────────────────────────────────────────────────────────
-
-  /**
-   * Request historical data backfill from Garmin.
-   *
-   * Garmin processes backfill requests asynchronously and delivers data
-   * via the configured webhook endpoint. Maximum range: 90 days per request.
-   *
-   * @param summaryType - The data type to backfill (e.g., "dailies", "activities", "sleeps", "bodyComps")
-   * @param params - Time range for the backfill
-   */
-  async requestBackfill(
-    summaryType: string,
-    params: TimeRangeParams,
-  ): Promise<void> {
-    const query = timeRangeQuery(params);
-    await this.get(
-      `/wellness-api/rest/backfill/${summaryType}`,
-      query,
-    );
-  }
-
-  // ─── Training API V2 ────────────────────────────────────────────────
-
-  /**
-   * Check which permissions the user has granted.
-   *
-   * Garmin OAuth 2.0 PKCE spec: `GET /wellness-api/rest/user/permissions`
-   */
-  async getUserPermissions(): Promise<string[]> {
-    return this.get<string[]>("/wellness-api/rest/user/permissions");
-  }
-
-  /**
-   * 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>(
-    path: string,
-    queryParams?: Record<string, string>,
-  ): Promise<T> {
-    const fullUrl = `${this.baseUrl}${path}`;
-    const qs = queryParams
-      ? `?${new URLSearchParams(queryParams).toString()}`
-      : "";
-    const requestUrl = `${fullUrl}${qs}`;
-
-    const response = await fetch(requestUrl, {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${this.accessToken}`,
-        Accept: "application/json",
-      },
-    });
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      throw new GarminApiError(
-        `Garmin API error: ${response.status} ${response.statusText}`,
-        response.status,
-        body,
-      );
-    }
-
-    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(() => "");
-      const isTrainingApi =
-        path.includes("/workoutportal/") || path.includes("/training-api/");
-      const hint =
-        isTrainingApi && response.status === 401
-          ? " — Ensure the Garmin app is registered for the Training API program " +
-            "and the user has WORKOUT_IMPORT permission."
-          : "";
-      throw new GarminApiError(
-        `Garmin API error: ${response.status} ${response.statusText}${hint}`,
-        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 ──────────────────────────────────────────────────────────────────
-
-export interface TimeRangeParams {
-  /** Start of the time range as Unix epoch seconds. */
-  uploadStartTimeInSeconds: number;
-  /** End of the time range as Unix epoch seconds. */
-  uploadEndTimeInSeconds: number;
-}
-
-function timeRangeQuery(params: TimeRangeParams): Record<string, string> {
-  return {
-    uploadStartTimeInSeconds: String(params.uploadStartTimeInSeconds),
-    uploadEndTimeInSeconds: String(params.uploadEndTimeInSeconds),
-  };
-}
-
-// ─── Error ────────────────────────────────────────────────────────────────────
-
-export class GarminApiError extends Error {
-  constructor(
-    message: string,
-    public readonly status: number,
-    public readonly body: string,
-  ) {
-    super(message);
-    this.name = "GarminApiError";
-  }
-}

package/src/garmin/daily.ts

@@ -1,211 +0,0 @@
-// ─── Daily Transformer ───────────────────────────────────────────────────────
-// Transforms a Garmin daily wellness summary into the Soma Daily schema shape.
-
-import type { GarminDailySummary } from "./types.js";
-
-export type DailyData = ReturnType<typeof transformDaily>;
-
-/**
- * Transform a Garmin daily summary into a Soma Daily document shape.
- *
- * @param daily - The Garmin daily summary from the Health API
- * @returns Soma Daily fields (without connectionId/userId)
- */
-export function transformDaily(daily: GarminDailySummary) {
-  const startMs = daily.startTimeInSeconds * 1000;
-  const endMs = startMs + daily.durationInSeconds * 1000;
-
-  return {
-    metadata: {
-      start_time: new Date(startMs).toISOString(),
-      end_time: new Date(endMs).toISOString(),
-      upload_type: 1, // Automatic
-    },
-
-    active_durations_data: buildActiveDurationsData(daily),
-
-    calories_data: buildCaloriesData(daily),
-
-    distance_data: buildDistanceData(daily),
-
-    heart_rate_data: buildHeartRateData(daily),
-
-    oxygen_data: buildOxygenData(daily),
-
-    stress_data: buildStressData(daily),
-  };
-}
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-function buildActiveDurationsData(daily: GarminDailySummary) {
-  if (
-    daily.activeTimeInSeconds == null &&
-    daily.moderateIntensityDurationInSeconds == null &&
-    daily.vigorousIntensityDurationInSeconds == null
-  ) {
-    return undefined;
-  }
-
-  return {
-    activity_seconds: daily.activeTimeInSeconds,
-    moderate_intensity_seconds: daily.moderateIntensityDurationInSeconds,
-    vigorous_intensity_seconds: daily.vigorousIntensityDurationInSeconds,
-  };
-}
-
-function buildCaloriesData(daily: GarminDailySummary) {
-  if (daily.activeKilocalories == null && daily.bmrKilocalories == null) {
-    return undefined;
-  }
-
-  const total =
-    (daily.activeKilocalories ?? 0) + (daily.bmrKilocalories ?? 0);
-
-  return {
-    net_activity_calories: daily.activeKilocalories,
-    BMR_calories: daily.bmrKilocalories,
-    total_burned_calories: total || undefined,
-  };
-}
-
-function buildDistanceData(daily: GarminDailySummary) {
-  if (
-    daily.distanceInMeters == null &&
-    daily.steps == null &&
-    daily.floorsClimbed == null
-  ) {
-    return undefined;
-  }
-
-  return {
-    distance_meters: daily.distanceInMeters,
-    steps: daily.steps,
-    floors_climbed: daily.floorsClimbed,
-  };
-}
-
-function buildHeartRateData(daily: GarminDailySummary) {
-  const hasSummary =
-    daily.averageHeartRateInBeatsPerMinute != null ||
-    daily.maxHeartRateInBeatsPerMinute != null ||
-    daily.restingHeartRateInBeatsPerMinute != null;
-  const hasSamples =
-    daily.timeOffsetHeartRateSamples != null &&
-    Object.keys(daily.timeOffsetHeartRateSamples).length > 0;
-
-  if (!hasSummary && !hasSamples) return undefined;
-
-  const hrSamples = hasSamples
-    ? buildTimeOffsetSamples(
-        daily.startTimeInSeconds,
-        daily.timeOffsetHeartRateSamples!,
-        (bpm) => ({ bpm }),
-      )
-    : undefined;
-
-  return {
-    summary: hasSummary
-      ? {
-          avg_hr_bpm: daily.averageHeartRateInBeatsPerMinute,
-          max_hr_bpm: daily.maxHeartRateInBeatsPerMinute,
-          min_hr_bpm: daily.minHeartRateInBeatsPerMinute,
-          resting_hr_bpm: daily.restingHeartRateInBeatsPerMinute,
-        }
-      : undefined,
-    detailed:
-      hrSamples && hrSamples.length > 0
-        ? { hr_samples: hrSamples }
-        : undefined,
-  };
-}
-
-function buildOxygenData(daily: GarminDailySummary) {
-  if (daily.averageSpo2Value == null && daily.timeOffsetSpo2Values == null) {
-    return undefined;
-  }
-
-  const samples =
-    daily.timeOffsetSpo2Values != null
-      ? buildTimeOffsetSamples(
-          daily.startTimeInSeconds,
-          daily.timeOffsetSpo2Values,
-          (pct) => ({ percentage: pct }),
-        )
-      : undefined;
-
-  return {
-    avg_saturation_percentage: daily.averageSpo2Value,
-    saturation_samples:
-      samples && samples.length > 0 ? samples : undefined,
-  };
-}
-
-function buildStressData(daily: GarminDailySummary) {
-  const hasStress =
-    daily.averageStressLevel != null ||
-    daily.maxStressLevel != null ||
-    daily.stressDurationInSeconds != null;
-  const hasStressSamples =
-    daily.timeOffsetStressLevelValues != null &&
-    Object.keys(daily.timeOffsetStressLevelValues).length > 0;
-  const hasBodyBatterySamples =
-    daily.timeOffsetBodyBatteryValues != null &&
-    Object.keys(daily.timeOffsetBodyBatteryValues).length > 0;
-
-  if (!hasStress && !hasStressSamples && !hasBodyBatterySamples) {
-    return undefined;
-  }
-
-  const stressSamples = hasStressSamples
-    ? buildTimeOffsetSamples(
-        daily.startTimeInSeconds,
-        daily.timeOffsetStressLevelValues!,
-        (level) => ({ level }),
-      )
-    : undefined;
-
-  const bodyBatterySamples = hasBodyBatterySamples
-    ? buildTimeOffsetSamples(
-        daily.startTimeInSeconds,
-        daily.timeOffsetBodyBatteryValues!,
-        (level) => ({ level }),
-      )
-    : undefined;
-
-  return {
-    avg_stress_level: daily.averageStressLevel,
-    max_stress_level: daily.maxStressLevel,
-    stress_duration_seconds: daily.stressDurationInSeconds,
-    rest_stress_duration_seconds: daily.restStressDurationInSeconds,
-    activity_stress_duration_seconds: daily.activityStressDurationInSeconds,
-    low_stress_duration_seconds: daily.lowStressDurationInSeconds,
-    medium_stress_duration_seconds: daily.mediumStressDurationInSeconds,
-    high_stress_duration_seconds: daily.highStressDurationInSeconds,
-    samples:
-      stressSamples && stressSamples.length > 0 ? stressSamples : undefined,
-    body_battery_samples:
-      bodyBatterySamples && bodyBatterySamples.length > 0
-        ? bodyBatterySamples
-        : undefined,
-  };
-}
-
-/**
- * Convert Garmin offset-keyed time-series data into timestamped samples.
- *
- * Garmin sends time-series as `{ [offsetSeconds]: value }` maps.
- * This converts to `{ timestamp: ISO-8601, ...fields }[]`.
- */
-function buildTimeOffsetSamples<T extends Record<string, unknown>>(
-  startTimeInSeconds: number,
-  offsets: Record<string, number>,
-  mapValue: (value: number) => T,
-): Array<{ timestamp: string } & T> {
-  return Object.entries(offsets).map(([offset, value]) => ({
-    timestamp: new Date(
-      (startTimeInSeconds + parseInt(offset, 10)) * 1000,
-    ).toISOString(),
-    ...mapValue(value),
-  }));
-}

package/src/garmin/index.ts

@@ -1,75 +0,0 @@
-// ─── @nativesquare/soma/garmin ───────────────────────────────────────────────
-// Garmin Health API → Soma schema transformers, API client, OAuth 2.0 PKCE helpers, and sync.
-//
-// Uses the Web Crypto API for PKCE code challenge generation.
-// Compatible with both the Convex V8 runtime and Node.js environments.
-
-// ── Transformers ─────────────────────────────────────────────────────────────
-export { transformActivity } from "./activity.js";
-export type { ActivityData } from "./activity.js";
-
-export { transformDaily } from "./daily.js";
-export type { DailyData } from "./daily.js";
-
-export { transformSleep } from "./sleep.js";
-export type { SleepData } from "./sleep.js";
-
-export { transformBody } from "./body.js";
-export type { BodyData } from "./body.js";
-
-export { transformMenstruation } from "./menstruation.js";
-export type { MenstruationData } from "./menstruation.js";
-
-// ── Enum Maps ────────────────────────────────────────────────────────────────
-export { mapActivityType } from "./maps/activity-type.js";
-export { mapSleepLevel } from "./maps/sleep-level.js";
-
-// ── API Client ───────────────────────────────────────────────────────────────
-export { GarminClient, GarminApiError } from "./client.js";
-export type { GarminClientOptions, TimeRangeParams } from "./client.js";
-
-// ── OAuth 2.0 PKCE Helpers ───────────────────────────────────────────────────
-export {
-  generateCodeVerifier,
-  generateCodeChallenge,
-  generateState,
-  buildAuthUrl,
-  exchangeCode,
-  refreshToken,
-} from "./auth.js";
-export type {
-  BuildAuthUrlOptions,
-  ExchangeCodeOptions,
-  RefreshTokenOptions,
-} from "./auth.js";
-
-// ── Sync Helpers ─────────────────────────────────────────────────────────────
-export {
-  syncAll,
-  syncActivities,
-  syncDailies,
-  syncSleep,
-  syncBody,
-  syncMenstruation,
-} from "./sync.js";
-export type {
-  SyncOptions,
-  SyncResult,
-  SyncAllResult,
-} from "./sync.js";
-
-// ── Types ────────────────────────────────────────────────────────────────────
-export type {
-  GarminActivity,
-  GarminActivityLap,
-  GarminActivitySample,
-  GarminDailySummary,
-  GarminSleep,
-  GarminSleepLevel,
-  GarminBodyComposition,
-  GarminMenstrualCycleData,
-  GarminUserProfile,
-  GarminActivityType,
-  GarminOAuth2TokenResponse,
-  GarminWebhookPayload,
-} from "./types.js";